tar.texi(,2) @comment %**start of header
tar.texi(,3) @setfilename tar.info
version.texi(,1) @set UPDATED 26 June 2006
version.texi(,2) @set UPDATED-MONTH June 2006
version.texi(,3) @set EDITION 1.15.92
version.texi(,4) @set VERSION 1.15.92
tar.texi(,5) @settitle GNU tar 1.15.92
tar.texi(,6) @setchapternewpage odd
tar.texi(,7) 
tar.texi(,8) @finalout
tar.texi(,9) 
tar.texi(,10) @smallbook
tar.texi(,11) @c %**end of header
tar.texi(,12) 
tar.texi(,13) @c Maintenance notes:
tar.texi(,14) @c  1. Pay attention to @FIXME{}s and @UNREVISED{}s
tar.texi(,15) @c  2. Before creating final variant:
tar.texi(,16) @c    2.1. Run `make check-options' to make sure all options are properly
tar.texi(,17) @c         documented;
tar.texi(,18) @c    2.2. Run `make master-menu' (see comment before the master menu).
tar.texi(,19) 
rendition.texi(,1) @c This is part of GNU tar manual.
rendition.texi(,2) @c Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
rendition.texi(,3) @c 2003, 2004, 2006 Free Software Foundation, Inc.
rendition.texi(,4) @c See file tar.texi for copying conditions.
rendition.texi(,5) 
rendition.texi(,6) @c This file contains support for 'renditions' by Fran@,{c}ois Pinard
rendition.texi(,7) @c I extended it by adding a FIXME_FOOTNOTE variable, which controls
rendition.texi(,8) @c whether FIXME information should be placed in footnotes or
rendition.texi(,9) @c inlined. --gray
rendition.texi(,10) 
rendition.texi(,11) @c ======================================================================
rendition.texi(,12) @c This document has three levels of rendition: PUBLISH, DISTRIB or PROOF,
rendition.texi(,13) @c as decided by @set symbols.  The PUBLISH rendition does not show
rendition.texi(,14) @c notes or marks asking for revision.  Most users will prefer having more
rendition.texi(,15) @c information, even if this information is not fully revised for adequacy,
rendition.texi(,16) @c so DISTRIB is the default for distributions.  The PROOF rendition
rendition.texi(,17) @c show all marks to the point of ugliness, but is nevertheless useful to
rendition.texi(,18) @c those working on the manual itself.
rendition.texi(,19) @c ======================================================================
rendition.texi(,20) 
rendition.texi(,21) @c Set this symbol if you wish FIXMEs to appear in footnotes, instead
rendition.texi(,22) @c of being inserted into the text.
rendition.texi(,23) @c @set PROOF_FOOTNOTED
rendition.texi(,24) 
rendition.texi(,28) @set DISTRIB
rendition.texi(,32) 
rendition.texi(,36) 
rendition.texi(,38) @set RENDITION FTP release, version
rendition.texi(,40) 
rendition.texi(,44) 
rendition.texi(,45) @c Output marks for nodes needing revision, but not in PUBLISH rendition.
rendition.texi(,46) 
rendition.texi(,54) 
rendition.texi(,55) @c Output various FIXME information only in PROOF rendition.
rendition.texi(,56) 
rendition.texi(,72) 
rendition.texi(,79) 
rendition.texi(,87) 
rendition.texi(,94) 
rendition.texi(,95) @c End of rendition.texi
value.texi(,1) @c This is part of GNU tar manual.
value.texi(,2) @c Copyright (C) 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
value.texi(,3) @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
value.texi(,4) @c See file tar.texi for copying conditions.
value.texi(,5) 
value.texi(,9) 
value.texi(,13) 
value.texi(,21) 
value.texi(,22) 
tar.texi(,22) 
tar.texi(,23) @defcodeindex op  
tar.texi(,24) 
tar.texi(,25) @c Put everything in one index (arbitrarily chosen to be the concept index).
tar.texi(,26) @syncodeindex fn cp
tar.texi(,27) @syncodeindex ky cp
tar.texi(,28) @syncodeindex pg cp
tar.texi(,29) @syncodeindex vr cp
tar.texi(,30) 
tar.texi(,31) @copying
tar.texi(,32) 
tar.texi(,33) This manual is for @acronym{GNU} @command{tar} (version
tar.texi(,34) 1.15.92, 26 June 2006), which creates and extracts files
tar.texi(,35) from archives.
tar.texi(,36) 
tar.texi(,37) Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001,
tar.texi(,38) 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
tar.texi(,39) 
tar.texi(,40) @quotation
tar.texi(,41) Permission is granted to copy, distribute and/or modify this document
tar.texi(,42) under the terms of the GNU Free Documentation License, Version 1.1 or
tar.texi(,43) any later version published by the Free Software Foundation; with no
tar.texi(,44) Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
tar.texi(,45) and with the Back-Cover Texts as in (a) below.  A copy of the license
tar.texi(,46) is included in the section entitled "GNU Free Documentation License".
tar.texi(,47) 
tar.texi(,48) (a) The FSF's Back-Cover Text is: ``You are free to copy and modify
tar.texi(,49) this GNU Manual.  Buying copies from GNU Press supports the FSF in
tar.texi(,50) developing GNU and promoting software freedom.''
tar.texi(,51) @end quotation
tar.texi(,52) @end copying
tar.texi(,53) 
tar.texi(,54) @dircategory Archiving
tar.texi(,58) 
tar.texi(,59) @dircategory Individual utilities
tar.texi(,63) 
tar.texi(,64) @shorttitlepage @acronym{GNU} @command{tar}
tar.texi(,65) 
tar.texi(,66) @titlepage
tar.texi(,67) @title @acronym{GNU} tar: an archiver tool
tar.texi(,68) @subtitle FTP release, version 1.15.92, 26 June 2006
tar.texi(,69) @author John Gilmore, Jay Fenlason et al.
tar.texi(,70) 
tar.texi(,71) @page
tar.texi(,72) @vskip 0pt plus 1filll
tar.texi(,73) @insertcopying
tar.texi(,74) @end titlepage
tar.texi(,75) 
tar.texi(,77) @node Top
tar.texi(,78) @top @acronym{GNU} tar: an archiver tool
tar.texi(,79) 
tar.texi(,80) @insertcopying
tar.texi(,81) 
tar.texi(,82) @cindex file archival
tar.texi(,83) @cindex archiving files
tar.texi(,84) 
tar.texi(,85) The first part of this master menu lists the major nodes in this Info
tar.texi(,86) document.  The rest of the menu lists all the lower level nodes.
tar.texi(,88) 
tar.texi(,89) @c The master menu goes here.
tar.texi(,90) @c
tar.texi(,91) @c NOTE: To update it from within Emacs, make sure mastermenu.el is
tar.texi(,92) @c loaded and run texinfo-master-menu.
tar.texi(,93) @c To update it from the command line, run
tar.texi(,94) @c
tar.texi(,95) @c    make master-menu
tar.texi(,96) 
tar.texi(,97) @menu
tar.texi(,98) * Introduction::
tar.texi(,99) * Tutorial::
tar.texi(,100) * tar invocation::
tar.texi(,101) * operations::
tar.texi(,102) * Backups::
tar.texi(,103) * Choosing::
tar.texi(,104) * Date input formats::
tar.texi(,105) * Formats::
tar.texi(,106) * Media::
tar.texi(,107) 
tar.texi(,108) Appendices
tar.texi(,109) 
tar.texi(,110) * Changes::
tar.texi(,111) * Configuring Help Summary::
tar.texi(,112) * Tar Internals::
tar.texi(,113) * Genfile::
tar.texi(,114) * Free Software Needs Free Documentation::
tar.texi(,115) * Copying This Manual::
tar.texi(,116) * Index of Command Line Options::
tar.texi(,117) * Index::
tar.texi(,118) 
tar.texi(,119) @detailmenu
tar.texi(,120)  --- The Detailed Node Listing ---
tar.texi(,121) 
tar.texi(,122) Introduction
tar.texi(,123) 
tar.texi(,124) * Book Contents::               What this Book Contains
tar.texi(,125) * Definitions::                 Some Definitions
tar.texi(,126) * What tar Does::               What @command{tar} Does
tar.texi(,127) * Naming tar Archives::         How @command{tar} Archives are Named
tar.texi(GNUTAR,128) * Authors::                     tar.texi(GNUTAR,128) @acronym{GNU} @command{tar} Authors
tar.texi(,129) * Reports::                     Reporting bugs or suggestions
tar.texi(,130) 
tar.texi(,131) Tutorial Introduction to @command{tar}
tar.texi(,132) 
tar.texi(,133) * assumptions::
tar.texi(,134) * stylistic conventions::
tar.texi(,135) * basic tar options::           Basic @command{tar} Operations and Options
tar.texi(,136) * frequent operations::
tar.texi(,137) * Two Frequent Options::
tar.texi(,138) * create::                      How to Create Archives
tar.texi(,139) * list::                        How to List Archives
tar.texi(,140) * extract::                     How to Extract Members from an Archive
tar.texi(,141) * going further::
tar.texi(,142) 
tar.texi(,143) Two Frequently Used Options
tar.texi(,144) 
tar.texi(,145) * file tutorial::
tar.texi(,146) * verbose tutorial::
tar.texi(,147) * help tutorial::
tar.texi(,148) 
tar.texi(,149) How to Create Archives
tar.texi(,150) 
tar.texi(,151) * prepare for examples::
tar.texi(,152) * Creating the archive::
tar.texi(,153) * create verbose::
tar.texi(,154) * short create::
tar.texi(,155) * create dir::
tar.texi(,156) 
tar.texi(,157) How to List Archives
tar.texi(,158) 
tar.texi(,159) * list dir::
tar.texi(,160) 
tar.texi(,161) How to Extract Members from an Archive
tar.texi(,162) 
tar.texi(,163) * extracting archives::
tar.texi(,164) * extracting files::
tar.texi(,165) * extract dir::
tar.texi(,166) * extracting untrusted archives::
tar.texi(,167) * failing commands::
tar.texi(,168) 
tar.texi(GNUTAR,169) Invoking tar.texi(GNUTAR,169) @acronym{GNU} @command{tar}
tar.texi(,170) 
tar.texi(,171) * Synopsis::
tar.texi(,172) * using tar options::
tar.texi(,173) * Styles::
tar.texi(,174) * All Options::
tar.texi(,175) * help::
tar.texi(,176) * defaults::
tar.texi(,177) * verbose::
tar.texi(,178) * interactive::
tar.texi(,179) 
tar.texi(,180) The Three Option Styles
tar.texi(,181) 
tar.texi(,182) * Long Options::                Long Option Style
tar.texi(,183) * Short Options::               Short Option Style
tar.texi(,184) * Old Options::                 Old Option Style
tar.texi(,185) * Mixing::                      Mixing Option Styles
tar.texi(,186) 
tar.texi(,187) All @command{tar} Options
tar.texi(,188) 
tar.texi(,189) * Operation Summary::
tar.texi(,190) * Option Summary::
tar.texi(,191) * Short Option Summary::
tar.texi(,192) 
tar.texi(GNUTAR,193) @acronym{GNU} @command{tar} Operations
tar.texi(,194) 
tar.texi(,195) * Basic tar::
tar.texi(,196) * Advanced tar::
tar.texi(,197) * create options::
tar.texi(,198) * extract options::
tar.texi(,199) * backup::
tar.texi(,200) * Applications::
tar.texi(,201) * looking ahead::
tar.texi(,202) 
tar.texi(GNUTAR,203) Advanced tar.texi(GNUTAR,203) @acronym{GNU} @command{tar} Operations
tar.texi(,204) 
tar.texi(,205) * Operations::
tar.texi(,206) * append::
tar.texi(,207) * update::
tar.texi(,208) * concatenate::
tar.texi(,209) * delete::
tar.texi(,210) * compare::
tar.texi(,211) 
tar.texi(,212) How to Add Files to Existing Archives: @option{--append}
tar.texi(,213) 
tar.texi(,214) * appending files::             Appending Files to an Archive
tar.texi(,215) * multiple::
tar.texi(,216) 
tar.texi(,217) Updating an Archive
tar.texi(,218) 
tar.texi(,219) * how to update::
tar.texi(,220) 
tar.texi(,221) Options Used by @option{--create}
tar.texi(,222) 
tar.texi(,223) * override::                  Overriding File Metadata.
tar.texi(,224) * Ignore Failed Read::
tar.texi(,225) 
tar.texi(,226) Options Used by @option{--extract}
tar.texi(,227) 
tar.texi(,228) * Reading::                     Options to Help Read Archives
tar.texi(,229) * Writing::                     Changing How @command{tar} Writes Files
tar.texi(,230) * Scarce::                      Coping with Scarce Resources
tar.texi(,231) 
tar.texi(,232) Options to Help Read Archives
tar.texi(,233) 
tar.texi(,234) * read full records::
tar.texi(,235) * Ignore Zeros::
tar.texi(,236) 
tar.texi(,237) Changing How @command{tar} Writes Files
tar.texi(,238) 
tar.texi(,239) * Dealing with Old Files::
tar.texi(,240) * Overwrite Old Files::
tar.texi(,241) * Keep Old Files::
tar.texi(,242) * Keep Newer Files::
tar.texi(,243) * Unlink First::
tar.texi(,244) * Recursive Unlink::
tar.texi(,245) * Data Modification Times::
tar.texi(,246) * Setting Access Permissions::
tar.texi(,247) * Directory Modification Times and Permissions::
tar.texi(,248) * Writing to Standard Output::
tar.texi(,249) * Writing to an External Program::
tar.texi(,250) * remove files::
tar.texi(,251) 
tar.texi(,252) Coping with Scarce Resources
tar.texi(,253) 
tar.texi(,254) * Starting File::
tar.texi(,255) * Same Order::
tar.texi(,256) 
tar.texi(,257) Performing Backups and Restoring Files
tar.texi(,258) 
tar.texi(,259) * Full Dumps::                  Using @command{tar} to Perform Full Dumps
tar.texi(,260) * Incremental Dumps::           Using @command{tar} to Perform Incremental Dumps
tar.texi(,261) * Backup Levels::               Levels of Backups
tar.texi(,262) * Backup Parameters::           Setting Parameters for Backups and Restoration
tar.texi(,263) * Scripted Backups::            Using the Backup Scripts
tar.texi(,264) * Scripted Restoration::        Using the Restore Script
tar.texi(,265) 
tar.texi(,266) Setting Parameters for Backups and Restoration
tar.texi(,267) 
tar.texi(,268) * General-Purpose Variables::
tar.texi(,269) * Magnetic Tape Control::
tar.texi(,270) * User Hooks::
tar.texi(,271) * backup-specs example::        An Example Text of @file{Backup-specs}
tar.texi(,272) 
tar.texi(,273) Choosing Files and Names for @command{tar}
tar.texi(,274) 
tar.texi(,275) * file::                        Choosing the Archive's Name
tar.texi(,276) * Selecting Archive Members::
tar.texi(,277) * files::                       Reading Names from a File
tar.texi(,278) * exclude::                     Excluding Some Files
tar.texi(,279) * wildcards::                   Wildcards Patterns and Matching
tar.texi(,280) * quoting styles::              Ways of Quoting Special Characters in Names
tar.texi(,281) * transform::                   Modifying File and Member Names
tar.texi(,282) * after::                       Operating Only on New Files
tar.texi(,283) * recurse::                     Descending into Directories
tar.texi(,284) * one::                         Crossing File System Boundaries
tar.texi(,285) 
tar.texi(,286) Reading Names from a File
tar.texi(,287) 
tar.texi(,288) * nul::
tar.texi(,289) 
tar.texi(,290) Excluding Some Files
tar.texi(,291) 
tar.texi(,292) * problems with exclude::
tar.texi(,293) 
tar.texi(,294) Wildcards Patterns and Matching
tar.texi(,295) 
tar.texi(,296) * controlling pattern-matching::
tar.texi(,297) 
tar.texi(,298) Crossing File System Boundaries
tar.texi(,299) 
tar.texi(,300) * directory::                   Changing Directory
tar.texi(,301) * absolute::                    Absolute File Names
tar.texi(,302) 
tar.texi(,303) Date input formats
tar.texi(,304) 
tar.texi(,305) * General date syntax::            Common rules.
tar.texi(,306) * Calendar date items::            19 Dec 1994.
tar.texi(,307) * Time of day items::              9:20pm.
tar.texi(,308) * Time zone items::                @sc{est}, @sc{pdt}, @sc{gmt}.
tar.texi(,309) * Day of week items::              Monday and others.
tar.texi(,310) * Relative items in date strings:: next tuesday, 2 years ago.
tar.texi(,311) * Pure numbers in date strings::   19931219, 1440.
tar.texi(,312) * Seconds since the Epoch::        @@1078100502.
tar.texi(,313) * Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
tar.texi(,314) * Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.
tar.texi(,315) 
tar.texi(,316) Controlling the Archive Format
tar.texi(,317) 
tar.texi(,318) * Portability::                 Making @command{tar} Archives More Portable
tar.texi(,319) * Compression::                 Using Less Space through Compression
tar.texi(,320) * Attributes::                  Handling File Attributes
tar.texi(,321) * cpio::                        Comparison of @command{tar} and @command{cpio}
tar.texi(,322) 
tar.texi(,323) Making @command{tar} Archives More Portable
tar.texi(,324) 
tar.texi(,325) * Portable Names::              Portable Names
tar.texi(,326) * dereference::                 Symbolic Links
tar.texi(,327) * old::                         Old V7 Archives
tar.texi(,328) * ustar::                       Ustar Archives
tar.texi(,329) * gnu::                         GNU and old GNU format archives.
tar.texi(,330) * posix::                       @acronym{POSIX} archives
tar.texi(,331) * Checksumming::                Checksumming Problems
tar.texi(,332) * Large or Negative Values::    Large files, negative time stamps, etc.
tar.texi(,333) * Other Tars::                  How to Extract GNU-Specific Data Using
tar.texi(,334)                                 Other @command{tar} Implementations
tar.texi(,335) 
tar.texi(GNUTAR,336) @acronym{GNU} @command{tar} and @acronym{POSIX} @command{tar}
tar.texi(,337) 
tar.texi(,338) * PAX keywords:: Controlling Extended Header Keywords.
tar.texi(,339) 
tar.texi(,340) How to Extract GNU-Specific Data Using Other @command{tar} Implementations
tar.texi(,341) 
tar.texi(,342) * Split Recovery::       Members Split Between Volumes
tar.texi(,343) * Sparse Recovery::      Sparse Members
tar.texi(,344) 
tar.texi(,345) Using Less Space through Compression
tar.texi(,346) 
tar.texi(,347) * gzip::                        Creating and Reading Compressed Archives
tar.texi(,348) * sparse::                      Archiving Sparse Files
tar.texi(,349) 
tar.texi(,350) Tapes and Other Archive Media
tar.texi(,351) 
tar.texi(,352) * Device::                      Device selection and switching
tar.texi(,353) * Remote Tape Server::
tar.texi(,354) * Common Problems and Solutions::
tar.texi(,355) * Blocking::                    Blocking
tar.texi(,356) * Many::                        Many archives on one tape
tar.texi(,357) * Using Multiple Tapes::        Using Multiple Tapes
tar.texi(,358) * label::                       Including a Label in the Archive
tar.texi(,359) * verify::
tar.texi(,360) * Write Protection::
tar.texi(,361) 
tar.texi(,362) Blocking
tar.texi(,363) 
tar.texi(,364) * Format Variations::           Format Variations
tar.texi(,365) * Blocking Factor::             The Blocking Factor of an Archive
tar.texi(,366) 
tar.texi(,367) Many Archives on One Tape
tar.texi(,368) 
tar.texi(,369) * Tape Positioning::            Tape Positions and Tape Marks
tar.texi(,370) * mt::                          The @command{mt} Utility
tar.texi(,371) 
tar.texi(,372) Using Multiple Tapes
tar.texi(,373) 
tar.texi(,374) * Multi-Volume Archives::       Archives Longer than One Tape or Disk
tar.texi(,375) * Tape Files::                  Tape Files
tar.texi(,376) * Tarcat::                      Concatenate Volumes into a Single Archive
tar.texi(,377) 
tar.texi(,378) 
tar.texi(,379) Tar Internals
tar.texi(,380) 
tar.texi(,381) * Standard::           Basic Tar Format
tar.texi(,382) * Extensions::         @acronym{GNU} Extensions to the Archive Format
tar.texi(,383) * Sparse Formats::     Storing Sparse Files
tar.texi(,384) * Snapshot Files::
tar.texi(,385) * Dumpdir::
tar.texi(,386) 
tar.texi(,387) Storing Sparse Files
tar.texi(,388) 
tar.texi(,389) * Old GNU Format::
tar.texi(,390) * PAX 0::                PAX Format, Versions 0.0 and 0.1
tar.texi(,391) * PAX 1::                PAX Format, Version 1.0
tar.texi(,392) 
tar.texi(,393) Genfile
tar.texi(,394) 
tar.texi(,395) * Generate Mode::     File Generation Mode.
tar.texi(,396) * Status Mode::       File Status Mode.
tar.texi(,397) * Exec Mode::         Synchronous Execution mode.
tar.texi(,398) 
tar.texi(,399) Copying This Manual
tar.texi(,400) 
tar.texi(,401) * GNU Free Documentation License::  License for copying this manual
tar.texi(,402) 
tar.texi(,403) @end detailmenu
tar.texi(,404) @end menu
tar.texi(,405) 
tar.texi(,406) @node Introduction
tar.texi(,407) @chapter Introduction
tar.texi(,408) 
tar.texi(GNUTAR,409) @acronym{GNU} @command{tar} creates
tar.texi(,410) and manipulates @dfn{archives} which are actually collections of
tar.texi(,411) many other files; the program provides users with an organized and
tar.texi(,412) systematic method for controlling a large amount of data.
tar.texi(,413) The name ``tar'' originally came from the phrase ``Tape ARchive'', but
tar.texi(,414) archives need not (and these days, typically do not) reside on tapes.
tar.texi(,415) 
tar.texi(,416) @menu
tar.texi(,417) * Book Contents::               What this Book Contains
tar.texi(,418) * Definitions::                 Some Definitions
tar.texi(,419) * What tar Does::               What @command{tar} Does
tar.texi(,420) * Naming tar Archives::         How @command{tar} Archives are Named
tar.texi(GNUTAR,421) * Authors::                     tar.texi(GNUTAR,421) @acronym{GNU} @command{tar} Authors
tar.texi(,422) * Reports::                     Reporting bugs or suggestions
tar.texi(,423) @end menu
tar.texi(,424) 
tar.texi(,425) @node Book Contents
tar.texi(,426) @section What this Book Contains
tar.texi(,427) 
tar.texi(,428) The first part of this chapter introduces you to various terms that will
tar.texi(GNUTAR,429) recur throughout the book.  It also tells you who has worked on tar.texi(GNUTAR,429) @acronym{GNU} @command{tar}
tar.texi(,430) and its documentation, and where you should send bug reports
tar.texi(,431) or comments.
tar.texi(,432) 
tar.texi(,433) The second chapter is a tutorial (@pxref{Tutorial}) which provides a
tar.texi(,434) gentle introduction for people who are new to using @command{tar}.  It is
tar.texi(,435) meant to be self contained, not requiring any reading from subsequent
tar.texi(,436) chapters to make sense.  It moves from topic to topic in a logical,
tar.texi(,437) progressive order, building on information already explained.
tar.texi(,438) 
tar.texi(,439) Although the tutorial is paced and structured to allow beginners to
tar.texi(,440) learn how to use @command{tar}, it is not intended solely for beginners.
tar.texi(,441) The tutorial explains how to use the three most frequently used
tar.texi(,442) operations (@samp{create}, @samp{list}, and @samp{extract}) as well as
tar.texi(,443) two frequently used options (@samp{file} and @samp{verbose}).  The other
tar.texi(,444) chapters do not refer to the tutorial frequently; however, if a section
tar.texi(,445) discusses something which is a complex variant of a basic concept, there
tar.texi(,446) may be a cross reference to that basic concept.  (The entire book,
tar.texi(,447) including the tutorial, assumes that the reader understands some basic
tar.texi(,448) concepts of using a Unix-type operating system; @pxref{Tutorial}.)
tar.texi(,449) 
tar.texi(,450) The third chapter presents the remaining five operations, and
tar.texi(,451) information about using @command{tar} options and option syntax.
tar.texi(,452) 
tar.texi(FIXME,455) @allow-recursion
tar.texi(FIXME,455) @quote-arg
tar.texi(FIXME,455)   The other chapters are meant to be used as a
tar.texi(,456) reference.  Each chapter presents everything that needs to be said
tar.texi(,457) about a specific topic.
tar.texi(,458) 
tar.texi(,459) One of the chapters (@pxref{Date input formats}) exists in its
tar.texi(,460) entirety in other @acronym{GNU} manuals, and is mostly self-contained.
tar.texi(,461) In addition, one section of this manual (@pxref{Standard}) contains a
tar.texi(,462) big quote which is taken directly from @command{tar} sources.
tar.texi(,463) 
tar.texi(,464) In general, we give both long and short (abbreviated) option names
tar.texi(,465) at least once in each section where the relevant option is covered, so
tar.texi(,466) that novice readers will become familiar with both styles.  (A few
tar.texi(,467) options have no short versions, and the relevant sections will
tar.texi(,468) indicate this.)
tar.texi(,469) 
tar.texi(,470) @node Definitions
tar.texi(,471) @section Some Definitions
tar.texi(,472) 
tar.texi(,473) @cindex archive
tar.texi(,474) @cindex tar archive
tar.texi(,475) The @command{tar} program is used to create and manipulate @command{tar}
tar.texi(,476) archives.  An @dfn{archive} is a single file which contains the contents
tar.texi(,477) of many files, while still identifying the names of the files, their
tar.texi(,478) owner(s), and so forth.  (In addition, archives record access
tar.texi(,479) permissions, user and group, size in bytes, and data modification time.
tar.texi(,480) Some archives also record the file names in each archived directory, as
tar.texi(,481) well as other file and directory information.)  You can use @command{tar}
tar.texi(,482) to @dfn{create} a new archive in a specified directory.
tar.texi(,483) 
tar.texi(,484) @cindex member
tar.texi(,485) @cindex archive member
tar.texi(,486) @cindex file name
tar.texi(,487) @cindex member name
tar.texi(,488) The files inside an archive are called @dfn{members}.  Within this
tar.texi(,489) manual, we use the term @dfn{file} to refer only to files accessible in
tar.texi(,490) the normal ways (by @command{ls}, @command{cat}, and so forth), and the term
tar.texi(,491) @dfn{member} to refer only to the members of an archive.  Similarly, a
tar.texi(,492) @dfn{file name} is the name of a file, as it resides in the file system,
tar.texi(,493) and a @dfn{member name} is the name of an archive member within the
tar.texi(,494) archive.
tar.texi(,495) 
tar.texi(,496) @cindex extraction
tar.texi(,497) @cindex unpacking
tar.texi(,498) The term @dfn{extraction} refers to the process of copying an archive
tar.texi(,499) member (or multiple members) into a file in the file system.  Extracting
tar.texi(,500) all the members of an archive is often called @dfn{extracting the
tar.texi(,501) archive}.  The term @dfn{unpack} can also be used to refer to the
tar.texi(,502) extraction of many or all the members of an archive.  Extracting an
tar.texi(,503) archive does not destroy the archive's structure, just as creating an
tar.texi(,504) archive does not destroy the copies of the files that exist outside of
tar.texi(,505) the archive.  You may also @dfn{list} the members in a given archive
tar.texi(,506) (this is often thought of as ``printing'' them to the standard output,
tar.texi(,507) or the command line), or @dfn{append} members to a pre-existing archive.
tar.texi(,508) All of these operations can be performed using @command{tar}.
tar.texi(,509) 
tar.texi(,510) @node What tar Does
tar.texi(,511) @section What @command{tar} Does
tar.texi(,512) 
tar.texi(,513) @cindex tar
tar.texi(,514) The @command{tar} program provides the ability to create @command{tar}
tar.texi(,515) archives, as well as various other kinds of manipulation.  For example,
tar.texi(,516) you can use @command{tar} on previously created archives to extract files,
tar.texi(,517) to store additional files, or to update or list files which were already
tar.texi(,518) stored.
tar.texi(,519) 
tar.texi(,520) Initially, @command{tar} archives were used to store files conveniently on
tar.texi(,521) magnetic tape.  The name @command{tar} comes from this use; it stands for
tar.texi(,522) @code{t}ape @code{ar}chiver.  Despite the utility's name, @command{tar} can
tar.texi(,523) direct its output to available devices, files, or other programs (using
tar.texi(,524) pipes).  @command{tar} may even access remote devices or files (as archives).
tar.texi(,525) 
tar.texi(,526) You can use @command{tar} archives in many ways.  We want to stress a few
tar.texi(,527) of them: storage, backup, and transportation.
tar.texi(,528) 
tar.texi(FIXME,529) @allow-recursion
tar.texi(FIXME,529) @quote-arg
tar.texi(FIXME,529) 
tar.texi(,530) @table @asis
tar.texi(,531) @item Storage
tar.texi(,532) Often, @command{tar} archives are used to store related files for
tar.texi(,533) convenient file transfer over a network.  For example, the
tar.texi(,534) @acronym{GNU} Project distributes its software bundled into
tar.texi(,535) @command{tar} archives, so that all the files relating to a particular
tar.texi(,536) program (or set of related programs) can be transferred as a single
tar.texi(,537) unit.
tar.texi(,538) 
tar.texi(,539) A magnetic tape can store several files in sequence.  However, the tape
tar.texi(,540) has no names for these files; it only knows their relative position on
tar.texi(,541) the tape.  One way to store several files on one tape and retain their
tar.texi(,542) names is by creating a @command{tar} archive.  Even when the basic transfer
tar.texi(,543) mechanism can keep track of names, as FTP can, the nuisance of handling
tar.texi(,544) multiple files, directories, and multiple links makes @command{tar}
tar.texi(,545) archives useful.
tar.texi(,546) 
tar.texi(,547) Archive files are also used for long-term storage.  You can think of
tar.texi(,548) this as transportation from the present into the future.  (It is a
tar.texi(,549) science-fiction idiom that you can move through time as well as in
tar.texi(,550) space; the idea here is that @command{tar} can be used to move archives in
tar.texi(,551) all dimensions, even time!)
tar.texi(,552) 
tar.texi(,553) @item Backup
tar.texi(,554) Because the archive created by @command{tar} is capable of preserving
tar.texi(,555) file information and directory structure, @command{tar} is commonly
tar.texi(,556) used for performing full and incremental backups of disks.  A backup
tar.texi(,557) puts a collection of files (possibly pertaining to many users and
tar.texi(,558) projects) together on a disk or a tape.  This guards against
tar.texi(,559) accidental destruction of the information in those files.
tar.texi(GNUTAR,560) @acronym{GNU} @command{tar} has special features that allow it to be
tar.texi(,561) used to make incremental and full dumps of all the files in a
tar.texi(,562) file system.
tar.texi(,563) 
tar.texi(,564) @item Transportation
tar.texi(,565) You can create an archive on one system, transfer it to another system,
tar.texi(,566) and extract the contents there.  This allows you to transport a group of
tar.texi(,567) files from one system to another.
tar.texi(,568) @end table
tar.texi(,569) 
tar.texi(,570) @node Naming tar Archives
tar.texi(,571) @section How @command{tar} Archives are Named
tar.texi(,572) 
tar.texi(,573) Conventionally, @command{tar} archives are given names ending with
tar.texi(,574) @samp{.tar}.  This is not necessary for @command{tar} to operate properly,
tar.texi(,575) but this manual follows that convention in order to accustom readers to
tar.texi(,576) it and to make examples more clear.
tar.texi(,577) 
tar.texi(,578) @cindex tar file
tar.texi(,579) @cindex entry
tar.texi(,580) @cindex tar entry
tar.texi(,581) Often, people refer to @command{tar} archives as ``@command{tar} files,'' and
tar.texi(,582) archive members as ``files'' or ``entries''.  For people familiar with
tar.texi(,583) the operation of @command{tar}, this causes no difficulty.  However, in
tar.texi(,584) this manual, we consistently refer to ``archives'' and ``archive
tar.texi(,585) members'' to make learning to use @command{tar} easier for novice users.
tar.texi(,586) 
tar.texi(,587) @node Authors
tar.texi(GNUTAR,588) @section tar.texi(GNUTAR,588) @acronym{GNU} @command{tar} Authors
tar.texi(,589) 
tar.texi(GNUTAR,590) @acronym{GNU} @command{tar} was originally written by John Gilmore,
tar.texi(,591) and modified by many people.  The @acronym{GNU} enhancements were
tar.texi(,592) written by Jay Fenlason, then Joy Kendall, and the whole package has
tar.texi(,593) been further maintained by Thomas Bushnell, n/BSG, Fran@,{c}ois
tar.texi(,594) Pinard, Paul Eggert, and finally Sergey Poznyakoff with the help of
tar.texi(,595) numerous and kind users.
tar.texi(,596) 
tar.texi(,597) We wish to stress that @command{tar} is a collective work, and owes much to
tar.texi(,598) all those people who reported problems, offered solutions and other
tar.texi(,599) insights, or shared their thoughts and suggestions.  An impressive, yet
tar.texi(,600) partial list of those contributors can be found in the @file{THANKS}
tar.texi(GNUTAR,601) file from the tar.texi(GNUTAR,601) @acronym{GNU} @command{tar} distribution.
tar.texi(,602) 
tar.texi(FIXME,606) @allow-recursion
tar.texi(FIXME,606) @quote-arg
tar.texi(FIXME,606) 
tar.texi(,607) 
tar.texi(FIXME,609) @allow-recursion
tar.texi(FIXME,609) @quote-arg
tar.texi(FIXME,609) 
tar.texi(,610) 
tar.texi(GNUTAR,611) Jay Fenlason put together a draft of a tar.texi(GNUTAR,611) @acronym{GNU} @command{tar}
tar.texi(,612) manual, borrowing notes from the original man page from John Gilmore.
tar.texi(,613) This was withdrawn in version 1.11.  Thomas Bushnell, n/BSG and Amy
tar.texi(GNUTAR,614) Gorin worked on a tutorial and manual for tar.texi(GNUTAR,614) @acronym{GNU} @command{tar}.
tar.texi(,615) Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
tar.texi(,616) taking information from all these sources and merging them.  Melissa
tar.texi(,617) Weisshaus finally edited and redesigned the book to create version
tar.texi(,618) 1.12.  The book for versions from 1.14 up to 1.15.92 were edited
tar.texi(,619) by the current maintainer, Sergey Poznyakoff.
tar.texi(,620) 
tar.texi(,621) For version 1.12, Daniel Hagerty contributed a great deal of technical
tar.texi(,622) consulting.  In particular, he is the primary author of @ref{Backups}.
tar.texi(,623) 
tar.texi(GNUTAR,624) In July, 2003 tar.texi(GNUTAR,624) @acronym{GNU} @command{tar} was put on CVS at savannah.gnu.org
tar.texi(,625) (see @url{http://savannah.gnu.org/projects/tar}), and
tar.texi(,626) active development and maintenance work has started
tar.texi(GNUTAR,627) again.  Currently tar.texi(GNUTAR,627) @acronym{GNU} @command{tar} is being maintained by Paul Eggert, Sergey
tar.texi(,628) Poznyakoff and Jeff Bailey.
tar.texi(,629) 
tar.texi(,630) Support for @acronym{POSIX} archives was added by Sergey Poznyakoff.
tar.texi(,631) 
tar.texi(,632) @node Reports
tar.texi(,633) @section Reporting bugs or suggestions
tar.texi(,634) 
tar.texi(,635) @cindex bug reports
tar.texi(,636) @cindex reporting bugs
tar.texi(,637) If you find problems or have suggestions about this program or manual,
tar.texi(,638) please report them to @file{bug-tar@@gnu.org}.
tar.texi(,639) 
tar.texi(,640) When reporting a bug, please be sure to include as much detail as
tar.texi(FIXME,643) possible, in order to reproduce it.  tar.texi(FIXME,643) @allow-recursion
tar.texi(FIXME,643) @quote-arg
tar.texi(FIXME,643) .
tar.texi(,644) 
tar.texi(,645) @node Tutorial
tar.texi(,646) @chapter Tutorial Introduction to @command{tar}
tar.texi(,647) 
tar.texi(,648) This chapter guides you through some basic examples of three @command{tar}
tar.texi(,649) operations: @option{--create}, @option{--list}, and @option{--extract}.  If
tar.texi(,650) you already know how to use some other version of @command{tar}, then you
tar.texi(,651) may not need to read this chapter.  This chapter omits most complicated
tar.texi(,652) details about how @command{tar} works.
tar.texi(,653) 
tar.texi(,654) @menu
tar.texi(,655) * assumptions::
tar.texi(,656) * stylistic conventions::
tar.texi(,657) * basic tar options::           Basic @command{tar} Operations and Options
tar.texi(,658) * frequent operations::
tar.texi(,659) * Two Frequent Options::
tar.texi(,660) * create::                      How to Create Archives
tar.texi(,661) * list::                        How to List Archives
tar.texi(,662) * extract::                     How to Extract Members from an Archive
tar.texi(,663) * going further::
tar.texi(,664) @end menu
tar.texi(,665) 
tar.texi(,666) @node assumptions
tar.texi(,667) @section Assumptions this Tutorial Makes
tar.texi(,668) 
tar.texi(,669) This chapter is paced to allow beginners to learn about @command{tar}
tar.texi(,670) slowly.  At the same time, we will try to cover all the basic aspects of
tar.texi(,671) these three operations.  In order to accomplish both of these tasks, we
tar.texi(,672) have made certain assumptions about your knowledge before reading this
tar.texi(,673) manual, and the hardware you will be using:
tar.texi(,674) 
tar.texi(,675) @itemize @bullet
tar.texi(,676) @item
tar.texi(,677) Before you start to work through this tutorial, you should understand
tar.texi(,678) what the terms ``archive'' and ``archive member'' mean
tar.texi(,679) (@pxref{Definitions}).  In addition, you should understand something
tar.texi(,680) about how Unix-type operating systems work, and you should know how to
tar.texi(,681) use some basic utilities.  For example, you should know how to create,
tar.texi(,682) list, copy, rename, edit, and delete files and directories; how to
tar.texi(,683) change between directories; and how to figure out where you are in the
tar.texi(,684) file system.  You should have some basic understanding of directory
tar.texi(,685) structure and how files are named according to which directory they are
tar.texi(,686) in.  You should understand concepts such as standard output and standard
tar.texi(,687) input, what various definitions of the term ``argument'' mean, and the
tar.texi(FIXME,689) differences between relative and absolute path names.  tar.texi(FIXME,689) @allow-recursion
tar.texi(FIXME,689) @quote-arg
tar.texi(FIXME,689) 
tar.texi(,690) 
tar.texi(,691) @item
tar.texi(,692) This manual assumes that you are working from your own home directory
tar.texi(,693) (unless we state otherwise).  In this tutorial, you will create a
tar.texi(,694) directory to practice @command{tar} commands in.  When we show path names,
tar.texi(,695) we will assume that those paths are relative to your home directory.
tar.texi(,696) For example, my home directory path is @file{/home/fsf/melissa}.  All of
tar.texi(,697) my examples are in a subdirectory of the directory named by that path
tar.texi(,698) name; the subdirectory is called @file{practice}.
tar.texi(,699) 
tar.texi(,700) @item
tar.texi(,701) In general, we show examples of archives which exist on (or can be
tar.texi(,702) written to, or worked with from) a directory on a hard disk.  In most
tar.texi(,703) cases, you could write those archives to, or work with them on any other
tar.texi(,704) device, such as a tape drive.  However, some of the later examples in
tar.texi(,705) the tutorial and next chapter will not work on tape drives.
tar.texi(,706) Additionally, working with tapes is much more complicated than working
tar.texi(,707) with hard disks.  For these reasons, the tutorial does not cover working
tar.texi(,708) with tape drives.  @xref{Media}, for complete information on using
tar.texi(,709) @command{tar} archives with tape drives.
tar.texi(,710) 
tar.texi(FIXME,711) @allow-recursion
tar.texi(FIXME,711) @quote-arg
tar.texi(FIXME,711) 
tar.texi(,712) @end itemize
tar.texi(,713) 
tar.texi(,714) @node stylistic conventions
tar.texi(,715) @section Stylistic Conventions
tar.texi(,716) 
tar.texi(,717) In the examples, @samp{$} represents a typical shell prompt.  It
tar.texi(,718) precedes lines you should type; to make this more clear, those lines are
tar.texi(,719) shown in @kbd{this font}, as opposed to lines which represent the
tar.texi(,720) computer's response; those lines are shown in @code{this font}, or
tar.texi(,721) sometimes @samp{like this}.
tar.texi(,722) 
tar.texi(,723) @c When we have lines which are too long to be
tar.texi(,724) @c displayed in any other way, we will show them like this:
tar.texi(,725) 
tar.texi(,726) @node basic tar options
tar.texi(,727) @section Basic @command{tar} Operations and Options
tar.texi(,728) 
tar.texi(,729) @command{tar} can take a wide variety of arguments which specify and define
tar.texi(,730) the actions it will have on the particular set of files or the archive.
tar.texi(,731) The main types of arguments to @command{tar} fall into one of two classes:
tar.texi(,732) operations, and options.
tar.texi(,733) 
tar.texi(,734) Some arguments fall into a class called @dfn{operations}; exactly one of
tar.texi(,735) these is both allowed and required for any instance of using @command{tar};
tar.texi(,736) you may @emph{not} specify more than one.  People sometimes speak of
tar.texi(,737) @dfn{operating modes}.  You are in a particular operating mode when you
tar.texi(,738) have specified the operation which specifies it; there are eight
tar.texi(,739) operations in total, and thus there are eight operating modes.
tar.texi(,740) 
tar.texi(,741) The other arguments fall into the class known as @dfn{options}.  You are
tar.texi(,742) not required to specify any options, and you are allowed to specify more
tar.texi(,743) than one at a time (depending on the way you are using @command{tar} at
tar.texi(,744) that time).  Some options are used so frequently, and are so useful for
tar.texi(,745) helping you type commands more carefully that they are effectively
tar.texi(,746) ``required''.  We will discuss them in this chapter.
tar.texi(,747) 
tar.texi(,748) You can write most of the @command{tar} operations and options in any
tar.texi(,749) of three forms: long (mnemonic) form, short form, and old style.  Some
tar.texi(,750) of the operations and options have no short or ``old'' forms; however,
tar.texi(,751) the operations and options which we will cover in this tutorial have
tar.texi(FIXME,753) corresponding abbreviations.  tar.texi(FIXME,753) @allow-recursion
tar.texi(FIXME,753) @quote-arg
tar.texi(FIXME,753) We will indicate those abbreviations appropriately to get
tar.texi(,754) you used to seeing them.  (Note that the ``old style'' option forms
tar.texi(GNUTAR,755) exist in tar.texi(GNUTAR,755) @acronym{GNU} @command{tar} for compatibility with Unix
tar.texi(,756) @command{tar}.  In this book we present a full discussion of this way
tar.texi(,757) of writing options and operations (@pxref{Old Options}), and we discuss
tar.texi(,758) the other two styles of writing options (@xref{Long Options}, and
tar.texi(,759) @pxref{Short Options}).
tar.texi(,760) 
tar.texi(,761) In the examples and in the text of this tutorial, we usually use the
tar.texi(,762) long forms of operations and options; but the ``short'' forms produce
tar.texi(,763) the same result and can make typing long @command{tar} commands easier.
tar.texi(,764) For example, instead of typing
tar.texi(,765) 
tar.texi(,766) @smallexample
tar.texi(,767) @kbd{tar --create --verbose --file=afiles.tar apple angst aspic}
tar.texi(,768) @end smallexample
tar.texi(,769) 
tar.texi(,770) @noindent
tar.texi(,771) you can type
tar.texi(,772) @smallexample
tar.texi(,773) @kbd{tar -c -v -f afiles.tar apple angst aspic}
tar.texi(,774) @end smallexample
tar.texi(,775) 
tar.texi(,776) @noindent
tar.texi(,777) or even
tar.texi(,778) @smallexample
tar.texi(,779) @kbd{tar -cvf afiles.tar apple angst aspic}
tar.texi(,780) @end smallexample
tar.texi(,781) 
tar.texi(,782) @noindent
tar.texi(,783) For more information on option syntax, see @ref{Advanced tar}.  In
tar.texi(,784) discussions in the text, when we name an option by its long form, we
tar.texi(,785) also give the corresponding short option in parentheses.
tar.texi(,786) 
tar.texi(,787) The term, ``option'', can be confusing at times, since ``operations''
tar.texi(,788) are often lumped in with the actual, @emph{optional} ``options'' in certain
tar.texi(,789) general class statements.  For example, we just talked about ``short and
tar.texi(,790) long forms of options and operations''.  However, experienced @command{tar}
tar.texi(,791) users often refer to these by shorthand terms such as, ``short and long
tar.texi(,792) options''.  This term assumes that the ``operations'' are included, also.
tar.texi(,793) Context will help you determine which definition of ``options'' to use.
tar.texi(,794) 
tar.texi(,795) Similarly, the term ``command'' can be confusing, as it is often used in
tar.texi(,796) two different ways.  People sometimes refer to @command{tar} ``commands''.
tar.texi(,797) A @command{tar} @dfn{command} is the entire command line of user input
tar.texi(,798) which tells @command{tar} what to do --- including the operation, options,
tar.texi(,799) and any arguments (file names, pipes, other commands, etc).  However,
tar.texi(,800) you will also sometimes hear the term ``the @command{tar} command''.  When
tar.texi(,801) the word ``command'' is used specifically like this, a person is usually
tar.texi(,802) referring to the @command{tar} @emph{operation}, not the whole line.
tar.texi(,803) Again, use context to figure out which of the meanings the speaker
tar.texi(,804) intends.
tar.texi(,805) 
tar.texi(,806) @node frequent operations
tar.texi(,807) @section The Three Most Frequently Used Operations
tar.texi(,808) 
tar.texi(,809) Here are the three most frequently used operations (both short and long
tar.texi(,810) forms), as well as a brief description of their meanings.  The rest of
tar.texi(,811) this chapter will cover how to use these operations in detail.  We will
tar.texi(,812) present the rest of the operations in the next chapter.
tar.texi(,813) 
tar.texi(,814) @table @option
tar.texi(,815) @item --create
tar.texi(,816) @itemx -c
tar.texi(,817) Create a new @command{tar} archive.
tar.texi(,818) @item --list
tar.texi(,819) @itemx -t
tar.texi(,820) List the contents of an archive.
tar.texi(,821) @item --extract
tar.texi(,822) @itemx -x
tar.texi(,823) Extract one or more members from an archive.
tar.texi(,824) @end table
tar.texi(,825) 
tar.texi(,826) @node Two Frequent Options
tar.texi(,827) @section Two Frequently Used Options
tar.texi(,828) 
tar.texi(,829) To understand how to run @command{tar} in the three operating modes listed
tar.texi(,830) previously, you also need to understand how to use two of the options to
tar.texi(,831) @command{tar}: @option{--file} (which takes an archive file as an argument)
tar.texi(,832) and @option{--verbose}.  (You are usually not @emph{required} to specify
tar.texi(,833) either of these options when you run @command{tar}, but they can be very
tar.texi(,834) useful in making things more clear and helping you avoid errors.)
tar.texi(,835) 
tar.texi(,836) @menu
tar.texi(,837) * file tutorial::
tar.texi(,838) * verbose tutorial::
tar.texi(,839) * help tutorial::
tar.texi(,840) @end menu
tar.texi(,841) 
tar.texi(,842) @node file tutorial
tar.texi(,843) @unnumberedsubsec The @option{--file} Option
tar.texi(,844) 
tar.texi(,845) @table @option
tar.texi(xopindex,846) @opindex file@r{, tutorial}
tar.texi(,847) @item --file=@var{archive-name}
tar.texi(,848) @itemx -f @var{archive-name}
tar.texi(,849) Specify the name of an archive file.
tar.texi(,850) @end table
tar.texi(,851) 
tar.texi(,852) You can specify an argument for the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option whenever you
tar.texi(,853) use @command{tar}; this option determines the name of the archive file
tar.texi(,854) that @command{tar} will work on.
tar.texi(,855) 
tar.texi(,856) @vrindex TAPE
tar.texi(,857) If you don't specify this argument, then @command{tar} will examine
tar.texi(,858) the environment variable @env{TAPE}.  If it is set, its value will be
tar.texi(,859) used as the archive name.  Otherwise, @command{tar} will use the
tar.texi(,860) default archive, determined at the compile time. Usually it is
tar.texi(,861) standard output or some physical tape drive attached to your machine
tar.texi(,862) (you can verify what the default is by running @kbd{tar
tar.texi(,863) --show-defaults}, @pxref{defaults}).  If there is no tape drive
tar.texi(,864) attached, or the default is not meaningful, then @command{tar} will
tar.texi(,865) print an error message.  The error message might look roughly like one
tar.texi(,866) of the following:
tar.texi(,867) 
tar.texi(,868) @smallexample
tar.texi(,869) tar: can't open /dev/rmt8 : No such device or address
tar.texi(,870) tar: can't open /dev/rsmt0 : I/O error
tar.texi(,871) @end smallexample
tar.texi(,872) 
tar.texi(,873) @noindent
tar.texi(,874) To avoid confusion, we recommend that you always specify an archive file
tar.texi(,875) name by using @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) when writing your @command{tar} commands.
tar.texi(,876) For more information on using the @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) option, see
tar.texi(,877) @ref{file}.
tar.texi(,878) 
tar.texi(,879) @node verbose tutorial
tar.texi(,880) @unnumberedsubsec The @option{--verbose} Option
tar.texi(,881) 
tar.texi(,882) @table @option
tar.texi(xopindex,883) @opindex verbose@r{, introduced}
tar.texi(,884) @item --verbose
tar.texi(,885) @itemx -v
tar.texi(,886) Show the files being worked on as @command{tar} is running.
tar.texi(,887) @end table
tar.texi(,888) 
tar.texi(,889) @option{--verbose} (@option{-v}) shows details about the results of running
tar.texi(,890) @command{tar}.  This can be especially useful when the results might not be
tar.texi(,891) obvious.  For example, if you want to see the progress of @command{tar} as
tar.texi(,892) it writes files into the archive, you can use the @option{--verbose}
tar.texi(,893) option.  In the beginning, you may find it useful to use
tar.texi(,894) @option{--verbose} at all times; when you are more accustomed to
tar.texi(,895) @command{tar}, you will likely want to use it at certain times but not at
tar.texi(,896) others.  We will use @option{--verbose} at times to help make something
tar.texi(,897) clear, and we will give many examples both using and not using
tar.texi(,898) @option{--verbose} to show the differences.
tar.texi(,899) 
tar.texi(,900) Each instance of @option{--verbose} on the command line increases the
tar.texi(,901) verbosity level by one, so if you need more details on the output, 
tar.texi(,902) specify it twice.
tar.texi(,903) 
tar.texi(,904) When reading archives (@option{--list}, @option{--extract},
tar.texi(,905) @option{--diff}), @command{tar} by default prints only the names of
tar.texi(,906) the members being extracted.  Using @option{--verbose} will show a full,
tar.texi(,907) @command{ls} style member listing.
tar.texi(,908) 
tar.texi(,909) In contrast, when writing archives (@option{--create}, @option{--append},
tar.texi(,910) @option{--update}), @command{tar} does not print file names by
tar.texi(,911) default.  So, a single @option{--verbose} option shows the file names
tar.texi(,912) being added to the archive, while two @option{--verbose} options
tar.texi(,913) enable the full listing.
tar.texi(,914)    
tar.texi(,915) For example, to create an archive in verbose mode:
tar.texi(,916) 
tar.texi(,917) @smallexample
tar.texi(,918) $ @kbd{tar -cvf afiles.tar apple angst aspic}
tar.texi(,919) apple
tar.texi(,920) angst
tar.texi(,921) aspic
tar.texi(,922) @end smallexample
tar.texi(,923) 
tar.texi(,924) @noindent
tar.texi(,925) Creating the same archive with the verbosity level 2 could give:
tar.texi(,926) 
tar.texi(,927) @smallexample
tar.texi(,928) $ @kbd{tar -cvvf afiles.tar apple angst aspic}
tar.texi(,929) -rw-r--r-- gray/staff    62373 2006-06-09 12:06 apple
tar.texi(,930) -rw-r--r-- gray/staff    11481 2006-06-09 12:06 angst
tar.texi(,931) -rw-r--r-- gray/staff    23152 2006-06-09 12:06 aspic
tar.texi(,932) @end smallexample
tar.texi(,933) 
tar.texi(,934) @noindent
tar.texi(,935) This works equally well using short or long forms of options.  Using
tar.texi(,936) long forms, you would simply write out the mnemonic form of the option
tar.texi(,937) twice, like this:
tar.texi(,938) 
tar.texi(,939) @smallexample
tar.texi(,940) $ @kbd{tar --create --verbose --verbose @dots{}}
tar.texi(,941) @end smallexample
tar.texi(,942) 
tar.texi(,943) @noindent
tar.texi(,944) Note that you must double the hyphens properly each time.
tar.texi(,945) 
tar.texi(,946) Later in the tutorial, we will give examples using @w{@option{--verbose
tar.texi(,947) --verbose}}.
tar.texi(,948) 
tar.texi(,949) @anchor{verbose member listing}
tar.texi(,950) The full output consists of six fields:
tar.texi(,951) 
tar.texi(,952) @itemize @bullet
tar.texi(,953) @item File type and permissions in symbolic form.
tar.texi(,954) These are displayed in the same format as the first column of
tar.texi(,955) @command{ls -l} output (@pxref{What information is listed,
tar.texi(,956) format=verbose, Verbose listing, fileutils, GNU file utilities}).
tar.texi(,957) 
tar.texi(,958) @item Owner name and group separated by a slash character.
tar.texi(,959) If these data are not available (for example, when listing a @samp{v7} format
tar.texi(,960) archive), numeric ID values are printed instead.
tar.texi(,961) 
tar.texi(,962) @item Size of the file, in bytes.
tar.texi(,963) 
tar.texi(,964) @item File modification date in ISO 8601 format.
tar.texi(,965) 
tar.texi(,966) @item File modification time.
tar.texi(,967) 
tar.texi(,968) @item File name.
tar.texi(,969) If the name contains any special characters (white space, newlines,
tar.texi(,970) etc.) these are displayed in an unambiguous form using so called
tar.texi(,971) @dfn{quoting style}.  For the detailed discussion of available styles
tar.texi(,972) and on how to use them, see @ref{quoting styles}.
tar.texi(,973) 
tar.texi(,974) Depending on the file type, the name can be followed by some
tar.texi(,975) additional information, described in the following table:
tar.texi(,976) 
tar.texi(,977) @table @samp
tar.texi(,978) @item -> @var{link-name}
tar.texi(,979) The file or archive member is a @dfn{symbolic link} and
tar.texi(,980) @var{link-name} is the name of file it links to.
tar.texi(,981) 
tar.texi(,982) @item link to @var{link-name}
tar.texi(,983) The file or archive member is a @dfn{hard link} and @var{link-name} is
tar.texi(,984) the name of file it links to.
tar.texi(,985) 
tar.texi(,986) @item --Long Link--
tar.texi(,987) The archive member is an old GNU format long link.  You will normally
tar.texi(,988) not encounter this.
tar.texi(,989) 
tar.texi(,990) @item --Long Name--
tar.texi(,991) The archive member is an old GNU format long name.  You will normally
tar.texi(,992) not encounter this.
tar.texi(,993) 
tar.texi(,994) @item --Volume Header--
tar.texi(,995) The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}).
tar.texi(,996) 
tar.texi(,997) @item --Continued at byte @var{n}--
tar.texi(,998) Encountered only at the beginning of a multy-volume archive
tar.texi(,999) (@pxref{Using Multiple Tapes}).  This archive member is a continuation
tar.texi(,1000) from the previous volume. The number @var{n} gives the offset where
tar.texi(,1001) the original file was split.  
tar.texi(,1002) 
tar.texi(,1003) @item --Mangled file names--
tar.texi(,1004) This archive member contains @dfn{mangled file names} declarations,
tar.texi(GNUTAR,1005) a special member type that was used by early versions of tar.texi(GNUTAR,1005) @acronym{GNU} @command{tar}.
tar.texi(,1006) You probably will never encounter this, unless you are reading a very
tar.texi(,1007) old archive.
tar.texi(,1008) 
tar.texi(,1009) @item  unknown file type @var{c}
tar.texi(,1010) An archive member of unknown type. @var{c} is the type character from
tar.texi(,1011) the archive header.  If you encounter such a message, it means that
tar.texi(GNUTAR,1012) either your archive contains proprietary member types tar.texi(GNUTAR,1012) @acronym{GNU} @command{tar} is not
tar.texi(,1013) able to handle, or the archive is corrupted.
tar.texi(,1014) @end table
tar.texi(,1015) 
tar.texi(,1016) @end itemize
tar.texi(,1017) 
tar.texi(,1018) For example, here is an archive listing containing most of the special
tar.texi(,1019) suffixes explained above:
tar.texi(,1020) 
tar.texi(,1021) @smallexample
tar.texi(,1022) @group
tar.texi(,1023) V--------- 0/0          1536 2006-06-09 13:07 MyVolume--Volume Header--
tar.texi(,1024) -rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
tar.texi(,1025) byte 32456--
tar.texi(,1026) -rw-r--r-- gray/staff  62373 2006-06-09 12:06 apple
tar.texi(,1027) lrwxrwxrwx gray/staff      0 2006-06-09 13:01 angst -> apple
tar.texi(,1028) -rw-r--r-- gray/staff  35793 2006-06-09 12:06 blues
tar.texi(,1029) hrw-r--r-- gray/staff      0 2006-06-09 12:06 music link to blues
tar.texi(,1030) @end group
tar.texi(,1031) @end smallexample
tar.texi(,1032) 
tar.texi(,1033) @smallexample
tar.texi(,1034) @end smallexample
tar.texi(,1035) 
tar.texi(,1036) @node help tutorial
tar.texi(,1037) @unnumberedsubsec Getting Help: Using the @option{--help} Option
tar.texi(,1038) 
tar.texi(,1039) @table @option
tar.texi(,1040) @opindex help
tar.texi(,1041) @item --help
tar.texi(,1042) 
tar.texi(,1043) The @option{--help} option to @command{tar} prints out a very brief list of
tar.texi(,1044) all operations and option available for the current version of
tar.texi(,1045) @command{tar} available on your system.
tar.texi(,1046) @end table
tar.texi(,1047) 
tar.texi(,1048) @node create
tar.texi(,1049) @section How to Create Archives
tar.texi(UNREVISED,1050) @quotation
tar.texi(UNREVISED,1050) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,1050) @end quotation
tar.texi(,1051) 
tar.texi(,1052) @cindex Creation of the archive
tar.texi(,1053) @cindex Archive, creation of
tar.texi(,1054) One of the basic operations of @command{tar} is @option{--create} (@option{-c}), which
tar.texi(,1055) you use to create a @command{tar} archive.  We will explain
tar.texi(,1056) @option{--create} first because, in order to learn about the other
tar.texi(,1057) operations, you will find it useful to have an archive available to
tar.texi(,1058) practice on.
tar.texi(,1059) 
tar.texi(,1060) To make this easier, in this section you will first create a directory
tar.texi(,1061) containing three files.  Then, we will show you how to create an
tar.texi(,1062) @emph{archive} (inside the new directory).  Both the directory, and
tar.texi(,1063) the archive are specifically for you to practice on.  The rest of this
tar.texi(,1064) chapter and the next chapter will show many examples using this
tar.texi(,1065) directory and the files you will create: some of those files may be
tar.texi(,1066) other directories and other archives.
tar.texi(,1067) 
tar.texi(,1068) The three files you will archive in this example are called
tar.texi(,1069) @file{blues}, @file{folk}, and @file{jazz}.  The archive is called
tar.texi(,1070) @file{collection.tar}.
tar.texi(,1071) 
tar.texi(,1072) This section will proceed slowly, detailing how to use @option{--create}
tar.texi(,1073) in @code{verbose} mode, and showing examples using both short and long
tar.texi(,1074) forms.  In the rest of the tutorial, and in the examples in the next
tar.texi(,1075) chapter, we will proceed at a slightly quicker pace.  This section
tar.texi(,1076) moves more slowly to allow beginning users to understand how
tar.texi(,1077) @command{tar} works.
tar.texi(,1078) 
tar.texi(,1079) @menu
tar.texi(,1080) * prepare for examples::
tar.texi(,1081) * Creating the archive::
tar.texi(,1082) * create verbose::
tar.texi(,1083) * short create::
tar.texi(,1084) * create dir::
tar.texi(,1085) @end menu
tar.texi(,1086) 
tar.texi(,1087) @node prepare for examples
tar.texi(,1088) @subsection Preparing a Practice Directory for Examples
tar.texi(,1089) 
tar.texi(,1090) To follow along with this and future examples, create a new directory
tar.texi(,1091) called @file{practice} containing files called @file{blues}, @file{folk}
tar.texi(,1092) and @file{jazz}.  The files can contain any information you like:
tar.texi(,1093) ideally, they should contain information which relates to their names,
tar.texi(,1094) and be of different lengths.  Our examples assume that @file{practice}
tar.texi(,1095) is a subdirectory of your home directory.
tar.texi(,1096) 
tar.texi(,1097) Now @command{cd} to the directory named @file{practice}; @file{practice}
tar.texi(,1098) is now your @dfn{working directory}.  (@emph{Please note}: Although
tar.texi(,1099) the full path name of this directory is
tar.texi(,1100) @file{/@var{homedir}/practice}, in our examples we will refer to
tar.texi(,1101) this directory as @file{practice}; the @var{homedir} is presumed.
tar.texi(,1102) 
tar.texi(,1103) In general, you should check that the files to be archived exist where
tar.texi(,1104) you think they do (in the working directory) by running @command{ls}.
tar.texi(,1105) Because you just created the directory and the files and have changed to
tar.texi(,1106) that directory, you probably don't need to do that this time.
tar.texi(,1107) 
tar.texi(,1108) It is very important to make sure there isn't already a file in the
tar.texi(,1109) working directory with the archive name you intend to use (in this case,
tar.texi(,1110) @samp{collection.tar}), or that you don't care about its contents.
tar.texi(,1111) Whenever you use @samp{create}, @command{tar} will erase the current
tar.texi(,1112) contents of the file named by @option{--file=@var{archive-name}} (@option{-f @var{archive-name}}) if it exists.  @command{tar}
tar.texi(,1113) will not tell you if you are about to overwrite an archive unless you
tar.texi(,1114) specify an option which does this (@pxref{backup}, for the
tar.texi(,1115) information on how to do so).  To add files to an existing archive,
tar.texi(,1116) you need to use a different option, such as @option{--append} (@option{-r}); see
tar.texi(,1117) @ref{append} for information on how to do this.
tar.texi(,1118) 
tar.texi(,1119) @node Creating the archive
tar.texi(,1120) @subsection Creating the Archive
tar.texi(,1121) 
tar.texi(xopindex,1122) @opindex create@r{, introduced}
tar.texi(,1123) To place the files @file{blues}, @file{folk}, and @file{jazz} into an
tar.texi(,1124) archive named @file{collection.tar}, use the following command:
tar.texi(,1125) 
tar.texi(,1126) @smallexample
tar.texi(,1127) $ @kbd{tar --create --file=collection.tar blues folk jazz}
tar.texi(,1128) @end smallexample
tar.texi(,1129) 
tar.texi(,1130) The order of the arguments is not very important, @emph{when using long
tar.texi(,1131) option forms}.  You could also say:
tar.texi(,1132) 
tar.texi(,1133) @smallexample
tar.texi(,1134) $ @kbd{tar blues --create folk --file=collection.tar jazz}
tar.texi(,1135) @end smallexample
tar.texi(,1136) 
tar.texi(,1137) @noindent
tar.texi(,1138) However, you can see that this order is harder to understand; this is
tar.texi(,1139) why we will list the arguments in the order that makes the commands
tar.texi(,1140) easiest to understand (and we encourage you to do the same when you use
tar.texi(,1141) @command{tar}, to avoid errors).
tar.texi(,1142) 
tar.texi(,1143) Note that the sequence
tar.texi(,1144) @option{--file=@-collection.tar} is considered to be @emph{one} argument.
tar.texi(,1145) If you substituted any other string of characters for
tar.texi(,1146) @kbd{collection.tar},  then that string would become the name of the
tar.texi(,1147) archive file you create.
tar.texi(,1148) 
tar.texi(,1149) The order of the options becomes more important when you begin to use
tar.texi(,1150) short forms.  With short forms, if you type commands in the wrong order
tar.texi(,1151) (even if you type them correctly in all other ways), you may end up with
tar.texi(,1152) results you don't expect.  For this reason, it is a good idea to get
tar.texi(,1153) into the habit of typing options in the order that makes inherent sense.
tar.texi(,1154) @xref{short create}, for more information on this.
tar.texi(,1155) 
tar.texi(,1156) In this example, you type the command as shown above: @option{--create}
tar.texi(,1157) is the operation which creates the new archive
tar.texi(,1158) (@file{collection.tar}), and @option{--file} is the option which lets
tar.texi(,1159) you give it the name you chose.  The files, @file{blues}, @file{folk},
tar.texi(,1160) and @file{jazz}, are now members of the archive, @file{collection.tar}
tar.texi(,1161) (they are @dfn{file name arguments} to the @option{--create} operation.
tar.texi(,1162) @xref{Choosing}, for the detailed discussion on these.) Now that they are
tar.texi(,1163) in the archive, they are called @emph{archive members}, not files.
tar.texi(,1164) (@pxref{Definitions,members}).
tar.texi(,1165) 
tar.texi(,1166) When you create an archive, you @emph{must} specify which files you
tar.texi(,1167) want placed in the archive.  If you do not specify any archive
tar.texi(GNUTAR,1168) members, tar.texi(GNUTAR,1168) @acronym{GNU} @command{tar} will complain.
tar.texi(,1169) 
tar.texi(,1170) If you now list the contents of the working directory (@command{ls}), you will
tar.texi(,1171) find the archive file listed as well as the files you saw previously:
tar.texi(,1172) 
tar.texi(,1173) @smallexample
tar.texi(,1174) blues   folk   jazz   collection.tar
tar.texi(,1175) @end smallexample
tar.texi(,1176) 
tar.texi(,1177) @noindent
tar.texi(,1178) Creating the archive @samp{collection.tar} did not destroy the copies of
tar.texi(,1179) the files in the directory.
tar.texi(,1180) 
tar.texi(,1181) Keep in mind that if you don't indicate an operation, @command{tar} will not
tar.texi(,1182) run and will prompt you for one.  If you don't name any files, @command{tar}
tar.texi(,1183) will complain.  You must have write access to the working directory,
tar.texi(,1184) or else you will not be able to create an archive in that directory.
tar.texi(,1185) 
tar.texi(,1186) @emph{Caution}: Do not attempt to use @option{--create} (@option{-c}) to add files to
tar.texi(,1187) an existing archive; it will delete the archive and write a new one.
tar.texi(,1188) Use @option{--append} (@option{-r}) instead.  @xref{append}.
tar.texi(,1189) 
tar.texi(,1190) @node create verbose
tar.texi(,1191) @subsection Running @option{--create} with @option{--verbose}
tar.texi(,1192) 
tar.texi(xopindex,1193) @opindex create@r{, using with @option{--verbose}}
tar.texi(xopindex,1194) @opindex verbose@r{, using with @option{--create}}
tar.texi(,1195) If you include the @option{--verbose} (@option{-v}) option on the command line,
tar.texi(,1196) @command{tar} will list the files it is acting on as it is working.  In
tar.texi(,1197) verbose mode, the @code{create} example above would appear as:
tar.texi(,1198) 
tar.texi(,1199) @smallexample
tar.texi(,1200) $ @kbd{tar --create --verbose --file=collection.tar blues folk jazz}
tar.texi(,1201) blues
tar.texi(,1202) folk
tar.texi(,1203) jazz
tar.texi(,1204) @end smallexample
tar.texi(,1205) 
tar.texi(,1206) This example is just like the example we showed which did not use
tar.texi(,1207) @option{--verbose}, except that @command{tar} generated the remaining lines
tar.texi(,1214) 
tar.texi(,1215) In the rest of the examples in this chapter, we will frequently use
tar.texi(,1216) @code{verbose} mode so we can show actions or @command{tar} responses that
tar.texi(,1217) you would otherwise not see, and which are important for you to
tar.texi(,1218) understand.
tar.texi(,1219) 
tar.texi(,1220) @node short create
tar.texi(,1221) @subsection Short Forms with @samp{create}
tar.texi(,1222) 
tar.texi(,1223) As we said before, the @option{--create} (@option{-c}) operation is one of the most
tar.texi(,1224) basic uses of @command{tar}, and you will use it countless times.
tar.texi(,1225) Eventually, you will probably want to use abbreviated (or ``short'')
tar.texi(,1226) forms of options.  A full discussion of the three different forms that
tar.texi(,1227) options can take appears in @ref{Styles}; for now, here is what the
tar.texi(,1228) previous example (including the @option{--verbose} (@option{-v}) option) looks like
tar.texi(,1229) using short option forms:
tar.texi(,1230) 
tar.texi(,1231) @smallexample
tar.texi(,1232) $ @kbd{tar -cvf collection.tar blues folk jazz}
tar.texi(,1233) blues
tar.texi(,1234) folk
tar.texi(,1235) jazz
tar.texi(,1236) @end smallexample
tar.texi(,1237) 
tar.texi(,1238) @noindent
tar.texi(,1239) As you can see, the system responds the same no matter whether you use
tar.texi(,1240) long or short option forms.
tar.texi(,1241) 
tar.texi(FIXME,1242) @allow-recursion
tar.texi(FIXME,1242) @quote-arg
tar.texi(FIXME,1242)  One difference between using
tar.texi(,1243) short and long option forms is that, although the exact placement of
tar.texi(,1244) arguments following options is no more specific when using short forms,
tar.texi(,1245) it is easier to become confused and make a mistake when using short
tar.texi(,1246) forms.  For example, suppose you attempted the above example in the
tar.texi(,1247) following way:
tar.texi(,1248) 
tar.texi(,1249) @smallexample
tar.texi(,1250) $ @kbd{tar -cfv collection.tar blues folk jazz}
tar.texi(,1251) @end smallexample
tar.texi(,1252) 
tar.texi(,1253) @noindent
tar.texi(,1254) In this case, @command{tar} will make an archive file called @file{v},
tar.texi(,1255) containing the files @file{blues}, @file{folk}, and @file{jazz}, because
tar.texi(,1256) the @samp{v} is the closest ``file name'' to the @option{-f} option, and
tar.texi(,1257) is thus taken to be the chosen archive file name.  @command{tar} will try
tar.texi(,1258) to add a file called @file{collection.tar} to the @file{v} archive file;
tar.texi(,1259) if the file @file{collection.tar} did not already exist, @command{tar} will
tar.texi(,1260) report an error indicating that this file does not exist.  If the file
tar.texi(,1261) @file{collection.tar} does already exist (e.g., from a previous command
tar.texi(,1262) you may have run), then @command{tar} will add this file to the archive.
tar.texi(,1263) Because the @option{-v} option did not get registered, @command{tar} will not
tar.texi(,1264) run under @samp{verbose} mode, and will not report its progress.
tar.texi(,1265) 
tar.texi(,1266) The end result is that you may be quite confused about what happened,
tar.texi(,1267) and possibly overwrite a file.  To illustrate this further, we will show
tar.texi(,1268) you how an example we showed previously would look using short forms.
tar.texi(,1269) 
tar.texi(,1270) This example,
tar.texi(,1271) 
tar.texi(,1272) @smallexample
tar.texi(,1273) $ @kbd{tar blues --create folk --file=collection.tar jazz}
tar.texi(,1274) @end smallexample
tar.texi(,1275) 
tar.texi(,1276) @noindent
tar.texi(,1277) is confusing as it is.  When shown using short forms, however, it
tar.texi(,1278) becomes much more so:
tar.texi(,1279) 
tar.texi(,1280) @smallexample
tar.texi(,1281) $ @kbd{tar blues -c folk -f collection.tar jazz}
tar.texi(,1282) @end smallexample
tar.texi(,1283) 
tar.texi(,1284) @noindent
tar.texi(,1285) It would be very easy to put the wrong string of characters
tar.texi(,1286) immediately following the @option{-f}, but doing that could sacrifice
tar.texi(,1287) valuable data.
tar.texi(,1288) 
tar.texi(,1289) For this reason, we recommend that you pay very careful attention to
tar.texi(,1290) the order of options and placement of file and archive names,
tar.texi(,1291) especially when using short option forms.  Not having the option name
tar.texi(,1292) written out mnemonically can affect how well you remember which option
tar.texi(,1293) does what, and therefore where different names have to be placed.
tar.texi(,1294) 
tar.texi(,1295) @node create dir
tar.texi(,1296) @subsection Archiving Directories
tar.texi(,1297) 
tar.texi(,1298) @cindex Archiving Directories
tar.texi(,1299) @cindex Directories, Archiving
tar.texi(,1300) You can archive a directory by specifying its directory name as a
tar.texi(,1301) file name argument to @command{tar}.  The files in the directory will be
tar.texi(,1302) archived relative to the working directory, and the directory will be
tar.texi(,1303) re-created along with its contents when the archive is extracted.
tar.texi(,1304) 
tar.texi(,1305) To archive a directory, first move to its superior directory.  If you
tar.texi(,1306) have followed the previous instructions in this tutorial, you should
tar.texi(,1307) type:
tar.texi(,1308) 
tar.texi(,1309) @smallexample
tar.texi(,1310) $ @kbd{cd ..}
tar.texi(,1311) $
tar.texi(,1312) @end smallexample
tar.texi(,1313) 
tar.texi(,1314) @noindent
tar.texi(,1315) This will put you into the directory which contains @file{practice},
tar.texi(,1316) i.e., your home directory.  Once in the superior directory, you can
tar.texi(,1317) specify the subdirectory, @file{practice}, as a file name argument.  To
tar.texi(,1318) store @file{practice} in the new archive file @file{music.tar}, type:
tar.texi(,1319) 
tar.texi(,1320) @smallexample
tar.texi(,1321) $ @kbd{tar --create --verbose --file=music.tar practice}
tar.texi(,1322) @end smallexample
tar.texi(,1323) 
tar.texi(,1324) @noindent
tar.texi(,1325) @command{tar} should output:
tar.texi(,1326) 
tar.texi(,1327) @smallexample
tar.texi(,1328) practice/
tar.texi(,1329) practice/blues
tar.texi(,1330) practice/folk
tar.texi(,1331) practice/jazz
tar.texi(,1332) practice/collection.tar
tar.texi(,1333) @end smallexample
tar.texi(,1334) 
tar.texi(,1335) Note that the archive thus created is not in the subdirectory
tar.texi(,1336) @file{practice}, but rather in the current working directory---the
tar.texi(,1337) directory from which @command{tar} was invoked.  Before trying to archive a
tar.texi(,1338) directory from its superior directory, you should make sure you have
tar.texi(,1339) write access to the superior directory itself, not only the directory
tar.texi(,1340) you are trying archive with @command{tar}.  For example, you will probably
tar.texi(,1341) not be able to store your home directory in an archive by invoking
tar.texi(,1342) @command{tar} from the root directory; @xref{absolute}.  (Note
tar.texi(,1343) also that @file{collection.tar}, the original archive file, has itself
tar.texi(,1344) been archived.  @command{tar} will accept any file as a file to be
tar.texi(,1345) archived, regardless of its content.  When @file{music.tar} is
tar.texi(,1346) extracted, the archive file @file{collection.tar} will be re-written
tar.texi(,1347) into the file system).
tar.texi(,1348) 
tar.texi(,1349) If you give @command{tar} a command such as
tar.texi(,1350) 
tar.texi(,1351) @smallexample
tar.texi(,1352) $ @kbd{tar --create --file=foo.tar .}
tar.texi(,1353) @end smallexample
tar.texi(,1354) 
tar.texi(,1355) @noindent
tar.texi(,1356) @command{tar} will report @samp{tar: ./foo.tar is the archive; not
tar.texi(,1357) dumped}.  This happens because @command{tar} creates the archive
tar.texi(,1358) @file{foo.tar} in the current directory before putting any files into
tar.texi(,1359) it.  Then, when @command{tar} attempts to add all the files in the
tar.texi(,1360) directory @file{.} to the archive, it notices that the file
tar.texi(,1361) @file{./foo.tar} is the same as the archive @file{foo.tar}, and skips
tar.texi(GNUTAR,1362) it.  (It makes no sense to put an archive into itself.)  tar.texi(GNUTAR,1362) @acronym{GNU} @command{tar}
tar.texi(,1363) will continue in this case, and create the archive
tar.texi(,1364) normally, except for the exclusion of that one file.  (@emph{Please
tar.texi(,1365) note:} Other implementations of @command{tar} may not be so clever;
tar.texi(,1366) they will enter an infinite loop when this happens, so you should not
tar.texi(,1367) depend on this behavior unless you are certain you are running
tar.texi(GNUTAR,1368) @acronym{GNU} @command{tar}.  In general, it is wise to always place the archive outside
tar.texi(,1369) of the directory being dumped.
tar.texi(,1370) 
tar.texi(,1371) @node list
tar.texi(,1372) @section How to List Archives
tar.texi(,1373) 
tar.texi(,1374) @opindex list
tar.texi(,1375) Frequently, you will find yourself wanting to determine exactly what a
tar.texi(,1376) particular archive contains.  You can use the @option{--list}
tar.texi(,1377) (@option{-t}) operation to get the member names as they currently
tar.texi(,1378) appear in the archive, as well as various attributes of the files at
tar.texi(,1379) the time they were archived.  For example, you can examine the archive
tar.texi(,1380) @file{collection.tar} that you created in the last section with the
tar.texi(,1381) command, 
tar.texi(,1382) 
tar.texi(,1383) @smallexample
tar.texi(,1384) $ @kbd{tar --list --file=collection.tar}
tar.texi(,1385) @end smallexample
tar.texi(,1386) 
tar.texi(,1387) @noindent
tar.texi(,1388) The output of @command{tar} would then be:
tar.texi(,1389) 
tar.texi(,1390) @smallexample
tar.texi(,1391) blues
tar.texi(,1392) folk
tar.texi(,1393) jazz
tar.texi(,1394) @end smallexample
tar.texi(,1395) 
tar.texi(,1396) @noindent
tar.texi(,1397) The archive @file{bfiles.tar} would list as follows:
tar.texi(,1398) 
tar.texi(,1399) @smallexample
tar.texi(,1400) ./birds
tar.texi(,1401) baboon
tar.texi(,1402) ./box
tar.texi(,1403) @end smallexample
tar.texi(,1404) 
tar.texi(,1405) @noindent
tar.texi(,1406) Be sure to use a @option{--file=@var{archive-name}} (@option{-f
tar.texi(,1407) @var{archive-name}}) option just as with @option{--create}
tar.texi(,1408) (@option{-c}) to specify the name of the archive.
tar.texi(,1409) 
tar.texi(xopindex,1410) @opindex list@r{, using with @option{--verbose}}
tar.texi(xopindex,1411) @opindex verbose@r{, using with @option{--list}}
tar.texi(,1412) If you use the @option{--verbose} (@option{-v}) option with
tar.texi(,1413) @option{--list}, then @command{tar} will print out a listing
tar.texi(,1414) reminiscent of @w{@samp{ls -l}}, showing owner, file size, and so
tar.texi(,1415) forth.  This output is described in detail in @ref{verbose member listing}.
tar.texi(,1416) 
tar.texi(,1417) If you had used @option{--verbose} (@option{-v}) mode, the example
tar.texi(,1418) above would look like:
tar.texi(,1419) 
tar.texi(,1420) @smallexample
tar.texi(,1421) $ @kbd{tar --list --verbose --file=collection.tar folk}
tar.texi(,1422) -rw-r--r-- myself user 62 1990-05-23 10:55 folk
tar.texi(,1423) @end smallexample
tar.texi(,1424) 
tar.texi(,1425) @cindex listing member and file names
tar.texi(,1426) @anchor{listing member and file names}
tar.texi(,1427) It is important to notice that the output of @kbd{tar --list
tar.texi(,1428) --verbose} does not necessarily match that produced by @kbd{tar
tar.texi(,1429) --create --verbose} while creating the archive.  It is because
tar.texi(GNUTAR,1430) @acronym{GNU} @command{tar}, unless told explicitly not to do so, removes some directory
tar.texi(,1431) prefixes from file names before storing them in the archive
tar.texi(,1432) (@xref{absolute}, for more information).  In other
tar.texi(GNUTAR,1433) words, in verbose mode tar.texi(GNUTAR,1433) @acronym{GNU} @command{tar} shows @dfn{file names} when creating
tar.texi(,1434) an archive and @dfn{member names} when listing it.  Consider this
tar.texi(,1435) example:
tar.texi(,1436) 
tar.texi(,1437) @smallexample
tar.texi(,1438) @group
tar.texi(,1439) $ @kbd{tar cfv archive /etc/mail}
tar.texi(,1440) tar: Removing leading `/' from member names
tar.texi(,1441) /etc/mail/
tar.texi(,1442) /etc/mail/sendmail.cf
tar.texi(,1443) /etc/mail/aliases
tar.texi(,1444) $ @kbd{tar tf archive}
tar.texi(,1445) etc/mail/
tar.texi(,1446) etc/mail/sendmail.cf
tar.texi(,1447) etc/mail/aliases
tar.texi(,1448) @end group
tar.texi(,1449) @end smallexample
tar.texi(,1450) 
tar.texi(,1451) @opindex show-stored-names
tar.texi(,1452)   This default behavior can sometimes be inconvenient.  You can force
tar.texi(GNUTAR,1453) @acronym{GNU} @command{tar} show member names when creating archive by supplying
tar.texi(,1454) @option{--show-stored-names} option.
tar.texi(,1455) 
tar.texi(,1456) @table @option
tar.texi(,1457) @item --show-stored-names
tar.texi(,1458) Print member (as opposed to @emph{file}) names when creating the archive.
tar.texi(,1459) @end table
tar.texi(,1460) 
tar.texi(,1461) @cindex File name arguments, using @option{--list} with
tar.texi(xopindex,1462) @opindex list@r{, using with file name arguments}
tar.texi(,1463) You can specify one or more individual member names as arguments when
tar.texi(,1464) using @samp{list}.  In this case, @command{tar} will only list the
tar.texi(,1465) names of members you identify.  For example, @w{@kbd{tar --list
tar.texi(,1466) --file=afiles.tar apple}} would only print @file{apple}.
tar.texi(,1467) 
tar.texi(,1468) Because @command{tar} preserves paths, file names must be specified as
tar.texi(,1469) they appear in the archive (i.e., relative to the directory from which
tar.texi(,1470) the archive was created).  Therefore, it is essential when specifying
tar.texi(,1471) member names to @command{tar} that you give the exact member names.
tar.texi(,1472) For example, @w{@kbd{tar --list --file=bfiles.tar birds}} would produce an
tar.texi(,1473) error message something like @samp{tar: birds: Not found in archive},
tar.texi(,1474) because there is no member named @file{birds}, only one named
tar.texi(,1475) @file{./birds}.  While the names @file{birds} and @file{./birds} name
tar.texi(,1476) the same file, @emph{member} names by default are compared verbatim.
tar.texi(,1477) 
tar.texi(,1478) However, @w{@kbd{tar --list --file=bfiles.tar baboon}} would respond
tar.texi(,1479) with @file{baboon}, because this exact member name is in the archive file
tar.texi(,1480) @file{bfiles.tar}.  If you are not sure of the exact file name,
tar.texi(,1481) use @dfn{globbing patterns}, for example:
tar.texi(,1482) 
tar.texi(,1483) @smallexample
tar.texi(,1484) $ @kbd{tar --list --file=bfiles.tar --wildcards '*b*'}
tar.texi(,1485) @end smallexample
tar.texi(,1486) 
tar.texi(,1487) @noindent
tar.texi(,1488) will list all members whose name contains @samp{b}.  @xref{wildcards},
tar.texi(,1489) for a detailed discussion of globbing patterns and related
tar.texi(,1490) @command{tar} command line options.
tar.texi(,1491) 
tar.texi(,1492) @menu
tar.texi(,1493) * list dir::
tar.texi(,1494) @end menu
tar.texi(,1495) 
tar.texi(,1496) @node list dir
tar.texi(,1497) @unnumberedsubsec Listing the Contents of a Stored Directory
tar.texi(,1498) 
tar.texi(,1499) To get information about the contents of an archived directory,
tar.texi(,1500) use the directory name as a file name argument in conjunction with
tar.texi(,1501) @option{--list} (@option{-t}).  To find out file attributes, include the
tar.texi(,1502) @option{--verbose} (@option{-v}) option.
tar.texi(,1503) 
tar.texi(,1504) For example, to find out about files in the directory @file{practice}, in
tar.texi(,1505) the archive file @file{music.tar}, type:
tar.texi(,1506) 
tar.texi(,1507) @smallexample
tar.texi(,1508) $ @kbd{tar --list --verbose --file=music.tar practice}
tar.texi(,1509) @end smallexample
tar.texi(,1510) 
tar.texi(,1511) @command{tar} responds:
tar.texi(,1512) 
tar.texi(,1513) @smallexample
tar.texi(,1514) drwxrwxrwx myself user 0 1990-05-31 21:49 practice/
tar.texi(,1515) -rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues
tar.texi(,1516) -rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk
tar.texi(,1517) -rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz
tar.texi(,1518) -rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar
tar.texi(,1519) @end smallexample
tar.texi(,1520) 
tar.texi(,1521) When you use a directory name as a file name argument, @command{tar} acts on
tar.texi(,1522) all the files (including sub-directories) in that directory.
tar.texi(,1523) 
tar.texi(,1524) @node extract
tar.texi(,1525) @section How to Extract Members from an Archive
tar.texi(UNREVISED,1526) @quotation
tar.texi(UNREVISED,1526) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,1526) @end quotation
tar.texi(,1527) @cindex Extraction
tar.texi(,1528) @cindex Retrieving files from an archive
tar.texi(,1529) @cindex Resurrecting files from an archive
tar.texi(,1530) 
tar.texi(,1531) @opindex extract
tar.texi(,1532) Creating an archive is only half the job---there is no point in storing
tar.texi(,1533) files in an archive if you can't retrieve them.  The act of retrieving
tar.texi(,1534) members from an archive so they can be used and manipulated as
tar.texi(,1535) unarchived files again is called @dfn{extraction}.  To extract files
tar.texi(,1536) from an archive, use the @option{--extract} (@option{--get} or
tar.texi(,1537) @option{-x}) operation.  As with @option{--create}, specify the name
tar.texi(,1538) of the archive with @option{--file} (@option{-f}) option. Extracting
tar.texi(,1539) an archive does not modify the archive in any way; you can extract it
tar.texi(,1540) multiple times if you want or need to.
tar.texi(,1541) 
tar.texi(,1542) Using @option{--extract}, you can extract an entire archive, or specific
tar.texi(,1543) files.  The files can be directories containing other files, or not.  As
tar.texi(,1544) with @option{--create} (@option{-c}) and @option{--list} (@option{-t}), you may use the short or the
tar.texi(,1545) long form of the operation without affecting the performance.
tar.texi(,1546) 
tar.texi(,1547) @menu
tar.texi(,1548) * extracting archives::
tar.texi(,1549) * extracting files::
tar.texi(,1550) * extract dir::
tar.texi(,1551) * extracting untrusted archives::
tar.texi(,1552) * failing commands::
tar.texi(,1553) @end menu
tar.texi(,1554) 
tar.texi(,1555) @node extracting archives
tar.texi(,1556) @subsection Extracting an Entire Archive
tar.texi(,1557) 
tar.texi(,1558) To extract an entire archive, specify the archive file name only, with
tar.texi(,1559) no individual file names as arguments.  For example,
tar.texi(,1560) 
tar.texi(,1561) @smallexample
tar.texi(,1562) $ @kbd{tar -xvf collection.tar}
tar.texi(,1563) @end smallexample
tar.texi(,1564) 
tar.texi(,1565) @noindent
tar.texi(,1566) produces this:
tar.texi(,1567) 
tar.texi(,1568) @smallexample
tar.texi(,1569) -rw-r--r-- me user     28 1996-10-18 16:31 jazz
tar.texi(,1570) -rw-r--r-- me user     21 1996-09-23 16:44 blues
tar.texi(,1571) -rw-r--r-- me user     20 1996-09-23 16:44 folk
tar.texi(,1572) @end smallexample
tar.texi(,1573) 
tar.texi(,1574) @node extracting files
tar.texi(,1575) @subsection Extracting Specific Files
tar.texi(,1576) 
tar.texi(,1577) To extract specific archive members, give their exact member names as
tar.texi(,1578) arguments, as printed by @option{--list} (@option{-t}).  If you had
tar.texi(,1579) mistakenly deleted one of the files you had placed in the archive
tar.texi(,1580) @file{collection.tar} earlier (say, @file{blues}), you can extract it
tar.texi(,1581) from the archive without changing the archive's structure.  Its
tar.texi(,1582) contents will be identical to the original file @file{blues} that you
tar.texi(,1583) deleted. 
tar.texi(,1584) 
tar.texi(,1585) First, make sure you are in the @file{practice} directory, and list the
tar.texi(,1586) files in the directory.  Now, delete the file, @samp{blues}, and list
tar.texi(,1587) the files in the directory again.
tar.texi(,1588) 
tar.texi(,1589) You can now extract the member @file{blues} from the archive file
tar.texi(,1590) @file{collection.tar} like this:
tar.texi(,1591) 
tar.texi(,1592) @smallexample
tar.texi(,1593) $ @kbd{tar --extract --file=collection.tar blues}
tar.texi(,1594) @end smallexample
tar.texi(,1595) 
tar.texi(,1596) @noindent
tar.texi(,1597) If you list the files in the directory again, you will see that the file
tar.texi(,1598) @file{blues} has been restored, with its original permissions, data
tar.texi(,1599) modification times, and owner.@footnote{This is only accidentally
tar.texi(,1600) true, but not in general.  Whereas modification times are always
tar.texi(,1601) restored, in most cases, one has to be root for restoring the owner,
tar.texi(,1602) and use a special option for restoring permissions.  Here, it just
tar.texi(,1603) happens that the restoring user is also the owner of the archived
tar.texi(,1604) members, and that the current @code{umask} is compatible with original
tar.texi(,1605) permissions.}  (These parameters will be identical to those which
tar.texi(,1606) the file had when you originally placed it in the archive; any changes
tar.texi(,1607) you may have made before deleting the file from the file system,
tar.texi(,1608) however, will @emph{not} have been made to the archive member.)  The
tar.texi(,1609) archive file, @samp{collection.tar}, is the same as it was before you
tar.texi(,1610) extracted @samp{blues}.  You can confirm this by running @command{tar} with
tar.texi(,1611) @option{--list} (@option{-t}).
tar.texi(,1612) 
tar.texi(,1613) Remember that as with other operations, specifying the exact member
tar.texi(,1614) name is important.  @w{@kbd{tar --extract --file=bfiles.tar birds}}
tar.texi(,1615) will fail, because there is no member named @file{birds}.  To extract
tar.texi(,1616) the member named @file{./birds}, you must specify @w{@kbd{tar
tar.texi(,1617) --extract --file=bfiles.tar ./birds}}.  If you don't remember the
tar.texi(,1618) exact member names, use @option{--list} (@option{-t}) option
tar.texi(,1619) (@pxref{list}).  You can also extract those members that match a
tar.texi(,1620) specific @dfn{globbing pattern}.  For example, to extract from
tar.texi(,1621) @file{bfiles.tar} all files that begin with @samp{b}, no matter their
tar.texi(,1622) directory prefix, you could type:
tar.texi(,1623) 
tar.texi(,1624) @smallexample
tar.texi(,1625) $ @kbd{tar -x -f bfiles.tar --wildcards --no-anchored 'b*'}
tar.texi(,1626) @end smallexample
tar.texi(,1627) 
tar.texi(,1628) @noindent
tar.texi(,1629) Here, @option{--wildcards} instructs @command{tar} to treat
tar.texi(,1630) command line arguments as globbing patterns and @option{--no-anchored}
tar.texi(,1631) informs it that the patterns apply to member names after any @samp{/}
tar.texi(,1632) delimiter.  The use of globbing patterns is discussed in detail in
tar.texi(,1633) @xref{wildcards}. 
tar.texi(,1634) 
tar.texi(,1635) You can extract a file to standard output by combining the above options
tar.texi(,1636) with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard
tar.texi(,1637) Output}).
tar.texi(,1638) 
tar.texi(,1639) If you give the @option{--verbose} option, then @option{--extract}
tar.texi(,1640) will print the names of the archive members as it extracts them.
tar.texi(,1641) 
tar.texi(,1642) @node extract dir
tar.texi(,1643) @subsection Extracting Files that are Directories
tar.texi(,1644) 
tar.texi(,1645) Extracting directories which are members of an archive is similar to
tar.texi(,1646) extracting other files.  The main difference to be aware of is that if
tar.texi(,1647) the extracted directory has the same name as any directory already in
tar.texi(,1648) the working directory, then files in the extracted directory will be
tar.texi(,1649) placed into the directory of the same name.  Likewise, if there are
tar.texi(,1650) files in the pre-existing directory with the same names as the members
tar.texi(,1651) which you extract, the files from the extracted archive will replace
tar.texi(,1652) the files already in the working directory (and possible
tar.texi(,1653) subdirectories).  This will happen regardless of whether or not the
tar.texi(,1654) files in the working directory were more recent than those extracted
tar.texi(,1655) (there exist, however, special options that alter this behavior
tar.texi(,1656) @pxref{Writing}).
tar.texi(,1657) 
tar.texi(,1658) However, if a file was stored with a directory name as part of its file
tar.texi(,1659) name, and that directory does not exist under the working directory when
tar.texi(,1660) the file is extracted, @command{tar} will create the directory.
tar.texi(,1661) 
tar.texi(,1662) We can demonstrate how to use @option{--extract} to extract a directory
tar.texi(,1663) file with an example.  Change to the @file{practice} directory if you
tar.texi(,1664) weren't there, and remove the files @file{folk} and @file{jazz}.  Then,
tar.texi(,1665) go back to the parent directory and extract the archive
tar.texi(,1666) @file{music.tar}.  You may either extract the entire archive, or you may
tar.texi(,1667) extract only the files you just deleted.  To extract the entire archive,
tar.texi(,1668) don't give any file names as arguments after the archive name
tar.texi(,1669) @file{music.tar}.  To extract only the files you deleted, use the
tar.texi(,1670) following command:
tar.texi(,1671) 
tar.texi(,1672) @smallexample
tar.texi(,1673) $ @kbd{tar -xvf music.tar practice/folk practice/jazz}
tar.texi(,1674) practice/folk
tar.texi(,1675) practice/jazz
tar.texi(,1676) @end smallexample
tar.texi(,1677) 
tar.texi(,1678) @noindent
tar.texi(,1679) If you were to specify two @option{--verbose} (@option{-v}) options, @command{tar}
tar.texi(,1680) would have displayed more detail about the extracted files, as shown
tar.texi(,1681) in the example below:
tar.texi(,1682) 
tar.texi(,1683) @smallexample
tar.texi(,1684) $ @kbd{tar -xvvf music.tar practice/folk practice/jazz}
tar.texi(,1685) -rw-r--r-- me user     28 1996-10-18 16:31 practice/jazz
tar.texi(,1686) -rw-r--r-- me user     20 1996-09-23 16:44 practice/folk
tar.texi(,1687) @end smallexample
tar.texi(,1688) 
tar.texi(,1689) @noindent
tar.texi(,1690) Because you created the directory with @file{practice} as part of the
tar.texi(,1691) file names of each of the files by archiving the @file{practice}
tar.texi(,1692) directory as @file{practice}, you must give @file{practice} as part
tar.texi(,1693) of the file names when you extract those files from the archive.
tar.texi(,1694) 
tar.texi(,1695) @node extracting untrusted archives
tar.texi(,1696) @subsection Extracting Archives from Untrusted Sources
tar.texi(,1697) 
tar.texi(,1698) Extracting files from archives can overwrite files that already exist.
tar.texi(,1699) If you receive an archive from an untrusted source, you should make a
tar.texi(,1700) new directory and extract into that directory, so that you don't have
tar.texi(,1701) to worry about the extraction overwriting one of your existing files.
tar.texi(,1702) For example, if @file{untrusted.tar} came from somewhere else on the
tar.texi(,1703) Internet, and you don't necessarily trust its contents, you can
tar.texi(,1704) extract it as follows:
tar.texi(,1705) 
tar.texi(,1706) @smallexample
tar.texi(,1707) $ @kbd{mkdir newdir}
tar.texi(,1708) $ @kbd{cd newdir}
tar.texi(,1709) $ @kbd{tar -xvf ../untrusted.tar}
tar.texi(,1710) @end smallexample
tar.texi(,1711) 
tar.texi(,1712) It is also a good practice to examine contents of the archive
tar.texi(,1713) before extracting it, using @option{--list} (@option{-t}) option, possibly combined
tar.texi(,1714) with @option{--verbose} (@option{-v}).
tar.texi(,1715) 
tar.texi(,1716) @node failing commands
tar.texi(,1717) @subsection Commands That Will Fail
tar.texi(,1718) 
tar.texi(,1719) Here are some sample commands you might try which will not work, and why
tar.texi(,1720) they won't work.
tar.texi(,1721) 
tar.texi(,1722) If you try to use this command,
tar.texi(,1723) 
tar.texi(,1724) @smallexample
tar.texi(,1725) $ @kbd{tar -xvf music.tar folk jazz}
tar.texi(,1726) @end smallexample
tar.texi(,1727) 
tar.texi(,1728) @noindent
tar.texi(,1729) you will get the following response:
tar.texi(,1730) 
tar.texi(,1731) @smallexample
tar.texi(,1732) tar: folk: Not found in archive
tar.texi(,1733) tar: jazz: Not found in archive
tar.texi(,1734) $
tar.texi(,1735) @end smallexample
tar.texi(,1736) 
tar.texi(,1737) @noindent
tar.texi(,1738) This is because these files were not originally @emph{in} the parent
tar.texi(,1739) directory @file{..}, where the archive is located; they were in the
tar.texi(,1740) @file{practice} directory, and their file names reflect this:
tar.texi(,1741) 
tar.texi(,1742) @smallexample
tar.texi(,1743) $ @kbd{tar -tvf music.tar}
tar.texi(,1744) practice/folk
tar.texi(,1745) practice/jazz
tar.texi(,1746) practice/rock
tar.texi(,1747) @end smallexample
tar.texi(,1748) 
tar.texi(FIXME,1750) @allow-recursion
tar.texi(FIXME,1750) @quote-arg
tar.texi(FIXME,1750) 
tar.texi(,1751) 
tar.texi(,1752) @noindent
tar.texi(,1753) Likewise, if you try to use this command,
tar.texi(,1754) 
tar.texi(,1755) @smallexample
tar.texi(,1756) $ @kbd{tar -tvf music.tar folk jazz}
tar.texi(,1757) @end smallexample
tar.texi(,1758) 
tar.texi(,1759) @noindent
tar.texi(,1760) you would get a similar response.  Members with those names are not in the
tar.texi(,1761) archive.  You must use the correct member names, or wildcards, in order
tar.texi(,1762) to extract the files from the archive.
tar.texi(,1763) 
tar.texi(,1764) If you have forgotten the correct names of the files in the archive,
tar.texi(,1765) use @w{@kbd{tar --list --verbose}} to list them correctly.
tar.texi(,1766) 
tar.texi(FIXME,1767) @allow-recursion
tar.texi(FIXME,1767) @quote-arg
tar.texi(FIXME,1767) 
tar.texi(,1768) 
tar.texi(,1769) @node going further
tar.texi(,1770) @section Going Further Ahead in this Manual
tar.texi(,1771) 
tar.texi(FIXME,1773) @allow-recursion
tar.texi(FIXME,1773) @quote-arg
tar.texi(FIXME,1773) 
tar.texi(,1774) 
tar.texi(,1775) @node tar invocation
tar.texi(GNUTAR,1776) @chapter Invoking tar.texi(GNUTAR,1776) @acronym{GNU} @command{tar}
tar.texi(UNREVISED,1777) @quotation
tar.texi(UNREVISED,1777) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,1777) @end quotation
tar.texi(,1778) 
tar.texi(GNUTAR,1779) This chapter is about how one invokes the tar.texi(GNUTAR,1779) @acronym{GNU} @command{tar}
tar.texi(,1780) command, from the command synopsis (@pxref{Synopsis}).  There are
tar.texi(,1781) numerous options, and many styles for writing them.  One mandatory
tar.texi(,1782) option specifies the operation @command{tar} should perform
tar.texi(,1783) (@pxref{Operation Summary}), other options are meant to detail how
tar.texi(,1784) this operation should be performed (@pxref{Option Summary}).
tar.texi(,1785) Non-option arguments are not always interpreted the same way,
tar.texi(,1786) depending on what the operation is.
tar.texi(,1787) 
tar.texi(,1788) You will find in this chapter everything about option styles and rules for
tar.texi(,1789) writing them (@pxref{Styles}).  On the other hand, operations and options
tar.texi(,1790) are fully described elsewhere, in other chapters.  Here, you will find
tar.texi(,1791) only synthetic descriptions for operations and options, together with
tar.texi(,1792) pointers to other parts of the @command{tar} manual.
tar.texi(,1793) 
tar.texi(,1794) Some options are so special they are fully described right in this
tar.texi(,1795) chapter.  They have the effect of inhibiting the normal operation of
tar.texi(,1796) @command{tar} or else, they globally alter the amount of feedback the user
tar.texi(,1797) receives about what is going on.  These are the @option{--help} and
tar.texi(,1798) @option{--version} (@pxref{help}), @option{--verbose} (@pxref{verbose})
tar.texi(,1799) and @option{--interactive} options (@pxref{interactive}).
tar.texi(,1800) 
tar.texi(,1801) @menu
tar.texi(,1802) * Synopsis::
tar.texi(,1803) * using tar options::
tar.texi(,1804) * Styles::
tar.texi(,1805) * All Options::
tar.texi(,1806) * help::
tar.texi(,1807) * defaults::
tar.texi(,1808) * verbose::
tar.texi(,1809) * interactive::
tar.texi(,1810) @end menu
tar.texi(,1811) 
tar.texi(,1812) @node Synopsis
tar.texi(,1813) @section General Synopsis of @command{tar}
tar.texi(,1814) 
tar.texi(GNUTAR,1815) The tar.texi(GNUTAR,1815) @acronym{GNU} @command{tar} program is invoked as either one of:
tar.texi(,1816) 
tar.texi(,1817) @smallexample
tar.texi(,1818) @kbd{tar @var{option}@dots{} [@var{name}]@dots{}}
tar.texi(,1819) @kbd{tar @var{letter}@dots{} [@var{argument}]@dots{} [@var{option}]@dots{} [@var{name}]@dots{}}
tar.texi(,1820) @end smallexample
tar.texi(,1821) 
tar.texi(,1822) The second form is for when old options are being used.
tar.texi(,1823) 
tar.texi(,1824) You can use @command{tar} to store files in an archive, to extract them from
tar.texi(,1825) an archive, and to do other types of archive manipulation.  The primary
tar.texi(,1826) argument to @command{tar}, which is called the @dfn{operation}, specifies
tar.texi(,1827) which action to take.  The other arguments to @command{tar} are either
tar.texi(,1828) @dfn{options}, which change the way @command{tar} performs an operation,
tar.texi(,1829) or file names or archive members, which specify the files or members
tar.texi(,1830) @command{tar} is to act on.
tar.texi(,1831) 
tar.texi(,1832) You can actually type in arguments in any order, even if in this manual
tar.texi(,1833) the options always precede the other arguments, to make examples easier
tar.texi(,1834) to understand.  Further, the option stating the main operation mode
tar.texi(,1835) (the @command{tar} main command) is usually given first.
tar.texi(,1836) 
tar.texi(,1837) Each @var{name} in the synopsis above is interpreted as an archive member
tar.texi(,1838) name when the main command is one of @option{--compare}
tar.texi(,1839) (@option{--diff}, @option{-d}), @option{--delete}, @option{--extract}
tar.texi(,1840) (@option{--get}, @option{-x}), @option{--list} (@option{-t}) or
tar.texi(,1841) @option{--update} (@option{-u}).  When naming archive members, you
tar.texi(,1842) must give the exact name of the member in the archive, as it is
tar.texi(,1843) printed by @option{--list}.  For @option{--append} (@option{-r}) and
tar.texi(,1844) @option{--create} (@option{-c}), these @var{name} arguments specify
tar.texi(,1845) the names of either files or directory hierarchies to place in the archive.
tar.texi(,1846) These files or hierarchies should already exist in the file system,
tar.texi(,1847) prior to the execution of the @command{tar} command.
tar.texi(,1848) 
tar.texi(,1849) @command{tar} interprets relative file names as being relative to the
tar.texi(,1850) working directory.  @command{tar} will make all file names relative
tar.texi(,1851) (by removing leading slashes when archiving or restoring files),
tar.texi(,1852) unless you specify otherwise (using the @option{--absolute-names}
tar.texi(,1853) option).  @xref{absolute}, for more information about
tar.texi(,1854) @option{--absolute-names}.
tar.texi(,1855) 
tar.texi(,1856) If you give the name of a directory as either a file name or a member
tar.texi(,1857) name, then @command{tar} acts recursively on all the files and directories
tar.texi(,1858) beneath that directory.  For example, the name @file{/} identifies all
tar.texi(,1859) the files in the file system to @command{tar}.
tar.texi(,1860) 
tar.texi(,1861) The distinction between file names and archive member names is especially
tar.texi(,1862) important when shell globbing is used, and sometimes a source of confusion
tar.texi(,1863) for newcomers.  @xref{wildcards}, for more information about globbing.
tar.texi(,1864) The problem is that shells may only glob using existing files in the
tar.texi(,1865) file system.  Only @command{tar} itself may glob on archive members, so when
tar.texi(,1866) needed, you must ensure that wildcard characters reach @command{tar} without
tar.texi(,1867) being interpreted by the shell first.  Using a backslash before @samp{*}
tar.texi(,1868) or @samp{?}, or putting the whole argument between quotes, is usually
tar.texi(,1869) sufficient for this.
tar.texi(,1870) 
tar.texi(,1871) Even if @var{name}s are often specified on the command line, they
tar.texi(,1872) can also be read from a text file in the file system, using the
tar.texi(,1873) @option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}}) option.
tar.texi(,1874) 
tar.texi(,1875) If you don't use any file name arguments, @option{--append} (@option{-r}),
tar.texi(,1876) @option{--delete} and @option{--concatenate} (@option{--catenate},
tar.texi(,1877) @option{-A}) will do nothing, while @option{--create} (@option{-c})
tar.texi(,1878) will usually yield a diagnostic and inhibit @command{tar} execution.
tar.texi(,1879) The other operations of @command{tar} (@option{--list},
tar.texi(,1880) @option{--extract}, @option{--compare}, and @option{--update})
tar.texi(,1881) will act on the entire contents of the archive.
tar.texi(,1882) 
tar.texi(,1883) @cindex exit status
tar.texi(,1884) @cindex return status
tar.texi(GNUTAR,1885) Besides successful exits, tar.texi(GNUTAR,1885) @acronym{GNU} @command{tar} may fail for
tar.texi(,1886) many reasons.  Some reasons correspond to bad usage, that is, when the
tar.texi(,1887) @command{tar} command is improperly written.  Errors may be
tar.texi(,1888) encountered later, while encountering an error processing the archive
tar.texi(,1889) or the files.  Some errors are recoverable, in which case the failure
tar.texi(,1890) is delayed until @command{tar} has completed all its work.  Some
tar.texi(,1891) errors are such that it would not meaningful, or at least risky, to
tar.texi(,1892) continue processing: @command{tar} then aborts processing immediately.
tar.texi(,1893) All abnormal exits, whether immediate or delayed, should always be
tar.texi(,1894) clearly diagnosed on @code{stderr}, after a line stating the nature of
tar.texi(,1895) the error.
tar.texi(,1896) 
tar.texi(GNUTAR,1897) @acronym{GNU} @command{tar} returns only a few exit statuses.  I'm really
tar.texi(,1898) aiming simplicity in that area, for now.  If you are not using the
tar.texi(,1899) @option{--compare} @option{--diff}, @option{-d}) option, zero means
tar.texi(,1900) that everything went well, besides maybe innocuous warnings.  Nonzero
tar.texi(,1901) means that something went wrong. Right now, as of today, ``nonzero''
tar.texi(,1902) is almost always 2, except for remote operations, where it may be
tar.texi(,1903) 128.
tar.texi(,1904) 
tar.texi(,1905) @node using tar options
tar.texi(,1906) @section Using @command{tar} Options
tar.texi(,1907) 
tar.texi(GNUTAR,1908) @acronym{GNU} @command{tar} has a total of eight operating modes which
tar.texi(,1909) allow you to perform a variety of tasks.  You are required to choose
tar.texi(,1910) one operating mode each time you employ the @command{tar} program by
tar.texi(,1911) specifying one, and only one operation as an argument to the
tar.texi(,1912) @command{tar} command (two lists of four operations each may be found
tar.texi(,1913) at @ref{frequent operations} and @ref{Operations}).  Depending on
tar.texi(,1914) circumstances, you may also wish to customize how the chosen operating
tar.texi(,1915) mode behaves.  For example, you may wish to change the way the output
tar.texi(,1916) looks, or the format of the files that you wish to archive may require
tar.texi(,1917) you to do something special in order to make the archive look right.
tar.texi(,1918) 
tar.texi(,1919) You can customize and control @command{tar}'s performance by running
tar.texi(,1920) @command{tar} with one or more options (such as @option{--verbose}
tar.texi(,1921) (@option{-v}), which we used in the tutorial).  As we said in the
tar.texi(,1922) tutorial, @dfn{options} are arguments to @command{tar} which are (as
tar.texi(,1923) their name suggests) optional. Depending on the operating mode, you
tar.texi(,1924) may specify one or more options. Different options will have different
tar.texi(,1925) effects, but in general they all change details of the operation, such
tar.texi(,1926) as archive format, archive name, or level of user interaction.  Some
tar.texi(,1927) options make sense with all operating modes, while others are
tar.texi(,1928) meaningful only with particular modes. You will likely use some
tar.texi(,1929) options frequently, while you will only use others infrequently, or
tar.texi(,1930) not at all.  (A full list of options is available in @pxref{All Options}.)
tar.texi(,1931) 
tar.texi(,1932) @vrindex TAR_OPTIONS, environment variable
tar.texi(,1933) @anchor{TAR_OPTIONS}
tar.texi(,1934) The @env{TAR_OPTIONS} environment variable specifies default options to
tar.texi(,1935) be placed in front of any explicit options.  For example, if
tar.texi(,1936) @code{TAR_OPTIONS} is @samp{-v --unlink-first}, @command{tar} behaves as
tar.texi(,1937) if the two options @option{-v} and @option{--unlink-first} had been
tar.texi(,1938) specified before any explicit options.  Option specifications are
tar.texi(,1939) separated by whitespace.  A backslash escapes the next character, so it
tar.texi(,1940) can be used to specify an option containing whitespace or a backslash.
tar.texi(,1941) 
tar.texi(,1942) Note that @command{tar} options are case sensitive.  For example, the
tar.texi(,1943) options @option{-T} and @option{-t} are different; the first requires an
tar.texi(,1944) argument for stating the name of a file providing a list of @var{name}s,
tar.texi(,1945) while the second does not require an argument and is another way to
tar.texi(,1946) write @option{--list} (@option{-t}).
tar.texi(,1947) 
tar.texi(,1948) In addition to the eight operations, there are many options to
tar.texi(,1949) @command{tar}, and three different styles for writing both: long (mnemonic)
tar.texi(,1950) form, short form, and old style.  These styles are discussed below.
tar.texi(,1951) Both the options and the operations can be written in any of these three
tar.texi(,1952) styles.
tar.texi(,1953) 
tar.texi(FIXME,1956) @allow-recursion
tar.texi(FIXME,1956) @quote-arg
tar.texi(FIXME,1956) 
tar.texi(,1957) 
tar.texi(,1958) @node Styles
tar.texi(,1959) @section The Three Option Styles
tar.texi(,1960) 
tar.texi(,1961) There are three styles for writing operations and options to the command
tar.texi(,1962) line invoking @command{tar}.  The different styles were developed at
tar.texi(,1963) different times during the history of @command{tar}.  These styles will be
tar.texi(,1964) presented below, from the most recent to the oldest.
tar.texi(,1965) 
tar.texi(,1966) Some options must take an argument.  (For example, @option{--file}
tar.texi(,1967) (@option{-f})) takes the name of an archive file as an argument.  If
tar.texi(,1968) you do not supply an archive file name, @command{tar} will use a
tar.texi(,1969) default, but this can be confusing; thus, we recommend that you always
tar.texi(,1970) supply a specific archive file name.)  Where you @emph{place} the
tar.texi(,1971) arguments generally depends on which style of options you choose.  We
tar.texi(,1972) will detail specific information relevant to each option style in the
tar.texi(,1973) sections on the different option styles, below.  The differences are
tar.texi(,1974) subtle, yet can often be very important; incorrect option placement
tar.texi(,1975) can cause you to overwrite a number of important files.  We urge you
tar.texi(,1976) to note these differences, and only use the option style(s) which
tar.texi(,1977) makes the most sense to you until you feel comfortable with the others.
tar.texi(,1978) 
tar.texi(,1979) Some options @emph{may} take an argument.  Such options may have at
tar.texi(,1980) most long and short forms, they do not have old style equivalent.  The
tar.texi(,1981) rules for specifying an argument for such options are stricter than
tar.texi(,1982) those for specifying mandatory arguments.  Please, pay special
tar.texi(,1983) attention to them. 
tar.texi(,1984) 
tar.texi(,1985) @menu
tar.texi(,1986) * Long Options::                Long Option Style
tar.texi(,1987) * Short Options::               Short Option Style
tar.texi(,1988) * Old Options::                 Old Option Style
tar.texi(,1989) * Mixing::                      Mixing Option Styles
tar.texi(,1990) @end menu
tar.texi(,1991) 
tar.texi(,1992) @node Long Options
tar.texi(,1993) @subsection Long Option Style
tar.texi(,1994) 
tar.texi(,1995) Each option has at least one @dfn{long} (or @dfn{mnemonic}) name starting with two
tar.texi(,1996) dashes in a row, e.g., @option{--list}.  The long names are more clear than
tar.texi(,1997) their corresponding short or old names.  It sometimes happens that a
tar.texi(,1998) single long option has many different different names which are
tar.texi(,1999) synonymous, such as @option{--compare} and @option{--diff}.  In addition,
tar.texi(,2000) long option names can be given unique abbreviations.  For example,
tar.texi(,2001) @option{--cre} can be used in place of @option{--create} because there is no
tar.texi(,2002) other long option which begins with @samp{cre}.  (One way to find
tar.texi(,2003) this out is by trying it and seeing what happens; if a particular
tar.texi(,2004) abbreviation could represent more than one option, @command{tar} will tell
tar.texi(,2005) you that that abbreviation is ambiguous and you'll know that that
tar.texi(,2006) abbreviation won't work.  You may also choose to run @samp{tar --help}
tar.texi(,2007) to see a list of options.  Be aware that if you run @command{tar} with a
tar.texi(,2008) unique abbreviation for the long name of an option you didn't want to
tar.texi(,2009) use, you are stuck; @command{tar} will perform the command as ordered.)
tar.texi(,2010) 
tar.texi(,2011) Long options are meant to be obvious and easy to remember, and their
tar.texi(,2012) meanings are generally easier to discern than those of their
tar.texi(,2013) corresponding short options (see below).  For example:
tar.texi(,2014) 
tar.texi(,2015) @smallexample
tar.texi(,2016) $ @kbd{tar --create --verbose --blocking-factor=20 --file=/dev/rmt0}
tar.texi(,2017) @end smallexample
tar.texi(,2018) 
tar.texi(,2019) @noindent
tar.texi(,2020) gives a fairly good set of hints about what the command does, even
tar.texi(,2021) for those not fully acquainted with @command{tar}.
tar.texi(,2022) 
tar.texi(,2023) Long options which require arguments take those arguments
tar.texi(,2024) immediately following the option name.  There are two ways of
tar.texi(,2025) specifying a mandatory argument.  It can be separated from the
tar.texi(,2026) option name either by an equal sign, or by any amount of
tar.texi(,2027) white space characters.  For example, the @option{--file} option (which
tar.texi(,2028) tells the name of the @command{tar} archive) is given a file such as
tar.texi(,2029) @file{archive.tar} as argument by using any of the following notations:
tar.texi(,2030) @option{--file=archive.tar} or @option{--file archive.tar}.
tar.texi(,2031) 
tar.texi(,2032) In contrast, optional arguments must always be introduced using
tar.texi(,2033) an equal sign.  For example, the @option{--backup} option takes
tar.texi(,2034) an optional argument specifying backup type.  It must be used
tar.texi(,2035) as @option{--backup=@var{backup-type}}.
tar.texi(,2036) 
tar.texi(,2037) @node Short Options
tar.texi(,2038) @subsection Short Option Style
tar.texi(,2039) 
tar.texi(,2040) Most options also have a @dfn{short option} name.  Short options start with
tar.texi(,2041) a single dash, and are followed by a single character, e.g., @option{-t}
tar.texi(,2042) (which is equivalent to @option{--list}).  The forms are absolutely
tar.texi(,2043) identical in function; they are interchangeable.
tar.texi(,2044) 
tar.texi(,2045) The short option names are faster to type than long option names.
tar.texi(,2046) 
tar.texi(,2047) Short options which require arguments take their arguments immediately
tar.texi(,2048) following the option, usually separated by white space.  It is also
tar.texi(,2049) possible to stick the argument right after the short option name, using
tar.texi(,2050) no intervening space.  For example, you might write @w{@option{-f
tar.texi(,2051) archive.tar}} or @option{-farchive.tar} instead of using
tar.texi(,2052) @option{--file=archive.tar}.  Both @option{--file=@var{archive-name}} and
tar.texi(,2053) @w{@option{-f @var{archive-name}}} denote the option which indicates a
tar.texi(,2054) specific archive, here named @file{archive.tar}.
tar.texi(,2055) 
tar.texi(,2056) Short options which take optional arguments take their arguments
tar.texi(,2057) immediately following the option letter, @emph{without any intervening
tar.texi(,2058) white space characters}.
tar.texi(,2059) 
tar.texi(,2060) Short options' letters may be clumped together, but you are not
tar.texi(,2061) required to do this (as compared to old options; see below).  When
tar.texi(,2062) short options are clumped as a set, use one (single) dash for them
tar.texi(,2063) all, e.g., @w{@samp{@command{tar} -cvf}}.  Only the last option in
tar.texi(,2064) such a set is allowed to have an argument@footnote{Clustering many
tar.texi(,2065) options, the last of which has an argument, is a rather opaque way to
tar.texi(,2066) write options.  Some wonder if @acronym{GNU} @code{getopt} should not
tar.texi(,2067) even be made helpful enough for considering such usages as invalid.}.
tar.texi(,2068) 
tar.texi(,2069) When the options are separated, the argument for each option which requires
tar.texi(,2070) an argument directly follows that option, as is usual for Unix programs.
tar.texi(,2071) For example:
tar.texi(,2072) 
tar.texi(,2073) @smallexample
tar.texi(,2074) $ @kbd{tar -c -v -b 20 -f /dev/rmt0}
tar.texi(,2075) @end smallexample
tar.texi(,2076) 
tar.texi(,2077) If you reorder short options' locations, be sure to move any arguments
tar.texi(,2078) that belong to them.  If you do not move the arguments properly, you may
tar.texi(,2079) end up overwriting files.
tar.texi(,2080) 
tar.texi(,2081) @node Old Options
tar.texi(,2082) @subsection Old Option Style
tar.texi(UNREVISED,2083) @quotation
tar.texi(UNREVISED,2083) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,2083) @end quotation
tar.texi(,2084) 
tar.texi(,2085) Like short options, @dfn{old options} are single letters.  However, old options
tar.texi(,2086) must be written together as a single clumped set, without spaces separating
tar.texi(,2087) them or dashes preceding them@footnote{Beware that if you precede options
tar.texi(,2088) with a dash, you are announcing the short option style instead of the
tar.texi(,2089) old option style; short options are decoded differently.}.  This set
tar.texi(,2090) of letters must be the first to appear on the command line, after the
tar.texi(,2091) @command{tar} program name and some white space; old options cannot appear
tar.texi(,2092) anywhere else.  The letter of an old option is exactly the same letter as
tar.texi(,2093) the corresponding short option.  For example, the old option @samp{t} is
tar.texi(,2094) the same as the short option @option{-t}, and consequently, the same as the
tar.texi(,2095) long option @option{--list}.  So for example, the command @w{@samp{tar
tar.texi(,2096) cv}} specifies the option @option{-v} in addition to the operation @option{-c}.
tar.texi(,2097) 
tar.texi(,2098) When options that need arguments are given together with the command,
tar.texi(,2099) all the associated arguments follow, in the same order as the options.
tar.texi(,2100) Thus, the example given previously could also be written in the old
tar.texi(,2101) style as follows:
tar.texi(,2102) 
tar.texi(,2103) @smallexample
tar.texi(,2104) $ @kbd{tar cvbf 20 /dev/rmt0}
tar.texi(,2105) @end smallexample
tar.texi(,2106) 
tar.texi(,2107) @noindent
tar.texi(,2108) Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is
tar.texi(,2109) the argument of @option{-f}.
tar.texi(,2110) 
tar.texi(,2111) On the other hand, this old style syntax makes it difficult to match
tar.texi(,2112) option letters with their corresponding arguments, and is often
tar.texi(,2113) confusing.  In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example,
tar.texi(,2114) @samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the
tar.texi(,2115) argument for @option{-f}, and @option{-v} does not have a corresponding
tar.texi(,2116) argument.  Even using short options like in @w{@samp{tar -c -v -b 20 -f
tar.texi(,2117) /dev/rmt0}} is clearer, putting all arguments next to the option they
tar.texi(,2118) pertain to.
tar.texi(,2119) 
tar.texi(,2120) If you want to reorder the letters in the old option argument, be
tar.texi(,2121) sure to reorder any corresponding argument appropriately.
tar.texi(,2122) 
tar.texi(,2123) This old way of writing @command{tar} options can surprise even experienced
tar.texi(,2124) users.  For example, the two commands:
tar.texi(,2125) 
tar.texi(,2126) @smallexample
tar.texi(,2127) @kbd{tar cfz archive.tar.gz file}
tar.texi(,2128) @kbd{tar -cfz archive.tar.gz file}
tar.texi(,2129) @end smallexample
tar.texi(,2130) 
tar.texi(,2131) @noindent
tar.texi(,2132) are quite different.  The first example uses @file{archive.tar.gz} as
tar.texi(,2133) the value for option @samp{f} and recognizes the option @samp{z}.  The
tar.texi(,2134) second example, however, uses @file{z} as the value for option
tar.texi(,2135) @samp{f} --- probably not what was intended.
tar.texi(,2136) 
tar.texi(,2137) Old options are kept for compatibility with old versions of @command{tar}.
tar.texi(,2138) 
tar.texi(,2139) This second example could be corrected in many ways, among which the
tar.texi(,2140) following are equivalent:
tar.texi(,2141) 
tar.texi(,2142) @smallexample
tar.texi(,2143) @kbd{tar -czf archive.tar.gz file}
tar.texi(,2144) @kbd{tar -cf archive.tar.gz -z file}
tar.texi(,2145) @kbd{tar cf archive.tar.gz -z file}
tar.texi(,2146) @end smallexample
tar.texi(,2147) 
tar.texi(,2148) @cindex option syntax, traditional
tar.texi(,2149) As far as we know, all @command{tar} programs, @acronym{GNU} and
tar.texi(GNUTAR,2150) non-@acronym{GNU}, support old options.  tar.texi(GNUTAR,2150) @acronym{GNU} @command{tar}
tar.texi(,2151) supports them not only for historical reasons, but also because many
tar.texi(,2152) people are used to them.  For compatibility with Unix @command{tar},
tar.texi(,2153) the first argument is always treated as containing command and option
tar.texi(,2154) letters even if it doesn't start with @samp{-}.  Thus, @samp{tar c} is
tar.texi(,2155) equivalent to @w{@samp{tar -c}:} both of them specify the
tar.texi(,2156) @option{--create} (@option{-c}) command to create an archive.
tar.texi(,2157) 
tar.texi(,2158) @node Mixing
tar.texi(,2159) @subsection Mixing Option Styles
tar.texi(,2160) 
tar.texi(,2161) All three styles may be intermixed in a single @command{tar} command,
tar.texi(,2162) so long as the rules for each style are fully
tar.texi(GNUTAR,2163) respected@footnote{Before @acronym{GNU} @command{tar} version 1.11.6,
tar.texi(,2164) a bug prevented intermixing old style options with long options in
tar.texi(,2165) some cases.}.  Old style options and either of the modern styles of
tar.texi(,2166) options may be mixed within a single @command{tar} command.  However,
tar.texi(,2167) old style options must be introduced as the first arguments only,
tar.texi(,2168) following the rule for old options (old options must appear directly
tar.texi(,2169) after the @command{tar} command and some white space).  Modern options
tar.texi(,2170) may be given only after all arguments to the old options have been
tar.texi(,2171) collected.  If this rule is not respected, a modern option might be
tar.texi(,2172) falsely interpreted as the value of the argument to one of the old
tar.texi(,2173) style options.
tar.texi(,2174) 
tar.texi(,2175) For example, all the following commands are wholly equivalent, and
tar.texi(,2176) illustrate the many combinations and orderings of option styles.
tar.texi(,2177) 
tar.texi(,2178) @smallexample
tar.texi(,2179) @kbd{tar --create --file=archive.tar}
tar.texi(,2180) @kbd{tar --create -f archive.tar}
tar.texi(,2181) @kbd{tar --create -farchive.tar}
tar.texi(,2182) @kbd{tar --file=archive.tar --create}
tar.texi(,2183) @kbd{tar --file=archive.tar -c}
tar.texi(,2184) @kbd{tar -c --file=archive.tar}
tar.texi(,2185) @kbd{tar -c -f archive.tar}
tar.texi(,2186) @kbd{tar -c -farchive.tar}
tar.texi(,2187) @kbd{tar -cf archive.tar}
tar.texi(,2188) @kbd{tar -cfarchive.tar}
tar.texi(,2189) @kbd{tar -f archive.tar --create}
tar.texi(,2190) @kbd{tar -f archive.tar -c}
tar.texi(,2191) @kbd{tar -farchive.tar --create}
tar.texi(,2192) @kbd{tar -farchive.tar -c}
tar.texi(,2193) @kbd{tar c --file=archive.tar}
tar.texi(,2194) @kbd{tar c -f archive.tar}
tar.texi(,2195) @kbd{tar c -farchive.tar}
tar.texi(,2196) @kbd{tar cf archive.tar}
tar.texi(,2197) @kbd{tar f archive.tar --create}
tar.texi(,2198) @kbd{tar f archive.tar -c}
tar.texi(,2199) @kbd{tar fc archive.tar}
tar.texi(,2200) @end smallexample
tar.texi(,2201) 
tar.texi(,2202) On the other hand, the following commands are @emph{not} equivalent to
tar.texi(,2203) the previous set:
tar.texi(,2204) 
tar.texi(,2205) @smallexample
tar.texi(,2206) @kbd{tar -f -c archive.tar}
tar.texi(,2207) @kbd{tar -fc archive.tar}
tar.texi(,2208) @kbd{tar -fcarchive.tar}
tar.texi(,2209) @kbd{tar -farchive.tarc}
tar.texi(,2210) @kbd{tar cfarchive.tar}
tar.texi(,2211) @end smallexample
tar.texi(,2212) 
tar.texi(,2213) @noindent
tar.texi(,2214) These last examples mean something completely different from what the
tar.texi(,2215) user intended (judging based on the example in the previous set which
tar.texi(,2216) uses long options, whose intent is therefore very clear).  The first
tar.texi(,2217) four specify that the @command{tar} archive would be a file named
tar.texi(,2218) @option{-c}, @samp{c}, @samp{carchive.tar} or @samp{archive.tarc},
tar.texi(,2219) respectively.  The first two examples also specify a single non-option,
tar.texi(,2220) @var{name} argument having the value @samp{archive.tar}.  The last
tar.texi(,2221) example contains only old style option letters (repeating option
tar.texi(,2222) @samp{c} twice), not all of which are meaningful (eg., @samp{.},
tar.texi(FIXME,2224) @samp{h}, or @samp{i}), with no argument value.  tar.texi(FIXME,2224) @allow-recursion
tar.texi(FIXME,2224) @quote-arg
tar.texi(FIXME,2224) 
tar.texi(,2225) 
tar.texi(,2226) @node All Options
tar.texi(,2227) @section All @command{tar} Options
tar.texi(,2228) 
tar.texi(,2229) The coming manual sections contain an alphabetical listing of all
tar.texi(,2230) @command{tar} operations and options, with brief descriptions and cross
tar.texi(,2231) references to more in-depth explanations in the body of the manual.
tar.texi(,2232) They also contain an alphabetically arranged table of the short option
tar.texi(,2233) forms with their corresponding long option.  You can use this table as
tar.texi(,2234) a reference for deciphering @command{tar} commands in scripts.
tar.texi(,2235) 
tar.texi(,2236) @menu
tar.texi(,2237) * Operation Summary::
tar.texi(,2238) * Option Summary::
tar.texi(,2239) * Short Option Summary::
tar.texi(,2240) @end menu
tar.texi(,2241) 
tar.texi(,2242) @node Operation Summary
tar.texi(,2243) @subsection Operations
tar.texi(,2244) 
tar.texi(,2245) @table @option
tar.texi(,2246) 
tar.texi(opsummary,2247) @set ANCHOR--append 1
tar.texi(opsummary,2247) @anchor{--append}
tar.texi(opsummary,2247) @opindex append@r{, summary}
tar.texi(,2248) @item --append
tar.texi(,2249) @itemx -r
tar.texi(,2250) 
tar.texi(,2251) Appends files to the end of the archive.  @xref{append}.
tar.texi(,2252) 
tar.texi(opsummary,2253) @set ANCHOR--catenate 1
tar.texi(opsummary,2253) @anchor{--catenate}
tar.texi(opsummary,2253) @opindex catenate@r{, summary}
tar.texi(,2254) @item --catenate
tar.texi(,2255) @itemx -A
tar.texi(,2256) 
tar.texi(,2257) Same as @option{--concatenate}.  @xref{concatenate}.
tar.texi(,2258) 
tar.texi(opsummary,2259) @set ANCHOR--compare 1
tar.texi(opsummary,2259) @anchor{--compare}
tar.texi(opsummary,2259) @opindex compare@r{, summary}
tar.texi(,2260) @item --compare
tar.texi(,2261) @itemx -d
tar.texi(,2262) 
tar.texi(,2263) Compares archive members with their counterparts in the file
tar.texi(,2264) system, and reports differences in file size, mode, owner,
tar.texi(,2265) modification date and contents.  @xref{compare}.
tar.texi(,2266) 
tar.texi(opsummary,2267) @set ANCHOR--concatenate 1
tar.texi(opsummary,2267) @anchor{--concatenate}
tar.texi(opsummary,2267) @opindex concatenate@r{, summary}
tar.texi(,2268) @item --concatenate
tar.texi(,2269) @itemx -A
tar.texi(,2270) 
tar.texi(,2271) Appends other @command{tar} archives to the end of the archive.
tar.texi(,2272) @xref{concatenate}.
tar.texi(,2273) 
tar.texi(opsummary,2274) @set ANCHOR--create 1
tar.texi(opsummary,2274) @anchor{--create}
tar.texi(opsummary,2274) @opindex create@r{, summary}
tar.texi(,2275) @item --create
tar.texi(,2276) @itemx -c
tar.texi(,2277) 
tar.texi(,2278) Creates a new @command{tar} archive.  @xref{create}.
tar.texi(,2279) 
tar.texi(opsummary,2280) @set ANCHOR--delete 1
tar.texi(opsummary,2280) @anchor{--delete}
tar.texi(opsummary,2280) @opindex delete@r{, summary}
tar.texi(,2281) @item --delete
tar.texi(,2282) 
tar.texi(,2283) Deletes members from the archive.  Don't try this on a archive on a
tar.texi(,2284) tape!  @xref{delete}.
tar.texi(,2285) 
tar.texi(opsummary,2286) @set ANCHOR--diff 1
tar.texi(opsummary,2286) @anchor{--diff}
tar.texi(opsummary,2286) @opindex diff@r{, summary}
tar.texi(,2287) @item --diff
tar.texi(,2288) @itemx -d
tar.texi(,2289) 
tar.texi(,2290) Same @option{--compare}.  @xref{compare}.
tar.texi(,2291) 
tar.texi(opsummary,2292) @set ANCHOR--extract 1
tar.texi(opsummary,2292) @anchor{--extract}
tar.texi(opsummary,2292) @opindex extract@r{, summary}
tar.texi(,2293) @item --extract
tar.texi(,2294) @itemx -x
tar.texi(,2295) 
tar.texi(,2296) Extracts members from the archive into the file system.  @xref{extract}.
tar.texi(,2297) 
tar.texi(opsummary,2298) @set ANCHOR--get 1
tar.texi(opsummary,2298) @anchor{--get}
tar.texi(opsummary,2298) @opindex get@r{, summary}
tar.texi(,2299) @item --get
tar.texi(,2300) @itemx -x
tar.texi(,2301) 
tar.texi(,2302) Same as @option{--extract}.  @xref{extract}.
tar.texi(,2303) 
tar.texi(opsummary,2304) @set ANCHOR--list 1
tar.texi(opsummary,2304) @anchor{--list}
tar.texi(opsummary,2304) @opindex list@r{, summary}
tar.texi(,2305) @item --list
tar.texi(,2306) @itemx -t
tar.texi(,2307) 
tar.texi(,2308) Lists the members in an archive.  @xref{list}.
tar.texi(,2309) 
tar.texi(opsummary,2310) @set ANCHOR--update 1
tar.texi(opsummary,2310) @anchor{--update}
tar.texi(opsummary,2310) @opindex update@r{, summary}
tar.texi(,2311) @item --update
tar.texi(,2312) @itemx -u
tar.texi(,2313) 
tar.texi(,2314) Adds files to the end of the archive, but only if they are newer than
tar.texi(,2315) their counterparts already in the archive, or if they do not already
tar.texi(,2316) exist in the archive. @xref{update}.
tar.texi(,2317) 
tar.texi(,2318) @end table
tar.texi(,2319) 
tar.texi(,2320) @node Option Summary
tar.texi(,2321) @subsection @command{tar} Options
tar.texi(,2322) 
tar.texi(,2323) @table @option
tar.texi(,2324) 
tar.texi(opsummary,2325) @set ANCHOR--absolute-names 1
tar.texi(opsummary,2325) @anchor{--absolute-names}
tar.texi(opsummary,2325) @opindex absolute-names@r{, summary}
tar.texi(,2326) @item --absolute-names
tar.texi(,2327) @itemx -P
tar.texi(,2328) 
tar.texi(,2329) Normally when creating an archive, @command{tar} strips an initial
tar.texi(,2330) @samp{/} from member names.  This option disables that behavior.
tar.texi(,2331) @xref{absolute}.
tar.texi(,2332) 
tar.texi(opsummary,2333) @set ANCHOR--after-date 1
tar.texi(opsummary,2333) @anchor{--after-date}
tar.texi(opsummary,2333) @opindex after-date@r{, summary}
tar.texi(,2334) @item --after-date
tar.texi(,2335) 
tar.texi(,2336) (See @option{--newer}, @pxref{after})
tar.texi(,2337) 
tar.texi(opsummary,2338) @set ANCHOR--anchored 1
tar.texi(opsummary,2338) @anchor{--anchored}
tar.texi(opsummary,2338) @opindex anchored@r{, summary}
tar.texi(,2339) @item --anchored
tar.texi(,2340) A pattern must match an initial subsequence of the name's components.
tar.texi(,2341) @xref{controlling pattern-matching}.
tar.texi(,2342) 
tar.texi(opsummary,2343) @set ANCHOR--atime-preserve 1
tar.texi(opsummary,2343) @anchor{--atime-preserve}
tar.texi(opsummary,2343) @opindex atime-preserve@r{, summary}
tar.texi(,2344) @item --atime-preserve
tar.texi(,2345) @itemx --atime-preserve=replace
tar.texi(,2346) @itemx --atime-preserve=system
tar.texi(,2347) 
tar.texi(,2348) Attempt to preserve the access time of files when reading them.  This
tar.texi(,2349) option currently is effective only on files that you own, unless you
tar.texi(,2350) have superuser privileges.
tar.texi(,2351) 
tar.texi(,2352) @option{--atime-preserve=replace} remembers the access time of a file
tar.texi(,2353) before reading it, and then restores the access time afterwards.  This
tar.texi(,2354) may cause problems if other programs are reading the file at the same
tar.texi(,2355) time, as the times of their accesses will be lost.  On most platforms
tar.texi(,2356) restoring the access time also requires @command{tar} to restore the
tar.texi(,2357) data modification time too, so this option may also cause problems if
tar.texi(,2358) other programs are writing the file at the same time.  (Tar attempts
tar.texi(,2359) to detect this situation, but cannot do so reliably due to race
tar.texi(,2360) conditions.)  Worse, on most platforms restoring the access time also
tar.texi(,2361) updates the status change time, which means that this option is
tar.texi(,2362) incompatible with incremental backups.
tar.texi(,2363) 
tar.texi(,2364) @option{--atime-preserve=system} avoids changing time stamps on files,
tar.texi(,2365) without interfering with time stamp updates
tar.texi(,2366) caused by other programs, so it works better with incremental backups.
tar.texi(,2367) However, it requires a special @code{O_NOATIME} option from the
tar.texi(,2368) underlying operating and file system implementation, and it also requires
tar.texi(,2369) that searching directories does not update their access times.  As of
tar.texi(,2370) this writing (November 2005) this works only with Linux, and only with
tar.texi(,2371) Linux kernels 2.6.8 and later.  Worse, there is currently no reliable
tar.texi(,2372) way to know whether this feature actually works.  Sometimes
tar.texi(,2373) @command{tar} knows that it does not work, and if you use
tar.texi(,2374) @option{--atime-preserve=system} then @command{tar} complains and
tar.texi(,2375) exits right away.  But other times @command{tar} might think that the
tar.texi(,2376) option works when it actually does not.
tar.texi(,2377) 
tar.texi(,2378) Currently @option{--atime-preserve} with no operand defaults to
tar.texi(,2379) @option{--atime-preserve=replace}, but this may change in the future
tar.texi(,2380) as support for @option{--atime-preserve=system} improves.
tar.texi(,2381) 
tar.texi(,2382) If your operating system does not support
tar.texi(,2383) @option{--atime-preserve=@-system}, you might be able to preserve access
tar.texi(,2384) times reliably by by using the @command{mount} command.  For example,
tar.texi(,2385) you can mount the file system read-only, or access the file system via
tar.texi(,2386) a read-only loopback mount, or use the @samp{noatime} mount option
tar.texi(,2387) available on some systems.  However, mounting typically requires
tar.texi(,2388) superuser privileges and can be a pain to manage.
tar.texi(,2389) 
tar.texi(opsummary,2390) @set ANCHOR--backup 1
tar.texi(opsummary,2390) @anchor{--backup}
tar.texi(opsummary,2390) @opindex backup@r{, summary}
tar.texi(,2391) @item --backup=@var{backup-type}
tar.texi(,2392) 
tar.texi(,2393) Rather than deleting files from the file system, @command{tar} will
tar.texi(,2394) back them up using simple or numbered backups, depending upon
tar.texi(,2395) @var{backup-type}.  @xref{backup}.
tar.texi(,2396) 
tar.texi(opsummary,2397) @set ANCHOR--block-number 1
tar.texi(opsummary,2397) @anchor{--block-number}
tar.texi(opsummary,2397) @opindex block-number@r{, summary}
tar.texi(,2398) @item --block-number
tar.texi(,2399) @itemx -R
tar.texi(,2400) 
tar.texi(,2401) With this option present, @command{tar} prints error messages for read errors
tar.texi(,2402) with the block number in the archive file.  @xref{block-number}.
tar.texi(,2403) 
tar.texi(opsummary,2404) @set ANCHOR--blocking-factor 1
tar.texi(opsummary,2404) @anchor{--blocking-factor}
tar.texi(opsummary,2404) @opindex blocking-factor@r{, summary}
tar.texi(,2405) @item --blocking-factor=@var{blocking}
tar.texi(,2406) @itemx -b @var{blocking}
tar.texi(,2407) 
tar.texi(,2408) Sets the blocking factor @command{tar} uses to @var{blocking} x 512 bytes per
tar.texi(,2409) record.  @xref{Blocking Factor}.
tar.texi(,2410) 
tar.texi(opsummary,2411) @set ANCHOR--bzip2 1
tar.texi(opsummary,2411) @anchor{--bzip2}
tar.texi(opsummary,2411) @opindex bzip2@r{, summary}
tar.texi(,2412) @item --bzip2
tar.texi(,2413) @itemx -j
tar.texi(,2414) 
tar.texi(,2415) This option tells @command{tar} to read or write archives through
tar.texi(,2416) @code{bzip2}.  @xref{gzip}.
tar.texi(,2417) 
tar.texi(opsummary,2418) @set ANCHOR--checkpoint 1
tar.texi(opsummary,2418) @anchor{--checkpoint}
tar.texi(opsummary,2418) @opindex checkpoint@r{, summary}
tar.texi(,2419) @item --checkpoint[=@var{number}]
tar.texi(,2420) 
tar.texi(,2421) This option directs @command{tar} to print periodic checkpoint
tar.texi(,2422) messages as it reads through the archive.  It is intended for when you
tar.texi(,2423) want a visual indication that @command{tar} is still running, but
tar.texi(,2424) don't want to see @option{--verbose} output.  For a detailed
tar.texi(,2425) description, see @ref{Progress information}.
tar.texi(,2426) 
tar.texi(opsummary,2427) @set ANCHOR--check-links 1
tar.texi(opsummary,2427) @anchor{--check-links}
tar.texi(opsummary,2427) @opindex check-links@r{, summary}
tar.texi(,2428) @item --check-links
tar.texi(,2429) @itemx -l
tar.texi(,2430) If this option was given, @command{tar} will check the number of links
tar.texi(,2431) dumped for each processed file.  If this number does not match the
tar.texi(,2432) total number of hard links for the file, a warning message will be
tar.texi(GNUTAR,2433) output @footnote{Earlier versions of @acronym{GNU} @command{tar} understood @option{-l} as a
tar.texi(,2434) synonym for @option{--one-file-system}.  The current semantics, which
tar.texi(,2435) complies to UNIX98, was introduced with version
tar.texi(,2436) 1.15.91. @xref{Changes}, for more information.}. 
tar.texi(,2437) 
tar.texi(opsummary,2438) @set ANCHOR--compress 1
tar.texi(opsummary,2438) @anchor{--compress}
tar.texi(opsummary,2438) @opindex compress@r{, summary}
tar.texi(opsummary,2439) @set ANCHOR--uncompress 1
tar.texi(opsummary,2439) @anchor{--uncompress}
tar.texi(opsummary,2439) @opindex uncompress@r{, summary}
tar.texi(,2440) @item --compress
tar.texi(,2441) @itemx --uncompress
tar.texi(,2442) @itemx -Z
tar.texi(,2443) 
tar.texi(,2444) @command{tar} will use the @command{compress} program when reading or
tar.texi(,2445) writing the archive.  This allows you to directly act on archives
tar.texi(,2446) while saving space.  @xref{gzip}.
tar.texi(,2447) 
tar.texi(opsummary,2448) @set ANCHOR--confirmation 1
tar.texi(opsummary,2448) @anchor{--confirmation}
tar.texi(opsummary,2448) @opindex confirmation@r{, summary}
tar.texi(,2449) @item --confirmation
tar.texi(,2450) 
tar.texi(,2451) (See @option{--interactive}.)  @xref{interactive}.
tar.texi(,2452) 
tar.texi(opsummary,2453) @set ANCHOR--delay-directory-restore 1
tar.texi(opsummary,2453) @anchor{--delay-directory-restore}
tar.texi(opsummary,2453) @opindex delay-directory-restore@r{, summary}
tar.texi(,2454) @item --delay-directory-restore
tar.texi(,2455) 
tar.texi(,2456) Delay setting modification times and permissions of extracted
tar.texi(,2457) directories until the end of extraction. @xref{Directory Modification Times and Permissions}.
tar.texi(,2458) 
tar.texi(opsummary,2459) @set ANCHOR--dereference 1
tar.texi(opsummary,2459) @anchor{--dereference}
tar.texi(opsummary,2459) @opindex dereference@r{, summary}
tar.texi(,2460) @item --dereference
tar.texi(,2461) @itemx -h
tar.texi(,2462) 
tar.texi(,2463) When creating a @command{tar} archive, @command{tar} will archive the
tar.texi(,2464) file that a symbolic link points to, rather than archiving the
tar.texi(,2465) symlink.  @xref{dereference}.
tar.texi(,2466) 
tar.texi(opsummary,2467) @set ANCHOR--directory 1
tar.texi(opsummary,2467) @anchor{--directory}
tar.texi(opsummary,2467) @opindex directory@r{, summary}
tar.texi(,2468) @item --directory=@var{dir}
tar.texi(,2469) @itemx -C @var{dir}
tar.texi(,2470) 
tar.texi(,2471) When this option is specified, @command{tar} will change its current directory
tar.texi(,2472) to @var{dir} before performing any operations.  When this option is used
tar.texi(,2473) during archive creation, it is order sensitive.  @xref{directory}.
tar.texi(,2474) 
tar.texi(opsummary,2475) @set ANCHOR--exclude 1
tar.texi(opsummary,2475) @anchor{--exclude}
tar.texi(opsummary,2475) @opindex exclude@r{, summary}
tar.texi(,2476) @item --exclude=@var{pattern}
tar.texi(,2477) 
tar.texi(,2478) When performing operations, @command{tar} will skip files that match
tar.texi(,2479) @var{pattern}.  @xref{exclude}.
tar.texi(,2480) 
tar.texi(opsummary,2481) @set ANCHOR--exclude-from 1
tar.texi(opsummary,2481) @anchor{--exclude-from}
tar.texi(opsummary,2481) @opindex exclude-from@r{, summary}
tar.texi(,2482) @item --exclude-from=@var{file}
tar.texi(,2483) @itemx -X @var{file}
tar.texi(,2484) 
tar.texi(,2485) Similar to @option{--exclude}, except @command{tar} will use the list of
tar.texi(,2486) patterns in the file @var{file}.  @xref{exclude}.
tar.texi(,2487) 
tar.texi(opsummary,2488) @set ANCHOR--exclude-caches 1
tar.texi(opsummary,2488) @anchor{--exclude-caches}
tar.texi(opsummary,2488) @opindex exclude-caches@r{, summary}
tar.texi(,2489) @item --exclude-caches
tar.texi(,2490) 
tar.texi(,2491) Automatically excludes all directories
tar.texi(,2492) containing a cache directory tag.  @xref{exclude}.
tar.texi(,2493) 
tar.texi(opsummary,2494) @set ANCHOR--file 1
tar.texi(opsummary,2494) @anchor{--file}
tar.texi(opsummary,2494) @opindex file@r{, summary}
tar.texi(,2495) @item --file=@var{archive}
tar.texi(,2496) @itemx -f @var{archive}
tar.texi(,2497) 
tar.texi(,2498) @command{tar} will use the file @var{archive} as the @command{tar} archive it
tar.texi(,2499) performs operations on, rather than @command{tar}'s compilation dependent
tar.texi(,2500) default.  @xref{file tutorial}.
tar.texi(,2501) 
tar.texi(opsummary,2502) @set ANCHOR--files-from 1
tar.texi(opsummary,2502) @anchor{--files-from}
tar.texi(opsummary,2502) @opindex files-from@r{, summary}
tar.texi(,2503) @item --files-from=@var{file}
tar.texi(,2504) @itemx -T @var{file}
tar.texi(,2505) 
tar.texi(,2506) @command{tar} will use the contents of @var{file} as a list of archive members
tar.texi(,2507) or files to operate on, in addition to those specified on the
tar.texi(,2508) command-line.  @xref{files}.
tar.texi(,2509) 
tar.texi(opsummary,2510) @set ANCHOR--force-local 1
tar.texi(opsummary,2510) @anchor{--force-local}
tar.texi(opsummary,2510) @opindex force-local@r{, summary}
tar.texi(,2511) @item --force-local
tar.texi(,2512) 
tar.texi(,2513) Forces @command{tar} to interpret the filename given to @option{--file}
tar.texi(,2514) as a local file, even if it looks like a remote tape drive name.
tar.texi(,2515) @xref{local and remote archives}.
tar.texi(,2516) 
tar.texi(opsummary,2517) @set ANCHOR--format 1
tar.texi(opsummary,2517) @anchor{--format}
tar.texi(opsummary,2517) @opindex format@r{, summary}
tar.texi(,2518) @item --format=@var{format}
tar.texi(,2519) @itemx -H @var{format}
tar.texi(,2520) 
tar.texi(,2521) Selects output archive format.  @var{Format} may be one of the
tar.texi(,2522) following:
tar.texi(,2523) 
tar.texi(,2524) @table @samp
tar.texi(,2525) @item v7
tar.texi(,2526) Creates an archive that is compatible with Unix V7 @command{tar}.
tar.texi(,2527) 
tar.texi(,2528) @item oldgnu
tar.texi(,2529) Creates an archive that is compatible with GNU @command{tar} version
tar.texi(,2530) 1.12 or earlier.
tar.texi(,2531) 
tar.texi(,2532) @item gnu
tar.texi(,2533) Creates archive in GNU tar 1.13 format.  Basically it is the same as
tar.texi(,2534) @samp{oldgnu} with the only difference in the way it handles long
tar.texi(,2535) numeric fields.
tar.texi(,2536) 
tar.texi(,2537) @item ustar
tar.texi(,2538) Creates a @acronym{POSIX.1-1988} compatible archive.
tar.texi(,2539) 
tar.texi(,2540) @item posix
tar.texi(,2541) Creates a @acronym{POSIX.1-2001 archive}.
tar.texi(,2542) 
tar.texi(,2543) @end table
tar.texi(,2544) 
tar.texi(,2545) @xref{Formats}, for a detailed discussion of these formats.
tar.texi(,2546) 
tar.texi(opsummary,2547) @set ANCHOR--group 1
tar.texi(opsummary,2547) @anchor{--group}
tar.texi(opsummary,2547) @opindex group@r{, summary}
tar.texi(,2548) @item --group=@var{group}
tar.texi(,2549) 
tar.texi(,2550) Files added to the @command{tar} archive will have a group id of @var{group},
tar.texi(,2551) rather than the group from the source file.  @var{group} is first decoded
tar.texi(,2552) as a group symbolic name, but if this interpretation fails, it has to be
tar.texi(,2553) a decimal numeric group ID.  @xref{override}.
tar.texi(,2554) 
tar.texi(,2555) Also see the comments for the @option{--owner=@var{user}} option.
tar.texi(,2556) 
tar.texi(opsummary,2557) @set ANCHOR--gzip 1
tar.texi(opsummary,2557) @anchor{--gzip}
tar.texi(opsummary,2557) @opindex gzip@r{, summary}
tar.texi(opsummary,2558) @set ANCHOR--gunzip 1
tar.texi(opsummary,2558) @anchor{--gunzip}
tar.texi(opsummary,2558) @opindex gunzip@r{, summary}
tar.texi(opsummary,2559) @set ANCHOR--ungzip 1
tar.texi(opsummary,2559) @anchor{--ungzip}
tar.texi(opsummary,2559) @opindex ungzip@r{, summary}
tar.texi(,2560) @item --gzip
tar.texi(,2561) @itemx --gunzip
tar.texi(,2562) @itemx --ungzip
tar.texi(,2563) @itemx -z
tar.texi(,2564) 
tar.texi(,2565) This option tells @command{tar} to read or write archives through
tar.texi(,2566) @command{gzip}, allowing @command{tar} to directly operate on several
tar.texi(,2567) kinds of compressed archives transparently.  @xref{gzip}.
tar.texi(,2568) 
tar.texi(opsummary,2569) @set ANCHOR--help 1
tar.texi(opsummary,2569) @anchor{--help}
tar.texi(opsummary,2569) @opindex help@r{, summary}
tar.texi(,2570) @item --help
tar.texi(,2571) @itemx -?
tar.texi(,2572) 
tar.texi(,2573) @command{tar} will print out a short message summarizing the operations and
tar.texi(,2574) options to @command{tar} and exit. @xref{help}.
tar.texi(,2575) 
tar.texi(opsummary,2576) @set ANCHOR--ignore-case 1
tar.texi(opsummary,2576) @anchor{--ignore-case}
tar.texi(opsummary,2576) @opindex ignore-case@r{, summary}
tar.texi(,2577) @item --ignore-case
tar.texi(,2578) Ignore case when matching member or file names with
tar.texi(,2579) patterns. @xref{controlling pattern-matching}. 
tar.texi(,2580) 
tar.texi(opsummary,2581) @set ANCHOR--ignore-command-error 1
tar.texi(opsummary,2581) @anchor{--ignore-command-error}
tar.texi(opsummary,2581) @opindex ignore-command-error@r{, summary}
tar.texi(,2582) @item --ignore-command-error
tar.texi(,2583) Ignore exit codes of subprocesses. @xref{Writing to an External Program}.
tar.texi(,2584) 
tar.texi(opsummary,2585) @set ANCHOR--ignore-failed-read 1
tar.texi(opsummary,2585) @anchor{--ignore-failed-read}
tar.texi(opsummary,2585) @opindex ignore-failed-read@r{, summary}
tar.texi(,2586) @item --ignore-failed-read
tar.texi(,2587) 
tar.texi(,2588) Do not exit unsuccessfully merely because an unreadable file was encountered.
tar.texi(,2589) @xref{Reading}.
tar.texi(,2590) 
tar.texi(opsummary,2591) @set ANCHOR--ignore-zeros 1
tar.texi(opsummary,2591) @anchor{--ignore-zeros}
tar.texi(opsummary,2591) @opindex ignore-zeros@r{, summary}
tar.texi(,2592) @item --ignore-zeros
tar.texi(,2593) @itemx -i
tar.texi(,2594) 
tar.texi(,2595) With this option, @command{tar} will ignore zeroed blocks in the
tar.texi(,2596) archive, which normally signals EOF.  @xref{Reading}.
tar.texi(,2597) 
tar.texi(opsummary,2598) @set ANCHOR--incremental 1
tar.texi(opsummary,2598) @anchor{--incremental}
tar.texi(opsummary,2598) @opindex incremental@r{, summary}
tar.texi(,2599) @item --incremental
tar.texi(,2600) @itemx -G
tar.texi(,2601) 
tar.texi(,2602) Used to inform @command{tar} that it is working with an old
tar.texi(,2603) @acronym{GNU}-format incremental backup archive.  It is intended
tar.texi(,2604) primarily for backwards compatibility only.  @xref{Incremental Dumps},
tar.texi(,2605) for a detailed discussion of incremental archives.
tar.texi(,2606) 
tar.texi(opsummary,2607) @set ANCHOR--index-file 1
tar.texi(opsummary,2607) @anchor{--index-file}
tar.texi(opsummary,2607) @opindex index-file@r{, summary}
tar.texi(,2608) @item --index-file=@var{file}
tar.texi(,2609) 
tar.texi(,2610) Send verbose output to @var{file} instead of to standard output.
tar.texi(,2611) 
tar.texi(opsummary,2612) @set ANCHOR--info-script 1
tar.texi(opsummary,2612) @anchor{--info-script}
tar.texi(opsummary,2612) @opindex info-script@r{, summary}
tar.texi(opsummary,2613) @set ANCHOR--new-volume-script 1
tar.texi(opsummary,2613) @anchor{--new-volume-script}
tar.texi(opsummary,2613) @opindex new-volume-script@r{, summary}
tar.texi(,2614) @item --info-script=@var{script-file}
tar.texi(,2615) @itemx --new-volume-script=@var{script-file}
tar.texi(,2616) @itemx -F @var{script-file}
tar.texi(,2617) 
tar.texi(,2618) When @command{tar} is performing multi-tape backups, @var{script-file} is run
tar.texi(,2619) at the end of each tape.  If @var{script-file} exits with nonzero status,
tar.texi(,2620) @command{tar} fails immediately.  @xref{info-script}, for a detailed
tar.texi(,2621) discussion of @var{script-file}.
tar.texi(,2622) 
tar.texi(opsummary,2623) @set ANCHOR--interactive 1
tar.texi(opsummary,2623) @anchor{--interactive}
tar.texi(opsummary,2623) @opindex interactive@r{, summary}
tar.texi(,2624) @item --interactive
tar.texi(,2625) @itemx --confirmation
tar.texi(,2626) @itemx -w
tar.texi(,2627) 
tar.texi(,2628) Specifies that @command{tar} should ask the user for confirmation before
tar.texi(,2629) performing potentially destructive options, such as overwriting files.
tar.texi(,2630) @xref{interactive}.
tar.texi(,2631) 
tar.texi(opsummary,2632) @set ANCHOR--keep-newer-files 1
tar.texi(opsummary,2632) @anchor{--keep-newer-files}
tar.texi(opsummary,2632) @opindex keep-newer-files@r{, summary}
tar.texi(,2633) @item --keep-newer-files
tar.texi(,2634) 
tar.texi(,2635) Do not replace existing files that are newer than their archive copies
tar.texi(,2636) when extracting files from an archive.
tar.texi(,2637) 
tar.texi(opsummary,2638) @set ANCHOR--keep-old-files 1
tar.texi(opsummary,2638) @anchor{--keep-old-files}
tar.texi(opsummary,2638) @opindex keep-old-files@r{, summary}
tar.texi(,2639) @item --keep-old-files
tar.texi(,2640) @itemx -k
tar.texi(,2641) 
tar.texi(,2642) Do not overwrite existing files when extracting files from an archive.
tar.texi(,2643) @xref{Keep Old Files}.
tar.texi(,2644) 
tar.texi(opsummary,2645) @set ANCHOR--label 1
tar.texi(opsummary,2645) @anchor{--label}
tar.texi(opsummary,2645) @opindex label@r{, summary}
tar.texi(,2646) @item --label=@var{name}
tar.texi(,2647) @itemx -V @var{name}
tar.texi(,2648) 
tar.texi(,2649) When creating an archive, instructs @command{tar} to write @var{name}
tar.texi(,2650) as a name record in the archive.  When extracting or listing archives,
tar.texi(,2651) @command{tar} will only operate on archives that have a label matching
tar.texi(,2652) the pattern specified in @var{name}.  @xref{Tape Files}.
tar.texi(,2653) 
tar.texi(opsummary,2654) @set ANCHOR--listed-incremental 1
tar.texi(opsummary,2654) @anchor{--listed-incremental}
tar.texi(opsummary,2654) @opindex listed-incremental@r{, summary}
tar.texi(,2655) @item --listed-incremental=@var{snapshot-file}
tar.texi(,2656) @itemx -g @var{snapshot-file}
tar.texi(,2657) 
tar.texi(,2658) During a @option{--create} operation, specifies that the archive that
tar.texi(,2659) @command{tar} creates is a new @acronym{GNU}-format incremental
tar.texi(,2660) backup, using @var{snapshot-file} to determine which files to backup.
tar.texi(,2661) With other operations, informs @command{tar} that the archive is in
tar.texi(,2662) incremental format.  @xref{Incremental Dumps}.
tar.texi(,2663) 
tar.texi(opsummary,2664) @set ANCHOR--mode 1
tar.texi(opsummary,2664) @anchor{--mode}
tar.texi(opsummary,2664) @opindex mode@r{, summary}
tar.texi(,2665) @item --mode=@var{permissions}
tar.texi(,2666) 
tar.texi(,2667) When adding files to an archive, @command{tar} will use
tar.texi(,2668) @var{permissions} for the archive members, rather than the permissions
tar.texi(,2669) from the files.  @var{permissions} can be specified either as an octal
tar.texi(,2670) number or as symbolic permissions, like with
tar.texi(,2671) @command{chmod}. @xref{override}.
tar.texi(,2672) 
tar.texi(opsummary,2673) @set ANCHOR--mtime 1
tar.texi(opsummary,2673) @anchor{--mtime}
tar.texi(opsummary,2673) @opindex mtime@r{, summary}
tar.texi(,2674) @item --mtime=@var{date}
tar.texi(,2675) 
tar.texi(,2676) When adding files to an archive, @command{tar} will use @var{date} as
tar.texi(,2677) the modification time of members when creating archives, instead of
tar.texi(,2678) their actual modification times.  The value of @var{date} can be
tar.texi(,2679) either a textual date representation (@pxref{Date input formats}) or a
tar.texi(,2680) name of the existing file, starting with @samp{/} or @samp{.}.  In the
tar.texi(,2681) latter case, the modification time of that file is used. @xref{override}.
tar.texi(,2682) 
tar.texi(opsummary,2683) @set ANCHOR--multi-volume 1
tar.texi(opsummary,2683) @anchor{--multi-volume}
tar.texi(opsummary,2683) @opindex multi-volume@r{, summary}
tar.texi(,2684) @item --multi-volume
tar.texi(,2685) @itemx -M
tar.texi(,2686) 
tar.texi(,2687) Informs @command{tar} that it should create or otherwise operate on a
tar.texi(,2688) multi-volume @command{tar} archive.  @xref{Using Multiple Tapes}.
tar.texi(,2689) 
tar.texi(opsummary,2690) @opindex new-volume-script@r{, summary}
tar.texi(,2691) @item --new-volume-script
tar.texi(,2692) 
tar.texi(,2693) (see --info-script)
tar.texi(,2694) 
tar.texi(opsummary,2695) @set ANCHOR--seek 1
tar.texi(opsummary,2695) @anchor{--seek}
tar.texi(opsummary,2695) @opindex seek@r{, summary}
tar.texi(,2696) @item --seek
tar.texi(,2697) @itemx -n
tar.texi(,2698) 
tar.texi(,2699) Assume that the archive media supports seeks to arbitrary
tar.texi(,2700) locations.  Usually @command{tar} determines automatically whether
tar.texi(,2701) the archive can be seeked or not.  This option is intended for use
tar.texi(,2702) in cases when such recognition fails.
tar.texi(,2703) 
tar.texi(opsummary,2704) @set ANCHOR--newer 1
tar.texi(opsummary,2704) @anchor{--newer}
tar.texi(opsummary,2704) @opindex newer@r{, summary}
tar.texi(,2705) @item --newer=@var{date}
tar.texi(,2706) @itemx --after-date=@var{date}
tar.texi(,2707) @itemx -N
tar.texi(,2708) 
tar.texi(,2709) When creating an archive, @command{tar} will only add files that have changed
tar.texi(,2710) since @var{date}.  If @var{date} begins with @samp{/} or @samp{.}, it
tar.texi(,2711) is taken to be the name of a file whose data modification time specifies
tar.texi(,2712) the date.  @xref{after}.
tar.texi(,2713) 
tar.texi(opsummary,2714) @set ANCHOR--newer-mtime 1
tar.texi(opsummary,2714) @anchor{--newer-mtime}
tar.texi(opsummary,2714) @opindex newer-mtime@r{, summary}
tar.texi(,2715) @item --newer-mtime=@var{date}
tar.texi(,2716) 
tar.texi(,2717) Like @option{--newer}, but add only files whose
tar.texi(,2718) contents have changed (as opposed to just @option{--newer}, which will
tar.texi(,2719) also back up files for which any status information has
tar.texi(,2720) changed).  @xref{after}.
tar.texi(,2721) 
tar.texi(opsummary,2722) @set ANCHOR--no-anchored 1
tar.texi(opsummary,2722) @anchor{--no-anchored}
tar.texi(opsummary,2722) @opindex no-anchored@r{, summary}
tar.texi(,2723) @item --no-anchored
tar.texi(,2724) An exclude pattern can match any subsequence of the name's components.
tar.texi(,2725) @xref{controlling pattern-matching}.
tar.texi(,2726) 
tar.texi(opsummary,2727) @set ANCHOR--no-delay-directory-restore 1
tar.texi(opsummary,2727) @anchor{--no-delay-directory-restore}
tar.texi(opsummary,2727) @opindex no-delay-directory-restore@r{, summary}
tar.texi(,2728) @item --no-delay-directory-restore
tar.texi(,2729) 
tar.texi(,2730) Setting modification times and permissions of extracted
tar.texi(,2731) directories when all files from this directory has been
tar.texi(,2732) extracted. This is the default. @xref{Directory Modification Times and Permissions}.
tar.texi(,2733) 
tar.texi(opsummary,2734) @set ANCHOR--no-ignore-case 1
tar.texi(opsummary,2734) @anchor{--no-ignore-case}
tar.texi(opsummary,2734) @opindex no-ignore-case@r{, summary}
tar.texi(,2735) @item --no-ignore-case
tar.texi(,2736) Use case-sensitive matching.
tar.texi(,2737) @xref{controlling pattern-matching}.
tar.texi(,2738) 
tar.texi(opsummary,2739) @set ANCHOR--no-ignore-command-error 1
tar.texi(opsummary,2739) @anchor{--no-ignore-command-error}
tar.texi(opsummary,2739) @opindex no-ignore-command-error@r{, summary}
tar.texi(,2740) @item --no-ignore-command-error
tar.texi(,2741) Print warnings about subprocesses terminated with a non-zero exit
tar.texi(,2742) code. @xref{Writing to an External Program}.
tar.texi(,2743) 
tar.texi(opsummary,2744) @set ANCHOR--no-overwrite-dir 1
tar.texi(opsummary,2744) @anchor{--no-overwrite-dir}
tar.texi(opsummary,2744) @opindex no-overwrite-dir@r{, summary}
tar.texi(,2745) @item --no-overwrite-dir
tar.texi(,2746) 
tar.texi(,2747) Preserve metadata of existing directories when extracting files
tar.texi(,2748) from an archive.  @xref{Overwrite Old Files}.
tar.texi(,2749) 
tar.texi(opsummary,2750) @set ANCHOR--no-quote-chars 1
tar.texi(opsummary,2750) @anchor{--no-quote-chars}
tar.texi(opsummary,2750) @opindex no-quote-chars@r{, summary}
tar.texi(,2751) @item --no-quote-chars=@var{string}
tar.texi(,2752) Remove characters listed in @var{string} from the list of quoted
tar.texi(,2753) characters set by the previous @option{--quote-chars} option
tar.texi(,2754) (@pxref{quoting styles}).
tar.texi(,2755) 
tar.texi(opsummary,2756) @set ANCHOR--no-recursion 1
tar.texi(opsummary,2756) @anchor{--no-recursion}
tar.texi(opsummary,2756) @opindex no-recursion@r{, summary}
tar.texi(,2757) @item --no-recursion
tar.texi(,2758) 
tar.texi(,2759) With this option, @command{tar} will not recurse into directories.
tar.texi(,2760) @xref{recurse}.
tar.texi(,2761) 
tar.texi(opsummary,2762) @set ANCHOR--no-same-owner 1
tar.texi(opsummary,2762) @anchor{--no-same-owner}
tar.texi(opsummary,2762) @opindex no-same-owner@r{, summary}
tar.texi(,2763) @item --no-same-owner
tar.texi(,2764) @itemx -o
tar.texi(,2765) 
tar.texi(,2766) When extracting an archive, do not attempt to preserve the owner
tar.texi(,2767) specified in the @command{tar} archive.  This the default behavior
tar.texi(,2768) for ordinary users.
tar.texi(,2769) 
tar.texi(opsummary,2770) @set ANCHOR--no-same-permissions 1
tar.texi(opsummary,2770) @anchor{--no-same-permissions}
tar.texi(opsummary,2770) @opindex no-same-permissions@r{, summary}
tar.texi(,2771) @item --no-same-permissions
tar.texi(,2772) 
tar.texi(,2773) When extracting an archive, subtract the user's umask from files from
tar.texi(,2774) the permissions specified in the archive.  This is the default behavior
tar.texi(,2775) for ordinary users.
tar.texi(,2776) 
tar.texi(opsummary,2777) @set ANCHOR--no-unquote 1
tar.texi(opsummary,2777) @anchor{--no-unquote}
tar.texi(opsummary,2777) @opindex no-unquote@r{, summary}
tar.texi(,2778) @item --no-unquote
tar.texi(,2779) Treat all input file or member names literally, do not interpret
tar.texi(,2780) escape sequences.  @xref{input name quoting}.
tar.texi(,2781) 
tar.texi(opsummary,2782) @set ANCHOR--no-wildcards 1
tar.texi(opsummary,2782) @anchor{--no-wildcards}
tar.texi(opsummary,2782) @opindex no-wildcards@r{, summary}
tar.texi(,2783) @item --no-wildcards
tar.texi(,2784) Do not use wildcards.
tar.texi(,2785) @xref{controlling pattern-matching}.
tar.texi(,2786) 
tar.texi(opsummary,2787) @set ANCHOR--no-wildcards-match-slash 1
tar.texi(opsummary,2787) @anchor{--no-wildcards-match-slash}
tar.texi(opsummary,2787) @opindex no-wildcards-match-slash@r{, summary}
tar.texi(,2788) @item --no-wildcards-match-slash
tar.texi(,2789) Wildcards do not match @samp{/}.
tar.texi(,2790) @xref{controlling pattern-matching}.
tar.texi(,2791) 
tar.texi(opsummary,2792) @set ANCHOR--null 1
tar.texi(opsummary,2792) @anchor{--null}
tar.texi(opsummary,2792) @opindex null@r{, summary}
tar.texi(,2793) @item --null
tar.texi(,2794) 
tar.texi(,2795) When @command{tar} is using the @option{--files-from} option, this option
tar.texi(,2796) instructs @command{tar} to expect filenames terminated with @option{NUL}, so
tar.texi(,2797) @command{tar} can correctly work with file names that contain newlines.
tar.texi(,2798) @xref{nul}.
tar.texi(,2799) 
tar.texi(opsummary,2800) @set ANCHOR--numeric-owner 1
tar.texi(opsummary,2800) @anchor{--numeric-owner}
tar.texi(opsummary,2800) @opindex numeric-owner@r{, summary}
tar.texi(,2801) @item --numeric-owner
tar.texi(,2802) 
tar.texi(,2803) This option will notify @command{tar} that it should use numeric user
tar.texi(,2804) and group IDs when creating a @command{tar} file, rather than names.
tar.texi(,2805) @xref{Attributes}.
tar.texi(,2806) 
tar.texi(,2807) @item -o
tar.texi(,2808) The function of this option depends on the action @command{tar} is
tar.texi(,2809) performing.  When extracting files, @option{-o} is a synonym for
tar.texi(,2810) @option{--no-same-owner}, i.e.  it prevents @command{tar} from
tar.texi(,2811) restoring ownership of files being extracted.
tar.texi(,2812) 
tar.texi(,2813) When creating an archive, it is a synonym for
tar.texi(,2814) @option{--old-archive}.  This behavior is for compatibility
tar.texi(GNUTAR,2815) with previous versions of tar.texi(GNUTAR,2815) @acronym{GNU} @command{tar}, and will be
tar.texi(,2816) removed in the future releases.
tar.texi(,2817) 
tar.texi(,2818) @xref{Changes}, for more information.
tar.texi(,2819) 
tar.texi(opsummary,2820) @set ANCHOR--occurrence 1
tar.texi(opsummary,2820) @anchor{--occurrence}
tar.texi(opsummary,2820) @opindex occurrence@r{, summary}
tar.texi(,2821) @item --occurrence[=@var{number}]
tar.texi(,2822) 
tar.texi(,2823) This option can be used in conjunction with one of the subcommands
tar.texi(,2824) @option{--delete}, @option{--diff}, @option{--extract} or
tar.texi(,2825) @option{--list} when a list of files is given either on the command
tar.texi(,2826) line or via @option{-T} option.
tar.texi(,2827) 
tar.texi(,2828) This option instructs @command{tar} to process only the @var{number}th
tar.texi(,2829) occurrence of each named file.  @var{Number} defaults to 1, so
tar.texi(,2830) 
tar.texi(,2831) @smallexample
tar.texi(,2832) tar -x -f archive.tar --occurrence filename
tar.texi(,2833) @end smallexample
tar.texi(,2834) 
tar.texi(,2835) @noindent
tar.texi(,2836) will extract the first occurrence of the member @file{filename} from @file{archive.tar}
tar.texi(,2837) and will terminate without scanning to the end of the archive.
tar.texi(,2838) 
tar.texi(opsummary,2839) @set ANCHOR--old-archive 1
tar.texi(opsummary,2839) @anchor{--old-archive}
tar.texi(opsummary,2839) @opindex old-archive@r{, summary}
tar.texi(,2840) @item --old-archive
tar.texi(,2841) Synonym for @option{--format=v7}.
tar.texi(,2842) 
tar.texi(opsummary,2843) @set ANCHOR--one-file-system 1
tar.texi(opsummary,2843) @anchor{--one-file-system}
tar.texi(opsummary,2843) @opindex one-file-system@r{, summary}
tar.texi(,2844) @item --one-file-system
tar.texi(,2845) Used when creating an archive.  Prevents @command{tar} from recursing into
tar.texi(,2846) directories that are on different file systems from the current
tar.texi(GNUTAR,2847) directory @footnote{Earlier versions of @acronym{GNU} @command{tar} understood @option{-l} as a
tar.texi(,2848) synonym for @option{--one-file-system}.  This has changed in version
tar.texi(,2849) 1.15.91. @xref{Changes}, for more information.}.
tar.texi(,2850) 
tar.texi(opsummary,2851) @set ANCHOR--overwrite 1
tar.texi(opsummary,2851) @anchor{--overwrite}
tar.texi(opsummary,2851) @opindex overwrite@r{, summary}
tar.texi(,2852) @item --overwrite
tar.texi(,2853) 
tar.texi(,2854) Overwrite existing files and directory metadata when extracting files
tar.texi(,2855) from an archive.  @xref{Overwrite Old Files}.
tar.texi(,2856) 
tar.texi(opsummary,2857) @set ANCHOR--overwrite-dir 1
tar.texi(opsummary,2857) @anchor{--overwrite-dir}
tar.texi(opsummary,2857) @opindex overwrite-dir@r{, summary}
tar.texi(,2858) @item --overwrite-dir
tar.texi(,2859) 
tar.texi(,2860) Overwrite the metadata of existing directories when extracting files
tar.texi(,2861) from an archive.  @xref{Overwrite Old Files}.
tar.texi(,2862) 
tar.texi(opsummary,2863) @set ANCHOR--owner 1
tar.texi(opsummary,2863) @anchor{--owner}
tar.texi(opsummary,2863) @opindex owner@r{, summary}
tar.texi(,2864) @item --owner=@var{user}
tar.texi(,2865) 
tar.texi(,2866) Specifies that @command{tar} should use @var{user} as the owner of members
tar.texi(,2867) when creating archives, instead of the user associated with the source
tar.texi(,2868) file.  @var{user} is first decoded as a user symbolic name, but if
tar.texi(,2869) this interpretation fails, it has to be a decimal numeric user ID.
tar.texi(,2870) @xref{override}.
tar.texi(,2871) 
tar.texi(,2872) This option does not affect extraction from archives.
tar.texi(,2873) 
tar.texi(opsummary,2874) @set ANCHOR--transform 1
tar.texi(opsummary,2874) @anchor{--transform}
tar.texi(opsummary,2874) @opindex transform@r{, summary}
tar.texi(,2875) @item --transform=@var{sed-expr}
tar.texi(,2876) 
tar.texi(,2877) Transform file or member names using @command{sed} replacement expression
tar.texi(,2878) @var{sed-expr}.  For example,
tar.texi(,2879) 
tar.texi(,2880) @smallexample
tar.texi(,2881) $ @kbd{tar cf archive.tar --transform 's,^\./,usr/,' .}
tar.texi(,2882) @end smallexample
tar.texi(,2883) 
tar.texi(,2884) @noindent
tar.texi(,2885) will add to @file{archive} files from the current working directory,
tar.texi(,2886) replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
tar.texi(,2887) discussion, @xref{transform}.
tar.texi(,2888) 
tar.texi(,2889) To see transformed member names in verbose listings, use
tar.texi(,2890) @option{--show-transformed-names} option
tar.texi(,2891) (@pxref{show-transformed-names}).  
tar.texi(,2892) 
tar.texi(opsummary,2893) @set ANCHOR--quote-chars 1
tar.texi(opsummary,2893) @anchor{--quote-chars}
tar.texi(opsummary,2893) @opindex quote-chars@r{, summary}
tar.texi(,2894) @item --quote-chars=@var{string}
tar.texi(,2895) Always quote characters from @var{string}, even if the selected
tar.texi(,2896) quoting style would not quote them (@pxref{quoting styles}).
tar.texi(,2897) 
tar.texi(opsummary,2898) @set ANCHOR--quoting-style 1
tar.texi(opsummary,2898) @anchor{--quoting-style}
tar.texi(opsummary,2898) @opindex quoting-style@r{, summary}
tar.texi(,2899) @item --quoting-style=@var{style}
tar.texi(,2900) Set quoting style to use when printing member and file names
tar.texi(,2901) (@pxref{quoting styles}). Valid @var{style} values are:
tar.texi(,2902) @code{literal}, @code{shell}, @code{shell-always}, @code{c},
tar.texi(,2903) @code{escape}, @code{locale}, and @code{clocale}. Default quoting
tar.texi(,2904) style is @code{escape}, unless overridden while configuring the
tar.texi(,2905) package.
tar.texi(,2906) 
tar.texi(opsummary,2907) @set ANCHOR--pax-option 1
tar.texi(opsummary,2907) @anchor{--pax-option}
tar.texi(opsummary,2907) @opindex pax-option@r{, summary}
tar.texi(,2908) @item --pax-option=@var{keyword-list}
tar.texi(,2909) This option is meaningful only with @acronym{POSIX.1-2001} archives
tar.texi(,2910) (@pxref{posix}).  It modifies the way @command{tar} handles the
tar.texi(,2911) extended header keywords.  @var{Keyword-list} is a comma-separated
tar.texi(,2912) list of keyword options.  @xref{PAX keywords}, for a detailed
tar.texi(,2913) discussion.
tar.texi(,2914) 
tar.texi(opsummary,2915) @set ANCHOR--portability 1
tar.texi(opsummary,2915) @anchor{--portability}
tar.texi(opsummary,2915) @opindex portability@r{, summary}
tar.texi(,2916) @item --portability
tar.texi(,2917) @itemx --old-archive
tar.texi(,2918) Synonym for @option{--format=v7}.
tar.texi(,2919) 
tar.texi(opsummary,2920) @set ANCHOR--posix 1
tar.texi(opsummary,2920) @anchor{--posix}
tar.texi(opsummary,2920) @opindex posix@r{, summary}
tar.texi(,2921) @item --posix
tar.texi(,2922) Same as @option{--format=posix}.
tar.texi(,2923) 
tar.texi(opsummary,2924) @set ANCHOR--preserve 1
tar.texi(opsummary,2924) @anchor{--preserve}
tar.texi(opsummary,2924) @opindex preserve@r{, summary}
tar.texi(,2925) @item --preserve
tar.texi(,2926) 
tar.texi(,2927) Synonymous with specifying both @option{--preserve-permissions} and
tar.texi(,2928) @option{--same-order}.  @xref{Setting Access Permissions}.
tar.texi(,2929) 
tar.texi(opsummary,2930) @set ANCHOR--preserve-order 1
tar.texi(opsummary,2930) @anchor{--preserve-order}
tar.texi(opsummary,2930) @opindex preserve-order@r{, summary}
tar.texi(,2931) @item --preserve-order
tar.texi(,2932) 
tar.texi(,2933) (See @option{--same-order}; @pxref{Reading}.)
tar.texi(,2934) 
tar.texi(opsummary,2935) @set ANCHOR--preserve-permissions 1
tar.texi(opsummary,2935) @anchor{--preserve-permissions}
tar.texi(opsummary,2935) @opindex preserve-permissions@r{, summary}
tar.texi(opsummary,2936) @set ANCHOR--same-permissions 1
tar.texi(opsummary,2936) @anchor{--same-permissions}
tar.texi(opsummary,2936) @opindex same-permissions@r{, summary}
tar.texi(,2937) @item --preserve-permissions
tar.texi(,2938) @itemx --same-permissions
tar.texi(,2939) @itemx -p
tar.texi(,2940) 
tar.texi(,2941) When @command{tar} is extracting an archive, it normally subtracts the
tar.texi(,2942) users' umask from the permissions specified in the archive and uses
tar.texi(,2943) that number as the permissions to create the destination file.
tar.texi(,2944) Specifying this option instructs @command{tar} that it should use the
tar.texi(,2945) permissions directly from the archive.  @xref{Setting Access Permissions}.
tar.texi(,2946) 
tar.texi(opsummary,2947) @set ANCHOR--read-full-records 1
tar.texi(opsummary,2947) @anchor{--read-full-records}
tar.texi(opsummary,2947) @opindex read-full-records@r{, summary}
tar.texi(,2948) @item --read-full-records
tar.texi(,2949) @itemx -B
tar.texi(,2950) 
tar.texi(,2951) Specifies that @command{tar} should reblock its input, for reading
tar.texi(,2952) from pipes on systems with buggy implementations.  @xref{Reading}.
tar.texi(,2953) 
tar.texi(opsummary,2954) @set ANCHOR--record-size 1
tar.texi(opsummary,2954) @anchor{--record-size}
tar.texi(opsummary,2954) @opindex record-size@r{, summary}
tar.texi(,2955) @item --record-size=@var{size}
tar.texi(,2956) 
tar.texi(,2957) Instructs @command{tar} to use @var{size} bytes per record when accessing the
tar.texi(,2958) archive.  @xref{Blocking Factor}.
tar.texi(,2959) 
tar.texi(opsummary,2960) @set ANCHOR--recursion 1
tar.texi(opsummary,2960) @anchor{--recursion}
tar.texi(opsummary,2960) @opindex recursion@r{, summary}
tar.texi(,2961) @item --recursion
tar.texi(,2962) 
tar.texi(,2963) With this option, @command{tar} recurses into directories.
tar.texi(,2964) @xref{recurse}.
tar.texi(,2965) 
tar.texi(opsummary,2966) @set ANCHOR--recursive-unlink 1
tar.texi(opsummary,2966) @anchor{--recursive-unlink}
tar.texi(opsummary,2966) @opindex recursive-unlink@r{, summary}
tar.texi(,2967) @item --recursive-unlink
tar.texi(,2968) 
tar.texi(,2969) Remove existing
tar.texi(,2970) directory hierarchies before extracting directories of the same name
tar.texi(,2971) from the archive.  @xref{Recursive Unlink}.
tar.texi(,2972) 
tar.texi(opsummary,2973) @set ANCHOR--remove-files 1
tar.texi(opsummary,2973) @anchor{--remove-files}
tar.texi(opsummary,2973) @opindex remove-files@r{, summary}
tar.texi(,2974) @item --remove-files
tar.texi(,2975) 
tar.texi(,2976) Directs @command{tar} to remove the source file from the file system after
tar.texi(,2977) appending it to an archive.  @xref{remove files}.
tar.texi(,2978) 
tar.texi(opsummary,2979) @set ANCHOR--restrict 1
tar.texi(opsummary,2979) @anchor{--restrict}
tar.texi(opsummary,2979) @opindex restrict@r{, summary}
tar.texi(,2980) @item --restrict
tar.texi(,2981) 
tar.texi(,2982) Disable use of some potentially harmful @command{tar} options.
tar.texi(,2983) Currently this option disables shell invocaton from multi-volume menu
tar.texi(,2984) (@pxref{Using Multiple Tapes}).
tar.texi(,2985) 
tar.texi(opsummary,2986) @set ANCHOR--rmt-command 1
tar.texi(opsummary,2986) @anchor{--rmt-command}
tar.texi(opsummary,2986) @opindex rmt-command@r{, summary}
tar.texi(,2987) @item --rmt-command=@var{cmd}
tar.texi(,2988) 
tar.texi(,2989) Notifies @command{tar} that it should use @var{cmd} instead of
tar.texi(,2990) the default @file{/usr/libexec/rmt} (@pxref{Remote Tape Server}).
tar.texi(,2991) 
tar.texi(opsummary,2992) @set ANCHOR--rsh-command 1
tar.texi(opsummary,2992) @anchor{--rsh-command}
tar.texi(opsummary,2992) @opindex rsh-command@r{, summary}
tar.texi(,2993) @item --rsh-command=@var{cmd}
tar.texi(,2994) 
tar.texi(,2995) Notifies @command{tar} that is should use @var{cmd} to communicate with remote
tar.texi(,2996) devices.  @xref{Device}.
tar.texi(,2997) 
tar.texi(opsummary,2998) @set ANCHOR--same-order 1
tar.texi(opsummary,2998) @anchor{--same-order}
tar.texi(opsummary,2998) @opindex same-order@r{, summary}
tar.texi(,2999) @item --same-order
tar.texi(,3000) @itemx --preserve-order
tar.texi(,3001) @itemx -s
tar.texi(,3002) 
tar.texi(,3003) This option is an optimization for @command{tar} when running on machines with
tar.texi(,3004) small amounts of memory.  It informs @command{tar} that the list of file
tar.texi(,3005) arguments has already been sorted to match the order of files in the
tar.texi(,3006) archive.  @xref{Reading}.
tar.texi(,3007) 
tar.texi(opsummary,3008) @set ANCHOR--same-owner 1
tar.texi(opsummary,3008) @anchor{--same-owner}
tar.texi(opsummary,3008) @opindex same-owner@r{, summary}
tar.texi(,3009) @item --same-owner
tar.texi(,3010) 
tar.texi(,3011) When extracting an archive, @command{tar} will attempt to preserve the owner
tar.texi(,3012) specified in the @command{tar} archive with this option present.
tar.texi(,3013) This is the default behavior for the superuser; this option has an
tar.texi(,3014) effect only for ordinary users.  @xref{Attributes}.
tar.texi(,3015) 
tar.texi(opsummary,3016) @opindex same-permissions@r{, summary}
tar.texi(,3017) @item --same-permissions
tar.texi(,3018) 
tar.texi(,3019) (See @option{--preserve-permissions}; @pxref{Setting Access Permissions}.)
tar.texi(,3020) 
tar.texi(opsummary,3021) @set ANCHOR--show-defaults 1
tar.texi(opsummary,3021) @anchor{--show-defaults}
tar.texi(opsummary,3021) @opindex show-defaults@r{, summary}
tar.texi(,3022) @item --show-defaults
tar.texi(,3023) 
tar.texi(,3024) Displays the default options used by @command{tar} and exits
tar.texi(,3025) successfully.  This option is intended for use in shell scripts.
tar.texi(,3026) Here is an example of what you can see using this option:
tar.texi(,3027) 
tar.texi(,3028) @smallexample
tar.texi(,3029) $ tar --show-defaults
tar.texi(,3030) --format=gnu -f- -b20 --quoting-style=escape \
tar.texi(,3031) --rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh
tar.texi(,3032) @end smallexample
tar.texi(,3033) 
tar.texi(opsummary,3034) @set ANCHOR--show-omitted-dirs 1
tar.texi(opsummary,3034) @anchor{--show-omitted-dirs}
tar.texi(opsummary,3034) @opindex show-omitted-dirs@r{, summary}
tar.texi(,3035) @item --show-omitted-dirs
tar.texi(,3036) 
tar.texi(,3037) Instructs @command{tar} to mention directories its skipping over when
tar.texi(,3038) operating on a @command{tar} archive.  @xref{show-omitted-dirs}.
tar.texi(,3039) 
tar.texi(opsummary,3040) @set ANCHOR--show-transformed-names 1
tar.texi(opsummary,3040) @anchor{--show-transformed-names}
tar.texi(opsummary,3040) @opindex show-transformed-names@r{, summary}
tar.texi(opsummary,3041) @set ANCHOR--show-stored-names 1
tar.texi(opsummary,3041) @anchor{--show-stored-names}
tar.texi(opsummary,3041) @opindex show-stored-names@r{, summary}
tar.texi(,3042) @item --show-transformed-names
tar.texi(,3043) @itemx --show-stored-names
tar.texi(,3044) 
tar.texi(,3045) Display file or member names after applying any transformations
tar.texi(,3046) (@pxref{transform}).  In particular, when used in conjunction with one of
tar.texi(,3047) archive creation operations it instructs tar to list the member names
tar.texi(,3048) stored in the archive, as opposed to the actual file
tar.texi(,3049) names.  @xref{listing member and file names}.
tar.texi(,3050) 
tar.texi(opsummary,3051) @set ANCHOR--sparse 1
tar.texi(opsummary,3051) @anchor{--sparse}
tar.texi(opsummary,3051) @opindex sparse@r{, summary}
tar.texi(,3052) @item --sparse
tar.texi(,3053) @itemx -S
tar.texi(,3054) 
tar.texi(,3055) Invokes a @acronym{GNU} extension when adding files to an archive that handles
tar.texi(,3056) sparse files efficiently.  @xref{sparse}.
tar.texi(,3057) 
tar.texi(opsummary,3058) @set ANCHOR--sparse-version 1
tar.texi(opsummary,3058) @anchor{--sparse-version}
tar.texi(opsummary,3058) @opindex sparse-version@r{, summary}
tar.texi(,3059) @item --sparse-version=@var{version}
tar.texi(,3060) 
tar.texi(,3061) Specified the @dfn{format version} to use when archiving sparse
tar.texi(,3062) files.  Implies @option{--sparse}.  @xref{sparse}. For the description
tar.texi(,3063) of the supported sparse formats, @xref{Sparse Formats}.
tar.texi(,3064) 
tar.texi(opsummary,3065) @set ANCHOR--starting-file 1
tar.texi(opsummary,3065) @anchor{--starting-file}
tar.texi(opsummary,3065) @opindex starting-file@r{, summary}
tar.texi(,3066) @item --starting-file=@var{name}
tar.texi(,3067) @itemx -K @var{name}
tar.texi(,3068) 
tar.texi(,3069) This option affects extraction only; @command{tar} will skip extracting
tar.texi(,3070) files in the archive until it finds one that matches @var{name}.
tar.texi(,3071) @xref{Scarce}.
tar.texi(,3072) 
tar.texi(opsummary,3073) @set ANCHOR--strip-components 1
tar.texi(opsummary,3073) @anchor{--strip-components}
tar.texi(opsummary,3073) @opindex strip-components@r{, summary}
tar.texi(,3074) @item --strip-components=@var{number}
tar.texi(,3075) Strip given @var{number} of leading components from file names before
tar.texi(,3076) extraction.@footnote{This option was called @option{--strip-path} in
tar.texi(,3077) version 1.14.} For example, if archive @file{archive.tar} contained
tar.texi(,3078) @file{/some/file/name}, then running
tar.texi(,3079) 
tar.texi(,3080) @smallexample
tar.texi(,3081) tar --extract --file archive.tar --strip-components=2
tar.texi(,3082) @end smallexample
tar.texi(,3083) 
tar.texi(,3084) @noindent
tar.texi(,3085) would extract this file to file @file{name}.
tar.texi(,3086) 
tar.texi(opsummary,3087) @set ANCHOR--suffix 1
tar.texi(opsummary,3087) @anchor{--suffix}
tar.texi(opsummary,3087) @opindex suffix@r{, summary}, summary
tar.texi(,3088) @item --suffix=@var{suffix}
tar.texi(,3089) 
tar.texi(,3090) Alters the suffix @command{tar} uses when backing up files from the default
tar.texi(,3091) @samp{~}.  @xref{backup}.
tar.texi(,3092) 
tar.texi(opsummary,3093) @set ANCHOR--tape-length 1
tar.texi(opsummary,3093) @anchor{--tape-length}
tar.texi(opsummary,3093) @opindex tape-length@r{, summary}
tar.texi(,3094) @item --tape-length=@var{num}
tar.texi(,3095) @itemx -L @var{num}
tar.texi(,3096) 
tar.texi(,3097) Specifies the length of tapes that @command{tar} is writing as being
tar.texi(,3098) @w{@var{num} x 1024} bytes long.  @xref{Using Multiple Tapes}.
tar.texi(,3099) 
tar.texi(opsummary,3100) @set ANCHOR--test-label 1
tar.texi(opsummary,3100) @anchor{--test-label}
tar.texi(opsummary,3100) @opindex test-label@r{, summary}
tar.texi(,3101) @item --test-label
tar.texi(,3102) 
tar.texi(,3103) Reads the volume label.  If an argument is specified, test whether it
tar.texi(,3104) matches the volume label.  @xref{--test-label option}.
tar.texi(,3105) 
tar.texi(opsummary,3106) @set ANCHOR--to-command 1
tar.texi(opsummary,3106) @anchor{--to-command}
tar.texi(opsummary,3106) @opindex to-command@r{, summary}
tar.texi(,3107) @item --to-command=@var{command}
tar.texi(,3108) 
tar.texi(,3109) During extraction @command{tar} will pipe extracted files to the
tar.texi(,3110) standard input of @var{command}.  @xref{Writing to an External Program}.
tar.texi(,3111) 
tar.texi(opsummary,3112) @set ANCHOR--to-stdout 1
tar.texi(opsummary,3112) @anchor{--to-stdout}
tar.texi(opsummary,3112) @opindex to-stdout@r{, summary}
tar.texi(,3113) @item --to-stdout
tar.texi(,3114) @itemx -O
tar.texi(,3115) 
tar.texi(,3116) During extraction, @command{tar} will extract files to stdout rather
tar.texi(,3117) than to the file system.  @xref{Writing to Standard Output}.
tar.texi(,3118) 
tar.texi(opsummary,3119) @set ANCHOR--totals 1
tar.texi(opsummary,3119) @anchor{--totals}
tar.texi(opsummary,3119) @opindex totals@r{, summary}
tar.texi(,3120) @item --totals[=@var{signo}]
tar.texi(,3121) 
tar.texi(,3122) Displays the total number of bytes transferred when processing an
tar.texi(,3123) archive.  If an argument is given, these data are displayed on
tar.texi(,3124) request, when signal @var{signo} is delivered to @command{tar}.
tar.texi(,3125) @xref{totals}.
tar.texi(,3126) 
tar.texi(opsummary,3127) @set ANCHOR--touch 1
tar.texi(opsummary,3127) @anchor{--touch}
tar.texi(opsummary,3127) @opindex touch@r{, summary}
tar.texi(,3128) @item --touch
tar.texi(,3129) @itemx -m
tar.texi(,3130) 
tar.texi(,3131) Sets the data modification time of extracted files to the extraction time,
tar.texi(,3132) rather than the data modification time stored in the archive.
tar.texi(,3133) @xref{Data Modification Times}.
tar.texi(,3134) 
tar.texi(opsummary,3135) @opindex uncompress@r{, summary}
tar.texi(,3136) @item --uncompress
tar.texi(,3137) 
tar.texi(,3138) (See @option{--compress}. @pxref{gzip})
tar.texi(,3139) 
tar.texi(opsummary,3140) @opindex ungzip@r{, summary}
tar.texi(,3141) @item --ungzip
tar.texi(,3142) 
tar.texi(,3143) (See @option{--gzip}. @pxref{gzip})
tar.texi(,3144) 
tar.texi(opsummary,3145) @set ANCHOR--unlink-first 1
tar.texi(opsummary,3145) @anchor{--unlink-first}
tar.texi(opsummary,3145) @opindex unlink-first@r{, summary}
tar.texi(,3146) @item --unlink-first
tar.texi(,3147) @itemx -U
tar.texi(,3148) 
tar.texi(,3149) Directs @command{tar} to remove the corresponding file from the file
tar.texi(,3150) system before extracting it from the archive.  @xref{Unlink First}.
tar.texi(,3151) 
tar.texi(opsummary,3152) @set ANCHOR--unquote 1
tar.texi(opsummary,3152) @anchor{--unquote}
tar.texi(opsummary,3152) @opindex unquote@r{, summary}
tar.texi(,3153) @item --unquote
tar.texi(,3154) Enable unquoting input file or member names (default).  @xref{input
tar.texi(,3155) name quoting}.
tar.texi(,3156) 
tar.texi(opsummary,3157) @set ANCHOR--use-compress-program 1
tar.texi(opsummary,3157) @anchor{--use-compress-program}
tar.texi(opsummary,3157) @opindex use-compress-program@r{, summary}
tar.texi(,3158) @item --use-compress-program=@var{prog}
tar.texi(,3159) 
tar.texi(,3160) Instructs @command{tar} to access the archive through @var{prog}, which is
tar.texi(,3161) presumed to be a compression program of some sort.  @xref{gzip}.
tar.texi(,3162) 
tar.texi(opsummary,3163) @set ANCHOR--utc 1
tar.texi(opsummary,3163) @anchor{--utc}
tar.texi(opsummary,3163) @opindex utc@r{, summary}
tar.texi(,3164) @item --utc
tar.texi(,3165) 
tar.texi(,3166) Display file modification dates in @acronym{UTC}.  This option implies
tar.texi(,3167) @option{--verbose}.
tar.texi(,3168) 
tar.texi(opsummary,3169) @set ANCHOR--verbose 1
tar.texi(opsummary,3169) @anchor{--verbose}
tar.texi(opsummary,3169) @opindex verbose@r{, summary}
tar.texi(,3170) @item --verbose
tar.texi(,3171) @itemx -v
tar.texi(,3172) 
tar.texi(,3173) Specifies that @command{tar} should be more verbose about the operations its
tar.texi(,3174) performing.  This option can be specified multiple times for some
tar.texi(,3175) operations to increase the amount of information displayed.
tar.texi(,3176) @xref{verbose}.
tar.texi(,3177) 
tar.texi(opsummary,3178) @set ANCHOR--verify 1
tar.texi(opsummary,3178) @anchor{--verify}
tar.texi(opsummary,3178) @opindex verify@r{, summary}
tar.texi(,3179) @item --verify
tar.texi(,3180) @itemx -W
tar.texi(,3181) 
tar.texi(,3182) Verifies that the archive was correctly written when creating an
tar.texi(,3183) archive.  @xref{verify}.
tar.texi(,3184) 
tar.texi(opsummary,3185) @set ANCHOR--version 1
tar.texi(opsummary,3185) @anchor{--version}
tar.texi(opsummary,3185) @opindex version@r{, summary}
tar.texi(,3186) @item --version
tar.texi(,3187) 
tar.texi(,3188) Print information about the program's name, version, origin and legal
tar.texi(,3189) status, all on standard output, and then exit successfully.
tar.texi(,3190) @xref{help}.
tar.texi(,3191) 
tar.texi(opsummary,3192) @set ANCHOR--volno-file 1
tar.texi(opsummary,3192) @anchor{--volno-file}
tar.texi(opsummary,3192) @opindex volno-file@r{, summary}
tar.texi(,3193) @item --volno-file=@var{file}
tar.texi(,3194) 
tar.texi(,3195) Used in conjunction with @option{--multi-volume}.  @command{tar} will
tar.texi(,3196) keep track of which volume of a multi-volume archive its working in
tar.texi(,3197) @var{file}.  @xref{volno-file}.
tar.texi(,3198) 
tar.texi(opsummary,3199) @set ANCHOR--wildcards 1
tar.texi(opsummary,3199) @anchor{--wildcards}
tar.texi(opsummary,3199) @opindex wildcards@r{, summary}
tar.texi(,3200) @item --wildcards
tar.texi(,3201) Use wildcards when matching member names with patterns.
tar.texi(,3202) @xref{controlling pattern-matching}.
tar.texi(,3203) 
tar.texi(opsummary,3204) @set ANCHOR--wildcards-match-slash 1
tar.texi(opsummary,3204) @anchor{--wildcards-match-slash}
tar.texi(opsummary,3204) @opindex wildcards-match-slash@r{, summary}
tar.texi(,3205) @item --wildcards-match-slash
tar.texi(,3206) Wildcards match @samp{/}.
tar.texi(,3207) @xref{controlling pattern-matching}.
tar.texi(,3208) @end table
tar.texi(,3209) 
tar.texi(,3210) @node Short Option Summary
tar.texi(,3211) @subsection Short Options Cross Reference
tar.texi(,3212) 
tar.texi(,3213) Here is an alphabetized list of all of the short option forms, matching
tar.texi(,3214) them with the equivalent long option.
tar.texi(,3215) 
tar.texi(,3216) @multitable @columnfractions 0.20 0.80
tar.texi(,3217) @headitem Short Option  @tab Reference
tar.texi(,3218) 
tar.texi(,3219) @item -A @tab @ref{--concatenate}.
tar.texi(,3220) 
tar.texi(,3221) @item -B @tab @ref{--read-full-records}.
tar.texi(,3222) 
tar.texi(,3223) @item -C @tab @ref{--directory}.
tar.texi(,3224) 
tar.texi(,3225) @item -F @tab @ref{--info-script}.
tar.texi(,3226) 
tar.texi(,3227) @item -G @tab @ref{--incremental}.
tar.texi(,3228) 
tar.texi(,3229) @item -K @tab @ref{--starting-file}.
tar.texi(,3230) 
tar.texi(,3231) @item -L @tab @ref{--tape-length}.
tar.texi(,3232) 
tar.texi(,3233) @item -M @tab @ref{--multi-volume}.
tar.texi(,3234) 
tar.texi(,3235) @item -N @tab @ref{--newer}.
tar.texi(,3236) 
tar.texi(,3237) @item -O @tab @ref{--to-stdout}.
tar.texi(,3238) 
tar.texi(,3239) @item -P @tab @ref{--absolute-names}.
tar.texi(,3240) 
tar.texi(,3241) @item -R @tab @ref{--block-number}.
tar.texi(,3242) 
tar.texi(,3243) @item -S @tab @ref{--sparse}.
tar.texi(,3244) 
tar.texi(,3245) @item -T @tab @ref{--files-from}.
tar.texi(,3246) 
tar.texi(,3247) @item -U @tab @ref{--unlink-first}.
tar.texi(,3248) 
tar.texi(,3249) @item -V @tab @ref{--label}.
tar.texi(,3250) 
tar.texi(,3251) @item -W @tab @ref{--verify}.
tar.texi(,3252) 
tar.texi(,3253) @item -X @tab @ref{--exclude-from}.
tar.texi(,3254) 
tar.texi(,3255) @item -Z @tab @ref{--compress}.
tar.texi(,3256) 
tar.texi(,3257) @item -b @tab @ref{--blocking-factor}.
tar.texi(,3258) 
tar.texi(,3259) @item -c @tab @ref{--create}.
tar.texi(,3260) 
tar.texi(,3261) @item -d @tab @ref{--compare}.
tar.texi(,3262) 
tar.texi(,3263) @item -f @tab @ref{--file}.
tar.texi(,3264) 
tar.texi(,3265) @item -g @tab @ref{--listed-incremental}.
tar.texi(,3266) 
tar.texi(,3267) @item -h @tab @ref{--dereference}.
tar.texi(,3268) 
tar.texi(,3269) @item -i @tab @ref{--ignore-zeros}.
tar.texi(,3270) 
tar.texi(,3271) @item -j @tab @ref{--bzip2}.
tar.texi(,3272) 
tar.texi(,3273) @item -k @tab @ref{--keep-old-files}.
tar.texi(,3274) 
tar.texi(,3275) @item -l @tab @ref{--check-links}.
tar.texi(,3276) 
tar.texi(,3277) @item -m @tab @ref{--touch}.
tar.texi(,3278) 
tar.texi(,3279) @item -o @tab When creating, @ref{--no-same-owner}, when extracting ---
tar.texi(,3280) @ref{--portability}. 
tar.texi(,3281) 
tar.texi(,3282) The later usage is deprecated.  It is retained for compatibility with
tar.texi(GNUTAR,3283) the earlier versions of tar.texi(GNUTAR,3283) @acronym{GNU} @command{tar}.  In the future releases
tar.texi(,3284) @option{-o} will be equivalent to @option{--no-same-owner} only.
tar.texi(,3285) 
tar.texi(,3286) @item -p @tab @ref{--preserve-permissions}.
tar.texi(,3287) 
tar.texi(,3288) @item -r @tab @ref{--append}.
tar.texi(,3289) 
tar.texi(,3290) @item -s @tab @ref{--same-order}.
tar.texi(,3291) 
tar.texi(,3292) @item -t @tab @ref{--list}.
tar.texi(,3293) 
tar.texi(,3294) @item -u @tab @ref{--update}.
tar.texi(,3295) 
tar.texi(,3296) @item -v @tab @ref{--verbose}.
tar.texi(,3297) 
tar.texi(,3298) @item -w @tab @ref{--interactive}.
tar.texi(,3299) 
tar.texi(,3300) @item -x @tab @ref{--extract}.
tar.texi(,3301) 
tar.texi(,3302) @item -z @tab @ref{--gzip}.
tar.texi(,3303) 
tar.texi(,3304) @end multitable
tar.texi(,3305) 
tar.texi(,3306) @node help
tar.texi(GNUTAR,3307) @section tar.texi(GNUTAR,3307) @acronym{GNU} @command{tar} documentation
tar.texi(,3308) 
tar.texi(,3309) @cindex Getting program version number
tar.texi(,3310) @opindex version
tar.texi(,3311) @cindex Version of the @command{tar} program
tar.texi(,3312) Being careful, the first thing is really checking that you are using
tar.texi(GNUTAR,3313) @acronym{GNU} @command{tar}, indeed.  The @option{--version} option
tar.texi(,3314) causes @command{tar} to print information about its name, version,
tar.texi(,3315) origin and legal status, all on standard output, and then exit
tar.texi(,3316) successfully.  For example, @w{@samp{tar --version}} might print:
tar.texi(,3317) 
tar.texi(,3318) @smallexample
tar.texi(,3319) tar (GNU tar) 1.15.92
tar.texi(,3320) Copyright (C) 2006 Free Software Foundation, Inc.
tar.texi(,3321) This is free software.  You may redistribute copies of it under the terms
tar.texi(,3322) of the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
tar.texi(,3323) There is NO WARRANTY, to the extent permitted by law.
tar.texi(,3324) 
tar.texi(,3325) Written by John Gilmore and Jay Fenlason.
tar.texi(,3326) @end smallexample
tar.texi(,3327) 
tar.texi(,3328) @noindent
tar.texi(,3329) The first occurrence of @samp{tar} in the result above is the program
tar.texi(,3330) name in the package (for example, @command{rmt} is another program),
tar.texi(,3331) while the second occurrence of @samp{tar} is the name of the package
tar.texi(,3332) itself, containing possibly many programs.  The package is currently
tar.texi(,3333) named @samp{tar}, after the name of the main program it
tar.texi(,3334) contains@footnote{There are plans to merge the @command{cpio} and
tar.texi(,3335) @command{tar} packages into a single one which would be called
tar.texi(,3336) @code{paxutils}.  So, who knows if, one of this days, the
tar.texi(,3337) @option{--version} would not output @w{@samp{tar (@acronym{GNU}
tar.texi(,3338) paxutils) 3.2}}}.
tar.texi(,3339) 
tar.texi(,3340) @cindex Obtaining help
tar.texi(,3341) @cindex Listing all @command{tar} options
tar.texi(xopindex,3342) @opindex help@r{, introduction}
tar.texi(,3343) Another thing you might want to do is checking the spelling or meaning
tar.texi(,3344) of some particular @command{tar} option, without resorting to this
tar.texi(GNUTAR,3345) manual, for once you have carefully read it.  tar.texi(GNUTAR,3345) @acronym{GNU} @command{tar}
tar.texi(,3346) has a short help feature, triggerable through the
tar.texi(,3347) @option{--help} option.  By using this option, @command{tar} will
tar.texi(,3348) print a usage message listing all available options on standard
tar.texi(,3349) output, then exit successfully, without doing anything else and
tar.texi(,3350) ignoring all other options.  Even if this is only a brief summary, it
tar.texi(,3351) may be several screens long.  So, if you are not using some kind of
tar.texi(,3352) scrollable window, you might prefer to use something like:
tar.texi(,3353) 
tar.texi(,3354) @smallexample
tar.texi(,3355) $ @kbd{tar --help | less}
tar.texi(,3356) @end smallexample
tar.texi(,3357) 
tar.texi(,3358) @noindent
tar.texi(,3359) presuming, here, that you like using @command{less} for a pager.  Other
tar.texi(,3360) popular pagers are @command{more} and @command{pg}.  If you know about some
tar.texi(,3361) @var{keyword} which interests you and do not want to read all the
tar.texi(,3362) @option{--help} output, another common idiom is doing:
tar.texi(,3363) 
tar.texi(,3364) @smallexample
tar.texi(,3365) tar --help | grep @var{keyword}
tar.texi(,3366) @end smallexample
tar.texi(,3367) 
tar.texi(,3368) @noindent
tar.texi(,3369) for getting only the pertinent lines.  Notice, however, that some
tar.texi(,3370) @command{tar} options have long description lines and the above
tar.texi(,3371) command will list only the first of them.
tar.texi(,3372) 
tar.texi(,3373) The exact look of the option summary displayed by @kbd{tar --help} is
tar.texi(,3374) configurable. @xref{Configuring Help Summary}, for a detailed description.
tar.texi(,3375) 
tar.texi(,3376) @opindex usage
tar.texi(,3377) If you only wish to check the spelling of an option, running @kbd{tar
tar.texi(,3378) --usage} may be a better choice.  This will display a terse list of
tar.texi(,3379) @command{tar} option without accompanying explanations.
tar.texi(,3380) 
tar.texi(,3381) The short help output is quite succinct, and you might have to get
tar.texi(,3382) back to the full documentation for precise points.  If you are reading
tar.texi(,3383) this paragraph, you already have the @command{tar} manual in some
tar.texi(,3384) form.  This manual is available in a variety of forms from
tar.texi(GNUTAR,3385) @url{http://www.gnu.org/software/tar/manual}.  It may be printed out of the tar.texi(GNUTAR,3385) @acronym{GNU} @command{tar}
tar.texi(,3386) distribution, provided you have @TeX{} already installed somewhere,
tar.texi(,3387) and a laser printer around.  Just configure the distribution, execute
tar.texi(,3388) the command @w{@samp{make dvi}}, then print @file{doc/tar.dvi} the
tar.texi(GNUTAR,3389) usual way (contact your local guru to know how).  If tar.texi(GNUTAR,3389) @acronym{GNU} @command{tar}
tar.texi(,3390) has been conveniently installed at your place, this
tar.texi(,3391) manual is also available in interactive, hypertextual form as an Info
tar.texi(,3392) file.  Just call @w{@samp{info tar}} or, if you do not have the
tar.texi(,3393) @command{info} program handy, use the Info reader provided within
tar.texi(,3394) @acronym{GNU} Emacs, calling @samp{tar} from the main Info menu.
tar.texi(,3395) 
tar.texi(GNUTAR,3396) There is currently no @code{man} page for tar.texi(GNUTAR,3396) @acronym{GNU} @command{tar}.
tar.texi(,3397) If you observe such a @code{man} page on the system you are running,
tar.texi(GNUTAR,3398) either it does not belong to tar.texi(GNUTAR,3398) @acronym{GNU} @command{tar}, or it has not
tar.texi(,3399) been produced by @acronym{GNU}.  Some package maintainers convert
tar.texi(,3400) @kbd{tar --help} output to a man page, using @command{help2man}.  In
tar.texi(,3401) any case, please bear in mind that the authoritative source of
tar.texi(GNUTAR,3402) information about tar.texi(GNUTAR,3402) @acronym{GNU} @command{tar} is this Texinfo documentation.
tar.texi(,3403) 
tar.texi(,3404) @node defaults
tar.texi(GNUTAR,3405) @section Obtaining tar.texi(GNUTAR,3405) @acronym{GNU} @command{tar} default values
tar.texi(,3406) 
tar.texi(,3407) @opindex show-defaults
tar.texi(GNUTAR,3408) @acronym{GNU} @command{tar} has some predefined defaults that are used when you do not
tar.texi(,3409) explicitely specify another values.  To obtain a list of such
tar.texi(,3410) defaults, use @option{--show-defaults} option.  This will output the
tar.texi(,3411) values in the form of @command{tar} command line options:
tar.texi(,3412) 
tar.texi(,3413) @smallexample
tar.texi(,3414) @group
tar.texi(,3415) @kbd{tar --show-defaults}
tar.texi(,3416) --format=gnu -f- -b20 --quoting-style=escape 
tar.texi(,3417) --rmt-command=/etc/rmt --rsh-command=/usr/bin/rsh
tar.texi(,3418) @end group
tar.texi(,3419) @end smallexample
tar.texi(,3420) 
tar.texi(,3421) @noindent
tar.texi(,3422) Notice, that this option outputs only one line.  The example output above
tar.texi(,3423) has been split to fit page boundaries.
tar.texi(,3424) 
tar.texi(,3425) @noindent
tar.texi(GNUTAR,3426) The above output shows that this version of tar.texi(GNUTAR,3426) @acronym{GNU} @command{tar} defaults to
tar.texi(,3427) using @samp{gnu} archive format (@pxref{Formats}), it uses standard
tar.texi(,3428) output as the archive, if no @option{--file} option has been given
tar.texi(,3429) (@pxref{file tutorial}), the default blocking factor is 20
tar.texi(,3430) (@pxref{Blocking Factor}).  It also shows the default locations where
tar.texi(,3431) @command{tar} will look for @command{rmt} and @command{rsh} binaries.
tar.texi(,3432) 
tar.texi(,3433) @node verbose
tar.texi(,3434) @section Checking @command{tar} progress
tar.texi(,3435) 
tar.texi(,3436) Typically, @command{tar} performs most operations without reporting any
tar.texi(,3437) information to the user except error messages.  When using @command{tar}
tar.texi(,3438) with many options, particularly ones with complicated or
tar.texi(,3439) difficult-to-predict behavior, it is possible to make serious mistakes.
tar.texi(,3440) @command{tar} provides several options that make observing @command{tar}
tar.texi(,3441) easier.  These options cause @command{tar} to print information as it
tar.texi(,3442) progresses in its job, and you might want to use them just for being
tar.texi(,3443) more careful about what is going on, or merely for entertaining
tar.texi(,3444) yourself.  If you have encountered a problem when operating on an
tar.texi(,3445) archive, however, you may need more information than just an error
tar.texi(,3446) message in order to solve the problem.  The following options can be
tar.texi(,3447) helpful diagnostic tools.
tar.texi(,3448) 
tar.texi(,3449) @cindex Verbose operation
tar.texi(,3450) @opindex verbose
tar.texi(,3451) Normally, the @option{--list} (@option{-t}) command to list an archive
tar.texi(,3452) prints just the file names (one per line) and the other commands are
tar.texi(,3453) silent. When used with most operations, the @option{--verbose}
tar.texi(,3454) (@option{-v}) option causes @command{tar} to print the name of each
tar.texi(,3455) file or archive member as it is processed.  This and the other options
tar.texi(,3456) which make @command{tar} print status information can be useful in
tar.texi(,3457) monitoring @command{tar}.
tar.texi(,3458) 
tar.texi(,3459) With @option{--create} or @option{--extract}, @option{--verbose} used
tar.texi(,3460) once just prints the names of the files or members as they are processed.
tar.texi(,3461) Using it twice causes @command{tar} to print a longer listing
tar.texi(,3462) (@xref{verbose member listing}, for the description) for each member.
tar.texi(,3463) Since @option{--list} already prints  the names of the members,
tar.texi(,3464) @option{--verbose} used once with @option{--list} causes @command{tar}
tar.texi(,3465) to print an @samp{ls -l} type listing of the files in the archive.
tar.texi(,3466) The following examples both extract members with long list output:
tar.texi(,3467) 
tar.texi(,3468) @smallexample
tar.texi(,3469) $ @kbd{tar --extract --file=archive.tar --verbose --verbose}
tar.texi(,3470) $ @kbd{tar xvvf archive.tar}
tar.texi(,3471) @end smallexample
tar.texi(,3472) 
tar.texi(,3473) Verbose output appears on the standard output except when an archive is
tar.texi(,3474) being written to the standard output, as with @samp{tar --create
tar.texi(,3475) --file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the
tar.texi(,3476) installer let standard output be the default archive).  In that case
tar.texi(,3477) @command{tar} writes verbose output to the standard error stream.
tar.texi(,3478) 
tar.texi(,3479) If @option{--index-file=@var{file}} is specified, @command{tar} sends
tar.texi(,3480) verbose output to @var{file} rather than to standard output or standard
tar.texi(,3481) error.
tar.texi(,3482) 
tar.texi(,3483) @anchor{totals}
tar.texi(,3484) @cindex Obtaining total status information
tar.texi(,3485) @opindex totals
tar.texi(,3486) The @option{--totals} option causes @command{tar} to print on the
tar.texi(,3487) standard error the total amount of bytes transferred when processing
tar.texi(,3488) an archive.  When creating or appending to an archive, this option
tar.texi(,3489) prints the number of bytes written to the archive and the average
tar.texi(,3490) speed at which they have been written, e.g.:
tar.texi(,3491) 
tar.texi(,3492) @smallexample
tar.texi(,3493) @group
tar.texi(,3494) $ @kbd{tar -c -f archive.tar --totals /home}
tar.texi(,3495) Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
tar.texi(,3496) @end group
tar.texi(,3497) @end smallexample
tar.texi(,3498) 
tar.texi(,3499) When reading an archive, this option displays the number of bytes
tar.texi(,3500) read:
tar.texi(,3501) 
tar.texi(,3502) @smallexample
tar.texi(,3503) @group
tar.texi(,3504) $ @kbd{tar -x -f archive.tar --totals}
tar.texi(,3505) Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
tar.texi(,3506) @end group
tar.texi(,3507) @end smallexample
tar.texi(,3508) 
tar.texi(,3509) Finally, when deleting from an archive, the @option{--totals} option
tar.texi(,3510) displays both numbers plus number of bytes removed from the archive:
tar.texi(,3511) 
tar.texi(,3512) @smallexample
tar.texi(,3513) @group
tar.texi(,3514) $ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'}
tar.texi(,3515) Total bytes read: 9543680 (9.2MiB, 201MiB/s)
tar.texi(,3516) Total bytes written: 3829760 (3.7MiB, 81MiB/s)
tar.texi(,3517) Total bytes deleted: 1474048
tar.texi(,3518) @end group
tar.texi(,3519) @end smallexample
tar.texi(,3520) 
tar.texi(,3521) You can also obtain this information on request.  When
tar.texi(,3522) @option{--totals} is used with an argument, this argument is
tar.texi(,3523) interpreted as a symbolic name of a signal, upon delivery of which the
tar.texi(,3524) statistics is to be printed:
tar.texi(,3525) 
tar.texi(,3526) @table @option
tar.texi(,3527) @item --totals=@var{signo}
tar.texi(,3528) Print statistics upon delivery of signal @var{signo}.  Valid arguments
tar.texi(,3529) are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and
tar.texi(,3530) @code{SIGUSR2}.  Shortened names without @samp{SIG} prefix are also
tar.texi(,3531) accepted. 
tar.texi(,3532) @end table
tar.texi(,3533) 
tar.texi(,3534) Both forms of @option{--totals} option can be used simultaneously.
tar.texi(,3535) Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to
tar.texi(,3536) extract all members from its default archive and print statistics
tar.texi(,3537) after finishing the extraction, as well as when receiving signal
tar.texi(,3538) @code{SIGUSR1}. 
tar.texi(,3539) 
tar.texi(,3540) @anchor{Progress information}
tar.texi(,3541) @cindex Progress information
tar.texi(,3542) @opindex checkpoint
tar.texi(,3543) The @option{--checkpoint} option prints an occasional message
tar.texi(,3544) as @command{tar} reads or writes the archive.  It is designed for
tar.texi(,3545) those who don't need the more detailed (and voluminous) output of
tar.texi(,3546) @option{--block-number} (@option{-R}), but do want visual confirmation
tar.texi(,3547) that @command{tar} is actually making forward progress.  By default it
tar.texi(,3548) prints a message each 10 records read or written.  This can be changed
tar.texi(,3549) by giving it a numeric argument after an equal sign:
tar.texi(,3550) 
tar.texi(,3551) @smallexample
tar.texi(,3552) $ @kbd{tar -c --checkpoint=1000} /var
tar.texi(,3553) tar: Write checkpoint 1000
tar.texi(,3554) tar: Write checkpoint 2000
tar.texi(,3555) tar: Write checkpoint 3000
tar.texi(,3556) @end smallexample
tar.texi(,3557) 
tar.texi(,3558) This example shows the default checkpoint message used by
tar.texi(,3559) @command{tar}.  If you place a dot immediately after the equal
tar.texi(,3560) sign, it will print a @samp{.} at each checkpoint.  For example:
tar.texi(,3561) 
tar.texi(,3562) @smallexample
tar.texi(,3563) $ @kbd{tar -c --checkpoint=.1000} /var
tar.texi(,3564) ...
tar.texi(,3565) @end smallexample
tar.texi(,3566) 
tar.texi(,3567) @opindex show-omitted-dirs
tar.texi(,3568) @anchor{show-omitted-dirs}
tar.texi(,3569) The @option{--show-omitted-dirs} option, when reading an archive---with
tar.texi(,3570) @option{--list} or @option{--extract}, for example---causes a message
tar.texi(,3571) to be printed for each directory in the archive which is skipped.
tar.texi(,3572) This happens regardless of the reason for skipping: the directory might
tar.texi(,3573) not have been named on the command line (implicitly or explicitly),
tar.texi(,3574) it might be excluded by the use of the
tar.texi(,3575) @option{--exclude=@var{pattern}} option, or some other reason.
tar.texi(,3576) 
tar.texi(,3577) @opindex block-number
tar.texi(,3578) @cindex Block number where error occurred
tar.texi(,3579) @anchor{block-number}
tar.texi(,3580) If @option{--block-number} (@option{-R}) is used, @command{tar} prints, along with
tar.texi(,3581) every message it would normally produce, the block number within the
tar.texi(,3582) archive where the message was triggered.  Also, supplementary messages
tar.texi(,3583) are triggered when reading blocks full of NULs, or when hitting end of
tar.texi(,3584) file on the archive.  As of now, if the archive if properly terminated
tar.texi(,3585) with a NUL block, the reading of the file may stop before end of file
tar.texi(,3586) is met, so the position of end of file will not usually show when
tar.texi(GNUTAR,3587) @option{--block-number} (@option{-R}) is used.  Note that tar.texi(GNUTAR,3587) @acronym{GNU} @command{tar}
tar.texi(,3588) drains the archive before exiting when reading the
tar.texi(,3589) archive from a pipe.
tar.texi(,3590) 
tar.texi(,3591) @cindex Error message, block number of
tar.texi(,3592) This option is especially useful when reading damaged archives, since
tar.texi(,3593) it helps pinpoint the damaged sections.  It can also be used with
tar.texi(,3594) @option{--list} (@option{-t}) when listing a file-system backup tape, allowing you to
tar.texi(,3595) choose among several backup tapes when retrieving a file later, in
tar.texi(,3596) favor of the tape where the file appears earliest (closest to the
tar.texi(,3597) front of the tape).  @xref{backup}.
tar.texi(,3598) 
tar.texi(,3599) @node interactive
tar.texi(,3600) @section Asking for Confirmation During Operations
tar.texi(,3601) @cindex Interactive operation
tar.texi(,3602) 
tar.texi(,3603) Typically, @command{tar} carries out a command without stopping for
tar.texi(,3604) further instructions.  In some situations however, you may want to
tar.texi(,3605) exclude some files and archive members from the operation (for instance
tar.texi(,3606) if disk or storage space is tight).  You can do this by excluding
tar.texi(,3607) certain files automatically (@pxref{Choosing}), or by performing
tar.texi(,3608) an operation interactively, using the @option{--interactive} (@option{-w}) option.
tar.texi(,3609) @command{tar} also accepts @option{--confirmation} for this option.
tar.texi(,3610) 
tar.texi(,3611) @opindex interactive
tar.texi(,3612) When the @option{--interactive} (@option{-w}) option is specified, before
tar.texi(,3613) reading, writing, or deleting files, @command{tar} first prints a message
tar.texi(,3614) for each such file, telling what operation it intends to take, then asks
tar.texi(,3615) for confirmation on the terminal.  The actions which require
tar.texi(,3616) confirmation include adding a file to the archive, extracting a file
tar.texi(,3617) from the archive, deleting a file from the archive, and deleting a file
tar.texi(,3618) from disk.  To confirm the action, you must type a line of input
tar.texi(,3619) beginning with @samp{y}.  If your input line begins with anything other
tar.texi(,3620) than @samp{y}, @command{tar} skips that file.
tar.texi(,3621) 
tar.texi(,3622) If @command{tar} is reading the archive from the standard input,
tar.texi(,3623) @command{tar} opens the file @file{/dev/tty} to support the interactive
tar.texi(,3624) communications.
tar.texi(,3625) 
tar.texi(,3626) Verbose output is normally sent to standard output, separate from
tar.texi(,3627) other error messages.  However, if the archive is produced directly
tar.texi(,3628) on standard output, then verbose output is mixed with errors on
tar.texi(,3629) @code{stderr}.  Producing the archive on standard output may be used
tar.texi(,3630) as a way to avoid using disk space, when the archive is soon to be
tar.texi(,3631) consumed by another process reading it, say.  Some people felt the need
tar.texi(,3632) of producing an archive on stdout, still willing to segregate between
tar.texi(,3633) verbose output and error output.  A possible approach would be using a
tar.texi(,3634) named pipe to receive the archive, and having the consumer process to
tar.texi(,3635) read from that named pipe.  This has the advantage of letting standard
tar.texi(,3636) output free to receive verbose output, all separate from errors.
tar.texi(,3637) 
tar.texi(,3638) @node operations
tar.texi(GNUTAR,3639) @chapter tar.texi(GNUTAR,3639) @acronym{GNU} @command{tar} Operations
tar.texi(,3640) 
tar.texi(,3641) @menu
tar.texi(,3642) * Basic tar::
tar.texi(,3643) * Advanced tar::
tar.texi(,3644) * create options::
tar.texi(,3645) * extract options::
tar.texi(,3646) * backup::
tar.texi(,3647) * Applications::
tar.texi(,3648) * looking ahead::
tar.texi(,3649) @end menu
tar.texi(,3650) 
tar.texi(,3651) @node Basic tar
tar.texi(GNUTAR,3652) @section Basic tar.texi(GNUTAR,3652) @acronym{GNU} @command{tar} Operations
tar.texi(,3653) 
tar.texi(,3654) The basic @command{tar} operations, @option{--create} (@option{-c}),
tar.texi(,3655) @option{--list} (@option{-t}) and @option{--extract} (@option{--get},
tar.texi(,3656) @option{-x}), are currently presented and described in the tutorial
tar.texi(,3657) chapter of this manual.  This section provides some complementary notes
tar.texi(,3658) for these operations.
tar.texi(,3659) 
tar.texi(,3660) @table @option
tar.texi(xopindex,3661) @opindex create@r{, complementary notes}
tar.texi(,3662) @item --create
tar.texi(,3663) @itemx -c
tar.texi(,3664) 
tar.texi(,3665) Creating an empty archive would have some kind of elegance.  One can
tar.texi(,3666) initialize an empty archive and later use @option{--append}
tar.texi(,3667) (@option{-r}) for adding all members.  Some applications would not
tar.texi(,3668) welcome making an exception in the way of adding the first archive
tar.texi(,3669) member.  On the other hand, many people reported that it is
tar.texi(,3670) dangerously too easy for @command{tar} to destroy a magnetic tape with
tar.texi(,3671) an empty archive@footnote{This is well described in @cite{Unix-haters
tar.texi(,3672) Handbook}, by Simson Garfinkel, Daniel Weise & Steven Strassmann, IDG
tar.texi(,3673) Books, ISBN 1-56884-203-1.}.  The two most common errors are:
tar.texi(,3674) 
tar.texi(,3675) @enumerate
tar.texi(,3676) @item
tar.texi(,3677) Mistakingly using @code{create} instead of @code{extract}, when the
tar.texi(,3678) intent was to extract the full contents of an archive.  This error
tar.texi(,3679) is likely: keys @kbd{c} and @kbd{x} are right next to each other on
tar.texi(,3680) the QWERTY keyboard.  Instead of being unpacked, the archive then
tar.texi(,3681) gets wholly destroyed.  When users speak about @dfn{exploding} an
tar.texi(,3682) archive, they usually mean something else :-).
tar.texi(,3683) 
tar.texi(,3684) @item
tar.texi(,3685) Forgetting the argument to @code{file}, when the intent was to create
tar.texi(,3686) an archive with a single file in it.  This error is likely because a
tar.texi(,3687) tired user can easily add the @kbd{f} key to the cluster of option
tar.texi(,3688) letters, by the mere force of habit, without realizing the full
tar.texi(,3689) consequence of doing so.  The usual consequence is that the single
tar.texi(,3690) file, which was meant to be saved, is rather destroyed.
tar.texi(,3691) @end enumerate
tar.texi(,3692) 
tar.texi(,3693) So, recognizing the likelihood and the catastrophical nature of these
tar.texi(GNUTAR,3694) errors, tar.texi(GNUTAR,3694) @acronym{GNU} @command{tar} now takes some distance from elegance, and
tar.texi(,3695) cowardly refuses to create an archive when @option{--create} option is
tar.texi(,3696) given, there are no arguments besides options, and
tar.texi(,3697) @option{--files-from} (@option{-T}) option is @emph{not} used.  To get
tar.texi(GNUTAR,3698) around the cautiousness of tar.texi(GNUTAR,3698) @acronym{GNU} @command{tar} and nevertheless create an
tar.texi(,3699) archive with nothing in it, one may still use, as the value for the
tar.texi(,3700) @option{--files-from} option, a file with no names in it, as shown in
tar.texi(,3701) the following commands:
tar.texi(,3702) 
tar.texi(,3703) @smallexample
tar.texi(,3704) @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
tar.texi(,3705) @kbd{tar cfT empty-archive.tar /dev/null}
tar.texi(,3706) @end smallexample
tar.texi(,3707) 
tar.texi(xopindex,3708) @opindex extract@r{, complementary notes}
tar.texi(,3709) @item --extract
tar.texi(,3710) @itemx --get
tar.texi(,3711) @itemx -x
tar.texi(,3712) 
tar.texi(GNUTAR,3713) A socket is stored, within a tar.texi(GNUTAR,3713) @acronym{GNU} @command{tar} archive, as a pipe.
tar.texi(,3714) 
tar.texi(,3715) @item @option{--list} (@option{-t})
tar.texi(,3716) 
tar.texi(GNUTAR,3717) @acronym{GNU} @command{tar} now shows dates as @samp{1996-08-30},
tar.texi(,3718) while it used to show them as @samp{Aug 30 1996}. Preferably,
tar.texi(,3719) people should get used to ISO 8601 dates.  Local American dates should
tar.texi(,3720) be made available again with full date localization support, once
tar.texi(,3721) ready.  In the meantime, programs not being localizable for dates
tar.texi(,3722) should prefer international dates, that's really the way to go.
tar.texi(,3723) 
tar.texi(,3724) Look up @url{http://www.cl.cam.ac.uk/@/~mgk25/@/iso-time.html} if you
tar.texi(,3725) are curious, it contains a detailed explanation of the ISO 8601 standard.
tar.texi(,3726) 
tar.texi(,3727) @end table
tar.texi(,3728) 
tar.texi(,3729) @node Advanced tar
tar.texi(GNUTAR,3730) @section Advanced tar.texi(GNUTAR,3730) @acronym{GNU} @command{tar} Operations
tar.texi(,3731) 
tar.texi(GNUTAR,3732) Now that you have learned the basics of using tar.texi(GNUTAR,3732) @acronym{GNU} @command{tar}, you may want
tar.texi(,3733) to learn about further ways in which @command{tar} can help you.
tar.texi(,3734) 
tar.texi(,3735) This chapter presents five, more advanced operations which you probably
tar.texi(,3736) won't use on a daily basis, but which serve more specialized functions.
tar.texi(,3737) We also explain the different styles of options and why you might want
tar.texi(,3738) to use one or another, or a combination of them in your @command{tar}
tar.texi(,3739) commands.  Additionally, this chapter includes options which allow you to
tar.texi(,3740) define the output from @command{tar} more carefully, and provide help and
tar.texi(,3741) error correction in special circumstances.
tar.texi(,3742) 
tar.texi(FIXME,3744) @allow-recursion
tar.texi(FIXME,3744) @quote-arg
tar.texi(FIXME,3744) 
tar.texi(,3745) 
tar.texi(,3746) @menu
tar.texi(,3747) * Operations::
tar.texi(,3748) * append::
tar.texi(,3749) * update::
tar.texi(,3750) * concatenate::
tar.texi(,3751) * delete::
tar.texi(,3752) * compare::
tar.texi(,3753) @end menu
tar.texi(,3754) 
tar.texi(,3755) @node Operations
tar.texi(,3756) @subsection The Five Advanced @command{tar} Operations
tar.texi(UNREVISED,3757) @quotation
tar.texi(UNREVISED,3757) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,3757) @end quotation
tar.texi(,3758) 
tar.texi(,3759) In the last chapter, you learned about the first three operations to
tar.texi(,3760) @command{tar}.  This chapter presents the remaining five operations to
tar.texi(,3761) @command{tar}: @option{--append}, @option{--update}, @option{--concatenate},
tar.texi(,3762) @option{--delete}, and @option{--compare}.
tar.texi(,3763) 
tar.texi(,3764) You are not likely to use these operations as frequently as those
tar.texi(,3765) covered in the last chapter; however, since they perform specialized
tar.texi(,3766) functions, they are quite useful when you do need to use them.  We
tar.texi(,3767) will give examples using the same directory and files that you created
tar.texi(,3768) in the last chapter.  As you may recall, the directory is called
tar.texi(,3769) @file{practice}, the files are @samp{jazz}, @samp{blues}, @samp{folk},
tar.texi(,3770) @samp{rock}, and the two archive files you created are
tar.texi(,3771) @samp{collection.tar} and @samp{music.tar}.
tar.texi(,3772) 
tar.texi(,3773) We will also use the archive files @samp{afiles.tar} and
tar.texi(,3774) @samp{bfiles.tar}.  The archive @samp{afiles.tar} contains the members @samp{apple},
tar.texi(,3775) @samp{angst}, and @samp{aspic}; @samp{bfiles.tar} contains the members
tar.texi(,3776) @samp{./birds}, @samp{baboon}, and @samp{./box}.
tar.texi(,3777) 
tar.texi(,3778) Unless we state otherwise, all practicing you do and examples you follow
tar.texi(,3779) in this chapter will take place in the @file{practice} directory that
tar.texi(,3780) you created in the previous chapter; see @ref{prepare for examples}.
tar.texi(,3781) (Below in this section, we will remind you of the state of the examples
tar.texi(,3782) where the last chapter left them.)
tar.texi(,3783) 
tar.texi(,3784) The five operations that we will cover in this chapter are:
tar.texi(,3785) 
tar.texi(,3786) @table @option
tar.texi(,3787) @item --append
tar.texi(,3788) @itemx -r
tar.texi(,3789) Add new entries to an archive that already exists.
tar.texi(,3790) @item --update
tar.texi(,3791) @itemx -r
tar.texi(,3792) Add more recent copies of archive members to the end of an archive, if
tar.texi(,3793) they exist.
tar.texi(,3794) @item --concatenate
tar.texi(,3795) @itemx --catenate
tar.texi(,3796) @itemx -A
tar.texi(,3797) Add one or more pre-existing archives to the end of another archive.
tar.texi(,3798) @item --delete
tar.texi(,3799) Delete items from an archive (does not work on tapes).
tar.texi(,3800) @item --compare
tar.texi(,3801) @itemx --diff
tar.texi(,3802) @itemx -d
tar.texi(,3803) Compare archive members to their counterparts in the file system.
tar.texi(,3804) @end table
tar.texi(,3805) 
tar.texi(,3806) @node append
tar.texi(,3807) @subsection How to Add Files to Existing Archives: @option{--append}
tar.texi(UNREVISED,3808) @quotation
tar.texi(UNREVISED,3808) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,3808) @end quotation
tar.texi(,3809) 
tar.texi(,3810) @opindex append
tar.texi(,3811) If you want to add files to an existing archive, you don't need to
tar.texi(,3812) create a new archive; you can use @option{--append} (@option{-r}).
tar.texi(,3813) The archive must already exist in order to use @option{--append}.  (A
tar.texi(,3814) related operation is the @option{--update} operation; you can use this
tar.texi(,3815) to add newer versions of archive members to an existing archive.  To learn how to
tar.texi(,3816) do this with @option{--update}, @pxref{update}.)
tar.texi(,3817) 
tar.texi(,3818) If you use @option{--append} to add a file that has the same name as an
tar.texi(,3819) archive member to an archive containing that archive member, then the
tar.texi(,3820) old member is not deleted.  What does happen, however, is somewhat
tar.texi(,3821) complex.  @command{tar} @emph{allows} you to have infinite number of files
tar.texi(,3822) with the same name.  Some operations treat these same-named members no
tar.texi(,3823) differently than any other set of archive members: for example, if you
tar.texi(,3824) view an archive with @option{--list} (@option{-t}), you will see all
tar.texi(,3825) of those members listed, with their data modification times, owners, etc.
tar.texi(,3826) 
tar.texi(,3827) Other operations don't deal with these members as perfectly as you might
tar.texi(,3828) prefer; if you were to use @option{--extract} to extract the archive,
tar.texi(,3829) only the most recently added copy of a member with the same name as four
tar.texi(,3830) other members would end up in the working directory.  This is because
tar.texi(,3831) @option{--extract} extracts an archive in the order the members appeared
tar.texi(,3832) in the archive; the most recently archived members will be extracted
tar.texi(,3833) last.  Additionally, an extracted member will @emph{replace} a file of
tar.texi(,3834) the same name which existed in the directory already, and @command{tar}
tar.texi(,3835) will not prompt you about this@footnote{Unless you give it
tar.texi(,3836) @option{--keep-old-files} option, or the disk copy is newer than the
tar.texi(,3837) the one in the archive and you invoke @command{tar} with
tar.texi(,3838) @option{--keep-newer-files} option}.  Thus, only the most recently archived
tar.texi(,3839) member will end up being extracted, as it will replace the one
tar.texi(,3840) extracted before it, and so on.
tar.texi(,3841) 
tar.texi(,3842) There exists a special option that allows you to get around this
tar.texi(,3843) behavior and extract (or list) only a particular copy of the file.
tar.texi(,3844) This is @option{--occurrence} option.  If you run @command{tar} with
tar.texi(,3845) this option, it will extract only the first copy of the file.  You
tar.texi(,3846) may also give this option an argument specifying the number of
tar.texi(,3847) copy to be extracted.  Thus, for example if the archive
tar.texi(,3848) @file{archive.tar} contained three copies of file @file{myfile}, then
tar.texi(,3849) the command
tar.texi(,3850) 
tar.texi(,3851) @smallexample
tar.texi(,3852) tar --extract --file archive.tar --occurrence=2 myfile
tar.texi(,3853) @end smallexample
tar.texi(,3854) 
tar.texi(,3855) @noindent
tar.texi(,3856) would extract only the second copy.  @xref{Option
tar.texi(,3857) Summary,---occurrence}, for the description of @option{--occurrence}
tar.texi(,3858) option.
tar.texi(,3859) 
tar.texi(FIXME,3864) @allow-recursion
tar.texi(FIXME,3864) @quote-arg
tar.texi(FIXME,3864) 
tar.texi(,3865) 
tar.texi(,3866) @cindex Members, replacing with other members
tar.texi(,3867) @cindex Replacing members with other members
tar.texi(,3868) If you want to replace an archive member, use @option{--delete} to
tar.texi(,3869) delete the member you want to remove from the archive, , and then use
tar.texi(,3870) @option{--append} to add the member you want to be in the archive.  Note
tar.texi(,3871) that you can not change the order of the archive; the most recently
tar.texi(,3872) added member will still appear last.  In this sense, you cannot truly
tar.texi(,3873) ``replace'' one member with another.  (Replacing one member with another
tar.texi(,3874) will not work on certain types of media, such as tapes; see @ref{delete}
tar.texi(,3875) and @ref{Media}, for more information.)
tar.texi(,3876) 
tar.texi(,3877) @menu
tar.texi(,3878) * appending files::             Appending Files to an Archive
tar.texi(,3879) * multiple::
tar.texi(,3880) @end menu
tar.texi(,3881) 
tar.texi(,3882) @node appending files
tar.texi(,3883) @subsubsection Appending Files to an Archive
tar.texi(UNREVISED,3884) @quotation
tar.texi(UNREVISED,3884) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,3884) @end quotation
tar.texi(,3885) @cindex Adding files to an Archive
tar.texi(,3886) @cindex Appending files to an Archive
tar.texi(,3887) @cindex Archives, Appending files to
tar.texi(,3888) 
tar.texi(,3889) The simplest way to add a file to an already existing archive is the
tar.texi(,3890) @option{--append} (@option{-r}) operation, which writes specified
tar.texi(,3891) files into the archive whether or not they are already among the
tar.texi(,3892) archived files.
tar.texi(,3893) 
tar.texi(,3894) When you use @option{--append}, you @emph{must} specify file name
tar.texi(,3895) arguments, as there is no default.  If you specify a file that already
tar.texi(,3896) exists in the archive, another copy of the file will be added to the
tar.texi(,3897) end of the archive.  As with other operations, the member names of the
tar.texi(,3898) newly added files will be exactly the same as their names given on the
tar.texi(,3899) command line.  The @option{--verbose} (@option{-v}) option will print
tar.texi(,3900) out the names of the files as they are written into the archive.
tar.texi(,3901) 
tar.texi(,3902) @option{--append} cannot be performed on some tape drives, unfortunately,
tar.texi(,3903) due to deficiencies in the formats those tape drives use.  The archive
tar.texi(,3904) must be a valid @command{tar} archive, or else the results of using this
tar.texi(,3905) operation will be unpredictable.  @xref{Media}.
tar.texi(,3906) 
tar.texi(,3907) To demonstrate using @option{--append} to add a file to an archive,
tar.texi(,3908) create a file called @file{rock} in the @file{practice} directory.
tar.texi(,3909) Make sure you are in the @file{practice} directory.  Then, run the
tar.texi(,3910) following @command{tar} command to add @file{rock} to
tar.texi(,3911) @file{collection.tar}:
tar.texi(,3912) 
tar.texi(,3913) @smallexample
tar.texi(,3914) $ @kbd{tar --append --file=collection.tar rock}
tar.texi(,3915) @end smallexample
tar.texi(,3916) 
tar.texi(,3917) @noindent
tar.texi(,3918) If you now use the @option{--list} (@option{-t}) operation, you will see that
tar.texi(,3919) @file{rock} has been added to the archive:
tar.texi(,3920) 
tar.texi(,3921) @smallexample
tar.texi(,3922) $ @kbd{tar --list --file=collection.tar}
tar.texi(,3923) -rw-r--r-- me user     28 1996-10-18 16:31 jazz
tar.texi(,3924) -rw-r--r-- me user     21 1996-09-23 16:44 blues
tar.texi(,3925) -rw-r--r-- me user     20 1996-09-23 16:44 folk
tar.texi(,3926) -rw-r--r-- me user     20 1996-09-23 16:44 rock
tar.texi(,3927) @end smallexample
tar.texi(,3928) 
tar.texi(,3929) @node multiple
tar.texi(,3930) @subsubsection Multiple Members with the Same Name
tar.texi(,3931) 
tar.texi(,3932) You can use @option{--append} (@option{-r}) to add copies of files
tar.texi(,3933) which have been updated since the archive was created.  (However, we
tar.texi(,3934) do not recommend doing this since there is another @command{tar}
tar.texi(,3935) option called @option{--update}; @xref{update}, for more information.
tar.texi(,3936) We describe this use of @option{--append} here for the sake of
tar.texi(,3937) completeness.)  When you extract the archive, the older version will
tar.texi(,3938) be effectively lost.  This works because files are extracted from an
tar.texi(,3939) archive in the order in which they were archived.  Thus, when the
tar.texi(,3940) archive is extracted, a file archived later in time will replace a
tar.texi(,3941) file of the same name which was archived earlier, even though the
tar.texi(,3942) older version of the file will remain in the archive unless you delete
tar.texi(,3943) all versions of the file. 
tar.texi(,3944) 
tar.texi(,3945) Supposing you change the file @file{blues} and then append the changed
tar.texi(,3946) version to @file{collection.tar}.  As you saw above, the original
tar.texi(,3947) @file{blues} is in the archive @file{collection.tar}.  If you change the
tar.texi(,3948) file and append the new version of the file to the archive, there will
tar.texi(,3949) be two copies in the archive.  When you extract the archive, the older
tar.texi(,3950) version of the file will be extracted first, and then replaced by the
tar.texi(,3951) newer version when it is extracted.
tar.texi(,3952) 
tar.texi(,3953) You can append the new, changed copy of the file @file{blues} to the
tar.texi(,3954) archive in this way:
tar.texi(,3955) 
tar.texi(,3956) @smallexample
tar.texi(,3957) $ @kbd{tar --append --verbose --file=collection.tar blues}
tar.texi(,3958) blues
tar.texi(,3959) @end smallexample
tar.texi(,3960) 
tar.texi(,3961) @noindent
tar.texi(,3962) Because you specified the @option{--verbose} option, @command{tar} has
tar.texi(,3963) printed the name of the file being appended as it was acted on.  Now
tar.texi(,3964) list the contents of the archive:
tar.texi(,3965) 
tar.texi(,3966) @smallexample
tar.texi(,3967) $ @kbd{tar --list --verbose --file=collection.tar}
tar.texi(,3968) -rw-r--r-- me user     28 1996-10-18 16:31 jazz
tar.texi(,3969) -rw-r--r-- me user     21 1996-09-23 16:44 blues
tar.texi(,3970) -rw-r--r-- me user     20 1996-09-23 16:44 folk
tar.texi(,3971) -rw-r--r-- me user     20 1996-09-23 16:44 rock
tar.texi(,3972) -rw-r--r-- me user     58 1996-10-24 18:30 blues
tar.texi(,3973) @end smallexample
tar.texi(,3974) 
tar.texi(,3975) @noindent
tar.texi(,3976) The newest version of @file{blues} is now at the end of the archive
tar.texi(,3977) (note the different creation dates and file sizes).  If you extract
tar.texi(,3978) the archive, the older version of the file @file{blues} will be
tar.texi(,3979) replaced by the newer version.  You can confirm this by extracting
tar.texi(,3980) the archive and running @samp{ls} on the directory.
tar.texi(,3981) 
tar.texi(,3982) If you wish to extract the first occurrence of the file @file{blues}
tar.texi(,3983) from the archive, use @option{--occurrence} option, as shown in
tar.texi(,3984) the following example:
tar.texi(,3985) 
tar.texi(,3986) @smallexample
tar.texi(,3987) $ @kbd{tar --extract -vv --occurrence --file=collection.tar blues}
tar.texi(,3988) -rw-r--r-- me user     21 1996-09-23 16:44 blues
tar.texi(,3989) @end smallexample
tar.texi(,3990) 
tar.texi(,3991) @xref{Writing}, for more information on @option{--extract} and
tar.texi(,3992) @xref{Option Summary, --occurrence}, for the description of
tar.texi(,3993) @option{--occurrence} option.
tar.texi(,3994) 
tar.texi(,3995) @node update
tar.texi(,3996) @subsection Updating an Archive
tar.texi(UNREVISED,3997) @quotation
tar.texi(UNREVISED,3997) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,3997) @end quotation
tar.texi(,3998) @cindex Updating an archive
tar.texi(,3999) 
tar.texi(,4000) @opindex update
tar.texi(,4001) In the previous section, you learned how to use @option{--append} to
tar.texi(,4002) add a file to an existing archive.  A related operation is
tar.texi(,4003) @option{--update} (@option{-u}).  The @option{--update} operation
tar.texi(,4004) updates a @command{tar} archive by comparing the date of the specified
tar.texi(,4005) archive members against the date of the file with the same name.  If
tar.texi(,4006) the file has been modified more recently than the archive member, then
tar.texi(,4007) the newer version of the file is added to the archive (as with
tar.texi(,4008) @option{--append}).
tar.texi(,4009) 
tar.texi(,4010) Unfortunately, you cannot use @option{--update} with magnetic tape drives.
tar.texi(,4011) The operation will fail.
tar.texi(,4012) 
tar.texi(FIXME,4014) @allow-recursion
tar.texi(FIXME,4014) @quote-arg
tar.texi(FIXME,4014) 
tar.texi(,4015) 
tar.texi(,4016) Both @option{--update} and @option{--append} work by adding to the end
tar.texi(,4017) of the archive.  When you extract a file from the archive, only the
tar.texi(,4018) version stored last will wind up in the file system, unless you use
tar.texi(,4019) the @option{--backup} option.  @xref{multiple}, for a detailed discussion.
tar.texi(,4020) 
tar.texi(,4021) @menu
tar.texi(,4022) * how to update::
tar.texi(,4023) @end menu
tar.texi(,4024) 
tar.texi(,4025) @node how to update
tar.texi(,4026) @subsubsection How to Update an Archive Using @option{--update}
tar.texi(,4027) 
tar.texi(,4028) You must use file name arguments with the @option{--update}
tar.texi(,4029) (@option{-u}) operation.  If you don't specify any files,
tar.texi(,4030) @command{tar} won't act on any files and won't tell you that it didn't
tar.texi(,4031) do anything (which may end up confusing you).
tar.texi(,4032) 
tar.texi(,4033) @c note: the above parenthetical added because in fact, this
tar.texi(,4034) @c behavior just confused the author. :-)
tar.texi(,4035) 
tar.texi(,4036) To see the @option{--update} option at work, create a new file,
tar.texi(,4037) @file{classical}, in your practice directory, and some extra text to the
tar.texi(,4038) file @file{blues}, using any text editor.  Then invoke @command{tar} with
tar.texi(,4039) the @samp{update} operation and the @option{--verbose} (@option{-v})
tar.texi(,4040) option specified, using the names of all the files in the practice
tar.texi(,4041) directory as file name arguments:
tar.texi(,4042) 
tar.texi(,4043) @smallexample
tar.texi(,4044) $ @kbd{tar --update -v -f collection.tar blues folk rock classical}
tar.texi(,4045) blues
tar.texi(,4046) classical
tar.texi(,4047) $
tar.texi(,4048) @end smallexample
tar.texi(,4049) 
tar.texi(,4050) @noindent
tar.texi(,4051) Because we have specified verbose mode, @command{tar} prints out the names
tar.texi(,4052) of the files it is working on, which in this case are the names of the
tar.texi(,4053) files that needed to be updated.  If you run @samp{tar --list} and look
tar.texi(,4054) at the archive, you will see @file{blues} and @file{classical} at its
tar.texi(,4055) end.  There will be a total of two versions of the member @samp{blues};
tar.texi(,4056) the one at the end will be newer and larger, since you added text before
tar.texi(,4057) updating it.
tar.texi(,4058) 
tar.texi(,4059) (The reason @command{tar} does not overwrite the older file when updating
tar.texi(,4060) it is because writing to the middle of a section of tape is a difficult
tar.texi(,4061) process.  Tapes are not designed to go backward.  @xref{Media}, for more
tar.texi(,4062) information about tapes.
tar.texi(,4063) 
tar.texi(,4064) @option{--update} (@option{-u}) is not suitable for performing backups for two
tar.texi(,4065) reasons: it does not change directory content entries, and it
tar.texi(GNUTAR,4066) lengthens the archive every time it is used.  The tar.texi(GNUTAR,4066) @acronym{GNU} @command{tar}
tar.texi(,4067) options intended specifically for backups are more
tar.texi(,4068) efficient.  If you need to run backups, please consult @ref{Backups}.
tar.texi(,4069) 
tar.texi(,4070) @node concatenate
tar.texi(,4071) @subsection Combining Archives with @option{--concatenate}
tar.texi(,4072) 
tar.texi(,4073) @cindex Adding archives to an archive
tar.texi(,4074) @cindex Concatenating Archives
tar.texi(,4075) @opindex concatenate
tar.texi(,4076) @opindex catenate
tar.texi(,4077) @c @cindex @option{-A} described
tar.texi(,4078) Sometimes it may be convenient to add a second archive onto the end of
tar.texi(,4079) an archive rather than adding individual files to the archive.  To add
tar.texi(,4080) one or more archives to the end of another archive, you should use the
tar.texi(,4081) @option{--concatenate} (@option{--catenate}, @option{-A}) operation.
tar.texi(,4082) 
tar.texi(,4083) To use @option{--concatenate}, give the first archive with
tar.texi(,4084) @option{--file} option and name the rest of archives to be
tar.texi(,4085) concatenated on the command line.  The members, and their member
tar.texi(,4086) names, will be copied verbatim from those archives to the first one.
tar.texi(,4087) @footnote{This can cause multiple members to have the same name, for
tar.texi(,4088) information on how this affects reading the archive, @ref{multiple}.}
tar.texi(,4089) The new, concatenated archive will be called by the same name as the
tar.texi(,4090) one given with the @option{--file} option.  As usual, if you omit
tar.texi(,4091) @option{--file}, @command{tar} will use the value of the environment
tar.texi(,4092) variable @env{TAPE}, or, if this has not been set, the default archive name.
tar.texi(,4093) 
tar.texi(FIXME,4094) @allow-recursion
tar.texi(FIXME,4094) @quote-arg
tar.texi(FIXME,4094) 
tar.texi(,4095) 
tar.texi(,4096) To demonstrate how @option{--concatenate} works, create two small archives
tar.texi(,4097) called @file{bluesrock.tar} and @file{folkjazz.tar}, using the relevant
tar.texi(,4098) files from @file{practice}:
tar.texi(,4099) 
tar.texi(,4100) @smallexample
tar.texi(,4101) $ @kbd{tar -cvf bluesrock.tar blues rock}
tar.texi(,4102) blues
tar.texi(,4103) rock
tar.texi(,4104) $ @kbd{tar -cvf folkjazz.tar folk jazz}
tar.texi(,4105) folk
tar.texi(,4106) jazz
tar.texi(,4107) @end smallexample
tar.texi(,4108) 
tar.texi(,4109) @noindent
tar.texi(,4110) If you like, You can run @samp{tar --list} to make sure the archives
tar.texi(,4111) contain what they are supposed to:
tar.texi(,4112) 
tar.texi(,4113) @smallexample
tar.texi(,4114) $ @kbd{tar -tvf bluesrock.tar}
tar.texi(,4115) -rw-r--r-- melissa user    105 1997-01-21 19:42 blues
tar.texi(,4116) -rw-r--r-- melissa user     33 1997-01-20 15:34 rock
tar.texi(,4117) $ @kbd{tar -tvf jazzfolk.tar}
tar.texi(,4118) -rw-r--r-- melissa user     20 1996-09-23 16:44 folk
tar.texi(,4119) -rw-r--r-- melissa user     65 1997-01-30 14:15 jazz
tar.texi(,4120) @end smallexample
tar.texi(,4121) 
tar.texi(,4122) We can concatenate these two archives with @command{tar}:
tar.texi(,4123) 
tar.texi(,4124) @smallexample
tar.texi(,4125) $ @kbd{cd ..}
tar.texi(,4126) $ @kbd{tar --concatenate --file=bluesrock.tar jazzfolk.tar}
tar.texi(,4127) @end smallexample
tar.texi(,4128) 
tar.texi(,4129) If you now list the contents of the @file{bluesrock.tar}, you will see
tar.texi(,4130) that now it also contains the archive members of @file{jazzfolk.tar}:
tar.texi(,4131) 
tar.texi(,4132) @smallexample
tar.texi(,4133) $ @kbd{tar --list --file=bluesrock.tar}
tar.texi(,4134) blues
tar.texi(,4135) rock
tar.texi(,4136) folk
tar.texi(,4137) jazz
tar.texi(,4138) @end smallexample
tar.texi(,4139) 
tar.texi(,4140) When you use @option{--concatenate}, the source and target archives must
tar.texi(,4141) already exist and must have been created using compatible format
tar.texi(,4142) parameters.  Notice, that @command{tar} does not check whether the
tar.texi(,4143) archives it concatenates have compatible formats, it does not
tar.texi(,4144) even check if the files are really tar archives.
tar.texi(,4145) 
tar.texi(,4146) Like @option{--append} (@option{-r}), this operation cannot be performed on some
tar.texi(,4147) tape drives, due to deficiencies in the formats those tape drives use.
tar.texi(,4148) 
tar.texi(,4149) @cindex @code{concatenate} vs @command{cat}
tar.texi(,4150) @cindex @command{cat} vs @code{concatenate}
tar.texi(,4151) It may seem more intuitive to you to want or try to use @command{cat} to
tar.texi(,4152) concatenate two archives instead of using the @option{--concatenate}
tar.texi(,4153) operation; after all, @command{cat} is the utility for combining files.
tar.texi(,4154) 
tar.texi(,4155) However, @command{tar} archives incorporate an end-of-file marker which
tar.texi(,4156) must be removed if the concatenated archives are to be read properly as
tar.texi(,4157) one archive.  @option{--concatenate} removes the end-of-archive marker
tar.texi(,4158) from the target archive before each new archive is appended.  If you use
tar.texi(,4159) @command{cat} to combine the archives, the result will not be a valid
tar.texi(,4160) @command{tar} format archive.  If you need to retrieve files from an
tar.texi(,4161) archive that was added to using the @command{cat} utility, use the
tar.texi(,4162) @option{--ignore-zeros} (@option{-i}) option.  @xref{Ignore Zeros}, for further
tar.texi(,4163) information on dealing with archives improperly combined using the
tar.texi(,4164) @command{cat} shell utility.
tar.texi(,4165) 
tar.texi(,4166) @node delete
tar.texi(,4167) @subsection Removing Archive Members Using @option{--delete}
tar.texi(UNREVISED,4168) @quotation
tar.texi(UNREVISED,4168) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,4168) @end quotation
tar.texi(,4169) @cindex Deleting files from an archive
tar.texi(,4170) @cindex Removing files from an archive
tar.texi(,4171) 
tar.texi(,4172) @opindex delete
tar.texi(,4173) You can remove members from an archive by using the @option{--delete}
tar.texi(,4174) option.  Specify the name of the archive with @option{--file}
tar.texi(,4175) (@option{-f}) and then specify the names of the members to be deleted;
tar.texi(,4176) if you list no member names, nothing will be deleted.  The
tar.texi(,4177) @option{--verbose} option will cause @command{tar} to print the names
tar.texi(,4178) of the members as they are deleted. As with @option{--extract}, you
tar.texi(,4179) must give the exact member names when using @samp{tar --delete}.
tar.texi(,4180) @option{--delete} will remove all versions of the named file from the
tar.texi(,4181) archive.  The @option{--delete} operation can run very slowly.
tar.texi(,4182) 
tar.texi(,4183) Unlike other operations, @option{--delete} has no short form.
tar.texi(,4184) 
tar.texi(,4185) @cindex Tapes, using @option{--delete} and
tar.texi(,4186) @cindex Deleting from tape archives
tar.texi(,4187) This operation will rewrite the archive.  You can only use
tar.texi(,4188) @option{--delete} on an archive if the archive device allows you to
tar.texi(,4189) write to any point on the media, such as a disk; because of this, it
tar.texi(,4190) does not work on magnetic tapes.  Do not try to delete an archive member
tar.texi(,4191) from a magnetic tape; the action will not succeed, and you will be
tar.texi(,4192) likely to scramble the archive and damage your tape.  There is no safe
tar.texi(,4193) way (except by completely re-writing the archive) to delete files from
tar.texi(,4194) most kinds of magnetic tape.  @xref{Media}.
tar.texi(,4195) 
tar.texi(,4196) To delete all versions of the file @file{blues} from the archive
tar.texi(,4197) @file{collection.tar} in the @file{practice} directory, make sure you
tar.texi(,4198) are in that directory, and then,
tar.texi(,4199) 
tar.texi(,4200) @smallexample
tar.texi(,4201) $ @kbd{tar --list --file=collection.tar}
tar.texi(,4202) blues
tar.texi(,4203) folk
tar.texi(,4204) jazz
tar.texi(,4205) rock
tar.texi(,4206) $ @kbd{tar --delete --file=collection.tar blues}
tar.texi(,4207) $ @kbd{tar --list --file=collection.tar}
tar.texi(,4208) folk
tar.texi(,4209) jazz
tar.texi(,4210) rock
tar.texi(,4211) $
tar.texi(,4212) @end smallexample
tar.texi(,4213) 
tar.texi(FIXME,4215) @allow-recursion
tar.texi(FIXME,4215) @quote-arg
tar.texi(FIXME,4215) 
tar.texi(,4216) 
tar.texi(,4217) The @option{--delete} option has been reported to work properly when
tar.texi(,4218) @command{tar} acts as a filter from @code{stdin} to @code{stdout}.
tar.texi(,4219) 
tar.texi(,4220) @node compare
tar.texi(,4221) @subsection Comparing Archive Members with the File System
tar.texi(,4222) @cindex Verifying the currency of an archive
tar.texi(UNREVISED,4223) @quotation
tar.texi(UNREVISED,4223) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,4223) @end quotation
tar.texi(,4224) 
tar.texi(,4225) @opindex compare
tar.texi(,4226) The @option{--compare} (@option{-d}), or @option{--diff} operation compares
tar.texi(,4227) specified archive members against files with the same names, and then
tar.texi(,4228) reports differences in file size, mode, owner, modification date and
tar.texi(,4229) contents.  You should @emph{only} specify archive member names, not file
tar.texi(,4230) names.  If you do not name any members, then @command{tar} will compare the
tar.texi(,4231) entire archive.  If a file is represented in the archive but does not
tar.texi(,4232) exist in the file system, @command{tar} reports a difference.
tar.texi(,4233) 
tar.texi(,4234) You have to specify the record size of the archive when modifying an
tar.texi(,4235) archive with a non-default record size.
tar.texi(,4236) 
tar.texi(,4237) @command{tar} ignores files in the file system that do not have
tar.texi(,4238) corresponding members in the archive.
tar.texi(,4239) 
tar.texi(,4240) The following example compares the archive members @file{rock},
tar.texi(,4241) @file{blues} and @file{funk} in the archive @file{bluesrock.tar} with
tar.texi(,4242) files of the same name in the file system.  (Note that there is no file,
tar.texi(,4243) @file{funk}; @command{tar} will report an error message.)
tar.texi(,4244) 
tar.texi(,4245) @smallexample
tar.texi(,4246) $ @kbd{tar --compare --file=bluesrock.tar rock blues funk}
tar.texi(,4247) rock
tar.texi(,4248) blues
tar.texi(,4249) tar: funk not found in archive
tar.texi(,4250) @end smallexample
tar.texi(,4251) 
tar.texi(,4252) The spirit behind the @option{--compare} (@option{--diff},
tar.texi(,4253) @option{-d}) option is to check whether the archive represents the
tar.texi(,4254) current state of files on disk, more than validating the integrity of
tar.texi(,4255) the archive media.  For this later goal, @xref{verify}. 
tar.texi(,4256) 
tar.texi(,4257) @node create options
tar.texi(,4258) @section Options Used by @option{--create}
tar.texi(,4259) 
tar.texi(xopindex,4260) @opindex create@r{, additional options}
tar.texi(,4261) The previous chapter described the basics of how to use
tar.texi(,4262) @option{--create} (@option{-c}) to create an archive from a set of files.
tar.texi(,4263) @xref{create}.  This section described advanced options to be used with
tar.texi(,4264) @option{--create}.
tar.texi(,4265) 
tar.texi(,4266) @menu
tar.texi(,4267) * override::                  Overriding File Metadata.
tar.texi(,4268) * Ignore Failed Read::
tar.texi(,4269) @end menu
tar.texi(,4270) 
tar.texi(,4271) @node override
tar.texi(,4272) @subsection Overriding File Metadata
tar.texi(,4273) 
tar.texi(,4274) As described above, a @command{tar} archive keeps, for each member it contains,
tar.texi(,4275) its @dfn{metadata}, such as modification time, mode and ownership of
tar.texi(GNUTAR,4276) the file.  tar.texi(GNUTAR,4276) @acronym{GNU} @command{tar} allows to replace these data with other values
tar.texi(,4277) when adding files to the archive.  The options described in this
tar.texi(,4278) section affect creation of archives of any type.  For POSIX archives,
tar.texi(,4279) see also @ref{PAX keywords}, for additional ways of controlling
tar.texi(,4280) metadata, stored in the archive.
tar.texi(,4281) 
tar.texi(,4282) @table @option
tar.texi(,4283) @opindex mode
tar.texi(,4284) @item --mode=@var{permissions}
tar.texi(,4285) 
tar.texi(,4286) When adding files to an archive, @command{tar} will use
tar.texi(,4287) @var{permissions} for the archive members, rather than the permissions
tar.texi(,4288) from the files.  @var{permissions} can be specified either as an octal
tar.texi(,4289) number or as symbolic permissions, like with
tar.texi(,4290) @command{chmod} (@xref{File permissions, Permissions, File
tar.texi(,4291) permissions, fileutils, @acronym{GNU} file utilities}.  This reference
tar.texi(,4292) also has useful information for those not being overly familiar with
tar.texi(,4293) the UNIX permission system).  Using latter syntax allows for
tar.texi(,4294) more flexibility.  For example, the value @samp{a+rw} adds read and write
tar.texi(,4295) permissions for everybody, while retaining executable bits on directories
tar.texi(,4296) or on any other file already marked as executable:
tar.texi(,4297) 
tar.texi(,4298) @smallexample
tar.texi(,4299) $ @kbd{tar -c -f archive.tar --mode='a+rw' .}
tar.texi(,4300) @end smallexample
tar.texi(,4301) 
tar.texi(,4302) @item --mtime=@var{date}
tar.texi(,4303) @opindex mtime
tar.texi(,4304) 
tar.texi(,4305) When adding files to an archive, @command{tar} will use @var{date} as
tar.texi(,4306) the modification time of members when creating archives, instead of
tar.texi(,4307) their actual modification times.  The argument @var{date} can be
tar.texi(,4308) either a textual date representation in almost arbitrary format
tar.texi(,4309) (@pxref{Date input formats}) or a name of the existing file, starting
tar.texi(,4310) with @samp{/} or @samp{.}.  In the latter case, the modification time
tar.texi(,4311) of that file will be used.
tar.texi(,4312) 
tar.texi(,4313) The following example will set the modification date to 00:00:00 UTC,
tar.texi(,4314) January 1, 1970:
tar.texi(,4315) 
tar.texi(,4316) @smallexample
tar.texi(,4317) $ @kbd{tar -c -f archive.tar --mtime='1970-01-01' .}
tar.texi(,4318) @end smallexample
tar.texi(,4319) 
tar.texi(,4320) @noindent
tar.texi(GNUTAR,4321) When used with @option{--verbose} (@pxref{verbose tutorial}) tar.texi(GNUTAR,4321) @acronym{GNU} @command{tar}
tar.texi(,4322) will try to convert the specified date back to its textual
tar.texi(,4323) representation and compare it with the one given with
tar.texi(,4324) @option{--mtime} options.  If the two dates differ, @command{tar} will
tar.texi(,4325) print a warning saying what date it will use.  This is to help user
tar.texi(,4326) ensure he is using the right date.
tar.texi(,4327) 
tar.texi(,4328) For example:
tar.texi(,4329) 
tar.texi(,4330) @smallexample
tar.texi(,4331) $ @kbd{tar -c -f archive.tar -v --mtime=yesterday .}
tar.texi(,4332) tar: Option --mtime: Treating date `yesterday' as 2006-06-20
tar.texi(,4333) 13:06:29.152478
tar.texi(,4334) @dots{}
tar.texi(,4335) @end smallexample
tar.texi(,4336) 
tar.texi(,4337) @item --owner=@var{user}
tar.texi(,4338) @opindex owner
tar.texi(,4339) 
tar.texi(,4340) Specifies that @command{tar} should use @var{user} as the owner of members
tar.texi(,4341) when creating archives, instead of the user associated with the source
tar.texi(,4342) file.  The argument @var{user} can be either an existing user symbolic
tar.texi(,4343) name, or a decimal numeric user ID.
tar.texi(,4344) 
tar.texi(,4345) There is no value indicating a missing number, and @samp{0} usually means
tar.texi(,4346) @code{root}.  Some people like to force @samp{0} as the value to offer in
tar.texi(,4347) their distributions for the owner of files, because the @code{root} user is
tar.texi(,4348) anonymous anyway, so that might as well be the owner of anonymous
tar.texi(,4349) archives.  For example:
tar.texi(,4350) 
tar.texi(,4351) @smallexample
tar.texi(,4352) @group
tar.texi(,4353) $ @kbd{tar -c -f archive.tar --owner=0 .}
tar.texi(,4354) # @r{Or:}
tar.texi(,4355) $ @kbd{tar -c -f archive.tar --owner=root .}
tar.texi(,4356) @end group
tar.texi(,4357) @end smallexample
tar.texi(,4358) 
tar.texi(,4359) @item --group=@var{group}
tar.texi(,4360) @opindex group
tar.texi(,4361) 
tar.texi(,4362) Files added to the @command{tar} archive will have a group id of @var{group},
tar.texi(,4363) rather than the group from the source file.  The argument @var{group}
tar.texi(,4364) can be either an existing group symbolic name, or a decimal numeric group ID.
tar.texi(,4365) @end table
tar.texi(,4366) 
tar.texi(,4367) @node Ignore Failed Read
tar.texi(,4368) @subsection Ignore Fail Read
tar.texi(,4369) 
tar.texi(,4370) @table @option
tar.texi(,4371) @item --ignore-failed-read
tar.texi(,4372) @opindex ignore-failed-read
tar.texi(,4373) Do not exit with nonzero on unreadable files or directories.
tar.texi(,4374) @end table
tar.texi(,4375) 
tar.texi(,4376) @node extract options
tar.texi(,4377) @section Options Used by @option{--extract}
tar.texi(UNREVISED,4378) @quotation
tar.texi(UNREVISED,4378) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,4378) @end quotation
tar.texi(,4379) 
tar.texi(xopindex,4380) @opindex extract@r{, additional options}
tar.texi(,4381) The previous chapter showed how to use @option{--extract} to extract
tar.texi(,4382) an archive into the file system.  Various options cause @command{tar} to
tar.texi(,4383) extract more information than just file contents, such as the owner,
tar.texi(,4384) the permissions, the modification date, and so forth.  This section
tar.texi(,4385) presents options to be used with @option{--extract} when certain special
tar.texi(,4386) considerations arise.  You may review the information presented in
tar.texi(,4387) @ref{extract} for more basic information about the
tar.texi(,4388) @option{--extract} operation.
tar.texi(,4389) 
tar.texi(,4390) @menu
tar.texi(,4391) * Reading::                     Options to Help Read Archives
tar.texi(,4392) * Writing::                     Changing How @command{tar} Writes Files
tar.texi(,4393) * Scarce::                      Coping with Scarce Resources
tar.texi(,4394) @end menu
tar.texi(,4395) 
tar.texi(,4396) @node Reading
tar.texi(,4397) @subsection Options to Help Read Archives
tar.texi(,4398) @cindex Options when reading archives
tar.texi(UNREVISED,4399) @quotation
tar.texi(UNREVISED,4399) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,4399) @end quotation
tar.texi(,4400) 
tar.texi(,4401) @cindex Reading incomplete records
tar.texi(,4402) @cindex Records, incomplete
tar.texi(,4403) @opindex read-full-records
tar.texi(,4404) Normally, @command{tar} will request data in full record increments from
tar.texi(,4405) an archive storage device.  If the device cannot return a full record,
tar.texi(,4406) @command{tar} will report an error.  However, some devices do not always
tar.texi(,4407) return full records, or do not require the last record of an archive to
tar.texi(,4408) be padded out to the next record boundary.  To keep reading until you
tar.texi(,4409) obtain a full record, or to accept an incomplete record if it contains
tar.texi(,4410) an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option
tar.texi(,4411) in conjunction with the @option{--extract} or @option{--list} operations.
tar.texi(,4412) @xref{Blocking}.
tar.texi(,4413) 
tar.texi(,4414) The @option{--read-full-records} (@option{-B}) option is turned on by default when
tar.texi(,4415) @command{tar} reads an archive from standard input, or from a remote
tar.texi(,4416) machine.  This is because on BSD Unix systems, attempting to read a
tar.texi(,4417) pipe returns however much happens to be in the pipe, even if it is
tar.texi(,4418) less than was requested.  If this option were not enabled, @command{tar}
tar.texi(,4419) would fail as soon as it read an incomplete record from the pipe.
tar.texi(,4420) 
tar.texi(,4421) If you're not sure of the blocking factor of an archive, you can
tar.texi(,4422) read the archive by specifying @option{--read-full-records} (@option{-B}) and
tar.texi(,4423) @option{--blocking-factor=@var{512-size}} (@option{-b
tar.texi(,4424) @var{512-size}}), using a blocking factor larger than what the archive
tar.texi(,4425) uses.  This lets you avoid having to determine the blocking factor
tar.texi(,4426) of an archive.  @xref{Blocking Factor}.
tar.texi(,4427) 
tar.texi(,4428) @menu
tar.texi(,4429) * read full records::
tar.texi(,4430) * Ignore Zeros::
tar.texi(,4431) @end menu
tar.texi(,4432) 
tar.texi(,4433) @node read full records
tar.texi(,4434) @unnumberedsubsubsec Reading Full Records
tar.texi(,4435) 
tar.texi(FIXME,4436) @allow-recursion
tar.texi(FIXME,4436) @quote-arg
tar.texi(FIXME,4436) 
tar.texi(,4437) 
tar.texi(,4438) @table @option
tar.texi(,4439) @opindex read-full-records
tar.texi(,4440) @item --read-full-records
tar.texi(,4441) @item -B
tar.texi(,4442) Use in conjunction with @option{--extract} (@option{--get},
tar.texi(,4443) @option{-x}) to read an archive which contains incomplete records, or
tar.texi(,4444) one which has a blocking factor less than the one specified.
tar.texi(,4445) @end table
tar.texi(,4446) 
tar.texi(,4447) @node Ignore Zeros
tar.texi(,4448) @unnumberedsubsubsec Ignoring Blocks of Zeros
tar.texi(,4449) 
tar.texi(,4450) @cindex End-of-archive blocks, ignoring
tar.texi(,4451) @cindex Ignoring end-of-archive blocks
tar.texi(,4452) @opindex ignore-zeros
tar.texi(,4453) Normally, @command{tar} stops reading when it encounters a block of zeros
tar.texi(,4454) between file entries (which usually indicates the end of the archive).
tar.texi(,4455) @option{--ignore-zeros} (@option{-i}) allows @command{tar} to
tar.texi(,4456) completely read an archive which contains a block of zeros before the
tar.texi(,4457) end (i.e., a damaged archive, or one that was created by concatenating
tar.texi(,4458) several archives together).
tar.texi(,4459) 
tar.texi(,4460) The @option{--ignore-zeros} (@option{-i}) option is turned off by default because many
tar.texi(,4461) versions of @command{tar} write garbage after the end-of-archive entry,
tar.texi(GNUTAR,4462) since that part of the media is never supposed to be read.  tar.texi(GNUTAR,4462) @acronym{GNU} @command{tar}
tar.texi(,4463) does not write after the end of an archive, but seeks to
tar.texi(,4464) maintain compatiblity among archiving utilities.
tar.texi(,4465) 
tar.texi(,4466) @table @option
tar.texi(,4467) @item --ignore-zeros
tar.texi(,4468) @itemx -i
tar.texi(,4469) To ignore blocks of zeros (i.e., end-of-archive entries) which may be
tar.texi(,4470) encountered while reading an archive.  Use in conjunction with
tar.texi(,4471) @option{--extract} or @option{--list}.
tar.texi(,4472) @end table
tar.texi(,4473) 
tar.texi(,4474) @node Writing
tar.texi(,4475) @subsection Changing How @command{tar} Writes Files
tar.texi(UNREVISED,4476) @quotation
tar.texi(UNREVISED,4476) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,4476) @end quotation
tar.texi(,4477) 
tar.texi(FIXME,4478) @allow-recursion
tar.texi(FIXME,4478) @quote-arg
tar.texi(FIXME,4478) 
tar.texi(,4479) 
tar.texi(,4480) @menu
tar.texi(,4481) * Dealing with Old Files::
tar.texi(,4482) * Overwrite Old Files::
tar.texi(,4483) * Keep Old Files::
tar.texi(,4484) * Keep Newer Files::
tar.texi(,4485) * Unlink First::
tar.texi(,4486) * Recursive Unlink::
tar.texi(,4487) * Data Modification Times::
tar.texi(,4488) * Setting Access Permissions::
tar.texi(,4489) * Directory Modification Times and Permissions::
tar.texi(,4490) * Writing to Standard Output::
tar.texi(,4491) * Writing to an External Program::
tar.texi(,4492) * remove files::
tar.texi(,4493) @end menu
tar.texi(,4494) 
tar.texi(,4495) @node Dealing with Old Files
tar.texi(,4496) @unnumberedsubsubsec Options Controlling the Overwriting of Existing Files
tar.texi(,4497) 
tar.texi(xopindex,4498) @opindex overwrite-dir@r{, introduced}
tar.texi(,4499) When extracting files, if @command{tar} discovers that the extracted
tar.texi(,4500) file already exists, it normally replaces the file by removing it before
tar.texi(,4501) extracting it, to prevent confusion in the presence of hard or symbolic
tar.texi(,4502) links.  (If the existing file is a symbolic link, it is removed, not
tar.texi(,4503) followed.)  However, if a directory cannot be removed because it is
tar.texi(,4504) nonempty, @command{tar} normally overwrites its metadata (ownership,
tar.texi(,4505) permission, etc.).  The @option{--overwrite-dir} option enables this
tar.texi(,4506) default behavior.  To be more cautious and preserve the metadata of
tar.texi(,4507) such a directory, use the @option{--no-overwrite-dir} option.
tar.texi(,4508) 
tar.texi(,4509) @cindex Overwriting old files, prevention
tar.texi(xopindex,4510) @opindex keep-old-files@r{, introduced}
tar.texi(,4511) To be even more cautious and prevent existing files from being replaced, use
tar.texi(,4512) the @option{--keep-old-files} (@option{-k}) option.  It causes @command{tar} to refuse
tar.texi(,4513) to replace or update a file that already exists, i.e., a file with the
tar.texi(,4514) same name as an archive member prevents extraction of that archive
tar.texi(,4515) member.  Instead, it reports an error.
tar.texi(,4516) 
tar.texi(xopindex,4517) @opindex overwrite@r{, introduced}
tar.texi(,4518) To be more aggressive about altering existing files, use the
tar.texi(,4519) @option{--overwrite} option.  It causes @command{tar} to overwrite
tar.texi(,4520) existing files and to follow existing symbolic links when extracting.
tar.texi(,4521) 
tar.texi(,4522) @cindex Protecting old files
tar.texi(GNUTAR,4523) Some people argue that tar.texi(GNUTAR,4523) @acronym{GNU} @command{tar} should not hesitate
tar.texi(,4524) to overwrite files with other files when extracting.  When extracting
tar.texi(,4525) a @command{tar} archive, they expect to see a faithful copy of the
tar.texi(,4526) state of the file system when the archive was created.  It is debatable
tar.texi(,4527) that this would always be a proper behavior.  For example, suppose one
tar.texi(,4528) has an archive in which @file{usr/local} is a link to
tar.texi(,4529) @file{usr/local2}.  Since then, maybe the site removed the link and
tar.texi(,4530) renamed the whole hierarchy from @file{/usr/local2} to
tar.texi(,4531) @file{/usr/local}.  Such things happen all the time.  I guess it would
tar.texi(GNUTAR,4532) not be welcome at all that tar.texi(GNUTAR,4532) @acronym{GNU} @command{tar} removes the
tar.texi(,4533) whole hierarchy just to make room for the link to be reinstated
tar.texi(,4534) (unless it @emph{also} simultaneously restores the full
tar.texi(GNUTAR,4535) @file{/usr/local2}, of course!)  tar.texi(GNUTAR,4535) @acronym{GNU} @command{tar} is indeed
tar.texi(,4536) able to remove a whole hierarchy to reestablish a symbolic link, for
tar.texi(,4537) example, but @emph{only if} @option{--recursive-unlink} is specified
tar.texi(,4538) to allow this behavior.  In any case, single files are silently
tar.texi(,4539) removed.
tar.texi(,4540) 
tar.texi(xopindex,4541) @opindex unlink-first@r{, introduced}
tar.texi(,4542) Finally, the @option{--unlink-first} (@option{-U}) option can improve performance in
tar.texi(,4543) some cases by causing @command{tar} to remove files unconditionally
tar.texi(,4544) before extracting them.
tar.texi(,4545) 
tar.texi(,4546) @node Overwrite Old Files
tar.texi(,4547) @unnumberedsubsubsec Overwrite Old Files
tar.texi(,4548) 
tar.texi(,4549) @table @option
tar.texi(,4550) @opindex overwrite
tar.texi(,4551) @item --overwrite
tar.texi(,4552) Overwrite existing files and directory metadata when extracting files
tar.texi(,4553) from an archive.
tar.texi(,4554) 
tar.texi(,4555) This causes @command{tar} to write extracted files into the file system without
tar.texi(,4556) regard to the files already on the system; i.e., files with the same
tar.texi(,4557) names as archive members are overwritten when the archive is extracted.
tar.texi(,4558) It also causes @command{tar} to extract the ownership, permissions,
tar.texi(,4559) and time stamps onto any preexisting files or directories.
tar.texi(,4560) If the name of a corresponding file name is a symbolic link, the file
tar.texi(,4561) pointed to by the symbolic link will be overwritten instead of the
tar.texi(,4562) symbolic link itself (if this is possible).  Moreover, special devices,
tar.texi(,4563) empty directories and even symbolic links are automatically removed if
tar.texi(,4564) they are in the way of extraction.
tar.texi(,4565) 
tar.texi(,4566) Be careful when using the @option{--overwrite} option, particularly when
tar.texi(,4567) combined with the @option{--absolute-names} (@option{-P}) option, as this combination
tar.texi(,4568) can change the contents, ownership or permissions of any file on your
tar.texi(,4569) system.  Also, many systems do not take kindly to overwriting files that
tar.texi(,4570) are currently being executed.
tar.texi(,4571) 
tar.texi(,4572) @opindex overwrite-dir
tar.texi(,4573) @item --overwrite-dir
tar.texi(,4574) Overwrite the metadata of directories when extracting files from an
tar.texi(,4575) archive, but remove other files before extracting.
tar.texi(,4576) @end table
tar.texi(,4577) 
tar.texi(,4578) @node Keep Old Files
tar.texi(,4579) @unnumberedsubsubsec Keep Old Files
tar.texi(,4580) 
tar.texi(,4581) @table @option
tar.texi(,4582) @opindex keep-old-files
tar.texi(,4583) @item --keep-old-files
tar.texi(,4584) @itemx -k
tar.texi(,4585) Do not replace existing files from archive.  The
tar.texi(,4586) @option{--keep-old-files} (@option{-k}) option prevents @command{tar}
tar.texi(,4587) from replacing existing files with files with the same name from the
tar.texi(,4588) archive. The @option{--keep-old-files} option is meaningless with
tar.texi(,4589) @option{--list} (@option{-t}).  Prevents @command{tar} from replacing
tar.texi(,4590) files in the file system during extraction.
tar.texi(,4591) @end table
tar.texi(,4592) 
tar.texi(,4593) @node Keep Newer Files
tar.texi(,4594) @unnumberedsubsubsec Keep Newer Files
tar.texi(,4595) 
tar.texi(,4596) @table @option
tar.texi(,4597) @opindex keep-newer-files
tar.texi(,4598) @item --keep-newer-files
tar.texi(,4599) Do not replace existing files that are newer than their archive
tar.texi(,4600) copies.  This option is meaningless with @option{--list} (@option{-t}).
tar.texi(,4601) @end table
tar.texi(,4602) 
tar.texi(,4603) @node Unlink First
tar.texi(,4604) @unnumberedsubsubsec Unlink First
tar.texi(,4605) 
tar.texi(,4606) @table @option
tar.texi(,4607) @opindex unlink-first
tar.texi(,4608) @item --unlink-first
tar.texi(,4609) @itemx -U
tar.texi(,4610) Remove files before extracting over them.
tar.texi(,4611) This can make @command{tar} run a bit faster if you know in advance
tar.texi(,4612) that the extracted files all need to be removed.  Normally this option
tar.texi(,4613) slows @command{tar} down slightly, so it is disabled by default.
tar.texi(,4614) @end table
tar.texi(,4615) 
tar.texi(,4616) @node Recursive Unlink
tar.texi(,4617) @unnumberedsubsubsec Recursive Unlink
tar.texi(,4618) 
tar.texi(,4619) @table @option
tar.texi(,4620) @opindex recursive-unlink
tar.texi(,4621) @item --recursive-unlink
tar.texi(,4622) When this option is specified, try removing files and directory hierarchies
tar.texi(,4623) before extracting over them.  @emph{This is a dangerous option!}
tar.texi(,4624) @end table
tar.texi(,4625) 
tar.texi(,4626) If you specify the @option{--recursive-unlink} option,
tar.texi(,4627) @command{tar} removes @emph{anything} that keeps you from extracting a file
tar.texi(,4628) as far as current permissions will allow it.  This could include removal
tar.texi(,4629) of the contents of a full directory hierarchy.
tar.texi(,4630) 
tar.texi(,4631) @node Data Modification Times
tar.texi(,4632) @unnumberedsubsubsec Setting Data Modification Times
tar.texi(,4633) 
tar.texi(,4634) @cindex Data modification times of extracted files
tar.texi(,4635) @cindex Modification times of extracted files
tar.texi(,4636) Normally, @command{tar} sets the data modification times of extracted
tar.texi(,4637) files to the corresponding times recorded for the files in the archive, but
tar.texi(,4638) limits the permissions of extracted files by the current @code{umask}
tar.texi(,4639) setting.
tar.texi(,4640) 
tar.texi(,4641) To set the data modification times of extracted files to the time when
tar.texi(,4642) the files were extracted, use the @option{--touch} (@option{-m}) option in
tar.texi(,4643) conjunction with @option{--extract} (@option{--get}, @option{-x}).
tar.texi(,4644) 
tar.texi(,4645) @table @option
tar.texi(,4646) @opindex touch
tar.texi(,4647) @item --touch
tar.texi(,4648) @itemx -m
tar.texi(,4649) Sets the data modification time of extracted archive members to the time
tar.texi(,4650) they were extracted, not the time recorded for them in the archive.
tar.texi(,4651) Use in conjunction with @option{--extract} (@option{--get}, @option{-x}).
tar.texi(,4652) @end table
tar.texi(,4653) 
tar.texi(,4654) @node Setting Access Permissions
tar.texi(,4655) @unnumberedsubsubsec Setting Access Permissions
tar.texi(,4656) 
tar.texi(,4657) @cindex Permissions of extracted files
tar.texi(,4658) @cindex Modes of extracted files
tar.texi(,4659) To set the modes (access permissions) of extracted files to those
tar.texi(,4660) recorded for those files in the archive, use @option{--same-permissions}
tar.texi(,4661) in conjunction with the @option{--extract} (@option{--get},
tar.texi(,4662) @option{-x}) operation.  
tar.texi(,4663) 
tar.texi(,4664) @table @option
tar.texi(,4665) @opindex preserve-permissions
tar.texi(,4666) @opindex same-permissions
tar.texi(,4667) @item --preserve-permissions
tar.texi(,4668) @itemx --same-permissions
tar.texi(,4669) @c @itemx --ignore-umask
tar.texi(,4670) @itemx -p
tar.texi(,4671) Set modes of extracted archive members to those recorded in the
tar.texi(,4672) archive, instead of current umask settings.  Use in conjunction with
tar.texi(,4673) @option{--extract} (@option{--get}, @option{-x}).
tar.texi(,4674) @end table
tar.texi(,4675) 
tar.texi(,4676) @node Directory Modification Times and Permissions
tar.texi(,4677) @unnumberedsubsubsec Directory Modification Times and Permissions
tar.texi(,4678) 
tar.texi(GNUTAR,4679) After sucessfully extracting a file member, tar.texi(GNUTAR,4679) @acronym{GNU} @command{tar} normally
tar.texi(,4680) restores its permissions and modification times, as described in the
tar.texi(,4681) previous sections.  This cannot be done for directories, because
tar.texi(,4682) after extracting a directory @command{tar} will almost certainly
tar.texi(,4683) extract files into that directory and this will cause the directory
tar.texi(,4684) modification time to be updated.  Moreover, restoring that directory
tar.texi(,4685) permissions may not permit file creation within it.  Thus, restoring
tar.texi(,4686) directory permissions and modification times must be delayed at least
tar.texi(GNUTAR,4687) until all files have been extracted into that directory.  tar.texi(GNUTAR,4687) @acronym{GNU} @command{tar}
tar.texi(,4688) restores directories using the following approach.
tar.texi(,4689) 
tar.texi(,4690) The extracted directories are created with the mode specified in the
tar.texi(,4691) archive, as modified by the umask of the user, which gives sufficient
tar.texi(,4692) permissions to allow file creation.  The meta-information about the
tar.texi(,4693) directory is recorded in the temporary list of directories.  When
tar.texi(GNUTAR,4694) preparing to extract next archive member, tar.texi(GNUTAR,4694) @acronym{GNU} @command{tar} checks if the
tar.texi(,4695) directory prefix of this file contains the remembered directory.  If
tar.texi(,4696) it does not, the program assumes that all files have been extracted
tar.texi(,4697) into that directory, restores its modification time and permissions
tar.texi(,4698) and removes its entry from the internal list.  This approach allows
tar.texi(,4699) to correctly restore directory meta-information in the majority of
tar.texi(,4700) cases, while keeping memory requirements sufficiently small.  It is
tar.texi(,4701) based on the fact, that most @command{tar} archives use the predefined
tar.texi(,4702) order of members: first the directory, then all the files and
tar.texi(,4703) subdirectories in that directory.
tar.texi(,4704) 
tar.texi(,4705) However, this is not always true.  The most important exception are
tar.texi(,4706) incremental archives (@pxref{Incremental Dumps}).  The member order in
tar.texi(,4707) an incremental archive is reversed: first all directory members are
tar.texi(,4708) stored, followed by other (non-directory) members.  So, when extracting
tar.texi(GNUTAR,4709) from incremental archives, tar.texi(GNUTAR,4709) @acronym{GNU} @command{tar} alters the above procedure.  It
tar.texi(,4710) remebers all restored directories, and restores their meta-data
tar.texi(,4711) only after the entire archive has been processed.  Notice, that you do
tar.texi(GNUTAR,4712) not need to specity any special options for that, as tar.texi(GNUTAR,4712) @acronym{GNU} @command{tar}
tar.texi(,4713) automatically detects archives in incremental format.
tar.texi(,4714) 
tar.texi(,4715) There may be cases, when such processing is required for normal archives
tar.texi(,4716) too.  Consider the following example:
tar.texi(,4717) 
tar.texi(,4718) @smallexample
tar.texi(,4719) @group
tar.texi(,4720) $ @kbd{tar --no-recursion -cvf archive \
tar.texi(,4721)     foo foo/file1 bar bar/file foo/file2}
tar.texi(,4722) foo/
tar.texi(,4723) foo/file1
tar.texi(,4724) bar/
tar.texi(,4725) bar/file
tar.texi(,4726) foo/file2
tar.texi(,4727) @end group
tar.texi(,4728) @end smallexample
tar.texi(,4729) 
tar.texi(,4730) During the normal operation, after encountering @file{bar}
tar.texi(GNUTAR,4731) @acronym{GNU} @command{tar} will assume that all files from the directory @file{foo}
tar.texi(,4732) were already extracted and will therefore restore its timestamp and
tar.texi(,4733) permission bits.  However, after extracting @file{foo/file2} the
tar.texi(,4734) directory timestamp will be offset again.
tar.texi(,4735) 
tar.texi(,4736) To correctly restore directory meta-information in such cases, use
tar.texi(,4737) @option{delay-directory-restore} command line option:
tar.texi(,4738) 
tar.texi(,4739) @table @option
tar.texi(,4740) @opindex delay-directory-restore
tar.texi(,4741) @item --delay-directory-restore
tar.texi(,4742) Delays restoring of the modification times and permissions of extracted
tar.texi(,4743) directories until the end of extraction.  This way, correct
tar.texi(,4744) meta-information is restored even if the archive has unusual member
tar.texi(,4745) ordering.
tar.texi(,4746) 
tar.texi(,4747) @opindex no-delay-directory-restore
tar.texi(,4748) @item --no-delay-directory-restore
tar.texi(,4749) Cancel the effect of the previous @option{--delay-directory-restore}.
tar.texi(,4750) Use this option if you have used @option{--delay-directory-restore} in
tar.texi(,4751) @env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to
tar.texi(,4752) temporarily disable it.
tar.texi(,4753) @end table
tar.texi(,4754) 
tar.texi(,4755) @node Writing to Standard Output
tar.texi(,4756) @unnumberedsubsubsec Writing to Standard Output
tar.texi(,4757) 
tar.texi(,4758) @cindex Writing extracted files to standard output
tar.texi(,4759) @cindex Standard output, writing extracted files to
tar.texi(,4760) To write the extracted files to the standard output, instead of
tar.texi(,4761) creating the files on the file system, use @option{--to-stdout} (@option{-O}) in
tar.texi(,4762) conjunction with @option{--extract} (@option{--get}, @option{-x}).  This option is useful if you are
tar.texi(,4763) extracting files to send them through a pipe, and do not need to
tar.texi(,4764) preserve them in the file system.  If you extract multiple members,
tar.texi(,4765) they appear on standard output concatenated, in the order they are
tar.texi(,4766) found in the archive.
tar.texi(,4767) 
tar.texi(,4768) @table @option
tar.texi(,4769) @opindex to-stdout
tar.texi(,4770) @item --to-stdout
tar.texi(,4771) @itemx -O
tar.texi(,4772) Writes files to the standard output.  Use only in conjunction with
tar.texi(,4773) @option{--extract} (@option{--get}, @option{-x}).  When this option is
tar.texi(,4774) used, instead of creating the files specified, @command{tar} writes
tar.texi(,4775) the contents of the files extracted to its standard output.  This may
tar.texi(,4776) be useful if you are only extracting the files in order to send them
tar.texi(,4777) through a pipe.  This option is meaningless with @option{--list}
tar.texi(,4778) (@option{-t}).
tar.texi(,4779) @end table
tar.texi(,4780) 
tar.texi(,4781) This can be useful, for example, if you have a tar archive containing
tar.texi(,4782) a big file and don't want to store the file on disk before processing
tar.texi(,4783) it.  You can use a command like this:
tar.texi(,4784) 
tar.texi(,4785) @smallexample
tar.texi(,4786) tar -xOzf foo.tgz bigfile | process
tar.texi(,4787) @end smallexample
tar.texi(,4788) 
tar.texi(,4789) or even like this if you want to process the concatenation of the files:
tar.texi(,4790) 
tar.texi(,4791) @smallexample
tar.texi(,4792) tar -xOzf foo.tgz bigfile1 bigfile2 | process
tar.texi(,4793) @end smallexample
tar.texi(,4794) 
tar.texi(,4795) Hovewer, @option{--to-command} may be more convenient for use with
tar.texi(,4796) multiple files. See the next section.
tar.texi(,4797) 
tar.texi(,4798) @node Writing to an External Program
tar.texi(,4799) @unnumberedsubsubsec Writing to an External Program
tar.texi(,4800) 
tar.texi(,4801) You can instruct @command{tar} to send the contents of each extracted
tar.texi(,4802) file to the standard input of an external program:
tar.texi(,4803) 
tar.texi(,4804) @table @option
tar.texi(,4805) @opindex to-command
tar.texi(,4806) @item --to-command=@var{command}
tar.texi(,4807) Extract files and pipe their contents to the standard input of
tar.texi(,4808) @var{command}. When this option is used, instead of creating the
tar.texi(,4809) files specified, @command{tar} invokes @var{command} and pipes the
tar.texi(,4810) contents of the files to its standard output. @var{Command} may
tar.texi(,4811) contain command line arguments. The program is executed via
tar.texi(,4812) @code{sh -c}. Notice, that @var{command} is executed once for each regular file
tar.texi(,4813) extracted. Non-regular files (directories, etc.) are ignored when this
tar.texi(,4814) option is used.
tar.texi(,4815) @end table
tar.texi(,4816) 
tar.texi(,4817) The command can obtain the information about the file it processes
tar.texi(,4818) from the following environment variables:
tar.texi(,4819) 
tar.texi(,4820) @table @var
tar.texi(,4821) @vrindex TAR_FILETYPE, to-command environment
tar.texi(,4822) @item TAR_FILETYPE
tar.texi(,4823) Type of the file. It is a single letter with the following meaning:
tar.texi(,4824) 
tar.texi(,4825) @multitable @columnfractions 0.10 0.90
tar.texi(,4826) @item f @tab Regular file
tar.texi(,4827) @item d @tab Directory
tar.texi(,4828) @item l @tab Symbolic link
tar.texi(,4829) @item h @tab Hard link
tar.texi(,4830) @item b @tab Block device
tar.texi(,4831) @item c @tab Character device
tar.texi(,4832) @end multitable
tar.texi(,4833) 
tar.texi(,4834) Currently only regular files are supported.
tar.texi(,4835) 
tar.texi(,4836) @vrindex TAR_MODE, to-command environment
tar.texi(,4837) @item TAR_MODE
tar.texi(,4838) File mode, an octal number.
tar.texi(,4839) 
tar.texi(,4840) @vrindex TAR_FILENAME, to-command environment
tar.texi(,4841) @item TAR_FILENAME
tar.texi(,4842) The name of the file.
tar.texi(,4843) 
tar.texi(,4844) @vrindex TAR_REALNAME, to-command environment
tar.texi(,4845) @item TAR_REALNAME
tar.texi(,4846) Name of the file as stored in the archive.
tar.texi(,4847) 
tar.texi(,4848) @vrindex TAR_UNAME, to-command environment
tar.texi(,4849) @item TAR_UNAME
tar.texi(,4850) Name of the file owner.
tar.texi(,4851) 
tar.texi(,4852) @vrindex TAR_GNAME, to-command environment
tar.texi(,4853) @item TAR_GNAME
tar.texi(,4854) Name of the file owner group.
tar.texi(,4855) 
tar.texi(,4856) @vrindex TAR_ATIME, to-command environment
tar.texi(,4857) @item TAR_ATIME
tar.texi(,4858) Time of last access. It is a decimal number, representing seconds
tar.texi(,4859) since the epoch.  If the archive provides times with nanosecond
tar.texi(,4860) precision, the nanoseconds are appended to the timestamp after a
tar.texi(,4861) decimal point.
tar.texi(,4862) 
tar.texi(,4863) @vrindex TAR_MTIME, to-command environment
tar.texi(,4864) @item TAR_MTIME
tar.texi(,4865) Time of last modification.
tar.texi(,4866) 
tar.texi(,4867) @vrindex TAR_CTIME, to-command environment
tar.texi(,4868) @item TAR_CTIME
tar.texi(,4869) Time of last status change.
tar.texi(,4870) 
tar.texi(,4871) @vrindex TAR_SIZE, to-command environment
tar.texi(,4872) @item TAR_SIZE
tar.texi(,4873) Size of the file.
tar.texi(,4874) 
tar.texi(,4875) @vrindex TAR_UID, to-command environment
tar.texi(,4876) @item TAR_UID
tar.texi(,4877) UID of the file owner.
tar.texi(,4878) 
tar.texi(,4879) @vrindex TAR_GID, to-command environment
tar.texi(,4880) @item TAR_GID
tar.texi(,4881) GID of the file owner.
tar.texi(,4882) @end table
tar.texi(,4883) 
tar.texi(,4884) In addition to these variables, @env{TAR_VERSION} contains the
tar.texi(GNUTAR,4885) @acronym{GNU} @command{tar} version number.
tar.texi(,4886) 
tar.texi(,4887) If @var{command} exits with a non-0 status, @command{tar} will print
tar.texi(,4888) an error message similar to the following:
tar.texi(,4889) 
tar.texi(,4890) @smallexample
tar.texi(,4891) tar: 2345: Child returned status 1
tar.texi(,4892) @end smallexample
tar.texi(,4893) 
tar.texi(,4894) Here, @samp{2345} is the PID of the finished process.
tar.texi(,4895) 
tar.texi(,4896) If this behavior is not wanted, use @option{--ignore-command-error}:
tar.texi(,4897) 
tar.texi(,4898) @table @option
tar.texi(,4899) @opindex ignore-command-error
tar.texi(,4900) @item --ignore-command-error
tar.texi(,4901) Ignore exit codes of subprocesses.  Notice that if the program
tar.texi(,4902) exits on signal or otherwise terminates abnormally, the error message
tar.texi(,4903) will be printed even if this option is used.
tar.texi(,4904) 
tar.texi(,4905) @opindex no-ignore-command-error
tar.texi(,4906) @item --no-ignore-command-error
tar.texi(,4907) Cancel the effect of any previous @option{--ignore-command-error}
tar.texi(,4908) option. This option is useful if you have set
tar.texi(,4909) @option{--ignore-command-error} in @env{TAR_OPTIONS}
tar.texi(,4910) (@pxref{TAR_OPTIONS}) and wish to temporarily cancel it.
tar.texi(,4911) @end table
tar.texi(,4912) 
tar.texi(,4913) @node remove files
tar.texi(,4914) @unnumberedsubsubsec Removing Files
tar.texi(,4915) 
tar.texi(FIXME,4917) @allow-recursion
tar.texi(FIXME,4917) @quote-arg
tar.texi(FIXME,4917) 
tar.texi(,4918) 
tar.texi(,4919) @table @option
tar.texi(,4920) @opindex remove-files
tar.texi(,4921) @item --remove-files
tar.texi(,4922) Remove files after adding them to the archive.
tar.texi(,4923) @end table
tar.texi(,4924) 
tar.texi(,4925) @node Scarce
tar.texi(,4926) @subsection Coping with Scarce Resources
tar.texi(UNREVISED,4927) @quotation
tar.texi(UNREVISED,4927) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,4927) @end quotation
tar.texi(,4928) 
tar.texi(,4929) @cindex Small memory
tar.texi(,4930) @cindex Running out of space
tar.texi(,4931) 
tar.texi(,4932) @menu
tar.texi(,4933) * Starting File::
tar.texi(,4934) * Same Order::
tar.texi(,4935) @end menu
tar.texi(,4936) 
tar.texi(,4937) @node Starting File
tar.texi(,4938) @unnumberedsubsubsec Starting File
tar.texi(,4939) 
tar.texi(,4940) @table @option
tar.texi(,4941) @opindex starting-file
tar.texi(,4942) @item --starting-file=@var{name}
tar.texi(,4943) @itemx -K @var{name}
tar.texi(,4944) Starts an operation in the middle of an archive.  Use in conjunction
tar.texi(,4945) with @option{--extract} (@option{--get}, @option{-x}) or @option{--list} (@option{-t}).
tar.texi(,4946) @end table
tar.texi(,4947) 
tar.texi(,4948) @cindex Middle of the archive, starting in the
tar.texi(,4949) If a previous attempt to extract files failed due to lack of disk
tar.texi(,4950) space, you can use @option{--starting-file=@var{name}} (@option{-K
tar.texi(,4951) @var{name}}) to start extracting only after member @var{name} of the
tar.texi(,4952) archive.  This assumes, of course, that there is now free space, or
tar.texi(,4953) that you are now extracting into a different file system.  (You could
tar.texi(,4954) also choose to suspend @command{tar}, remove unnecessary files from
tar.texi(,4955) the file system, and then restart the same @command{tar} operation.
tar.texi(,4956) In this case, @option{--starting-file} is not necessary.
tar.texi(,4957) @xref{Incremental Dumps}, @xref{interactive}, and @ref{exclude}.)
tar.texi(,4958) 
tar.texi(,4959) @node Same Order
tar.texi(,4960) @unnumberedsubsubsec Same Order
tar.texi(,4961) 
tar.texi(,4962) @table @option
tar.texi(,4963) @cindex Large lists of file names on small machines
tar.texi(,4964) @opindex same-order
tar.texi(,4965) @opindex preserve-order
tar.texi(,4966) @item --same-order
tar.texi(,4967) @itemx --preserve-order
tar.texi(,4968) @itemx -s
tar.texi(,4969) To process large lists of file names on machines with small amounts of
tar.texi(,4970) memory.  Use in conjunction with @option{--compare} (@option{--diff},
tar.texi(,4971) @option{-d}), @option{--list} (@option{-t}) or @option{--extract}
tar.texi(,4972) (@option{--get}, @option{-x}).
tar.texi(,4973) @end table
tar.texi(,4974) 
tar.texi(,4975) The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file
tar.texi(,4976) names to be listed or extracted is sorted in the same order as the
tar.texi(,4977) files in the archive.  This allows a large list of names to be used,
tar.texi(,4978) even on a small machine that would not otherwise be able to hold all
tar.texi(,4979) the names in memory at the same time.  Such a sorted list can easily be
tar.texi(,4980) created by running @samp{tar -t} on the archive and editing its output.
tar.texi(,4981) 
tar.texi(,4982) This option is probably never needed on modern computer systems.
tar.texi(,4983) 
tar.texi(,4984) @node backup
tar.texi(,4985) @section Backup options
tar.texi(,4986) 
tar.texi(,4987) @cindex backup options
tar.texi(,4988) 
tar.texi(GNUTAR,4989) @acronym{GNU} @command{tar} offers options for making backups of files
tar.texi(,4990) before writing new versions.  These options control the details of
tar.texi(,4991) these backups.  They may apply to the archive itself before it is
tar.texi(,4992) created or rewritten, as well as individual extracted members.  Other
tar.texi(,4993) @acronym{GNU} programs (@command{cp}, @command{install}, @command{ln},
tar.texi(,4994) and @command{mv}, for example) offer similar options.
tar.texi(,4995) 
tar.texi(,4996) Backup options may prove unexpectedly useful when extracting archives
tar.texi(,4997) containing many members having identical name, or when extracting archives
tar.texi(,4998) on systems having file name limitations, making different members appear
tar.texi(,4999) has having similar names through the side-effect of name truncation.
tar.texi(,5000) (This is true only if we have a good scheme for truncated backup names,
tar.texi(,5001) which I'm not sure at all: I suspect work is needed in this area.)
tar.texi(,5002) When any existing file is backed up before being overwritten by extraction,
tar.texi(,5003) then clashing files are automatically be renamed to be unique, and the
tar.texi(,5004) true name is kept for only the last file of a series of clashing files.
tar.texi(,5005) By using verbose mode, users may track exactly what happens.
tar.texi(,5006) 
tar.texi(,5007) At the detail level, some decisions are still experimental, and may
tar.texi(,5008) change in the future, we are waiting comments from our users.  So, please
tar.texi(,5009) do not learn to depend blindly on the details of the backup features.
tar.texi(,5010) For example, currently, directories themselves are never renamed through
tar.texi(,5011) using these options, so, extracting a file over a directory still has
tar.texi(,5012) good chances to fail.  Also, backup options apply to created archives,
tar.texi(,5013) not only to extracted members.  For created archives, backups will not
tar.texi(,5014) be attempted when the archive is a block or character device, or when it
tar.texi(,5015) refers to a remote file.
tar.texi(,5016) 
tar.texi(,5017) For the sake of simplicity and efficiency, backups are made by renaming old
tar.texi(,5018) files prior to creation or extraction, and not by copying.  The original
tar.texi(,5019) name is restored if the file creation fails.  If a failure occurs after a
tar.texi(,5020) partial extraction of a file, both the backup and the partially extracted
tar.texi(,5021) file are kept.
tar.texi(,5022) 
tar.texi(,5023) @table @samp
tar.texi(,5024) @item --backup[=@var{method}]
tar.texi(,5025) @opindex backup
tar.texi(,5026) @vindex VERSION_CONTROL
tar.texi(,5027) @cindex backups
tar.texi(,5028) Back up files that are about to be overwritten or removed.
tar.texi(,5029) Without this option, the original versions are destroyed.
tar.texi(,5030) 
tar.texi(,5031) Use @var{method} to determine the type of backups made.
tar.texi(,5032) If @var{method} is not specified, use the value of the @env{VERSION_CONTROL}
tar.texi(,5033) environment variable.  And if @env{VERSION_CONTROL} is not set,
tar.texi(,5034) use the @samp{existing} method.
tar.texi(,5035) 
tar.texi(,5036) @vindex version-control @r{Emacs variable}
tar.texi(,5037) This option corresponds to the Emacs variable @samp{version-control};
tar.texi(,5038) the same values for @var{method} are accepted as in Emacs.  This option
tar.texi(,5039) also allows more descriptive names.  The valid @var{method}s are:
tar.texi(,5040) 
tar.texi(,5041) @table @samp
tar.texi(,5042) @item t
tar.texi(,5043) @itemx numbered
tar.texi(,5044) @cindex numbered @r{backup method}
tar.texi(,5045) Always make numbered backups.
tar.texi(,5046) 
tar.texi(,5047) @item nil
tar.texi(,5048) @itemx existing
tar.texi(,5049) @cindex existing @r{backup method}
tar.texi(,5050) Make numbered backups of files that already have them, simple backups
tar.texi(,5051) of the others.
tar.texi(,5052) 
tar.texi(,5053) @item never
tar.texi(,5054) @itemx simple
tar.texi(,5055) @cindex simple @r{backup method}
tar.texi(,5056) Always make simple backups.
tar.texi(,5057) 
tar.texi(,5058) @end table
tar.texi(,5059) 
tar.texi(,5060) @item --suffix=@var{suffix}
tar.texi(,5061) @opindex suffix
tar.texi(,5062) @cindex backup suffix
tar.texi(,5063) @vindex SIMPLE_BACKUP_SUFFIX
tar.texi(,5064) Append @var{suffix} to each backup file made with @option{--backup}.  If this
tar.texi(,5065) option is not specified, the value of the @env{SIMPLE_BACKUP_SUFFIX}
tar.texi(,5066) environment variable is used.  And if @env{SIMPLE_BACKUP_SUFFIX} is not
tar.texi(,5067) set, the default is @samp{~}, just as in Emacs.
tar.texi(,5068) 
tar.texi(,5069) @end table
tar.texi(,5070) 
tar.texi(,5071) @node Applications
tar.texi(,5072) @section Notable @command{tar} Usages
tar.texi(UNREVISED,5073) @quotation
tar.texi(UNREVISED,5073) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,5073) @end quotation
tar.texi(,5074) 
tar.texi(FIXME,5077) @allow-recursion
tar.texi(FIXME,5077) @quote-arg
tar.texi(FIXME,5077) 
tar.texi(,5078) 
tar.texi(FIXME,5079) @allow-recursion
tar.texi(FIXME,5079) @quote-arg
tar.texi(FIXME,5079) 
tar.texi(,5080) 
tar.texi(,5081) @findex uuencode
tar.texi(,5082) You can easily use archive files to transport a group of files from
tar.texi(,5083) one system to another: put all relevant files into an archive on one
tar.texi(,5084) computer system, transfer the archive to another system, and extract
tar.texi(,5085) the contents there.  The basic transfer medium might be magnetic tape,
tar.texi(,5086) Internet FTP, or even electronic mail (though you must encode the
tar.texi(,5087) archive with @command{uuencode} in order to transport it properly by
tar.texi(,5088) mail).  Both machines do not have to use the same operating system, as
tar.texi(,5089) long as they both support the @command{tar} program.
tar.texi(,5090) 
tar.texi(,5091) For example, here is how you might copy a directory's contents from
tar.texi(,5092) one disk to another, while preserving the dates, modes, owners and
tar.texi(,5093) link-structure of all the files therein.  In this case, the transfer
tar.texi(,5094) medium is a @dfn{pipe}, which is one a Unix redirection mechanism:
tar.texi(,5095) 
tar.texi(,5096) @smallexample
tar.texi(,5097) $ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xf -)}
tar.texi(,5098) @end smallexample
tar.texi(,5099) 
tar.texi(,5100) @noindent
tar.texi(,5101) You can avoid subshells by using @option{-C} option:
tar.texi(,5102) 
tar.texi(,5103) @smallexample
tar.texi(,5104) $ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xf -}
tar.texi(,5105) @end smallexample
tar.texi(,5106) 
tar.texi(,5107) @noindent
tar.texi(,5108) The command also works using short option forms:
tar.texi(,5109) 
tar.texi(,5110) @smallexample
tar.texi(,5111) $ @kbd{(cd sourcedir; tar --create --file=- . ) \
tar.texi(,5112)        | (cd targetdir; tar --extract --file=-)}
tar.texi(,5113) # Or:
tar.texi(,5114) $ @kbd{tar --directory sourcedir --create --file=- . ) \
tar.texi(,5115)        | tar --directory targetdir --extract --file=-}
tar.texi(,5116) @end smallexample
tar.texi(,5117) 
tar.texi(,5118) @noindent
tar.texi(,5119) This is one of the easiest methods to transfer a @command{tar} archive.
tar.texi(,5120) 
tar.texi(,5121) @node looking ahead
tar.texi(,5122) @section Looking Ahead: The Rest of this Manual
tar.texi(,5123) 
tar.texi(,5124) You have now seen how to use all eight of the operations available to
tar.texi(,5125) @command{tar}, and a number of the possible options.  The next chapter
tar.texi(,5126) explains how to choose and change file and archive names, how to use
tar.texi(,5127) files to store names of other files which you can then call as
tar.texi(,5128) arguments to @command{tar} (this can help you save time if you expect to
tar.texi(,5129) archive the same list of files a number of times), and so forth.
tar.texi(FIXME,5133) @allow-recursion
tar.texi(FIXME,5133) @quote-arg
tar.texi(FIXME,5133) 
tar.texi(,5134) 
tar.texi(,5135) If there are too many files to conveniently list on the command line,
tar.texi(,5136) you can list the names in a file, and @command{tar} will read that file.
tar.texi(,5137) @xref{files}.
tar.texi(,5138) 
tar.texi(,5139) There are various ways of causing @command{tar} to skip over some files,
tar.texi(,5140) and not archive them.  @xref{Choosing}.
tar.texi(,5141) 
tar.texi(,5142) @node Backups
tar.texi(,5143) @chapter Performing Backups and Restoring Files
tar.texi(UNREVISED,5144) @quotation
tar.texi(UNREVISED,5144) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,5144) @end quotation
tar.texi(,5145) 
tar.texi(GNUTAR,5146) @acronym{GNU} @command{tar} is distributed along with the scripts
tar.texi(,5147) which the Free Software Foundation uses for performing backups.  There
tar.texi(,5148) is no corresponding scripts available yet for doing restoration of
tar.texi(,5149) files.  Even if there is a good chance those scripts may be satisfying
tar.texi(,5150) to you, they are not the only scripts or methods available for doing
tar.texi(,5151) backups and restore.  You may well create your own, or use more
tar.texi(,5152) sophisticated packages dedicated to that purpose.
tar.texi(,5153) 
tar.texi(,5154) Some users are enthusiastic about @code{Amanda} (The Advanced Maryland
tar.texi(,5155) Automatic Network Disk Archiver), a backup system developed by James
tar.texi(,5156) da Silva @file{jds@@cs.umd.edu} and available on many Unix systems.
tar.texi(,5157) This is free software, and it is available at these places:
tar.texi(,5158) 
tar.texi(,5159) @smallexample
tar.texi(,5160) http://www.cs.umd.edu/projects/amanda/amanda.html
tar.texi(,5161) ftp://ftp.cs.umd.edu/pub/amanda
tar.texi(,5162) @end smallexample
tar.texi(,5163) 
tar.texi(FIXME,5209) @allow-recursion
tar.texi(FIXME,5209) @quote-arg
tar.texi(FIXME,5209) 
tar.texi(,5210) 
tar.texi(,5211) This chapter documents both the provided shell scripts and @command{tar}
tar.texi(,5212) options which are more specific to usage as a backup tool.
tar.texi(,5213) 
tar.texi(,5214) To @dfn{back up} a file system means to create archives that contain
tar.texi(,5215) all the files in that file system.  Those archives can then be used to
tar.texi(,5216) restore any or all of those files (for instance if a disk crashes or a
tar.texi(,5217) file is accidentally deleted).  File system @dfn{backups} are also
tar.texi(,5218) called @dfn{dumps}.
tar.texi(,5219) 
tar.texi(,5220) @menu
tar.texi(,5221) * Full Dumps::                  Using @command{tar} to Perform Full Dumps
tar.texi(,5222) * Incremental Dumps::           Using @command{tar} to Perform Incremental Dumps
tar.texi(,5223) * Backup Levels::               Levels of Backups
tar.texi(,5224) * Backup Parameters::           Setting Parameters for Backups and Restoration
tar.texi(,5225) * Scripted Backups::            Using the Backup Scripts
tar.texi(,5226) * Scripted Restoration::        Using the Restore Script
tar.texi(,5227) @end menu
tar.texi(,5228) 
tar.texi(,5229) @node Full Dumps
tar.texi(,5230) @section Using @command{tar} to Perform Full Dumps
tar.texi(UNREVISED,5231) @quotation
tar.texi(UNREVISED,5231) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,5231) @end quotation
tar.texi(,5232) 
tar.texi(,5233) @cindex full dumps
tar.texi(,5234) @cindex dumps, full
tar.texi(,5235) 
tar.texi(,5236) @cindex corrupted archives
tar.texi(,5237) Full dumps should only be made when no other people or programs
tar.texi(,5238) are modifying files in the file system.  If files are modified while
tar.texi(,5239) @command{tar} is making the backup, they may not be stored properly in
tar.texi(,5240) the archive, in which case you won't be able to restore them if you
tar.texi(,5241) have to.  (Files not being modified are written with no trouble, and do
tar.texi(,5242) not corrupt the entire archive.)
tar.texi(,5243) 
tar.texi(,5244) You will want to use the @option{--label=@var{archive-label}}
tar.texi(,5245) (@option{-V @var{archive-label}}) option to give the archive a
tar.texi(,5246) volume label, so you can tell what this archive is even if the label
tar.texi(,5247) falls off the tape, or anything like that.
tar.texi(,5248) 
tar.texi(,5249) Unless the file system you are dumping is guaranteed to fit on
tar.texi(,5250) one volume, you will need to use the @option{--multi-volume} (@option{-M}) option.
tar.texi(,5251) Make sure you have enough tapes on hand to complete the backup.
tar.texi(,5252) 
tar.texi(,5253) If you want to dump each file system separately you will need to use
tar.texi(,5254) the @option{--one-file-system} option to prevent
tar.texi(,5255) @command{tar} from crossing file system boundaries when storing
tar.texi(,5256) (sub)directories.
tar.texi(,5257) 
tar.texi(,5258) The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
tar.texi(,5259) option is not needed, since this is a complete copy of everything in
tar.texi(,5260) the file system, and a full restore from this backup would only be
tar.texi(,5261) done onto a completely
tar.texi(,5262) empty disk.
tar.texi(,5263) 
tar.texi(,5264) Unless you are in a hurry, and trust the @command{tar} program (and your
tar.texi(,5265) tapes), it is a good idea to use the @option{--verify} (@option{-W})
tar.texi(,5266) option, to make sure your files really made it onto the dump properly.
tar.texi(,5267) This will also detect cases where the file was modified while (or just
tar.texi(,5268) after) it was being archived.  Not all media (notably cartridge tapes)
tar.texi(,5269) are capable of being verified, unfortunately.
tar.texi(,5270) 
tar.texi(,5271) @node Incremental Dumps
tar.texi(,5272) @section Using @command{tar} to Perform Incremental Dumps
tar.texi(,5273) 
tar.texi(GNUTAR,5274) @dfn{Incremental backup} is a special form of tar.texi(GNUTAR,5274) @acronym{GNU} @command{tar} archive that
tar.texi(,5275) stores additional metadata so that exact state of the file system
tar.texi(,5276) can be restored when extracting the archive.
tar.texi(,5277) 
tar.texi(GNUTAR,5278) @acronym{GNU} @command{tar} currently offers two options for handling incremental
tar.texi(,5279) backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g
tar.texi(,5280) @var{snapshot-file}}) and @option{--incremental} (@option{-G}).
tar.texi(,5281) 
tar.texi(,5282) @opindex listed-incremental
tar.texi(,5283) The option @option{--listed-incremental} instructs tar to operate on
tar.texi(,5284) an incremental archive with additional metadata stored in a standalone
tar.texi(,5285) file, called a @dfn{snapshot file}.  The purpose of this file is to help
tar.texi(,5286) determine which files have been changed, added or deleted since the
tar.texi(,5287) last backup, so that the next incremental backup will contain only
tar.texi(,5288) modified files.  The name of the snapshot file is given as an argument
tar.texi(,5289) to the option:
tar.texi(,5290) 
tar.texi(,5291) @table @option
tar.texi(,5292) @item --listed-incremental=@var{file}
tar.texi(,5293) @itemx -g @var{file}
tar.texi(,5294)   Handle incremental backups with snapshot data in @var{file}.
tar.texi(,5295) @end table
tar.texi(,5296) 
tar.texi(,5297) To create an incremental backup, you would use
tar.texi(,5298) @option{--listed-incremental} together with @option{--create}
tar.texi(,5299) (@pxref{create}).  For example:
tar.texi(,5300) 
tar.texi(,5301) @smallexample
tar.texi(,5302) $ @kbd{tar --create \
tar.texi(,5303)            --file=archive.1.tar \
tar.texi(,5304)            --listed-incremental=/var/log/usr.snar \
tar.texi(,5305)            /usr}
tar.texi(,5306) @end smallexample
tar.texi(,5307) 
tar.texi(,5308) This will create in @file{archive.1.tar} an incremental backup of
tar.texi(,5309) the @file{/usr} file system, storing additional metadata in the file
tar.texi(,5310) @file{/var/log/usr.snar}.  If this file does not exist, it will be
tar.texi(,5311) created.  The created archive will then be a @dfn{level 0 backup};
tar.texi(,5312) please see the next section for more on backup levels.
tar.texi(,5313) 
tar.texi(,5314) Otherwise, if the file @file{/var/log/usr.snar} exists, it
tar.texi(,5315) determines which files are modified.  In this case only these files will be
tar.texi(,5316) stored in the archive.  Suppose, for example, that after running the
tar.texi(,5317) above command, you delete file @file{/usr/doc/old} and create
tar.texi(,5318) directory @file{/usr/local/db} with the following contents:
tar.texi(,5319) 
tar.texi(,5320) @smallexample
tar.texi(,5321) $ @kbd{ls /usr/local/db}
tar.texi(,5322) /usr/local/db/data
tar.texi(,5323) /usr/local/db/index
tar.texi(,5324) @end smallexample
tar.texi(,5325) 
tar.texi(,5326) Some time later you create another incremental backup.  You will
tar.texi(,5327) then see:
tar.texi(,5328) 
tar.texi(,5329) @smallexample
tar.texi(,5330) $ @kbd{tar --create \
tar.texi(,5331)            --file=archive.2.tar \
tar.texi(,5332)            --listed-incremental=/var/log/usr.snar \
tar.texi(,5333)            /usr}
tar.texi(,5334) tar: usr/local/db: Directory is new
tar.texi(,5335) usr/local/db/
tar.texi(,5336) usr/local/db/data
tar.texi(,5337) usr/local/db/index
tar.texi(,5338) @end smallexample
tar.texi(,5339) 
tar.texi(,5340) @noindent
tar.texi(,5341) The created archive @file{archive.2.tar} will contain only these
tar.texi(,5342) three members.  This archive is called a @dfn{level 1 backup}.  Notice
tar.texi(,5343) that @file{/var/log/usr.snar} will be updated with the new data, so if
tar.texi(,5344) you plan to create more @samp{level 1} backups, it is necessary to
tar.texi(,5345) create a working copy of the snapshot file before running
tar.texi(,5346) @command{tar}.  The above example will then be modified as follows:
tar.texi(,5347) 
tar.texi(,5348) @smallexample
tar.texi(,5349) $ @kbd{cp /var/log/usr.snar /var/log/usr.snar-1}
tar.texi(,5350) $ @kbd{tar --create \
tar.texi(,5351)            --file=archive.2.tar \
tar.texi(,5352)            --listed-incremental=/var/log/usr.snar-1 \
tar.texi(,5353)            /usr}
tar.texi(,5354) @end smallexample
tar.texi(,5355) 
tar.texi(,5356) Incremental dumps depend crucially on time stamps, so the results are
tar.texi(,5357) unreliable if you modify a file's time stamps during dumping (e.g.,
tar.texi(,5358) with the @option{--atime-preserve=replace} option), or if you set the clock
tar.texi(,5359) backwards.
tar.texi(,5360) 
tar.texi(,5361) Metadata stored in snapshot files include device numbers, which,
tar.texi(,5362) obviously is supposed to be a non-volatile value.  However, it turns
tar.texi(,5363) out that NFS devices have undependable values when an automounter
tar.texi(,5364) gets in the picture.  This can lead to a great deal of spurious
tar.texi(,5365) redumping in incremental dumps, so it is somewhat useless to compare
tar.texi(,5366) two NFS devices numbers over time.  The solution implemented currently
tar.texi(,5367) is to considers all NFS devices as being equal when it comes to
tar.texi(,5368) comparing directories; this is fairly gross, but there does not seem
tar.texi(,5369) to be a better way to go.
tar.texi(,5370) 
tar.texi(,5371) Note that incremental archives use @command{tar} extensions and may
tar.texi(,5372) not be readable by non-@acronym{GNU} versions of the @command{tar} program.
tar.texi(,5373) 
tar.texi(xopindex,5374) @opindex listed-incremental@r{, using with @option{--extract}}
tar.texi(xopindex,5375) @opindex extract@r{, using with @option{--listed-incremental}}
tar.texi(,5376) To extract from the incremental dumps, use
tar.texi(,5377) @option{--listed-incremental} together with @option{--extract}
tar.texi(,5378) option (@pxref{extracting files}).  In this case, @command{tar} does
tar.texi(,5379) not need to access snapshot file, since all the data necessary for
tar.texi(,5380) extraction are stored in the archive itself.  So, when extracting, you
tar.texi(,5381) can give whatever argument to @option{--listed-incremental}, the usual
tar.texi(,5382) practice is to use @option{--listed-incremental=/dev/null}.
tar.texi(,5383) Alternatively, you can use @option{--incremental}, which needs no
tar.texi(,5384) arguments.  In general, @option{--incremental} (@option{-G}) can be
tar.texi(,5385) used as a shortcut for @option{--listed-incremental} when listing or
tar.texi(,5386) extracting incremental backups (for more information, regarding this
tar.texi(,5387) option, @pxref{incremental-op}).
tar.texi(,5388) 
tar.texi(GNUTAR,5389) When extracting from the incremental backup tar.texi(GNUTAR,5389) @acronym{GNU} @command{tar} attempts to
tar.texi(,5390) restore the exact state the file system had when the archive was
tar.texi(,5391) created.  In particular, it will @emph{delete} those files in the file
tar.texi(,5392) system that did not exist in their directories when the archive was
tar.texi(,5393) created.  If you have created several levels of incremental files,
tar.texi(,5394) then in order to restore the exact contents the file system  had when
tar.texi(,5395) the last level was created, you will need to restore from all backups
tar.texi(,5396) in turn.  Continuing our example, to restore the state of @file{/usr}
tar.texi(,5397) file system, one would do@footnote{Notice, that since both archives
tar.texi(,5398) were created withouth @option{-P} option (@pxref{absolute}), these
tar.texi(,5399) commands should be run from the root file system.}:
tar.texi(,5400) 
tar.texi(,5401) @smallexample
tar.texi(,5402) $ @kbd{tar --extract \
tar.texi(,5403)            --listed-incremental=/dev/null \
tar.texi(,5404)            --file archive.1.tar}
tar.texi(,5405) $ @kbd{tar --extract \
tar.texi(,5406)            --listed-incremental=/dev/null \
tar.texi(,5407)            --file archive.2.tar}
tar.texi(,5408) @end smallexample
tar.texi(,5409) 
tar.texi(,5410) To list the contents of an incremental archive, use @option{--list}
tar.texi(,5411) (@pxref{list}), as usual.  To obtain more information about the
tar.texi(,5412) archive, use @option{--listed-incremental} or @option{--incremental}
tar.texi(,5413) combined with two @option{--verbose} options@footnote{Two
tar.texi(,5414) @option{--verbose} options were selected to avoid breaking usual
tar.texi(,5415) verbose listing output (@option{--list --verbose}) when using in
tar.texi(,5416) scripts.
tar.texi(,5417) 
tar.texi(xopindex,5418) @opindex incremental@r{, using with @option{--list}}
tar.texi(xopindex,5419) @opindex listed-incremental@r{, using with @option{--list}}
tar.texi(xopindex,5420) @opindex list@r{, using with @option{--incremental}}
tar.texi(xopindex,5421) @opindex list@r{, using with @option{--listed-incremental}}
tar.texi(GNUTAR,5422) Versions of @acronym{GNU} @command{tar} up to 1.15.1 used to dump verbatim binary
tar.texi(,5423) contents of the DUMPDIR header (with terminating nulls) when
tar.texi(,5424) @option{--incremental} or @option{--listed-incremental} option was
tar.texi(,5425) given, no matter what the verbosity level.  This behavior, and,
tar.texi(,5426) especially, the binary output it produced were considered incovenient
tar.texi(,5427) and were changed in version 1.16}:
tar.texi(,5428) 
tar.texi(,5429) @smallexample
tar.texi(,5430) @kbd{tar --list --incremental --verbose --verbose archive.tar}
tar.texi(,5431) @end smallexample
tar.texi(,5432) 
tar.texi(,5433) This command will print, for each directory in the archive, the list
tar.texi(,5434) of files in that directory at the time the archive was created.  This
tar.texi(,5435) information is put out in a format which is both human-readable and
tar.texi(,5436) unambiguous for a program: each file name is printed as
tar.texi(,5437) 
tar.texi(,5438) @smallexample
tar.texi(,5439) @var{x} @var{file}
tar.texi(,5440) @end smallexample
tar.texi(,5441) 
tar.texi(,5442) @noindent
tar.texi(,5443) where @var{x} is a letter describing the status of the file: @samp{Y}
tar.texi(,5444) if the file  is present in the archive, @samp{N} if the file is not
tar.texi(,5445) included in the archive, or a @samp{D} if the file is a directory (and
tar.texi(,5446) is included in the archive).  @xref{Dumpdir}, for the detailed
tar.texi(,5447) description of dumpdirs and status codes.  Each such
tar.texi(,5448) line is terminated by a newline character.  The last line is followed
tar.texi(,5449) by an additional newline to indicate the end of the data.
tar.texi(,5450) 
tar.texi(,5451) @anchor{incremental-op}The option @option{--incremental} (@option{-G})
tar.texi(,5452) gives the same behavior as @option{--listed-incremental} when used
tar.texi(,5453) with @option{--list} and @option{--extract} options.  When used with
tar.texi(,5454) @option{--create} option, it creates an incremental archive without
tar.texi(,5455) creating snapshot file.  Thus, it is impossible to create several
tar.texi(,5456) levels of incremental backups with @option{--incremental} option.
tar.texi(,5457) 
tar.texi(,5458) @node Backup Levels
tar.texi(,5459) @section Levels of Backups
tar.texi(,5460) 
tar.texi(,5461) An archive containing all the files in the file system is called a
tar.texi(,5462) @dfn{full backup} or @dfn{full dump}.  You could insure your data by
tar.texi(,5463) creating a full dump every day.  This strategy, however, would waste a
tar.texi(,5464) substantial amount of archive media and user time, as unchanged files
tar.texi(,5465) are daily re-archived.
tar.texi(,5466) 
tar.texi(,5467) It is more efficient to do a full dump only occasionally.  To back up
tar.texi(,5468) files between full dumps, you can use @dfn{incremental dumps}.  A @dfn{level
tar.texi(,5469) one} dump archives all the files that have changed since the last full
tar.texi(,5470) dump.
tar.texi(,5471) 
tar.texi(,5472) A typical dump strategy would be to perform a full dump once a week,
tar.texi(,5473) and a level one dump once a day.  This means some versions of files
tar.texi(,5474) will in fact be archived more than once, but this dump strategy makes
tar.texi(,5475) it possible to restore a file system to within one day of accuracy by
tar.texi(,5476) only extracting two archives---the last weekly (full) dump and the
tar.texi(,5477) last daily (level one) dump.  The only information lost would be in
tar.texi(,5478) files changed or created since the last daily backup.  (Doing dumps
tar.texi(,5479) more than once a day is usually not worth the trouble).
tar.texi(,5480) 
tar.texi(GNUTAR,5481) @acronym{GNU} @command{tar} comes with scripts you can use to do full
tar.texi(,5482) and level-one (actually, even level-two and so on) dumps.  Using
tar.texi(,5483) scripts (shell programs) to perform backups and restoration is a
tar.texi(,5484) convenient and reliable alternative to typing out file name lists
tar.texi(,5485) and @command{tar} commands by hand.
tar.texi(,5486) 
tar.texi(,5487) Before you use these scripts, you need to edit the file
tar.texi(,5488) @file{backup-specs}, which specifies parameters used by the backup
tar.texi(,5489) scripts and by the restore script.  This file is usually located
tar.texi(,5490) in @file{/etc/backup} directory.  @xref{Backup Parameters}, for its
tar.texi(,5491) detailed description.  Once the backup parameters are set, you can
tar.texi(,5492) perform backups or restoration by running the appropriate script.
tar.texi(,5493) 
tar.texi(,5494) The name of the backup script is @code{backup}.  The name of the
tar.texi(,5495) restore script is @code{restore}.  The following sections describe
tar.texi(,5496) their use in detail.
tar.texi(,5497) 
tar.texi(,5498) @emph{Please Note:} The backup and restoration scripts are
tar.texi(,5499) designed to be used together.  While it is possible to restore files by
tar.texi(,5500) hand from an archive which was created using a backup script, and to create
tar.texi(,5501) an archive by hand which could then be extracted using the restore script,
tar.texi(,5502) it is easier to use the scripts.  @xref{Incremental Dumps}, before
tar.texi(,5503) making such an attempt.
tar.texi(,5504) 
tar.texi(,5505) @node Backup Parameters
tar.texi(,5506) @section Setting Parameters for Backups and Restoration
tar.texi(,5507) 
tar.texi(,5508) The file @file{backup-specs} specifies backup parameters for the
tar.texi(,5509) backup and restoration scripts provided with @command{tar}.  You must
tar.texi(,5510) edit @file{backup-specs} to fit your system configuration and schedule
tar.texi(,5511) before using these scripts.
tar.texi(,5512) 
tar.texi(,5513) Syntactically, @file{backup-specs} is a shell script, containing
tar.texi(,5514) mainly variable assignments.  However, any valid shell construct
tar.texi(,5515) is allowed in this file.  Particularly, you may wish to define
tar.texi(,5516) functions within that script (e.g., see @code{RESTORE_BEGIN} below).
tar.texi(,5517) For more information about shell script syntax, please refer to
tar.texi(,5518) @url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
tar.texi(,5519) g_02, the definition of the Shell Command Language}.  See also
tar.texi(,5520) @ref{Top,,Bash Features,bashref,Bash Reference Manual}.
tar.texi(,5521) 
tar.texi(,5522) The shell variables controlling behavior of @code{backup} and
tar.texi(,5523) @code{restore} are described in the following subsections.
tar.texi(,5524) 
tar.texi(,5525) @menu
tar.texi(,5526) * General-Purpose Variables::
tar.texi(,5527) * Magnetic Tape Control::
tar.texi(,5528) * User Hooks::
tar.texi(,5529) * backup-specs example::        An Example Text of @file{Backup-specs}
tar.texi(,5530) @end menu
tar.texi(,5531) 
tar.texi(,5532) @node General-Purpose Variables
tar.texi(,5533) @subsection General-Purpose Variables
tar.texi(,5534) 
tar.texi(,5535) @defvr {Backup variable} ADMINISTRATOR
tar.texi(,5536) The user name of the backup administrator.  @code{Backup} scripts
tar.texi(,5537) sends a backup report to this address.
tar.texi(,5538) @end defvr
tar.texi(,5539) 
tar.texi(,5540) @defvr {Backup variable} BACKUP_HOUR
tar.texi(,5541) The hour at which the backups are done.  This can be a number from 0
tar.texi(,5542) to 23, or the time specification in form @var{hours}:@var{minutes},
tar.texi(,5543) or the string @samp{now}.
tar.texi(,5544) 
tar.texi(,5545) This variable is used by @code{backup}.  Its value may be overridden
tar.texi(,5546) using @option{--time} option (@pxref{Scripted Backups}).
tar.texi(,5547) @end defvr
tar.texi(,5548) 
tar.texi(,5549) @defvr {Backup variable} TAPE_FILE
tar.texi(,5550) 
tar.texi(,5551) The device @command{tar} writes the archive to.  If @var{TAPE_FILE}
tar.texi(,5552) is a remote archive (@pxref{remote-dev}), backup script will suppose
tar.texi(,5553) that your @command{mt} is able to access remote devices.  If @var{RSH}
tar.texi(,5554) (@pxref{RSH}) is set, @option{--rsh-command} option will be added to
tar.texi(,5555) invocations of @command{mt}.
tar.texi(,5556) @end defvr
tar.texi(,5557) 
tar.texi(,5558) @defvr {Backup variable} BLOCKING
tar.texi(,5559) 
tar.texi(,5560) The blocking factor @command{tar} will use when writing the dump archive.
tar.texi(,5561) @xref{Blocking Factor}.
tar.texi(,5562) @end defvr
tar.texi(,5563) 
tar.texi(,5564) @defvr {Backup variable} BACKUP_DIRS
tar.texi(,5565) 
tar.texi(,5566) A list of file systems to be dumped (for @code{backup}), or restored
tar.texi(,5567) (for @code{restore}).  You can include any directory
tar.texi(,5568) name in the list --- subdirectories on that file system will be
tar.texi(,5569) included, regardless of how they may look to other networked machines.
tar.texi(,5570) Subdirectories on other file systems will be ignored.
tar.texi(,5571) 
tar.texi(,5572) The host name specifies which host to run @command{tar} on, and should
tar.texi(,5573) normally be the host that actually contains the file system.  However,
tar.texi(GNUTAR,5574) the host machine must have tar.texi(GNUTAR,5574) @acronym{GNU} @command{tar} installed, and
tar.texi(,5575) must be able to access the directory containing the backup scripts and
tar.texi(,5576) their support files using the same file name that is used on the
tar.texi(,5577) machine where the scripts are run (i.e.  what @command{pwd} will print
tar.texi(,5578) when in that directory on that machine).  If the host that contains
tar.texi(,5579) the file system does not have this capability, you can specify another
tar.texi(,5580) host as long as it can access the file system through NFS.
tar.texi(,5581) 
tar.texi(,5582) If the list of file systems is very long you may wish to put it
tar.texi(,5583) in a separate file.  This file is usually named
tar.texi(,5584) @file{/etc/backup/dirs}, but this name may be overridden in
tar.texi(,5585) @file{backup-specs} using @code{DIRLIST} variable.
tar.texi(,5586) @end defvr
tar.texi(,5587) 
tar.texi(,5588) @defvr {Backup variable} DIRLIST
tar.texi(,5589) 
tar.texi(,5590) A path to the file containing the list of the file systems to backup
tar.texi(,5591) or restore.  By default it is @file{/etc/backup/dirs}.
tar.texi(,5592) @end defvr
tar.texi(,5593) 
tar.texi(,5594) @defvr {Backup variable} BACKUP_FILES
tar.texi(,5595) 
tar.texi(,5596) A list of individual files to be dumped (for @code{backup}), or restored
tar.texi(,5597) (for @code{restore}).  These should be accessible from the machine on
tar.texi(,5598) which the backup script is run.
tar.texi(,5599) 
tar.texi(,5600) If the list of file systems is very long you may wish to store it
tar.texi(,5601) in a separate file.  This file is usually named
tar.texi(,5602) @file{/etc/backup/files}, but this name may be overridden in
tar.texi(,5603) @file{backup-specs} using @code{FILELIST} variable.
tar.texi(,5604) @end defvr
tar.texi(,5605) 
tar.texi(,5606) @defvr {Backup variable} FILELIST
tar.texi(,5607) 
tar.texi(,5608) A path to the file containing the list of the individual files to backup
tar.texi(,5609) or restore.  By default it is @file{/etc/backup/files}.
tar.texi(,5610) @end defvr
tar.texi(,5611) 
tar.texi(,5612) @defvr {Backup variable} MT
tar.texi(,5613) 
tar.texi(,5614) Full file name of @command{mt} binary.
tar.texi(,5615) @end defvr
tar.texi(,5616) 
tar.texi(,5617) @defvr {Backup variable} RSH
tar.texi(,5618) @anchor{RSH}
tar.texi(,5619) Full file name of @command{rsh} binary or its equivalent.  You may wish to
tar.texi(,5620) set it to @code{ssh}, to improve security.  In this case you will have
tar.texi(,5621) to use public key authentication.
tar.texi(,5622) @end defvr
tar.texi(,5623) 
tar.texi(,5624) @defvr {Backup variable} RSH_COMMAND
tar.texi(,5625) 
tar.texi(,5626) Full file name of @command{rsh} binary on remote mashines.  This will
tar.texi(,5627) be passed via @option{--rsh-command} option to the remote invocation
tar.texi(GNUTAR,5628) of tar.texi(GNUTAR,5628) @acronym{GNU} @command{tar}.
tar.texi(,5629) @end defvr
tar.texi(,5630) 
tar.texi(,5631) @defvr {Backup variable} VOLNO_FILE
tar.texi(,5632) 
tar.texi(,5633) Name of temporary file to hold volume numbers.  This needs to be accessible
tar.texi(,5634) by all the machines which have file systems to be dumped.
tar.texi(,5635) @end defvr
tar.texi(,5636) 
tar.texi(,5637) @defvr {Backup variable} XLIST
tar.texi(,5638) 
tar.texi(,5639) Name of @dfn{exclude file list}.  An @dfn{exclude file list} is a file
tar.texi(,5640) located on the remote machine and containing the list of files to
tar.texi(,5641) be excluded from the backup.  Exclude file lists are searched in
tar.texi(,5642) /etc/tar-backup directory.  A common use for exclude file lists
tar.texi(,5643) is to exclude files containing security-sensitive information
tar.texi(,5644) (e.g., @file{/etc/shadow} from backups).
tar.texi(,5645) 
tar.texi(,5646) This variable affects only @code{backup}.
tar.texi(,5647) @end defvr
tar.texi(,5648) 
tar.texi(,5649) @defvr {Backup variable} SLEEP_TIME
tar.texi(,5650) 
tar.texi(,5651) Time to sleep between dumps of any two successive file systems
tar.texi(,5652) 
tar.texi(,5653) This variable affects only @code{backup}.
tar.texi(,5654) @end defvr
tar.texi(,5655) 
tar.texi(,5656) @defvr {Backup variable} DUMP_REMIND_SCRIPT
tar.texi(,5657) 
tar.texi(,5658) Script to be run when it's time to insert a new tape in for the next
tar.texi(,5659) volume.  Administrators may want to tailor this script for their site.
tar.texi(GNUTAR,5660) If this variable isn't set, tar.texi(GNUTAR,5660) @acronym{GNU} @command{tar} will display its built-in
tar.texi(,5661) prompt, and will expect confirmation from the console.  For the
tar.texi(,5662) description of the default prompt, see @ref{change volume prompt}.
tar.texi(,5663) 
tar.texi(,5664) @end defvr
tar.texi(,5665) 
tar.texi(,5666) @defvr {Backup variable} SLEEP_MESSAGE
tar.texi(,5667) 
tar.texi(,5668) Message to display on the terminal while waiting for dump time.  Usually
tar.texi(,5669) this will just be some literal text.
tar.texi(,5670) @end defvr
tar.texi(,5671) 
tar.texi(,5672) @defvr {Backup variable} TAR
tar.texi(,5673) 
tar.texi(GNUTAR,5674) Full file name of the tar.texi(GNUTAR,5674) @acronym{GNU} @command{tar} executable.  If this is not set, backup
tar.texi(,5675) scripts will search @command{tar} in the current shell path.
tar.texi(,5676) @end defvr
tar.texi(,5677) 
tar.texi(,5678) @node Magnetic Tape Control
tar.texi(,5679) @subsection Magnetic Tape Control
tar.texi(,5680) 
tar.texi(,5681) Backup scripts access tape device using special @dfn{hook functions}.
tar.texi(,5682) These functions take a single argument -- the name of the tape
tar.texi(,5683) device.  Their names are kept in the following variables:
tar.texi(,5684) 
tar.texi(,5685) @defvr {Backup variable} MT_BEGIN
tar.texi(,5686) The name of @dfn{begin} function.  This function is called before
tar.texi(,5687) accessing the drive.  By default it retensions the tape:
tar.texi(,5688) 
tar.texi(,5689) @smallexample
tar.texi(,5690) MT_BEGIN=mt_begin
tar.texi(,5691) 
tar.texi(,5692) mt_begin() @{
tar.texi(,5693)     mt -f "$1" retension
tar.texi(,5694) @}
tar.texi(,5695) @end smallexample
tar.texi(,5696) @end defvr
tar.texi(,5697) 
tar.texi(,5698) @defvr {Backup variable} MT_REWIND
tar.texi(,5699) The name of @dfn{rewind} function.  The default definition is as
tar.texi(,5700) follows:
tar.texi(,5701) 
tar.texi(,5702) @smallexample
tar.texi(,5703) MT_REWIND=mt_rewind
tar.texi(,5704) 
tar.texi(,5705) mt_rewind() @{
tar.texi(,5706)     mt -f "$1" rewind
tar.texi(,5707) @}
tar.texi(,5708) @end smallexample
tar.texi(,5709) 
tar.texi(,5710) @end defvr
tar.texi(,5711) 
tar.texi(,5712) @defvr {Backup variable} MT_OFFLINE
tar.texi(,5713) The name of the function switching the tape off line.  By default
tar.texi(,5714) it is defined as follows:
tar.texi(,5715) 
tar.texi(,5716) @smallexample
tar.texi(,5717) MT_OFFLINE=mt_offline
tar.texi(,5718) 
tar.texi(,5719) mt_offline() @{
tar.texi(,5720)     mt -f "$1" offl
tar.texi(,5721) @}
tar.texi(,5722) @end smallexample
tar.texi(,5723) @end defvr
tar.texi(,5724) 
tar.texi(,5725) @defvr {Backup variable} MT_STATUS
tar.texi(,5726) The name of the function used to obtain the status of the archive device,
tar.texi(,5727) including error count.  Default definition:
tar.texi(,5728) 
tar.texi(,5729) @smallexample
tar.texi(,5730) MT_STATUS=mt_status
tar.texi(,5731) 
tar.texi(,5732) mt_status() @{
tar.texi(,5733)     mt -f "$1" status
tar.texi(,5734) @}
tar.texi(,5735) @end smallexample
tar.texi(,5736) @end defvr
tar.texi(,5737) 
tar.texi(,5738) @node User Hooks
tar.texi(,5739) @subsection User Hooks
tar.texi(,5740) 
tar.texi(,5741) @dfn{User hooks} are shell functions executed before and after
tar.texi(,5742) each @command{tar} invocation.  Thus, there are @dfn{backup
tar.texi(,5743) hooks}, which are executed before and after dumping each file
tar.texi(,5744) system, and @dfn{restore hooks}, executed before and
tar.texi(,5745) after restoring a file system.  Each user hook is a shell function
tar.texi(,5746) taking four arguments:
tar.texi(,5747) 
tar.texi(,5748) @deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname}
tar.texi(,5749) Its arguments are:
tar.texi(,5750) 
tar.texi(,5751) @table @var
tar.texi(,5752) @item level
tar.texi(,5753) Current backup or restore level.
tar.texi(,5754) 
tar.texi(,5755) @item host
tar.texi(,5756) Name or IP address of the host machine being dumped or restored.
tar.texi(,5757) 
tar.texi(,5758) @item fs
tar.texi(,5759) Full path name to the file system being dumped or restored.
tar.texi(,5760) 
tar.texi(,5761) @item fsname
tar.texi(,5762) File system name with directory separators replaced with colons.  This
tar.texi(,5763) is useful, e.g., for creating unique files.
tar.texi(,5764) @end table
tar.texi(,5765) @end deffn
tar.texi(,5766) 
tar.texi(,5767) Following variables keep the names of user hook functions
tar.texi(,5768) 
tar.texi(,5769) @defvr {Backup variable} DUMP_BEGIN
tar.texi(,5770) Dump begin function.  It is executed before dumping the file system.
tar.texi(,5771) @end defvr
tar.texi(,5772) 
tar.texi(,5773) @defvr {Backup variable} DUMP_END
tar.texi(,5774) Executed after dumping the file system.
tar.texi(,5775) @end defvr
tar.texi(,5776) 
tar.texi(,5777) @defvr {Backup variable} RESTORE_BEGIN
tar.texi(,5778) Executed before restoring the file system.
tar.texi(,5779) @end defvr
tar.texi(,5780) 
tar.texi(,5781) @defvr {Backup variable} RESTORE_END
tar.texi(,5782) Executed after restoring the file system.
tar.texi(,5783) @end defvr
tar.texi(,5784) 
tar.texi(,5785) @node backup-specs example
tar.texi(,5786) @subsection An Example Text of @file{Backup-specs}
tar.texi(,5787) 
tar.texi(,5788) The following is an example of @file{backup-specs}:
tar.texi(,5789) 
tar.texi(,5790) @smallexample
tar.texi(,5791) # site-specific parameters for file system backup.
tar.texi(,5792) 
tar.texi(,5793) ADMINISTRATOR=friedman
tar.texi(,5794) BACKUP_HOUR=1
tar.texi(,5795) TAPE_FILE=/dev/nrsmt0
tar.texi(,5796) 
tar.texi(,5797) # Use @code{ssh} instead of the less secure @code{rsh}
tar.texi(,5798) RSH=/usr/bin/ssh
tar.texi(,5799) RSH_COMMAND=/usr/bin/ssh
tar.texi(,5800) 
tar.texi(,5801) # Override MT_STATUS function:
tar.texi(,5802) my_status() @{
tar.texi(,5803)       mts -t $TAPE_FILE
tar.texi(,5804) @}
tar.texi(,5805) MT_STATUS=my_status
tar.texi(,5806) 
tar.texi(,5807) # Disable MT_OFFLINE function
tar.texi(,5808) MT_OFFLINE=:
tar.texi(,5809) 
tar.texi(,5810) BLOCKING=124
tar.texi(,5811) BACKUP_DIRS="
tar.texi(,5812)         albert:/fs/fsf
tar.texi(,5813)         apple-gunkies:/gd
tar.texi(,5814)         albert:/fs/gd2
tar.texi(,5815)         albert:/fs/gp
tar.texi(,5816)         geech:/usr/jla
tar.texi(,5817)         churchy:/usr/roland
tar.texi(,5818)         albert:/
tar.texi(,5819)         albert:/usr
tar.texi(,5820)         apple-gunkies:/
tar.texi(,5821)         apple-gunkies:/usr
tar.texi(,5822)         gnu:/hack
tar.texi(,5823)         gnu:/u
tar.texi(,5824)         apple-gunkies:/com/mailer/gnu
tar.texi(,5825)         apple-gunkies:/com/archive/gnu"
tar.texi(,5826) 
tar.texi(,5827) BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
tar.texi(,5828) 
tar.texi(,5829) @end smallexample
tar.texi(,5830) 
tar.texi(,5831) @node Scripted Backups
tar.texi(,5832) @section Using the Backup Scripts
tar.texi(,5833) 
tar.texi(,5834) The syntax for running a backup script is:
tar.texi(,5835) 
tar.texi(,5836) @smallexample
tar.texi(,5837) backup --level=@var{level} --time=@var{time}
tar.texi(,5838) @end smallexample
tar.texi(,5839) 
tar.texi(,5840) The @option{level} option requests the dump level.  Thus, to produce
tar.texi(,5841) a full dump, specify @code{--level=0} (this is the default, so
tar.texi(,5842) @option{--level} may be omitted if its value is @code{0}).
tar.texi(,5843) @footnote{For backward compatibility, the @code{backup} will also
tar.texi(,5844) try to deduce the requested dump level from the name of the
tar.texi(,5845) script itself.  If the name consists of a string @samp{level-}
tar.texi(,5846) followed by a single decimal digit, that digit is taken as
tar.texi(,5847) the dump level number.  Thus, you may create a link from @code{backup}
tar.texi(,5848) to @code{level-1} and then run @code{level-1} whenever you need to
tar.texi(,5849) create a level one dump.}
tar.texi(,5850) 
tar.texi(,5851) The @option{--time} option determines when should the backup be
tar.texi(,5852) run.  @var{Time} may take three forms:
tar.texi(,5853) 
tar.texi(,5854) @table @asis
tar.texi(,5855) @item @var{hh}:@var{mm}
tar.texi(,5856) 
tar.texi(,5857) The dump must be run at @var{hh} hours @var{mm} minutes.
tar.texi(,5858) 
tar.texi(,5859) @item @var{hh}
tar.texi(,5860) 
tar.texi(,5861) The dump must be run at @var{hh} hours
tar.texi(,5862) 
tar.texi(,5863) @item now
tar.texi(,5864) 
tar.texi(,5865) The dump must be run immediately.
tar.texi(,5866) @end table
tar.texi(,5867) 
tar.texi(,5868) You should start a script with a tape or disk mounted.  Once you
tar.texi(,5869) start a script, it prompts you for new tapes or disks as it
tar.texi(,5870) needs them.  Media volumes don't have to correspond to archive
tar.texi(,5871) files --- a multi-volume archive can be started in the middle of a
tar.texi(,5872) tape that already contains the end of another multi-volume archive.
tar.texi(,5873) The @code{restore} script prompts for media by its archive volume,
tar.texi(,5874) so to avoid an error message you should keep track of which tape
tar.texi(,5875) (or disk) contains which volume of the archive (@pxref{Scripted
tar.texi(,5876) Restoration}).
tar.texi(,5877) 
tar.texi(,5878) The backup scripts write two files on the file system.  The first is a
tar.texi(,5879) record file in @file{/etc/tar-backup/}, which is used by the scripts
tar.texi(,5880) to store and retrieve information about which files were dumped.  This
tar.texi(,5881) file is not meant to be read by humans, and should not be deleted by
tar.texi(,5882) them.  @xref{Snapshot Files}, for a more detailed explanation of this
tar.texi(,5883) file.
tar.texi(,5884) 
tar.texi(,5885) The second file is a log file containing the names of the file systems
tar.texi(,5886) and files dumped, what time the backup was made, and any error
tar.texi(,5887) messages that were generated, as well as how much space was left in
tar.texi(,5888) the media volume after the last volume of the archive was written.
tar.texi(,5889) You should check this log file after every backup.  The file name is
tar.texi(,5890) @file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy}
tar.texi(,5891) represents current date, and @var{n} represents current dump level number.
tar.texi(,5892) 
tar.texi(,5893) The script also prints the name of each system being dumped to the
tar.texi(,5894) standard output.
tar.texi(,5895) 
tar.texi(,5896) Following is the full list of options accepted by @code{backup}
tar.texi(,5897) script:
tar.texi(,5898) 
tar.texi(,5899) @table @option
tar.texi(,5900) @item -l @var{level}
tar.texi(,5901) @itemx --level=@var{level}
tar.texi(,5902) Do backup level @var{level} (default 0).
tar.texi(,5903) 
tar.texi(,5904) @item -f
tar.texi(,5905) @itemx --force
tar.texi(,5906) Force backup even if today's log file already exists.
tar.texi(,5907) 
tar.texi(,5908) @item -v[@var{level}]
tar.texi(,5909) @itemx --verbose[=@var{level}]
tar.texi(,5910) Set verbosity level.  The higher the level is, the more debugging
tar.texi(,5911) information will be output during execution.  Devault @var{level}
tar.texi(,5912) is 100, which means the highest debugging level.
tar.texi(,5913) 
tar.texi(,5914) @item -t @var{start-time}
tar.texi(,5915) @itemx --time=@var{start-time}
tar.texi(,5916) Wait till @var{time}, then do backup.
tar.texi(,5917) 
tar.texi(,5918) @item -h
tar.texi(,5919) @itemx --help
tar.texi(,5920) Display short help message and exit.
tar.texi(,5921) 
tar.texi(,5922) @item -V
tar.texi(,5923) @itemx --version
tar.texi(,5924) Display information about the program's name, version, origin and legal
tar.texi(,5925) status, all on standard output, and then exit successfully.
tar.texi(,5926) @end table
tar.texi(,5927) 
tar.texi(,5928) 
tar.texi(,5929) @node Scripted Restoration
tar.texi(,5930) @section Using the Restore Script
tar.texi(,5931) 
tar.texi(,5932) To restore files that were archived using a scripted backup, use the
tar.texi(,5933) @code{restore} script.  Its usage is quite straightforward.  In the
tar.texi(,5934) simplest form, invoke @code{restore --all}, it will
tar.texi(,5935) then restore all the file systems and files specified in
tar.texi(,5936) @file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
tar.texi(,5937) 
tar.texi(,5938) You may select the file systems (and/or files) to restore by
tar.texi(,5939) giving @code{restore} list of @dfn{patterns} in its command
tar.texi(,5940) line.  For example, running
tar.texi(,5941) 
tar.texi(,5942) @smallexample
tar.texi(,5943) restore 'albert:*'
tar.texi(,5944) @end smallexample
tar.texi(,5945) 
tar.texi(,5946) @noindent
tar.texi(,5947) will restore all file systems on the machine @samp{albert}.  A more
tar.texi(,5948) complicated example:
tar.texi(,5949) 
tar.texi(,5950) @smallexample
tar.texi(,5951) restore 'albert:*' '*:/var'
tar.texi(,5952) @end smallexample
tar.texi(,5953) 
tar.texi(,5954) @noindent
tar.texi(,5955) This command will restore all file systems on the machine @samp{albert}
tar.texi(,5956) as well as @file{/var} file system on all machines.
tar.texi(,5957) 
tar.texi(,5958) By default @code{restore} will start restoring files from the lowest
tar.texi(,5959) available dump level (usually zero) and will continue through
tar.texi(,5960) all available dump levels.  There may be situations where such a
tar.texi(,5961) thorough restore is not necessary.  For example, you may wish to
tar.texi(,5962) restore only files from the recent level one backup.  To do so,
tar.texi(,5963) use @option{--level} option, as shown in the example below:
tar.texi(,5964) 
tar.texi(,5965) @smallexample
tar.texi(,5966) restore --level=1
tar.texi(,5967) @end smallexample
tar.texi(,5968) 
tar.texi(,5969) The full list of options accepted by @code{restore} follows:
tar.texi(,5970) 
tar.texi(,5971) @table @option
tar.texi(,5972) @item -a
tar.texi(,5973) @itemx --all
tar.texi(,5974) Restore all file systems and files specified in @file{backup-specs}
tar.texi(,5975) 
tar.texi(,5976) @item -l @var{level}
tar.texi(,5977) @itemx --level=@var{level}
tar.texi(,5978) Start restoring from the given backup level, instead of the default 0.
tar.texi(,5979) 
tar.texi(,5980) @item -v[@var{level}]
tar.texi(,5981) @itemx --verbose[=@var{level}]
tar.texi(,5982) Set verbosity level.  The higher the level is, the more debugging
tar.texi(,5983) information will be output during execution.  Devault @var{level}
tar.texi(,5984) is 100, which means the highest debugging level.
tar.texi(,5985) 
tar.texi(,5986) @item -h
tar.texi(,5987) @itemx --help
tar.texi(,5988) Display short help message and exit.
tar.texi(,5989) 
tar.texi(,5990) @item -V
tar.texi(,5991) @itemx --version
tar.texi(,5992) Display information about the program's name, version, origin and legal
tar.texi(,5993) status, all on standard output, and then exit successfully.
tar.texi(,5994) @end table
tar.texi(,5995) 
tar.texi(,5996) You should start the restore script with the media containing the
tar.texi(,5997) first volume of the archive mounted.  The script will prompt for other
tar.texi(,5998) volumes as they are needed.  If the archive is on tape, you don't need
tar.texi(,5999) to rewind the tape to to its beginning---if the tape head is
tar.texi(,6000) positioned past the beginning of the archive, the script will rewind
tar.texi(,6001) the tape as needed.  @xref{Tape Positioning}, for a discussion of tape
tar.texi(,6002) positioning.
tar.texi(,6003) 
tar.texi(,6004) @quotation
tar.texi(,6005) @strong{Warning:} The script will delete files from the active file
tar.texi(,6006) system if they were not in the file system when the archive was made.
tar.texi(,6007) @end quotation
tar.texi(,6008) 
tar.texi(,6009) @xref{Incremental Dumps}, for an explanation of how the script makes
tar.texi(,6010) that determination.
tar.texi(,6011) 
tar.texi(,6012) @node Choosing
tar.texi(,6013) @chapter Choosing Files and Names for @command{tar}
tar.texi(UNREVISED,6014) @quotation
tar.texi(UNREVISED,6014) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,6014) @end quotation
tar.texi(,6015) 
tar.texi(,6016) Certain options to @command{tar} enable you to specify a name for your
tar.texi(,6017) archive.  Other options let you decide which files to include or exclude
tar.texi(,6018) from the archive, based on when or whether files were modified, whether
tar.texi(,6019) the file names do or don't match specified patterns, or whether files
tar.texi(,6020) are in specified directories.
tar.texi(,6021) 
tar.texi(,6022) This chapter discusses these options in detail.
tar.texi(,6023) 
tar.texi(,6024) @menu
tar.texi(,6025) * file::                        Choosing the Archive's Name
tar.texi(,6026) * Selecting Archive Members::
tar.texi(,6027) * files::                       Reading Names from a File
tar.texi(,6028) * exclude::                     Excluding Some Files
tar.texi(,6029) * wildcards::                   Wildcards Patterns and Matching
tar.texi(,6030) * quoting styles::              Ways of Quoting Special Characters in Names
tar.texi(,6031) * transform::                   Modifying File and Member Names
tar.texi(,6032) * after::                       Operating Only on New Files
tar.texi(,6033) * recurse::                     Descending into Directories
tar.texi(,6034) * one::                         Crossing File System Boundaries
tar.texi(,6035) @end menu
tar.texi(,6036) 
tar.texi(,6037) @node file
tar.texi(,6038) @section Choosing and Naming Archive Files
tar.texi(UNREVISED,6039) @quotation
tar.texi(UNREVISED,6039) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,6039) @end quotation
tar.texi(,6040) 
tar.texi(,6041) @cindex Naming an archive
tar.texi(,6042) @cindex Archive Name
tar.texi(,6043) @cindex Choosing an archive file
tar.texi(,6044) @cindex Where is the archive?
tar.texi(,6045) By default, @command{tar} uses an archive file name that was compiled when
tar.texi(,6046) it was built on the system; usually this name refers to some physical
tar.texi(,6047) tape drive on the machine.  However, the person who installed @command{tar}
tar.texi(,6048) on the system may not have set the default to a meaningful value as far as
tar.texi(,6049) most users are concerned.  As a result, you will usually want to tell
tar.texi(,6050) @command{tar} where to find (or create) the archive.  The
tar.texi(,6051) @option{--file=@var{archive-name}} (@option{-f @var{archive-name}})
tar.texi(,6052) option allows you to either specify or name a file to use as the archive
tar.texi(,6053) instead of the default archive file location.
tar.texi(,6054) 
tar.texi(,6055) @table @option
tar.texi(xopindex,6056) @opindex file@r{, short description}
tar.texi(,6057) @item --file=@var{archive-name}
tar.texi(,6058) @itemx -f @var{archive-name}
tar.texi(,6059) Name the archive to create or operate on.  Use in conjunction with
tar.texi(,6060) any operation.
tar.texi(,6061) @end table
tar.texi(,6062) 
tar.texi(,6063) For example, in this @command{tar} command,
tar.texi(,6064) 
tar.texi(,6065) @smallexample
tar.texi(,6066) $ @kbd{tar -cvf collection.tar blues folk jazz}
tar.texi(,6067) @end smallexample
tar.texi(,6068) 
tar.texi(,6069) @noindent
tar.texi(,6070) @file{collection.tar} is the name of the archive.  It must directly
tar.texi(,6071) follow the @option{-f} option, since whatever directly follows @option{-f}
tar.texi(,6072) @emph{will} end up naming the archive.  If you neglect to specify an
tar.texi(,6073) archive name, you may end up overwriting a file in the working directory
tar.texi(,6074) with the archive you create since @command{tar} will use this file's name
tar.texi(,6075) for the archive name.
tar.texi(,6076) 
tar.texi(,6077) An archive can be saved as a file in the file system, sent through a
tar.texi(,6078) pipe or over a network, or written to an I/O device such as a tape,
tar.texi(,6079) floppy disk, or CD write drive.
tar.texi(,6080) 
tar.texi(,6081) @cindex Writing new archives
tar.texi(,6082) @cindex Archive creation
tar.texi(,6083) If you do not name the archive, @command{tar} uses the value of the
tar.texi(,6084) environment variable @env{TAPE} as the file name for the archive.  If
tar.texi(,6085) that is not available, @command{tar} uses a default, compiled-in archive
tar.texi(,6086) name, usually that for tape unit zero (i.e.  @file{/dev/tu00}).
tar.texi(,6087) 
tar.texi(,6088) @cindex Standard input and output
tar.texi(,6089) @cindex tar to standard input and output
tar.texi(,6090) If you use @file{-} as an @var{archive-name}, @command{tar} reads the
tar.texi(,6091) archive from standard input (when listing or extracting files), or
tar.texi(,6092) writes it to standard output (when creating an archive).  If you use
tar.texi(,6093) @file{-} as an @var{archive-name} when modifying an archive,
tar.texi(,6094) @command{tar} reads the original archive from its standard input and
tar.texi(,6095) writes the entire new archive to its standard output.
tar.texi(,6096) 
tar.texi(,6097) The following example is a convenient way of copying directory
tar.texi(,6098) hierarchy from @file{sourcedir} to @file{targetdir}.
tar.texi(,6099) 
tar.texi(,6100) @smallexample
tar.texi(,6101) $ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
tar.texi(,6102) @end smallexample
tar.texi(,6103) 
tar.texi(,6104) The @option{-C} option allows to avoid using subshells:
tar.texi(,6105) 
tar.texi(,6106) @smallexample
tar.texi(,6107) $ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
tar.texi(,6108) @end smallexample
tar.texi(,6109) 
tar.texi(,6110) In both examples above, the leftmost @command{tar} invocation archives
tar.texi(,6111) the contents of @file{sourcedir} to the standard output, while the
tar.texi(,6112) rightmost one reads this archive from its standard input and
tar.texi(,6113) extracts it.  The @option{-p} option tells it to restore permissions
tar.texi(,6114) of the extracted files.
tar.texi(,6115) 
tar.texi(,6116) @cindex Remote devices
tar.texi(,6117) @cindex tar to a remote device
tar.texi(,6118) @anchor{remote-dev}
tar.texi(,6119) To specify an archive file on a device attached to a remote machine,
tar.texi(,6120) use the following:
tar.texi(,6121) 
tar.texi(,6122) @smallexample
tar.texi(,6123) @kbd{--file=@var{hostname}:/@var{dev}/@var{file-name}}
tar.texi(,6124) @end smallexample
tar.texi(,6125) 
tar.texi(,6126) @noindent
tar.texi(,6127) @command{tar} will complete the remote connection, if possible, and
tar.texi(,6128) prompt you for a username and password.  If you use
tar.texi(,6129) @option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
tar.texi(,6130) will complete the remote connection, if possible, using your username
tar.texi(,6131) as the username on the remote machine.
tar.texi(,6132) 
tar.texi(,6133) @cindex Local and remote archives
tar.texi(,6134) @anchor{local and remote archives}
tar.texi(,6135) If the archive file name includes a colon (@samp{:}), then it is assumed
tar.texi(,6136) to be a file on another machine.  If the archive file is
tar.texi(,6137) @samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
tar.texi(,6138) host @var{host}.  The remote host is accessed using the @command{rsh}
tar.texi(,6139) program, with a username of @var{user}.  If the username is omitted
tar.texi(,6140) (along with the @samp{@@} sign), then your user name will be used.
tar.texi(,6141) (This is the normal @command{rsh} behavior.)  It is necessary for the
tar.texi(,6142) remote machine, in addition to permitting your @command{rsh} access, to
tar.texi(,6143) have the @file{rmt} program installed (This command is included in
tar.texi(GNUTAR,6144) the tar.texi(GNUTAR,6144) @acronym{GNU} @command{tar} distribution and by default is installed under
tar.texi(,6145) @file{@var{prefix}/libexec/rmt}, were @var{prefix} means your
tar.texi(,6146) installation prefix).  If you need to use a file whose name includes a
tar.texi(,6147) colon, then the remote tape drive behavior
tar.texi(,6148) can be inhibited by using the @option{--force-local} option.
tar.texi(,6149) 
tar.texi(GNUTAR,6150) When the archive is being created to @file{/dev/null}, tar.texi(GNUTAR,6150) @acronym{GNU} @command{tar}
tar.texi(,6151) tries to minimize input and output operations.  The Amanda backup
tar.texi(GNUTAR,6152) system, when used with tar.texi(GNUTAR,6152) @acronym{GNU} @command{tar}, has an initial sizing pass which
tar.texi(,6153) uses this feature. 
tar.texi(,6154) 
tar.texi(,6155) @node Selecting Archive Members
tar.texi(,6156) @section Selecting Archive Members
tar.texi(,6157) @cindex Specifying files to act on
tar.texi(,6158) @cindex Specifying archive members
tar.texi(,6159) 
tar.texi(,6160) @dfn{File Name arguments} specify which files in the file system
tar.texi(,6161) @command{tar} operates on, when creating or adding to an archive, or which
tar.texi(,6162) archive members @command{tar} operates on, when reading or deleting from
tar.texi(,6163) an archive.  @xref{Operations}.
tar.texi(,6164) 
tar.texi(,6165) To specify file names, you can include them as the last arguments on
tar.texi(,6166) the command line, as follows:
tar.texi(,6167) @smallexample
tar.texi(,6168) @kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
tar.texi(,6169) @end smallexample
tar.texi(,6170) 
tar.texi(,6171) If a file name begins with dash (@samp{-}), precede it with
tar.texi(,6172) @option{--add-file} option to prevent it from being treated as an
tar.texi(,6173) option.
tar.texi(,6174) 
tar.texi(,6175) @anchor{input name quoting}
tar.texi(GNUTAR,6176) By default tar.texi(GNUTAR,6176) @acronym{GNU} @command{tar} attempts to @dfn{unquote} each file or member
tar.texi(,6177) name, replacing @dfn{escape sequences} according to the following
tar.texi(,6178) table:
tar.texi(,6179) 
tar.texi(,6180) @multitable @columnfractions 0.20 0.60
tar.texi(,6181) @headitem Escape @tab Replaced with    
tar.texi(,6182) @item \a         @tab Audible bell (ASCII 7)
tar.texi(,6183) @item \b         @tab Backspace (ASCII 8)  
tar.texi(,6184) @item \f         @tab Form feed (ASCII 12)
tar.texi(,6185) @item \n         @tab New line (ASCII 10)
tar.texi(,6186) @item \r         @tab Carriage return (ASCII 13)
tar.texi(,6187) @item \t         @tab Horizontal tabulation (ASCII 9)
tar.texi(,6188) @item \v         @tab Vertical tabulation (ASCII 11)
tar.texi(,6189) @item \?         @tab ASCII 127
tar.texi(,6190) @item \@var{n}   @tab ASCII @var{n} (@var{n} should be an octal number
tar.texi(,6191)                  of up to 3 digits)
tar.texi(,6192) @end multitable
tar.texi(,6193) 
tar.texi(,6194) A backslash followed by any other symbol is retained.
tar.texi(,6195) 
tar.texi(,6196) This default behavior is controlled by the following command line
tar.texi(,6197) option:
tar.texi(,6198) 
tar.texi(,6199) @table @option
tar.texi(,6200) @opindex unquote
tar.texi(,6201) @item --unquote
tar.texi(,6202) Enable unquoting input file or member names (default).
tar.texi(,6203) 
tar.texi(,6204) @opindex no-unquote
tar.texi(,6205) @item --no-unquote
tar.texi(,6206) Disable unquoting input file or member names.
tar.texi(,6207) @end table
tar.texi(,6208) 
tar.texi(,6209) If you specify a directory name as a file name argument, all the files
tar.texi(,6210) in that directory are operated on by @command{tar}.
tar.texi(,6211) 
tar.texi(,6212) If you do not specify files, @command{tar} behavior differs depending
tar.texi(,6213) on the operation mode as described below:
tar.texi(,6214) 
tar.texi(,6215) When @command{tar} is invoked with @option{--create} (@option{-c}),
tar.texi(,6216) @command{tar} will stop immediately, reporting the following:
tar.texi(,6217) 
tar.texi(,6218) @smallexample
tar.texi(,6219) @group
tar.texi(,6220) $ @kbd{tar cf a.tar}
tar.texi(,6221) tar: Cowardly refusing to create an empty archive
tar.texi(,6222) Try `tar --help' or `tar --usage' for more information.
tar.texi(,6223) @end group
tar.texi(,6224) @end smallexample
tar.texi(,6225) 
tar.texi(,6226) If you specify either @option{--list} (@option{-t}) or
tar.texi(,6227) @option{--extract} (@option{--get}, @option{-x}), @command{tar}
tar.texi(,6228) operates on all the archive members in the archive.
tar.texi(,6229) 
tar.texi(,6230) If run with @option{--diff} option, tar will compare the archive with
tar.texi(,6231) the contents of the current working directory.
tar.texi(,6232) 
tar.texi(,6233) If you specify any other operation, @command{tar} does nothing.
tar.texi(,6234) 
tar.texi(,6235) By default, @command{tar} takes file names from the command line.  However,
tar.texi(,6236) there are other ways to specify file or member names, or to modify the
tar.texi(,6237) manner in which @command{tar} selects the files or members upon which to
tar.texi(,6238) operate.  In general, these methods work both for specifying the names
tar.texi(,6239) of files and archive members. 
tar.texi(,6240) 
tar.texi(,6241) @node files
tar.texi(,6242) @section Reading Names from a File
tar.texi(,6243) 
tar.texi(,6244) @cindex Reading file names from a file
tar.texi(,6245) @cindex Lists of file names
tar.texi(,6246) @cindex File Name arguments, alternatives
tar.texi(,6247) Instead of giving the names of files or archive members on the command
tar.texi(,6248) line, you can put the names into a file, and then use the
tar.texi(,6249) @option{--files-from=@var{file-of-names}} (@option{-T
tar.texi(,6250) @var{file-of-names}}) option to @command{tar}.  Give the name of the
tar.texi(,6251) file which contains the list of files to include as the argument to 
tar.texi(,6252) @option{--files-from}.  In the list, the file names should be separated by
tar.texi(,6253) newlines.  You will frequently use this option when you have generated
tar.texi(,6254) the list of files to archive with the @command{find} utility.
tar.texi(,6255) 
tar.texi(,6256) @table @option
tar.texi(,6257) @opindex files-from
tar.texi(,6258) @item --files-from=@var{file-name}
tar.texi(,6259) @itemx -T @var{file-name}
tar.texi(,6260) Get names to extract or create from file @var{file-name}.
tar.texi(,6261) @end table
tar.texi(,6262) 
tar.texi(,6263) If you give a single dash as a file name for @option{--files-from}, (i.e.,
tar.texi(,6264) you specify either @code{--files-from=-} or @code{-T -}), then the file
tar.texi(,6265) names are read from standard input.
tar.texi(,6266) 
tar.texi(,6267) Unless you are running @command{tar} with @option{--create}, you can not use
tar.texi(,6268) both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
tar.texi(,6269) command.
tar.texi(,6270) 
tar.texi(,6271) Any number of @option{-T} options can be given in the command line.
tar.texi(,6272) 
tar.texi(,6273) The following example shows how to use @command{find} to generate a list of
tar.texi(,6274) files smaller than 400K in length and put that list into a file
tar.texi(,6275) called @file{small-files}.  You can then use the @option{-T} option to
tar.texi(,6276) @command{tar} to specify the files from that file, @file{small-files}, to
tar.texi(,6277) create the archive @file{little.tgz}.  (The @option{-z} option to
tar.texi(,6278) @command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for
tar.texi(,6279) more information.)
tar.texi(,6280) 
tar.texi(,6281) @smallexample
tar.texi(,6282) $ @kbd{find .  -size -400 -print > small-files}
tar.texi(,6283) $ @kbd{tar -c -v -z -T small-files -f little.tgz}
tar.texi(,6284) @end smallexample
tar.texi(,6285) 
tar.texi(,6286) @noindent
tar.texi(,6287) In the file list given by @option{-T} option, any file name beginning
tar.texi(,6288) with @samp{-} character is considered a @command{tar} option and is
tar.texi(GNUTAR,6289) processed accordingly.@footnote{Versions of @acronym{GNU} @command{tar} up to 1.15.1
tar.texi(,6290) recognized only @option{-C} option in file lists, and only if the
tar.texi(,6291) option and its argument occupied two consecutive lines.} For example,
tar.texi(,6292) the common use of this feature is to change to another directory by
tar.texi(,6293) specifying @option{-C} option:
tar.texi(,6294) 
tar.texi(,6295) @smallexample
tar.texi(,6296) @group
tar.texi(,6297) $ @kbd{cat list}
tar.texi(,6298) -C/etc
tar.texi(,6299) passwd
tar.texi(,6300) hosts
tar.texi(,6301) -C/lib
tar.texi(,6302) libc.a
tar.texi(,6303) $ @kbd{tar -c -f foo.tar --files-from list}
tar.texi(,6304) @end group
tar.texi(,6305) @end smallexample
tar.texi(,6306) 
tar.texi(,6307) @noindent
tar.texi(,6308) In this example, @command{tar} will first switch to @file{/etc}
tar.texi(,6309) directory and add files @file{passwd} and @file{hosts} to the
tar.texi(,6310) archive.  Then it will change to @file{/lib} directory and will archive
tar.texi(,6311) the file @file{libc.a}.  Thus, the resulting archive @file{foo.tar} will
tar.texi(,6312) contain:
tar.texi(,6313) 
tar.texi(,6314) @smallexample
tar.texi(,6315) @group
tar.texi(,6316) $ @kbd{tar tf foo.tar}
tar.texi(,6317) passwd
tar.texi(,6318) hosts
tar.texi(,6319) libc.a
tar.texi(,6320) @end group
tar.texi(,6321) @end smallexample
tar.texi(,6322) 
tar.texi(,6323) @noindent
tar.texi(xopindex,6324) @opindex directory@r{, using in @option{--files-from} argument}
tar.texi(,6325) Notice that the option parsing algorithm used with @option{-T} is
tar.texi(,6326) stricter than the one used by shell.  Namely, when specifying option
tar.texi(,6327) arguments, you should observe the following rules:
tar.texi(,6328) 
tar.texi(,6329) @itemize @bullet
tar.texi(,6330) @item
tar.texi(,6331) When using short (single-letter) option form, its argument must
tar.texi(,6332) immediately follow the option letter, without any intervening
tar.texi(,6333) whitespace.  For example: @code{-Cdir}.
tar.texi(,6334) 
tar.texi(,6335) @item
tar.texi(,6336) When using long option form, the option argument must be separated
tar.texi(,6337) from the option by a single equal sign.  No whitespace is allowed on
tar.texi(,6338) any side of the equal sign.  For example: @code{--directory=dir}.
tar.texi(,6339) 
tar.texi(,6340) @item
tar.texi(,6341) For both short and long option forms, the option argument can be given
tar.texi(,6342) on the next line after the option name, e.g.:
tar.texi(,6343) 
tar.texi(,6344) @smallexample
tar.texi(,6345) @group
tar.texi(,6346) --directory
tar.texi(,6347) dir
tar.texi(,6348) @end group
tar.texi(,6349) @end smallexample
tar.texi(,6350) 
tar.texi(,6351) @noindent
tar.texi(,6352) and
tar.texi(,6353) 
tar.texi(,6354) @smallexample
tar.texi(,6355) @group
tar.texi(,6356) -C
tar.texi(,6357) dir
tar.texi(,6358) @end group
tar.texi(,6359) @end smallexample
tar.texi(,6360) @end itemize
tar.texi(,6361) 
tar.texi(,6362) @opindex add-file
tar.texi(,6363) If you happen to have a file whose name starts with @samp{-},
tar.texi(,6364) precede it with @option{--add-file} option to prevent it from
tar.texi(,6365) being recognized as an option.  For example: @code{--add-file=--my-file}.
tar.texi(,6366) 
tar.texi(,6367) @menu
tar.texi(,6368) * nul::
tar.texi(,6369) @end menu
tar.texi(,6370) 
tar.texi(,6371) @node nul
tar.texi(,6372) @subsection @code{NUL} Terminated File Names
tar.texi(,6373) 
tar.texi(,6374) @cindex File names, terminated by @code{NUL}
tar.texi(,6375) @cindex @code{NUL} terminated file names
tar.texi(,6376) The @option{--null} option causes
tar.texi(,6377) @option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}})
tar.texi(,6378) to read file names terminated by a @code{NUL} instead of a newline, so
tar.texi(,6379) files whose names contain newlines can be archived using
tar.texi(,6380) @option{--files-from}. 
tar.texi(,6381) 
tar.texi(,6382) @table @option
tar.texi(,6383) @opindex null
tar.texi(,6384) @item --null
tar.texi(,6385) Only consider @code{NUL} terminated file names, instead of files that
tar.texi(,6386) terminate in a newline.
tar.texi(,6387) @end table
tar.texi(,6388) 
tar.texi(,6389) The @option{--null} option is just like the one in @acronym{GNU}
tar.texi(,6390) @command{xargs} and @command{cpio}, and is useful with the
tar.texi(,6391) @option{-print0} predicate of @acronym{GNU} @command{find}.  In
tar.texi(,6392) @command{tar}, @option{--null} also disables special handling for
tar.texi(,6393) file names that begin with dash.
tar.texi(,6394) 
tar.texi(,6395) This example shows how to use @command{find} to generate a list of files
tar.texi(,6396) larger than 800K in length and put that list into a file called
tar.texi(,6397) @file{long-files}.  The @option{-print0} option to @command{find} is just
tar.texi(,6398) like @option{-print}, except that it separates files with a @code{NUL}
tar.texi(,6399) rather than with a newline.  You can then run @command{tar} with both the
tar.texi(,6400) @option{--null} and @option{-T} options to specify that @command{tar} get the
tar.texi(,6401) files from that file, @file{long-files}, to create the archive
tar.texi(,6402) @file{big.tgz}.  The @option{--null} option to @command{tar} will cause
tar.texi(,6403) @command{tar} to recognize the @code{NUL} separator between files.
tar.texi(,6404) 
tar.texi(,6405) @smallexample
tar.texi(,6406) $ @kbd{find .  -size +800 -print0 > long-files}
tar.texi(,6407) $ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
tar.texi(,6408) @end smallexample
tar.texi(,6409) 
tar.texi(FIXME,6410) @allow-recursion
tar.texi(FIXME,6410) @quote-arg
tar.texi(FIXME,6410) 
tar.texi(,6411) 
tar.texi(,6412) @node exclude
tar.texi(,6413) @section Excluding Some Files
tar.texi(UNREVISED,6414) @quotation
tar.texi(UNREVISED,6414) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,6414) @end quotation
tar.texi(,6415) 
tar.texi(,6416) @cindex File names, excluding files by
tar.texi(,6417) @cindex Excluding files by name and pattern
tar.texi(,6418) @cindex Excluding files by file system
tar.texi(,6419) To avoid operating on files whose names match a particular pattern,
tar.texi(,6420) use the @option{--exclude} or @option{--exclude-from} options.
tar.texi(,6421) 
tar.texi(,6422) @table @option
tar.texi(,6423) @opindex exclude
tar.texi(,6424) @item --exclude=@var{pattern}
tar.texi(,6425) Causes @command{tar} to ignore files that match the @var{pattern}.
tar.texi(,6426) @end table
tar.texi(,6427) 
tar.texi(,6428) @findex exclude
tar.texi(,6429) The @option{--exclude=@var{pattern}} option prevents any file or
tar.texi(,6430) member whose name matches the shell wildcard (@var{pattern}) from
tar.texi(,6431) being operated on. 
tar.texi(,6432) For example, to create an archive with all the contents of the directory
tar.texi(,6433) @file{src} except for files whose names end in @file{.o}, use the
tar.texi(,6434) command @samp{tar -cf src.tar --exclude='*.o' src}.
tar.texi(,6435) 
tar.texi(,6436) You may give multiple @option{--exclude} options.
tar.texi(,6437) 
tar.texi(,6438) @table @option
tar.texi(,6439) @opindex exclude-from
tar.texi(,6440) @item --exclude-from=@var{file}
tar.texi(,6441) @itemx -X @var{file}
tar.texi(,6442) Causes @command{tar} to ignore files that match the patterns listed in
tar.texi(,6443) @var{file}.
tar.texi(,6444) @end table
tar.texi(,6445) 
tar.texi(,6446) @findex exclude-from
tar.texi(,6447) Use the @option{--exclude-from} option to read a
tar.texi(,6448) list of patterns, one per line, from @var{file}; @command{tar} will
tar.texi(,6449) ignore files matching those patterns.  Thus if @command{tar} is
tar.texi(,6450) called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
tar.texi(,6451) single line @file{*.o}, no files whose names end in @file{.o} will be
tar.texi(,6452) added to the archive.
tar.texi(,6453) 
tar.texi(,6454) @table @option
tar.texi(,6455) @opindex exclude-caches
tar.texi(,6456) @item --exclude-caches
tar.texi(,6457) Causes @command{tar} to ignore directories containing a cache directory tag.
tar.texi(,6458) @end table
tar.texi(,6459) 
tar.texi(,6460) @findex exclude-caches
tar.texi(,6461) When creating an archive, the @option{--exclude-caches} option causes
tar.texi(,6462) @command{tar} to exclude all directories that contain a @dfn{cache
tar.texi(,6463) directory tag}. A cache directory tag is a short file with the
tar.texi(,6464) well-known name @file{CACHEDIR.TAG} and having a standard header
tar.texi(,6465) specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
tar.texi(,6466) Various applications write cache directory tags into directories they
tar.texi(,6467) use to hold regenerable, non-precious data, so that such data can be
tar.texi(,6468) more easily excluded from backups.
tar.texi(,6469) 
tar.texi(,6470) @menu
tar.texi(,6471) * problems with exclude::
tar.texi(,6472) @end menu
tar.texi(,6473) 
tar.texi(,6474) @node problems with exclude
tar.texi(,6475) @unnumberedsubsec Problems with Using the @code{exclude} Options
tar.texi(,6476) 
tar.texi(xopindex,6477) @opindex exclude@r{, potential problems with}
tar.texi(,6478) Some users find @samp{exclude} options confusing.  Here are some common
tar.texi(,6479) pitfalls:
tar.texi(,6480) 
tar.texi(,6481) @itemize @bullet
tar.texi(,6482) @item
tar.texi(,6483) The main operating mode of @command{tar} does not act on a path name
tar.texi(,6484) explicitly listed on the command line if one of its file name
tar.texi(,6485) components is excluded.  In the example above, if
tar.texi(,6486) you create an archive and exclude files that end with @samp{*.o}, but
tar.texi(,6487) explicitly name the file @samp{dir.o/foo} after all the options have been
tar.texi(,6488) listed, @samp{dir.o/foo} will be excluded from the archive.
tar.texi(,6489) 
tar.texi(,6490) @item
tar.texi(,6491) You can sometimes confuse the meanings of @option{--exclude} and
tar.texi(,6492) @option{--exclude-from}.  Be careful: use @option{--exclude} when files
tar.texi(,6493) to be excluded are given as a pattern on the command line.  Use
tar.texi(,6494) @option{--exclude-from} to introduce the name of a file which contains
tar.texi(,6495) a list of patterns, one per line; each of these patterns can exclude
tar.texi(,6496) zero, one, or many files.
tar.texi(,6497) 
tar.texi(,6498) @item
tar.texi(,6499) When you use @option{--exclude=@var{pattern}}, be sure to quote the
tar.texi(GNUTAR,6500) @var{pattern} parameter, so tar.texi(GNUTAR,6500) @acronym{GNU} @command{tar} sees wildcard characters
tar.texi(,6501) like @samp{*}.  If you do not do this, the shell might expand the
tar.texi(,6502) @samp{*} itself using files at hand, so @command{tar} might receive a
tar.texi(,6503) list of files instead of one pattern, or none at all, making the
tar.texi(,6504) command somewhat illegal.  This might not correspond to what you want.
tar.texi(,6505) 
tar.texi(,6506) For example, write:
tar.texi(,6507) 
tar.texi(,6508) @smallexample
tar.texi(,6509) $ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
tar.texi(,6510) @end smallexample
tar.texi(,6511) 
tar.texi(,6512) @noindent
tar.texi(,6513) rather than:
tar.texi(,6514) 
tar.texi(,6515) @smallexample
tar.texi(,6516) # @emph{Wrong!}
tar.texi(,6517) $ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
tar.texi(,6518) @end smallexample
tar.texi(,6519) 
tar.texi(,6520) @item
tar.texi(,6521) You must use use shell syntax, or globbing, rather than @code{regexp}
tar.texi(,6522) syntax, when using exclude options in @command{tar}.  If you try to use
tar.texi(,6523) @code{regexp} syntax to describe files to be excluded, your command
tar.texi(,6524) might fail.
tar.texi(,6525) 
tar.texi(,6526) @item
tar.texi(FIXME,6529) @allow-recursion
tar.texi(FIXME,6529) @quote-arg
tar.texi(FIXME,6529)  
tar.texi(,6530) In earlier versions of @command{tar}, what is now the
tar.texi(,6531) @option{--exclude-from} option was called @option{--exclude} instead.
tar.texi(,6532) Now, @option{--exclude} applies to patterns listed on the command
tar.texi(,6533) line and @option{--exclude-from} applies to patterns listed in a
tar.texi(,6534) file.
tar.texi(,6535) 
tar.texi(,6536) @end itemize
tar.texi(,6537) 
tar.texi(,6538) @node wildcards
tar.texi(,6539) @section Wildcards Patterns and Matching
tar.texi(,6540) 
tar.texi(,6541) @dfn{Globbing} is the operation by which @dfn{wildcard} characters,
tar.texi(,6542) @samp{*} or @samp{?} for example, are replaced and expanded into all
tar.texi(GNUTAR,6543) existing files matching the given pattern.  tar.texi(GNUTAR,6543) @acronym{GNU} @command{tar} can use wildcard
tar.texi(,6544) patterns for matching (or globbing) archive members when extracting
tar.texi(,6545) from or listing an archive.  Wildcard patterns are also used for
tar.texi(,6546) verifying volume labels of @command{tar} archives.  This section has the
tar.texi(,6547) purpose of explaining wildcard syntax for @command{tar}.
tar.texi(,6548) 
tar.texi(FIXME,6549) @allow-recursion
tar.texi(FIXME,6549) @quote-arg
tar.texi(FIXME,6549) 
tar.texi(,6550) 
tar.texi(,6551) A @var{pattern} should be written according to shell syntax, using wildcard
tar.texi(,6552) characters to effect globbing.  Most characters in the pattern stand
tar.texi(,6553) for themselves in the matched string, and case is significant: @samp{a}
tar.texi(,6554) will match only @samp{a}, and not @samp{A}.  The character @samp{?} in the
tar.texi(,6555) pattern matches any single character in the matched string.  The character
tar.texi(,6556) @samp{*} in the pattern matches zero, one, or more single characters in
tar.texi(,6557) the matched string.  The character @samp{\} says to take the following
tar.texi(,6558) character of the pattern @emph{literally}; it is useful when one needs to
tar.texi(,6559) match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
tar.texi(,6560) 
tar.texi(,6561) The character @samp{[}, up to the matching @samp{]}, introduces a character
tar.texi(,6562) class.  A @dfn{character class} is a list of acceptable characters
tar.texi(,6563) for the next single character of the matched string.  For example,
tar.texi(,6564) @samp{[abcde]} would match any of the first five letters of the alphabet.
tar.texi(,6565) Note that within a character class, all of the ``special characters''
tar.texi(,6566) listed above other than @samp{\} lose their special meaning; for example,
tar.texi(,6567) @samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
tar.texi(,6568) @samp{[}, @samp{*}, @samp{?}, or @samp{]}.  (Due to parsing constraints,
tar.texi(,6569) the characters @samp{-} and @samp{]} must either come @emph{first} or
tar.texi(,6570) @emph{last} in a character class.)
tar.texi(,6571) 
tar.texi(,6572) @cindex Excluding characters from a character class
tar.texi(,6573) @cindex Character class, excluding characters from
tar.texi(,6574) If the first character of the class after the opening @samp{[}
tar.texi(,6575) is @samp{!} or @samp{^}, then the meaning of the class is reversed.
tar.texi(,6576) Rather than listing character to match, it lists those characters which
tar.texi(,6577) are @emph{forbidden} as the next single character of the matched string.
tar.texi(,6578) 
tar.texi(,6579) Other characters of the class stand for themselves.  The special
tar.texi(,6580) construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
tar.texi(,6581) letters, is meant to represent all characters between @var{a} and
tar.texi(,6582) @var{e}, inclusive.
tar.texi(,6583) 
tar.texi(FIXME,6585) @allow-recursion
tar.texi(FIXME,6585) @quote-arg
tar.texi(FIXME,6585) 
tar.texi(,6586) 
tar.texi(,6587) Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
tar.texi(,6588) special for wildcard matches.  However, if a pattern completely matches
tar.texi(,6589) a directory prefix of a matched string, then it matches the full matched
tar.texi(,6590) string: thus, excluding a directory also excludes all the files beneath it.
tar.texi(,6591) 
tar.texi(,6592) @menu
tar.texi(,6593) * controlling pattern-matching::
tar.texi(,6594) @end menu
tar.texi(,6595) 
tar.texi(,6596) @node controlling pattern-matching
tar.texi(,6597) @unnumberedsubsec Controlling Pattern-Matching
tar.texi(,6598) 
tar.texi(,6599) For the purposes of this section, we call @dfn{exclusion members} all
tar.texi(,6600) member names obtained while processing @option{--exclude} and
tar.texi(,6601) @option{--exclude-from} options, and @dfn{inclusion members} those
tar.texi(,6602) member names that were given in the command line or read from the file
tar.texi(,6603) specified with @option{--files-from} option.
tar.texi(,6604) 
tar.texi(,6605) These two pairs of member lists are used in the following operations:
tar.texi(,6606) @option{--diff}, @option{--extract}, @option{--list},
tar.texi(,6607) @option{--update}.
tar.texi(,6608) 
tar.texi(,6609) There are no inclusion members in create mode (@option{--create} and
tar.texi(,6610) @option{--append}), since in this mode the names obtained from the
tar.texi(,6611) command line refer to @emph{files}, not archive members.
tar.texi(,6612) 
tar.texi(,6613) By default, inclusion members are compared with archive members
tar.texi(GNUTAR,6614) literally @footnote{Notice that earlier @acronym{GNU} @command{tar} versions used 
tar.texi(,6615) globbing for inclusion members, which contradicted to UNIX98
tar.texi(,6616) specification and was not documented. @xref{Changes}, for more
tar.texi(,6617) information on this and other changes.} and exclusion members are
tar.texi(,6618) treated as globbing patterns.  For example:
tar.texi(,6619) 
tar.texi(,6620) @smallexample
tar.texi(,6621) @group
tar.texi(,6622) $ @kbd{tar tf foo.tar}
tar.texi(,6623) a.c
tar.texi(,6624) b.c
tar.texi(,6625) a.txt
tar.texi(,6626) [remarks]
tar.texi(,6627) # @i{Member names are used verbatim:}
tar.texi(,6628) $ @kbd{tar -xf foo.tar -v '[remarks]'}
tar.texi(,6629) [remarks]
tar.texi(,6630) # @i{Exclude member names are globbed:}
tar.texi(,6631) $ @kbd{tar -xf foo.tar -v --exclude '*.c'}
tar.texi(,6632) a.txt
tar.texi(,6633) [remarks]
tar.texi(,6634) @end group
tar.texi(,6635) @end smallexample
tar.texi(,6636) 
tar.texi(,6637) This behavior can be altered by using the following options:
tar.texi(,6638) 
tar.texi(,6639) @table @option
tar.texi(,6640) @opindex wildcards
tar.texi(,6641) @item --wildcards
tar.texi(,6642) Treat all member names as wildcards. 
tar.texi(,6643) 
tar.texi(,6644) @opindex no-wildcards
tar.texi(,6645) @item --no-wildcards
tar.texi(,6646) Treat all member names as literal strings.
tar.texi(,6647) @end table
tar.texi(,6648) 
tar.texi(,6649) Thus, to extract files whose names end in @samp{.c}, you can use:
tar.texi(,6650) 
tar.texi(,6651) @smallexample
tar.texi(,6652) $ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
tar.texi(,6653) a.c
tar.texi(,6654) b.c
tar.texi(,6655) @end smallexample
tar.texi(,6656) 
tar.texi(,6657) @noindent
tar.texi(,6658) Notice quoting of the pattern to prevent the shell from interpreting
tar.texi(,6659) it.
tar.texi(,6660) 
tar.texi(,6661) The effect of @option{--wildcards} option is cancelled by
tar.texi(,6662) @option{--no-wildcards}.  This can be used to pass part of
tar.texi(,6663) the command line arguments verbatim and other part as globbing
tar.texi(,6664) patterns.  For example, the following invocation:
tar.texi(,6665) 
tar.texi(,6666) @smallexample
tar.texi(,6667) $ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
tar.texi(,6668) @end smallexample
tar.texi(,6669) 
tar.texi(,6670) @noindent
tar.texi(,6671) instructs @command{tar} to extract from @file{foo.tar} all files whose
tar.texi(,6672) names end in @samp{.txt} and the file named @file{[remarks]}.
tar.texi(,6673) 
tar.texi(,6674) Normally, a pattern matches a name if an initial subsequence of the
tar.texi(,6675) name's components matches the pattern, where @samp{*}, @samp{?}, and
tar.texi(,6676) @samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards,
tar.texi(,6677) and wildcards can match @samp{/}.
tar.texi(,6678) 
tar.texi(,6679) Other than optionally stripping leading @samp{/} from names
tar.texi(,6680) (@pxref{absolute}), patterns and names are used as-is.  For
tar.texi(,6681) example, trailing @samp{/} is not trimmed from a user-specified name
tar.texi(,6682) before deciding whether to exclude it.
tar.texi(,6683) 
tar.texi(,6684) However, this matching procedure can be altered by the options listed
tar.texi(,6685) below.  These options accumulate.  For example:
tar.texi(,6686) 
tar.texi(,6687) @smallexample
tar.texi(,6688) --ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
tar.texi(,6689) @end smallexample
tar.texi(,6690) 
tar.texi(,6691) @noindent
tar.texi(,6692) ignores case when excluding @samp{makefile}, but not when excluding
tar.texi(,6693) @samp{readme}.
tar.texi(,6694) 
tar.texi(,6695) @table @option
tar.texi(,6696) @opindex anchored
tar.texi(,6697) @opindex no-anchored
tar.texi(,6698) @item --anchored
tar.texi(,6699) @itemx --no-anchored
tar.texi(,6700) If anchored, a pattern must match an initial subsequence
tar.texi(,6701) of the name's components.  Otherwise, the pattern can match any
tar.texi(,6702) subsequence.  Default is @option{--no-anchored} for exclusion members
tar.texi(,6703) and @option{--anchored} inclusion members.
tar.texi(,6704) 
tar.texi(,6705) @opindex ignore-case
tar.texi(,6706) @opindex no-ignore-case
tar.texi(,6707) @item --ignore-case
tar.texi(,6708) @itemx --no-ignore-case
tar.texi(,6709) When ignoring case, upper-case patterns match lower-case names and vice versa.
tar.texi(,6710) When not ignoring case (the default), matching is case-sensitive.
tar.texi(,6711) 
tar.texi(,6712) @opindex wildcards-match-slash
tar.texi(,6713) @opindex no-wildcards-match-slash
tar.texi(,6714) @item --wildcards-match-slash
tar.texi(,6715) @itemx --no-wildcards-match-slash
tar.texi(,6716) When wildcards match slash (the default for exclusion members), a
tar.texi(,6717) wildcard like @samp{*} in the pattern can match a @samp{/} in the
tar.texi(,6718) name.  Otherwise, @samp{/} is matched only by @samp{/}.
tar.texi(,6719) 
tar.texi(,6720) @end table
tar.texi(,6721) 
tar.texi(,6722) The @option{--recursion} and @option{--no-recursion} options
tar.texi(,6723) (@pxref{recurse}) also affect how member patterns are interpreted.  If
tar.texi(,6724) recursion is in effect, a pattern matches a name if it matches any of
tar.texi(,6725) the name's parent directories.
tar.texi(,6726) 
tar.texi(,6727) The following table summarizes pattern-matching default values:
tar.texi(,6728) 
tar.texi(,6729) @multitable @columnfractions .3 .7
tar.texi(,6730) @headitem Members @tab Default settings
tar.texi(,6731) @item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash}
tar.texi(,6732) @item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash}
tar.texi(,6733) @end multitable
tar.texi(,6734) 
tar.texi(,6735) @node quoting styles
tar.texi(,6736) @section Quoting Member Names
tar.texi(,6737) 
tar.texi(,6738) When displaying member names, @command{tar} takes care to avoid
tar.texi(,6739) ambiguities caused by certain characters.  This is called @dfn{name
tar.texi(,6740) quoting}.  The characters in question are:
tar.texi(,6741) 
tar.texi(,6742) @itemize @bullet
tar.texi(,6743) @item Non-printable control characters:
tar.texi(,6744) 
tar.texi(,6745) @multitable @columnfractions 0.20 0.10 0.60
tar.texi(,6746) @headitem Character @tab ASCII @tab Character name
tar.texi(,6747) @item \a @tab 7  @tab Audible bell
tar.texi(,6748) @item \b @tab 8  @tab Backspace
tar.texi(,6749) @item \f @tab 12 @tab Form feed
tar.texi(,6750) @item \n @tab 10 @tab New line
tar.texi(,6751) @item \r @tab 13 @tab Carriage return
tar.texi(,6752) @item \t @tab 9  @tab Horizontal tabulation
tar.texi(,6753) @item \v @tab 11 @tab Vertical tabulation
tar.texi(,6754) @end multitable
tar.texi(,6755) 
tar.texi(,6756) @item Space (ASCII 32)
tar.texi(,6757) 
tar.texi(,6758) @item Single and double quotes (@samp{'} and @samp{"})
tar.texi(,6759) 
tar.texi(,6760) @item Backslash (@samp{\})
tar.texi(,6761) @end itemize
tar.texi(,6762) 
tar.texi(,6763) The exact way @command{tar} uses to quote these characters depends on
tar.texi(,6764) the @dfn{quoting style}.  The default quoting style, called
tar.texi(,6765) @dfn{escape} (see below), uses backslash notation to represent control
tar.texi(,6766) characters, space and backslash.  Using this quoting style, control
tar.texi(,6767) characters are represented as listed in column @samp{Character} in the
tar.texi(,6768) above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
tar.texi(,6769) 
tar.texi(GNUTAR,6770) @acronym{GNU} @command{tar} offers seven distinct quoting styles, which can be selected
tar.texi(,6771) using @option{--quoting-style} option:
tar.texi(,6772) 
tar.texi(,6773) @table @option
tar.texi(,6774) @item --quoting-style=@var{style}
tar.texi(,6775) @opindex quoting-style
tar.texi(,6776) 
tar.texi(,6777) Sets quoting style.  Valid values for @var{style} argument are:
tar.texi(,6778) literal, shell, shell-always, c, escape, locale, clocale.
tar.texi(,6779) @end table
tar.texi(,6780) 
tar.texi(,6781) These styles are described in detail below.  To illustrate their
tar.texi(,6782) effect, we will use an imaginary tar archive @file{arch.tar}
tar.texi(,6783) containing the following members:
tar.texi(,6784) 
tar.texi(,6785) @smallexample
tar.texi(,6786) @group
tar.texi(,6787) # 1. Contains horizontal tabulation character.
tar.texi(,6788) a       tab
tar.texi(,6789) # 2. Contains newline character
tar.texi(,6790) a
tar.texi(,6791) newline
tar.texi(,6792) # 3. Contains a space
tar.texi(,6793) a space
tar.texi(,6794) # 4. Contains double quotes
tar.texi(,6795) a"double"quote
tar.texi(,6796) # 5. Contains single quotes
tar.texi(,6797) a'single'quote
tar.texi(,6798) # 6. Contains a backslash character:
tar.texi(,6799) a\backslash
tar.texi(,6800) @end group
tar.texi(,6801) @end smallexample
tar.texi(,6802) 
tar.texi(,6803) Here is how usual @command{ls} command would have listed them, if they
tar.texi(,6804) had existed in the current working directory:
tar.texi(,6805) 
tar.texi(,6806) @smallexample
tar.texi(,6807) @group
tar.texi(,6808) $ @kbd{ls}
tar.texi(,6809) a\ttab
tar.texi(,6810) a\nnewline
tar.texi(,6811) a\ space
tar.texi(,6812) a"double"quote
tar.texi(,6813) a'single'quote
tar.texi(,6814) a\\backslash
tar.texi(,6815) @end group
tar.texi(,6816) @end smallexample
tar.texi(,6817) 
tar.texi(,6818) Quoting styles:
tar.texi(,6819) 
tar.texi(,6820) @table @samp
tar.texi(,6821) @item literal
tar.texi(,6822) No quoting, display each character as is:
tar.texi(,6823) 
tar.texi(,6824) @smallexample
tar.texi(,6825) @group 
tar.texi(,6826) $ @kbd{tar tf arch.tar --quoting-style=literal}
tar.texi(,6827) ./
tar.texi(,6828) ./a space
tar.texi(,6829) ./a'single'quote
tar.texi(,6830) ./a"double"quote
tar.texi(,6831) ./a\backslash
tar.texi(,6832) ./a	tab
tar.texi(,6833) ./a
tar.texi(,6834) newline
tar.texi(,6835) @end group
tar.texi(,6836) @end smallexample
tar.texi(,6837) 
tar.texi(,6838) @item shell
tar.texi(,6839) Display characters the same way Bourne shell does:
tar.texi(,6840) control characters, except @samp{\t} and @samp{\n}, are printed using
tar.texi(,6841) backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
tar.texi(,6842) single quote is printed as @samp{\'}.  If a name contains any quoted
tar.texi(,6843) characters, it is enclosed in single quotes.  In particular, if a name
tar.texi(,6844) contains single quotes, it is printed as several single-quoted strings:
tar.texi(,6845) 
tar.texi(,6846) @smallexample
tar.texi(,6847) @group
tar.texi(,6848) $ @kbd{tar tf arch.tar --quoting-style=shell}
tar.texi(,6849) ./
tar.texi(,6850) './a space'
tar.texi(,6851) './a'\''single'\''quote'
tar.texi(,6852) './a"double"quote'
tar.texi(,6853) './a\backslash'
tar.texi(,6854) './a	tab'
tar.texi(,6855) './a
tar.texi(,6856) newline'
tar.texi(,6857) @end group
tar.texi(,6858) @end smallexample
tar.texi(,6859) 
tar.texi(,6860) @item shell-always
tar.texi(,6861) Same as @samp{shell}, but the names are always enclosed in single
tar.texi(,6862) quotes:
tar.texi(,6863) 
tar.texi(,6864) @smallexample
tar.texi(,6865) @group
tar.texi(,6866) $ @kbd{tar tf arch.tar --quoting-style=shell-always}
tar.texi(,6867) './'
tar.texi(,6868) './a space'
tar.texi(,6869) './a'\''single'\''quote'
tar.texi(,6870) './a"double"quote'
tar.texi(,6871) './a\backslash'
tar.texi(,6872) './a	tab'
tar.texi(,6873) './a
tar.texi(,6874) newline'
tar.texi(,6875) @end group
tar.texi(,6876) @end smallexample
tar.texi(,6877) 
tar.texi(,6878) @item c
tar.texi(,6879) Use the notation of the C programming language.  All names are
tar.texi(,6880) enclosed in double quotes.  Control characters are quoted using
tar.texi(,6881) backslash notations, double quotes are represented as @samp{\"},
tar.texi(,6882) backslash characters are represented as @samp{\\}.  Single quotes and
tar.texi(,6883) spaces are not quoted:
tar.texi(,6884) 
tar.texi(,6885) @smallexample
tar.texi(,6886) @group
tar.texi(,6887) $ @kbd{tar tf arch.tar --quoting-style=c}
tar.texi(,6888) "./"
tar.texi(,6889) "./a space"
tar.texi(,6890) "./a'single'quote"
tar.texi(,6891) "./a\"double\"quote"
tar.texi(,6892) "./a\\backslash"
tar.texi(,6893) "./a\ttab"
tar.texi(,6894) "./a\nnewline"
tar.texi(,6895) @end group
tar.texi(,6896) @end smallexample
tar.texi(,6897) 
tar.texi(,6898) @item escape
tar.texi(,6899) Control characters are printed using backslash notation, a space is
tar.texi(,6900) printed as @samp{\ } and a backslash as @samp{\\}.  This is the
tar.texi(,6901) default quoting style, unless it was changed when configured the
tar.texi(,6902) package.
tar.texi(,6903) 
tar.texi(,6904) @smallexample
tar.texi(,6905) @group
tar.texi(,6906) $ @kbd{tar tf arch.tar --quoting-style=escape}
tar.texi(,6907) ./
tar.texi(,6908) ./a space
tar.texi(,6909) ./a'single'quote
tar.texi(,6910) ./a"double"quote
tar.texi(,6911) ./a\\backslash
tar.texi(,6912) ./a\ttab
tar.texi(,6913) ./a\nnewline
tar.texi(,6914) @end group
tar.texi(,6915) @end smallexample
tar.texi(,6916) 
tar.texi(,6917) @item locale
tar.texi(,6918) Control characters, single quote and backslash are printed using
tar.texi(,6919) backslash notation.  All names are quoted using left and right
tar.texi(,6920) quotation marks, appropriate to the current locale.  If it does not
tar.texi(,6921) define quotation marks, use @samp{`} as left and @samp{'} as right
tar.texi(,6922) quotation marks.  Any occurrences of the right quotation mark in a
tar.texi(,6923) name are escaped with @samp{\}, for example:
tar.texi(,6924) 
tar.texi(,6925) For example:
tar.texi(,6926) 
tar.texi(,6927) @smallexample
tar.texi(,6928) @group
tar.texi(,6929) $ @kbd{tar tf arch.tar --quoting-style=locale}
tar.texi(,6930) `./'
tar.texi(,6931) `./a space'
tar.texi(,6932) `./a\'single\'quote'
tar.texi(,6933) `./a"double"quote'
tar.texi(,6934) `./a\\backslash'
tar.texi(,6935) `./a\ttab'
tar.texi(,6936) `./a\nnewline'
tar.texi(,6937) @end group
tar.texi(,6938) @end smallexample
tar.texi(,6939) 
tar.texi(,6940) @item clocale
tar.texi(,6941) Same as @samp{locale}, but @samp{"} is used for both left and right
tar.texi(,6942) quotation marks, if not provided by the currently selected locale:
tar.texi(,6943) 
tar.texi(,6944) @smallexample
tar.texi(,6945) @group
tar.texi(,6946) $ @kbd{tar tf arch.tar --quoting-style=clocale}
tar.texi(,6947) "./"
tar.texi(,6948) "./a space"
tar.texi(,6949) "./a'single'quote"
tar.texi(,6950) "./a\"double\"quote"
tar.texi(,6951) "./a\\backslash"
tar.texi(,6952) "./a\ttab"
tar.texi(,6953) "./a\nnewline"
tar.texi(,6954) @end group
tar.texi(,6955) @end smallexample
tar.texi(,6956) @end table
tar.texi(,6957) 
tar.texi(,6958) You can specify which characters should be quoted in addition to those
tar.texi(,6959) implied by the current quoting style:
tar.texi(,6960) 
tar.texi(,6961) @table @option
tar.texi(,6962) @item --quote-chars=@var{string}
tar.texi(,6963) Always quote characters from @var{string}, even if the selected
tar.texi(,6964) quoting style would not quote them.
tar.texi(,6965) @end table
tar.texi(,6966) 
tar.texi(,6967) For example, using @samp{escape} quoting (compare with the usual
tar.texi(,6968) escape listing above): 
tar.texi(,6969) 
tar.texi(,6970) @smallexample
tar.texi(,6971) @group
tar.texi(,6972) $ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
tar.texi(,6973) ./
tar.texi(,6974) ./a\ space
tar.texi(,6975) ./a'single'quote
tar.texi(,6976) ./a\"double\"quote
tar.texi(,6977) ./a\\backslash
tar.texi(,6978) ./a\ttab
tar.texi(,6979) ./a\nnewline
tar.texi(,6980) @end group
tar.texi(,6981) @end smallexample
tar.texi(,6982) 
tar.texi(,6983) To disable quoting of such additional characters, use the following
tar.texi(,6984) option:
tar.texi(,6985) 
tar.texi(,6986) @table @option
tar.texi(,6987) @item --no-quote-chars=@var{string}
tar.texi(,6988) Remove characters listed in @var{string} from the list of quoted
tar.texi(,6989) characters set by the previous @option{--quote-chars} option.
tar.texi(,6990) @end table
tar.texi(,6991) 
tar.texi(,6992) This option is particularly useful if you have added
tar.texi(,6993) @option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
tar.texi(,6994) and wish to disable it for the current invocation.
tar.texi(,6995) 
tar.texi(,6996) Note, that @option{--no-quote-chars} does @emph{not} disable those
tar.texi(,6997) characters that are quoted by default in the selected quoting style.
tar.texi(,6998) 
tar.texi(,6999) @node transform
tar.texi(,7000) @section Modifying File and Member Names
tar.texi(,7001) 
tar.texi(,7002) @command{Tar} archives contain detailed information about files stored
tar.texi(,7003) in them and full file names are part of that information.  When
tar.texi(,7004) storing file to an archive, its file name is recorded in the archive
tar.texi(,7005) along with the actual file contents.  When restoring from an archive,
tar.texi(,7006) a file is created on disk with exactly the same name as that stored
tar.texi(,7007) in the archive.  In the majority of cases this is the desired behavior
tar.texi(,7008) of a file archiver.  However, there are some cases when it is not.
tar.texi(,7009) 
tar.texi(,7010) First of all, it is often unsafe to extract archive members with
tar.texi(GNUTAR,7011) absolute file names or those that begin with a @file{../}.  tar.texi(GNUTAR,7011) @acronym{GNU} @command{tar}
tar.texi(,7012) takes special precautions when extracting such names and provides a
tar.texi(,7013) special option for handling them, which is described in
tar.texi(,7014) @ref{absolute}.
tar.texi(,7015) 
tar.texi(,7016) Secondly, you may wish to extract file names without some leading
tar.texi(,7017) directory components, or with otherwise modified names.  In other
tar.texi(,7018) cases it is desirable to store files under differing names in the
tar.texi(,7019) archive.
tar.texi(,7020) 
tar.texi(GNUTAR,7021) @acronym{GNU} @command{tar} provides two options for these needs.
tar.texi(,7022) 
tar.texi(,7023) @table @option
tar.texi(,7024) @opindex strip-components
tar.texi(,7025) @item --strip-components=@var{number}
tar.texi(,7026) Strip given @var{number} of leading components from file names before
tar.texi(,7027) extraction.
tar.texi(,7028) @end table
tar.texi(,7029) 
tar.texi(,7030) For example, suppose you have archived whole @file{/usr} hierarchy to
tar.texi(,7031) a tar archive named @file{usr.tar}.  Among other files, this archive
tar.texi(,7032) contains @file{usr/include/stdlib.h}, which you wish to extract to
tar.texi(,7033) the current working directory.  To do so, you type:
tar.texi(,7034) 
tar.texi(,7035) @smallexample
tar.texi(,7036) $ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h}
tar.texi(,7037) @end smallexample
tar.texi(,7038) 
tar.texi(,7039) The option @option{--strip=2} instructs @command{tar} to strip the
tar.texi(,7040) two leading components (@file{usr/} and @file{include/}) off the file
tar.texi(,7041) name. 
tar.texi(,7042) 
tar.texi(,7043) If you add to the above invocation @option{--verbose} (@option{-v})
tar.texi(,7044) option, you will note that the verbose listing still contains the
tar.texi(,7045) full file name, with the two removed components still in place.  This
tar.texi(,7046) can be inconvenient, so @command{tar} provides a special option for
tar.texi(,7047) altering this behavior:
tar.texi(,7048) 
tar.texi(,7049) @anchor{show-transformed-names}
tar.texi(,7050) @table @option
tar.texi(,7051) @opindex show-transformed-names
tar.texi(,7052) @item --show-transformed-names
tar.texi(,7053) Display file or member names with all requested transformations
tar.texi(,7054) applied.
tar.texi(,7055) @end table
tar.texi(,7056) 
tar.texi(,7057) @noindent
tar.texi(,7058) For example:
tar.texi(,7059) 
tar.texi(,7060) @smallexample
tar.texi(,7061) @group
tar.texi(,7062) $ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h}
tar.texi(,7063) usr/include/stdlib.h
tar.texi(,7064) $ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h}
tar.texi(,7065) stdlib.h
tar.texi(,7066) @end group
tar.texi(,7067) @end smallexample
tar.texi(,7068) 
tar.texi(,7069) Notice that in both cases the file is @file{stdlib.h} extracted to the
tar.texi(,7070) current working directory, @option{--show-transformed-names} affects
tar.texi(,7071) only the way its name is displayed.
tar.texi(,7072) 
tar.texi(,7073) This option is especially useful for verifying whether the invocation
tar.texi(,7074) will have the desired effect.  Thus, before running
tar.texi(,7075) 
tar.texi(,7076) @smallexample
tar.texi(,7077) $ @kbd{tar -x --strip=@var{n}}
tar.texi(,7078) @end smallexample
tar.texi(,7079) 
tar.texi(,7080) @noindent
tar.texi(,7081) it is often advisable to run
tar.texi(,7082) 
tar.texi(,7083) @smallexample
tar.texi(,7084) $ @kbd{tar -t -v --show-transformed --strip=@var{n}}
tar.texi(,7085) @end smallexample
tar.texi(,7086) 
tar.texi(,7087) @noindent
tar.texi(,7088) to make sure the command will produce the intended results.
tar.texi(,7089) 
tar.texi(,7090) In case you need to apply more complex modifications to the file name,
tar.texi(GNUTAR,7091) @acronym{GNU} @command{tar} provides a general-purpose transformation option:
tar.texi(,7092) 
tar.texi(,7093) @table @option
tar.texi(,7094) @opindex transform
tar.texi(,7095) @item --transform=@var{expression}
tar.texi(,7096) Modify file names using supplied @var{expression}.
tar.texi(,7097) @end table
tar.texi(,7098) 
tar.texi(,7099) @noindent
tar.texi(,7100) The @var{expression} is a @command{sed}-like replace expression of the
tar.texi(,7101) form:
tar.texi(,7102) 
tar.texi(,7103) @smallexample
tar.texi(,7104) s/@var{regexp}/@var{replace}/[@var{flags}]
tar.texi(,7105) @end smallexample
tar.texi(,7106) 
tar.texi(,7107) @noindent
tar.texi(,7108) where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
tar.texi(,7109) replacement for each file name part that matches @var{regexp}.  Both
tar.texi(,7110) @var{regexp} and @var{replace} are described in detail in
tar.texi(,7111) @ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
tar.texi(,7112) 
tar.texi(,7113) Supported @var{flags} are:
tar.texi(,7114) 
tar.texi(,7115) @table @samp
tar.texi(,7116) @item g
tar.texi(,7117) Apply the replacement to @emph{all} matches to the @var{regexp}, not
tar.texi(,7118) just the first.
tar.texi(,7119) 
tar.texi(,7120) @item i
tar.texi(,7121) Use case-insensitive matching
tar.texi(,7122) 
tar.texi(,7123) @item x
tar.texi(,7124) @var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
tar.texi(,7125) regexps, Extended regular expressions, Extended regular expressions,
tar.texi(,7126) sed, GNU sed}).
tar.texi(,7127) 
tar.texi(,7128) @item @var{number}
tar.texi(,7129) Only replace the @var{number}th match of the @var{regexp}.
tar.texi(,7130) 
tar.texi(,7131) Note: the @var{posix} standard does not specify what should happen
tar.texi(GNUTAR,7132) when you mix the @samp{g} and @var{number} modifiers.  tar.texi(GNUTAR,7132) @acronym{GNU} @command{tar}
tar.texi(,7133) follows the GNU @command{sed} implementation in this regard, so
tar.texi(,7134) the the interaction is defined to be: ignore matches before the
tar.texi(,7135) @var{number}th, and then match and replace all matches from the
tar.texi(,7136) @var{number}th on.
tar.texi(,7137)                                    
tar.texi(,7138) @end table
tar.texi(,7139) 
tar.texi(,7140) Any delimiter can be used in lieue of @samp{/}, the only requirement being
tar.texi(,7141) that it be used consistently throughout the expression. For example,
tar.texi(,7142) the following two expressions are equivalent:
tar.texi(,7143) 
tar.texi(,7144) @smallexample
tar.texi(,7145) @group
tar.texi(,7146) s/one/two/
tar.texi(,7147) s,one,two,
tar.texi(,7148) @end group
tar.texi(,7149) @end smallexample
tar.texi(,7150) 
tar.texi(,7151) Changing delimiters is often useful when the @var{regex} contains
tar.texi(,7152) slashes.  For example, it is more convenient to write @code{s,/,-,} than
tar.texi(,7153) @code{s/\//-/}.
tar.texi(,7154) 
tar.texi(,7155) Here are several examples of @option{--transform} usage:
tar.texi(,7156) 
tar.texi(,7157) @enumerate
tar.texi(,7158) @item Extract @file{usr/} hierarchy into @file{usr/local/}:
tar.texi(,7159) 
tar.texi(,7160) @smallexample
tar.texi(,7161) $ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
tar.texi(,7162) @end smallexample
tar.texi(,7163) 
tar.texi(,7164) @item Strip two leading directory components (equivalent to
tar.texi(,7165) @option{--strip-components=2}):
tar.texi(,7166) 
tar.texi(,7167) @smallexample
tar.texi(,7168) $ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
tar.texi(,7169) @end smallexample
tar.texi(,7170) 
tar.texi(,7171) @item Prepend @file{/prefix/}  to each file name:
tar.texi(,7172) 
tar.texi(,7173) @smallexample
tar.texi(,7174) $ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
tar.texi(,7175) @end smallexample
tar.texi(,7176) 
tar.texi(,7177) @item Convert each file name to lower case:
tar.texi(,7178) 
tar.texi(,7179) @smallexample
tar.texi(,7180) $ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
tar.texi(,7181) @end smallexample
tar.texi(,7182) 
tar.texi(,7183) @end enumerate
tar.texi(,7184) 
tar.texi(,7185) Unlike @option{--strip-components}, @option{--transform} can be used
tar.texi(GNUTAR,7186) in any tar.texi(GNUTAR,7186) @acronym{GNU} @command{tar} operation mode.  For example, the following command
tar.texi(,7187) adds files to the archive while replacing the leading @file{usr/}
tar.texi(,7188) component with @file{var/}:
tar.texi(,7189) 
tar.texi(,7190) @smallexample
tar.texi(,7191) $ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /}
tar.texi(,7192) @end smallexample
tar.texi(,7193) 
tar.texi(,7194) To test @option{--transform} effect we suggest using
tar.texi(,7195) @option{--show-transformed-names} option:
tar.texi(,7196) 
tar.texi(,7197) @smallexample
tar.texi(,7198) $ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
tar.texi(,7199)        --verbose --show-transformed-names /}
tar.texi(,7200) @end smallexample
tar.texi(,7201) 
tar.texi(,7202) If both @option{--strip-components} and @option{--transform} are used
tar.texi(,7203) together, then @option{--transform} is applied first, and the required
tar.texi(,7204) number of components is then stripped from its result.
tar.texi(,7205)     
tar.texi(,7206) @node after
tar.texi(,7207) @section Operating Only on New Files
tar.texi(UNREVISED,7208) @quotation
tar.texi(UNREVISED,7208) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,7208) @end quotation
tar.texi(,7209) 
tar.texi(,7210) @cindex Excluding file by age
tar.texi(,7211) @cindex Data Modification time, excluding files by
tar.texi(,7212) @cindex Modification time, excluding files by
tar.texi(,7213) @cindex Age, excluding files by
tar.texi(,7214) The @option{--after-date=@var{date}} (@option{--newer=@var{date}},
tar.texi(,7215) @option{-N @var{date}}) option causes @command{tar} to only work on
tar.texi(,7216) files whose data modification or status change times are newer than
tar.texi(,7217) the @var{date} given.  If @var{date} starts with @samp{/} or @samp{.},
tar.texi(,7218) it is taken to be a file name; the data modification time of that file
tar.texi(,7219) is used as the date. If you use this option when creating or appending
tar.texi(,7220) to an archive, the archive will only include new files.  If you use
tar.texi(,7221) @option{--after-date} when extracting an archive, @command{tar} will
tar.texi(,7222) only extract files newer than the @var{date} you specify.
tar.texi(,7223) 
tar.texi(,7224) If you only want @command{tar} to make the date comparison based on
tar.texi(,7225) modification of the file's data (rather than status
tar.texi(,7226) changes), then use the @option{--newer-mtime=@var{date}} option.
tar.texi(,7227) 
tar.texi(,7228) You may use these options with any operation.  Note that these options
tar.texi(,7229) differ from the @option{--update} (@option{-u}) operation in that they
tar.texi(,7230) allow you to specify a particular date against which @command{tar} can
tar.texi(,7231) compare when deciding whether or not to archive the files.
tar.texi(,7232) 
tar.texi(,7233) @table @option
tar.texi(,7234) @opindex after-date
tar.texi(,7235) @opindex newer
tar.texi(,7236) @item --after-date=@var{date}
tar.texi(,7237) @itemx --newer=@var{date}
tar.texi(,7238) @itemx -N @var{date}
tar.texi(,7239) Only store files newer than @var{date}.
tar.texi(,7240) 
tar.texi(,7241) Acts on files only if their data modification or status change times are
tar.texi(,7242) later than @var{date}.  Use in conjunction with any operation.
tar.texi(,7243) 
tar.texi(,7244) If @var{date} starts with @samp{/} or @samp{.}, it is taken to be a file
tar.texi(,7245) name; the data modification time of that file is used as the date.
tar.texi(,7246) 
tar.texi(,7247) @opindex newer-mtime
tar.texi(,7248) @item --newer-mtime=@var{date}
tar.texi(,7249) Acts like @option{--after-date}, but only looks at data modification times.
tar.texi(,7250) @end table
tar.texi(,7251) 
tar.texi(,7252) These options limit @command{tar} to operate only on files which have
tar.texi(,7253) been modified after the date specified.  A file's status is considered to have
tar.texi(,7254) changed if its contents have been modified, or if its owner,
tar.texi(,7255) permissions, and so forth, have been changed.  (For more information on
tar.texi(,7256) how to specify a date, see @ref{Date input formats}; remember that the
tar.texi(,7257) entire date argument must be quoted if it contains any spaces.)
tar.texi(,7258) 
tar.texi(,7259) Gurus would say that @option{--after-date} tests both the data
tar.texi(,7260) modification time (@code{mtime}, the time the contents of the file
tar.texi(,7261) were last modified) and the status change time (@code{ctime}, the time
tar.texi(,7262) the file's status was last changed: owner, permissions, etc.@:)
tar.texi(,7263) fields, while @option{--newer-mtime} tests only the @code{mtime}
tar.texi(,7264) field.
tar.texi(,7265) 
tar.texi(,7266) To be precise, @option{--after-date} checks @emph{both} @code{mtime} and
tar.texi(,7267) @code{ctime} and processes the file if either one is more recent than
tar.texi(,7268) @var{date}, while @option{--newer-mtime} only checks @code{mtime} and
tar.texi(,7269) disregards @code{ctime}.  Neither does it use @code{atime} (the last time the
tar.texi(,7270) contents of the file were looked at).
tar.texi(,7271) 
tar.texi(,7272) Date specifiers can have embedded spaces.  Because of this, you may need
tar.texi(,7273) to quote date arguments to keep the shell from parsing them as separate
tar.texi(,7274) arguments.  For example, the following command will add to the archive
tar.texi(,7275) all the files modified less than two days ago:
tar.texi(,7276) 
tar.texi(,7277) @smallexample
tar.texi(,7278) $ @kbd{tar -cf foo.tar --newer-mtime '2 days ago'}
tar.texi(,7279) @end smallexample
tar.texi(,7280) 
tar.texi(,7281) When any of these options is used with the option @option{--verbose}
tar.texi(GNUTAR,7282) (@pxref{verbose tutorial}) tar.texi(GNUTAR,7282) @acronym{GNU} @command{tar} will try to convert the specified
tar.texi(,7283) date back to its textual representation and compare that with the
tar.texi(,7284) one given with the option.  If the two dates differ, @command{tar} will
tar.texi(,7285) print a warning saying what date it will use.  This is to help user
tar.texi(,7286) ensure he is using the right date.  For example:
tar.texi(,7287) 
tar.texi(,7288) @smallexample
tar.texi(,7289) @group
tar.texi(,7290) $ @kbd{tar -c -f archive.tar --after-date='10 days ago' .}
tar.texi(,7291) tar: Option --after-date: Treating date `10 days ago' as 2006-06-11
tar.texi(,7292) 13:19:37.232434
tar.texi(,7293) @end group
tar.texi(,7294) @end smallexample
tar.texi(,7295) 
tar.texi(,7296) @quotation
tar.texi(,7297) @strong{Please Note:} @option{--after-date} and @option{--newer-mtime}
tar.texi(,7298) should not be used for incremental backups.  @xref{Incremental Dumps},
tar.texi(,7299) for proper way of creating incremental backups.
tar.texi(,7300) @end quotation
tar.texi(,7301) 
tar.texi(,7302) @node recurse
tar.texi(,7303) @section Descending into Directories
tar.texi(UNREVISED,7304) @quotation
tar.texi(UNREVISED,7304) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,7304) @end quotation
tar.texi(,7305) @cindex Avoiding recursion in directories
tar.texi(,7306) @cindex Descending directories, avoiding
tar.texi(,7307) @cindex Directories, avoiding recursion
tar.texi(,7308) @cindex Recursion in directories, avoiding
tar.texi(,7309) 
tar.texi(FIXME,7310) @allow-recursion
tar.texi(FIXME,7310) @quote-arg
tar.texi(FIXME,7310) 
tar.texi(,7311) 
tar.texi(,7312) Usually, @command{tar} will recursively explore all directories (either
tar.texi(,7313) those given on the command line or through the @option{--files-from}
tar.texi(,7314) option) for the various files they contain.  However, you may not always
tar.texi(,7315) want @command{tar} to act this way.
tar.texi(,7316) 
tar.texi(,7317) @opindex no-recursion
tar.texi(,7318) The @option{--no-recursion} option inhibits @command{tar}'s recursive descent
tar.texi(,7319) into specified directories.  If you specify @option{--no-recursion}, you can
tar.texi(,7320) use the @command{find} utility for hunting through levels of directories to
tar.texi(,7321) construct a list of file names which you could then pass to @command{tar}.
tar.texi(,7322) @command{find} allows you to be more selective when choosing which files to
tar.texi(,7323) archive; see @ref{files}, for more information on using @command{find} with
tar.texi(,7324) @command{tar}, or look.
tar.texi(,7325) 
tar.texi(,7326) @table @option
tar.texi(,7327) @item --no-recursion
tar.texi(,7328) Prevents @command{tar} from recursively descending directories.
tar.texi(,7329) 
tar.texi(,7330) @opindex recursion
tar.texi(,7331) @item --recursion
tar.texi(,7332) Requires @command{tar} to recursively descend directories.
tar.texi(,7333) This is the default.
tar.texi(,7334) @end table
tar.texi(,7335) 
tar.texi(GNUTAR,7336) When you use @option{--no-recursion}, tar.texi(GNUTAR,7336) @acronym{GNU} @command{tar} grabs
tar.texi(,7337) directory entries themselves, but does not descend on them
tar.texi(,7338) recursively.  Many people use @command{find} for locating files they
tar.texi(,7339) want to back up, and since @command{tar} @emph{usually} recursively
tar.texi(,7340) descends on directories, they have to use the @samp{@w{-not -type d}}
tar.texi(,7341) test in their @command{find} invocation (@pxref{Type, Type, Type test,
tar.texi(,7342) find, Finding Files}), as they usually do not want all the files in a
tar.texi(,7343) directory. They then use the @option{--files-from} option to archive
tar.texi(,7344) the files located via @command{find}.
tar.texi(,7345) 
tar.texi(,7346) The problem when restoring files archived in this manner is that the
tar.texi(,7347) directories themselves are not in the archive; so the
tar.texi(,7348) @option{--same-permissions} (@option{--preserve-permissions},
tar.texi(,7349) @option{-p}) option does not affect them---while users might really
tar.texi(,7350) like it to.  Specifying @option{--no-recursion} is a way to tell
tar.texi(,7351) @command{tar} to grab only the directory entries given to it, adding
tar.texi(,7352) no new files on its own.  To summarize, if you use @command{find} to
tar.texi(,7353) create a list of files to be stored in an archive, use it as follows:
tar.texi(,7354) 
tar.texi(,7355) @smallexample
tar.texi(,7356) @group
tar.texi(,7357) $ @kbd{find @var{dir} @var{tests} | \
tar.texi(,7358)   tar -cf @var{archive} -T - --no-recursion}
tar.texi(,7359) @end group
tar.texi(,7360) @end smallexample
tar.texi(,7361) 
tar.texi(,7362) The @option{--no-recursion} option also applies when extracting: it
tar.texi(,7363) causes @command{tar} to extract only the matched directory entries, not
tar.texi(,7364) the files under those directories.
tar.texi(,7365) 
tar.texi(,7366) The @option{--no-recursion} option also affects how globbing patterns
tar.texi(,7367) are interpreted (@pxref{controlling pattern-matching}).
tar.texi(,7368) 
tar.texi(,7369) The @option{--no-recursion} and @option{--recursion} options apply to
tar.texi(,7370) later options and operands, and can be overridden by later occurrences
tar.texi(,7371) of @option{--no-recursion} and @option{--recursion}.  For example:
tar.texi(,7372) 
tar.texi(,7373) @smallexample
tar.texi(,7374) $ @kbd{tar -cf jams.tar --no-recursion grape --recursion grape/concord}
tar.texi(,7375) @end smallexample
tar.texi(,7376) 
tar.texi(,7377) @noindent
tar.texi(,7378) creates an archive with one entry for @file{grape}, and the recursive
tar.texi(,7379) contents of @file{grape/concord}, but no entries under @file{grape}
tar.texi(,7380) other than @file{grape/concord}.
tar.texi(,7381) 
tar.texi(,7382) @node one
tar.texi(,7383) @section Crossing File System Boundaries
tar.texi(,7384) @cindex File system boundaries, not crossing
tar.texi(UNREVISED,7385) @quotation
tar.texi(UNREVISED,7385) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,7385) @end quotation
tar.texi(,7386) 
tar.texi(,7387) @command{tar} will normally automatically cross file system boundaries in
tar.texi(,7388) order to archive files which are part of a directory tree.  You can
tar.texi(,7389) change this behavior by running @command{tar} and specifying
tar.texi(,7390) @option{--one-file-system}.  This option only affects files that are
tar.texi(,7391) archived because they are in a directory that is being archived;
tar.texi(,7392) @command{tar} will still archive files explicitly named on the command line
tar.texi(,7393) or through @option{--files-from}, regardless of where they reside.
tar.texi(,7394) 
tar.texi(,7395) @table @option
tar.texi(,7396) @opindex one-file-system
tar.texi(,7397) @item --one-file-system
tar.texi(,7398) Prevents @command{tar} from crossing file system boundaries when
tar.texi(,7399) archiving.  Use in conjunction with any write operation.
tar.texi(,7400) @end table
tar.texi(,7401) 
tar.texi(,7402) The @option{--one-file-system} option causes @command{tar} to modify its
tar.texi(,7403) normal behavior in archiving the contents of directories.  If a file in
tar.texi(,7404) a directory is not on the same file system as the directory itself, then
tar.texi(,7405) @command{tar} will not archive that file.  If the file is a directory
tar.texi(,7406) itself, @command{tar} will not archive anything beneath it; in other words,
tar.texi(,7407) @command{tar} will not cross mount points.
tar.texi(,7408) 
tar.texi(,7409) This option is useful for making full or incremental archival backups of
tar.texi(,7410) a file system.  If this option is used in conjunction with
tar.texi(,7411) @option{--verbose} (@option{-v}), files that are excluded are
tar.texi(,7412) mentioned by name on the standard error.
tar.texi(,7413) 
tar.texi(,7414) @menu
tar.texi(,7415) * directory::                   Changing Directory
tar.texi(,7416) * absolute::                    Absolute File Names
tar.texi(,7417) @end menu
tar.texi(,7418) 
tar.texi(,7419) @node directory
tar.texi(,7420) @subsection Changing the Working Directory
tar.texi(UNREVISED,7421) @quotation
tar.texi(UNREVISED,7421) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,7421) @end quotation
tar.texi(,7422) 
tar.texi(FIXME,7424) @allow-recursion
tar.texi(FIXME,7424) @quote-arg
tar.texi(FIXME,7424) 
tar.texi(,7425) 
tar.texi(,7426) @cindex Changing directory mid-stream
tar.texi(,7427) @cindex Directory, changing mid-stream
tar.texi(,7428) @cindex Working directory, specifying
tar.texi(,7429) To change the working directory in the middle of a list of file names,
tar.texi(,7430) either on the command line or in a file specified using
tar.texi(,7431) @option{--files-from} (@option{-T}), use @option{--directory} (@option{-C}).
tar.texi(,7432) This will change the working directory to the specified directory
tar.texi(,7433) after that point in the list.
tar.texi(,7434) 
tar.texi(,7435) @table @option
tar.texi(,7436) @opindex directory
tar.texi(,7437) @item --directory=@var{directory}
tar.texi(,7438) @itemx -C @var{directory}
tar.texi(,7439) Changes the working directory in the middle of a command line.
tar.texi(,7440) @end table
tar.texi(,7441) 
tar.texi(,7442) For example,
tar.texi(,7443) 
tar.texi(,7444) @smallexample
tar.texi(,7445) $ @kbd{tar -c -f jams.tar grape prune -C food cherry}
tar.texi(,7446) @end smallexample
tar.texi(,7447) 
tar.texi(,7448) @noindent
tar.texi(,7449) will place the files @file{grape} and @file{prune} from the current
tar.texi(,7450) directory into the archive @file{jams.tar}, followed by the file
tar.texi(,7451) @file{cherry} from the directory @file{food}.  This option is especially
tar.texi(,7452) useful when you have several widely separated files that you want to
tar.texi(,7453) store in the same archive.
tar.texi(,7454) 
tar.texi(,7455) Note that the file @file{cherry} is recorded in the archive under the
tar.texi(,7456) precise name @file{cherry}, @emph{not} @file{food/cherry}.  Thus, the
tar.texi(,7457) archive will contain three files that all appear to have come from the
tar.texi(,7458) same directory; if the archive is extracted with plain @samp{tar
tar.texi(,7459) --extract}, all three files will be written in the current directory.
tar.texi(,7460) 
tar.texi(,7461) Contrast this with the command,
tar.texi(,7462) 
tar.texi(,7463) @smallexample
tar.texi(,7464) $ @kbd{tar -c -f jams.tar grape prune -C food red/cherry}
tar.texi(,7465) @end smallexample
tar.texi(,7466) 
tar.texi(,7467) @noindent
tar.texi(,7468) which records the third file in the archive under the name
tar.texi(,7469) @file{red/cherry} so that, if the archive is extracted using
tar.texi(,7470) @samp{tar --extract}, the third file will be written in a subdirectory
tar.texi(,7471) named @file{orange-colored}.
tar.texi(,7472) 
tar.texi(,7473) You can use the @option{--directory} option to make the archive
tar.texi(,7474) independent of the original name of the directory holding the files.
tar.texi(,7475) The following command places the files @file{/etc/passwd},
tar.texi(,7476) @file{/etc/hosts}, and @file{/lib/libc.a} into the archive
tar.texi(,7477) @file{foo.tar}:
tar.texi(,7478) 
tar.texi(,7479) @smallexample
tar.texi(,7480) $ @kbd{tar -c -f foo.tar -C /etc passwd hosts -C /lib libc.a}
tar.texi(,7481) @end smallexample
tar.texi(,7482) 
tar.texi(,7483) @noindent
tar.texi(,7484) However, the names of the archive members will be exactly what they were
tar.texi(,7485) on the command line: @file{passwd}, @file{hosts}, and @file{libc.a}.
tar.texi(,7486) They will not appear to be related by file name to the original
tar.texi(,7487) directories where those files were located.
tar.texi(,7488) 
tar.texi(,7489) Note that @option{--directory} options are interpreted consecutively.  If
tar.texi(,7490) @option{--directory} specifies a relative file name, it is interpreted
tar.texi(,7491) relative to the then current directory, which might not be the same as
tar.texi(,7492) the original current working directory of @command{tar}, due to a previous
tar.texi(,7493) @option{--directory} option.
tar.texi(,7494) 
tar.texi(,7495) When using @option{--files-from} (@pxref{files}), you can put various
tar.texi(,7496) @command{tar} options (including @option{-C}) in the file list.  Notice,
tar.texi(,7497) however, that in this case the option and its argument may not be
tar.texi(,7498) separated by whitespace.  If you use short option, its argument must
tar.texi(,7499) either follow the option letter immediately, without any intervening
tar.texi(,7500) whitespace, or occupy the next line.  Otherwise, if you use long
tar.texi(,7501) option, separate its argument by an equal sign.
tar.texi(,7502) 
tar.texi(,7503) For instance, the file list for the above example will be:
tar.texi(,7504) 
tar.texi(,7505) @smallexample
tar.texi(,7506) @group
tar.texi(,7507) -C
tar.texi(,7508) /etc
tar.texi(,7509) passwd
tar.texi(,7510) hosts
tar.texi(,7511) -C
tar.texi(,7512) /lib
tar.texi(,7513) libc.a
tar.texi(,7514) @end group
tar.texi(,7515) @end smallexample
tar.texi(,7516) 
tar.texi(,7517) @noindent
tar.texi(,7518) To use it, you would invoke @command{tar} as follows:
tar.texi(,7519) 
tar.texi(,7520) @smallexample
tar.texi(,7521) $ @kbd{tar -c -f foo.tar --files-from list}
tar.texi(,7522) @end smallexample
tar.texi(,7523) 
tar.texi(,7524) Notice also that you can only use the short option variant in the file
tar.texi(,7525) list, i.e., always use @option{-C}, not @option{--directory}.
tar.texi(,7526) 
tar.texi(,7527) The interpretation of @option{--directory} is disabled by
tar.texi(,7528) @option{--null} option.
tar.texi(,7529) 
tar.texi(,7530) @node absolute
tar.texi(,7531) @subsection Absolute File Names
tar.texi(UNREVISED,7532) @quotation
tar.texi(UNREVISED,7532) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,7532) @end quotation
tar.texi(,7533) 
tar.texi(,7534) @table @option
tar.texi(,7535) @opindex absolute-names
tar.texi(,7536) @item --absolute-names
tar.texi(,7537) @itemx -P
tar.texi(,7538) Do not strip leading slashes from file names, and permit file names
tar.texi(,7539) containing a @file{..} file name component.
tar.texi(,7540) @end table
tar.texi(,7541) 
tar.texi(GNUTAR,7542) By default, tar.texi(GNUTAR,7542) @acronym{GNU} @command{tar} drops a leading @samp{/} on
tar.texi(,7543) input or output, and complains about file names containing a @file{..}
tar.texi(,7544) component.  This option turns off this behavior.
tar.texi(,7545) 
tar.texi(,7546) When @command{tar} extracts archive members from an archive, it strips any
tar.texi(,7547) leading slashes (@samp{/}) from the member name.  This causes absolute
tar.texi(,7548) member names in the archive to be treated as relative file names.  This
tar.texi(,7549) allows you to have such members extracted wherever you want, instead of
tar.texi(,7550) being restricted to extracting the member in the exact directory named
tar.texi(,7551) in the archive.  For example, if the archive member has the name
tar.texi(,7552) @file{/etc/passwd}, @command{tar} will extract it as if the name were
tar.texi(,7553) really @file{etc/passwd}.
tar.texi(,7554) 
tar.texi(,7555) File names containing @file{..} can cause problems when extracting, so
tar.texi(,7556) @command{tar} normally warns you about such files when creating an
tar.texi(,7557) archive, and rejects attempts to extracts such files.
tar.texi(,7558) 
tar.texi(,7559) Other @command{tar} programs do not do this.  As a result, if you
tar.texi(,7560) create an archive whose member names start with a slash, they will be
tar.texi(GNUTAR,7561) difficult for other people with a non-tar.texi(GNUTAR,7561) @acronym{GNU} @command{tar}
tar.texi(GNUTAR,7562) program to use.  Therefore, tar.texi(GNUTAR,7562) @acronym{GNU} @command{tar} also strips
tar.texi(,7563) leading slashes from member names when putting members into the
tar.texi(,7564) archive.  For example, if you ask @command{tar} to add the file
tar.texi(,7565) @file{/bin/ls} to an archive, it will do so, but the member name will
tar.texi(,7566) be @file{bin/ls}.@footnote{A side effect of this is that when
tar.texi(,7567) @option{--create} is used with @option{--verbose} the resulting output
tar.texi(,7568) is not, generally speaking, the same as the one you'd get running
tar.texi(,7569) @kbd{tar --list} command.  This may be important if you use some
tar.texi(,7570) scripts for comparing both outputs.  @xref{listing member and file names},
tar.texi(,7571) for the information on how to handle this case.}
tar.texi(,7572) 
tar.texi(,7573) If you use the @option{--absolute-names} (@option{-P}) option,
tar.texi(,7574) @command{tar} will do none of these transformations.
tar.texi(,7575) 
tar.texi(,7576) To archive or extract files relative to the root directory, specify
tar.texi(,7577) the @option{--absolute-names} (@option{-P}) option.
tar.texi(,7578) 
tar.texi(,7579) Normally, @command{tar} acts on files relative to the working
tar.texi(,7580) directory---ignoring superior directory names when archiving, and
tar.texi(,7581) ignoring leading slashes when extracting.
tar.texi(,7582) 
tar.texi(,7583) When you specify @option{--absolute-names} (@option{-P}),
tar.texi(,7584) @command{tar} stores file names including all superior directory
tar.texi(,7585) names, and preserves leading slashes.  If you only invoked
tar.texi(,7586) @command{tar} from the root directory you would never need the
tar.texi(,7587) @option{--absolute-names} option, but using this option
tar.texi(,7588) may be more convenient than switching to root.
tar.texi(,7589) 
tar.texi(FIXME,7591) @allow-recursion
tar.texi(FIXME,7591) @quote-arg
tar.texi(FIXME,7591) 
tar.texi(,7592) 
tar.texi(FIXME,7593) @allow-recursion
tar.texi(FIXME,7593) @quote-arg
tar.texi(FIXME,7593) 
tar.texi(,7594) 
tar.texi(,7595) @table @option
tar.texi(,7596) @item --absolute-names
tar.texi(,7597) Preserves full file names (including superior directory names) when
tar.texi(,7598) archiving files.  Preserves leading slash when extracting files.
tar.texi(,7599) 
tar.texi(,7600) @end table
tar.texi(,7601) 
tar.texi(FIXME,7602) @allow-recursion
tar.texi(FIXME,7602) @quote-arg
tar.texi(FIXME,7602) 
tar.texi(,7603) 
tar.texi(,7604) @command{tar} prints out a message about removing the @samp{/} from
tar.texi(GNUTAR,7605) file names.  This message appears once per tar.texi(GNUTAR,7605) @acronym{GNU} @command{tar}
tar.texi(,7606) invocation.  It represents something which ought to be told; ignoring
tar.texi(,7607) what it means can cause very serious surprises, later.
tar.texi(,7608) 
tar.texi(,7609) Some people, nevertheless, do not want to see this message.  Wanting to
tar.texi(,7610) play really dangerously, one may of course redirect @command{tar} standard
tar.texi(,7611) error to the sink.  For example, under @command{sh}:
tar.texi(,7612) 
tar.texi(,7613) @smallexample
tar.texi(,7614) $ @kbd{tar -c -f archive.tar /home 2> /dev/null}
tar.texi(,7615) @end smallexample
tar.texi(,7616) 
tar.texi(,7617) @noindent
tar.texi(,7618) Another solution, both nicer and simpler, would be to change to
tar.texi(,7619) the @file{/} directory first, and then avoid absolute notation.
tar.texi(,7620) For example:
tar.texi(,7621) 
tar.texi(,7622) @smallexample
tar.texi(,7623) $ @kbd{(cd / && tar -c -f archive.tar home)}
tar.texi(,7624) # @i{or}:
tar.texi(,7625) $ @kbd{tar -c -f archive.tar -C  / home}
tar.texi(,7626) @end smallexample
tar.texi(,7627) 
getdate.texi(,1) @c GNU date syntax documentation
getdate.texi(,2) 
getdate.texi(,3) @c Copyright (C) 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002,
getdate.texi(,4) @c 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
getdate.texi(,5) 
getdate.texi(,6) @c Permission is granted to copy, distribute and/or modify this document
getdate.texi(,7) @c under the terms of the GNU Free Documentation License, Version 1.1 or
getdate.texi(,8) @c any later version published by the Free Software Foundation; with no
getdate.texi(,9) @c Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
getdate.texi(,10) @c Texts.  A copy of the license is included in the ``GNU Free
getdate.texi(,11) @c Documentation License'' file as part of this distribution.
getdate.texi(,12) 
getdate.texi(,13) @node Date input formats
getdate.texi(,14) @chapter Date input formats
getdate.texi(,15) 
getdate.texi(,16) @cindex date input formats
getdate.texi(,17) @findex get_date
getdate.texi(,18) 
getdate.texi(,19) First, a quote:
getdate.texi(,20) 
getdate.texi(,21) @quotation
getdate.texi(,22) Our units of temporal measurement, from seconds on up to months, are so
getdate.texi(,23) complicated, asymmetrical and disjunctive so as to make coherent mental
getdate.texi(,24) reckoning in time all but impossible.  Indeed, had some tyrannical god
getdate.texi(,25) contrived to enslave our minds to time, to make it all but impossible
getdate.texi(,26) for us to escape subjection to sodden routines and unpleasant surprises,
getdate.texi(,27) he could hardly have done better than handing down our present system.
getdate.texi(,28) It is like a set of trapezoidal building blocks, with no vertical or
getdate.texi(,29) horizontal surfaces, like a language in which the simplest thought
getdate.texi(,30) demands ornate constructions, useless particles and lengthy
getdate.texi(,31) circumlocutions.  Unlike the more successful patterns of language and
getdate.texi(,32) science, which enable us to face experience boldly or at least
getdate.texi(,33) level-headedly, our system of temporal calculation silently and
getdate.texi(,34) persistently encourages our terror of time.
getdate.texi(,35) 
getdate.texi(,36) @dots{}  It is as though architects had to measure length in feet, width
getdate.texi(,37) in meters and height in ells; as though basic instruction manuals
getdate.texi(,38) demanded a knowledge of five different languages.  It is no wonder then
getdate.texi(,39) that we often look into our own immediate past or future, last Tuesday
getdate.texi(,40) or a week from Sunday, with feelings of helpless confusion.  @dots{}
getdate.texi(,41) 
getdate.texi(,42) --- Robert Grudin, @cite{Time and the Art of Living}.
getdate.texi(,43) @end quotation
getdate.texi(,44) 
getdate.texi(,45) This section describes the textual date representations that @sc{gnu}
getdate.texi(,46) programs accept.  These are the strings you, as a user, can supply as
getdate.texi(,47) arguments to the various programs.  The C interface (via the
getdate.texi(,48) @code{get_date} function) is not described here.
getdate.texi(,49) 
getdate.texi(,50) @menu
getdate.texi(,51) * General date syntax::            Common rules.
getdate.texi(,52) * Calendar date items::            19 Dec 1994.
getdate.texi(,53) * Time of day items::              9:20pm.
getdate.texi(,54) * Time zone items::                @sc{est}, @sc{pdt}, @sc{gmt}.
getdate.texi(,55) * Day of week items::              Monday and others.
getdate.texi(,56) * Relative items in date strings:: next tuesday, 2 years ago.
getdate.texi(,57) * Pure numbers in date strings::   19931219, 1440.
getdate.texi(,58) * Seconds since the Epoch::        @@1078100502.
getdate.texi(,59) * Specifying time zone rules::     TZ="America/New_York", TZ="UTC0".
getdate.texi(,60) * Authors of get_date::            Bellovin, Eggert, Salz, Berets, et al.
getdate.texi(,61) @end menu
getdate.texi(,62) 
getdate.texi(,63) 
getdate.texi(,64) @node General date syntax
getdate.texi(,65) @section General date syntax
getdate.texi(,66) 
getdate.texi(,67) @cindex general date syntax
getdate.texi(,68) 
getdate.texi(,69) @cindex items in date strings
getdate.texi(,70) A @dfn{date} is a string, possibly empty, containing many items
getdate.texi(,71) separated by whitespace.  The whitespace may be omitted when no
getdate.texi(,72) ambiguity arises.  The empty string means the beginning of today (i.e.,
getdate.texi(,73) midnight).  Order of the items is immaterial.  A date string may contain
getdate.texi(,74) many flavors of items:
getdate.texi(,75) 
getdate.texi(,76) @itemize @bullet
getdate.texi(,77) @item calendar date items
getdate.texi(,78) @item time of day items
getdate.texi(,79) @item time zone items
getdate.texi(,80) @item day of the week items
getdate.texi(,81) @item relative items
getdate.texi(,82) @item pure numbers.
getdate.texi(,83) @end itemize
getdate.texi(,84) 
getdate.texi(,85) @noindent We describe each of these item types in turn, below.
getdate.texi(,86) 
getdate.texi(,87) @cindex numbers, written-out
getdate.texi(,88) @cindex ordinal numbers
getdate.texi(,89) @findex first @r{in date strings}
getdate.texi(,90) @findex next @r{in date strings}
getdate.texi(,91) @findex last @r{in date strings}
getdate.texi(,92) A few ordinal numbers may be written out in words in some contexts.  This is
getdate.texi(,93) most useful for specifying day of the week items or relative items (see
getdate.texi(,94) below).  Among the most commonly used ordinal numbers, the word
getdate.texi(,95) @samp{last} stands for @math{-1}, @samp{this} stands for 0, and
getdate.texi(,96) @samp{first} and @samp{next} both stand for 1.  Because the word
getdate.texi(,97) @samp{second} stands for the unit of time there is no way to write the
getdate.texi(,98) ordinal number 2, but for convenience @samp{third} stands for 3,
getdate.texi(,99) @samp{fourth} for 4, @samp{fifth} for 5,
getdate.texi(,100) @samp{sixth} for 6, @samp{seventh} for 7, @samp{eighth} for 8,
getdate.texi(,101) @samp{ninth} for 9, @samp{tenth} for 10, @samp{eleventh} for 11 and
getdate.texi(,102) @samp{twelfth} for 12.
getdate.texi(,103) 
getdate.texi(,104) @cindex months, written-out
getdate.texi(,105) When a month is written this way, it is still considered to be written
getdate.texi(,106) numerically, instead of being ``spelled in full''; this changes the
getdate.texi(,107) allowed strings.
getdate.texi(,108) 
getdate.texi(,109) @cindex language, in dates
getdate.texi(,110) In the current implementation, only English is supported for words and
getdate.texi(,111) abbreviations like @samp{AM}, @samp{DST}, @samp{EST}, @samp{first},
getdate.texi(,112) @samp{January}, @samp{Sunday}, @samp{tomorrow}, and @samp{year}.
getdate.texi(,113) 
getdate.texi(,114) @cindex language, in dates
getdate.texi(,115) @cindex time zone item
getdate.texi(,116) The output of the @command{date} command
getdate.texi(,117) is not always acceptable as a date string,
getdate.texi(,118) not only because of the language problem, but also because there is no
getdate.texi(,119) standard meaning for time zone items like @samp{IST}.  When using
getdate.texi(,120) @command{date} to generate a date string intended to be parsed later,
getdate.texi(,121) specify a date format that is independent of language and that does not
getdate.texi(,122) use time zone items other than @samp{UTC} and @samp{Z}.  Here are some
getdate.texi(,123) ways to do this:
getdate.texi(,124) 
getdate.texi(,125) @example
getdate.texi(,126) $ LC_ALL=C TZ=UTC0 date
getdate.texi(,127) Mon Mar  1 00:21:42 UTC 2004
getdate.texi(,128) $ TZ=UTC0 date +'%Y-%m-%d %H:%M:%SZ'
getdate.texi(,129) 2004-03-01 00:21:42Z
getdate.texi(,130) $ date --iso-8601=ns | tr T ' '  # --iso-8601 is a GNU extension.
getdate.texi(,131) 2004-02-29 16:21:42,692722128-0800
getdate.texi(,132) $ date --rfc-2822  # a GNU extension
getdate.texi(,133) Sun, 29 Feb 2004 16:21:42 -0800
getdate.texi(,134) $ date +'%Y-%m-%d %H:%M:%S %z'  # %z is a GNU extension.
getdate.texi(,135) 2004-02-29 16:21:42 -0800
getdate.texi(,136) $ date +'@@%s.%N'  # %s and %N are GNU extensions.
getdate.texi(,137) @@1078100502.692722128
getdate.texi(,138) @end example
getdate.texi(,139) 
getdate.texi(,140) @cindex case, ignored in dates
getdate.texi(,141) @cindex comments, in dates
getdate.texi(,142) Alphabetic case is completely ignored in dates.  Comments may be introduced
getdate.texi(,143) between round parentheses, as long as included parentheses are properly
getdate.texi(,144) nested.  Hyphens not followed by a digit are currently ignored.  Leading
getdate.texi(,145) zeros on numbers are ignored.
getdate.texi(,146) 
getdate.texi(,147) Invalid dates like @samp{2005-02-29} or times like @samp{24:00} are
getdate.texi(,148) rejected.  In the typical case of a host that does not support leap
getdate.texi(,149) seconds, a time like @samp{23:59:60} is rejected even if it
getdate.texi(,150) corresponds to a valid leap second.
getdate.texi(,151) 
getdate.texi(,152) 
getdate.texi(,153) @node Calendar date items
getdate.texi(,154) @section Calendar date items
getdate.texi(,155) 
getdate.texi(,156) @cindex calendar date item
getdate.texi(,157) 
getdate.texi(,158) A @dfn{calendar date item} specifies a day of the year.  It is
getdate.texi(,159) specified differently, depending on whether the month is specified
getdate.texi(,160) numerically or literally.  All these strings specify the same calendar date:
getdate.texi(,161) 
getdate.texi(,162) @example
getdate.texi(,163) 1972-09-24     # @sc{iso} 8601.
getdate.texi(,164) 72-9-24        # Assume 19xx for 69 through 99,
getdate.texi(,165)                # 20xx for 00 through 68.
getdate.texi(,166) 72-09-24       # Leading zeros are ignored.
getdate.texi(,167) 9/24/72        # Common U.S. writing.
getdate.texi(,168) 24 September 1972
getdate.texi(,169) 24 Sept 72     # September has a special abbreviation.
getdate.texi(,170) 24 Sep 72      # Three-letter abbreviations always allowed.
getdate.texi(,171) Sep 24, 1972
getdate.texi(,172) 24-sep-72
getdate.texi(,173) 24sep72
getdate.texi(,174) @end example
getdate.texi(,175) 
getdate.texi(,176) The year can also be omitted.  In this case, the last specified year is
getdate.texi(,177) used, or the current year if none.  For example:
getdate.texi(,178) 
getdate.texi(,179) @example
getdate.texi(,180) 9/24
getdate.texi(,181) sep 24
getdate.texi(,182) @end example
getdate.texi(,183) 
getdate.texi(,184) Here are the rules.
getdate.texi(,185) 
getdate.texi(,186) @cindex @sc{iso} 8601 date format
getdate.texi(,187) @cindex date format, @sc{iso} 8601
getdate.texi(,188) For numeric months, the @sc{iso} 8601 format
getdate.texi(,189) @samp{@var{year}-@var{month}-@var{day}} is allowed, where @var{year} is
getdate.texi(,190) any positive number, @var{month} is a number between 01 and 12, and
getdate.texi(,191) @var{day} is a number between 01 and 31.  A leading zero must be present
getdate.texi(,192) if a number is less than ten.  If @var{year} is 68 or smaller, then 2000
getdate.texi(,193) is added to it; otherwise, if @var{year} is less than 100,
getdate.texi(,194) then 1900 is added to it.  The construct
getdate.texi(,195) @samp{@var{month}/@var{day}/@var{year}}, popular in the United States,
getdate.texi(,196) is accepted.  Also @samp{@var{month}/@var{day}}, omitting the year.
getdate.texi(,197) 
getdate.texi(,198) @cindex month names in date strings
getdate.texi(,199) @cindex abbreviations for months
getdate.texi(,200) Literal months may be spelled out in full: @samp{January},
getdate.texi(,201) @samp{February}, @samp{March}, @samp{April}, @samp{May}, @samp{June},
getdate.texi(,202) @samp{July}, @samp{August}, @samp{September}, @samp{October},
getdate.texi(,203) @samp{November} or @samp{December}.  Literal months may be abbreviated
getdate.texi(,204) to their first three letters, possibly followed by an abbreviating dot.
getdate.texi(,205) It is also permitted to write @samp{Sept} instead of @samp{September}.
getdate.texi(,206) 
getdate.texi(,207) When months are written literally, the calendar date may be given as any
getdate.texi(,208) of the following:
getdate.texi(,209) 
getdate.texi(,210) @example
getdate.texi(,211) @var{day} @var{month} @var{year}
getdate.texi(,212) @var{day} @var{month}
getdate.texi(,213) @var{month} @var{day} @var{year}
getdate.texi(,214) @var{day}-@var{month}-@var{year}
getdate.texi(,215) @end example
getdate.texi(,216) 
getdate.texi(,217) Or, omitting the year:
getdate.texi(,218) 
getdate.texi(,219) @example
getdate.texi(,220) @var{month} @var{day}
getdate.texi(,221) @end example
getdate.texi(,222) 
getdate.texi(,223) 
getdate.texi(,224) @node Time of day items
getdate.texi(,225) @section Time of day items
getdate.texi(,226) 
getdate.texi(,227) @cindex time of day item
getdate.texi(,228) 
getdate.texi(,229) A @dfn{time of day item} in date strings specifies the time on a given
getdate.texi(,230) day.  Here are some examples, all of which represent the same time:
getdate.texi(,231) 
getdate.texi(,232) @example
getdate.texi(,233) 20:02:00.000000
getdate.texi(,234) 20:02
getdate.texi(,235) 8:02pm
getdate.texi(,236) 20:02-0500      # In @sc{est} (U.S. Eastern Standard Time).
getdate.texi(,237) @end example
getdate.texi(,238) 
getdate.texi(,239) More generally, the time of day may be given as
getdate.texi(,240) @samp{@var{hour}:@var{minute}:@var{second}}, where @var{hour} is
getdate.texi(,241) a number between 0 and 23, @var{minute} is a number between 0 and
getdate.texi(,242) 59, and @var{second} is a number between 0 and 59 possibly followed by
getdate.texi(,243) @samp{.} or @samp{,} and a fraction containing one or more digits.
getdate.texi(,244) Alternatively,
getdate.texi(,245) @samp{:@var{second}} can be omitted, in which case it is taken to
getdate.texi(,246) be zero.  On the rare hosts that support leap seconds, @var{second}
getdate.texi(,247) may be 60.
getdate.texi(,248) 
getdate.texi(,249) @findex am @r{in date strings}
getdate.texi(,250) @findex pm @r{in date strings}
getdate.texi(,251) @findex midnight @r{in date strings}
getdate.texi(,252) @findex noon @r{in date strings}
getdate.texi(,253) If the time is followed by @samp{am} or @samp{pm} (or @samp{a.m.}
getdate.texi(,254) or @samp{p.m.}), @var{hour} is restricted to run from 1 to 12, and
getdate.texi(,255) @samp{:@var{minute}} may be omitted (taken to be zero).  @samp{am}
getdate.texi(,256) indicates the first half of the day, @samp{pm} indicates the second
getdate.texi(,257) half of the day.  In this notation, 12 is the predecessor of 1:
getdate.texi(,258) midnight is @samp{12am} while noon is @samp{12pm}.
getdate.texi(,259) (This is the zero-oriented interpretation of @samp{12am} and @samp{12pm},
getdate.texi(,260) as opposed to the old tradition derived from Latin
getdate.texi(,261) which uses @samp{12m} for noon and @samp{12pm} for midnight.)
getdate.texi(,262) 
getdate.texi(,263) @cindex time zone correction
getdate.texi(,264) @cindex minutes, time zone correction by
getdate.texi(,265) The time may alternatively be followed by a time zone correction,
getdate.texi(,266) expressed as @samp{@var{s}@var{hh}@var{mm}}, where @var{s} is @samp{+}
getdate.texi(,267) or @samp{-}, @var{hh} is a number of zone hours and @var{mm} is a number
getdate.texi(,268) of zone minutes.  You can also separate @var{hh} from @var{mm} with a colon.
getdate.texi(,269) When a time zone correction is given this way, it
getdate.texi(,270) forces interpretation of the time relative to
getdate.texi(,271) Coordinated Universal Time (@sc{utc}), overriding any previous
getdate.texi(,272) specification for the time zone or the local time zone.  For example,
getdate.texi(,273) @samp{+0530} and @samp{+05:30} both stand for the time zone 5.5 hours
getdate.texi(,274) ahead of @sc{utc} (e.g., India).  The @var{minute}
getdate.texi(,275) part of the time of day may not be elided when a time zone correction
getdate.texi(,276) is used.  This is the best way to specify a time zone correction by
getdate.texi(,277) fractional parts of an hour.
getdate.texi(,278) 
getdate.texi(,279) Either @samp{am}/@samp{pm} or a time zone correction may be specified,
getdate.texi(,280) but not both.
getdate.texi(,281) 
getdate.texi(,282) 
getdate.texi(,283) @node Time zone items
getdate.texi(,284) @section Time zone items
getdate.texi(,285) 
getdate.texi(,286) @cindex time zone item
getdate.texi(,287) 
getdate.texi(,288) A @dfn{time zone item} specifies an international time zone, indicated
getdate.texi(,289) by a small set of letters, e.g., @samp{UTC} or @samp{Z}
getdate.texi(,290) for Coordinated Universal
getdate.texi(,291) Time.  Any included periods are ignored.  By following a
getdate.texi(,292) non-daylight-saving time zone by the string @samp{DST} in a separate
getdate.texi(,293) word (that is, separated by some white space), the corresponding
getdate.texi(,294) daylight saving time zone may be specified.
getdate.texi(,295) Alternatively, a non-daylight-saving time zone can be followed by a
getdate.texi(,296) time zone correction, to add the two values.  This is normally done
getdate.texi(,297) only for @samp{UTC}; for example, @samp{UTC+05:30} is equivalent to
getdate.texi(,298) @samp{+05:30}.
getdate.texi(,299) 
getdate.texi(,300) Time zone items other than @samp{UTC} and @samp{Z}
getdate.texi(,301) are obsolescent and are not recommended, because they
getdate.texi(,302) are ambiguous; for example, @samp{EST} has a different meaning in
getdate.texi(,303) Australia than in the United States.  Instead, it's better to use
getdate.texi(,304) unambiguous numeric time zone corrections like @samp{-0500}, as
getdate.texi(,305) described in the previous section.
getdate.texi(,306) 
getdate.texi(,307) If neither a time zone item nor a time zone correction is supplied,
getdate.texi(,308) time stamps are interpreted using the rules of the default time zone
getdate.texi(,309) (@pxref{Specifying time zone rules}).
getdate.texi(,310) 
getdate.texi(,311) 
getdate.texi(,312) @node Day of week items
getdate.texi(,313) @section Day of week items
getdate.texi(,314) 
getdate.texi(,315) @cindex day of week item
getdate.texi(,316) 
getdate.texi(,317) The explicit mention of a day of the week will forward the date
getdate.texi(,318) (only if necessary) to reach that day of the week in the future.
getdate.texi(,319) 
getdate.texi(,320) Days of the week may be spelled out in full: @samp{Sunday},
getdate.texi(,321) @samp{Monday}, @samp{Tuesday}, @samp{Wednesday}, @samp{Thursday},
getdate.texi(,322) @samp{Friday} or @samp{Saturday}.  Days may be abbreviated to their
getdate.texi(,323) first three letters, optionally followed by a period.  The special
getdate.texi(,324) abbreviations @samp{Tues} for @samp{Tuesday}, @samp{Wednes} for
getdate.texi(,325) @samp{Wednesday} and @samp{Thur} or @samp{Thurs} for @samp{Thursday} are
getdate.texi(,326) also allowed.
getdate.texi(,327) 
getdate.texi(,328) @findex next @var{day}
getdate.texi(,329) @findex last @var{day}
getdate.texi(,330) A number may precede a day of the week item to move forward
getdate.texi(,331) supplementary weeks.  It is best used in expression like @samp{third
getdate.texi(,332) monday}.  In this context, @samp{last @var{day}} or @samp{next
getdate.texi(,333) @var{day}} is also acceptable; they move one week before or after
getdate.texi(,334) the day that @var{day} by itself would represent.
getdate.texi(,335) 
getdate.texi(,336) A comma following a day of the week item is ignored.
getdate.texi(,337) 
getdate.texi(,338) 
getdate.texi(,339) @node Relative items in date strings
getdate.texi(,340) @section Relative items in date strings
getdate.texi(,341) 
getdate.texi(,342) @cindex relative items in date strings
getdate.texi(,343) @cindex displacement of dates
getdate.texi(,344) 
getdate.texi(,345) @dfn{Relative items} adjust a date (or the current date if none) forward
getdate.texi(,346) or backward.  The effects of relative items accumulate.  Here are some
getdate.texi(,347) examples:
getdate.texi(,348) 
getdate.texi(,349) @example
getdate.texi(,350) 1 year
getdate.texi(,351) 1 year ago
getdate.texi(,352) 3 years
getdate.texi(,353) 2 days
getdate.texi(,354) @end example
getdate.texi(,355) 
getdate.texi(,356) @findex year @r{in date strings}
getdate.texi(,357) @findex month @r{in date strings}
getdate.texi(,358) @findex fortnight @r{in date strings}
getdate.texi(,359) @findex week @r{in date strings}
getdate.texi(,360) @findex day @r{in date strings}
getdate.texi(,361) @findex hour @r{in date strings}
getdate.texi(,362) @findex minute @r{in date strings}
getdate.texi(,363) The unit of time displacement may be selected by the string @samp{year}
getdate.texi(,364) or @samp{month} for moving by whole years or months.  These are fuzzy
getdate.texi(,365) units, as years and months are not all of equal duration.  More precise
getdate.texi(,366) units are @samp{fortnight} which is worth 14 days, @samp{week} worth 7
getdate.texi(,367) days, @samp{day} worth 24 hours, @samp{hour} worth 60 minutes,
getdate.texi(,368) @samp{minute} or @samp{min} worth 60 seconds, and @samp{second} or
getdate.texi(,369) @samp{sec} worth one second.  An @samp{s} suffix on these units is
getdate.texi(,370) accepted and ignored.
getdate.texi(,371) 
getdate.texi(,372) @findex ago @r{in date strings}
getdate.texi(,373) The unit of time may be preceded by a multiplier, given as an optionally
getdate.texi(,374) signed number.  Unsigned numbers are taken as positively signed.  No
getdate.texi(,375) number at all implies 1 for a multiplier.  Following a relative item by
getdate.texi(,376) the string @samp{ago} is equivalent to preceding the unit by a
getdate.texi(,377) multiplier with value @math{-1}.
getdate.texi(,378) 
getdate.texi(,379) @findex day @r{in date strings}
getdate.texi(,380) @findex tomorrow @r{in date strings}
getdate.texi(,381) @findex yesterday @r{in date strings}
getdate.texi(,382) The string @samp{tomorrow} is worth one day in the future (equivalent
getdate.texi(,383) to @samp{day}), the string @samp{yesterday} is worth
getdate.texi(,384) one day in the past (equivalent to @samp{day ago}).
getdate.texi(,385) 
getdate.texi(,386) @findex now @r{in date strings}
getdate.texi(,387) @findex today @r{in date strings}
getdate.texi(,388) @findex this @r{in date strings}
getdate.texi(,389) The strings @samp{now} or @samp{today} are relative items corresponding
getdate.texi(,390) to zero-valued time displacement, these strings come from the fact
getdate.texi(,391) a zero-valued time displacement represents the current time when not
getdate.texi(,392) otherwise changed by previous items.  They may be used to stress other
getdate.texi(,393) items, like in @samp{12:00 today}.  The string @samp{this} also has
getdate.texi(,394) the meaning of a zero-valued time displacement, but is preferred in
getdate.texi(,395) date strings like @samp{this thursday}.
getdate.texi(,396) 
getdate.texi(,397) When a relative item causes the resulting date to cross a boundary
getdate.texi(,398) where the clocks were adjusted, typically for daylight saving time,
getdate.texi(,399) the resulting date and time are adjusted accordingly.
getdate.texi(,400) 
getdate.texi(,401) The fuzz in units can cause problems with relative items.  For
getdate.texi(,402) example, @samp{2003-07-31 -1 month} might evaluate to 2003-07-01,
getdate.texi(,403) because 2003-06-31 is an invalid date.  To determine the previous
getdate.texi(,404) month more reliably, you can ask for the month before the 15th of the
getdate.texi(,405) current month.  For example:
getdate.texi(,406) 
getdate.texi(,407) @example
getdate.texi(,408) $ date -R
getdate.texi(,409) Thu, 31 Jul 2003 13:02:39 -0700
getdate.texi(,410) $ date --date='-1 month' +'Last month was %B?'
getdate.texi(,411) Last month was July?
getdate.texi(,412) $ date --date="$(date +%Y-%m-15) -1 month" +'Last month was %B!'
getdate.texi(,413) Last month was June!
getdate.texi(,414) @end example
getdate.texi(,415) 
getdate.texi(,416) Also, take care when manipulating dates around clock changes such as
getdate.texi(,417) daylight saving leaps.  In a few cases these have added or subtracted
getdate.texi(,418) as much as 24 hours from the clock, so it is often wise to adopt
getdate.texi(,419) universal time by setting the @env{TZ} environment variable to
getdate.texi(,420) @samp{UTC0} before embarking on calendrical calculations.
getdate.texi(,421) 
getdate.texi(,422) @node Pure numbers in date strings
getdate.texi(,423) @section Pure numbers in date strings
getdate.texi(,424) 
getdate.texi(,425) @cindex pure numbers in date strings
getdate.texi(,426) 
getdate.texi(,427) The precise interpretation of a pure decimal number depends
getdate.texi(,428) on the context in the date string.
getdate.texi(,429) 
getdate.texi(,430) If the decimal number is of the form @var{yyyy}@var{mm}@var{dd} and no
getdate.texi(,431) other calendar date item (@pxref{Calendar date items}) appears before it
getdate.texi(,432) in the date string, then @var{yyyy} is read as the year, @var{mm} as the
getdate.texi(,433) month number and @var{dd} as the day of the month, for the specified
getdate.texi(,434) calendar date.
getdate.texi(,435) 
getdate.texi(,436) If the decimal number is of the form @var{hh}@var{mm} and no other time
getdate.texi(,437) of day item appears before it in the date string, then @var{hh} is read
getdate.texi(,438) as the hour of the day and @var{mm} as the minute of the hour, for the
getdate.texi(,439) specified time of day.  @var{mm} can also be omitted.
getdate.texi(,440) 
getdate.texi(,441) If both a calendar date and a time of day appear to the left of a number
getdate.texi(,442) in the date string, but no relative item, then the number overrides the
getdate.texi(,443) year.
getdate.texi(,444) 
getdate.texi(,445) 
getdate.texi(,446) @node Seconds since the Epoch
getdate.texi(,447) @section Seconds since the Epoch
getdate.texi(,448) 
getdate.texi(,449) If you precede a number with @samp{@@}, it represents an internal time
getdate.texi(,450) stamp as a count of seconds.  The number can contain an internal
getdate.texi(,451) decimal point (either @samp{.} or @samp{,}); any excess precision not
getdate.texi(,452) supported by the internal representation is truncated toward minus
getdate.texi(,453) infinity.  Such a number cannot be combined with any other date
getdate.texi(,454) item, as it specifies a complete time stamp.
getdate.texi(,455) 
getdate.texi(,456) @cindex beginning of time, for @acronym{POSIX}
getdate.texi(,457) @cindex epoch, for @acronym{POSIX}
getdate.texi(,458) Internally, computer times are represented as a count of seconds since
getdate.texi(,459) an epoch---a well-defined point of time.  On @acronym{GNU} and
getdate.texi(,460) @acronym{POSIX} systems, the epoch is 1970-01-01 00:00:00 @sc{utc}, so
getdate.texi(,461) @samp{@@0} represents this time, @samp{@@1} represents 1970-01-01
getdate.texi(,462) 00:00:01 @sc{utc}, and so forth.  @acronym{GNU} and most other
getdate.texi(,463) @acronym{POSIX}-compliant systems support such times as an extension
getdate.texi(,464) to @acronym{POSIX}, using negative counts, so that @samp{@@-1}
getdate.texi(,465) represents 1969-12-31 23:59:59 @sc{utc}.
getdate.texi(,466) 
getdate.texi(,467) Traditional Unix systems count seconds with 32-bit two's-complement
getdate.texi(,468) integers and can represent times from 1901-12-13 20:45:52 through
getdate.texi(,469) 2038-01-19 03:14:07 @sc{utc}.  More modern systems use 64-bit counts
getdate.texi(,470) of seconds with nanosecond subcounts, and can represent all the times
getdate.texi(,471) in the known lifetime of the universe to a resolution of 1 nanosecond.
getdate.texi(,472) 
getdate.texi(,473) On most hosts, these counts ignore the presence of leap seconds.
getdate.texi(,474) For example, on most hosts @samp{@@915148799} represents 1998-12-31
getdate.texi(,475) 23:59:59 @sc{utc}, @samp{@@915148800} represents 1999-01-01 00:00:00
getdate.texi(,476) @sc{utc}, and there is no way to represent the intervening leap second
getdate.texi(,477) 1998-12-31 23:59:60 @sc{utc}.
getdate.texi(,478) 
getdate.texi(,479) @node Specifying time zone rules
getdate.texi(,480) @section Specifying time zone rules
getdate.texi(,481) 
getdate.texi(,482) @vindex TZ
getdate.texi(,483) Normally, dates are interpreted using the rules of the current time
getdate.texi(,484) zone, which in turn are specified by the @env{TZ} environment
getdate.texi(,485) variable, or by a system default if @env{TZ} is not set.  To specify a
getdate.texi(,486) different set of default time zone rules that apply just to one date,
getdate.texi(,487) start the date with a string of the form @samp{TZ="@var{rule}"}.  The
getdate.texi(,488) two quote characters (@samp{"}) must be present in the date, and any
getdate.texi(,489) quotes or backslashes within @var{rule} must be escaped by a
getdate.texi(,490) backslash.
getdate.texi(,491) 
getdate.texi(,492) For example, with the @acronym{GNU} @command{date} command you can
getdate.texi(,493) answer the question ``What time is it in New York when a Paris clock
getdate.texi(,494) shows 6:30am on October 31, 2004?'' by using a date beginning with
getdate.texi(,495) @samp{TZ="Europe/Paris"} as shown in the following shell transcript:
getdate.texi(,496) 
getdate.texi(,497) @example
getdate.texi(,498) $ export TZ="America/New_York"
getdate.texi(,499) $ date --date='TZ="Europe/Paris" 2004-10-31 06:30'
getdate.texi(,500) Sun Oct 31 01:30:00 EDT 2004
getdate.texi(,501) @end example
getdate.texi(,502) 
getdate.texi(,503) In this example, the @option{--date} operand begins with its own
getdate.texi(,504) @env{TZ} setting, so the rest of that operand is processed according
getdate.texi(,505) to @samp{Europe/Paris} rules, treating the string @samp{2004-10-31
getdate.texi(,506) 06:30} as if it were in Paris.  However, since the output of the
getdate.texi(,507) @command{date} command is processed according to the overall time zone
getdate.texi(,508) rules, it uses New York time.  (Paris was normally six hours ahead of
getdate.texi(,509) New York in 2004, but this example refers to a brief Halloween period
getdate.texi(,510) when the gap was five hours.)
getdate.texi(,511) 
getdate.texi(,512) A @env{TZ} value is a rule that typically names a location in the
getdate.texi(,513) @uref{http://www.twinsun.com/tz/tz-link.htm, @samp{tz} database}.
getdate.texi(,514) A recent catalog of location names appears in the
getdate.texi(,515) @uref{http://twiki.org/cgi-bin/xtra/tzdate, TWiki Date and Time
getdate.texi(,516) Gateway}.  A few non-@acronym{GNU} hosts require a colon before a
getdate.texi(,517) location name in a @env{TZ} setting, e.g.,
getdate.texi(,518) @samp{TZ=":America/New_York"}.
getdate.texi(,519) 
getdate.texi(,520) The @samp{tz} database includes a wide variety of locations ranging
getdate.texi(,521) from @samp{Arctic/Longyearbyen} to @samp{Antarctica/South_Pole}, but
getdate.texi(,522) if you are at sea and have your own private time zone, or if you are
getdate.texi(,523) using a non-@acronym{GNU} host that does not support the @samp{tz}
getdate.texi(,524) database, you may need to use a @acronym{POSIX} rule instead.  Simple
getdate.texi(,525) @acronym{POSIX} rules like @samp{UTC0} specify a time zone without
getdate.texi(,526) daylight saving time; other rules can specify simple daylight saving
getdate.texi(,527) regimes.  @xref{TZ Variable,, Specifying the Time Zone with @code{TZ},
getdate.texi(,528) libc, The GNU C Library}.
getdate.texi(,529) 
getdate.texi(,530) @node Authors of get_date
getdate.texi(,531) @section Authors of @code{get_date}
getdate.texi(,532) 
getdate.texi(,533) @cindex authors of @code{get_date}
getdate.texi(,534) 
getdate.texi(,535) @cindex Bellovin, Steven M.
getdate.texi(,536) @cindex Salz, Rich
getdate.texi(,537) @cindex Berets, Jim
getdate.texi(,538) @cindex MacKenzie, David
getdate.texi(,539) @cindex Meyering, Jim
getdate.texi(,540) @cindex Eggert, Paul
getdate.texi(,541) @code{get_date} was originally implemented by Steven M. Bellovin
getdate.texi(,542) (@email{smb@@research.att.com}) while at the University of North Carolina
getdate.texi(,543) at Chapel Hill.  The code was later tweaked by a couple of people on
getdate.texi(,544) Usenet, then completely overhauled by Rich $alz (@email{rsalz@@bbn.com})
getdate.texi(,545) and Jim Berets (@email{jberets@@bbn.com}) in August, 1990.  Various
getdate.texi(,546) revisions for the @sc{gnu} system were made by David MacKenzie, Jim Meyering,
getdate.texi(,547) Paul Eggert and others.
getdate.texi(,548) 
getdate.texi(,549) @cindex Pinard, F.
getdate.texi(,550) @cindex Berry, K.
getdate.texi(,551) This chapter was originally produced by Fran@,{c}ois Pinard
getdate.texi(,552) (@email{pinard@@iro.umontreal.ca}) from the @file{getdate.y} source code,
getdate.texi(,553) and then edited by K.@: Berry (@email{kb@@cs.umb.edu}).
tar.texi(,7629) 
tar.texi(,7630) @node Formats
tar.texi(,7631) @chapter Controlling the Archive Format
tar.texi(,7632) 
tar.texi(,7633) @cindex Tar archive formats
tar.texi(,7634) Due to historical reasons, there are several formats of tar archives.
tar.texi(,7635) All of them are based on the same principles, but have some subtle
tar.texi(,7636) differences that often make them incompatible with each other.
tar.texi(,7637) 
tar.texi(,7638) GNU tar is able to create and handle archives in a variety of formats.
tar.texi(,7639) The most frequently used formats are (in alphabetical order):
tar.texi(,7640) 
tar.texi(,7641) @table @asis
tar.texi(,7642) @item gnu
tar.texi(GNUTAR,7643) Format used by tar.texi(GNUTAR,7643) @acronym{GNU} @command{tar} versions up to 1.13.25.  This format derived
tar.texi(,7644) from an early @acronym{POSIX} standard, adding some improvements such as
tar.texi(,7645) sparse file handling and incremental archives.  Unfortunately these
tar.texi(,7646) features were implemented in a way incompatible with other archive
tar.texi(,7647) formats.
tar.texi(,7648) 
tar.texi(,7649) Archives in @samp{gnu} format are able to hold pathnames of unlimited
tar.texi(,7650) length.
tar.texi(,7651) 
tar.texi(,7652) @item oldgnu
tar.texi(GNUTAR,7653) Format used by tar.texi(GNUTAR,7653) @acronym{GNU} @command{tar} of versions prior to 1.12.
tar.texi(,7654) 
tar.texi(,7655) @item v7
tar.texi(,7656) Archive format, compatible with the V7 implementation of tar.  This
tar.texi(,7657) format imposes a number of limitations.  The most important of them
tar.texi(,7658) are:
tar.texi(,7659) 
tar.texi(,7660) @enumerate
tar.texi(,7661) @item The maximum length of a file name is limited to 99 characters.
tar.texi(,7662) @item The maximum length of a symbolic link is limited to 99 characters.
tar.texi(,7663) @item It is impossible to store special files (block and character
tar.texi(,7664) devices, fifos etc.)
tar.texi(,7665) @item Maximum value of user or group ID is limited to 2097151 (7777777
tar.texi(,7666) octal)
tar.texi(,7667) @item V7 archives do not contain symbolic ownership information (user
tar.texi(,7668) and group name of the file owner).
tar.texi(,7669) @end enumerate
tar.texi(,7670) 
tar.texi(,7671) This format has traditionally been used by Automake when producing
tar.texi(,7672) Makefiles.  This practice will change in the future, in the meantime,
tar.texi(,7673) however this means that projects containing filenames more than 99
tar.texi(GNUTAR,7674) characters long will not be able to use tar.texi(GNUTAR,7674) @acronym{GNU} @command{tar} 1.15.92 and
tar.texi(,7675) Automake prior to 1.9.
tar.texi(,7676) 
tar.texi(,7677) @item ustar
tar.texi(,7678) Archive format defined by @acronym{POSIX.1-1988} specification.  It stores
tar.texi(,7679) symbolic ownership information.  It is also able to store
tar.texi(,7680) special files.  However, it imposes several restrictions as well:
tar.texi(,7681) 
tar.texi(,7682) @enumerate
tar.texi(,7683) @item The maximum length of a file name is limited to 256 characters,
tar.texi(,7684) provided that the filename can be split at directory separator in
tar.texi(,7685) two parts, first of them being at most 155 bytes long.  So, in most
tar.texi(,7686) cases the maximum file name length will be shorter than 256
tar.texi(,7687) characters.
tar.texi(,7688) @item The maximum length of a symbolic link name is limited to
tar.texi(,7689) 100 characters.
tar.texi(,7690) @item Maximum size of a file the archive is able to accomodate
tar.texi(,7691) is 8GB
tar.texi(,7692) @item Maximum value of UID/GID is 2097151.
tar.texi(,7693) @item Maximum number of bits in device major and minor numbers is 21.
tar.texi(,7694) @end enumerate
tar.texi(,7695) 
tar.texi(,7696) @item star
tar.texi(,7697) Format used by J@"org Schilling @command{star}
tar.texi(GNUTAR,7698) implementation.  tar.texi(GNUTAR,7698) @acronym{GNU} @command{tar} is able to read @samp{star} archives but
tar.texi(,7699) currently does not produce them.
tar.texi(,7700) 
tar.texi(,7701) @item posix
tar.texi(,7702) Archive format defined by @acronym{POSIX.1-2001} specification.  This is the
tar.texi(,7703) most flexible and feature-rich format.  It does not impose any
tar.texi(,7704) restrictions on file sizes or filename lengths.  This format is quite
tar.texi(,7705) recent, so not all tar implementations are able to handle it properly.
tar.texi(,7706) However, this format is designed in such a way that any tar
tar.texi(,7707) implementation able to read @samp{ustar} archives will be able to read
tar.texi(,7708) most @samp{posix} archives as well, with the only exception that any
tar.texi(,7709) additional information (such as long file names etc.) will in such
tar.texi(,7710) case be extracted as plain text files along with the files it refers to.
tar.texi(,7711) 
tar.texi(,7712) This archive format will be the default format for future versions
tar.texi(GNUTAR,7713) of tar.texi(GNUTAR,7713) @acronym{GNU} @command{tar}.
tar.texi(,7714) 
tar.texi(,7715) @end table
tar.texi(,7716) 
tar.texi(,7717) The following table summarizes the limitations of each of these
tar.texi(,7718) formats:
tar.texi(,7719) 
tar.texi(,7720) @multitable @columnfractions .10 .20 .20 .20 .20
tar.texi(,7721) @headitem Format @tab UID @tab File Size @tab Path Name @tab Devn
tar.texi(,7722) @item gnu    @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
tar.texi(,7723) @item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
tar.texi(,7724) @item v7     @tab 2097151 @tab 8GB @tab 99 @tab n/a
tar.texi(,7725) @item ustar  @tab 2097151 @tab 8GB @tab 256 @tab 21
tar.texi(,7726) @item posix  @tab Unlimited @tab Unlimited @tab Unlimited @tab Unlimited
tar.texi(,7727) @end multitable
tar.texi(,7728) 
tar.texi(GNUTAR,7729) The default format for tar.texi(GNUTAR,7729) @acronym{GNU} @command{tar} is defined at compilation
tar.texi(,7730) time.  You may check it by running @command{tar --help}, and examining
tar.texi(GNUTAR,7731) the last lines of its output.  Usually, tar.texi(GNUTAR,7731) @acronym{GNU} @command{tar} is configured
tar.texi(,7732) to create archives in @samp{gnu} format, however, future version will
tar.texi(,7733) switch to @samp{posix}.
tar.texi(,7734) 
tar.texi(,7735) @menu
tar.texi(,7736) * Compression::                 Using Less Space through Compression
tar.texi(,7737) * Attributes::                  Handling File Attributes
tar.texi(,7738) * Portability::                 Making @command{tar} Archives More Portable
tar.texi(,7739) * cpio::                        Comparison of @command{tar} and @command{cpio}
tar.texi(,7740) @end menu
tar.texi(,7741) 
tar.texi(,7742) @node Compression
tar.texi(,7743) @section Using Less Space through Compression
tar.texi(,7744) 
tar.texi(,7745) @menu
tar.texi(,7746) * gzip::                        Creating and Reading Compressed Archives
tar.texi(,7747) * sparse::                      Archiving Sparse Files
tar.texi(,7748) @end menu
tar.texi(,7749) 
tar.texi(,7750) @node gzip
tar.texi(,7751) @subsection Creating and Reading Compressed Archives
tar.texi(,7752) @cindex Compressed archives
tar.texi(,7753) @cindex Storing archives in compressed format
tar.texi(,7754) 
tar.texi(GNUTAR,7755) @acronym{GNU} @command{tar} is able to create and read compressed archives.  It supports
tar.texi(,7756) @command{gzip} and @command{bzip2} compression programs.  For backward
tar.texi(,7757) compatibilty, it also supports @command{compress} command, although
tar.texi(,7758) we strongly recommend against using it, since there is a patent
tar.texi(,7759) covering the algorithm it uses and you could be sued for patent
tar.texi(,7760) infringement merely by running @command{compress}!  Besides, it is less
tar.texi(,7761) effective than @command{gzip} and @command{bzip2}.
tar.texi(,7762) 
tar.texi(,7763) Creating a compressed archive is simple: you just specify a
tar.texi(,7764) @dfn{compression option} along with the usual archive creation
tar.texi(,7765) commands.  The compression option is @option{-z} (@option{--gzip}) to
tar.texi(,7766) create a @command{gzip} compressed archive, @option{-j}
tar.texi(,7767) (@option{--bzip2}) to create a @command{bzip2} compressed archive, and
tar.texi(,7768) @option{-Z} (@option{--compress}) to use @command{compress} program.
tar.texi(,7769) For example:
tar.texi(,7770) 
tar.texi(,7771) @smallexample
tar.texi(,7772) $ @kbd{tar cfz archive.tar.gz .}
tar.texi(,7773) @end smallexample
tar.texi(,7774) 
tar.texi(,7775) Reading compressed archive is even simpler: you don't need to specify
tar.texi(GNUTAR,7776) any additional options as tar.texi(GNUTAR,7776) @acronym{GNU} @command{tar} recognizes its format
tar.texi(,7777) automatically.  Thus, the following commands will list and extract the
tar.texi(,7778) archive created in previous example:
tar.texi(,7779) 
tar.texi(,7780) @smallexample
tar.texi(,7781) # List the compressed archive
tar.texi(,7782) $ @kbd{tar tf archive.tar.gz}
tar.texi(,7783) # Extract the compressed archive
tar.texi(,7784) $ @kbd{tar xf archive.tar.gz}
tar.texi(,7785) @end smallexample
tar.texi(,7786) 
tar.texi(,7787) The only case when you have to specify a decompression option while
tar.texi(,7788) reading the archive is when reading from a pipe or from a tape drive
tar.texi(GNUTAR,7789) that does not support random access.  However, in this case tar.texi(GNUTAR,7789) @acronym{GNU} @command{tar}
tar.texi(,7790) will indicate which option you should use.  For example:
tar.texi(,7791) 
tar.texi(,7792) @smallexample
tar.texi(,7793) $ @kbd{cat archive.tar.gz | tar tf -}
tar.texi(,7794) tar: Archive is compressed.  Use -z option
tar.texi(,7795) tar: Error is not recoverable: exiting now
tar.texi(,7796) @end smallexample
tar.texi(,7797) 
tar.texi(,7798) If you see such diagnostics, just add the suggested option to the
tar.texi(GNUTAR,7799) invocation of tar.texi(GNUTAR,7799) @acronym{GNU} @command{tar}:
tar.texi(,7800) 
tar.texi(,7801) @smallexample
tar.texi(,7802) $ @kbd{cat archive.tar.gz | tar tfz -}
tar.texi(,7803) @end smallexample
tar.texi(,7804) 
tar.texi(,7805) Notice also, that there are several restrictions on operations on
tar.texi(,7806) compressed archives.  First of all, compressed archives cannot be
tar.texi(,7807) modified, i.e., you cannot update (@option{--update} (@option{-u})) them or delete
tar.texi(,7808) (@option{--delete}) members from them.  Likewise, you cannot append
tar.texi(,7809) another @command{tar} archive to a compressed archive using
tar.texi(,7810) @option{--append} (@option{-r})).  Secondly, multi-volume archives cannot be
tar.texi(,7811) compressed.
tar.texi(,7812) 
tar.texi(GNUTAR,7813) The following table summarizes compression options used by tar.texi(GNUTAR,7813) @acronym{GNU} @command{tar}.
tar.texi(,7814) 
tar.texi(,7815) @table @option
tar.texi(,7816) @opindex gzip
tar.texi(,7817) @opindex ungzip
tar.texi(,7818) @item -z
tar.texi(,7819) @itemx --gzip
tar.texi(,7820) @itemx --ungzip
tar.texi(,7821) Filter the archive through @command{gzip}.
tar.texi(,7822) 
tar.texi(,7823) You can use @option{--gzip} and @option{--gunzip} on physical devices
tar.texi(,7824) (tape drives, etc.) and remote files as well as on normal files; data
tar.texi(,7825) to or from such devices or remote files is reblocked by another copy
tar.texi(,7826) of the @command{tar} program to enforce the specified (or default) record
tar.texi(,7827) size.  The default compression parameters are used; if you need to
tar.texi(,7828) override them, set @env{GZIP} environment variable, e.g.:
tar.texi(,7829) 
tar.texi(,7830) @smallexample
tar.texi(,7831) $ @kbd{GZIP=--best tar cfz archive.tar.gz subdir}
tar.texi(,7832) @end smallexample
tar.texi(,7833) 
tar.texi(,7834) @noindent
tar.texi(,7835) Another way would be to avoid the @option{--gzip} (@option{--gunzip}, @option{--ungzip}, @option{-z}) option and run
tar.texi(,7836) @command{gzip} explicitly:
tar.texi(,7837) 
tar.texi(,7838) @smallexample
tar.texi(,7839) $ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz}
tar.texi(,7840) @end smallexample
tar.texi(,7841) 
tar.texi(,7842) @cindex corrupted archives
tar.texi(,7843) About corrupted compressed archives: @command{gzip}'ed files have no
tar.texi(,7844) redundancy, for maximum compression.  The adaptive nature of the
tar.texi(,7845) compression scheme means that the compression tables are implicitly
tar.texi(,7846) spread all over the archive.  If you lose a few blocks, the dynamic
tar.texi(,7847) construction of the compression tables becomes unsynchronized, and there
tar.texi(,7848) is little chance that you could recover later in the archive.
tar.texi(,7849) 
tar.texi(,7850) There are pending suggestions for having a per-volume or per-file
tar.texi(GNUTAR,7851) compression in tar.texi(GNUTAR,7851) @acronym{GNU} @command{tar}.  This would allow for viewing the
tar.texi(,7852) contents without decompression, and for resynchronizing decompression at
tar.texi(,7853) every volume or file, in case of corrupted archives.  Doing so, we might
tar.texi(,7854) lose some compressibility.  But this would have make recovering easier.
tar.texi(,7855) So, there are pros and cons.  We'll see!
tar.texi(,7856) 
tar.texi(,7857) @opindex bzip2
tar.texi(,7858) @item -j
tar.texi(,7859) @itemx --bzip2
tar.texi(,7860) Filter the archive through @code{bzip2}.  Otherwise like @option{--gzip}.
tar.texi(,7861) 
tar.texi(,7862) @opindex compress
tar.texi(,7863) @opindex uncompress
tar.texi(,7864) @item -Z
tar.texi(,7865) @itemx --compress
tar.texi(,7866) @itemx --uncompress
tar.texi(,7867) Filter the archive through @command{compress}.  Otherwise like @option{--gzip}.
tar.texi(,7868) 
tar.texi(,7869) The @acronym{GNU} Project recommends you not use
tar.texi(,7870) @command{compress}, because there is a patent covering the algorithm it
tar.texi(,7871) uses.  You could be sued for patent infringement merely by running
tar.texi(,7872) @command{compress}.
tar.texi(,7873) 
tar.texi(,7874) @opindex use-compress-program
tar.texi(,7875) @item --use-compress-program=@var{prog}
tar.texi(,7876) Use external compression program @var{prog}.  Use this option if you
tar.texi(GNUTAR,7877) have a compression program that tar.texi(GNUTAR,7877) @acronym{GNU} @command{tar} does not support.  There
tar.texi(,7878) are two requirements to which @var{prog} should comply:
tar.texi(,7879) 
tar.texi(,7880) First, when called without options, it should read data from standard
tar.texi(,7881) input, compress it and output it on standard output.
tar.texi(,7882) 
tar.texi(,7883) Secondly, if called with @option{-d} argument, it should do exactly
tar.texi(,7884) the opposite, i.e., read the compressed data from the standard input
tar.texi(,7885) and produce uncompressed data on the standard output.
tar.texi(,7886) @end table
tar.texi(,7887) 
tar.texi(,7888) @cindex gpg, using with tar
tar.texi(,7889) @cindex gnupg, using with tar
tar.texi(,7890) @cindex Using encrypted archives
tar.texi(,7891) The @option{--use-compress-program} option, in particular, lets you
tar.texi(,7892) implement your own filters, not necessarily dealing with
tar.texi(,7893) compression/decomression.  For example, suppose you wish to implement
tar.texi(,7894) PGP encryption on top of compression, using @command{gpg} (@pxref{Top,
tar.texi(,7895) gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard
tar.texi(,7896) Manual}).  The following script does that:  
tar.texi(,7897) 
tar.texi(,7898) @smallexample
tar.texi(,7899) @group
tar.texi(,7900) #! /bin/sh
tar.texi(,7901) case $1 in
tar.texi(,7902) -d) gpg --decrypt - | gzip -d -c;;
tar.texi(,7903) '') gzip -c | gpg -s ;;
tar.texi(,7904) *)  echo "Unknown option $1">&2; exit 1;;
tar.texi(,7905) esac
tar.texi(,7906) @end group
tar.texi(,7907) @end smallexample
tar.texi(,7908) 
tar.texi(,7909) Suppose you name it @file{gpgz} and save it somewhere in your
tar.texi(,7910) @env{PATH}.  Then the following command will create a commpressed
tar.texi(,7911) archive signed with your private key:
tar.texi(,7912) 
tar.texi(,7913) @smallexample
tar.texi(,7914) $ @kbd{tar -cf foo.tar.gpgz --use-compress=gpgz .}
tar.texi(,7915) @end smallexample
tar.texi(,7916) 
tar.texi(,7917) @noindent
tar.texi(,7918) Likewise, the following command will list its contents:
tar.texi(,7919) 
tar.texi(,7920) @smallexample
tar.texi(,7921) $ @kbd{tar -tf foo.tar.gpgz --use-compress=gpgz .}
tar.texi(,7922) @end smallexample
tar.texi(,7923) 
tar.texi(,7962) 
tar.texi(,7963) @node sparse
tar.texi(,7964) @subsection Archiving Sparse Files
tar.texi(,7965) @cindex Sparse Files
tar.texi(,7966) 
tar.texi(,7967) Files in the file system occasionally have @dfn{holes}.  A @dfn{hole}
tar.texi(,7968) in a file is a section of the file's contents which was never written.
tar.texi(,7969) The contents of a hole reads as all zeros.  On many operating systems,
tar.texi(,7970) actual disk storage is not allocated for holes, but they are counted
tar.texi(,7971) in the length of the file.  If you archive such a file, @command{tar}
tar.texi(,7972) could create an archive longer than the original.  To have @command{tar}
tar.texi(,7973) attempt to recognize the holes in a file, use @option{--sparse}
tar.texi(,7974) (@option{-S}).  When you use this option, then, for any file using
tar.texi(,7975) less disk space than would be expected from its length, @command{tar}
tar.texi(,7976) searches the file for consecutive stretches of zeros.  It then records
tar.texi(,7977) in the archive for the file where the consecutive stretches of zeros
tar.texi(,7978) are, and only archives the ``real contents'' of the file.  On
tar.texi(,7979) extraction (using @option{--sparse} is not needed on extraction) any
tar.texi(,7980) such files have holes created wherever the continuous stretches of zeros
tar.texi(,7981) were found.  Thus, if you use @option{--sparse}, @command{tar} archives
tar.texi(,7982) won't take more space than the original.
tar.texi(,7983) 
tar.texi(,7984) @table @option
tar.texi(,7985) @opindex sparse
tar.texi(,7986) @item -S
tar.texi(,7987) @itemx --sparse
tar.texi(,7988) This option istructs @command{tar} to test each file for sparseness
tar.texi(,7989) before attempting to archive it.  If the file is found to be sparse it
tar.texi(,7990) is treated specially, thus allowing to decrease the amount of space
tar.texi(,7991) used by its image in the archive.
tar.texi(,7992) 
tar.texi(,7993) This option is meaningful only when creating or updating archives.  It
tar.texi(,7994) has no effect on extraction.
tar.texi(,7995) @end table
tar.texi(,7996) 
tar.texi(,7997) Consider using @option{--sparse} when performing file system backups,
tar.texi(,7998) to avoid archiving the expanded forms of files stored sparsely in the
tar.texi(,7999) system. 
tar.texi(,8000) 
tar.texi(,8001) Even if your system has no sparse files currently, some may be
tar.texi(,8002) created in the future.  If you use @option{--sparse} while making file
tar.texi(,8003) system backups as a matter of course, you can be assured the archive
tar.texi(,8004) will never take more space on the media than the files take on disk
tar.texi(,8005) (otherwise, archiving a disk filled with sparse files might take
tar.texi(,8006) hundreds of tapes).  @xref{Incremental Dumps}.
tar.texi(,8007) 
tar.texi(,8008) However, be aware that @option{--sparse} option presents a serious
tar.texi(,8009) drawback.  Namely, in order to determine if the file is sparse
tar.texi(,8010) @command{tar} has to read it before trying to archive it, so in total
tar.texi(,8011) the file is read @strong{twice}.  So, always bear in mind that the
tar.texi(,8012) time needed to process all files with this option is roughly twice
tar.texi(,8013) the time needed to archive them without it.
tar.texi(FIXME,8038) @allow-recursion
tar.texi(FIXME,8038) @quote-arg
tar.texi(FIXME,8038) 
tar.texi(,8039) 
tar.texi(,8040) @cindex sparse formats, defined
tar.texi(GNUTAR,8041) When using @samp{POSIX} archive format, tar.texi(GNUTAR,8041) @acronym{GNU} @command{tar} is able to store
tar.texi(,8042) sparse files using in three distinct ways, called @dfn{sparse
tar.texi(,8043) formats}.  A sparse format is identified by its @dfn{number},
tar.texi(,8044) consisting, as usual of two decimal numbers, delimited by a dot.  By
tar.texi(,8045) default, format @samp{1.0} is used.  If, for some reason, you wish to
tar.texi(,8046) use an earlier format, you can select it using
tar.texi(,8047) @option{--sparse-version} option. 
tar.texi(,8048) 
tar.texi(,8049) @table @option
tar.texi(,8050) @opindex sparse-version
tar.texi(,8051) @item --sparse-version=@var{version}
tar.texi(,8052) 
tar.texi(,8053) Select the format to store sparse files in.  Valid @var{version} values
tar.texi(,8054) are: @samp{0.0}, @samp{0.1} and @samp{1.0}.  @xref{Sparse Formats},
tar.texi(,8055) for a detailed description of each format.
tar.texi(,8056) @end table
tar.texi(,8057) 
tar.texi(,8058) Using @option{--sparse-format} option implies @option{--sparse}.
tar.texi(,8059) 
tar.texi(,8060) @node Attributes
tar.texi(,8061) @section Handling File Attributes
tar.texi(UNREVISED,8062) @quotation
tar.texi(UNREVISED,8062) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,8062) @end quotation
tar.texi(,8063) 
tar.texi(,8064) When @command{tar} reads files, it updates their access times.  To
tar.texi(,8065) avoid this, use the @option{--atime-preserve[=METHOD]} option, which can either
tar.texi(,8066) reset the access time retroactively or avoid changing it in the first
tar.texi(,8067) place.
tar.texi(,8068) 
tar.texi(,8069) Handling of file attributes
tar.texi(,8070) 
tar.texi(,8071) @table @option
tar.texi(,8072) @opindex atime-preserve
tar.texi(,8073) @item --atime-preserve
tar.texi(,8074) @itemx --atime-preserve=replace
tar.texi(,8075) @itemx --atime-preserve=system
tar.texi(,8076) Preserve the access times of files that are read.  This works only for
tar.texi(,8077) files that you own, unless you have superuser privileges.
tar.texi(,8078) 
tar.texi(,8079) @option{--atime-preserve=replace} works on most systems, but it also
tar.texi(,8080) restores the data modification time and updates the status change
tar.texi(,8081) time.  Hence it doesn't interact with incremental dumps nicely
tar.texi(,8082) (@pxref{Incremental Dumps}), and it can set access or data modification times
tar.texi(,8083) incorrectly if other programs access the file while @command{tar} is
tar.texi(,8084) running.
tar.texi(,8085) 
tar.texi(,8086) @option{--atime-preserve=system} avoids changing the access time in
tar.texi(,8087) the first place, if the operating system supports this.
tar.texi(,8088) Unfortunately, this may or may not work on any given operating system
tar.texi(,8089) or file system.  If @command{tar} knows for sure it won't work, it
tar.texi(,8090) complains right away.
tar.texi(,8091) 
tar.texi(,8092) Currently @option{--atime-preserve} with no operand defaults to
tar.texi(,8093) @option{--atime-preserve=replace}, but this is intended to change to
tar.texi(,8094) @option{--atime-preserve=system} when the latter is better-supported.
tar.texi(,8095) 
tar.texi(,8096) @opindex touch
tar.texi(,8097) @item -m
tar.texi(,8098) @itemx --touch
tar.texi(,8099) Do not extract data modification time.
tar.texi(,8100) 
tar.texi(,8101) When this option is used, @command{tar} leaves the data modification times
tar.texi(,8102) of the files it extracts as the times when the files were extracted,
tar.texi(,8103) instead of setting it to the times recorded in the archive.
tar.texi(,8104) 
tar.texi(,8105) This option is meaningless with @option{--list} (@option{-t}).
tar.texi(,8106) 
tar.texi(,8107) @opindex same-owner
tar.texi(,8108) @item --same-owner
tar.texi(,8109) Create extracted files with the same ownership they have in the
tar.texi(,8110) archive.
tar.texi(,8111) 
tar.texi(,8112) This is the default behavior for the superuser,
tar.texi(,8113) so this option is meaningful only for non-root users, when @command{tar}
tar.texi(,8114) is executed on those systems able to give files away.  This is
tar.texi(,8115) considered as a security flaw by many people, at least because it
tar.texi(,8116) makes quite difficult to correctly account users for the disk space
tar.texi(,8117) they occupy.  Also, the @code{suid} or @code{sgid} attributes of
tar.texi(,8118) files are easily and silently lost when files are given away.
tar.texi(,8119) 
tar.texi(,8120) When writing an archive, @command{tar} writes the user id and user name
tar.texi(,8121) separately.  If it can't find a user name (because the user id is not
tar.texi(,8122) in @file{/etc/passwd}), then it does not write one.  When restoring,
tar.texi(,8123) it tries to look the name (if one was written) up in
tar.texi(,8124) @file{/etc/passwd}.  If it fails, then it uses the user id stored in
tar.texi(,8125) the archive instead. 
tar.texi(,8126) 
tar.texi(,8127) @opindex no-same-owner
tar.texi(,8128) @item --no-same-owner
tar.texi(,8129) @itemx -o
tar.texi(,8130) Do not attempt to restore ownership when extracting.  This is the
tar.texi(,8131) default behavior for ordinary users, so this option has an effect
tar.texi(,8132) only for the superuser.
tar.texi(,8133) 
tar.texi(,8134) @opindex numeric-owner
tar.texi(,8135) @item --numeric-owner
tar.texi(,8136) The @option{--numeric-owner} option allows (ANSI) archives to be written
tar.texi(,8137) without user/group name information or such information to be ignored
tar.texi(,8138) when extracting.  It effectively disables the generation and/or use
tar.texi(,8139) of user/group name information.  This option forces extraction using
tar.texi(,8140) the numeric ids from the archive, ignoring the names.
tar.texi(,8141) 
tar.texi(,8142) This is useful in certain circumstances, when restoring a backup from
tar.texi(,8143) an emergency floppy with different passwd/group files for example.
tar.texi(,8144) It is otherwise impossible to extract files with the right ownerships
tar.texi(,8145) if the password file in use during the extraction does not match the
tar.texi(,8146) one belonging to the file system(s) being extracted.  This occurs,
tar.texi(,8147) for example, if you are restoring your files after a major crash and
tar.texi(,8148) had booted from an emergency floppy with no password file or put your
tar.texi(,8149) disk into another machine to do the restore.
tar.texi(,8150) 
tar.texi(,8151) The numeric ids are @emph{always} saved into @command{tar} archives.
tar.texi(,8152) The identifying names are added at create time when provided by the
tar.texi(,8153) system, unless @option{--old-archive} (@option{-o}) is used.  Numeric ids could be
tar.texi(,8154) used when moving archives between a collection of machines using
tar.texi(,8155) a centralized management for attribution of numeric ids to users
tar.texi(,8156) and groups.  This is often made through using the NIS capabilities.
tar.texi(,8157) 
tar.texi(,8158) When making a @command{tar} file for distribution to other sites, it
tar.texi(,8159) is sometimes cleaner to use a single owner for all files in the
tar.texi(,8160) distribution, and nicer to specify the write permission bits of the
tar.texi(,8161) files as stored in the archive independently of their actual value on
tar.texi(,8162) the file system.  The way to prepare a clean distribution is usually
tar.texi(,8163) to have some Makefile rule creating a directory, copying all needed
tar.texi(,8164) files in that directory, then setting ownership and permissions as
tar.texi(,8165) wanted (there are a lot of possible schemes), and only then making a
tar.texi(,8166) @command{tar} archive out of this directory, before cleaning
tar.texi(,8167) everything out.  Of course, we could add a lot of options to
tar.texi(GNUTAR,8168) @acronym{GNU} @command{tar} for fine tuning permissions and ownership.
tar.texi(GNUTAR,8169) This is not the good way, I think.  tar.texi(GNUTAR,8169) @acronym{GNU} @command{tar} is
tar.texi(,8170) already crowded with options and moreover, the approach just explained
tar.texi(,8171) gives you a great deal of control already.
tar.texi(,8172) 
tar.texi(xopindex,8173) @opindex same-permissions@r{, short description}
tar.texi(xopindex,8174) @opindex preserve-permissions@r{, short description}
tar.texi(,8175) @item -p
tar.texi(,8176) @itemx --same-permissions
tar.texi(,8177) @itemx --preserve-permissions
tar.texi(,8178) Extract all protection information.
tar.texi(,8179) 
tar.texi(,8180) This option causes @command{tar} to set the modes (access permissions) of
tar.texi(,8181) extracted files exactly as recorded in the archive.  If this option
tar.texi(,8182) is not used, the current @code{umask} setting limits the permissions
tar.texi(,8183) on extracted files.  This option is by default enabled when
tar.texi(,8184) @command{tar} is executed by a superuser.
tar.texi(,8185) 
tar.texi(,8186) 
tar.texi(,8187) This option is meaningless with @option{--list} (@option{-t}).
tar.texi(,8188) 
tar.texi(,8189) @opindex preserve
tar.texi(,8190) @item --preserve
tar.texi(,8191) Same as both @option{--same-permissions} and @option{--same-order}.
tar.texi(,8192) 
tar.texi(,8193) The @option{--preserve} option has no equivalent short option name.
tar.texi(,8194) It is equivalent to @option{--same-permissions} plus @option{--same-order}.
tar.texi(,8195) 
tar.texi(FIXME,8197) @allow-recursion
tar.texi(FIXME,8197) @quote-arg
tar.texi(FIXME,8197) 
tar.texi(,8198) 
tar.texi(,8199) @end table
tar.texi(,8200) 
tar.texi(,8201) @node Portability
tar.texi(,8202) @section Making @command{tar} Archives More Portable
tar.texi(,8203) 
tar.texi(,8204) Creating a @command{tar} archive on a particular system that is meant to be
tar.texi(,8205) useful later on many other machines and with other versions of @command{tar}
tar.texi(,8206) is more challenging than you might think.  @command{tar} archive formats
tar.texi(,8207) have been evolving since the first versions of Unix.  Many such formats
tar.texi(,8208) are around, and are not always compatible with each other.  This section
tar.texi(,8209) discusses a few problems, and gives some advice about making @command{tar}
tar.texi(,8210) archives more portable.
tar.texi(,8211) 
tar.texi(,8212) One golden rule is simplicity.  For example, limit your @command{tar}
tar.texi(,8213) archives to contain only regular files and directories, avoiding
tar.texi(,8214) other kind of special files.  Do not attempt to save sparse files or
tar.texi(,8215) contiguous files as such.  Let's discuss a few more problems, in turn.
tar.texi(,8216) 
tar.texi(FIXME,8218) @allow-recursion
tar.texi(FIXME,8218) @quote-arg
tar.texi(FIXME,8218) 
tar.texi(,8219) 
tar.texi(,8220) @menu
tar.texi(,8221) * Portable Names::              Portable Names
tar.texi(,8222) * dereference::                 Symbolic Links
tar.texi(,8223) * old::                         Old V7 Archives
tar.texi(,8224) * ustar::                       Ustar Archives
tar.texi(,8225) * gnu::                         GNU and old GNU format archives.
tar.texi(,8226) * posix::                       @acronym{POSIX} archives
tar.texi(,8227) * Checksumming::                Checksumming Problems
tar.texi(,8228) * Large or Negative Values::    Large files, negative time stamps, etc.
tar.texi(,8229) * Other Tars::                  How to Extract GNU-Specific Data Using
tar.texi(,8230)                                 Other @command{tar} Implementations
tar.texi(,8231) @end menu
tar.texi(,8232) 
tar.texi(,8233) @node Portable Names
tar.texi(,8234) @subsection Portable Names
tar.texi(,8235) 
tar.texi(,8236) Use portable file and member names.  A name is portable if it contains
tar.texi(,8237) only ASCII letters and digits, @samp{/}, @samp{.}, @samp{_}, and
tar.texi(,8238) @samp{-}; it cannot be empty, start with @samp{-} or @samp{//}, or
tar.texi(,8239) contain @samp{/-}.  Avoid deep directory nesting.  For portability to
tar.texi(,8240) old Unix hosts, limit your file name components to 14 characters or
tar.texi(,8241) less.
tar.texi(,8242) 
tar.texi(,8243) If you intend to have your @command{tar} archives to be read under
tar.texi(,8244) MSDOS, you should not rely on case distinction for file names, and you
tar.texi(,8245) might use the @acronym{GNU} @command{doschk} program for helping you
tar.texi(,8246) further diagnosing illegal MSDOS names, which are even more limited
tar.texi(,8247) than System V's.
tar.texi(,8248) 
tar.texi(,8249) @node dereference
tar.texi(,8250) @subsection Symbolic Links
tar.texi(,8251) @cindex File names, using symbolic links
tar.texi(,8252) @cindex Symbolic link as file name
tar.texi(,8253) 
tar.texi(,8254) @opindex dereference
tar.texi(,8255) Normally, when @command{tar} archives a symbolic link, it writes a
tar.texi(,8256) block to the archive naming the target of the link.  In that way, the
tar.texi(,8257) @command{tar} archive is a faithful record of the file system contents.
tar.texi(,8258) @option{--dereference} (@option{-h}) is used with @option{--create} (@option{-c}), and causes
tar.texi(,8259) @command{tar} to archive the files symbolic links point to, instead of
tar.texi(,8260) the links themselves.  When this option is used, when @command{tar}
tar.texi(,8261) encounters a symbolic link, it will archive the linked-to file,
tar.texi(,8262) instead of simply recording the presence of a symbolic link.
tar.texi(,8263) 
tar.texi(,8264) The name under which the file is stored in the file system is not
tar.texi(,8265) recorded in the archive.  To record both the symbolic link name and
tar.texi(,8266) the file name in the system, archive the file under both names.  If
tar.texi(,8267) all links were recorded automatically by @command{tar}, an extracted file
tar.texi(,8268) might be linked to a file name that no longer exists in the file
tar.texi(,8269) system.
tar.texi(,8270) 
tar.texi(,8271) If a linked-to file is encountered again by @command{tar} while creating
tar.texi(,8272) the same archive, an entire second copy of it will be stored.  (This
tar.texi(,8273) @emph{might} be considered a bug.)
tar.texi(,8274) 
tar.texi(,8275) So, for portable archives, do not archive symbolic links as such,
tar.texi(,8276) and use @option{--dereference} (@option{-h}): many systems do not support
tar.texi(,8277) symbolic links, and moreover, your distribution might be unusable if
tar.texi(,8278) it contains unresolved symbolic links.
tar.texi(,8279) 
tar.texi(,8280) @node old
tar.texi(,8281) @subsection Old V7 Archives
tar.texi(,8282) @cindex Format, old style
tar.texi(,8283) @cindex Old style format
tar.texi(,8284) @cindex Old style archives
tar.texi(,8285) @cindex v7 archive format
tar.texi(,8286) 
tar.texi(,8287) Certain old versions of @command{tar} cannot handle additional
tar.texi(,8288) information recorded by newer @command{tar} programs.  To create an
tar.texi(,8289) archive in V7 format (not ANSI), which can be read by these old
tar.texi(,8290) versions, specify the @option{--format=v7} option in
tar.texi(,8291) conjunction with the @option{--create} (@option{-c}) (@command{tar} also
tar.texi(,8292) accepts @option{--portability} or @option{--old-archive} for this
tar.texi(,8293) option).  When you specify it,
tar.texi(,8294) @command{tar} leaves out information about directories, pipes, fifos,
tar.texi(,8295) contiguous files, and device files, and specifies file ownership by
tar.texi(,8296) group and user IDs instead of group and user names.
tar.texi(,8297) 
tar.texi(,8298) When updating an archive, do not use @option{--format=v7}
tar.texi(,8299) unless the archive was created using this option.
tar.texi(,8300) 
tar.texi(,8301) In most cases, a @emph{new} format archive can be read by an @emph{old}
tar.texi(,8302) @command{tar} program without serious trouble, so this option should
tar.texi(,8303) seldom be needed.  On the other hand, most modern @command{tar}s are
tar.texi(,8304) able to read old format archives, so it might be safer for you to
tar.texi(,8305) always use @option{--format=v7} for your distributions.  Notice,
tar.texi(,8306) however, that @samp{ustar} format is a better alternative, as it is
tar.texi(,8307) free from many of @samp{v7}'s drawbacks.
tar.texi(,8308) 
tar.texi(,8309) @node ustar
tar.texi(,8310) @subsection Ustar Archive Format
tar.texi(,8311) 
tar.texi(,8312) @cindex ustar archive format
tar.texi(,8313) Archive format defined by @acronym{POSIX}.1-1988 specification is called
tar.texi(,8314) @code{ustar}.  Although it is more flexible than the V7 format, it
tar.texi(,8315) still has many restrictions (@xref{Formats,ustar}, for the detailed
tar.texi(,8316) description of @code{ustar} format).  Along with V7 format,
tar.texi(,8317) @code{ustar} format is a good choice for archives intended to be read
tar.texi(,8318) with other implementations of @command{tar}.
tar.texi(,8319) 
tar.texi(,8320) To create archive in @code{ustar} format, use @option{--format=ustar}
tar.texi(,8321) option in conjunction with the @option{--create} (@option{-c}).
tar.texi(,8322) 
tar.texi(,8323) @node gnu
tar.texi(GNUTAR,8324) @subsection @acronym{GNU} and old tar.texi(GNUTAR,8324) @acronym{GNU} @command{tar} format
tar.texi(,8325) 
tar.texi(,8326) @cindex GNU archive format
tar.texi(,8327) @cindex Old GNU archive format
tar.texi(GNUTAR,8328) @acronym{GNU} @command{tar} was based on an early draft of the
tar.texi(,8329) @acronym{POSIX} 1003.1 @code{ustar} standard.  @acronym{GNU} extensions to
tar.texi(,8330) @command{tar}, such as the support for file names longer than 100
tar.texi(,8331) characters, use portions of the @command{tar} header record which were
tar.texi(,8332) specified in that @acronym{POSIX} draft as unused.  Subsequent changes in
tar.texi(,8333) @acronym{POSIX} have allocated the same parts of the header record for
tar.texi(GNUTAR,8334) other purposes.  As a result, tar.texi(GNUTAR,8334) @acronym{GNU} @command{tar} format is
tar.texi(,8335) incompatible with the current @acronym{POSIX} specification, and with
tar.texi(,8336) @command{tar} programs that follow it.
tar.texi(,8337) 
tar.texi(,8338) In the majority of cases, @command{tar} will be configured to create
tar.texi(,8339) this format by default.  This will change in the future releases, since
tar.texi(,8340) we plan to make @samp{POSIX} format the default.
tar.texi(,8341) 
tar.texi(GNUTAR,8342) To force creation a tar.texi(GNUTAR,8342) @acronym{GNU} @command{tar} archive, use option
tar.texi(,8343) @option{--format=gnu}.
tar.texi(,8344) 
tar.texi(,8345) @node posix
tar.texi(GNUTAR,8346) @subsection tar.texi(GNUTAR,8346) @acronym{GNU} @command{tar} and @acronym{POSIX} @command{tar}
tar.texi(,8347) 
tar.texi(,8348) @cindex POSIX archive format
tar.texi(,8349) @cindex PAX archive format
tar.texi(GNUTAR,8350) Starting from version 1.14 tar.texi(GNUTAR,8350) @acronym{GNU} @command{tar} features full support for
tar.texi(,8351) @acronym{POSIX.1-2001} archives.
tar.texi(,8352) 
tar.texi(,8353) A @acronym{POSIX} conformant archive will be created if @command{tar}
tar.texi(,8354) was given @option{--format=posix} (@option{--format=pax}) option.  No
tar.texi(,8355) special option is required to read and extract from a @acronym{POSIX}
tar.texi(,8356) archive. 
tar.texi(,8357) 
tar.texi(,8358) @menu
tar.texi(,8359) * PAX keywords:: Controlling Extended Header Keywords.
tar.texi(,8360) @end menu
tar.texi(,8361) 
tar.texi(,8362) @node PAX keywords
tar.texi(,8363) @subsubsection Controlling Extended Header Keywords
tar.texi(,8364) 
tar.texi(,8365) @table @option
tar.texi(,8366) @opindex pax-option
tar.texi(,8367) @item --pax-option=@var{keyword-list}
tar.texi(,8368) Handle keywords in @acronym{PAX} extended headers.  This option is
tar.texi(,8369) equivalent to @option{-o} option of the @command{pax} utility.
tar.texi(,8370) @end table
tar.texi(,8371) 
tar.texi(,8372) @var{Keyword-list} is a comma-separated
tar.texi(,8373) list of keyword options, each keyword option taking one of
tar.texi(,8374) the following forms:
tar.texi(,8375) 
tar.texi(,8376) @table @code
tar.texi(,8377) @item delete=@var{pattern}
tar.texi(,8378) When used with one of archive-creation commands,
tar.texi(,8379) this option instructs @command{tar} to omit from extended header records
tar.texi(,8380) that it produces any keywords matching the string @var{pattern}.
tar.texi(,8381) 
tar.texi(,8382) When used in extract or list mode, this option instructs tar
tar.texi(,8383) to ignore any keywords matching the given @var{pattern} in the extended
tar.texi(,8384) header records.  In both cases, matching is performed using the pattern
tar.texi(,8385) matching notation described in @acronym{POSIX 1003.2}, 3.13
tar.texi(,8386) (@pxref{wildcards}). For example:
tar.texi(,8387) 
tar.texi(,8388) @smallexample
tar.texi(,8389) --pax-option delete=security.*
tar.texi(,8390) @end smallexample
tar.texi(,8391) 
tar.texi(,8392) would suppress security-related information.
tar.texi(,8393) 
tar.texi(,8394) @item exthdr.name=@var{string}
tar.texi(,8395) 
tar.texi(,8396) This keyword allows user control over the name that is written into the
tar.texi(,8397) ustar header blocks for the extended headers.  The name is obtained
tar.texi(,8398) from @var{string} after making the following substitutions:
tar.texi(,8399) 
tar.texi(,8400) @multitable @columnfractions .25 .55
tar.texi(,8401) @headitem Meta-character @tab Replaced By
tar.texi(,8402) @item %d @tab  The directory name of the file, equivalent to the
tar.texi(,8403) result of the @command{dirname} utility on the translated pathname.
tar.texi(,8404) @item %f @tab  The filename of the file, equivalent to the result
tar.texi(,8405) of the @command{basename} utility on the translated pathname.
tar.texi(,8406) @item %p @tab  The process ID of the @command{tar} process.
tar.texi(,8407) @item %% @tab  A @samp{%} character.
tar.texi(,8408) @end multitable
tar.texi(,8409) 
tar.texi(,8410) Any other @samp{%} characters in @var{string} produce undefined
tar.texi(,8411) results.
tar.texi(,8412) 
tar.texi(,8413) If no option @samp{exthdr.name=string} is specified, @command{tar}
tar.texi(,8414) will use the following default value:
tar.texi(,8415) 
tar.texi(,8416) @smallexample
tar.texi(,8417) %d/PaxHeaders.%p/%f
tar.texi(,8418) @end smallexample
tar.texi(,8419) 
tar.texi(,8420) @item globexthdr.name=@var{string}
tar.texi(,8421) This keyword allows user control over the name that is written into
tar.texi(,8422) the ustar header blocks for global extended header records.  The name
tar.texi(,8423) is obtained from the contents of @var{string}, after making
tar.texi(,8424) the following substitutions:
tar.texi(,8425) 
tar.texi(,8426) @multitable @columnfractions .25 .55
tar.texi(,8427) @headitem Meta-character @tab Replaced By
tar.texi(,8428) @item %n @tab An integer that represents the
tar.texi(,8429) sequence number of the global extended header record in the archive,
tar.texi(,8430) starting at 1.
tar.texi(,8431) @item %p @tab The process ID of the @command{tar} process.
tar.texi(,8432) @item %% @tab A @samp{%} character.
tar.texi(,8433) @end multitable
tar.texi(,8434) 
tar.texi(,8435) Any other @samp{%} characters in @var{string} produce undefined results.
tar.texi(,8436) 
tar.texi(,8437) If no option @samp{globexthdr.name=string} is specified, @command{tar}
tar.texi(,8438) will use the following default value:
tar.texi(,8439) 
tar.texi(,8440) @smallexample
tar.texi(,8441) $TMPDIR/GlobalHead.%p.%n
tar.texi(,8442) @end smallexample
tar.texi(,8443) 
tar.texi(,8444) @noindent
tar.texi(,8445) where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
tar.texi(,8446) environment variable.  If @var{TMPDIR} is not set, @command{tar}
tar.texi(,8447) uses @samp{/tmp}.
tar.texi(,8448) 
tar.texi(,8449) @item @var{keyword}=@var{value}
tar.texi(,8450) When used with one of archive-creation commands, these keyword/value pairs
tar.texi(,8451) will be included at the beginning of the archive in a global extended
tar.texi(,8452) header record.  When used with one of archive-reading commands,
tar.texi(,8453) @command{tar} will behave as if it has encountered these keyword/value
tar.texi(,8454) pairs at the beginning of the archive in a global extended header
tar.texi(,8455) record.
tar.texi(,8456) 
tar.texi(,8457) @item @var{keyword}:=@var{value}
tar.texi(,8458) When used with one of archive-creation commands, these keyword/value pairs
tar.texi(,8459) will be included as records at the beginning of an extended header for
tar.texi(,8460) each file.  This is effectively equivalent to @var{keyword}=@var{value}
tar.texi(,8461) form except that it creates no global extended header records.
tar.texi(,8462) 
tar.texi(,8463) When used with one of archive-reading commands, @command{tar} will
tar.texi(,8464) behave as if these keyword/value pairs were included as records at the
tar.texi(,8465) end of each extended header; thus, they will override any global or
tar.texi(,8466) file-specific extended header record keywords of the same names.
tar.texi(,8467) For example, in the command:
tar.texi(,8468) 
tar.texi(,8469) @smallexample
tar.texi(,8470) tar --format=posix --create \
tar.texi(,8471)     --file archive --pax-option gname:=user .
tar.texi(,8472) @end smallexample
tar.texi(,8473) 
tar.texi(,8474) the group name will be forced to a new value for all files
tar.texi(,8475) stored in the archive.
tar.texi(,8476) @end table
tar.texi(,8477) 
tar.texi(,8478) @node Checksumming
tar.texi(,8479) @subsection Checksumming Problems
tar.texi(,8480) 
tar.texi(,8481) SunOS and HP-UX @command{tar} fail to accept archives created using
tar.texi(GNUTAR,8482) @acronym{GNU} @command{tar} and containing non-ASCII file names, that
tar.texi(,8483) is, file names having characters with the eight bit set, because they
tar.texi(GNUTAR,8484) use signed checksums, while tar.texi(GNUTAR,8484) @acronym{GNU} @command{tar} uses unsigned
tar.texi(,8485) checksums while creating archives, as per @acronym{POSIX} standards.  On
tar.texi(GNUTAR,8486) reading, tar.texi(GNUTAR,8486) @acronym{GNU} @command{tar} computes both checksums and
tar.texi(,8487) accept any.  It is somewhat worrying that a lot of people may go
tar.texi(,8488) around doing backup of their files using faulty (or at least
tar.texi(,8489) non-standard) software, not learning about it until it's time to
tar.texi(,8490) restore their missing files with an incompatible file extractor, or
tar.texi(,8491) vice versa.
tar.texi(,8492) 
tar.texi(GNUTAR,8493) @acronym{GNU} @command{tar} compute checksums both ways, and accept
tar.texi(,8494) any on read, so @acronym{GNU} tar can read Sun tapes even with their
tar.texi(GNUTAR,8495) wrong checksums.  tar.texi(GNUTAR,8495) @acronym{GNU} @command{tar} produces the standard
tar.texi(,8496) checksum, however, raising incompatibilities with Sun.  That is to
tar.texi(GNUTAR,8497) say, tar.texi(GNUTAR,8497) @acronym{GNU} @command{tar} has not been modified to
tar.texi(,8498) @emph{produce} incorrect archives to be read by buggy @command{tar}'s.
tar.texi(,8499) I've been told that more recent Sun @command{tar} now read standard
tar.texi(,8500) archives, so maybe Sun did a similar patch, after all?
tar.texi(,8501) 
tar.texi(,8502) The story seems to be that when Sun first imported @command{tar}
tar.texi(,8503) sources on their system, they recompiled it without realizing that
tar.texi(,8504) the checksums were computed differently, because of a change in
tar.texi(,8505) the default signing of @code{char}'s in their compiler.  So they
tar.texi(,8506) started computing checksums wrongly.  When they later realized their
tar.texi(,8507) mistake, they merely decided to stay compatible with it, and with
tar.texi(,8508) themselves afterwards.  Presumably, but I do not really know, HP-UX
tar.texi(,8509) has chosen that their @command{tar} archives to be compatible with Sun's.
tar.texi(,8510) The current standards do not favor Sun @command{tar} format.  In any
tar.texi(,8511) case, it now falls on the shoulders of SunOS and HP-UX users to get
tar.texi(,8512) a @command{tar} able to read the good archives they receive.
tar.texi(,8513) 
tar.texi(,8514) @node Large or Negative Values
tar.texi(,8515) @subsection Large or Negative Values
tar.texi(,8516) @cindex large values
tar.texi(,8517) @cindex future time stamps
tar.texi(,8518) @cindex negative time stamps
tar.texi(UNREVISED,8519) @quotation
tar.texi(UNREVISED,8519) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,8519) @end quotation
tar.texi(,8520) 
tar.texi(,8521) The above sections suggest to use @samp{oldest possible} archive
tar.texi(,8522) format if in doubt.  However, sometimes it is not possible.  If you
tar.texi(,8523) attempt to archive a file whose metadata cannot be represented using
tar.texi(GNUTAR,8524) required format, tar.texi(GNUTAR,8524) @acronym{GNU} @command{tar} will print error message and ignore such a
tar.texi(,8525) file.  You will than have to switch to a format that is able to
tar.texi(,8526) handle such values.  The format summary table (@pxref{Formats}) will
tar.texi(,8527) help you to do so.
tar.texi(,8528) 
tar.texi(,8529) In particular, when trying to archive files larger than 8GB or with
tar.texi(,8530) timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16
tar.texi(,8531) 12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and
tar.texi(,8532) @acronym{POSIX} archive formats.  When considering which format to
tar.texi(,8533) choose, bear in mind that the @acronym{GNU} format uses
tar.texi(,8534) two's-complement base-256 notation to store values that do not fit
tar.texi(,8535) into standard @acronym{ustar} range.  Such archives can generally be
tar.texi(GNUTAR,8536) read only by a tar.texi(GNUTAR,8536) @acronym{GNU} @command{tar} implementation.  Moreover, they sometimes
tar.texi(GNUTAR,8537) cannot be correctly restored on another hosts even by tar.texi(GNUTAR,8537) @acronym{GNU} @command{tar}. For
tar.texi(,8538) example, using two's complement representation for negative time
tar.texi(,8539) stamps that assumes a signed 32-bit @code{time_t} generates archives
tar.texi(,8540) that are not portable to hosts with differing @code{time_t}
tar.texi(,8541) representations.
tar.texi(,8542) 
tar.texi(,8543) On the other hand, @acronym{POSIX} archives, generally speaking, can
tar.texi(,8544) be extracted by any tar implementation that understands older
tar.texi(,8545) @acronym{ustar} format.  The only exception are files larger than 8GB.
tar.texi(,8546) 
tar.texi(FIXME,8548) @allow-recursion
tar.texi(FIXME,8548) @quote-arg
tar.texi(FIXME,8548) 
tar.texi(,8549) 
tar.texi(,8550) @node Other Tars
tar.texi(,8551) @subsection How to Extract GNU-Specific Data Using Other @command{tar} Implementations
tar.texi(,8552) 
tar.texi(,8553) In previous sections you became acquainted with various quircks
tar.texi(,8554) necessary to make your archives portable.  Sometimes you may need to
tar.texi(,8555) extract archives containing GNU-specific members using some
tar.texi(,8556) third-party @command{tar} implementation or an older version of
tar.texi(GNUTAR,8557) @acronym{GNU} @command{tar}.  Of course your best bet is to have tar.texi(GNUTAR,8557) @acronym{GNU} @command{tar} installed,
tar.texi(,8558) but if it is for some reason impossible, this section will explain
tar.texi(,8559) how to cope without it. 
tar.texi(,8560) 
tar.texi(,8561) When we speak about @dfn{GNU-specific} members we mean two classes of
tar.texi(,8562) them: members split between the volumes of a multi-volume archive and
tar.texi(,8563) sparse members.  You will be able to always recover such members if
tar.texi(,8564) the archive is in PAX format.  In addition split members can be
tar.texi(,8565) recovered from archives in old GNU format.  The following subsections
tar.texi(,8566) describe the required procedures in detail.
tar.texi(,8567) 
tar.texi(,8568) @menu
tar.texi(,8569) * Split Recovery::       Members Split Between Volumes
tar.texi(,8570) * Sparse Recovery::      Sparse Members
tar.texi(,8571) @end menu
tar.texi(,8572) 
tar.texi(,8573) @node Split Recovery
tar.texi(,8574) @subsubsection Extracting Members Split Between Volumes
tar.texi(,8575) 
tar.texi(,8576) @cindex Mutli-volume archives, extracting using non-GNU tars
tar.texi(,8577) If a member is split between several volumes of an old GNU format archive
tar.texi(,8578) most third party @command{tar} implementation will fail to extract
tar.texi(,8579) it.  To extract it, use @command{tarcat} program (@pxref{Tarcat}).
tar.texi(,8580) This program is available from
tar.texi(GNUTAR,8581) @uref{http://www.gnu.org/@/software/@/tar/@/utils/@/tarcat.html, @acronym{GNU} @command{tar}
tar.texi(,8582) home page}.  It concatenates several archive volumes into a single
tar.texi(,8583) valid archive.  For example, if you have three volumes named from
tar.texi(,8584) @file{vol-1.tar} to @file{vol-2.tar}, you can do the following to
tar.texi(,8585) extract them using a third-party @command{tar}:
tar.texi(,8586) 
tar.texi(,8587) @smallexample
tar.texi(,8588) $ @kbd{tarcat vol-1.tar vol-2.tar vol-3.tar | tar xf -}
tar.texi(,8589) @end smallexample
tar.texi(,8590) 
tar.texi(,8591) @cindex Mutli-volume archives in PAX format, extracting using non-GNU tars
tar.texi(,8592) You could use this approach for many (although not all) PAX
tar.texi(,8593) format archives as well.  However, extracting split members from a PAX
tar.texi(,8594) archive is a much easier task, because PAX volumes are constructed in
tar.texi(,8595) such a way that each part of a split member is extracted as a
tar.texi(,8596) different file by @command{tar} implementations that are not aware of
tar.texi(,8597) GNU extensions.  More specifically, the very first part retains its
tar.texi(,8598) original name, and all subsequent parts are named using the pattern:
tar.texi(,8599) 
tar.texi(,8600) @smallexample
tar.texi(,8601) %d/GNUFileParts.%p/%f.%n
tar.texi(,8602) @end smallexample
tar.texi(,8603) 
tar.texi(,8604) @noindent
tar.texi(,8605) where symbols preceeded by @samp{%} are @dfn{macro characters} that
tar.texi(,8606) have the following meaning:
tar.texi(,8607) 
tar.texi(,8608) @multitable @columnfractions .25 .55
tar.texi(,8609) @headitem Meta-character @tab Replaced By
tar.texi(,8610) @item %d @tab  The directory name of the file, equivalent to the
tar.texi(,8611) result of the @command{dirname} utility on its full name.
tar.texi(,8612) @item %f @tab  The file name of the file, equivalent to the result
tar.texi(,8613) of the @command{basename} utility on its full name.
tar.texi(,8614) @item %p @tab  The process ID of the @command{tar} process that
tar.texi(,8615) created the archive.
tar.texi(,8616) @item %n @tab  Ordinal number of this particular part.
tar.texi(,8617) @end multitable
tar.texi(,8618) 
tar.texi(,8619) For example, if, a file @file{var/longfile} was split during archive
tar.texi(,8620) creation between three volumes, and the creator @command{tar} process
tar.texi(,8621) had process ID @samp{27962}, then the member names will be:
tar.texi(,8622) 
tar.texi(,8623) @smallexample
tar.texi(,8624) var/longfile
tar.texi(,8625) var/GNUFileParts.27962/longfile.1
tar.texi(,8626) var/GNUFileParts.27962/longfile.2
tar.texi(,8627) @end smallexample
tar.texi(,8628) 
tar.texi(,8629) When you extract your archive using a third-party @command{tar}, these
tar.texi(,8630) files will be created on your disk, and the only thing you will need
tar.texi(,8631) to do to restore your file in its original form is concatenate them in
tar.texi(,8632) the proper order, for example:
tar.texi(,8633) 
tar.texi(,8634) @smallexample
tar.texi(,8635) @group
tar.texi(,8636) $ @kbd{cd var}
tar.texi(,8637) $ @kbd{cat GNUFileParts.27962/longfile.1 \
tar.texi(,8638)   GNUFileParts.27962/longfile.2 >> longfile}
tar.texi(,8639) $ rm -f GNUFileParts.27962
tar.texi(,8640) @end group
tar.texi(,8641) @end smallexample
tar.texi(,8642) 
tar.texi(,8643) Notice, that if the @command{tar} implementation you use supports PAX
tar.texi(,8644) format archives, it will probably emit warnings about unknown keywords
tar.texi(,8645) during extraction.  They will lool like this:
tar.texi(,8646) 
tar.texi(,8647) @smallexample
tar.texi(,8648) @group
tar.texi(,8649) Tar file too small
tar.texi(,8650) Unknown extended header keyword 'GNU.volume.filename' ignored.
tar.texi(,8651) Unknown extended header keyword 'GNU.volume.size' ignored.
tar.texi(,8652) Unknown extended header keyword 'GNU.volume.offset' ignored.
tar.texi(,8653) @end group
tar.texi(,8654) @end smallexample
tar.texi(,8655) 
tar.texi(,8656) @noindent
tar.texi(,8657) You can safely ignore these warnings.
tar.texi(,8658) 
tar.texi(,8659) If your @command{tar} implementation is not PAX-aware, you will get
tar.texi(,8660) more warnigns and more files generated on your disk, e.g.:
tar.texi(,8661) 
tar.texi(,8662) @smallexample
tar.texi(,8663) @group
tar.texi(,8664) $ @kbd{tar xf vol-1.tar}
tar.texi(,8665) var/PaxHeaders.27962/longfile: Unknown file type 'x', extracted as
tar.texi(,8666) normal file 
tar.texi(,8667) Unexpected EOF in archive
tar.texi(,8668) $ @kbd{tar xf vol-2.tar}
tar.texi(,8669) tmp/GlobalHead.27962.1: Unknown file type 'g', extracted as normal file
tar.texi(,8670) GNUFileParts.27962/PaxHeaders.27962/sparsefile.1: Unknown file type
tar.texi(,8671) 'x', extracted as normal file
tar.texi(,8672) @end group
tar.texi(,8673) @end smallexample
tar.texi(,8674) 
tar.texi(,8675) Ignore these warnings.  The @file{PaxHeaders.*} directories created
tar.texi(,8676) will contain files with @dfn{extended header keywords} describing the
tar.texi(,8677) extracted files.  You can delete them, unless they describe sparse
tar.texi(,8678) members.  Read further to learn more about them.
tar.texi(,8679) 
tar.texi(,8680) @node Sparse Recovery
tar.texi(,8681) @subsubsection Extracting Sparse Members
tar.texi(,8682) 
tar.texi(,8683) @cindex sparse files, extracting with non-GNU tars
tar.texi(,8684) Any @command{tar} implementation will be able to extract sparse members from a
tar.texi(,8685) PAX archive.  However, the extracted files will be @dfn{condensed},
tar.texi(,8686) i.e. any zero blocks will be removed from them.  When we restore such
tar.texi(,8687) a condensed file to its original form, by adding zero bloks (or
tar.texi(,8688) @dfn{holes}) back to their original locations, we call this process
tar.texi(,8689) @dfn{expanding} a compressed sparse file.
tar.texi(,8690) 
tar.texi(,8691) @pindex xsparse
tar.texi(,8692) To expand a file, you will need a simple auxiliary program called
tar.texi(,8693) @command{xsparse}.  It is available in source form from
tar.texi(GNUTAR,8694) @uref{http://www.gnu.org/@/software/@/tar/@/utils/@/xsparse.html, @acronym{GNU} @command{tar}
tar.texi(,8695) home page}.
tar.texi(,8696) 
tar.texi(,8697) @cindex sparse files v.1.0, extracting with non-GNU tars
tar.texi(,8698) Let's begin with archive members in @dfn{sparse format
tar.texi(,8699) version 1.0}@footnote{@xref{PAX 1}.}, which are the easiest to expand.
tar.texi(,8700) The condensed file will contain both file map and file data, so no
tar.texi(,8701) additional data will be needed to restore it.  If the original file
tar.texi(,8702) name was @file{@var{dir}/@var{name}}, then the condensed file will be
tar.texi(,8703) named @file{@var{dir}/@/GNUSparseFile.@var{n}/@/@var{name}}, where 
tar.texi(,8704) @var{n} is a decimal number@footnote{technically speaking, @var{n} is a
tar.texi(,8705) @dfn{process ID} of the @command{tar} process which created the
tar.texi(,8706) archive (@pxref{PAX keywords}).}.
tar.texi(,8707) 
tar.texi(,8708) To expand a version 1.0 file, run @command{xsparse} as follows:
tar.texi(,8709) 
tar.texi(,8710) @smallexample
tar.texi(,8711) $ @kbd{xsparse @file{cond-file}}
tar.texi(,8712) @end smallexample
tar.texi(,8713) 
tar.texi(,8714) @noindent
tar.texi(,8715) where @file{cond-file} is the name of the condensed file.  The utility
tar.texi(,8716) will deduce the name for the resulting expanded file using the
tar.texi(,8717) following algorithm:
tar.texi(,8718) 
tar.texi(,8719) @enumerate 1
tar.texi(,8720) @item If @file{cond-file} does not contain any directories,
tar.texi(,8721) @file{../cond-file} will be used;
tar.texi(,8722) 
tar.texi(,8723) @item If @file{cond-file} has the form
tar.texi(,8724) @file{@var{dir}/@var{t}/@var{name}}, where both @var{t} and @var{name}
tar.texi(,8725) are simple names, with no @samp{/} characters in them, the output file
tar.texi(,8726) name will be @file{@var{dir}/@var{name}}.
tar.texi(,8727) 
tar.texi(,8728) @item Otherwise, if @file{cond-file} has the form
tar.texi(,8729) @file{@var{dir}/@var{name}}, the output file name will be
tar.texi(,8730) @file{@var{name}}.
tar.texi(,8731) @end enumerate
tar.texi(,8732) 
tar.texi(,8733) In the unlikely case when this algorithm does not suite your needs,
tar.texi(,8734) you can explicitely specify output file name as a second argument to
tar.texi(,8735) the command:
tar.texi(,8736) 
tar.texi(,8737) @smallexample
tar.texi(,8738) $ @kbd{xsparse @file{cond-file}}
tar.texi(,8739) @end smallexample
tar.texi(,8740) 
tar.texi(,8741) It is often a good idea to run @command{xsparse} in @dfn{dry run} mode
tar.texi(,8742) first.  In this mode, the command does not actually expand the file,
tar.texi(,8743) but verbosely lists all actions it would be taking to do so.  The dry
tar.texi(,8744) run mode is enabled by @option{-n} command line argument:
tar.texi(,8745) 
tar.texi(,8746) @smallexample
tar.texi(,8747) @group
tar.texi(,8748) $ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile}
tar.texi(,8749) Reading v.1.0 sparse map
tar.texi(,8750) Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
tar.texi(,8751) `/home/gray/sparsefile'
tar.texi(,8752) Finished dry run
tar.texi(,8753) @end group
tar.texi(,8754) @end smallexample
tar.texi(,8755) 
tar.texi(,8756) To actually expand the file, you would run:
tar.texi(,8757) 
tar.texi(,8758) @smallexample
tar.texi(,8759) $ @kbd{xsparse /home/gray/GNUSparseFile.6058/sparsefile}
tar.texi(,8760) @end smallexample
tar.texi(,8761) 
tar.texi(,8762) @noindent
tar.texi(,8763) The program behaves the same way all UNIX utilities do: it will keep
tar.texi(,8764) quiet unless it has simething important to tell you (e.g. an error
tar.texi(,8765) condition or something).  If you wish it to produce verbose output,
tar.texi(,8766) similar to that from the dry run mode, give it @option{-v} option:
tar.texi(,8767) 
tar.texi(,8768) @smallexample
tar.texi(,8769) @group
tar.texi(,8770) $ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile}
tar.texi(,8771) Reading v.1.0 sparse map
tar.texi(,8772) Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
tar.texi(,8773) `/home/gray/sparsefile'
tar.texi(,8774) Done
tar.texi(,8775) @end group
tar.texi(,8776) @end smallexample
tar.texi(,8777) 
tar.texi(,8778) Additionally, if your @command{tar} implementation has extracted the
tar.texi(,8779) @dfn{extended headers} for this file, you can instruct @command{xstar}
tar.texi(,8780) to use them in order to verify the integrity of the expanded file.
tar.texi(,8781) The option @option{-x} sets the name of the extended header file to
tar.texi(,8782) use.  Continuing our example:
tar.texi(,8783) 
tar.texi(,8784) @smallexample
tar.texi(,8785) @group
tar.texi(,8786) $ @kbd{xsparse -v -x /home/gray/PaxHeaders.6058/sparsefile \
tar.texi(,8787)   /home/gray/GNUSparseFile.6058/sparsefile}
tar.texi(,8788) Reading extended header file
tar.texi(,8789) Found variable GNU.sparse.major = 1
tar.texi(,8790) Found variable GNU.sparse.minor = 0
tar.texi(,8791) Found variable GNU.sparse.name = sparsefile
tar.texi(,8792) Found variable GNU.sparse.realsize = 217481216
tar.texi(,8793) Reading v.1.0 sparse map
tar.texi(,8794) Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to
tar.texi(,8795) `/home/gray/sparsefile'
tar.texi(,8796) Done
tar.texi(,8797) @end group
tar.texi(,8798) @end smallexample
tar.texi(,8799) 
tar.texi(,8800) @anchor{extracting sparse v.0.x}
tar.texi(,8801) @cindex sparse files v.0.1, extracting with non-GNU tars
tar.texi(,8802) @cindex sparse files v.0.0, extracting with non-GNU tars
tar.texi(,8803) An @dfn{extended header} is a special @command{tar} archive header
tar.texi(,8804) that precedes an archive member and contains a set of
tar.texi(,8805) @dfn{variables}, describing the member properties that cannot be
tar.texi(,8806) stored in the standard @code{ustar} header.  While optional for
tar.texi(,8807) expanding sparse version 1.0 members, use of extended headers is
tar.texi(,8808) mandatory when expanding sparse members in older sparse formats: v.0.0
tar.texi(,8809) and v.0.1 (The sparse formats are described in detail in @pxref{Sparse
tar.texi(,8810) Formats}).  So, for this format, the question is: how to obtain
tar.texi(,8811) extended headers from the archive? 
tar.texi(,8812) 
tar.texi(,8813) If you use a @command{tar} implementation that does not support PAX
tar.texi(,8814) format, extended headers for each member will be extracted as a 
tar.texi(,8815) separate file.  If we represent the member name as
tar.texi(,8816) @file{@var{dir}/@var{name}}, then the extended header file will be
tar.texi(,8817) named @file{@var{dir}/@/PaxHeaders.@var{n}/@/@var{name}}, where
tar.texi(,8818) @var{n} is an integer number.
tar.texi(,8819) 
tar.texi(,8820) Things become more difficult if your @command{tar} implementation
tar.texi(,8821) does support PAX headers, because in this case you will have to
tar.texi(,8822) manually extract the headers.  We recommend the following algorithm:
tar.texi(,8823) 
tar.texi(,8824) @enumerate 1
tar.texi(,8825) @item 
tar.texi(,8826) Consult the documentation for your @command{tar} implementation for an
tar.texi(,8827) option that will print @dfn{block numbers} along with the archive
tar.texi(GNUTAR,8828) listing (analogous to tar.texi(GNUTAR,8828) @acronym{GNU} @command{tar}'s @option{-R} option).  For example,
tar.texi(,8829) @command{star} has @option{-block-number}.
tar.texi(,8830) 
tar.texi(,8831) @item
tar.texi(,8832) Obtain the verbose listing using the @samp{block number} option, and
tar.texi(,8833) find the position of the sparse member in question and the member
tar.texi(,8834) immediately following it.  For example, running @command{star} on our
tar.texi(,8835) archive we obtain:
tar.texi(,8836) 
tar.texi(,8837) @smallexample
tar.texi(,8838) @group
tar.texi(,8839) $ @kbd{star -t -v -block-number -f arc.tar}
tar.texi(,8840) @dots{}
tar.texi(,8841) star: Unknown extended header keyword 'GNU.sparse.size' ignored.
tar.texi(,8842) star: Unknown extended header keyword 'GNU.sparse.numblocks' ignored.
tar.texi(,8843) star: Unknown extended header keyword 'GNU.sparse.name' ignored.
tar.texi(,8844) star: Unknown extended header keyword 'GNU.sparse.map' ignored.
tar.texi(,8845) block        56:  425984 -rw-r--r--  gray/users Jun 25 14:46 2006 GNUSparseFile.28124/sparsefile
tar.texi(,8846) block       897:   65391 -rw-r--r--  gray/users Jun 24 20:06 2006 README
tar.texi(,8847) @dots{}
tar.texi(,8848) @end group
tar.texi(,8849) @end smallexample
tar.texi(,8850) 
tar.texi(,8851) @noindent
tar.texi(,8852) (as usual, ignore the warnings about unknown keywords.)
tar.texi(,8853) 
tar.texi(,8854) @item
tar.texi(,8855) Let @var{size} be the size of the sparse member, @var{Bs} be its block number
tar.texi(,8856) and @var{Bn} be the block number of the next member.
tar.texi(,8857) Compute: 
tar.texi(,8858) 
tar.texi(,8859) @smallexample
tar.texi(,8860) @var{N} = @var{Bs} - @var{Bn} - @var{size}/512 - 2
tar.texi(,8861) @end smallexample
tar.texi(,8862) 
tar.texi(,8863) @noindent
tar.texi(,8864) This number gives the size of the extended header part in tar @dfn{blocks}.
tar.texi(,8865) In our example, this formula gives: @code{897 - 56 - 425984 / 512 - 2
tar.texi(,8866) = 7}.
tar.texi(,8867) 
tar.texi(,8868) @item
tar.texi(,8869) Use @command{dd} to extract the headers:
tar.texi(,8870) 
tar.texi(,8871) @smallexample
tar.texi(,8872) @kbd{dd if=@var{archive} of=@var{hname} bs=512 skip=@var{Bs} count=@var{N}}
tar.texi(,8873) @end smallexample
tar.texi(,8874) 
tar.texi(,8875) @noindent
tar.texi(,8876) where @var{archive} is the archive name, @var{hname} is a name of the
tar.texi(,8877) file to store the extended header in, @var{Bs} and @var{N} are
tar.texi(,8878) computed in previous steps.
tar.texi(,8879) 
tar.texi(,8880) In our example, this command will be
tar.texi(,8881) 
tar.texi(,8882) @smallexample
tar.texi(,8883) $ @kbd{dd if=arc.tar of=xhdr bs=512 skip=56 count=7}
tar.texi(,8884) @end smallexample
tar.texi(,8885) @end enumerate
tar.texi(,8886) 
tar.texi(,8887) Finally, you can expand the condensed file, using the obtained header:
tar.texi(,8888) 
tar.texi(,8889) @smallexample
tar.texi(,8890) @group
tar.texi(,8891) $ @kbd{xsparse -v -x xhdr GNUSparseFile.6058/sparsefile}
tar.texi(,8892) Reading extended header file
tar.texi(,8893) Found variable GNU.sparse.size = 217481216
tar.texi(,8894) Found variable GNU.sparse.numblocks = 208
tar.texi(,8895) Found variable GNU.sparse.name = sparsefile
tar.texi(,8896) Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{}
tar.texi(,8897) Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile'
tar.texi(,8898) Done
tar.texi(,8899) @end group
tar.texi(,8900) @end smallexample
tar.texi(,8901) 
tar.texi(,8902) @node cpio
tar.texi(,8903) @section Comparison of @command{tar} and @command{cpio}
tar.texi(UNREVISED,8904) @quotation
tar.texi(UNREVISED,8904) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,8904) @end quotation
tar.texi(,8905) 
tar.texi(FIXME,8906) @allow-recursion
tar.texi(FIXME,8906) @quote-arg
tar.texi(FIXME,8906) 
tar.texi(,8907) 
tar.texi(,8908) The @command{cpio} archive formats, like @command{tar}, do have maximum
tar.texi(,8909) pathname lengths.  The binary and old ASCII formats have a max path
tar.texi(,8910) length of 256, and the new ASCII and CRC ASCII formats have a max
tar.texi(,8911) path length of 1024.  @acronym{GNU} @command{cpio} can read and write archives
tar.texi(,8912) with arbitrary pathname lengths, but other @command{cpio} implementations
tar.texi(,8913) may crash unexplainedly trying to read them.
tar.texi(,8914) 
tar.texi(,8915) @command{tar} handles symbolic links in the form in which it comes in BSD;
tar.texi(,8916) @command{cpio} doesn't handle symbolic links in the form in which it comes
tar.texi(,8917) in System V prior to SVR4, and some vendors may have added symlinks
tar.texi(,8918) to their system without enhancing @command{cpio} to know about them.
tar.texi(,8919) Others may have enhanced it in a way other than the way I did it
tar.texi(,8920) at Sun, and which was adopted by AT&T (and which is, I think, also
tar.texi(,8921) present in the @command{cpio} that Berkeley picked up from AT&T and put
tar.texi(,8922) into a later BSD release---I think I gave them my changes).
tar.texi(,8923) 
tar.texi(,8924) (SVR4 does some funny stuff with @command{tar}; basically, its @command{cpio}
tar.texi(,8925) can handle @command{tar} format input, and write it on output, and it
tar.texi(,8926) probably handles symbolic links.  They may not have bothered doing
tar.texi(,8927) anything to enhance @command{tar} as a result.)
tar.texi(,8928) 
tar.texi(,8929) @command{cpio} handles special files; traditional @command{tar} doesn't.
tar.texi(,8930) 
tar.texi(,8931) @command{tar} comes with V7, System III, System V, and BSD source;
tar.texi(,8932) @command{cpio} comes only with System III, System V, and later BSD
tar.texi(,8933) (4.3-tahoe and later).
tar.texi(,8934) 
tar.texi(,8935) @command{tar}'s way of handling multiple hard links to a file can handle
tar.texi(,8936) file systems that support 32-bit inumbers (e.g., the BSD file system);
tar.texi(,8937) @command{cpio}s way requires you to play some games (in its "binary"
tar.texi(,8938) format, i-numbers are only 16 bits, and in its "portable ASCII" format,
tar.texi(,8939) they're 18 bits---it would have to play games with the "file system ID"
tar.texi(,8940) field of the header to make sure that the file system ID/i-number pairs
tar.texi(,8941) of different files were always different), and I don't know which
tar.texi(,8942) @command{cpio}s, if any, play those games.  Those that don't might get
tar.texi(,8943) confused and think two files are the same file when they're not, and
tar.texi(,8944) make hard links between them.
tar.texi(,8945) 
tar.texi(,8946) @command{tar}s way of handling multiple hard links to a file places only
tar.texi(,8947) one copy of the link on the tape, but the name attached to that copy
tar.texi(,8948) is the @emph{only} one you can use to retrieve the file; @command{cpio}s
tar.texi(,8949) way puts one copy for every link, but you can retrieve it using any
tar.texi(,8950) of the names.
tar.texi(,8951) 
tar.texi(,8952) @quotation
tar.texi(,8953) What type of check sum (if any) is used, and how is this calculated.
tar.texi(,8954) @end quotation
tar.texi(,8955) 
tar.texi(,8956) See the attached manual pages for @command{tar} and @command{cpio} format.
tar.texi(,8957) @command{tar} uses a checksum which is the sum of all the bytes in the
tar.texi(,8958) @command{tar} header for a file; @command{cpio} uses no checksum.
tar.texi(,8959) 
tar.texi(,8960) @quotation
tar.texi(,8961) If anyone knows why @command{cpio} was made when @command{tar} was present
tar.texi(,8962) at the unix scene,
tar.texi(,8963) @end quotation
tar.texi(,8964) 
tar.texi(,8965) It wasn't.  @command{cpio} first showed up in PWB/UNIX 1.0; no
tar.texi(,8966) generally-available version of UNIX had @command{tar} at the time.  I don't
tar.texi(,8967) know whether any version that was generally available @emph{within AT&T}
tar.texi(,8968) had @command{tar}, or, if so, whether the people within AT&T who did
tar.texi(,8969) @command{cpio} knew about it.
tar.texi(,8970) 
tar.texi(,8971) On restore, if there is a corruption on a tape @command{tar} will stop at
tar.texi(,8972) that point, while @command{cpio} will skip over it and try to restore the
tar.texi(,8973) rest of the files.
tar.texi(,8974) 
tar.texi(,8975) The main difference is just in the command syntax and header format.
tar.texi(,8976) 
tar.texi(,8977) @command{tar} is a little more tape-oriented in that everything is blocked
tar.texi(,8978) to start on a record boundary.
tar.texi(,8979) 
tar.texi(,8980) @quotation
tar.texi(,8981) Is there any differences between the ability to recover crashed
tar.texi(,8982) archives between the two of them.  (Is there any chance of recovering
tar.texi(,8983) crashed archives at all.)
tar.texi(,8984) @end quotation
tar.texi(,8985) 
tar.texi(,8986) Theoretically it should be easier under @command{tar} since the blocking
tar.texi(,8987) lets you find a header with some variation of @samp{dd skip=@var{nn}}.
tar.texi(,8988) However, modern @command{cpio}'s and variations have an option to just
tar.texi(,8989) search for the next file header after an error with a reasonable chance
tar.texi(,8990) of resyncing.  However, lots of tape driver software won't allow you to
tar.texi(,8991) continue past a media error which should be the only reason for getting
tar.texi(,8992) out of sync unless a file changed sizes while you were writing the
tar.texi(,8993) archive.
tar.texi(,8994) 
tar.texi(,8995) @quotation
tar.texi(,8996) If anyone knows why @command{cpio} was made when @command{tar} was present
tar.texi(,8997) at the unix scene, please tell me about this too.
tar.texi(,8998) @end quotation
tar.texi(,8999) 
tar.texi(,9000) Probably because it is more media efficient (by not blocking everything
tar.texi(,9001) and using only the space needed for the headers where @command{tar}
tar.texi(,9002) always uses 512 bytes per file header) and it knows how to archive
tar.texi(,9003) special files.
tar.texi(,9004) 
tar.texi(,9005) You might want to look at the freely available alternatives.  The
tar.texi(GNUTAR,9006) major ones are @command{afio}, tar.texi(GNUTAR,9006) @acronym{GNU} @command{tar}, and
tar.texi(,9007) @command{pax}, each of which have their own extensions with some
tar.texi(,9008) backwards compatibility.
tar.texi(,9009) 
tar.texi(,9010) Sparse files were @command{tar}red as sparse files (which you can
tar.texi(,9011) easily test, because the resulting archive gets smaller, and
tar.texi(,9012) @acronym{GNU} @command{cpio} can no longer read it).
tar.texi(,9013) 
tar.texi(,9014) @node Media
tar.texi(,9015) @chapter Tapes and Other Archive Media
tar.texi(UNREVISED,9016) @quotation
tar.texi(UNREVISED,9016) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,9016) @end quotation
tar.texi(,9017) 
tar.texi(,9018) A few special cases about tape handling warrant more detailed
tar.texi(,9019) description.  These special cases are discussed below.
tar.texi(,9020) 
tar.texi(,9021) Many complexities surround the use of @command{tar} on tape drives.  Since
tar.texi(,9022) the creation and manipulation of archives located on magnetic tape was
tar.texi(,9023) the original purpose of @command{tar}, it contains many features making
tar.texi(,9024) such manipulation easier.
tar.texi(,9025) 
tar.texi(,9026) Archives are usually written on dismountable media---tape cartridges,
tar.texi(,9027) mag tapes, or floppy disks.
tar.texi(,9028) 
tar.texi(,9029) The amount of data a tape or disk holds depends not only on its size,
tar.texi(,9030) but also on how it is formatted.  A 2400 foot long reel of mag tape
tar.texi(,9031) holds 40 megabytes of data when formatted at 1600 bits per inch.  The
tar.texi(,9032) physically smaller EXABYTE tape cartridge holds 2.3 gigabytes.
tar.texi(,9033) 
tar.texi(,9034) Magnetic media are re-usable---once the archive on a tape is no longer
tar.texi(,9035) needed, the archive can be erased and the tape or disk used over.
tar.texi(,9036) Media quality does deteriorate with use, however.  Most tapes or disks
tar.texi(,9037) should be discarded when they begin to produce data errors.  EXABYTE
tar.texi(,9038) tape cartridges should be discarded when they generate an @dfn{error
tar.texi(,9039) count} (number of non-usable bits) of more than 10k.
tar.texi(,9040) 
tar.texi(,9041) Magnetic media are written and erased using magnetic fields, and
tar.texi(,9042) should be protected from such fields to avoid damage to stored data.
tar.texi(,9043) Sticking a floppy disk to a filing cabinet using a magnet is probably
tar.texi(,9044) not a good idea.
tar.texi(,9045) 
tar.texi(,9046) @menu
tar.texi(,9047) * Device::                      Device selection and switching
tar.texi(,9048) * Remote Tape Server::
tar.texi(,9049) * Common Problems and Solutions::
tar.texi(,9050) * Blocking::                    Blocking
tar.texi(,9051) * Many::                        Many archives on one tape
tar.texi(,9052) * Using Multiple Tapes::        Using Multiple Tapes
tar.texi(,9053) * label::                       Including a Label in the Archive
tar.texi(,9054) * verify::
tar.texi(,9055) * Write Protection::
tar.texi(,9056) @end menu
tar.texi(,9057) 
tar.texi(,9058) @node Device
tar.texi(,9059) @section Device Selection and Switching
tar.texi(UNREVISED,9060) @quotation
tar.texi(UNREVISED,9060) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,9060) @end quotation
tar.texi(,9061) 
tar.texi(,9062) @table @option
tar.texi(,9063) @item -f [@var{hostname}:]@var{file}
tar.texi(,9064) @itemx --file=[@var{hostname}:]@var{file}
tar.texi(,9065) Use archive file or device @var{file} on @var{hostname}.
tar.texi(,9066) @end table
tar.texi(,9067) 
tar.texi(,9068) This option is used to specify the file name of the archive @command{tar}
tar.texi(,9069) works on.
tar.texi(,9070) 
tar.texi(,9071) If the file name is @samp{-}, @command{tar} reads the archive from standard
tar.texi(,9072) input (when listing or extracting), or writes it to standard output
tar.texi(,9073) (when creating).  If the @samp{-} file name is given when updating an
tar.texi(,9074) archive, @command{tar} will read the original archive from its standard
tar.texi(,9075) input, and will write the entire new archive to its standard output.
tar.texi(,9076) 
tar.texi(,9077) If the file name contains a @samp{:}, it is interpreted as
tar.texi(,9078) @samp{hostname:file name}.  If the @var{hostname} contains an @dfn{at}
tar.texi(,9079) sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}.  In
tar.texi(,9080) either case, @command{tar} will invoke the command @command{rsh} (or
tar.texi(,9081) @command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote
tar.texi(,9082) machine.  If you give an alternate login name, it will be given to the
tar.texi(,9083) @command{rsh}.
tar.texi(,9084) Naturally, the remote machine must have an executable
tar.texi(,9085) @command{/usr/libexec/rmt}.  This program is free software from the
tar.texi(,9086) University of California, and a copy of the source code can be found
tar.texi(,9087) with the sources for @command{tar}; it's compiled and installed by default.
tar.texi(,9088) The exact path to this utility is determined when configuring the package.
tar.texi(,9089) It is @file{@var{prefix}/libexec/rmt}, where @var{prefix} stands for
tar.texi(,9090) your installation prefix.  This location may also be overridden at
tar.texi(,9091) runtime by using @option{rmt-command=@var{command}} option (@xref{Option Summary,
tar.texi(,9092) ---rmt-command}, for detailed description of this option.  @xref{Remote
tar.texi(,9093) Tape Server}, for the description of @command{rmt} command).
tar.texi(,9094) 
tar.texi(,9095) If this option is not given, but the environment variable @env{TAPE}
tar.texi(,9096) is set, its value is used; otherwise, old versions of @command{tar}
tar.texi(,9097) used a default archive name (which was picked when @command{tar} was
tar.texi(,9098) compiled).  The default is normally set up to be the @dfn{first} tape
tar.texi(,9099) drive or other transportable I/O medium on the system.
tar.texi(,9100) 
tar.texi(GNUTAR,9101) Starting with version 1.11.5, tar.texi(GNUTAR,9101) @acronym{GNU} @command{tar} uses
tar.texi(,9102) standard input and standard output as the default device, and I will
tar.texi(,9103) not try anymore supporting automatic device detection at installation
tar.texi(,9104) time.  This was failing really in too many cases, it was hopeless.
tar.texi(,9105) This is now completely left to the installer to override standard
tar.texi(,9106) input and standard output for default device, if this seems
tar.texi(,9107) preferable.  Further, I think @emph{most} actual usages of
tar.texi(,9108) @command{tar} are done with pipes or disks, not really tapes,
tar.texi(,9109) cartridges or diskettes.
tar.texi(,9110) 
tar.texi(,9111) Some users think that using standard input and output is running
tar.texi(,9112) after trouble.  This could lead to a nasty surprise on your screen if
tar.texi(,9113) you forget to specify an output file name---especially if you are going
tar.texi(,9114) through a network or terminal server capable of buffering large amounts
tar.texi(,9115) of output.  We had so many bug reports in that area of configuring
tar.texi(,9116) default tapes automatically, and so many contradicting requests, that
tar.texi(,9117) we finally consider the problem to be portably intractable.  We could
tar.texi(,9118) of course use something like @samp{/dev/tape} as a default, but this
tar.texi(,9119) is @emph{also} running after various kind of trouble, going from hung
tar.texi(,9120) processes to accidental destruction of real tapes.  After having seen
tar.texi(,9121) all this mess, using standard input and output as a default really
tar.texi(,9122) sounds like the only clean choice left, and a very useful one too.
tar.texi(,9123) 
tar.texi(GNUTAR,9124) @acronym{GNU} @command{tar} reads and writes archive in records, I
tar.texi(,9125) suspect this is the main reason why block devices are preferred over
tar.texi(,9126) character devices.  Most probably, block devices are more efficient
tar.texi(,9127) too.  The installer could also check for @samp{DEFTAPE} in
tar.texi(,9128) @file{<sys/mtio.h>}.
tar.texi(,9129) 
tar.texi(,9130) @table @option
tar.texi(xopindex,9131) @opindex force-local@r{, short description}
tar.texi(,9132) @item --force-local
tar.texi(,9133) Archive file is local even if it contains a colon.
tar.texi(,9134) 
tar.texi(,9135) @opindex rsh-command
tar.texi(,9136) @item --rsh-command=@var{command}
tar.texi(,9137) Use remote @var{command} instead of @command{rsh}.  This option exists
tar.texi(,9138) so that people who use something other than the standard @command{rsh}
tar.texi(,9139) (e.g., a Kerberized @command{rsh}) can access a remote device.
tar.texi(,9140) 
tar.texi(,9141) When this command is not used, the shell command found when
tar.texi(,9142) the @command{tar} program was installed is used instead.  This is
tar.texi(,9143) the first found of @file{/usr/ucb/rsh}, @file{/usr/bin/remsh},
tar.texi(,9144) @file{/usr/bin/rsh}, @file{/usr/bsd/rsh} or @file{/usr/bin/nsh}.
tar.texi(,9145) The installer may have overridden this by defining the environment
tar.texi(,9146) variable @env{RSH} @emph{at installation time}.
tar.texi(,9147) 
tar.texi(,9148) @item -[0-7][lmh]
tar.texi(,9149) Specify drive and density.
tar.texi(,9150) 
tar.texi(xopindex,9151) @opindex multi-volume@r{, short description}
tar.texi(,9152) @item -M
tar.texi(,9153) @itemx --multi-volume
tar.texi(,9154) Create/list/extract multi-volume archive.
tar.texi(,9155) 
tar.texi(,9156) This option causes @command{tar} to write a @dfn{multi-volume} archive---one
tar.texi(,9157) that may be larger than will fit on the medium used to hold it.
tar.texi(,9158) @xref{Multi-Volume Archives}.
tar.texi(,9159) 
tar.texi(xopindex,9160) @opindex tape-length@r{, short description}
tar.texi(,9161) @item -L @var{num}
tar.texi(,9162) @itemx --tape-length=@var{num}
tar.texi(,9163) Change tape after writing @var{num} x 1024 bytes.
tar.texi(,9164) 
tar.texi(,9165) This option might be useful when your tape drivers do not properly
tar.texi(,9166) detect end of physical tapes.  By being slightly conservative on the
tar.texi(,9167) maximum tape length, you might avoid the problem entirely.
tar.texi(,9168) 
tar.texi(xopindex,9169) @opindex info-script@r{, short description}
tar.texi(xopindex,9170) @opindex new-volume-script@r{, short description}
tar.texi(,9171) @item -F @var{file}
tar.texi(,9172) @itemx --info-script=@var{file}
tar.texi(,9173) @itemx --new-volume-script=@var{file}
tar.texi(,9174) Execute @file{file} at end of each tape.  This implies
tar.texi(,9175) @option{--multi-volume} (@option{-M}).  @xref{info-script}, for a detailed
tar.texi(,9176) description of this option.
tar.texi(,9177) @end table
tar.texi(,9178) 
tar.texi(,9179) @node Remote Tape Server
tar.texi(,9180) @section The Remote Tape Server
tar.texi(,9181) 
tar.texi(,9182) @cindex remote tape drive
tar.texi(,9183) @pindex rmt
tar.texi(,9184) In order to access the tape drive on a remote machine, @command{tar}
tar.texi(,9185) uses the remote tape server written at the University of California at
tar.texi(,9186) Berkeley.  The remote tape server must be installed as
tar.texi(,9187) @file{@var{prefix}/libexec/rmt} on any machine whose tape drive you
tar.texi(,9188) want to use.  @command{tar} calls @command{rmt} by running an
tar.texi(,9189) @command{rsh} or @command{remsh} to the remote machine, optionally
tar.texi(,9190) using a different login name if one is supplied.
tar.texi(,9191) 
tar.texi(,9192) A copy of the source for the remote tape server is provided.  It is
tar.texi(,9193) Copyright @copyright{} 1983 by the Regents of the University of
tar.texi(,9194) California, but can be freely distributed.  It is compiled and
tar.texi(,9195) installed by default.
tar.texi(,9196) 
tar.texi(,9197) @cindex absolute file names
tar.texi(,9198) Unless you use the @option{--absolute-names} (@option{-P}) option,
tar.texi(GNUTAR,9199) @acronym{GNU} @command{tar} will not allow you to create an archive that contains
tar.texi(,9200) absolute file names (a file name beginning with @samp{/}.) If you try,
tar.texi(,9201) @command{tar} will automatically remove the leading @samp{/} from the
tar.texi(,9202) file names it stores in the archive.  It will also type a warning
tar.texi(,9203) message telling you what it is doing.
tar.texi(,9204) 
tar.texi(,9205) When reading an archive that was created with a different
tar.texi(GNUTAR,9206) @command{tar} program, tar.texi(GNUTAR,9206) @acronym{GNU} @command{tar} automatically
tar.texi(,9207) extracts entries in the archive which have absolute file names as if
tar.texi(,9208) the file names were not absolute.  This is an important feature.  A
tar.texi(,9209) visitor here once gave a @command{tar} tape to an operator to restore;
tar.texi(GNUTAR,9210) the operator used Sun @command{tar} instead of tar.texi(GNUTAR,9210) @acronym{GNU} @command{tar},
tar.texi(,9211) and the result was that it replaced large portions of
tar.texi(,9212) our @file{/bin} and friends with versions from the tape; needless to
tar.texi(,9213) say, we were unhappy about having to recover the file system from
tar.texi(,9214) backup tapes.
tar.texi(,9215) 
tar.texi(,9216) For example, if the archive contained a file @file{/usr/bin/computoy},
tar.texi(GNUTAR,9217) @acronym{GNU} @command{tar} would extract the file to @file{usr/bin/computoy},
tar.texi(,9218) relative to the current directory.  If you want to extract the files in
tar.texi(,9219) an archive to the same absolute names that they had when the archive
tar.texi(,9220) was created, you should do a @samp{cd /} before extracting the files
tar.texi(,9221) from the archive, or you should either use the @option{--absolute-names}
tar.texi(,9222) option, or use the command @samp{tar -C / @dots{}}.
tar.texi(,9223) 
tar.texi(,9224) @cindex Ultrix 3.1 and write failure
tar.texi(,9225) Some versions of Unix (Ultrix 3.1 is known to have this problem),
tar.texi(,9226) can claim that a short write near the end of a tape succeeded,
tar.texi(,9227) when it actually failed.  This will result in the -M option not
tar.texi(,9228) working correctly.  The best workaround at the moment is to use a
tar.texi(,9229) significantly larger blocking factor than the default 20.
tar.texi(,9230) 
tar.texi(,9231) In order to update an archive, @command{tar} must be able to backspace the
tar.texi(,9232) archive in order to reread or rewrite a record that was just read (or
tar.texi(,9233) written).  This is currently possible only on two kinds of files: normal
tar.texi(,9234) disk files (or any other file that can be backspaced with @samp{lseek}),
tar.texi(,9235) and industry-standard 9-track magnetic tape (or any other kind of tape
tar.texi(,9236) that can be backspaced with the @code{MTIOCTOP} @code{ioctl}.
tar.texi(,9237) 
tar.texi(,9238) This means that the @option{--append}, @option{--concatenate}, and
tar.texi(,9239) @option{--delete} commands will not work on any other kind of file.
tar.texi(,9240) Some media simply cannot be backspaced, which means these commands and
tar.texi(,9241) options will never be able to work on them. These non-backspacing
tar.texi(,9242) media include pipes and cartridge tape drives.
tar.texi(,9243) 
tar.texi(,9244) Some other media can be backspaced, and @command{tar} will work on them
tar.texi(,9245) once @command{tar} is modified to do so.
tar.texi(,9246) 
tar.texi(,9247) Archives created with the @option{--multi-volume}, @option{--label}, and
tar.texi(,9248) @option{--incremental} (@option{-G}) options may not be readable by other version
tar.texi(,9249) of @command{tar}.  In particular, restoring a file that was split over
tar.texi(,9250) a volume boundary will require some careful work with @command{dd}, if
tar.texi(,9251) it can be done at all.  Other versions of @command{tar} may also create
tar.texi(,9252) an empty file whose name is that of the volume header.  Some versions
tar.texi(,9253) of @command{tar} may create normal files instead of directories archived
tar.texi(,9254) with the @option{--incremental} (@option{-G}) option.
tar.texi(,9255) 
tar.texi(,9256) @node Common Problems and Solutions
tar.texi(,9257) @section Some Common Problems and their Solutions
tar.texi(,9258) 
tar.texi(,9260) 
tar.texi(,9261) @format
tar.texi(,9262) errors from system:
tar.texi(,9263) permission denied
tar.texi(,9264) no such file or directory
tar.texi(,9265) not owner
tar.texi(,9266) 
tar.texi(,9267) errors from @command{tar}:
tar.texi(,9268) directory checksum error
tar.texi(,9269) header format error
tar.texi(,9270) 
tar.texi(,9271) errors from media/system:
tar.texi(,9272) i/o error
tar.texi(,9273) device busy
tar.texi(,9274) @end format
tar.texi(,9275) 
tar.texi(,9277) 
tar.texi(,9278) @node Blocking
tar.texi(,9279) @section Blocking
tar.texi(UNREVISED,9280) @quotation
tar.texi(UNREVISED,9280) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,9280) @end quotation
tar.texi(,9281) 
tar.texi(,9282) @dfn{Block} and @dfn{record} terminology is rather confused, and it
tar.texi(,9283) is also confusing to the expert reader.  On the other hand, readers
tar.texi(,9284) who are new to the field have a fresh mind, and they may safely skip
tar.texi(,9285) the next two paragraphs, as the remainder of this manual uses those
tar.texi(,9286) two terms in a quite consistent way.
tar.texi(,9287) 
tar.texi(,9288) John Gilmore, the writer of the public domain @command{tar} from which
tar.texi(GNUTAR,9289) @acronym{GNU} @command{tar} was originally derived, wrote (June 1995):
tar.texi(,9290) 
tar.texi(,9291) @quotation
tar.texi(,9292) The nomenclature of tape drives comes from IBM, where I believe
tar.texi(,9293) they were invented for the IBM 650 or so.  On IBM mainframes, what
tar.texi(,9294) is recorded on tape are tape blocks.  The logical organization of
tar.texi(,9295) data is into records.  There are various ways of putting records into
tar.texi(,9296) blocks, including @code{F} (fixed sized records), @code{V} (variable
tar.texi(,9297) sized records), @code{FB} (fixed blocked: fixed size records, @var{n}
tar.texi(,9298) to a block), @code{VB} (variable size records, @var{n} to a block),
tar.texi(,9299) @code{VSB} (variable spanned blocked: variable sized records that can
tar.texi(,9300) occupy more than one block), etc.  The @code{JCL} @samp{DD RECFORM=}
tar.texi(,9301) parameter specified this to the operating system.
tar.texi(,9302) 
tar.texi(,9303) The Unix man page on @command{tar} was totally confused about this.
tar.texi(,9304) When I wrote @code{PD TAR}, I used the historically correct terminology
tar.texi(,9305) (@command{tar} writes data records, which are grouped into blocks).
tar.texi(,9306) It appears that the bogus terminology made it into @acronym{POSIX} (no surprise
tar.texi(,9307) here), and now Fran@,{c}ois has migrated that terminology back
tar.texi(,9308) into the source code too.
tar.texi(,9309) @end quotation
tar.texi(,9310) 
tar.texi(,9311) The term @dfn{physical block} means the basic transfer chunk from or
tar.texi(,9312) to a device, after which reading or writing may stop without anything
tar.texi(,9313) being lost.  In this manual, the term @dfn{block} usually refers to
tar.texi(,9314) a disk physical block, @emph{assuming} that each disk block is 512
tar.texi(,9315) bytes in length.  It is true that some disk devices have different
tar.texi(,9316) physical blocks, but @command{tar} ignore these differences in its own
tar.texi(,9317) format, which is meant to be portable, so a @command{tar} block is always
tar.texi(,9318) 512 bytes in length, and @dfn{block} always mean a @command{tar} block.
tar.texi(,9319) The term @dfn{logical block} often represents the basic chunk of
tar.texi(,9320) allocation of many disk blocks as a single entity, which the operating
tar.texi(,9321) system treats somewhat atomically; this concept is only barely used
tar.texi(GNUTAR,9322) in tar.texi(GNUTAR,9322) @acronym{GNU} @command{tar}.
tar.texi(,9323) 
tar.texi(,9324) The term @dfn{physical record} is another way to speak of a physical
tar.texi(,9325) block, those two terms are somewhat interchangeable.  In this manual,
tar.texi(,9326) the term @dfn{record} usually refers to a tape physical block,
tar.texi(,9327) @emph{assuming} that the @command{tar} archive is kept on magnetic tape.
tar.texi(,9328) It is true that archives may be put on disk or used with pipes,
tar.texi(,9329) but nevertheless, @command{tar} tries to read and write the archive one
tar.texi(,9330) @dfn{record} at a time, whatever the medium in use.  One record is made
tar.texi(,9331) up of an integral number of blocks, and this operation of putting many
tar.texi(,9332) disk blocks into a single tape block is called @dfn{reblocking}, or
tar.texi(,9333) more simply, @dfn{blocking}.  The term @dfn{logical record} refers to
tar.texi(,9334) the logical organization of many characters into something meaningful
tar.texi(,9335) to the application.  The term @dfn{unit record} describes a small set
tar.texi(,9336) of characters which are transmitted whole to or by the application,
tar.texi(,9337) and often refers to a line of text.  Those two last terms are unrelated
tar.texi(GNUTAR,9338) to what we call a @dfn{record} in tar.texi(GNUTAR,9338) @acronym{GNU} @command{tar}.
tar.texi(,9339) 
tar.texi(,9340) When writing to tapes, @command{tar} writes the contents of the archive
tar.texi(,9341) in chunks known as @dfn{records}.  To change the default blocking
tar.texi(,9342) factor, use the @option{--blocking-factor=@var{512-size}} (@option{-b
tar.texi(,9343) @var{512-size}}) option.  Each record will then be composed of
tar.texi(,9344) @var{512-size} blocks.  (Each @command{tar} block is 512 bytes.
tar.texi(,9345) @xref{Standard}.)  Each file written to the archive uses at least one
tar.texi(,9346) full record.  As a result, using a larger record size can result in
tar.texi(,9347) more wasted space for small files.  On the other hand, a larger record
tar.texi(,9348) size can often be read and written much more efficiently.
tar.texi(,9349) 
tar.texi(,9350) Further complicating the problem is that some tape drives ignore the
tar.texi(,9351) blocking entirely.  For these, a larger record size can still improve
tar.texi(,9352) performance (because the software layers above the tape drive still
tar.texi(,9353) honor the blocking), but not as dramatically as on tape drives that
tar.texi(,9354) honor blocking.
tar.texi(,9355) 
tar.texi(,9356) When reading an archive, @command{tar} can usually figure out the
tar.texi(,9357) record size on itself.  When this is the case, and a non-standard
tar.texi(,9358) record size was used when the archive was created, @command{tar} will
tar.texi(,9359) print a message about a non-standard blocking factor, and then operate
tar.texi(,9360) normally.  On some tape devices, however, @command{tar} cannot figure
tar.texi(,9361) out the record size itself.  On most of those, you can specify a
tar.texi(,9362) blocking factor (with @option{--blocking-factor}) larger than the
tar.texi(,9363) actual blocking factor, and then use the @option{--read-full-records}
tar.texi(,9364) (@option{-B}) option.  (If you specify a blocking factor with
tar.texi(,9365) @option{--blocking-factor} and don't use the
tar.texi(,9366) @option{--read-full-records} option, then @command{tar} will not
tar.texi(,9367) attempt to figure out the recording size itself.)  On some devices,
tar.texi(,9368) you must always specify the record size exactly with
tar.texi(,9369) @option{--blocking-factor} when reading, because @command{tar} cannot
tar.texi(,9370) figure it out.  In any case, use @option{--list} (@option{-t}) before
tar.texi(,9371) doing any extractions to see whether @command{tar} is reading the archive
tar.texi(,9372) correctly.
tar.texi(,9373) 
tar.texi(,9374) @command{tar} blocks are all fixed size (512 bytes), and its scheme for
tar.texi(,9375) putting them into records is to put a whole number of them (one or
tar.texi(,9376) more) into each record.  @command{tar} records are all the same size;
tar.texi(,9377) at the end of the file there's a block containing all zeros, which
tar.texi(,9378) is how you tell that the remainder of the last record(s) are garbage.
tar.texi(,9379) 
tar.texi(,9380) In a standard @command{tar} file (no options), the block size is 512
tar.texi(,9381) and the record size is 10240, for a blocking factor of 20.  What the
tar.texi(,9382) @option{--blocking-factor} option does is sets the blocking factor,
tar.texi(,9383) changing the record size while leaving the block size at 512 bytes.
tar.texi(,9384) 20 was fine for ancient 800 or 1600 bpi reel-to-reel tape drives;
tar.texi(,9385) most tape drives these days prefer much bigger records in order to
tar.texi(,9386) stream and not waste tape.  When writing tapes for myself, some tend
tar.texi(,9387) to use a factor of the order of 2048, say, giving a record size of
tar.texi(,9388) around one megabyte.
tar.texi(,9389) 
tar.texi(,9390) If you use a blocking factor larger than 20, older @command{tar}
tar.texi(,9391) programs might not be able to read the archive, so we recommend this
tar.texi(GNUTAR,9392) as a limit to use in practice.  tar.texi(GNUTAR,9392) @acronym{GNU} @command{tar}, however,
tar.texi(,9393) will support arbitrarily large record sizes, limited only by the
tar.texi(,9394) amount of virtual memory or the physical characteristics of the tape
tar.texi(,9395) device.
tar.texi(,9396) 
tar.texi(,9397) @menu
tar.texi(,9398) * Format Variations::           Format Variations
tar.texi(,9399) * Blocking Factor::             The Blocking Factor of an Archive
tar.texi(,9400) @end menu
tar.texi(,9401) 
tar.texi(,9402) @node Format Variations
tar.texi(,9403) @subsection Format Variations
tar.texi(,9404) @cindex Format Parameters
tar.texi(,9405) @cindex Format Options
tar.texi(,9406) @cindex Options, archive format specifying
tar.texi(,9407) @cindex Options, format specifying
tar.texi(UNREVISED,9408) @quotation
tar.texi(UNREVISED,9408) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,9408) @end quotation
tar.texi(,9409) 
tar.texi(,9410) Format parameters specify how an archive is written on the archive
tar.texi(,9411) media.  The best choice of format parameters will vary depending on
tar.texi(,9412) the type and number of files being archived, and on the media used to
tar.texi(,9413) store the archive.
tar.texi(,9414) 
tar.texi(,9415) To specify format parameters when accessing or creating an archive,
tar.texi(,9416) you can use the options described in the following sections.
tar.texi(,9417) If you do not specify any format parameters, @command{tar} uses
tar.texi(,9418) default parameters.  You cannot modify a compressed archive.
tar.texi(,9419) If you create an archive with the @option{--blocking-factor} option
tar.texi(,9420) specified (@pxref{Blocking Factor}), you must specify that
tar.texi(,9421) blocking-factor when operating on the archive.  @xref{Formats}, for other
tar.texi(,9422) examples of format parameter considerations.
tar.texi(,9423) 
tar.texi(,9424) @node Blocking Factor
tar.texi(,9425) @subsection The Blocking Factor of an Archive
tar.texi(,9426) @cindex Blocking Factor
tar.texi(,9427) @cindex Record Size
tar.texi(,9428) @cindex Number of blocks per record
tar.texi(,9429) @cindex Number of bytes per record
tar.texi(,9430) @cindex Bytes per record
tar.texi(,9431) @cindex Blocks per record
tar.texi(UNREVISED,9432) @quotation
tar.texi(UNREVISED,9432) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,9432) @end quotation
tar.texi(,9433) 
tar.texi(,9434) @opindex blocking-factor
tar.texi(,9435) The data in an archive is grouped into blocks, which are 512 bytes.
tar.texi(,9436) Blocks are read and written in whole number multiples called
tar.texi(,9437) @dfn{records}.  The number of blocks in a record (i.e.  the size of a
tar.texi(,9438) record in units of 512 bytes) is called the @dfn{blocking factor}.
tar.texi(,9439) The @option{--blocking-factor=@var{512-size}} (@option{-b
tar.texi(,9440) @var{512-size}}) option specifies the blocking factor of an archive.
tar.texi(,9441) The default blocking factor is typically 20 (i.e., 10240 bytes), but
tar.texi(,9442) can be specified at installation.  To find out the blocking factor of
tar.texi(,9443) an existing archive, use @samp{tar --list --file=@var{archive-name}}.
tar.texi(,9444) This may not work on some devices.
tar.texi(,9445) 
tar.texi(,9446) Records are separated by gaps, which waste space on the archive media.
tar.texi(,9447) If you are archiving on magnetic tape, using a larger blocking factor
tar.texi(,9448) (and therefore larger records) provides faster throughput and allows you
tar.texi(,9449) to fit more data on a tape (because there are fewer gaps).  If you are
tar.texi(,9450) archiving on cartridge, a very large blocking factor (say 126 or more)
tar.texi(,9451) greatly increases performance.  A smaller blocking factor, on the other
tar.texi(,9452) hand, may be useful when archiving small files, to avoid archiving lots
tar.texi(,9453) of nulls as @command{tar} fills out the archive to the end of the record.
tar.texi(,9454) In general, the ideal record size depends on the size of the
tar.texi(,9455) inter-record gaps on the tape you are using, and the average size of the
tar.texi(,9456) files you are archiving.  @xref{create}, for information on
tar.texi(,9457) writing archives.
tar.texi(,9458) 
tar.texi(FIXME,9459) @allow-recursion
tar.texi(FIXME,9459) @quote-arg
tar.texi(FIXME,9459) 
tar.texi(,9460) 
tar.texi(,9461) Archives with blocking factors larger than 20 cannot be read
tar.texi(,9462) by very old versions of @command{tar}, or by some newer versions
tar.texi(,9463) of @command{tar} running on old machines with small address spaces.
tar.texi(GNUTAR,9464) With tar.texi(GNUTAR,9464) @acronym{GNU} @command{tar}, the blocking factor of an archive is limited
tar.texi(,9465) only by the maximum record size of the device containing the archive,
tar.texi(,9466) or by the amount of available virtual memory.
tar.texi(,9467) 
tar.texi(,9468) Also, on some systems, not using adequate blocking factors, as sometimes
tar.texi(,9469) imposed by the device drivers, may yield unexpected diagnostics.  For
tar.texi(,9470) example, this has been reported:
tar.texi(,9471) 
tar.texi(,9472) @smallexample
tar.texi(,9473) Cannot write to /dev/dlt: Invalid argument
tar.texi(,9474) @end smallexample
tar.texi(,9475) 
tar.texi(,9476) @noindent
tar.texi(,9477) In such cases, it sometimes happen that the @command{tar} bundled by
tar.texi(GNUTAR,9478) the system is aware of block size idiosyncrasies, while tar.texi(GNUTAR,9478) @acronym{GNU} @command{tar}
tar.texi(,9479) requires an explicit specification for the block size,
tar.texi(,9480) which it cannot guess.  This yields some people to consider
tar.texi(GNUTAR,9481) @acronym{GNU} @command{tar} is misbehaving, because by comparison,
tar.texi(,9482) @cite{the bundle @command{tar} works OK}.  Adding @w{@kbd{-b 256}},
tar.texi(,9483) for example, might resolve the problem.
tar.texi(,9484) 
tar.texi(,9485) If you use a non-default blocking factor when you create an archive, you
tar.texi(,9486) must specify the same blocking factor when you modify that archive.  Some
tar.texi(,9487) archive devices will also require you to specify the blocking factor when
tar.texi(,9488) reading that archive, however this is not typically the case.  Usually, you
tar.texi(,9489) can use @option{--list} (@option{-t}) without specifying a blocking factor---@command{tar}
tar.texi(,9490) reports a non-default record size and then lists the archive members as
tar.texi(,9491) it would normally.  To extract files from an archive with a non-standard
tar.texi(,9492) blocking factor (particularly if you're not sure what the blocking factor
tar.texi(,9493) is), you can usually use the @option{--read-full-records} (@option{-B}) option while
tar.texi(,9494) specifying a blocking factor larger then the blocking factor of the archive
tar.texi(,9495) (i.e.  @samp{tar --extract --read-full-records --blocking-factor=300}.
tar.texi(,9496) @xref{list}, for more information on the @option{--list} (@option{-t})
tar.texi(,9497) operation.  @xref{Reading}, for a more detailed explanation of that option.
tar.texi(,9498) 
tar.texi(,9499) @table @option
tar.texi(,9500) @item --blocking-factor=@var{number}
tar.texi(,9501) @itemx -b @var{number}
tar.texi(,9502) Specifies the blocking factor of an archive.  Can be used with any
tar.texi(,9503) operation, but is usually not necessary with @option{--list} (@option{-t}).
tar.texi(,9504) @end table
tar.texi(,9505) 
tar.texi(,9506) Device blocking
tar.texi(,9507) 
tar.texi(,9508) @table @option
tar.texi(,9509) @item -b @var{blocks}
tar.texi(,9510) @itemx --blocking-factor=@var{blocks}
tar.texi(,9511) Set record size to @math{@var{blocks} * 512} bytes.
tar.texi(,9512) 
tar.texi(,9513) This option is used to specify a @dfn{blocking factor} for the archive.
tar.texi(,9514) When reading or writing the archive, @command{tar}, will do reads and writes
tar.texi(,9515) of the archive in records of @math{@var{block}*512} bytes.  This is true
tar.texi(,9516) even when the archive is compressed.  Some devices requires that all
tar.texi(,9517) write operations be a multiple of a certain size, and so, @command{tar}
tar.texi(,9518) pads the archive out to the next record boundary.
tar.texi(,9519) 
tar.texi(,9520) The default blocking factor is set when @command{tar} is compiled, and is
tar.texi(,9521) typically 20.  Blocking factors larger than 20 cannot be read by very
tar.texi(,9522) old versions of @command{tar}, or by some newer versions of @command{tar}
tar.texi(,9523) running on old machines with small address spaces.
tar.texi(,9524) 
tar.texi(,9525) With a magnetic tape, larger records give faster throughput and fit
tar.texi(,9526) more data on a tape (because there are fewer inter-record gaps).
tar.texi(,9527) If the archive is in a disk file or a pipe, you may want to specify
tar.texi(,9528) a smaller blocking factor, since a large one will result in a large
tar.texi(,9529) number of null bytes at the end of the archive.
tar.texi(,9530) 
tar.texi(,9531) When writing cartridge or other streaming tapes, a much larger
tar.texi(,9532) blocking factor (say 126 or more) will greatly increase performance.
tar.texi(,9533) However, you must specify the same blocking factor when reading or
tar.texi(,9534) updating the archive.
tar.texi(,9535) 
tar.texi(,9536) Apparently, Exabyte drives have a physical block size of 8K bytes.
tar.texi(,9537) If we choose our blocksize as a multiple of 8k bytes, then the problem
tar.texi(,9538) seems to disappear.  Id est, we are using block size of 112 right
tar.texi(,9539) now, and we haven't had the problem since we switched@dots{}
tar.texi(,9540) 
tar.texi(GNUTAR,9541) With tar.texi(GNUTAR,9541) @acronym{GNU} @command{tar} the blocking factor is limited only
tar.texi(,9542) by the maximum record size of the device containing the archive, or by
tar.texi(,9543) the amount of available virtual memory.
tar.texi(,9544) 
tar.texi(,9545) However, deblocking or reblocking is virtually avoided in a special
tar.texi(,9546) case which often occurs in practice, but which requires all the
tar.texi(,9547) following conditions to be simultaneously true:
tar.texi(,9548) @itemize @bullet
tar.texi(,9549) @item
tar.texi(,9550) the archive is subject to a compression option,
tar.texi(,9551) @item
tar.texi(,9552) the archive is not handled through standard input or output, nor
tar.texi(,9553) redirected nor piped,
tar.texi(,9554) @item
tar.texi(,9555) the archive is directly handled to a local disk, instead of any special
tar.texi(,9556) device,
tar.texi(,9557) @item
tar.texi(,9558) @option{--blocking-factor} is not explicitly specified on the @command{tar}
tar.texi(,9559) invocation.
tar.texi(,9560) @end itemize
tar.texi(,9561) 
tar.texi(,9562) If the output goes directly to a local disk, and not through
tar.texi(,9563) stdout, then the last write is not extended to a full record size.
tar.texi(,9564) Otherwise, reblocking occurs.  Here are a few other remarks on this
tar.texi(,9565) topic:
tar.texi(,9566) 
tar.texi(,9567) @itemize @bullet
tar.texi(,9568) 
tar.texi(,9569) @item
tar.texi(,9570) @command{gzip} will complain about trailing garbage if asked to
tar.texi(,9571) uncompress a compressed archive on tape, there is an option to turn
tar.texi(,9572) the message off, but it breaks the regularity of simply having to use
tar.texi(,9573) @samp{@var{prog} -d} for decompression.  It would be nice if gzip was
tar.texi(,9574) silently ignoring any number of trailing zeros.  I'll ask Jean-loup
tar.texi(,9575) Gailly, by sending a copy of this message to him.
tar.texi(,9576) 
tar.texi(,9577) @item
tar.texi(,9578) @command{compress} does not show this problem, but as Jean-loup pointed
tar.texi(,9579) out to Michael, @samp{compress -d} silently adds garbage after
tar.texi(,9580) the result of decompression, which tar ignores because it already
tar.texi(,9581) recognized its end-of-file indicator.  So this bug may be safely
tar.texi(,9582) ignored.
tar.texi(,9583) 
tar.texi(,9584) @item
tar.texi(,9585) @samp{gzip -d -q} will be silent about the trailing zeros indeed,
tar.texi(,9586) but will still return an exit status of 2 which tar reports in turn.
tar.texi(,9587) @command{tar} might ignore the exit status returned, but I hate doing
tar.texi(,9588) that, as it weakens the protection @command{tar} offers users against
tar.texi(,9589) other possible problems at decompression time.  If @command{gzip} was
tar.texi(,9590) silently skipping trailing zeros @emph{and} also avoiding setting the
tar.texi(,9591) exit status in this innocuous case, that would solve this situation.
tar.texi(,9592) 
tar.texi(,9593) @item
tar.texi(,9594) @command{tar} should become more solid at not stopping to read a pipe at
tar.texi(,9595) the first null block encountered.  This inelegantly breaks the pipe.
tar.texi(,9596) @command{tar} should rather drain the pipe out before exiting itself.
tar.texi(,9597) @end itemize
tar.texi(,9598) 
tar.texi(xopindex,9599) @opindex ignore-zeros@r{, short description}
tar.texi(,9600) @item -i
tar.texi(,9601) @itemx --ignore-zeros
tar.texi(,9602) Ignore blocks of zeros in archive (means EOF).
tar.texi(,9603) 
tar.texi(,9604) The @option{--ignore-zeros} (@option{-i}) option causes @command{tar} to ignore blocks
tar.texi(,9605) of zeros in the archive.  Normally a block of zeros indicates the
tar.texi(,9606) end of the archive, but when reading a damaged archive, or one which
tar.texi(,9607) was created by concatenating several archives together, this option
tar.texi(,9608) allows @command{tar} to read the entire archive.  This option is not on
tar.texi(,9609) by default because many versions of @command{tar} write garbage after
tar.texi(,9610) the zeroed blocks.
tar.texi(,9611) 
tar.texi(,9612) Note that this option causes @command{tar} to read to the end of the
tar.texi(,9613) archive file, which may sometimes avoid problems when multiple files
tar.texi(,9614) are stored on a single physical tape.
tar.texi(,9615) 
tar.texi(xopindex,9616) @opindex read-full-records@r{, short description}
tar.texi(,9617) @item -B
tar.texi(,9618) @itemx --read-full-records
tar.texi(,9619) Reblock as we read (for reading 4.2BSD pipes).
tar.texi(,9620) 
tar.texi(,9621) If @option{--read-full-records} is used, @command{tar}
tar.texi(,9622) will not panic if an attempt to read a record from the archive does
tar.texi(,9623) not return a full record. Instead, @command{tar} will keep reading
tar.texi(,9624) until it has obtained a full
tar.texi(,9625) record.
tar.texi(,9626) 
tar.texi(,9627) This option is turned on by default when @command{tar} is reading
tar.texi(,9628) an archive from standard input, or from a remote machine.  This is
tar.texi(,9629) because on BSD Unix systems, a read of a pipe will return however
tar.texi(,9630) much happens to be in the pipe, even if it is less than @command{tar}
tar.texi(,9631) requested.  If this option was not used, @command{tar} would fail as
tar.texi(,9632) soon as it read an incomplete record from the pipe.
tar.texi(,9633) 
tar.texi(,9634) This option is also useful with the commands for updating an archive.
tar.texi(,9635) 
tar.texi(,9636) @end table
tar.texi(,9637) 
tar.texi(,9638) Tape blocking
tar.texi(,9639) 
tar.texi(FIXME,9640) @allow-recursion
tar.texi(FIXME,9640) @quote-arg
tar.texi(FIXME,9640) 
tar.texi(,9641) 
tar.texi(,9642) @cindex blocking factor
tar.texi(,9643) @cindex tape blocking
tar.texi(,9644) 
tar.texi(,9645) When handling various tapes or cartridges, you have to take care of
tar.texi(,9646) selecting a proper blocking, that is, the number of disk blocks you
tar.texi(,9647) put together as a single tape block on the tape, without intervening
tar.texi(,9648) tape gaps.  A @dfn{tape gap} is a small landing area on the tape
tar.texi(,9649) with no information on it, used for decelerating the tape to a
tar.texi(,9650) full stop, and for later regaining the reading or writing speed.
tar.texi(,9651) When the tape driver starts reading a record, the record has to
tar.texi(,9652) be read whole without stopping, as a tape gap is needed to stop the
tar.texi(,9653) tape motion without loosing information.
tar.texi(,9654) 
tar.texi(,9655) @cindex Exabyte blocking
tar.texi(,9656) @cindex DAT blocking
tar.texi(,9657) Using higher blocking (putting more disk blocks per tape block) will use
tar.texi(,9658) the tape more efficiently as there will be less tape gaps.  But reading
tar.texi(,9659) such tapes may be more difficult for the system, as more memory will be
tar.texi(,9660) required to receive at once the whole record.  Further, if there is a
tar.texi(,9661) reading error on a huge record, this is less likely that the system will
tar.texi(,9662) succeed in recovering the information.  So, blocking should not be too
tar.texi(,9663) low, nor it should be too high.  @command{tar} uses by default a blocking of
tar.texi(,9664) 20 for historical reasons, and it does not really matter when reading or
tar.texi(,9665) writing to disk.  Current tape technology would easily accommodate higher
tar.texi(,9666) blockings.  Sun recommends a blocking of 126 for Exabytes and 96 for DATs.
tar.texi(,9667) We were told that for some DLT drives, the blocking should be a multiple
tar.texi(,9668) of 4Kb, preferably 64Kb (@w{@kbd{-b 128}}) or 256 for decent performance.
tar.texi(,9669) Other manufacturers may use different recommendations for the same tapes.
tar.texi(,9670) This might also depends of the buffering techniques used inside modern
tar.texi(,9671) tape controllers.  Some imposes a minimum blocking, or a maximum blocking.
tar.texi(,9672) Others request blocking to be some exponent of two.
tar.texi(,9673) 
tar.texi(,9674) So, there is no fixed rule for blocking.  But blocking at read time
tar.texi(,9675) should ideally be the same as blocking used at write time.  At one place
tar.texi(,9676) I know, with a wide variety of equipment, they found it best to use a
tar.texi(,9677) blocking of 32 to guarantee that their tapes are fully interchangeable.
tar.texi(,9678) 
tar.texi(,9679) I was also told that, for recycled tapes, prior erasure (by the same
tar.texi(,9680) drive unit that will be used to create the archives) sometimes lowers
tar.texi(,9681) the error rates observed at rewriting time.
tar.texi(,9682) 
tar.texi(,9683) I might also use @option{--number-blocks} instead of
tar.texi(,9684) @option{--block-number}, so @option{--block} will then expand to
tar.texi(,9685) @option{--blocking-factor} unambiguously.
tar.texi(,9686) 
tar.texi(,9687) @node Many
tar.texi(,9688) @section Many Archives on One Tape
tar.texi(,9689) 
tar.texi(FIXME,9690) @allow-recursion
tar.texi(FIXME,9690) @quote-arg
tar.texi(FIXME,9690) 
tar.texi(,9691) 
tar.texi(,9692) @findex ntape @r{device}
tar.texi(,9693) Most tape devices have two entries in the @file{/dev} directory, or
tar.texi(,9694) entries that come in pairs, which differ only in the minor number for
tar.texi(,9695) this device.  Let's take for example @file{/dev/tape}, which often
tar.texi(,9696) points to the only or usual tape device of a given system.  There might
tar.texi(,9697) be a corresponding @file{/dev/nrtape} or @file{/dev/ntape}.  The simpler
tar.texi(,9698) name is the @emph{rewinding} version of the device, while the name
tar.texi(,9699) having @samp{nr} in it is the @emph{no rewinding} version of the same
tar.texi(,9700) device.
tar.texi(,9701) 
tar.texi(,9702) A rewinding tape device will bring back the tape to its beginning point
tar.texi(,9703) automatically when this device is opened or closed.  Since @command{tar}
tar.texi(,9704) opens the archive file before using it and closes it afterwards, this
tar.texi(,9705) means that a simple:
tar.texi(,9706) 
tar.texi(,9707) @smallexample
tar.texi(,9708) $ @kbd{tar cf /dev/tape @var{directory}}
tar.texi(,9709) @end smallexample
tar.texi(,9710) 
tar.texi(,9711) @noindent
tar.texi(,9712) will reposition the tape to its beginning both prior and after saving
tar.texi(,9713) @var{directory} contents to it, thus erasing prior tape contents and
tar.texi(,9714) making it so that any subsequent write operation will destroy what has
tar.texi(,9715) just been saved.
tar.texi(,9716) 
tar.texi(,9717) @cindex tape positioning
tar.texi(,9718) So, a rewinding device is normally meant to hold one and only one file.
tar.texi(,9719) If you want to put more than one @command{tar} archive on a given tape, you
tar.texi(,9720) will need to avoid using the rewinding version of the tape device.  You
tar.texi(,9721) will also have to pay special attention to tape positioning.  Errors in
tar.texi(,9722) positioning may overwrite the valuable data already on your tape.  Many
tar.texi(,9723) people, burnt by past experiences, will only use rewinding devices and
tar.texi(,9724) limit themselves to one file per tape, precisely to avoid the risk of
tar.texi(,9725) such errors.  Be fully aware that writing at the wrong position on a
tar.texi(,9726) tape loses all information past this point and most probably until the
tar.texi(,9727) end of the tape, and this destroyed information @emph{cannot} be
tar.texi(,9728) recovered.
tar.texi(,9729) 
tar.texi(,9730) To save @var{directory-1} as a first archive at the beginning of a
tar.texi(,9731) tape, and leave that tape ready for a second archive, you should use:
tar.texi(,9732) 
tar.texi(,9733) @smallexample
tar.texi(,9734) $ @kbd{mt -f /dev/nrtape rewind}
tar.texi(,9735) $ @kbd{tar cf /dev/nrtape @var{directory-1}}
tar.texi(,9736) @end smallexample
tar.texi(,9737) 
tar.texi(,9738) @cindex tape marks
tar.texi(,9739) @dfn{Tape marks} are special magnetic patterns written on the tape
tar.texi(,9740) media, which are later recognizable by the reading hardware.  These
tar.texi(,9741) marks are used after each file, when there are many on a single tape.
tar.texi(,9742) An empty file (that is to say, two tape marks in a row) signal the
tar.texi(,9743) logical end of the tape, after which no file exist.  Usually,
tar.texi(,9744) non-rewinding tape device drivers will react to the close request issued
tar.texi(,9745) by @command{tar} by first writing two tape marks after your archive, and by
tar.texi(,9746) backspacing over one of these.  So, if you remove the tape at that time
tar.texi(,9747) from the tape drive, it is properly terminated.  But if you write
tar.texi(,9748) another file at the current position, the second tape mark will be
tar.texi(,9749) erased by the new information, leaving only one tape mark between files.
tar.texi(,9750) 
tar.texi(,9751) So, you may now save @var{directory-2} as a second archive after the
tar.texi(,9752) first on the same tape by issuing the command:
tar.texi(,9753) 
tar.texi(,9754) @smallexample
tar.texi(,9755) $ @kbd{tar cf /dev/nrtape @var{directory-2}}
tar.texi(,9756) @end smallexample
tar.texi(,9757) 
tar.texi(,9758) @noindent
tar.texi(,9759) and so on for all the archives you want to put on the same tape.
tar.texi(,9760) 
tar.texi(,9761) Another usual case is that you do not write all the archives the same
tar.texi(,9762) day, and you need to remove and store the tape between two archive
tar.texi(,9763) sessions.  In general, you must remember how many files are already
tar.texi(,9764) saved on your tape.  Suppose your tape already has 16 files on it, and
tar.texi(,9765) that you are ready to write the 17th.  You have to take care of skipping
tar.texi(,9766) the first 16 tape marks before saving @var{directory-17}, say, by using
tar.texi(,9767) these commands:
tar.texi(,9768) 
tar.texi(,9769) @smallexample
tar.texi(,9770) $ @kbd{mt -f /dev/nrtape rewind}
tar.texi(,9771) $ @kbd{mt -f /dev/nrtape fsf 16}
tar.texi(,9772) $ @kbd{tar cf /dev/nrtape @var{directory-17}}
tar.texi(,9773) @end smallexample
tar.texi(,9774) 
tar.texi(,9775) In all the previous examples, we put aside blocking considerations, but
tar.texi(,9776) you should do the proper things for that as well.  @xref{Blocking}.
tar.texi(,9777) 
tar.texi(,9778) @menu
tar.texi(,9779) * Tape Positioning::            Tape Positions and Tape Marks
tar.texi(,9780) * mt::                          The @command{mt} Utility
tar.texi(,9781) @end menu
tar.texi(,9782) 
tar.texi(,9783) @node Tape Positioning
tar.texi(,9784) @subsection Tape Positions and Tape Marks
tar.texi(UNREVISED,9785) @quotation
tar.texi(UNREVISED,9785) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,9785) @end quotation
tar.texi(,9786) 
tar.texi(,9787) Just as archives can store more than one file from the file system,
tar.texi(,9788) tapes can store more than one archive file.  To keep track of where
tar.texi(,9789) archive files (or any other type of file stored on tape) begin and
tar.texi(,9790) end, tape archive devices write magnetic @dfn{tape marks} on the
tar.texi(,9791) archive media.  Tape drives write one tape mark between files,
tar.texi(,9792) two at the end of all the file entries.
tar.texi(,9793) 
tar.texi(,9794) If you think of data as a series of records "rrrr"'s, and tape marks as
tar.texi(,9795) "*"'s, a tape might look like the following:
tar.texi(,9796) 
tar.texi(,9797) @smallexample
tar.texi(,9798) rrrr*rrrrrr*rrrrr*rr*rrrrr**-------------------------
tar.texi(,9799) @end smallexample
tar.texi(,9800) 
tar.texi(,9801) Tape devices read and write tapes using a read/write @dfn{tape
tar.texi(,9802) head}---a physical part of the device which can only access one
tar.texi(,9803) point on the tape at a time.  When you use @command{tar} to read or
tar.texi(,9804) write archive data from a tape device, the device will begin reading
tar.texi(,9805) or writing from wherever on the tape the tape head happens to be,
tar.texi(,9806) regardless of which archive or what part of the archive the tape
tar.texi(,9807) head is on.  Before writing an archive, you should make sure that no
tar.texi(,9808) data on the tape will be overwritten (unless it is no longer needed).
tar.texi(,9809) Before reading an archive, you should make sure the tape head is at
tar.texi(,9810) the beginning of the archive you want to read.  You can do it manually
tar.texi(,9811) via @code{mt} utility (@pxref{mt}).  The @code{restore} script does
tar.texi(,9812) that automatically (@pxref{Scripted Restoration}).
tar.texi(,9813) 
tar.texi(,9814) If you want to add new archive file entries to a tape, you should
tar.texi(,9815) advance the tape to the end of the existing file entries, backspace
tar.texi(,9816) over the last tape mark, and write the new archive file.  If you were
tar.texi(,9817) to add two archives to the example above, the tape might look like the
tar.texi(,9818) following:
tar.texi(,9819) 
tar.texi(,9820) @smallexample
tar.texi(,9821) rrrr*rrrrrr*rrrrr*rr*rrrrr*rrr*rrrr**----------------
tar.texi(,9822) @end smallexample
tar.texi(,9823) 
tar.texi(,9824) @node mt
tar.texi(,9825) @subsection The @command{mt} Utility
tar.texi(UNREVISED,9826) @quotation
tar.texi(UNREVISED,9826) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,9826) @end quotation
tar.texi(,9827) 
tar.texi(FIXME,9829) @allow-recursion
tar.texi(FIXME,9829) @quote-arg
tar.texi(FIXME,9829) 
tar.texi(,9830) @xref{Blocking Factor}.
tar.texi(,9831) 
tar.texi(,9832) You can use the @command{mt} utility to advance or rewind a tape past a
tar.texi(,9833) specified number of archive files on the tape.  This will allow you
tar.texi(,9834) to move to the beginning of an archive before extracting or reading
tar.texi(,9835) it, or to the end of all the archives before writing a new one.
tar.texi(FIXME,9837) @allow-recursion
tar.texi(FIXME,9837) @quote-arg
tar.texi(FIXME,9837) 
tar.texi(,9838) 
tar.texi(,9839) The syntax of the @command{mt} command is:
tar.texi(,9840) 
tar.texi(,9841) @smallexample
tar.texi(,9842) @kbd{mt [-f @var{tapename}] @var{operation} [@var{number}]}
tar.texi(,9843) @end smallexample
tar.texi(,9844) 
tar.texi(,9845) where @var{tapename} is the name of the tape device, @var{number} is
tar.texi(,9846) the number of times an operation is performed (with a default of one),
tar.texi(,9847) and @var{operation} is one of the following:
tar.texi(,9848) 
tar.texi(FIXME,9849) @allow-recursion
tar.texi(FIXME,9849) @quote-arg
tar.texi(FIXME,9849) 
tar.texi(,9850) 
tar.texi(,9851) @table @option
tar.texi(,9852) @item eof
tar.texi(,9853) @itemx weof
tar.texi(,9854) Writes @var{number} tape marks at the current position on the tape.
tar.texi(,9855) 
tar.texi(,9856) @item fsf
tar.texi(,9857) Moves tape position forward @var{number} files.
tar.texi(,9858) 
tar.texi(,9859) @item bsf
tar.texi(,9860) Moves tape position back @var{number} files.
tar.texi(,9861) 
tar.texi(,9862) @item rewind
tar.texi(,9863) Rewinds the tape.  (Ignores @var{number}).
tar.texi(,9864) 
tar.texi(,9865) @item offline
tar.texi(,9866) @itemx rewoff1
tar.texi(,9867) Rewinds the tape and takes the tape device off-line.  (Ignores @var{number}).
tar.texi(,9868) 
tar.texi(,9869) @item status
tar.texi(,9870) Prints status information about the tape unit.
tar.texi(,9871) 
tar.texi(,9872) @end table
tar.texi(,9873) 
tar.texi(FIXME,9874) @allow-recursion
tar.texi(FIXME,9874) @quote-arg
tar.texi(FIXME,9874) 
tar.texi(,9875) 
tar.texi(,9876) If you don't specify a @var{tapename}, @command{mt} uses the environment
tar.texi(,9877) variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
tar.texi(,9878) the default device specified in your @file{sys/mtio.h} file
tar.texi(,9879) (@code{DEFTAPE} variable).  If this is not defined, the program will
tar.texi(,9880) display a descriptive error message and exit with code 1.
tar.texi(,9881) 
tar.texi(,9882) @command{mt} returns a 0 exit status when the operation(s) were
tar.texi(,9883) successful, 1 if the command was unrecognized, and 2 if an operation
tar.texi(,9884) failed.
tar.texi(,9885) 
tar.texi(,9886) @node Using Multiple Tapes
tar.texi(,9887) @section Using Multiple Tapes
tar.texi(,9888) 
tar.texi(,9889) Often you might want to write a large archive, one larger than will fit
tar.texi(,9890) on the actual tape you are using.  In such a case, you can run multiple
tar.texi(,9891) @command{tar} commands, but this can be inconvenient, particularly if you
tar.texi(,9892) are using options like @option{--exclude=@var{pattern}} or dumping entire file systems.
tar.texi(,9893) Therefore, @command{tar} provides a special mode for creating
tar.texi(,9894) multi-volume archives.
tar.texi(,9895) 
tar.texi(,9896) @dfn{Multi-volume} archive is a single @command{tar} archive, stored
tar.texi(,9897) on several media volumes of fixed size.  Although in this section we will
tar.texi(,9898) often call @samp{volume} a @dfn{tape}, there is absolutely no
tar.texi(,9899) requirement for multi-volume archives to be stored on tapes.  Instead,
tar.texi(,9900) they can use whatever media type the user finds convenient, they can
tar.texi(,9901) even be located on files.  
tar.texi(,9902) 
tar.texi(GNUTAR,9903) When creating a multi-volume arvhive, tar.texi(GNUTAR,9903) @acronym{GNU} @command{tar} continues to fill
tar.texi(,9904) current volume until it runs out of space, then it switches to
tar.texi(,9905) next volume (usually the operator is queried to replace the tape on
tar.texi(,9906) this point), and continues working on the new volume.  This operation
tar.texi(GNUTAR,9907) continues untill all requested files are dumped.  If tar.texi(GNUTAR,9907) @acronym{GNU} @command{tar} detects
tar.texi(,9908) end of media while dumping a file, such a file is archived in split
tar.texi(,9909) form.  Some very big files can even be split across several volumes. 
tar.texi(,9910) 
tar.texi(GNUTAR,9911) Each volume is itself a valid tar.texi(GNUTAR,9911) @acronym{GNU} @command{tar} archive, so it can be read
tar.texi(,9912) without any special options.  Consequently any file member residing
tar.texi(,9913) entirely on one volume can be extracted or otherwise operated upon
tar.texi(,9914) without needing the other volume.  Sure enough, to extract a split
tar.texi(,9915) member you would need all volumes its parts reside on.
tar.texi(,9916) 
tar.texi(,9917) Multi-volume archives suffer from several limitations.  In particular,
tar.texi(,9918) they cannot be compressed.
tar.texi(,9919) 
tar.texi(GNUTAR,9920) @acronym{GNU} @command{tar} is able to create multi-volume archives of two formats
tar.texi(,9921) (@pxref{Formats}): @samp{GNU} and @samp{POSIX}.
tar.texi(,9922) 
tar.texi(,9923) @menu
tar.texi(,9924) * Multi-Volume Archives::       Archives Longer than One Tape or Disk
tar.texi(,9925) * Tape Files::                  Tape Files
tar.texi(,9926) * Tarcat::                      Concatenate Volumes into a Single Archive
tar.texi(,9927) 
tar.texi(,9928) @end menu
tar.texi(,9929) 
tar.texi(,9930) @node Multi-Volume Archives
tar.texi(,9931) @subsection Archives Longer than One Tape or Disk
tar.texi(,9932) @cindex Multi-volume archives
tar.texi(,9933) 
tar.texi(,9934) @opindex multi-volume
tar.texi(,9935) To create an archive that is larger than will fit on a single unit of
tar.texi(,9936) the media, use the @option{--multi-volume} (@option{-M}) option in conjunction with
tar.texi(,9937) the @option{--create} option (@pxref{create}).  A @dfn{multi-volume}
tar.texi(,9938) archive can be manipulated like any other archive (provided the
tar.texi(,9939) @option{--multi-volume} option is specified), but is stored on more
tar.texi(,9940) than one tape or disk.
tar.texi(,9941) 
tar.texi(,9942) When you specify @option{--multi-volume}, @command{tar} does not report an
tar.texi(,9943) error when it comes to the end of an archive volume (when reading), or
tar.texi(,9944) the end of the media (when writing).  Instead, it prompts you to load
tar.texi(,9945) a new storage volume.  If the archive is on a magnetic tape, you
tar.texi(,9946) should change tapes when you see the prompt; if the archive is on a
tar.texi(,9947) floppy disk, you should change disks; etc.
tar.texi(,9948) 
tar.texi(,9949) @table @option
tar.texi(,9950) @item --multi-volume
tar.texi(,9951) @itemx -M
tar.texi(,9952) Creates a multi-volume archive, when used in conjunction with
tar.texi(,9953) @option{--create} (@option{-c}).  To perform any other operation on a multi-volume
tar.texi(,9954) archive, specify @option{--multi-volume} in conjunction with that
tar.texi(,9955) operation.
tar.texi(,9956) For example:
tar.texi(,9957) 
tar.texi(,9958) @smallexample
tar.texi(,9959) $ @kbd{tar --create --multi-volume --file=/dev/tape @var{files}}
tar.texi(,9960) @end smallexample
tar.texi(,9961) @end table
tar.texi(,9962) 
tar.texi(,9963) The method @command{tar} uses to detect end of tape is not perfect, and
tar.texi(,9964) fails on some operating systems or on some devices.  If @command{tar}
tar.texi(,9965) cannot detect the end of the tape itself, you can use
tar.texi(,9966) @option{--tape-length} option to inform it about the capacity of the
tar.texi(,9967) tape:
tar.texi(,9968) 
tar.texi(,9969) @anchor{tape-length}
tar.texi(,9970) @table @option
tar.texi(,9971) @opindex tape-length
tar.texi(,9972) @item --tape-length=@var{size}
tar.texi(,9973) @itemx -L @var{size}
tar.texi(,9974) Set maximum length of a volume.  The @var{size} argument should then
tar.texi(,9975) be the usable size of the tape in units of 1024 bytes.  This option
tar.texi(,9976) selects @option{--multi-volume} automatically.  For example:
tar.texi(,9977) 
tar.texi(,9978) @smallexample
tar.texi(,9979) $ @kbd{tar --create --tape-length=41943040 --file=/dev/tape @var{files}}
tar.texi(,9980) @end smallexample
tar.texi(,9981) @end table
tar.texi(,9982) 
tar.texi(,9983) @anchor{change volume prompt}
tar.texi(GNUTAR,9984) When tar.texi(GNUTAR,9984) @acronym{GNU} @command{tar} comes to the end of a storage media, it asks you to
tar.texi(,9985) change the volume.  The built-in prompt for POSIX locale
tar.texi(GNUTAR,9986) is@footnote{If you run @acronym{GNU} @command{tar} under a different locale, the
tar.texi(,9987) translation to the locale's language will be used.}: 
tar.texi(,9988) 
tar.texi(,9989) @smallexample
tar.texi(,9990) Prepare volume #@var{n} for `@var{archive}' and hit return:
tar.texi(,9991) @end smallexample
tar.texi(,9992) 
tar.texi(,9993) @noindent
tar.texi(,9994) where @var{n} is the ordinal number of the volume to be created and
tar.texi(,9995) @var{archive} is archive file or device name.
tar.texi(,9996) 
tar.texi(,9997) When prompting for a new tape, @command{tar} accepts any of the following
tar.texi(,9998) responses:
tar.texi(,9999) 
tar.texi(,10000) @table @kbd
tar.texi(,10001) @item ?
tar.texi(,10002) Request @command{tar} to explain possible responses
tar.texi(,10003) @item q
tar.texi(,10004) Request @command{tar} to exit immediately.
tar.texi(,10005) @item n @var{file-name}
tar.texi(,10006) Request @command{tar} to write the next volume on the file @var{file-name}.
tar.texi(,10007) @item !
tar.texi(,10008) Request @command{tar} to run a subshell.  This option can be disabled
tar.texi(,10009) by giving @option{--restrict} command line option to
tar.texi(,10010) @command{tar}@footnote{@xref{--restrict}, for more information about
tar.texi(,10011) this option}.
tar.texi(,10012) @item y
tar.texi(,10013) Request @command{tar} to begin writing the next volume.
tar.texi(,10014) @end table
tar.texi(,10015) 
tar.texi(,10016) (You should only type @samp{y} after you have changed the tape;
tar.texi(,10017) otherwise @command{tar} will write over the volume it just finished.)
tar.texi(,10018) 
tar.texi(,10019) @cindex Volume number file
tar.texi(,10020) @cindex volno file
tar.texi(,10021) @anchor{volno-file}
tar.texi(,10022) @opindex volno-file
tar.texi(,10023) The volume number used by @command{tar} in its tape-changing prompt
tar.texi(,10024) can be changed; if you give the
tar.texi(,10025) @option{--volno-file=@var{file-of-number}} option, then
tar.texi(,10026) @var{file-of-number} should be an unexisting file to be created, or
tar.texi(,10027) else, a file already containing a decimal number.  That number will be
tar.texi(,10028) used as the volume number of the first volume written.  When
tar.texi(,10029) @command{tar} is finished, it will rewrite the file with the
tar.texi(,10030) now-current volume number. (This does not change the volume number
tar.texi(,10031) written on a tape label, as per @ref{label}, it @emph{only} affects
tar.texi(,10032) the number used in the prompt.)
tar.texi(,10033) 
tar.texi(,10034) @cindex End-of-archive info script
tar.texi(,10035) @cindex Info script
tar.texi(,10036) @anchor{info-script}
tar.texi(,10037) @opindex info-script
tar.texi(,10038) @opindex new-volume-script
tar.texi(,10039) If you want more elaborate behavior than this, you can write a special
tar.texi(,10040) @dfn{new volume script}, that will be responsible for changing the
tar.texi(,10041) volume, and instruct @command{tar} to use it instead of its normal
tar.texi(,10042) prompting procedure: 
tar.texi(,10043) 
tar.texi(,10044) @table @option
tar.texi(,10045) @item --info-script=@var{script-name}
tar.texi(,10046) @itemx --new-volume-script=@var{script-name}
tar.texi(,10047) @itemx -F @var{script-name}
tar.texi(,10048) Specify the full name of the volume script to use.  The script can be
tar.texi(,10049) used to eject cassettes, or to broadcast messages such as
tar.texi(,10050) @samp{Someone please come change my tape} when performing unattended
tar.texi(,10051) backups.
tar.texi(,10052) @end table
tar.texi(,10053) 
tar.texi(,10054) The @var{script-name} is executed without any command line
tar.texi(,10055) arguments.  It inherits @command{tar}'s shell environment.
tar.texi(,10056) Additional data is passed to it via the following
tar.texi(,10057) environment variables:
tar.texi(,10058) 
tar.texi(,10059) @table @env
tar.texi(,10060) @vrindex TAR_VERSION, info script environment variable
tar.texi(,10061) @item TAR_VERSION
tar.texi(GNUTAR,10062) @acronym{GNU} @command{tar} version number.
tar.texi(,10063) 
tar.texi(,10064) @vrindex TAR_ARCHIVE, info script environment variable
tar.texi(,10065) @item TAR_ARCHIVE
tar.texi(,10066) The name of the archive @command{tar} is processing.
tar.texi(,10067) 
tar.texi(,10068) @vrindex TAR_VOLUME, info script environment variable
tar.texi(,10069) @item TAR_VOLUME
tar.texi(,10070) Ordinal number of the volume @command{tar} is about to start.
tar.texi(,10071) 
tar.texi(,10072) @vrindex TAR_SUBCOMMAND, info script environment variable
tar.texi(,10073) @item TAR_SUBCOMMAND
tar.texi(,10074) Short option describing the operation @command{tar} is executing
tar.texi(,10075) @xref{Operations}, for a complete list of subcommand options.
tar.texi(,10076) 
tar.texi(,10077) @vrindex TAR_FORMAT, info script environment variable
tar.texi(,10078) @item TAR_FORMAT
tar.texi(,10079) Format of the archive being processed. @xref{Formats}, for a complete
tar.texi(,10080) list of archive format names.
tar.texi(,10081) @end table
tar.texi(,10082) 
tar.texi(,10083) The volume script can instruct @command{tar} to use new archive name,
tar.texi(,10084) by writing in to file descriptor 3 (see below for an example).
tar.texi(,10085) 
tar.texi(,10086) If the info script fails, @command{tar} exits; otherwise, it begins
tar.texi(,10087) writing the next volume.
tar.texi(,10088) 
tar.texi(,10089) If you want @command{tar} to cycle through a series of files or tape
tar.texi(,10090) drives, there are three approaches to choose from.  First of all, you
tar.texi(,10091) can give @command{tar} multiple @option{--file} options.  In this case
tar.texi(,10092) the specified files will be used, in sequence, as the successive
tar.texi(,10093) volumes of the archive.  Only when the first one in the sequence needs
tar.texi(,10094) to be used again will @command{tar} prompt for a tape change (or run
tar.texi(,10095) the info script).  For example, suppose someone has two tape drives on
tar.texi(,10096) a system named @file{/dev/tape0} and @file{/dev/tape1}.  For having
tar.texi(GNUTAR,10097) @acronym{GNU} @command{tar} to switch to the second drive when it needs to write the
tar.texi(,10098) second tape, and then back to the first tape, etc., just do either of:
tar.texi(,10099) 
tar.texi(,10100) @smallexample
tar.texi(,10101) $ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}}
tar.texi(,10102) $ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}}
tar.texi(,10103) @end smallexample
tar.texi(,10104) 
tar.texi(,10105) The second method is to use the @samp{n} response to the tape-change
tar.texi(,10106) prompt.  
tar.texi(,10107) 
tar.texi(,10108) Finally, the most flexible approach is to use a volume script, that
tar.texi(,10109) writes new archive name to the file descriptor #3.  For example, the
tar.texi(,10110) following volume script will create a series of archive files, named
tar.texi(,10111) @file{@var{archive}-@var{vol}}, where @var{archive} is the name of the
tar.texi(,10112) archive being created (as given by @option{--file} option) and
tar.texi(,10113) @var{vol} is the ordinal number of the archive being created:
tar.texi(,10114) 
tar.texi(,10115) @smallexample
tar.texi(,10116) @group
tar.texi(,10117) #! /bin/sh
tar.texi(,10118) echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE.
tar.texi(,10119) 
tar.texi(,10120) name=`expr $TAR_ARCHIVE : '\(.*\)-.*'`
tar.texi(,10121) case $TAR_SUBCOMMAND in
tar.texi(,10122) -c)       ;;
tar.texi(,10123) -d|-x|-t) test -r $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME || exit 1
tar.texi(,10124) 	  ;;
tar.texi(,10125) *)        exit 1
tar.texi(,10126) esac
tar.texi(,10127) 
tar.texi(,10128) echo $@{name:-$TAR_ARCHIVE@}-$TAR_VOLUME >&3
tar.texi(,10129) @end group
tar.texi(,10130) @end smallexample
tar.texi(,10131) 
tar.texi(,10132) The same script cant be used while listing, comparing or extracting
tar.texi(,10133) from the created archive.  For example:
tar.texi(,10134) 
tar.texi(,10135) @smallexample
tar.texi(,10136) @group
tar.texi(,10137) # @r{Create a multi-volume archive:}
tar.texi(,10138) $ @kbd{tar -c -L1024 -f archive.tar -F new-volume .}
tar.texi(,10139) # @r{Extract from the created archive:}
tar.texi(,10140) $ @kbd{tar -x -f archive.tar -F new-volume .}
tar.texi(,10141) @end group
tar.texi(,10142) @end smallexample
tar.texi(,10143) 
tar.texi(,10144) @noindent
tar.texi(,10145) Notice, that the first command had to use @option{-L} option, since
tar.texi(GNUTAR,10146) otherwise tar.texi(GNUTAR,10146) @acronym{GNU} @command{tar} will end up writing everything to file
tar.texi(,10147) @file{archive.tar}.
tar.texi(,10148) 
tar.texi(,10149) You can read each individual volume of a multi-volume archive as if it
tar.texi(,10150) were an archive by itself.  For example, to list the contents of one
tar.texi(,10151) volume, use @option{--list}, without @option{--multi-volume} specified.
tar.texi(,10152) To extract an archive member from one volume (assuming it is described
tar.texi(,10153) that volume), use @option{--extract}, again without
tar.texi(,10154) @option{--multi-volume}.
tar.texi(,10155) 
tar.texi(,10156) If an archive member is split across volumes (i.e.  its entry begins on
tar.texi(,10157) one volume of the media and ends on another), you need to specify
tar.texi(,10158) @option{--multi-volume} to extract it successfully.  In this case, you
tar.texi(,10159) should load the volume where the archive member starts, and use
tar.texi(,10160) @samp{tar --extract --multi-volume}---@command{tar} will prompt for later
tar.texi(,10161) volumes as it needs them.  @xref{extracting archives}, for more
tar.texi(,10162) information about extracting archives.
tar.texi(,10163) 
tar.texi(,10164) Multi-volume archives can be modified like any other archive.  To add
tar.texi(,10165) files to a multi-volume archive, you need to only mount the last
tar.texi(,10166) volume of the archive media (and new volumes, if needed).  For all
tar.texi(,10167) other operations, you need to use the entire archive.
tar.texi(,10168) 
tar.texi(,10169) If a multi-volume archive was labeled using
tar.texi(,10170) @option{--label=@var{archive-label}} (@pxref{label}) when it was
tar.texi(,10171) created, @command{tar} will not automatically label volumes which are
tar.texi(,10172) added later.  To label subsequent volumes, specify
tar.texi(,10173) @option{--label=@var{archive-label}} again in conjunction with the
tar.texi(,10174) @option{--append}, @option{--update} or @option{--concatenate} operation.
tar.texi(,10175) 
tar.texi(,10176) Notice that multi-volume support is a GNU extension and the archives
tar.texi(GNUTAR,10177) created in this mode should be read only using tar.texi(GNUTAR,10177) @acronym{GNU} @command{tar}.  If you
tar.texi(,10178) absolutely have to process such archives using a third-party @command{tar}
tar.texi(,10179) implementation, read @ref{Split Recovery}.
tar.texi(,10180) 
tar.texi(,10181) @node Tape Files
tar.texi(,10182) @subsection Tape Files
tar.texi(UNREVISED,10183) @quotation
tar.texi(UNREVISED,10183) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,10183) @end quotation
tar.texi(,10184) 
tar.texi(,10185) To give the archive a name which will be recorded in it, use the
tar.texi(,10186) @option{--label=@var{volume-label}} (@option{-V @var{volume-label}})
tar.texi(,10187) option.  This will write a special block identifying
tar.texi(,10188) @var{volume-label} as the name of the archive to the front of the
tar.texi(,10189) archive which will be displayed when the archive is listed with
tar.texi(,10190) @option{--list}.  If you are creating a multi-volume archive with
tar.texi(,10191) @option{--multi-volume} (@pxref{Using Multiple Tapes}), then the
tar.texi(,10192) volume label will have @samp{Volume @var{nnn}} appended to the name
tar.texi(,10193) you give, where @var{nnn} is the number of the volume of the archive.
tar.texi(,10194) (If you use the @option{--label=@var{volume-label}}) option when
tar.texi(,10195) reading an archive, it checks to make sure the label on the tape
tar.texi(,10196) matches the one you give. @xref{label}.
tar.texi(,10197) 
tar.texi(,10198) When @command{tar} writes an archive to tape, it creates a single
tar.texi(,10199) tape file.  If multiple archives are written to the same tape, one
tar.texi(,10200) after the other, they each get written as separate tape files.  When
tar.texi(,10201) extracting, it is necessary to position the tape at the right place
tar.texi(,10202) before running @command{tar}.  To do this, use the @command{mt} command.
tar.texi(,10203) For more information on the @command{mt} command and on the organization
tar.texi(,10204) of tapes into a sequence of tape files, see @ref{mt}.
tar.texi(,10205) 
tar.texi(,10206) People seem to often do:
tar.texi(,10207) 
tar.texi(,10208) @smallexample
tar.texi(,10209) @kbd{--label="@var{some-prefix} `date +@var{some-format}`"}
tar.texi(,10210) @end smallexample
tar.texi(,10211) 
tar.texi(,10212) or such, for pushing a common date in all volumes or an archive set.
tar.texi(,10213) 
tar.texi(,10214) @node Tarcat
tar.texi(,10215) @subsection Concatenate Volumes into a Single Archive
tar.texi(,10216) 
tar.texi(,10217) @pindex tarcat
tar.texi(GNUTAR,10218)   Sometimes it is necessary to convert existing tar.texi(GNUTAR,10218) @acronym{GNU} @command{tar} multi-volume
tar.texi(,10219) archive to a single @command{tar} archive.  Simply concatenating all
tar.texi(,10220) volumes into one will not work, since each volume carries an additional
tar.texi(GNUTAR,10221) information at the beginning.  tar.texi(GNUTAR,10221) @acronym{GNU} @command{tar} is shipped with the shell
tar.texi(,10222) script @command{tarcat} designed for this purpose.
tar.texi(,10223) 
tar.texi(,10224)   The script takes a list of files comprising a multi-volume archive
tar.texi(,10225) and creates the resulting archive at the standard output.  For example:
tar.texi(,10226) 
tar.texi(,10227) @smallexample
tar.texi(,10228) @kbd{tarcat vol.1 vol.2 vol.3 | tar tf -}
tar.texi(,10229) @end smallexample
tar.texi(,10230) 
tar.texi(,10231)   The script implements a simple heuristics to determine the format of
tar.texi(,10232) the first volume file and to decide how to process the rest of the
tar.texi(,10233) files.  However, it makes no attempt to verify whether the files are
tar.texi(,10234) given in order or even if they are valid @command{tar} archives.
tar.texi(,10235) It uses @command{dd} and does not filter its standard error, so you
tar.texi(,10236) will usually see lots of spurious messages.
tar.texi(,10237) 
tar.texi(FIXME,10238) @allow-recursion
tar.texi(FIXME,10238) @quote-arg
tar.texi(FIXME,10238) 
tar.texi(,10239) 
tar.texi(,10240) @node label
tar.texi(,10241) @section Including a Label in the Archive
tar.texi(,10242) @cindex Labeling an archive
tar.texi(,10243) @cindex Labels on the archive media
tar.texi(,10244) @cindex Labeling multi-volume archives
tar.texi(UNREVISED,10245) @quotation
tar.texi(UNREVISED,10245) @emph{(This message will disappear, once this node revised.)}
tar.texi(UNREVISED,10245) @end quotation
tar.texi(,10246) 
tar.texi(,10247) @opindex label
tar.texi(,10248)   To avoid problems caused by misplaced paper labels on the archive
tar.texi(,10249) media, you can include a @dfn{label} entry---an archive member which
tar.texi(,10250) contains the name of the archive---in the archive itself.  Use the
tar.texi(,10251) @option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
tar.texi(,10252) option in conjunction with the @option{--create} operation to include
tar.texi(,10253) a label entry in the archive as it is being created.
tar.texi(,10254) 
tar.texi(,10255) @table @option
tar.texi(,10256) @item --label=@var{archive-label}
tar.texi(,10257) @itemx -V @var{archive-label}
tar.texi(,10258) Includes an @dfn{archive-label} at the beginning of the archive when
tar.texi(,10259) the archive is being created, when used in conjunction with the
tar.texi(,10260) @option{--create} operation.  Checks to make sure the archive label
tar.texi(,10261) matches the one specified (when used in conjunction with any other
tar.texi(,10262) operation.
tar.texi(,10263) @end table
tar.texi(,10264) 
tar.texi(,10265)   If you create an archive using both
tar.texi(,10266) @option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
tar.texi(,10267) and @option{--multi-volume} (@option{-M}), each volume of the archive
tar.texi(,10268) will have an archive label of the form @samp{@var{archive-label}
tar.texi(,10269) Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
tar.texi(,10270) next, and so on. @xref{Using Multiple Tapes}, for information on
tar.texi(,10271) creating multiple volume archives.
tar.texi(,10272) 
tar.texi(,10273) @cindex Volume label, listing
tar.texi(,10274) @cindex Listing volume label
tar.texi(,10275)   The volume label will be displayed by @option{--list} along with
tar.texi(,10276) the file contents.  If verbose display is requested, it will also be
tar.texi(,10277) explicitely marked as in the example below:
tar.texi(,10278) 
tar.texi(,10279) @smallexample
tar.texi(,10280) @group
tar.texi(,10281) $ @kbd{tar --verbose --list --file=iamanarchive}
tar.texi(,10282) V--------- 0 0        0 1992-03-07 12:01 iamalabel--Volume Header--
tar.texi(,10283) -rw-r--r-- ringo user 40 1990-05-21 13:30 iamafilename
tar.texi(,10284) @end group
tar.texi(,10285) @end smallexample
tar.texi(,10286) 
tar.texi(,10287) @opindex test-label
tar.texi(,10288) @anchor{--test-label option}
tar.texi(,10289)   However, @option{--list} option will cause listing entire
tar.texi(,10290) contents of the archive, which may be undesirable (for example, if the
tar.texi(,10291) archive is stored on a tape).  You can request checking only the volume
tar.texi(,10292) by specifying @option{--test-label} option.  This option reads only the
tar.texi(,10293) first block of an archive, so it can be used with slow storage
tar.texi(,10294) devices.  For example:
tar.texi(,10295) 
tar.texi(,10296) @smallexample
tar.texi(,10297) @group
tar.texi(,10298) $ @kbd{tar --test-label --file=iamanarchive}
tar.texi(,10299) iamalabel
tar.texi(,10300) @end group
tar.texi(,10301) @end smallexample
tar.texi(,10302) 
tar.texi(,10303)   If @option{--test-label} is used with a single command line
tar.texi(,10304) argument, @command{tar} compares the volume label with the
tar.texi(,10305) argument.  It exits with code 0 if the two strings match, and with code
tar.texi(,10306) 2 otherwise.  In this case no output is displayed.  For example:
tar.texi(,10307) 
tar.texi(,10308) @smallexample
tar.texi(,10309) @group
tar.texi(,10310) $ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
tar.texi(,10311) @result{} 0
tar.texi(,10312) $ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
tar.texi(,10313) @result{} 1
tar.texi(,10314) @end group
tar.texi(,10315) @end smallexample
tar.texi(,10316) 
tar.texi(,10317)   If you request any operation, other than @option{--create}, along
tar.texi(,10318) with using @option{--label} option, @command{tar} will first check if
tar.texi(,10319) the archive label matches the one specified and will refuse to proceed
tar.texi(,10320) if it does not.  Use this as a safety precaution to avoid accidentally
tar.texi(,10321) overwriting existing archives.  For example, if you wish to add files
tar.texi(,10322) to @file{archive}, presumably labelled with string @samp{My volume},
tar.texi(,10323) you will get:
tar.texi(,10324) 
tar.texi(,10325) @smallexample
tar.texi(,10326) @group
tar.texi(,10327) $ @kbd{tar -rf archive --label 'My volume' .}
tar.texi(,10328) tar: Archive not labeled to match `My volume'
tar.texi(,10329) @end group
tar.texi(,10330) @end smallexample
tar.texi(,10331) 
tar.texi(,10332) @noindent
tar.texi(,10333) in case its label does not match.  This will work even if
tar.texi(,10334) @file{archive} is not labelled at all.
tar.texi(,10335) 
tar.texi(,10336)   Similarly, @command{tar} will refuse to list or extract the
tar.texi(,10337) archive if its label doesn't match the @var{archive-label}
tar.texi(,10338) specified.  In those cases, @var{archive-label} argument is interpreted
tar.texi(,10339) as a globbing-style pattern which must match the actual magnetic
tar.texi(,10340) volume label.  @xref{exclude}, for a precise description of how match
tar.texi(,10341) is attempted@footnote{Previous versions of @command{tar} used full
tar.texi(,10342) regular expression matching, or before that, only exact string
tar.texi(,10343) matching, instead of wildcard matchers.  We decided for the sake of
tar.texi(,10344) simplicity to use a uniform matching device through
tar.texi(,10345) @command{tar}.}.  If the switch @option{--multi-volume} (@option{-M}) is being used,
tar.texi(,10346) the volume label matcher will also suffix @var{archive-label} by
tar.texi(,10347) @w{@samp{ Volume [1-9]*}} if the initial match fails, before giving
tar.texi(,10348) up.  Since the volume numbering is automatically added in labels at
tar.texi(,10349) creation time, it sounded logical to equally help the user taking care
tar.texi(,10350) of it when the archive is being read.
tar.texi(,10351) 
tar.texi(,10352)   The @option{--label} was once called @option{--volume}, but is not
tar.texi(,10353) available under that name anymore.
tar.texi(,10354) 
tar.texi(,10355)   You can also use @option{--label} to get a common information on
tar.texi(,10356) all tapes of a series.  For having this information different in each
tar.texi(,10357) series created through a single script used on a regular basis, just
tar.texi(,10358) manage to get some date string as part of the label.  For example:
tar.texi(,10359) 
tar.texi(,10360) @smallexample
tar.texi(,10361) @group
tar.texi(,10362) $ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
tar.texi(,10363) $ @kbd{tar --create --file=/dev/tape --multi-volume \
tar.texi(,10364)      --volume="Daily backup for `date +%Y-%m-%d`"}
tar.texi(,10365) @end group
tar.texi(,10366) @end smallexample
tar.texi(,10367) 
tar.texi(,10368)   Also note that each label has its own date and time, which corresponds
tar.texi(GNUTAR,10369) to when tar.texi(GNUTAR,10369) @acronym{GNU} @command{tar} initially attempted to write it,
tar.texi(,10370) often soon after the operator launches @command{tar} or types the
tar.texi(,10371) carriage return telling that the next tape is ready.  Comparing date
tar.texi(,10372) labels does give an idea of tape throughput only if the delays for
tar.texi(,10373) rewinding tapes and the operator switching them were negligible, which
tar.texi(,10374) is usually not the case.
tar.texi(,10375) 
tar.texi(,10376) @node verify
tar.texi(,10377) @section Verifying Data as It is Stored
tar.texi(,10378) @cindex Verifying a write operation
tar.texi(,10379) @cindex Double-checking a write operation
tar.texi(,10380) 
tar.texi(,10381) @table @option
tar.texi(,10382) @item -W
tar.texi(,10383) @itemx --verify
tar.texi(,10384) @opindex verify, short description
tar.texi(,10385) Attempt to verify the archive after writing.
tar.texi(,10386) @end table
tar.texi(,10387) 
tar.texi(,10388) This option causes @command{tar} to verify the archive after writing it.
tar.texi(,10389) Each volume is checked after it is written, and any discrepancies
tar.texi(,10390) are recorded on the standard error output.
tar.texi(,10391) 
tar.texi(,10392) Verification requires that the archive be on a back-space-able medium.
tar.texi(,10393) This means pipes, some cartridge tape drives, and some other devices
tar.texi(,10394) cannot be verified.
tar.texi(,10395) 
tar.texi(,10396) You can insure the accuracy of an archive by comparing files in the
tar.texi(,10397) system with archive members.  @command{tar} can compare an archive to the
tar.texi(,10398) file system as the archive is being written, to verify a write
tar.texi(,10399) operation, or can compare a previously written archive, to insure that
tar.texi(,10400) it is up to date.
tar.texi(,10401) 
tar.texi(xopindex,10402) @opindex verify@r{, using with @option{--create}}
tar.texi(xopindex,10403) @opindex create@r{, using with @option{--verify}}
tar.texi(,10404) To check for discrepancies in an archive immediately after it is
tar.texi(,10405) written, use the @option{--verify} (@option{-W}) option in conjunction with
tar.texi(,10406) the @option{--create} operation.  When this option is
tar.texi(,10407) specified, @command{tar} checks archive members against their counterparts
tar.texi(,10408) in the file system, and reports discrepancies on the standard error.
tar.texi(,10409) 
tar.texi(,10410) To verify an archive, you must be able to read it from before the end
tar.texi(,10411) of the last written entry.  This option is useful for detecting data
tar.texi(,10412) errors on some tapes.  Archives written to pipes, some cartridge tape
tar.texi(,10413) drives, and some other devices cannot be verified.
tar.texi(,10414) 
tar.texi(,10415) One can explicitly compare an already made archive with the file
tar.texi(,10416) system by using the @option{--compare} (@option{--diff}, @option{-d})
tar.texi(,10417) option, instead of using the more automatic @option{--verify} option.
tar.texi(,10418) @xref{compare}.
tar.texi(,10419) 
tar.texi(,10420) Note that these two options have a slightly different intent.  The
tar.texi(,10421) @option{--compare} option checks how identical are the logical contents of some
tar.texi(,10422) archive with what is on your disks, while the @option{--verify} option is
tar.texi(,10423) really for checking if the physical contents agree and if the recording
tar.texi(,10424) media itself is of dependable quality.  So, for the @option{--verify}
tar.texi(,10425) operation, @command{tar} tries to defeat all in-memory cache pertaining to
tar.texi(,10426) the archive, while it lets the speed optimization undisturbed for the
tar.texi(,10427) @option{--compare} option.  If you nevertheless use @option{--compare} for
tar.texi(,10428) media verification, you may have to defeat the in-memory cache yourself,
tar.texi(,10429) maybe by opening and reclosing the door latch of your recording unit,
tar.texi(,10430) forcing some doubt in your operating system about the fact this is really
tar.texi(,10431) the same volume as the one just written or read.
tar.texi(,10432) 
tar.texi(,10433) The @option{--verify} option would not be necessary if drivers were indeed
tar.texi(,10434) able to detect dependably all write failures.  This sometimes require many
tar.texi(,10435) magnetic heads, some able to read after the writes occurred.  One would
tar.texi(,10436) not say that drivers unable to detect all cases are necessarily flawed,
tar.texi(,10437) as long as programming is concerned.
tar.texi(,10438) 
tar.texi(,10439) The @option{--verify} (@option{-W}) option will not work in
tar.texi(,10440) conjunction with the @option{--multi-volume} (@option{-M}) option or
tar.texi(,10441) the @option{--append} (@option{-r}), @option{--update} (@option{-u})
tar.texi(,10442) and @option{--delete} operations.  @xref{Operations}, for more
tar.texi(,10443) information on these operations.
tar.texi(,10444) 
tar.texi(,10445) Also, since @command{tar} normally strips leading @samp{/} from file
tar.texi(,10446) names (@pxref{absolute}), a command like @samp{tar --verify -cf
tar.texi(,10447) /tmp/foo.tar /etc} will work as desired only if the working directory is
tar.texi(,10448) @file{/}, as @command{tar} uses the archive's relative member names
tar.texi(,10449) (e.g., @file{etc/motd}) when verifying the archive.
tar.texi(,10450) 
tar.texi(,10451) @node Write Protection
tar.texi(,10452) @section Write Protection
tar.texi(,10453) 
tar.texi(,10454) Almost all tapes and diskettes, and in a few rare cases, even disks can
tar.texi(,10455) be @dfn{write protected}, to protect data on them from being changed.
tar.texi(,10456) Once an archive is written, you should write protect the media to prevent
tar.texi(,10457) the archive from being accidentally overwritten or deleted.  (This will
tar.texi(,10458) protect the archive from being changed with a tape or floppy drive---it
tar.texi(,10459) will not protect it from magnet fields or other physical hazards).
tar.texi(,10460) 
tar.texi(,10461) The write protection device itself is usually an integral part of the
tar.texi(,10462) physical media, and can be a two position (write enabled/write
tar.texi(,10463) disabled) switch, a notch which can be popped out or covered, a ring
tar.texi(,10464) which can be removed from the center of a tape reel, or some other
tar.texi(,10465) changeable feature.
tar.texi(,10466) 
tar.texi(,10467) @node Changes
tar.texi(,10468) @appendix Changes
tar.texi(,10469) 
tar.texi(,10470) This appendix lists some important user-visible changes between
tar.texi(GNUTAR,10471) version tar.texi(GNUTAR,10471) @acronym{GNU} @command{tar} 1.15.92 and previous versions. An up-to-date
tar.texi(,10472) version of this document is available at
tar.texi(,10473) @uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the
tar.texi(GNUTAR,10474) @acronym{GNU} @command{tar} documentation page}.
tar.texi(,10475) 
tar.texi(,10476) @table @asis
tar.texi(,10477) @item Use of globbing patterns when listing and extracting.
tar.texi(,10478) 
tar.texi(,10479) Previous versions of GNU tar assumed shell-style globbing when
tar.texi(,10480) extracting from or listing an archive.  For example:
tar.texi(,10481) 
tar.texi(,10482) @smallexample
tar.texi(,10483) $ @kbd{tar xf foo.tar '*.c'}
tar.texi(,10484) @end smallexample
tar.texi(,10485) 
tar.texi(,10486) would extract all files whose names end in @samp{.c}.  This behavior
tar.texi(,10487) was not documented and was incompatible with traditional tar
tar.texi(,10488) implementations.  Therefore, starting from version 1.15.91, GNU tar
tar.texi(,10489) no longer uses globbing by default.  For example, the above invocation
tar.texi(,10490) is now interpreted as a request to extract from the archive the file
tar.texi(,10491) named @file{*.c}.
tar.texi(,10492) 
tar.texi(,10493) To facilitate transition to the new behavior for those users who got
tar.texi(,10494) used to the previous incorrect one, @command{tar} will print a warning
tar.texi(,10495) if it finds out that a requested member was not found in the archive
tar.texi(,10496) and its name looks like a globbing pattern.  For example:
tar.texi(,10497) 
tar.texi(,10498) @smallexample
tar.texi(,10499) $ @kbd{tar xf foo.tar  '*.c'}
tar.texi(,10500) tar: Pattern matching characters used in file names. Please,
tar.texi(,10501) tar: use --wildcards to enable pattern matching, or --no-wildcards to
tar.texi(,10502) tar: suppress this warning.
tar.texi(,10503) tar: *.c: Not found in archive
tar.texi(,10504) tar: Error exit delayed from previous errors
tar.texi(,10505) @end smallexample
tar.texi(,10506) 
tar.texi(,10507) To treat member names as globbing patterns, use --wildcards option.
tar.texi(,10508) If you want to tar to mimic the behavior of versions prior to 1.15.91,
tar.texi(,10509) add this option to your @env{TAR_OPTIONS} variable.
tar.texi(,10510) 
tar.texi(,10511) @xref{wildcards}, for the detailed discussion of the use of globbing
tar.texi(GNUTAR,10512) patterns by tar.texi(GNUTAR,10512) @acronym{GNU} @command{tar}.
tar.texi(,10513) 
tar.texi(,10514) @item Use of short option @option{-o}.
tar.texi(,10515) 
tar.texi(GNUTAR,10516) Earlier versions of tar.texi(GNUTAR,10516) @acronym{GNU} @command{tar} understood @option{-o} command line
tar.texi(,10517) option as a synonym for @option{--old-archive}.
tar.texi(,10518) 
tar.texi(GNUTAR,10519) @acronym{GNU} @command{tar} starting from version 1.13.90 understands this option as
tar.texi(,10520) a synonym for @option{--no-same-owner}.  This is compatible with
tar.texi(,10521) UNIX98 @command{tar} implementations.
tar.texi(,10522) 
tar.texi(,10523) However, to facilitate transition, @option{-o} option retains its
tar.texi(,10524) old semantics when it is used with one of archive-creation commands.
tar.texi(,10525) Users are encouraged to use @option{--format=oldgnu} instead.
tar.texi(,10526) 
tar.texi(,10527) It is especially important, since versions of @acronym{GNU} Automake
tar.texi(,10528) up to and including 1.8.4 invoke tar with this option to produce
tar.texi(,10529) distribution tarballs.  @xref{Formats,v7}, for the detailed discussion
tar.texi(,10530) of this issue and its implications.
tar.texi(,10531) 
tar.texi(FIXME,10534) @allow-recursion
tar.texi(FIXME,10534) @quote-arg
tar.texi(FIXME,10534) .
tar.texi(,10535) @xref{Options, tar-v7, Changing Automake's Behavior,
tar.texi(,10536) automake, GNU Automake}, for a description on how to use various
tar.texi(,10537) archive formats with @command{automake}.
tar.texi(,10538) 
tar.texi(GNUTAR,10539) Future versions of tar.texi(GNUTAR,10539) @acronym{GNU} @command{tar} will understand @option{-o} only as a
tar.texi(,10540) synonym for @option{--no-same-owner}.
tar.texi(,10541) 
tar.texi(,10542) @item Use of short option @option{-l}
tar.texi(,10543) 
tar.texi(GNUTAR,10544) Earlier versions of tar.texi(GNUTAR,10544) @acronym{GNU} @command{tar} understood @option{-l} option as a
tar.texi(,10545) synonym for @option{--one-file-system}.  Since such usage contradicted
tar.texi(,10546) to UNIX98 specification and harmed compatibility with other
tar.texi(,10547) implementation, it was declared deprecated in version 1.14.  However,
tar.texi(,10548) to facilitate transition to its new semantics, it was supported by
tar.texi(,10549) versions 1.15 and 1.15.90.  The present use of @option{-l} as a short
tar.texi(,10550) variant of @option{--check-links} was introduced in version 1.15.91.
tar.texi(,10551) 
tar.texi(,10552) @item Use of options @option{--portability} and @option{--old-archive}
tar.texi(,10553) 
tar.texi(,10554) These options are deprecated.  Please use @option{--format=v7} instead.
tar.texi(,10555) 
tar.texi(,10556) @item Use of option @option{--posix}
tar.texi(,10557) 
tar.texi(,10558) This option is deprecated.  Please use @option{--format=posix} instead.
tar.texi(,10559) @end table
tar.texi(,10560) 
tar.texi(,10561) @node Configuring Help Summary
tar.texi(,10562) @appendix Configuring Help Summary
tar.texi(,10563) 
tar.texi(,10564) Running @kbd{tar --help} displays the short @command{tar} option
tar.texi(,10565) summary (@pxref{help}). This summary is organised by @dfn{groups} of
tar.texi(,10566) semantically close options. The options within each group are printed
tar.texi(,10567) in the following order: a short option, eventually followed by a list
tar.texi(,10568) of corresponding long option names, followed by a short description of
tar.texi(,10569) the option. For example, here is an excerpt from the actual @kbd{tar
tar.texi(,10570) --help} output:
tar.texi(,10571) 
tar.texi(,10572) @verbatim
tar.texi(,10573)  Main operation mode:
tar.texi(,10574) 
tar.texi(,10575)   -A, --catenate, --concatenate   append tar files to an archive
tar.texi(,10576)   -c, --create               create a new archive
tar.texi(,10577)   -d, --diff, --compare      find differences between archive and
tar.texi(,10578)                              file system
tar.texi(,10579)       --delete               delete from the archive
tar.texi(,10580) @end verbatim
tar.texi(,10581) 
tar.texi(,10582) @vrindex ARGP_HELP_FMT, environment variable
tar.texi(,10583) The exact visual representation of the help output is configurable via
tar.texi(,10584) @env{ARGP_HELP_FMT} environment variable. The value of this variable
tar.texi(,10585) is a comma-separated list of @dfn{format variable} assignments. There
tar.texi(,10586) are two kinds of format variables. An @dfn{offset variable} keeps the
tar.texi(,10587) offset of some part of help output text from the leftmost column on
tar.texi(,10588) the screen. A @dfn{boolean} variable is a flag that toggles some
tar.texi(,10589) output feature on or off. Depending on the type of the corresponding
tar.texi(,10590) variable, there are two kinds of assignments:
tar.texi(,10591) 
tar.texi(,10592) @table @asis
tar.texi(,10593) @item Offset assignment
tar.texi(,10594) 
tar.texi(,10595) The assignment to an offset variable has the following syntax:
tar.texi(,10596) 
tar.texi(,10597) @smallexample
tar.texi(,10598) @var{variable}=@var{value}
tar.texi(,10599) @end smallexample
tar.texi(,10600) 
tar.texi(,10601) @noindent
tar.texi(,10602) where @var{variable} is the variable name, and @var{value} is a
tar.texi(,10603) numeric value to be assigned to the variable.
tar.texi(,10604) 
tar.texi(,10605) @item Boolean assignment
tar.texi(,10606) 
tar.texi(,10607) To assign @code{true} value to a variable, simply put this variable name. To
tar.texi(,10608) assign @code{false} value, prefix the variable name with @samp{no-}. For
tar.texi(,10609) example:
tar.texi(,10610) 
tar.texi(,10611) @smallexample
tar.texi(,10612) @group
tar.texi(,10613) # Assign @code{true} value:
tar.texi(,10614) dup-args
tar.texi(,10615) # Assign @code{false} value:
tar.texi(,10616) no-dup-args
tar.texi(,10617) @end group
tar.texi(,10618) @end smallexample
tar.texi(,10619) @end table
tar.texi(,10620) 
tar.texi(,10621) Following variables are declared:
tar.texi(,10622) 
tar.texi(,10623) @deftypevr {Help Output} boolean dup-args
tar.texi(,10624) If true, arguments for an option are shown with both short and long
tar.texi(,10625) options, even when a given option has both forms, for example:
tar.texi(,10626) 
tar.texi(,10627) @smallexample
tar.texi(,10628)   -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE
tar.texi(,10629) @end smallexample
tar.texi(,10630) 
tar.texi(,10631) If false, then if an option has both short and long forms, the
tar.texi(,10632) argument is only shown with the long one, for example:
tar.texi(,10633) 
tar.texi(,10634) @smallexample
tar.texi(,10635)   -f, --file=ARCHIVE         use archive file or device ARCHIVE
tar.texi(,10636) @end smallexample
tar.texi(,10637) 
tar.texi(,10638) @noindent
tar.texi(,10639) and a message indicating that the argument is applicable to both
tar.texi(,10640) forms is printed below the options. This message can be disabled
tar.texi(,10641) using @code{dup-args-note} (see below).
tar.texi(,10642) 
tar.texi(,10643) The default is false.
tar.texi(,10644) @end deftypevr
tar.texi(,10645) 
tar.texi(,10646) @deftypevr {Help Output} boolean dup-args-note
tar.texi(,10647) If this variable is true, which is the default, the following notice
tar.texi(,10648) is displayed at the end of the help output:
tar.texi(,10649) 
tar.texi(,10650) @quotation
tar.texi(,10651) Mandatory or optional arguments to long options are also mandatory or
tar.texi(,10652) optional for any corresponding short options.
tar.texi(,10653) @end quotation
tar.texi(,10654) 
tar.texi(,10655) Setting @code{no-dup-args-note} inhibits this message. Normally, only one of
tar.texi(,10656) variables @code{dup-args} or @code{dup-args-note} should be set.
tar.texi(,10657) @end deftypevr
tar.texi(,10658) 
tar.texi(,10659) @deftypevr {Help Output} offset short-opt-col
tar.texi(,10660) Column in which short options start. Default is 2.
tar.texi(,10661) 
tar.texi(,10662) @smallexample
tar.texi(,10663) @group
tar.texi(,10664) $ @kbd{tar --help|grep ARCHIVE}
tar.texi(,10665)   -f, --file=ARCHIVE   use archive file or device ARCHIVE
tar.texi(,10666) $ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE}
tar.texi(,10667)       -f, --file=ARCHIVE   use archive file or device ARCHIVE
tar.texi(,10668) @end group
tar.texi(,10669) @end smallexample
tar.texi(,10670) @end deftypevr
tar.texi(,10671) 
tar.texi(,10672) @deftypevr {Help Output} offset long-opt-col
tar.texi(,10673) Column in which long options start. Default is 6. For example:
tar.texi(,10674) 
tar.texi(,10675) @smallexample
tar.texi(,10676) @group
tar.texi(,10677) $ @kbd{tar --help|grep ARCHIVE}
tar.texi(,10678)   -f, --file=ARCHIVE   use archive file or device ARCHIVE
tar.texi(,10679) $ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE}
tar.texi(,10680)   -f,           --file=ARCHIVE   use archive file or device ARCHIVE
tar.texi(,10681) @end group
tar.texi(,10682) @end smallexample
tar.texi(,10683) @end deftypevr
tar.texi(,10684) 
tar.texi(,10685) @deftypevr {Help Output} offset doc-opt-col
tar.texi(,10686) Column in which @dfn{doc options} start.  A doc option isn't actually
tar.texi(,10687) an option, but rather an arbitrary piece of documentation that is
tar.texi(,10688) displayed in much the same manner as the options.  For example, in
tar.texi(,10689) the description of @option{--format} option:
tar.texi(,10690) 
tar.texi(,10691) @smallexample
tar.texi(,10692) @group
tar.texi(,10693)   -H, --format=FORMAT        create archive of the given format.
tar.texi(,10694) 
tar.texi(,10695)  FORMAT is one of the following:
tar.texi(,10696) 
tar.texi(,10697)     gnu                      GNU tar 1.13.x format
tar.texi(,10698)     oldgnu                   GNU format as per tar <= 1.12
tar.texi(,10699)     pax                      POSIX 1003.1-2001 (pax) format
tar.texi(,10700)     posix                    same as pax
tar.texi(,10701)     ustar                    POSIX 1003.1-1988 (ustar) format
tar.texi(,10702)     v7                       old V7 tar format
tar.texi(,10703) @end group
tar.texi(,10704) @end smallexample
tar.texi(,10705) 
tar.texi(,10706) @noindent
tar.texi(,10707) the format names are doc options. Thus, if you set
tar.texi(,10708) @kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output
tar.texi(,10709) will look as follows:
tar.texi(,10710) 
tar.texi(,10711) @smallexample
tar.texi(,10712) @group
tar.texi(,10713)   -H, --format=FORMAT        create archive of the given format.
tar.texi(,10714) 
tar.texi(,10715)  FORMAT is one of the following:
tar.texi(,10716) 
tar.texi(,10717)         gnu                      GNU tar 1.13.x format
tar.texi(,10718)         oldgnu                   GNU format as per tar <= 1.12
tar.texi(,10719)         pax                      POSIX 1003.1-2001 (pax) format
tar.texi(,10720)         posix                    same as pax
tar.texi(,10721)         ustar                    POSIX 1003.1-1988 (ustar) format
tar.texi(,10722)         v7                       old V7 tar format
tar.texi(,10723) @end group
tar.texi(,10724) @end smallexample
tar.texi(,10725) @end deftypevr
tar.texi(,10726) 
tar.texi(,10727) @deftypevr {Help Output} offset opt-doc-col
tar.texi(,10728) Column in which option description starts. Default is 29.
tar.texi(,10729) 
tar.texi(,10730) @smallexample
tar.texi(,10731) @group
tar.texi(,10732) $ @kbd{tar --help|grep ARCHIVE}
tar.texi(,10733)   -f, --file=ARCHIVE         use archive file or device ARCHIVE
tar.texi(,10734) $ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE}
tar.texi(,10735)   -f, --file=ARCHIVE   use archive file or device ARCHIVE
tar.texi(,10736) $ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE}
tar.texi(,10737)   -f, --file=ARCHIVE
tar.texi(,10738)            use archive file or device ARCHIVE
tar.texi(,10739) @end group
tar.texi(,10740) @end smallexample
tar.texi(,10741) 
tar.texi(,10742) @noindent
tar.texi(,10743) Notice, that the description starts on a separate line if
tar.texi(,10744) @code{opt-doc-col} value is too small.
tar.texi(,10745) @end deftypevr
tar.texi(,10746) 
tar.texi(,10747) @deftypevr {Help Output} offset header-col
tar.texi(,10748) Column in which @dfn{group headers} are printed.  A group header is a
tar.texi(,10749) descriptive text preceding an option group.  For example, in the
tar.texi(,10750) following text:
tar.texi(,10751) 
tar.texi(,10752) @verbatim
tar.texi(,10753)  Main operation mode:
tar.texi(,10754) 
tar.texi(,10755)   -A, --catenate, --concatenate   append tar files to
tar.texi(,10756)                              an archive
tar.texi(,10757)   -c, --create               create a new archive
tar.texi(,10758) @end verbatim
tar.texi(,10759) @noindent
tar.texi(,10760) @samp{Main operation mode:} is the group header.
tar.texi(,10761) 
tar.texi(,10762) The default value is 1.
tar.texi(,10763) @end deftypevr
tar.texi(,10764) 
tar.texi(,10765) @deftypevr {Help Output} offset usage-indent
tar.texi(,10766) Indentation of wrapped usage lines. Affects @option{--usage}
tar.texi(,10767) output. Default is 12.
tar.texi(,10768) @end deftypevr
tar.texi(,10769) 
tar.texi(,10770) @deftypevr {Help Output} offset rmargin
tar.texi(,10771) Right margin of the text output. Used for wrapping.
tar.texi(,10772) @end deftypevr
tar.texi(,10773) 
tar.texi(,10774) @node Tar Internals
tar.texi(,10775) @appendix Tar Internals
intern.texi(,1) @c This is part of the paxutils manual.
intern.texi(,2) @c Copyright (C) 2006 Free Software Foundation, Inc.
intern.texi(,3) @c This file is distributed under GFDL 1.1 or any later version
intern.texi(,4) @c published by the Free Software Foundation.
intern.texi(,5) 
intern.texi(,6) @menu
intern.texi(,7) * Standard::           Basic Tar Format
intern.texi(,8) * Extensions::         @acronym{GNU} Extensions to the Archive Format
intern.texi(,9) * Sparse Formats::     Storing Sparse Files
intern.texi(,10) * Snapshot Files::
intern.texi(,11) * Dumpdir::
intern.texi(,12) @end menu
intern.texi(,13) 
intern.texi(,14) @node Standard
intern.texi(,15) @unnumberedsec Basic Tar Format
intern.texi(UNREVISED,16) @quotation
intern.texi(UNREVISED,16) @emph{(This message will disappear, once this node revised.)}
intern.texi(UNREVISED,16) @end quotation
intern.texi(,17) 
intern.texi(,18) While an archive may contain many files, the archive itself is a
intern.texi(,19) single ordinary file.  Like any other file, an archive file can be
intern.texi(,20) written to a storage device such as a tape or disk, sent through a
intern.texi(,21) pipe or over a network, saved on the active file system, or even
intern.texi(,22) stored in another archive.  An archive file is not easy to read or
intern.texi(,23) manipulate without using the @command{tar} utility or Tar mode in
intern.texi(,24) @acronym{GNU} Emacs.
intern.texi(,25) 
intern.texi(,26) Physically, an archive consists of a series of file entries terminated
intern.texi(,27) by an end-of-archive entry, which consists of two 512 blocks of zero
intern.texi(,28) bytes.  A file
intern.texi(,29) entry usually describes one of the files in the archive (an
intern.texi(,30) @dfn{archive member}), and consists of a file header and the contents
intern.texi(,31) of the file.  File headers contain file names and statistics, checksum
intern.texi(,32) information which @command{tar} uses to detect file corruption, and
intern.texi(,33) information about file types.
intern.texi(,34) 
intern.texi(,35) Archives are permitted to have more than one member with the same
intern.texi(,36) member name.  One way this situation can occur is if more than one
intern.texi(,37) version of a file has been stored in the archive.  For information
intern.texi(,38) about adding new versions of a file to an archive, see @ref{update}.
intern.texi(FIXME-xref,40) @quote-arg
intern.texi(,41) 
intern.texi(,42) In addition to entries describing archive members, an archive may
intern.texi(,43) contain entries which @command{tar} itself uses to store information.
intern.texi(,44) @xref{label}, for an example of such an archive entry.
intern.texi(,45) 
intern.texi(,46) A @command{tar} archive file contains a series of blocks.  Each block
intern.texi(,47) contains @code{BLOCKSIZE} bytes.  Although this format may be thought
intern.texi(,48) of as being on magnetic tape, other media are often used.
intern.texi(,49) 
intern.texi(,50) Each file archived is represented by a header block which describes
intern.texi(,51) the file, followed by zero or more blocks which give the contents
intern.texi(,52) of the file.  At the end of the archive file there are two 512-byte blocks
intern.texi(,53) filled with binary zeros as an end-of-file marker.  A reasonable system
intern.texi(,54) should write such end-of-file marker at the end of an archive, but
intern.texi(,55) must not assume that such a block exists when reading an archive.  In
intern.texi(GNUTAR,56) particular intern.texi(GNUTAR,56) @acronym{GNU} @command{tar} always issues a warning if it does not encounter it.
intern.texi(,57) 
intern.texi(,58) The blocks may be @dfn{blocked} for physical I/O operations.
intern.texi(,59) Each record of @var{n} blocks (where @var{n} is set by the
intern.texi(,60) @option{--blocking-factor=@var{512-size}} (@option{-b @var{512-size}}) option to @command{tar}) is written with a single
intern.texi(,61) @w{@samp{write ()}} operation.  On magnetic tapes, the result of
intern.texi(,62) such a write is a single record.  When writing an archive,
intern.texi(,63) the last record of blocks should be written at the full size, with
intern.texi(,64) blocks after the zero block containing all zeros.  When reading
intern.texi(,65) an archive, a reasonable system should properly handle an archive
intern.texi(,66) whose last record is shorter than the rest, or which contains garbage
intern.texi(,67) records after a zero block.
intern.texi(,68) 
intern.texi(GNUTAR,69) The header block is defined in C as follows.  In the intern.texi(GNUTAR,69) @acronym{GNU} @command{tar}
intern.texi(,70) distribution, this is part of file @file{src/tar.h}:
intern.texi(,71) 
intern.texi(,72) @smallexample
header.texi(,1) @comment  GNU tar Archive Format description.
header.texi(,2) @comment
header.texi(,3) @comment   Copyright (C) 1988, 1989, 1991, 1992, 1993, 1994, 1995, 1996, 1997,
header.texi(,4) @comment   2000, 2001, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
header.texi(,5) @comment
header.texi(,6) @comment   This program is free software; you can redistribute it and/or modify it
header.texi(,7) @comment   under the terms of the GNU General Public License as published by the
header.texi(,8) @comment   Free Software Foundation; either version 2, or (at your option) any later
header.texi(,9) @comment   version.
header.texi(,10) @comment
header.texi(,11) @comment   This program is distributed in the hope that it will be useful, but
header.texi(,12) @comment   WITHOUT ANY WARRANTY; without even the implied warranty of
header.texi(,13) @comment   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
header.texi(,14) @comment   Public License for more details.
header.texi(,15) @comment
header.texi(,16) @comment   You should have received a copy of the GNU General Public License along
header.texi(,17) @comment   with this program; if not, write to the Free Software Foundation, Inc.,
header.texi(,18) @comment   51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.  
header.texi(,19) 
header.texi(,20) /*@r{ tar Header Block, from POSIX 1003.1-1990.  }*/
header.texi(,21) 
header.texi(,22) /*@r{ POSIX header.  }*/
header.texi(,23) 
header.texi(,24) struct posix_header
header.texi(,25) @{                              /*@r{ byte offset }*/
header.texi(,26)   char name[100];               /*@r{   0 }*/
header.texi(,27)   char mode[8];                 /*@r{ 100 }*/
header.texi(,28)   char uid[8];                  /*@r{ 108 }*/
header.texi(,29)   char gid[8];                  /*@r{ 116 }*/
header.texi(,30)   char size[12];                /*@r{ 124 }*/
header.texi(,31)   char mtime[12];               /*@r{ 136 }*/
header.texi(,32)   char chksum[8];               /*@r{ 148 }*/
header.texi(,33)   char typeflag;                /*@r{ 156 }*/
header.texi(,34)   char linkname[100];           /*@r{ 157 }*/
header.texi(,35)   char magic[6];                /*@r{ 257 }*/
header.texi(,36)   char version[2];              /*@r{ 263 }*/
header.texi(,37)   char uname[32];               /*@r{ 265 }*/
header.texi(,38)   char gname[32];               /*@r{ 297 }*/
header.texi(,39)   char devmajor[8];             /*@r{ 329 }*/
header.texi(,40)   char devminor[8];             /*@r{ 337 }*/
header.texi(,41)   char prefix[155];             /*@r{ 345 }*/
header.texi(,42)                                 /*@r{ 500 }*/
header.texi(,43) @};
header.texi(,44) 
header.texi(,45) #define TMAGIC   "ustar"        /*@r{ ustar and a null }*/
header.texi(,46) #define TMAGLEN  6
header.texi(,47) #define TVERSION "00"           /*@r{ 00 and no null }*/
header.texi(,48) #define TVERSLEN 2
header.texi(,49) 
header.texi(,50) /*@r{ Values used in typeflag field.  }*/
header.texi(,51) #define REGTYPE  '0'            /*@r{ regular file }*/
header.texi(,52) #define AREGTYPE '\0'           /*@r{ regular file }*/
header.texi(,53) #define LNKTYPE  '1'            /*@r{ link }*/
header.texi(,54) #define SYMTYPE  '2'            /*@r{ reserved }*/
header.texi(,55) #define CHRTYPE  '3'            /*@r{ character special }*/
header.texi(,56) #define BLKTYPE  '4'            /*@r{ block special }*/
header.texi(,57) #define DIRTYPE  '5'            /*@r{ directory }*/
header.texi(,58) #define FIFOTYPE '6'            /*@r{ FIFO special }*/
header.texi(,59) #define CONTTYPE '7'            /*@r{ reserved }*/
header.texi(,60) 
header.texi(,61) #define XHDTYPE  'x'            /*@r{ Extended header referring to the
header.texi(,62)                                    next file in the archive }*/
header.texi(,63) #define XGLTYPE  'g'            /*@r{ Global extended header }*/
header.texi(,64) 
header.texi(,65) /*@r{ Bits used in the mode field, values in octal.  }*/
header.texi(,66) #define TSUID    04000          /*@r{ set UID on execution }*/
header.texi(,67) #define TSGID    02000          /*@r{ set GID on execution }*/
header.texi(,68) #define TSVTX    01000          /*@r{ reserved }*/
header.texi(,69)                                 /*@r{ file permissions }*/
header.texi(,70) #define TUREAD   00400          /*@r{ read by owner }*/
header.texi(,71) #define TUWRITE  00200          /*@r{ write by owner }*/
header.texi(,72) #define TUEXEC   00100          /*@r{ execute/search by owner }*/
header.texi(,73) #define TGREAD   00040          /*@r{ read by group }*/
header.texi(,74) #define TGWRITE  00020          /*@r{ write by group }*/
header.texi(,75) #define TGEXEC   00010          /*@r{ execute/search by group }*/
header.texi(,76) #define TOREAD   00004          /*@r{ read by other }*/
header.texi(,77) #define TOWRITE  00002          /*@r{ write by other }*/
header.texi(,78) #define TOEXEC   00001          /*@r{ execute/search by other }*/
header.texi(,79) 
header.texi(,80) /*@r{ tar Header Block, GNU extensions.  }*/
header.texi(,81) 
header.texi(,82) /*@r{ In GNU tar, SYMTYPE is for to symbolic links, and CONTTYPE is for
header.texi(,83)    contiguous files, so maybe disobeying the `reserved' comment in POSIX
header.texi(,84)    header description.  I suspect these were meant to be used this way, and
header.texi(,85)    should not have really been `reserved' in the published standards.  }*/
header.texi(,86) 
header.texi(,87) /*@r{ *BEWARE* *BEWARE* *BEWARE* that the following information is still
header.texi(,88)    boiling, and may change.  Even if the OLDGNU format description should be
header.texi(,89)    accurate, the so-called GNU format is not yet fully decided.  It is
header.texi(,90)    surely meant to use only extensions allowed by POSIX, but the sketch
header.texi(,91)    below repeats some ugliness from the OLDGNU format, which should rather
header.texi(,92)    go away.  Sparse files should be saved in such a way that they do *not*
header.texi(,93)    require two passes at archive creation time.  Huge files get some POSIX
header.texi(,94)    fields to overflow, alternate solutions have to be sought for this.  }*/
header.texi(,95) 
header.texi(,96) /*@r{ Descriptor for a single file hole.  }*/
header.texi(,97) 
header.texi(,98) struct sparse
header.texi(,99) @{                              /*@r{ byte offset }*/
header.texi(,100)   char offset[12];              /*@r{   0 }*/
header.texi(,101)   char numbytes[12];            /*@r{  12 }*/
header.texi(,102)                                 /*@r{  24 }*/
header.texi(,103) @};
header.texi(,104) 
header.texi(,105) /*@r{ Sparse files are not supported in POSIX ustar format.  For sparse files
header.texi(,106)    with a POSIX header, a GNU extra header is provided which holds overall
header.texi(,107)    sparse information and a few sparse descriptors.  When an old GNU header
header.texi(,108)    replaces both the POSIX header and the GNU extra header, it holds some
header.texi(,109)    sparse descriptors too.  Whether POSIX or not, if more sparse descriptors
header.texi(,110)    are still needed, they are put into as many successive sparse headers as
header.texi(,111)    necessary.  The following constants tell how many sparse descriptors fit
header.texi(,112)    in each kind of header able to hold them.  }*/
header.texi(,113) 
header.texi(,114) #define SPARSES_IN_EXTRA_HEADER  16
header.texi(,115) #define SPARSES_IN_OLDGNU_HEADER 4
header.texi(,116) #define SPARSES_IN_SPARSE_HEADER 21
header.texi(,117) 
header.texi(,118) /*@r{ Extension header for sparse files, used immediately after the GNU extra
header.texi(,119)    header, and used only if all sparse information cannot fit into that
header.texi(,120)    extra header.  There might even be many such extension headers, one after
header.texi(,121)    the other, until all sparse information has been recorded.  }*/
header.texi(,122) 
header.texi(,123) struct sparse_header
header.texi(,124) @{                              /*@r{ byte offset }*/
header.texi(,125)   struct sparse sp[SPARSES_IN_SPARSE_HEADER];
header.texi(,126)                                 /*@r{   0 }*/
header.texi(,127)   char isextended;              /*@r{ 504 }*/
header.texi(,128)                                 /*@r{ 505 }*/
header.texi(,129) @};
header.texi(,130) 
header.texi(,131) /*@r{ The old GNU format header conflicts with POSIX format in such a way that
header.texi(,132)    POSIX archives may fool old GNU tar's, and POSIX tar's might well be
header.texi(,133)    fooled by old GNU tar archives.  An old GNU format header uses the space
header.texi(,134)    used by the prefix field in a POSIX header, and cumulates information
header.texi(,135)    normally found in a GNU extra header.  With an old GNU tar header, we
header.texi(,136)    never see any POSIX header nor GNU extra header.  Supplementary sparse
header.texi(,137)    headers are allowed, however.  }*/
header.texi(,138) 
header.texi(,139) struct oldgnu_header
header.texi(,140) @{                              /*@r{ byte offset }*/
header.texi(,141)   char unused_pad1[345];        /*@r{   0 }*/
header.texi(,142)   char atime[12];               /*@r{ 345 Incr. archive: atime of the file }*/
header.texi(,143)   char ctime[12];               /*@r{ 357 Incr. archive: ctime of the file }*/
header.texi(,144)   char offset[12];              /*@r{ 369 Multivolume archive: the offset of
header.texi(,145)                                    the start of this volume }*/
header.texi(,146)   char longnames[4];            /*@r{ 381 Not used }*/
header.texi(,147)   char unused_pad2;             /*@r{ 385 }*/
header.texi(,148)   struct sparse sp[SPARSES_IN_OLDGNU_HEADER];
header.texi(,149)                                 /*@r{ 386 }*/
header.texi(,150)   char isextended;              /*@r{ 482 Sparse file: Extension sparse header
header.texi(,151)                                    follows }*/
header.texi(,152)   char realsize[12];            /*@r{ 483 Sparse file: Real size}*/
header.texi(,153)                                 /*@r{ 495 }*/
header.texi(,154) @};
header.texi(,155) 
header.texi(,156) /*@r{ OLDGNU_MAGIC uses both magic and version fields, which are contiguous.
header.texi(,157)    Found in an archive, it indicates an old GNU header format, which will be
header.texi(,158)    hopefully become obsolescent.  With OLDGNU_MAGIC, uname and gname are
header.texi(,159)    valid, though the header is not truly POSIX conforming.  }*/
header.texi(,160) #define OLDGNU_MAGIC "ustar  "  /*@r{ 7 chars and a null }*/
header.texi(,161) 
header.texi(,162) /*@r{ The standards committee allows only capital A through capital Z for
header.texi(,163)    user-defined expansion.  Other letters in use include:
header.texi(,164) 
header.texi(,165)    'A' Solaris Access Control List
header.texi(,166)    'E' Solaris Extended Attribute File
header.texi(,167)    'I' Inode only, as in 'star'
header.texi(,168)    'X' POSIX 1003.1-2001 eXtended (VU version)  }*/
header.texi(,169) 
header.texi(,170) /*@r{ This is a dir entry that contains the names of files that were in the
header.texi(,171)    dir at the time the dump was made.  }*/
header.texi(,172) #define GNUTYPE_DUMPDIR 'D'
header.texi(,173) 
header.texi(,174) /*@r{ Identifies the *next* file on the tape as having a long linkname.  }*/
header.texi(,175) #define GNUTYPE_LONGLINK 'K'
header.texi(,176) 
header.texi(,177) /*@r{ Identifies the *next* file on the tape as having a long name.  }*/
header.texi(,178) #define GNUTYPE_LONGNAME 'L'
header.texi(,179) 
header.texi(,180) /*@r{ This is the continuation of a file that began on another volume.  }*/
header.texi(,181) #define GNUTYPE_MULTIVOL 'M'
header.texi(,182) 
header.texi(,183) /*@r{ For storing filenames that do not fit into the main header.  }*/
header.texi(,184) #define GNUTYPE_NAMES 'N'
header.texi(,185) 
header.texi(,186) /*@r{ This is for sparse files.  }*/
header.texi(,187) #define GNUTYPE_SPARSE 'S'
header.texi(,188) 
header.texi(,189) /*@r{ This file is a tape/volume header.  Ignore it on extraction.  }*/
header.texi(,190) #define GNUTYPE_VOLHDR 'V'
header.texi(,191) 
header.texi(,192) /*@r{ Solaris extended header }*/
header.texi(,193) #define SOLARIS_XHDTYPE 'X'
header.texi(,194) 
header.texi(,195) /*@r{ J@"org Schilling star header }*/
header.texi(,196) 
header.texi(,197) struct star_header
header.texi(,198) @{                              /*@r{ byte offset }*/
header.texi(,199)   char name[100];               /*@r{   0 }*/
header.texi(,200)   char mode[8];                 /*@r{ 100 }*/
header.texi(,201)   char uid[8];                  /*@r{ 108 }*/
header.texi(,202)   char gid[8];                  /*@r{ 116 }*/
header.texi(,203)   char size[12];                /*@r{ 124 }*/
header.texi(,204)   char mtime[12];               /*@r{ 136 }*/
header.texi(,205)   char chksum[8];               /*@r{ 148 }*/
header.texi(,206)   char typeflag;                /*@r{ 156 }*/
header.texi(,207)   char linkname[100];           /*@r{ 157 }*/
header.texi(,208)   char magic[6];                /*@r{ 257 }*/
header.texi(,209)   char version[2];              /*@r{ 263 }*/
header.texi(,210)   char uname[32];               /*@r{ 265 }*/
header.texi(,211)   char gname[32];               /*@r{ 297 }*/
header.texi(,212)   char devmajor[8];             /*@r{ 329 }*/
header.texi(,213)   char devminor[8];             /*@r{ 337 }*/
header.texi(,214)   char prefix[131];             /*@r{ 345 }*/
header.texi(,215)   char atime[12];               /*@r{ 476 }*/
header.texi(,216)   char ctime[12];               /*@r{ 488 }*/
header.texi(,217)                                 /*@r{ 500 }*/
header.texi(,218) @};
header.texi(,219) 
header.texi(,220) #define SPARSES_IN_STAR_HEADER      4
header.texi(,221) #define SPARSES_IN_STAR_EXT_HEADER  21
header.texi(,222) 
header.texi(,223) struct star_in_header
header.texi(,224) @{
header.texi(,225)   char fill[345];       /*@r{   0  Everything that is before t_prefix }*/
header.texi(,226)   char prefix[1];       /*@r{ 345  t_name prefix }*/
header.texi(,227)   char fill2;           /*@r{ 346  }*/
header.texi(,228)   char fill3[8];        /*@r{ 347  }*/
header.texi(,229)   char isextended;      /*@r{ 355  }*/
header.texi(,230)   struct sparse sp[SPARSES_IN_STAR_HEADER]; /*@r{ 356  }*/
header.texi(,231)   char realsize[12];    /*@r{ 452  Actual size of the file }*/
header.texi(,232)   char offset[12];      /*@r{ 464  Offset of multivolume contents }*/
header.texi(,233)   char atime[12];       /*@r{ 476  }*/
header.texi(,234)   char ctime[12];       /*@r{ 488  }*/
header.texi(,235)   char mfill[8];        /*@r{ 500  }*/
header.texi(,236)   char xmagic[4];       /*@r{ 508  "tar" }*/
header.texi(,237) @};
header.texi(,238) 
header.texi(,239) struct star_ext_header
header.texi(,240) @{
header.texi(,241)   struct sparse sp[SPARSES_IN_STAR_EXT_HEADER];
header.texi(,242)   char isextended;
header.texi(,243) @};
header.texi(,244) 
intern.texi(,74) @end smallexample
intern.texi(,75) 
intern.texi(,76) All characters in header blocks are represented by using 8-bit
intern.texi(,77) characters in the local variant of ASCII.  Each field within the
intern.texi(,78) structure is contiguous; that is, there is no padding used within
intern.texi(,79) the structure.  Each character on the archive medium is stored
intern.texi(,80) contiguously.
intern.texi(,81) 
intern.texi(,82) Bytes representing the contents of files (after the header block
intern.texi(,83) of each file) are not translated in any way and are not constrained
intern.texi(,84) to represent characters in any character set.  The @command{tar} format
intern.texi(,85) does not distinguish text files from binary files, and no translation
intern.texi(,86) of file contents is performed.
intern.texi(,87) 
intern.texi(,88) The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
intern.texi(,89) @code{gname} are null-terminated character strings.  All other fields
intern.texi(,90) are zero-filled octal numbers in ASCII.  Each numeric field of width
intern.texi(,91) @var{w} contains @var{w} minus 1 digits, and a null.
intern.texi(,92) 
intern.texi(,93) The @code{name} field is the file name of the file, with directory names
intern.texi(,94) (if any) preceding the file name, separated by slashes.
intern.texi(,95) 
intern.texi(FIXME,96) @allow-recursion
intern.texi(FIXME,96) @quote-arg
intern.texi(FIXME,96) 
intern.texi(,97) 
intern.texi(,98) The @code{mode} field provides nine bits specifying file permissions
intern.texi(,99) and three bits to specify the Set UID, Set GID, and Save Text
intern.texi(,100) (@dfn{sticky}) modes.  Values for these bits are defined above.
intern.texi(,101) When special permissions are required to create a file with a given
intern.texi(,102) mode, and the user restoring files from the archive does not hold such
intern.texi(,103) permissions, the mode bit(s) specifying those special permissions
intern.texi(,104) are ignored.  Modes which are not supported by the operating system
intern.texi(,105) restoring files from the archive will be ignored.  Unsupported modes
intern.texi(,106) should be faked up when creating or updating an archive; e.g., the
intern.texi(,107) group permission could be copied from the @emph{other} permission.
intern.texi(,108) 
intern.texi(,109) The @code{uid} and @code{gid} fields are the numeric user and group
intern.texi(,110) ID of the file owners, respectively.  If the operating system does
intern.texi(,111) not support numeric user or group IDs, these fields should be ignored.
intern.texi(,112) 
intern.texi(,113) The @code{size} field is the size of the file in bytes; linked files
intern.texi(FIXME-xref,115) are archived with this field specified as zero.  intern.texi(FIXME-xref,115) @quote-arg
intern.texi(,116) 
intern.texi(,117) The @code{mtime} field is the data modification time of the file at
intern.texi(,118) the time it was archived.  It is the ASCII representation of the octal
intern.texi(,119) value of the last time the file's contents were modified, represented
intern.texi(,120) as an integer number of
intern.texi(,121) seconds since January 1, 1970, 00:00 Coordinated Universal Time.
intern.texi(,122) 
intern.texi(,123) The @code{chksum} field is the ASCII representation of the octal value
intern.texi(,124) of the simple sum of all bytes in the header block.  Each 8-bit
intern.texi(,125) byte in the header is added to an unsigned integer, initialized to
intern.texi(,126) zero, the precision of which shall be no less than seventeen bits.
intern.texi(,127) When calculating the checksum, the @code{chksum} field is treated as
intern.texi(,128) if it were all blanks.
intern.texi(,129) 
intern.texi(,130) The @code{typeflag} field specifies the type of file archived.  If a
intern.texi(,131) particular implementation does not recognize or permit the specified
intern.texi(,132) type, the file will be extracted as if it were a regular file.  As this
intern.texi(,133) action occurs, @command{tar} issues a warning to the standard error.
intern.texi(,134) 
intern.texi(,135) The @code{atime} and @code{ctime} fields are used in making incremental
intern.texi(,136) backups; they store, respectively, the particular file's access and
intern.texi(,137) status change times.
intern.texi(,138) 
intern.texi(,139) The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option, when
intern.texi(,140) making a multi-volume archive.  The offset is number of bytes into
intern.texi(,141) the file that we need to restart at to continue the file on the next
intern.texi(,142) tape, i.e., where we store the location that a continued file is
intern.texi(,143) continued at.
intern.texi(,144) 
intern.texi(,145) The following fields were added to deal with sparse files.  A file
intern.texi(,146) is @dfn{sparse} if it takes in unallocated blocks which end up being
intern.texi(,147) represented as zeros, i.e., no useful data.  A test to see if a file
intern.texi(,148) is sparse is to look at the number blocks allocated for it versus the
intern.texi(,149) number of characters in the file; if there are fewer blocks allocated
intern.texi(,150) for the file than would normally be allocated for a file of that
intern.texi(,151) size, then the file is sparse.  This is the method @command{tar} uses to
intern.texi(,152) detect a sparse file, and once such a file is detected, it is treated
intern.texi(,153) differently from non-sparse files.
intern.texi(,154) 
intern.texi(,155) Sparse files are often @code{dbm} files, or other database-type files
intern.texi(,156) which have data at some points and emptiness in the greater part of
intern.texi(,157) the file.  Such files can appear to be very large when an @samp{ls
intern.texi(,158) -l} is done on them, when in truth, there may be a very small amount
intern.texi(,159) of important data contained in the file.  It is thus undesirable
intern.texi(,160) to have @command{tar} think that it must back up this entire file, as
intern.texi(,161) great quantities of room are wasted on empty blocks, which can lead
intern.texi(,162) to running out of room on a tape far earlier than is necessary.
intern.texi(,163) Thus, sparse files are dealt with so that these empty blocks are
intern.texi(,164) not written to the tape.  Instead, what is written to the tape is a
intern.texi(,165) description, of sorts, of the sparse file: where the holes are, how
intern.texi(,166) big the holes are, and how much data is found at the end of the hole.
intern.texi(,167) This way, the file takes up potentially far less room on the tape,
intern.texi(,168) and when the file is extracted later on, it will look exactly the way
intern.texi(,169) it looked beforehand.  The following is a description of the fields
intern.texi(,170) used to handle a sparse file:
intern.texi(,171) 
intern.texi(,172) The @code{sp} is an array of @code{struct sparse}.  Each @code{struct
intern.texi(,173) sparse} contains two 12-character strings which represent an offset
intern.texi(,174) into the file and a number of bytes to be written at that offset.
intern.texi(,175) The offset is absolute, and not relative to the offset in preceding
intern.texi(,176) array element.
intern.texi(,177) 
intern.texi(,178) The header can hold four of these @code{struct sparse} at the moment;
intern.texi(,179) if more are needed, they are not stored in the header.
intern.texi(,180) 
intern.texi(,181) The @code{isextended} flag is set when an @code{extended_header}
intern.texi(,182) is needed to deal with a file.  Note that this means that this flag
intern.texi(,183) can only be set when dealing with a sparse file, and it is only set
intern.texi(,184) in the event that the description of the file will not fit in the
intern.texi(,185) allotted room for sparse structures in the header.  In other words,
intern.texi(,186) an extended_header is needed.
intern.texi(,187) 
intern.texi(,188) The @code{extended_header} structure is used for sparse files which
intern.texi(,189) need more sparse structures than can fit in the header.  The header can
intern.texi(,190) fit 4 such structures; if more are needed, the flag @code{isextended}
intern.texi(,191) gets set and the next block is an @code{extended_header}.
intern.texi(,192) 
intern.texi(,193) Each @code{extended_header} structure contains an array of 21
intern.texi(,194) sparse structures, along with a similar @code{isextended} flag
intern.texi(,195) that the header had.  There can be an indeterminate number of such
intern.texi(,196) @code{extended_header}s to describe a sparse file.
intern.texi(,197) 
intern.texi(,198) @table @asis
intern.texi(,199) 
intern.texi(,200) @item @code{REGTYPE}
intern.texi(,201) @itemx @code{AREGTYPE}
intern.texi(,202) These flags represent a regular file.  In order to be compatible
intern.texi(,203) with older versions of @command{tar}, a @code{typeflag} value of
intern.texi(,204) @code{AREGTYPE} should be silently recognized as a regular file.
intern.texi(,205) New archives should be created using @code{REGTYPE}.  Also, for
intern.texi(,206) backward compatibility, @command{tar} treats a regular file whose name
intern.texi(,207) ends with a slash as a directory.
intern.texi(,208) 
intern.texi(,209) @item @code{LNKTYPE}
intern.texi(,210) This flag represents a file linked to another file, of any type,
intern.texi(,211) previously archived.  Such files are identified in Unix by each
intern.texi(,212) file having the same device and inode number.  The linked-to name is
intern.texi(,213) specified in the @code{linkname} field with a trailing null.
intern.texi(,214) 
intern.texi(,215) @item @code{SYMTYPE}
intern.texi(,216) This represents a symbolic link to another file.  The linked-to name
intern.texi(,217) is specified in the @code{linkname} field with a trailing null.
intern.texi(,218) 
intern.texi(,219) @item @code{CHRTYPE}
intern.texi(,220) @itemx @code{BLKTYPE}
intern.texi(,221) These represent character special files and block special files
intern.texi(,222) respectively.  In this case the @code{devmajor} and @code{devminor}
intern.texi(,223) fields will contain the major and minor device numbers respectively.
intern.texi(,224) Operating systems may map the device specifications to their own
intern.texi(,225) local specification, or may ignore the entry.
intern.texi(,226) 
intern.texi(,227) @item @code{DIRTYPE}
intern.texi(,228) This flag specifies a directory or sub-directory.  The directory
intern.texi(,229) name in the @code{name} field should end with a slash.  On systems where
intern.texi(,230) disk allocation is performed on a directory basis, the @code{size} field
intern.texi(,231) will contain the maximum number of bytes (which may be rounded to
intern.texi(,232) the nearest disk block allocation unit) which the directory may
intern.texi(,233) hold.  A @code{size} field of zero indicates no such limiting.  Systems
intern.texi(,234) which do not support limiting in this manner should ignore the
intern.texi(,235) @code{size} field.
intern.texi(,236) 
intern.texi(,237) @item @code{FIFOTYPE}
intern.texi(,238) This specifies a FIFO special file.  Note that the archiving of a
intern.texi(,239) FIFO file archives the existence of this file and not its contents.
intern.texi(,240) 
intern.texi(,241) @item @code{CONTTYPE}
intern.texi(,242) This specifies a contiguous file, which is the same as a normal
intern.texi(,243) file except that, in operating systems which support it, all its
intern.texi(,244) space is allocated contiguously on the disk.  Operating systems
intern.texi(,245) which do not allow contiguous allocation should silently treat this
intern.texi(,246) type as a normal file.
intern.texi(,247) 
intern.texi(,248) @item @code{A} @dots{} @code{Z}
intern.texi(,249) These are reserved for custom implementations.  Some of these are
intern.texi(,250) used in the @acronym{GNU} modified format, as described below.
intern.texi(,251) 
intern.texi(,252) @end table
intern.texi(,253) 
intern.texi(,254) Other values are reserved for specification in future revisions of
intern.texi(,255) the P1003 standard, and should not be used by any @command{tar} program.
intern.texi(,256) 
intern.texi(,257) The @code{magic} field indicates that this archive was output in
intern.texi(,258) the P1003 archive format.  If this field contains @code{TMAGIC},
intern.texi(,259) the @code{uname} and @code{gname} fields will contain the ASCII
intern.texi(,260) representation of the owner and group of the file respectively.
intern.texi(,261) If found, the user and group IDs are used rather than the values in
intern.texi(,262) the @code{uid} and @code{gid} fields.
intern.texi(,263) 
intern.texi(,264) For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
intern.texi(,265) 169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
intern.texi(,266) IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
intern.texi(,267) (section E.4.48) for @cite{pax - Portable archive interchange}.
intern.texi(,268) 
intern.texi(,269) @node Extensions
intern.texi(,270) @unnumberedsec @acronym{GNU} Extensions to the Archive Format
intern.texi(UNREVISED,271) @quotation
intern.texi(UNREVISED,271) @emph{(This message will disappear, once this node revised.)}
intern.texi(UNREVISED,271) @end quotation
intern.texi(,272) 
intern.texi(,273) The @acronym{GNU} format uses additional file types to describe new types of
intern.texi(,274) files in an archive.  These are listed below.
intern.texi(,275) 
intern.texi(,276) @table @code
intern.texi(,277) @item GNUTYPE_DUMPDIR
intern.texi(,278) @itemx 'D'
intern.texi(,279) This represents a directory and a list of files created by the
intern.texi(,280) @option{--incremental} (@option{-G}) option.  The @code{size} field gives the total
intern.texi(,281) size of the associated list of files.  Each file name is preceded by
intern.texi(,282) either a @samp{Y} (the file should be in this archive) or an @samp{N}.
intern.texi(,283) (The file is a directory, or is not stored in the archive.)  Each file
intern.texi(,284) name is terminated by a null.  There is an additional null after the
intern.texi(,285) last file name.
intern.texi(,286) 
intern.texi(,287) @item GNUTYPE_MULTIVOL
intern.texi(,288) @itemx 'M'
intern.texi(,289) This represents a file continued from another volume of a multi-volume
intern.texi(,290) archive created with the @option{--multi-volume} (@option{-M}) option.  The original
intern.texi(,291) type of the file is not given here.  The @code{size} field gives the
intern.texi(,292) maximum size of this piece of the file (assuming the volume does
intern.texi(,293) not end before the file is written out).  The @code{offset} field
intern.texi(,294) gives the offset from the beginning of the file where this part of
intern.texi(,295) the file begins.  Thus @code{size} plus @code{offset} should equal
intern.texi(,296) the original size of the file.
intern.texi(,297) 
intern.texi(,298) @item GNUTYPE_SPARSE
intern.texi(,299) @itemx 'S'
intern.texi(,300) This flag indicates that we are dealing with a sparse file.  Note
intern.texi(,301) that archiving a sparse file requires special operations to find
intern.texi(,302) holes in the file, which mark the positions of these holes, along
intern.texi(,303) with the number of bytes of data to be found after the hole.
intern.texi(,304) 
intern.texi(,305) @item GNUTYPE_VOLHDR
intern.texi(,306) @itemx 'V'
intern.texi(,307) This file type is used to mark the volume header that was given with
intern.texi(,308) the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option when the archive was created.  The @code{name}
intern.texi(,309) field contains the @code{name} given after the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option.
intern.texi(,310) The @code{size} field is zero.  Only the first file in each volume
intern.texi(,311) of an archive should have this type.
intern.texi(,312) 
intern.texi(,313) @end table
intern.texi(,314) 
intern.texi(,315) You may have trouble reading a @acronym{GNU} format archive on a
intern.texi(,316) non-@acronym{GNU} system if the options @option{--incremental} (@option{-G}),
intern.texi(,317) @option{--multi-volume} (@option{-M}), @option{--sparse} (@option{-S}), or @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) were
intern.texi(,318) used when writing the archive.  In general, if @command{tar} does not
intern.texi(,319) use the @acronym{GNU}-added fields of the header, other versions of
intern.texi(,320) @command{tar} should be able to read the archive.  Otherwise, the
intern.texi(,321) @command{tar} program will give an error, the most likely one being a
intern.texi(,322) checksum error.
intern.texi(,323) 
intern.texi(,324) @node Sparse Formats
intern.texi(,325) @unnumberedsec Storing Sparse Files
sparse.texi(,1) @c This is part of the paxutils manual.
sparse.texi(,2) @c Copyright (C) 2006 Free Software Foundation, Inc.
sparse.texi(,3) @c This file is distributed under GFDL 1.1 or any later version
sparse.texi(,4) @c published by the Free Software Foundation.
sparse.texi(,5) 
sparse.texi(,6) @cindex sparse formats
sparse.texi(,7) @cindex sparse versions
sparse.texi(,8) The notion of sparse file, and the ways of handling it from the point
sparse.texi(GNUTAR,9) of view of sparse.texi(GNUTAR,9) @acronym{GNU} @command{tar} user have been described in detail in
sparse.texi(GNUTAR,10) @ref{sparse}.  This chapter describes the internal format sparse.texi(GNUTAR,10) @acronym{GNU} @command{tar}
sparse.texi(,11) uses to store such files.
sparse.texi(,12) 
sparse.texi(GNUTAR,13) The support for sparse files in sparse.texi(GNUTAR,13) @acronym{GNU} @command{tar} has a long history.  The
sparse.texi(,14) earliest version featuring this support that I was able to find was 1.09,
sparse.texi(,15) released in November, 1990.  The format introduced back then is called
sparse.texi(,16) @dfn{old GNU} sparse format and in spite of the fact that its design
sparse.texi(GNUTAR,17) contained many flaws, it was the only format sparse.texi(GNUTAR,17) @acronym{GNU} @command{tar} supported 
sparse.texi(,18) until version 1.14 (May, 2004), which introduced initial support for
sparse.texi(,19) sparse archives in @acronym{PAX} archives (@pxref{posix}).  This
sparse.texi(,20) format was not free from design flows, either and it was subsequently
sparse.texi(,21) improved in versions 1.15.2 (November, 2005) and 1.15.92 (June,
sparse.texi(,22) 2006). 
sparse.texi(,23) 
sparse.texi(GNUTAR,24) In addition to GNU sparse format, sparse.texi(GNUTAR,24) @acronym{GNU} @command{tar} is able to read and
sparse.texi(,25) extract sparse files archived by @command{star}.
sparse.texi(,26) 
sparse.texi(,27) The following subsections describe each format in detail.
sparse.texi(,28) 
sparse.texi(,29) @menu
sparse.texi(,30) * Old GNU Format::
sparse.texi(,31) * PAX 0::                PAX Format, Versions 0.0 and 0.1
sparse.texi(,32) * PAX 1::                PAX Format, Version 1.0
sparse.texi(,33) @end menu
sparse.texi(,34) 
sparse.texi(,35) @node Old GNU Format
sparse.texi(,36) @appendixsubsec Old GNU Format
sparse.texi(,37) 
sparse.texi(,38) @cindex sparse formats, Old GNU
sparse.texi(,39) @cindex Old GNU sparse format
sparse.texi(,40) The format introduced some time around 1990 (v. 1.09).  It was
sparse.texi(,41) designed on top of standard @code{ustar} headers in such an
sparse.texi(,42) unfortunate way that some of its fields overwrote fields required by
sparse.texi(,43) POSIX.
sparse.texi(,44) 
sparse.texi(,45) An old GNU sparse header is designated by type @samp{S}
sparse.texi(,46) (@code{GNUTYPE_SPARSE}) and has the following layout:
sparse.texi(,47) 
sparse.texi(,48) @multitable @columnfractions 0.10 0.10 0.20 0.20 0.40
sparse.texi(,49) @headitem Offset @tab Size @tab Name   @tab Data type   @tab Contents
sparse.texi(,50) @item          0 @tab 345  @tab        @tab N/A         @tab Not used.
sparse.texi(,51) @item        345 @tab  12  @tab atime  @tab Number      @tab @code{atime} of the file.
sparse.texi(,52) @item        357 @tab  12  @tab ctime  @tab Number      @tab @code{ctime} of the file .
sparse.texi(,53) @item        369 @tab  12  @tab offset @tab Number      @tab For
sparse.texi(,54) multivolume archives: the offset of the start of this volume.
sparse.texi(,55) @item        381 @tab   4  @tab        @tab N/A         @tab Not used.
sparse.texi(,56) @item        385 @tab   1  @tab        @tab N/A         @tab Not used.
sparse.texi(,57) @item        386 @tab  96  @tab sp     @tab @code{sparse_header} @tab (4 entries) File map.
sparse.texi(,58) @item        482 @tab   1  @tab isextended @tab Bool        @tab @code{1} if an
sparse.texi(,59) extension sparse header follows, @code{0} otherwise.
sparse.texi(,60) @item        483 @tab  12  @tab realsize @tab Number      @tab Real size of the file.
sparse.texi(,61) @end multitable
sparse.texi(,62) 
sparse.texi(,63) Each of @code{sparse_header} object at offset 386 describes a single
sparse.texi(,64) data chunk. It has the following structure: 
sparse.texi(,65) 
sparse.texi(,66) @multitable @columnfractions 0.10 0.10 0.20 0.60
sparse.texi(,67) @headitem Offset @tab Size @tab Data type   @tab Contents
sparse.texi(,68) @item          0 @tab   12 @tab Number      @tab Offset of the
sparse.texi(,69) beginning of the chunk.
sparse.texi(,70) @item         12 @tab   12 @tab Number      @tab Size of the chunk.
sparse.texi(,71) @end multitable
sparse.texi(,72) 
sparse.texi(,73) If the member contains more than four chunks, the @code{isextended}
sparse.texi(,74) field of the header has the value @code{1} and the main header is
sparse.texi(,75) followed by one or more @dfn{extension headers}.  Each such header has
sparse.texi(,76) the following structure:
sparse.texi(,77) 
sparse.texi(,78) @multitable @columnfractions 0.10 0.10 0.20 0.20 0.40
sparse.texi(,79) @headitem Offset @tab Size @tab Name   @tab Data type   @tab Contents
sparse.texi(,80) @item          0 @tab   21 @tab sp     @tab @code{sparse_header} @tab
sparse.texi(,81) (21 entires) File map.
sparse.texi(,82) @item        504 @tab    1 @tab isextended @tab Bool    @tab @code{1} if an
sparse.texi(,83) extension sparse header follows, or @code{0} otherwise.
sparse.texi(,84) @end multitable
sparse.texi(,85) 
sparse.texi(,86) A header with @code{isextended=0} ends the map.
sparse.texi(,87) 
sparse.texi(,88) @node PAX 0
sparse.texi(,89) @appendixsubsec PAX Format, Versions 0.0 and 0.1
sparse.texi(,90) 
sparse.texi(,91) @cindex sparse formats, v.0.0
sparse.texi(,92) There are two formats available in this branch.  The version @code{0.0}
sparse.texi(,93) is the initial version of sparse format used by @command{tar}
sparse.texi(,94) versions 1.14--1.15.1.  The sparse file map is kept in extended
sparse.texi(,95) (@code{x}) PAX header variables:
sparse.texi(,96) 
sparse.texi(,97) @table @code
sparse.texi(,98) @vrindex GNU.sparse.size, extended header variable
sparse.texi(,99) @item GNU.sparse.size
sparse.texi(,100) Real size of the stored file
sparse.texi(,101) 
sparse.texi(,102) @item GNU.sparse.numblocks
sparse.texi(,103) @vrindex GNU.sparse.numblocks, extended header variable
sparse.texi(,104) Number of blocks in the sparse map
sparse.texi(,105) 
sparse.texi(,106) @item GNU.sparse.offset
sparse.texi(,107) @vrindex GNU.sparse.offset, extended header variable
sparse.texi(,108) Offset of the data block
sparse.texi(,109) 
sparse.texi(,110) @item GNU.sparse.numbytes
sparse.texi(,111) @vrindex GNU.sparse.numbytes, extended header variable
sparse.texi(,112) Size of the data block
sparse.texi(,113) @end table
sparse.texi(,114) 
sparse.texi(,115) The latter two variables repeat for each data block, so the overall
sparse.texi(,116) structure is like this:
sparse.texi(,117) 
sparse.texi(,118) @smallexample
sparse.texi(,119) @group
sparse.texi(,120) GNU.sparse.size=@var{size}      
sparse.texi(,121) GNU.sparse.numblocks=@var{numblocks} 
sparse.texi(,122) repeat @var{numblocks} times
sparse.texi(,123)   GNU.sparse.offset=@var{offset}    
sparse.texi(,124)   GNU.sparse.numbytes=@var{numbytes}  
sparse.texi(,125) end repeat
sparse.texi(,126) @end group
sparse.texi(,127) @end smallexample
sparse.texi(,128) 
sparse.texi(,129) This format presented the following two problems:
sparse.texi(,130) 
sparse.texi(,131) @enumerate 1
sparse.texi(,132) @item
sparse.texi(,133) Whereas the POSIX specification allows a variable to appear multiple
sparse.texi(,134) times in a header, it requires that only the last occurrence be
sparse.texi(,135) meaningful.  Thus, multiple ocurrences of @code{GNU.sparse.offset} and
sparse.texi(,136) @code{GNU.sparse.numbytes} are conficting with the POSIX specs.
sparse.texi(,137) 
sparse.texi(,138) @item
sparse.texi(,139) Attempting to extract such archives using a third-party @command{tar}s
sparse.texi(,140) results in extraction of sparse files in @emph{compressed form}.  If
sparse.texi(,141) the @command{tar} implementation in question does not support POSIX
sparse.texi(,142) format, it will also extract a file containing extension header
sparse.texi(,143) attributes.  This file can be used to expand the file to its original
sparse.texi(,144) state.  However, posix-aware @command{tar}s will usually ignore the
sparse.texi(,145) unknown variables, which makes restoring the file more
sparse.texi(,146) difficult.  @xref{extracting sparse v.0.x, Extraction of sparse
sparse.texi(,147) members in v.0.0 format}, for the detailed description of how to
sparse.texi(,148) restore such members using non-GNU @command{tar}s.
sparse.texi(,149) @end enumerate
sparse.texi(,150) 
sparse.texi(,151) @cindex sparse formats, v.0.1
sparse.texi(GNUTAR,152) @acronym{GNU} @command{tar} 1.15.2 introduced sparse format version @code{0.1}, which
sparse.texi(,153) attempted to solve these problems.  As its predecessor, this format
sparse.texi(,154) stores sparse map in the extended POSIX header.  It retains
sparse.texi(,155) @code{GNU.sparse.size} and @code{GNU.sparse.numblocks} variables, but
sparse.texi(,156) instead of @code{GNU.sparse.offset}/@code{GNU.sparse.numbytes} pairs
sparse.texi(,157) it uses a single variable:
sparse.texi(,158) 
sparse.texi(,159) @table @code
sparse.texi(,160) @item GNU.sparse.map
sparse.texi(,161) @vrindex GNU.sparse.map, extended header variable
sparse.texi(,162) Map of non-null data chunks.  It is a string consisting of
sparse.texi(,163) comma-separated values "@var{offset},@var{size}[,@var{offset-1},@var{size-1}...]" 
sparse.texi(,164) @end table
sparse.texi(,165) 
sparse.texi(,166) To address the 2nd problem, the @code{name} field in @code{ustar}
sparse.texi(,167) is replaced with a special name, constructed using the following pattern:
sparse.texi(,168) 
sparse.texi(,169) @smallexample
sparse.texi(,170) %d/GNUSparseFile.%p/%f
sparse.texi(,171) @end smallexample
sparse.texi(,172) 
sparse.texi(,173) @vrindex GNU.sparse.name, extended header variable
sparse.texi(,174) The real name of the sparse file is stored in the variable
sparse.texi(,175) @code{GNU.sparse.name}.  Thus, those @command{tar} implementations
sparse.texi(,176) that are not aware of GNU extensions will at least extract the files
sparse.texi(,177) into separate directories, giving the user a possibility to expand it
sparse.texi(,178) afterwards.  @xref{extracting sparse v.0.x, Extraction of sparse
sparse.texi(,179) members in v.0.1 format}, for the detailed description of how to
sparse.texi(,180) restore such members using non-GNU @command{tar}s.
sparse.texi(,181) 
sparse.texi(,182) The resulting @code{GNU.sparse.map} string can be @emph{very} long.
sparse.texi(,183) Although POSIX does not impose any limit on the length of a @code{x}
sparse.texi(,184) header variable, this possibly can confuse some tars.
sparse.texi(,185) 
sparse.texi(,186) @node PAX 1
sparse.texi(,187) @appendixsubsec PAX Format, Version 1.0
sparse.texi(,188) 
sparse.texi(,189) @cindex sparse formats, v.1.0
sparse.texi(GNUTAR,190) The version @code{1.0} of sparse format was introduced with sparse.texi(GNUTAR,190) @acronym{GNU} @command{tar}
sparse.texi(,191) 1.15.92.  Its main objective was to make the resulting file
sparse.texi(,192) extractable with little effort even by non-posix aware @command{tar}
sparse.texi(,193) implementations.  Starting from this version, the extended header
sparse.texi(,194) preceding a sparse member always contains the following variables that
sparse.texi(,195) identify the format being used:
sparse.texi(,196) 
sparse.texi(,197) @table @code
sparse.texi(,198) @item GNU.sparse.major
sparse.texi(,199) @vrindex GNU.sparse.major, extended header variable
sparse.texi(,200) Major version
sparse.texi(,201) 
sparse.texi(,202) @item GNU.sparse.minor
sparse.texi(,203) @vrindex GNU.sparse.minor, extended header variable
sparse.texi(,204) Minor version
sparse.texi(,205) @end table
sparse.texi(,206) 
sparse.texi(,207) The @code{name} field in @code{ustar} header contains a special name,
sparse.texi(,208) constructed using the following pattern:
sparse.texi(,209) 
sparse.texi(,210) @smallexample
sparse.texi(,211) %d/GNUSparseFile.%p/%f
sparse.texi(,212) @end smallexample
sparse.texi(,213) 
sparse.texi(,214) @vrindex GNU.sparse.name, extended header variable, in v.1.0
sparse.texi(,215) @vrindex GNU.sparse.realsize, extended header variable
sparse.texi(,216) The real name of the sparse file is stored in the variable
sparse.texi(,217) @code{GNU.sparse.name}.  The real size of the file is stored in the
sparse.texi(,218) variable @code{GNU.sparse.realsize}.
sparse.texi(,219) 
sparse.texi(,220) The sparse map itself is stored in the file data block, preceding the actual
sparse.texi(,221) file data.  It consists of a series of octal numbers of arbitrary length, delimited 
sparse.texi(,222) by newlines. The map is padded with nulls to the nearest block boundary.
sparse.texi(,223) 
sparse.texi(,224) The first number gives the number of entries in the map. Following are map entries,
sparse.texi(,225) each one consisting of two numbers giving the offset and size of the
sparse.texi(,226) data block it describes.
sparse.texi(,227) 
sparse.texi(,228) The format is designed in such a way that non-posix aware tars and tars not
sparse.texi(,229) supporting @code{GNU.sparse.*} keywords will extract each sparse file
sparse.texi(,230) in its condensed form with the file map prepended and will place it
sparse.texi(,231) into a separate directory.  Then, using a simple program it would be
sparse.texi(GNUTAR,232) possible to expand the file to its original form even without sparse.texi(GNUTAR,232) @acronym{GNU} @command{tar}.
sparse.texi(,233) @xref{Sparse Recovery}, for the detailed information on how to extract
sparse.texi(GNUTAR,234) sparse members without sparse.texi(GNUTAR,234) @acronym{GNU} @command{tar}.
sparse.texi(,235)  
intern.texi(,327) 
intern.texi(,328) @node Snapshot Files
intern.texi(,329) @unnumberedsec Format of the Incremental Snapshot Files
snapshot.texi(,1) @c This is part of the paxutils manual.
snapshot.texi(,2) @c Copyright (C) 2005 Free Software Foundation, Inc.
snapshot.texi(,3) @c Written by Sergey Poznyakoff
snapshot.texi(,4) @c This file is distributed under GFDL 1.1 or any later version
snapshot.texi(,5) @c published by the Free Software Foundation.
snapshot.texi(,6) 
snapshot.texi(,7)   A @dfn{snapshot file} (or @dfn{directory file}) is created during
snapshot.texi(,8) incremental backups (@pxref{Incremental Dumps}).  It
snapshot.texi(,9) contains the status of the filesystem at the time of the dump and is
snapshot.texi(,10) used to determine which files were modified since the last backup.
snapshot.texi(,11) 
snapshot.texi(GNUTAR,12)   snapshot.texi(GNUTAR,12) @acronym{GNU} @command{tar} version 1.15.92 supports two snapshot file
snapshot.texi(,13) formats.  The first format, called @dfn{format 0}, is the one used by
snapshot.texi(GNUTAR,14) @acronym{GNU} @command{tar} versions up to 1.15.1. The second format, called @dfn{format
snapshot.texi(,15) 1} is an extended version of this format, that contains more metadata
snapshot.texi(,16) and allows for further extensions.
snapshot.texi(,17) 
snapshot.texi(,18)   @samp{Format 0} snapshot file begins with a line containing a
snapshot.texi(,19) decimal number that represents the UNIX timestamp of the beginning of
snapshot.texi(,20) the last archivation. This line is followed by directory metadata
snapshot.texi(,21) descriptions, one per line. Each description has the following format:
snapshot.texi(,22) 
snapshot.texi(,23) @smallexample
snapshot.texi(,24) [@var{nfs}]@var{dev} @var{inode} @var{name}
snapshot.texi(,25) @end smallexample
snapshot.texi(,26) 
snapshot.texi(,27) @noindent
snapshot.texi(,28) where optional @var{nfs} is a single plus character (@samp{+}) if this
snapshot.texi(,29) directory is located on an NFS-mounted partition, @var{dev} and
snapshot.texi(,30) @var{inode} are the device and inode numbers of the directory, and
snapshot.texi(,31) @var{name} is the directory name.
snapshot.texi(,32) 
snapshot.texi(,33)   @samp{Format 1} snapshot file begins with a line specifying the
snapshot.texi(,34) format of the file. This line has the following structure:
snapshot.texi(,35) 
snapshot.texi(,36) @smallexample
snapshot.texi(,37) @samp{GNU tar-}@var{tar-version}@samp{-}@var{incr-format-version}
snapshot.texi(,38) @end smallexample
snapshot.texi(,39) 
snapshot.texi(,40) @noindent
snapshot.texi(GNUTAR,41) where @var{tar-version} is the version of snapshot.texi(GNUTAR,41) @acronym{GNU} @command{tar} implementation
snapshot.texi(,42) that created this snapshot, and @var{incr-format-version} is the
snapshot.texi(,43) version number of the snapshot format (in this case @samp{1}).
snapshot.texi(,44) 
snapshot.texi(,45)   The following line contains two decimal numbers, representing the
snapshot.texi(,46) time of the last backup. First number is the number of seconds, the
snapshot.texi(,47) second one is the number of nanoseconds, since the beginning of the
snapshot.texi(,48) epoch.
snapshot.texi(,49) 
snapshot.texi(,50)   Following lines contain directory metadate, one line per
snapshot.texi(,51) directory. The line format is:
snapshot.texi(,52) 
snapshot.texi(,53) @smallexample
snapshot.texi(,54) [@var{nfs}]@var{mtime-sec} @var{mtime-nsec} @var{dev} @var{inode} @var{name}
snapshot.texi(,55) @end smallexample
snapshot.texi(,56) 
snapshot.texi(,57) @noindent
snapshot.texi(,58) where @var{mtime-sec} and @var{mtime-nsec} represent the last
snapshot.texi(,59) modification time of this directory with nanosecond precision;
snapshot.texi(,60) @var{nfs}, @var{dev}, @var{inode} and @var{name} have the same meaning
snapshot.texi(,61) as with @samp{format 0}.
snapshot.texi(,62) 
snapshot.texi(,63) 
snapshot.texi(,64) @c End of snapshot.texi
snapshot.texi(,65) 
snapshot.texi(,66)   
intern.texi(,331) 
intern.texi(,332) @node Dumpdir
intern.texi(,333) @unnumberedsec Dumpdir
dumpdir.texi(,1) @c This is part of the paxutils manual.
dumpdir.texi(,2) @c Copyright (C) 2006 Free Software Foundation, Inc.
dumpdir.texi(,3) @c Written by Sergey Poznyakoff
dumpdir.texi(,4) @c This file is distributed under GFDL 1.1 or any later version
dumpdir.texi(,5) @c published by the Free Software Foundation.
dumpdir.texi(,6) 
dumpdir.texi(,7)   Incremental archives keep information about contents of each
dumpdir.texi(,8) dumped directory in special data blocks called @dfn{dumpdirs}.
dumpdir.texi(,9) 
dumpdir.texi(,10)   Dumpdir is a sequence of entries of the following form:
dumpdir.texi(,11) 
dumpdir.texi(,12) @smallexample
dumpdir.texi(,13) @var{C} @var{filename} \0
dumpdir.texi(,14) @end smallexample
dumpdir.texi(,15) 
dumpdir.texi(,16) @noindent
dumpdir.texi(,17) where @var{C} is one of the @dfn{control codes} described below,
dumpdir.texi(,18) @var{filename} is the name of the file @var{C} operates upon, and
dumpdir.texi(,19) @samp{\0} represents a nul character (ASCII 0).  The white space 
dumpdir.texi(,20) characters were added for readability, real dumpdirs do not contain
dumpdir.texi(,21) them.
dumpdir.texi(,22) 
dumpdir.texi(,23)   Each dumpdir ends with a single nul character.
dumpdir.texi(,24) 
dumpdir.texi(,25)   The following table describes control codes and their meanings:
dumpdir.texi(,26) 
dumpdir.texi(,27) @table @samp
dumpdir.texi(,28) @item Y
dumpdir.texi(,29) @var{filename} is contained in the archive.
dumpdir.texi(,30) 
dumpdir.texi(,31) @item N
dumpdir.texi(,32) @var{filename} was present in the directory at the time the archive
dumpdir.texi(,33) was made, yet it was not dumped to the archive, because it had not
dumpdir.texi(,34) changed since the last backup.
dumpdir.texi(,35) 
dumpdir.texi(,36) @item D
dumpdir.texi(,37) @var{filename} is a directory.
dumpdir.texi(,38) 
dumpdir.texi(,39) @item R
dumpdir.texi(,40) This code requests renaming of the @var{filename} to the name
dumpdir.texi(,41) specified with the following @samp{T} command.
dumpdir.texi(,42) 
dumpdir.texi(,43) @item T
dumpdir.texi(,44) Specify target file name for @samp{R} command (see below).
dumpdir.texi(,45) 
dumpdir.texi(,46) @item X
dumpdir.texi(,47) Specify @dfn{temporary directory} name for a rename operation (see below).
dumpdir.texi(,48) @end table
dumpdir.texi(,49) 
dumpdir.texi(,50)   Codes @samp{Y}, @samp{N} and @samp{D} require @var{filename} argument
dumpdir.texi(,51) to be a relative file name to the directory this dumpdir describes,
dumpdir.texi(,52) whereas codes @samp{R}, @samp{T} and @samp{X} require their argument
dumpdir.texi(,53) to be an absolute file name.
dumpdir.texi(,54) 
dumpdir.texi(,55)  The three codes @samp{R}, @samp{T} and @samp{X} specify a
dumpdir.texi(,56) @dfn{renaming operation}.  In the simplest case it is:
dumpdir.texi(,57) 
dumpdir.texi(,58) @smallexample
dumpdir.texi(,59) R@file{source}\0T@file{dest}\0
dumpdir.texi(,60) @end smallexample
dumpdir.texi(,61) 
dumpdir.texi(,62) @noindent
dumpdir.texi(,63) which means ``rename file @file{source} to file @file{dest}''.
dumpdir.texi(,64) 
dumpdir.texi(,65)   However, there are cases that require using a @dfn{temporary
dumpdir.texi(,66) directory}.  For example, consider the following scenario:
dumpdir.texi(,67) 
dumpdir.texi(,68) @enumerate 1
dumpdir.texi(,69) @item
dumpdir.texi(,70) Previous run dumped a directory @file{foo} which contained the
dumpdir.texi(,71) following three directories: 
dumpdir.texi(,72) 
dumpdir.texi(,73) @smallexample
dumpdir.texi(,74) a
dumpdir.texi(,75) b
dumpdir.texi(,76) c
dumpdir.texi(,77) @end smallexample
dumpdir.texi(,78) 
dumpdir.texi(,79) @item
dumpdir.texi(,80) They were renamed @emph{cyclically}, so that:
dumpdir.texi(,81) 
dumpdir.texi(,82) @example
dumpdir.texi(,83) @file{a} became @file{b}
dumpdir.texi(,84) @file{b} became @file{c}
dumpdir.texi(,85) @file{c} became @file{a}
dumpdir.texi(,86) @end example
dumpdir.texi(,87) 
dumpdir.texi(,88) @item
dumpdir.texi(,89) New incremental dump was made.
dumpdir.texi(,90) @end enumerate
dumpdir.texi(,91) 
dumpdir.texi(,92)   This case cannot be handled by three successive renames, since
dumpdir.texi(,93) renaming @file{a} to @file{b} will destroy existing directory.
dumpdir.texi(GNUTAR,94) To handle such case a temporary directory is required. dumpdir.texi(GNUTAR,94) @acronym{GNU} @command{tar}
dumpdir.texi(,95) will create the following dumpdir (newlines have been added for
dumpdir.texi(,96) readability): 
dumpdir.texi(,97) 
dumpdir.texi(,98) @smallexample
dumpdir.texi(,99) @group
dumpdir.texi(,100) Xfoo\0
dumpdir.texi(,101) Rfoo/a\0T\0
dumpdir.texi(,102) Rfoo/b\0Tfoo/c\0
dumpdir.texi(,103) Rfoo/c\0Tfoo/a\0
dumpdir.texi(,104) R\0Tfoo/a\0
dumpdir.texi(,105) @end group
dumpdir.texi(,106) @end smallexample
dumpdir.texi(,107) 
dumpdir.texi(,108)   The first command, @samp{Xfoo\0}, instructs the extractor to create a
dumpdir.texi(,109) temporary directory in the directory @file{foo}.  Second command,
dumpdir.texi(,110) @samp{Rfoo/aT\0}, says ``rename file @file{foo/a} to the temporary
dumpdir.texi(,111) directory that has just been created'' (empty file name after a
dumpdir.texi(,112) command means use temporary directory).  Third and fourth commands
dumpdir.texi(,113) work as usual, and, finally, the last command, @samp{R\0Tfoo/a\0}
dumpdir.texi(,114) tells tar to rename the temporary directory to @file{foo/a}.
dumpdir.texi(,115) 
dumpdir.texi(,116)   The exact placement of a dumpdir in the archive depends on the
dumpdir.texi(,117) archive format (@pxref{Formats}): 
dumpdir.texi(,118) 
dumpdir.texi(,119) @itemize
dumpdir.texi(,120) @item PAX archives
dumpdir.texi(,121) 
dumpdir.texi(,122) In PAX archives, dumpdir is stored in the extended header of the
dumpdir.texi(,123) corresponding directory, in variable @code{GNU.dumpdir}.
dumpdir.texi(,124) 
dumpdir.texi(,125) @item GNU and old GNU archives
dumpdir.texi(,126) 
dumpdir.texi(,127) These formats implement special header type @samp{D}, which is similar
dumpdir.texi(,128) to ustar header @samp{5} (directory), except that it preceeds a data
dumpdir.texi(,129) block containing the dumpdir.
dumpdir.texi(,130) @end itemize
dumpdir.texi(,131) 
dumpdir.texi(,132) @c End of dumpdir.texi
intern.texi(,335) 
tar.texi(,10777) 
tar.texi(,10778) @node Genfile
tar.texi(,10779) @appendix Genfile
genfile.texi(,1) @c This is part of the paxutils manual.
genfile.texi(,2) @c Copyright (C) 2005, 2006 Free Software Foundation, Inc.
genfile.texi(,3) @c Written by Sergey Poznyakoff
genfile.texi(,4) @c This file is distributed under GFDL 1.1 or any later version
genfile.texi(,5) @c published by the Free Software Foundation.
genfile.texi(,6) 
genfile.texi(,7) @cindex genfile
genfile.texi(,8)     This appendix describes @command{genfile}, an auxiliary program
genfile.texi(,9) used in the GNU tar testsuite. If you are not interested in developing
genfile.texi(,10) GNU tar, skip this appendix.
genfile.texi(,11) 
genfile.texi(,12)     Initially, @command{genfile} was used to generate data files for
genfile.texi(,13) the testsuite, hence its name. However, new operation modes were being
genfile.texi(,14) implemented as the testsuite grew more sophisticated, and now
genfile.texi(,15) @command{genfile} is a multi-purpose instrument.
genfile.texi(,16) 
genfile.texi(,17)     There are three basic operation modes:
genfile.texi(,18) 
genfile.texi(,19) @table @asis
genfile.texi(,20) @item File Generation
genfile.texi(,21)     This is the default mode. In this mode, @command{genfile}
genfile.texi(,22) generates data files.
genfile.texi(,23) 
genfile.texi(,24) @item File Status
genfile.texi(,25)     In this mode @command{genfile} displays status of specified files.
genfile.texi(,26) 
genfile.texi(,27) @item Synchronous Execution.
genfile.texi(,28)     In this mode @command{genfile} executes the given program with
genfile.texi(,29) @option{--checkpoint} option and executes a set of actions when
genfile.texi(,30) specified checkpoints are reached.
genfile.texi(,31) @end table
genfile.texi(,32) 
genfile.texi(,33) @menu
genfile.texi(,34) * Generate Mode::     File Generation Mode.
genfile.texi(,35) * Status Mode::       File Status Mode.
genfile.texi(,36) * Exec Mode::         Synchronous Execution mode.
genfile.texi(,37) @end menu
genfile.texi(,38) 
genfile.texi(,39) @node Generate Mode
genfile.texi(,40) @appendixsec Generate Mode
genfile.texi(,41) 
genfile.texi(,42) @cindex Generate Mode, @command{genfile}
genfile.texi(,43) @cindex @command{genfile}, generate mode
genfile.texi(,44) @cindex @command{genfile}, create file
genfile.texi(,45)     In this mode @command{genfile} creates a data file for the test
genfile.texi(,46) suite. The size of the file is given with the @option{--length}
genfile.texi(,47) (@option{-l}) option. By default the file contents is written to the
genfile.texi(,48) standard output, this can be changed using @option{--file}
genfile.texi(,49) (@option{-f}) command line option. Thus, the following two commands
genfile.texi(,50) are equivalent:
genfile.texi(,51) 
genfile.texi(,52) @smallexample
genfile.texi(,53) @group
genfile.texi(,54) genfile --length 100 > outfile
genfile.texi(,55) genfile --length 100 --file outfile
genfile.texi(,56) @end group
genfile.texi(,57) @end smallexample
genfile.texi(,58) 
genfile.texi(,59)     If @option{--length} is not given, @command{genfile} will
genfile.texi(,60) generate an empty (zero-length) file.
genfile.texi(,61) 
genfile.texi(,62) @cindex @command{genfile}, reading a list of file names
genfile.texi(,63)     You can instruct @command{genfile} to create several files at one
genfile.texi(,64) go, by giving it @option{--files-from} (@option{-T}) option followed
genfile.texi(,65) by a name of file containing a list of file names. Using dash
genfile.texi(,66) (@samp{-}) instead of the file name causes @command{genfile} to read
genfile.texi(,67) file list from the standard input. For example:
genfile.texi(,68) 
genfile.texi(,69) @smallexample
genfile.texi(,70) @group
genfile.texi(,71) # Read file names from file @file{file.list}
genfile.texi(,72) genfile --files-from file.list
genfile.texi(,73) # Read file names from standard input
genfile.texi(,74) genfile --files-from -
genfile.texi(,75) @end group
genfile.texi(,76) @end smallexample
genfile.texi(,77) 
genfile.texi(,78) @cindex File lists separated by NUL characters
genfile.texi(,79)     The list file is supposed to contain one file name per line. To
genfile.texi(,80) use file lists separated by ASCII NUL character, use @option{--null}
genfile.texi(,81) (@option{-0}) command line option:
genfile.texi(,82) 
genfile.texi(,83) @smallexample
genfile.texi(,84) genfile --null --files-from file.list
genfile.texi(,85) @end smallexample
genfile.texi(,86) 
genfile.texi(,87) @cindex pattern, @command{genfile}
genfile.texi(,88)     The default data pattern for filling the generated file consists
genfile.texi(,89) of first 256 letters of ASCII code, repeated enough times to fill the
genfile.texi(,90) entire file. This behavior can be changed with @option{--pattern}
genfile.texi(,91) option. This option takes a mandatory argument, specifying pattern
genfile.texi(,92) name to use. Currently two patterns are implemented:
genfile.texi(,93) 
genfile.texi(,94) @table @option
genfile.texi(,95) @item --pattern=default
genfile.texi(,96)     The default pattern as described above.
genfile.texi(,97) 
genfile.texi(,98) @item --pattern=zero
genfile.texi(,99)     Fills the file with zeroes.
genfile.texi(,100) @end table
genfile.texi(,101) 
genfile.texi(,102)     If no file name was given, the program exits with the code
genfile.texi(,103) @code{0}.  Otherwise, it exits with @code{0} only if it was able to
genfile.texi(,104) create a file of the specified length.
genfile.texi(,105)     
genfile.texi(,106) @cindex Sparse files, creating using @command{genfile}
genfile.texi(,107) @cindex @command{genfile}, creating sparse files
genfile.texi(,108)     Special option @option{--sparse} (@option{-s}) instructs
genfile.texi(,109) @command{genfile} to create a sparse file. Sparse files consist of
genfile.texi(,110) @dfn{data fragments}, separated by @dfn{holes} or blocks of zeros. On
genfile.texi(,111) many operating systems, actual disk storage is not allocated for
genfile.texi(,112) holes, but they are counted in the length of the file. To create a
genfile.texi(,113) sparse file, @command{genfile} should know where to put data fragments,
genfile.texi(,114) and what data to use to fill them. So, when @option{--sparse} is given
genfile.texi(,115) the rest of the command line specifies a so-called @dfn{file map}.
genfile.texi(,116) 
genfile.texi(,117)     The file map consists of any number of @dfn{fragment
genfile.texi(,118) descriptors}. Each descriptor is composed of two values: a number,
genfile.texi(,119) specifying fragment offset from the end of the previous fragment or,
genfile.texi(,120) for the very first fragment, from the beginning of the file, and
genfile.texi(,121) @dfn{contents string}, i.e. a string of characters, specifying the
genfile.texi(,122) pattern to fill the fragment with. File offset can be suffixed with
genfile.texi(,123) the following quantifiers:
genfile.texi(,124) 
genfile.texi(,125) @table @samp
genfile.texi(,126) @item k
genfile.texi(,127) @itemx K
genfile.texi(,128) The number is expressed in kilobytes.
genfile.texi(,129) @item m
genfile.texi(,130) @itemx M
genfile.texi(,131) The number is expressed in megabytes.
genfile.texi(,132) @item g
genfile.texi(,133) @itemx G
genfile.texi(,134) The number is expressed in gigabytes.
genfile.texi(,135) @end table
genfile.texi(,136) 
genfile.texi(,137)     For each letter in contents string @command{genfile} will generate
genfile.texi(,138) a @dfn{block} of data, filled with this letter and will write it to
genfile.texi(,139) the fragment. The size of block is given by @option{--block-size}
genfile.texi(,140) option. It defaults to 512. Thus, if the string consists of @var{n}
genfile.texi(,141) characters, the resulting file fragment will contain
genfile.texi(,142) @code{@var{n}*@var{block-size}} of data. 
genfile.texi(,143) 
genfile.texi(,144)     Last fragment descriptor can have only file offset part. In this
genfile.texi(,145) case @command{genfile} will create a hole at the end of the file up to
genfile.texi(,146) the given offset.
genfile.texi(,147) 
genfile.texi(,148)     For example, consider the following invocation:
genfile.texi(,149) 
genfile.texi(,150) @smallexample
genfile.texi(,151) genfile --sparse --file sparsefile 0 ABCD 1M EFGHI 2000K 
genfile.texi(,152) @end smallexample
genfile.texi(,153) 
genfile.texi(,154) @noindent
genfile.texi(,155) It will create 3101184-bytes long file of the following structure:
genfile.texi(,156) 
genfile.texi(,157) @multitable @columnfractions .35 .20 .45
genfile.texi(,158) @item Offset  @tab Length       @tab Contents
genfile.texi(,159) @item 0       @tab 4*512=2048   @tab Four 512-byte blocks, filled with
genfile.texi(,160) letters @samp{A}, @samp{B}, @samp{C} and @samp{D}.
genfile.texi(,161) @item 2048    @tab 1046528      @tab Zero bytes 
genfile.texi(,162) @item 1050624 @tab 5*512=2560   @tab Five blocks, filled with letters
genfile.texi(,163) @samp{E}, @samp{F}, @samp{G}, @samp{H}, @samp{I}.
genfile.texi(,164) @item 1053184  @tab 2048000     @tab Zero bytes
genfile.texi(,165) @end multitable
genfile.texi(,166) 
genfile.texi(,167)     The exit code of @command{genfile --status} command is @code{0}
genfile.texi(,168) only if created file is actually sparse.
genfile.texi(,169)     
genfile.texi(,170) @node Status Mode
genfile.texi(,171) @appendixsec Status Mode
genfile.texi(,172) 
genfile.texi(,173)     In status mode, @command{genfile} prints file system status for
genfile.texi(,174) each file specified in the command line. This mode is toggled by
genfile.texi(,175) @option{--stat} (@option{-S}) command line option. An optional argument to this
genfile.texi(,176) option specifies output @dfn{format}: a comma-separated list of
genfile.texi(,177) @code{struct stat} fields to be displayed. This list can contain
genfile.texi(FIXME,179) following identifiers genfile.texi(FIXME,179) @allow-recursion
genfile.texi(FIXME,179) @quote-arg
genfile.texi(FIXME,179) :
genfile.texi(,180) 
genfile.texi(,181) @table @asis
genfile.texi(,182) @item name
genfile.texi(,183)     The file name.
genfile.texi(,184)     
genfile.texi(,185) @item dev
genfile.texi(,186) @itemx st_dev
genfile.texi(,187)     Device number in decimal.
genfile.texi(,188)     
genfile.texi(,189) @item ino
genfile.texi(,190) @itemx st_ino
genfile.texi(,191)     Inode number.
genfile.texi(,192)     
genfile.texi(,193) @item mode[.@var{number}]
genfile.texi(,194) @itemx st_mode[.@var{number}]
genfile.texi(,195)     File mode in octal.  Optional @var{number} specifies octal mask to
genfile.texi(,196) be applied to the mode before outputting.  For example, @code{--stat
genfile.texi(,197) mode.777} will preserve lower nine bits of it.  Notice, that you can
genfile.texi(,198) use any punctuation caracter in place of @samp{.}.
genfile.texi(,199)     
genfile.texi(,200) @item nlink
genfile.texi(,201) @itemx st_nlink
genfile.texi(,202)     Number of hard links.
genfile.texi(,203)     
genfile.texi(,204) @item uid
genfile.texi(,205) @itemx st_uid
genfile.texi(,206)     User ID of owner.
genfile.texi(,207)     
genfile.texi(,208) @item gid
genfile.texi(,209) @itemx st_gid
genfile.texi(,210)     Group ID of owner.
genfile.texi(,211)     
genfile.texi(,212) @item size
genfile.texi(,213) @itemx st_size
genfile.texi(,214)     File size in decimal.
genfile.texi(,215)     
genfile.texi(,216) @item blksize
genfile.texi(,217) @itemx st_blksize
genfile.texi(,218)     The size in bytes of each file block.
genfile.texi(,219)     
genfile.texi(,220) @item blocks
genfile.texi(,221) @itemx st_blocks
genfile.texi(,222)     Number of blocks allocated.
genfile.texi(,223)      
genfile.texi(,224) @item atime
genfile.texi(,225) @itemx st_atime
genfile.texi(,226)     Time of last access.
genfile.texi(,227)     
genfile.texi(,228) @item mtime
genfile.texi(,229) @itemx st_mtime
genfile.texi(,230)     Time of last modification
genfile.texi(,231) 
genfile.texi(,232) @item ctime
genfile.texi(,233) @itemx st_ctime
genfile.texi(,234)     Time of last status change
genfile.texi(,235) 
genfile.texi(,236) @item sparse
genfile.texi(,237)     A boolean value indicating whether the file is @samp{sparse}.     
genfile.texi(,238) @end table
genfile.texi(,239) 
genfile.texi(,240)     Modification times are displayed in @acronym{UTC} as
genfile.texi(,241) @acronym{UNIX} timestamps, unless suffixed with @samp{H} (for
genfile.texi(,242) ``human-readable''), as in @samp{ctimeH}, in which case usual
genfile.texi(,243) @code{tar tv} output format is used.
genfile.texi(,244) 
genfile.texi(,245)     The default output format is: @samp{name,dev,ino,mode,
genfile.texi(,246) nlink,uid,gid,size,blksize,blocks,atime,mtime,ctime}. 
genfile.texi(,247) 
genfile.texi(,248)     For example, the following command will display file names and
genfile.texi(,249) corresponding times of last access for each file in the current working
genfile.texi(,250) directory:
genfile.texi(,251) 
genfile.texi(,252) @smallexample
genfile.texi(,253) genfile --stat=name,atime *
genfile.texi(,254) @end smallexample
genfile.texi(,255) 
genfile.texi(,256) @node Exec Mode
genfile.texi(,257) @appendixsec Exec Mode
genfile.texi(,258) 
genfile.texi(,259) @cindex Exec Mode, @command{genfile}
genfile.texi(,260)     This mode is designed for testing the behavior of @code{paxutils}
genfile.texi(,261) commands when some of the files change during archiving. It is an
genfile.texi(,262) experimental mode.
genfile.texi(,263) 
genfile.texi(,264)     The @samp{Exec Mode} is toggled by @option{--run} command line
genfile.texi(,265) option (or its alias @option{-r}). The argument to this option gives
genfile.texi(,266) the command line to be executed. The actual command line is
genfile.texi(,267) constructed by inserting @option{--checkpoint} option between the
genfile.texi(,268) command name and its first argument (if any). Due to this, the
genfile.texi(,269) argument to @option{--run} may not use traditional @command{tar}
genfile.texi(,270) option syntax, i.e. the following is wrong: 
genfile.texi(,271) 
genfile.texi(,272) @smallexample
genfile.texi(,273) # Wrong!
genfile.texi(,274) genfile --run 'tar cf foo bar'
genfile.texi(,275) @end smallexample
genfile.texi(,276) 
genfile.texi(,277) @noindent
genfile.texi(,278) 
genfile.texi(,279) Use the following syntax instead:
genfile.texi(,280) 
genfile.texi(,281) @smallexample
genfile.texi(,282) genfile --run 'tar -cf foo bar'
genfile.texi(,283) @end smallexample
genfile.texi(,284) 
genfile.texi(,285)     The rest of command line after @option{--run} or its equivalent
genfile.texi(,286) specifies checkpoint values and actions to be executed upon reaching
genfile.texi(,287) them. Checkpoint values are introduced with @option{--checkpoint}
genfile.texi(,288) command line option. Argument to this option is the number of
genfile.texi(,289) checkpoint in decimal.
genfile.texi(,290) 
genfile.texi(,291)     Any number of @dfn{actions} may be specified after a
genfile.texi(,292) checkpoint. Available actions are
genfile.texi(,293) 
genfile.texi(,294) @table @option
genfile.texi(,295) @item --cut @var{file}
genfile.texi(,296) @itemx --truncate @var{file}
genfile.texi(,297)     Truncate @var{file} to the size specified by previous
genfile.texi(,298) @option{--length} option (or 0, if it is not given).
genfile.texi(,299)     
genfile.texi(,300) @item --append @var{file}
genfile.texi(,301)     Append data to @var{file}. The size of data and its pattern are
genfile.texi(,302) given by previous @option{--length} and @option{pattern} options.
genfile.texi(,303) 
genfile.texi(,304) @item --touch @var{file}
genfile.texi(,305)     Update the access and modification times of @var{file}. These
genfile.texi(,306) timestamps are changed to the current time, unless @option{--date}
genfile.texi(,307) option was given, in which case they are changed to the specified
genfile.texi(,308) time. Argument to @option{--date} option is a date specification in
genfile.texi(,309) an almost arbitrary format (@pxref{Date input formats}).
genfile.texi(,310) 
genfile.texi(,311) @item --exec @var{command}
genfile.texi(,312)     Execute given shell command.
genfile.texi(,313)     
genfile.texi(,314) @end table
genfile.texi(,315) 
genfile.texi(,316)     Option @option{--verbose} instructs @command{genfile} to print on
genfile.texi(,317) standard output notifications about checkpoints being executed and to
genfile.texi(,318) verbosely describe exit status of the command.
genfile.texi(,319) 
genfile.texi(,320)     While the command is being executed its standard output remains
genfile.texi(,321) connected to descriptor 1. All messages it prints to file descriptor
genfile.texi(,322) 2, except checkpoint notifications, are forwarded to standard
genfile.texi(,323) error.
genfile.texi(,324) 
genfile.texi(,325)     @command{Genfile} exits with the exit status of the executed command.
tar.texi(,10781) 
tar.texi(,10782) @node Free Software Needs Free Documentation
tar.texi(,10783) @appendix Free Software Needs Free Documentation
freemanuals.texi(,1) @cindex free documentation
freemanuals.texi(,2) 
freemanuals.texi(,3) The biggest deficiency in the free software community today is not in
freemanuals.texi(,4) the software---it is the lack of good free documentation that we can
freemanuals.texi(,5) include with the free software.  Many of our most important
freemanuals.texi(,6) programs do not come with free reference manuals and free introductory
freemanuals.texi(,7) texts.  Documentation is an essential part of any software package;
freemanuals.texi(,8) when an important free software package does not come with a free
freemanuals.texi(,9) manual and a free tutorial, that is a major gap.  We have many such
freemanuals.texi(,10) gaps today.
freemanuals.texi(,11) 
freemanuals.texi(,12) Consider Perl, for instance.  The tutorial manuals that people
freemanuals.texi(,13) normally use are non-free.  How did this come about?  Because the
freemanuals.texi(,14) authors of those manuals published them with restrictive terms---no
freemanuals.texi(,15) copying, no modification, source files not available---which exclude
freemanuals.texi(,16) them from the free software world.
freemanuals.texi(,17) 
freemanuals.texi(,18) That wasn't the first time this sort of thing happened, and it was far
freemanuals.texi(,19) from the last.  Many times we have heard a GNU user eagerly describe a
freemanuals.texi(,20) manual that he is writing, his intended contribution to the community,
freemanuals.texi(,21) only to learn that he had ruined everything by signing a publication
freemanuals.texi(,22) contract to make it non-free.
freemanuals.texi(,23) 
freemanuals.texi(,24) Free documentation, like free software, is a matter of freedom, not
freemanuals.texi(,25) price.  The problem with the non-free manual is not that publishers
freemanuals.texi(,26) charge a price for printed copies---that in itself is fine.  (The Free
freemanuals.texi(,27) Software Foundation sells printed copies of manuals, too.)  The
freemanuals.texi(,28) problem is the restrictions on the use of the manual.  Free manuals
freemanuals.texi(,29) are available in source code form, and give you permission to copy and
freemanuals.texi(,30) modify.  Non-free manuals do not allow this.
freemanuals.texi(,31) 
freemanuals.texi(,32) The criteria of freedom for a free manual are roughly the same as for
freemanuals.texi(,33) free software.  Redistribution (including the normal kinds of
freemanuals.texi(,34) commercial redistribution) must be permitted, so that the manual can
freemanuals.texi(,35) accompany every copy of the program, both on-line and on paper.
freemanuals.texi(,36) 
freemanuals.texi(,37) Permission for modification of the technical content is crucial too.
freemanuals.texi(,38) When people modify the software, adding or changing features, if they
freemanuals.texi(,39) are conscientious they will change the manual too---so they can
freemanuals.texi(,40) provide accurate and clear documentation for the modified program.  A
freemanuals.texi(,41) manual that leaves you no choice but to write a new manual to document
freemanuals.texi(,42) a changed version of the program is not really available to our
freemanuals.texi(,43) community.
freemanuals.texi(,44) 
freemanuals.texi(,45) Some kinds of limits on the way modification is handled are
freemanuals.texi(,46) acceptable.  For example, requirements to preserve the original
freemanuals.texi(,47) author's copyright notice, the distribution terms, or the list of
freemanuals.texi(,48) authors, are ok.  It is also no problem to require modified versions
freemanuals.texi(,49) to include notice that they were modified.  Even entire sections that
freemanuals.texi(,50) may not be deleted or changed are acceptable, as long as they deal
freemanuals.texi(,51) with nontechnical topics (like this one).  These kinds of restrictions
freemanuals.texi(,52) are acceptable because they don't obstruct the community's normal use
freemanuals.texi(,53) of the manual.
freemanuals.texi(,54) 
freemanuals.texi(,55) However, it must be possible to modify all the @emph{technical}
freemanuals.texi(,56) content of the manual, and then distribute the result in all the usual
freemanuals.texi(,57) media, through all the usual channels.  Otherwise, the restrictions
freemanuals.texi(,58) obstruct the use of the manual, it is not free, and we need another
freemanuals.texi(,59) manual to replace it.
freemanuals.texi(,60) 
freemanuals.texi(,61) Please spread the word about this issue.  Our community continues to
freemanuals.texi(,62) lose manuals to proprietary publishing.  If we spread the word that
freemanuals.texi(,63) free software needs free reference manuals and free tutorials, perhaps
freemanuals.texi(,64) the next person who wants to contribute by writing documentation will
freemanuals.texi(,65) realize, before it is too late, that only free manuals contribute to
freemanuals.texi(,66) the free software community.
freemanuals.texi(,67) 
freemanuals.texi(,68) If you are writing documentation, please insist on publishing it under
freemanuals.texi(,69) the GNU Free Documentation License or another free documentation
freemanuals.texi(,70) license.  Remember that this decision requires your approval---you
freemanuals.texi(,71) don't have to let the publisher decide.  Some commercial publishers
freemanuals.texi(,72) will use a free license if you insist, but they will not propose the
freemanuals.texi(,73) option; it is up to you to raise the issue and say firmly that this is
freemanuals.texi(,74) what you want.  If the publisher you are dealing with refuses, please
freemanuals.texi(,75) try other publishers.  If you're not sure whether a proposed license
freemanuals.texi(,76) is free, write to @email{licensing@@gnu.org}.
freemanuals.texi(,77) 
freemanuals.texi(,78) You can encourage commercial publishers to sell more free, copylefted
freemanuals.texi(,79) manuals and tutorials by buying them, and particularly by buying
freemanuals.texi(,80) copies from the publishers that paid for their writing or for major
freemanuals.texi(,81) improvements.  Meanwhile, try to avoid buying non-free documentation
freemanuals.texi(,82) at all.  Check the distribution terms of a manual before you buy it,
freemanuals.texi(,83) and insist that whoever seeks your business must respect your freedom.
freemanuals.texi(,84) Check the history of the book, and try reward the publishers that have
freemanuals.texi(,85) paid or pay the authors to work on it.
freemanuals.texi(,86) 
freemanuals.texi(,87) The Free Software Foundation maintains a list of free documentation
freemanuals.texi(,88) published by other publishers, at
freemanuals.texi(,89) @url{http://www.fsf.org/doc/other-free-books.html}.
tar.texi(,10785) 
tar.texi(,10786) @node Copying This Manual
tar.texi(,10787) @appendix Copying This Manual
tar.texi(,10788) 
tar.texi(,10789) @menu
tar.texi(,10790) * GNU Free Documentation License::  License for copying this manual
tar.texi(,10791) @end menu
tar.texi(,10792) 
fdl.texi(,1) 
fdl.texi(,2) @node GNU Free Documentation License
fdl.texi(,3) @appendixsec GNU Free Documentation License
fdl.texi(,4) 
fdl.texi(,5) @cindex FDL, GNU Free Documentation License
fdl.texi(,6) @center Version 1.2, November 2002
fdl.texi(,7) 
fdl.texi(,8) @display
fdl.texi(,9) Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc.
fdl.texi(,10) 51 Franklin St, Fifth Floor, Boston, MA  02110-1301, USA
fdl.texi(,11) 
fdl.texi(,12) Everyone is permitted to copy and distribute verbatim copies
fdl.texi(,13) of this license document, but changing it is not allowed.
fdl.texi(,14) @end display
fdl.texi(,15) 
fdl.texi(,16) @enumerate 0
fdl.texi(,17) @item
fdl.texi(,18) PREAMBLE
fdl.texi(,19) 
fdl.texi(,20) The purpose of this License is to make a manual, textbook, or other
fdl.texi(,21) functional and useful document @dfn{free} in the sense of freedom: to
fdl.texi(,22) assure everyone the effective freedom to copy and redistribute it,
fdl.texi(,23) with or without modifying it, either commercially or noncommercially.
fdl.texi(,24) Secondarily, this License preserves for the author and publisher a way
fdl.texi(,25) to get credit for their work, while not being considered responsible
fdl.texi(,26) for modifications made by others.
fdl.texi(,27) 
fdl.texi(,28) This License is a kind of ``copyleft'', which means that derivative
fdl.texi(,29) works of the document must themselves be free in the same sense.  It
fdl.texi(,30) complements the GNU General Public License, which is a copyleft
fdl.texi(,31) license designed for free software.
fdl.texi(,32) 
fdl.texi(,33) We have designed this License in order to use it for manuals for free
fdl.texi(,34) software, because free software needs free documentation: a free
fdl.texi(,35) program should come with manuals providing the same freedoms that the
fdl.texi(,36) software does.  But this License is not limited to software manuals;
fdl.texi(,37) it can be used for any textual work, regardless of subject matter or
fdl.texi(,38) whether it is published as a printed book.  We recommend this License
fdl.texi(,39) principally for works whose purpose is instruction or reference.
fdl.texi(,40) 
fdl.texi(,41) @item
fdl.texi(,42) APPLICABILITY AND DEFINITIONS
fdl.texi(,43) 
fdl.texi(,44) This License applies to any manual or other work, in any medium, that
fdl.texi(,45) contains a notice placed by the copyright holder saying it can be
fdl.texi(,46) distributed under the terms of this License.  Such a notice grants a
fdl.texi(,47) world-wide, royalty-free license, unlimited in duration, to use that
fdl.texi(,48) work under the conditions stated herein.  The ``Document'', below,
fdl.texi(,49) refers to any such manual or work.  Any member of the public is a
fdl.texi(,50) licensee, and is addressed as ``you''.  You accept the license if you
fdl.texi(,51) copy, modify or distribute the work in a way requiring permission
fdl.texi(,52) under copyright law.
fdl.texi(,53) 
fdl.texi(,54) A ``Modified Version'' of the Document means any work containing the
fdl.texi(,55) Document or a portion of it, either copied verbatim, or with
fdl.texi(,56) modifications and/or translated into another language.
fdl.texi(,57) 
fdl.texi(,58) A ``Secondary Section'' is a named appendix or a front-matter section
fdl.texi(,59) of the Document that deals exclusively with the relationship of the
fdl.texi(,60) publishers or authors of the Document to the Document's overall
fdl.texi(,61) subject (or to related matters) and contains nothing that could fall
fdl.texi(,62) directly within that overall subject.  (Thus, if the Document is in
fdl.texi(,63) part a textbook of mathematics, a Secondary Section may not explain
fdl.texi(,64) any mathematics.)  The relationship could be a matter of historical
fdl.texi(,65) connection with the subject or with related matters, or of legal,
fdl.texi(,66) commercial, philosophical, ethical or political position regarding
fdl.texi(,67) them.
fdl.texi(,68) 
fdl.texi(,69) The ``Invariant Sections'' are certain Secondary Sections whose titles
fdl.texi(,70) are designated, as being those of Invariant Sections, in the notice
fdl.texi(,71) that says that the Document is released under this License.  If a
fdl.texi(,72) section does not fit the above definition of Secondary then it is not
fdl.texi(,73) allowed to be designated as Invariant.  The Document may contain zero
fdl.texi(,74) Invariant Sections.  If the Document does not identify any Invariant
fdl.texi(,75) Sections then there are none.
fdl.texi(,76) 
fdl.texi(,77) The ``Cover Texts'' are certain short passages of text that are listed,
fdl.texi(,78) as Front-Cover Texts or Back-Cover Texts, in the notice that says that
fdl.texi(,79) the Document is released under this License.  A Front-Cover Text may
fdl.texi(,80) be at most 5 words, and a Back-Cover Text may be at most 25 words.
fdl.texi(,81) 
fdl.texi(,82) A ``Transparent'' copy of the Document means a machine-readable copy,
fdl.texi(,83) represented in a format whose specification is available to the
fdl.texi(,84) general public, that is suitable for revising the document
fdl.texi(,85) straightforwardly with generic text editors or (for images composed of
fdl.texi(,86) pixels) generic paint programs or (for drawings) some widely available
fdl.texi(,87) drawing editor, and that is suitable for input to text formatters or
fdl.texi(,88) for automatic translation to a variety of formats suitable for input
fdl.texi(,89) to text formatters.  A copy made in an otherwise Transparent file
fdl.texi(,90) format whose markup, or absence of markup, has been arranged to thwart
fdl.texi(,91) or discourage subsequent modification by readers is not Transparent.
fdl.texi(,92) An image format is not Transparent if used for any substantial amount
fdl.texi(,93) of text.  A copy that is not ``Transparent'' is called ``Opaque''.
fdl.texi(,94) 
fdl.texi(,95) Examples of suitable formats for Transparent copies include plain
fdl.texi(,96) @sc{ascii} without markup, Texinfo input format, La@TeX{} input
fdl.texi(,97) format, @acronym{SGML} or @acronym{XML} using a publicly available
fdl.texi(,98) @acronym{DTD}, and standard-conforming simple @acronym{HTML},
fdl.texi(,99) PostScript or @acronym{PDF} designed for human modification.  Examples
fdl.texi(,100) of transparent image formats include @acronym{PNG}, @acronym{XCF} and
fdl.texi(,101) @acronym{JPG}.  Opaque formats include proprietary formats that can be
fdl.texi(,102) read and edited only by proprietary word processors, @acronym{SGML} or
fdl.texi(,103) @acronym{XML} for which the @acronym{DTD} and/or processing tools are
fdl.texi(,104) not generally available, and the machine-generated @acronym{HTML},
fdl.texi(,105) PostScript or @acronym{PDF} produced by some word processors for
fdl.texi(,106) output purposes only.
fdl.texi(,107) 
fdl.texi(,108) The ``Title Page'' means, for a printed book, the title page itself,
fdl.texi(,109) plus such following pages as are needed to hold, legibly, the material
fdl.texi(,110) this License requires to appear in the title page.  For works in
fdl.texi(,111) formats which do not have any title page as such, ``Title Page'' means
fdl.texi(,112) the text near the most prominent appearance of the work's title,
fdl.texi(,113) preceding the beginning of the body of the text.
fdl.texi(,114) 
fdl.texi(,115) A section ``Entitled XYZ'' means a named subunit of the Document whose
fdl.texi(,116) title either is precisely XYZ or contains XYZ in parentheses following
fdl.texi(,117) text that translates XYZ in another language.  (Here XYZ stands for a
fdl.texi(,118) specific section name mentioned below, such as ``Acknowledgements'',
fdl.texi(,119) ``Dedications'', ``Endorsements'', or ``History''.)  To ``Preserve the Title''
fdl.texi(,120) of such a section when you modify the Document means that it remains a
fdl.texi(,121) section ``Entitled XYZ'' according to this definition.
fdl.texi(,122) 
fdl.texi(,123) The Document may include Warranty Disclaimers next to the notice which
fdl.texi(,124) states that this License applies to the Document.  These Warranty
fdl.texi(,125) Disclaimers are considered to be included by reference in this
fdl.texi(,126) License, but only as regards disclaiming warranties: any other
fdl.texi(,127) implication that these Warranty Disclaimers may have is void and has
fdl.texi(,128) no effect on the meaning of this License.
fdl.texi(,129) 
fdl.texi(,130) @item
fdl.texi(,131) VERBATIM COPYING
fdl.texi(,132) 
fdl.texi(,133) You may copy and distribute the Document in any medium, either
fdl.texi(,134) commercially or noncommercially, provided that this License, the
fdl.texi(,135) copyright notices, and the license notice saying this License applies
fdl.texi(,136) to the Document are reproduced in all copies, and that you add no other
fdl.texi(,137) conditions whatsoever to those of this License.  You may not use
fdl.texi(,138) technical measures to obstruct or control the reading or further
fdl.texi(,139) copying of the copies you make or distribute.  However, you may accept
fdl.texi(,140) compensation in exchange for copies.  If you distribute a large enough
fdl.texi(,141) number of copies you must also follow the conditions in section 3.
fdl.texi(,142) 
fdl.texi(,143) You may also lend copies, under the same conditions stated above, and
fdl.texi(,144) you may publicly display copies.
fdl.texi(,145) 
fdl.texi(,146) @item
fdl.texi(,147) COPYING IN QUANTITY
fdl.texi(,148) 
fdl.texi(,149) If you publish printed copies (or copies in media that commonly have
fdl.texi(,150) printed covers) of the Document, numbering more than 100, and the
fdl.texi(,151) Document's license notice requires Cover Texts, you must enclose the
fdl.texi(,152) copies in covers that carry, clearly and legibly, all these Cover
fdl.texi(,153) Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
fdl.texi(,154) the back cover.  Both covers must also clearly and legibly identify
fdl.texi(,155) you as the publisher of these copies.  The front cover must present
fdl.texi(,156) the full title with all words of the title equally prominent and
fdl.texi(,157) visible.  You may add other material on the covers in addition.
fdl.texi(,158) Copying with changes limited to the covers, as long as they preserve
fdl.texi(,159) the title of the Document and satisfy these conditions, can be treated
fdl.texi(,160) as verbatim copying in other respects.
fdl.texi(,161) 
fdl.texi(,162) If the required texts for either cover are too voluminous to fit
fdl.texi(,163) legibly, you should put the first ones listed (as many as fit
fdl.texi(,164) reasonably) on the actual cover, and continue the rest onto adjacent
fdl.texi(,165) pages.
fdl.texi(,166) 
fdl.texi(,167) If you publish or distribute Opaque copies of the Document numbering
fdl.texi(,168) more than 100, you must either include a machine-readable Transparent
fdl.texi(,169) copy along with each Opaque copy, or state in or with each Opaque copy
fdl.texi(,170) a computer-network location from which the general network-using
fdl.texi(,171) public has access to download using public-standard network protocols
fdl.texi(,172) a complete Transparent copy of the Document, free of added material.
fdl.texi(,173) If you use the latter option, you must take reasonably prudent steps,
fdl.texi(,174) when you begin distribution of Opaque copies in quantity, to ensure
fdl.texi(,175) that this Transparent copy will remain thus accessible at the stated
fdl.texi(,176) location until at least one year after the last time you distribute an
fdl.texi(,177) Opaque copy (directly or through your agents or retailers) of that
fdl.texi(,178) edition to the public.
fdl.texi(,179) 
fdl.texi(,180) It is requested, but not required, that you contact the authors of the
fdl.texi(,181) Document well before redistributing any large number of copies, to give
fdl.texi(,182) them a chance to provide you with an updated version of the Document.
fdl.texi(,183) 
fdl.texi(,184) @item
fdl.texi(,185) MODIFICATIONS
fdl.texi(,186) 
fdl.texi(,187) You may copy and distribute a Modified Version of the Document under
fdl.texi(,188) the conditions of sections 2 and 3 above, provided that you release
fdl.texi(,189) the Modified Version under precisely this License, with the Modified
fdl.texi(,190) Version filling the role of the Document, thus licensing distribution
fdl.texi(,191) and modification of the Modified Version to whoever possesses a copy
fdl.texi(,192) of it.  In addition, you must do these things in the Modified Version:
fdl.texi(,193) 
fdl.texi(,194) @enumerate A
fdl.texi(,195) @item
fdl.texi(,196) Use in the Title Page (and on the covers, if any) a title distinct
fdl.texi(,197) from that of the Document, and from those of previous versions
fdl.texi(,198) (which should, if there were any, be listed in the History section
fdl.texi(,199) of the Document).  You may use the same title as a previous version
fdl.texi(,200) if the original publisher of that version gives permission.
fdl.texi(,201) 
fdl.texi(,202) @item
fdl.texi(,203) List on the Title Page, as authors, one or more persons or entities
fdl.texi(,204) responsible for authorship of the modifications in the Modified
fdl.texi(,205) Version, together with at least five of the principal authors of the
fdl.texi(,206) Document (all of its principal authors, if it has fewer than five),
fdl.texi(,207) unless they release you from this requirement.
fdl.texi(,208) 
fdl.texi(,209) @item
fdl.texi(,210) State on the Title page the name of the publisher of the
fdl.texi(,211) Modified Version, as the publisher.
fdl.texi(,212) 
fdl.texi(,213) @item
fdl.texi(,214) Preserve all the copyright notices of the Document.
fdl.texi(,215) 
fdl.texi(,216) @item
fdl.texi(,217) Add an appropriate copyright notice for your modifications
fdl.texi(,218) adjacent to the other copyright notices.
fdl.texi(,219) 
fdl.texi(,220) @item
fdl.texi(,221) Include, immediately after the copyright notices, a license notice
fdl.texi(,222) giving the public permission to use the Modified Version under the
fdl.texi(,223) terms of this License, in the form shown in the Addendum below.
fdl.texi(,224) 
fdl.texi(,225) @item
fdl.texi(,226) Preserve in that license notice the full lists of Invariant Sections
fdl.texi(,227) and required Cover Texts given in the Document's license notice.
fdl.texi(,228) 
fdl.texi(,229) @item
fdl.texi(,230) Include an unaltered copy of this License.
fdl.texi(,231) 
fdl.texi(,232) @item
fdl.texi(,233) Preserve the section Entitled ``History'', Preserve its Title, and add
fdl.texi(,234) to it an item stating at least the title, year, new authors, and
fdl.texi(,235) publisher of the Modified Version as given on the Title Page.  If
fdl.texi(,236) there is no section Entitled ``History'' in the Document, create one
fdl.texi(,237) stating the title, year, authors, and publisher of the Document as
fdl.texi(,238) given on its Title Page, then add an item describing the Modified
fdl.texi(,239) Version as stated in the previous sentence.
fdl.texi(,240) 
fdl.texi(,241) @item
fdl.texi(,242) Preserve the network location, if any, given in the Document for
fdl.texi(,243) public access to a Transparent copy of the Document, and likewise
fdl.texi(,244) the network locations given in the Document for previous versions
fdl.texi(,245) it was based on.  These may be placed in the ``History'' section.
fdl.texi(,246) You may omit a network location for a work that was published at
fdl.texi(,247) least four years before the Document itself, or if the original
fdl.texi(,248) publisher of the version it refers to gives permission.
fdl.texi(,249) 
fdl.texi(,250) @item
fdl.texi(,251) For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve
fdl.texi(,252) the Title of the section, and preserve in the section all the
fdl.texi(,253) substance and tone of each of the contributor acknowledgements and/or
fdl.texi(,254) dedications given therein.
fdl.texi(,255) 
fdl.texi(,256) @item
fdl.texi(,257) Preserve all the Invariant Sections of the Document,
fdl.texi(,258) unaltered in their text and in their titles.  Section numbers
fdl.texi(,259) or the equivalent are not considered part of the section titles.
fdl.texi(,260) 
fdl.texi(,261) @item
fdl.texi(,262) Delete any section Entitled ``Endorsements''.  Such a section
fdl.texi(,263) may not be included in the Modified Version.
fdl.texi(,264) 
fdl.texi(,265) @item
fdl.texi(,266) Do not retitle any existing section to be Entitled ``Endorsements'' or
fdl.texi(,267) to conflict in title with any Invariant Section.
fdl.texi(,268) 
fdl.texi(,269) @item
fdl.texi(,270) Preserve any Warranty Disclaimers.
fdl.texi(,271) @end enumerate
fdl.texi(,272) 
fdl.texi(,273) If the Modified Version includes new front-matter sections or
fdl.texi(,274) appendices that qualify as Secondary Sections and contain no material
fdl.texi(,275) copied from the Document, you may at your option designate some or all
fdl.texi(,276) of these sections as invariant.  To do this, add their titles to the
fdl.texi(,277) list of Invariant Sections in the Modified Version's license notice.
fdl.texi(,278) These titles must be distinct from any other section titles.
fdl.texi(,279) 
fdl.texi(,280) You may add a section Entitled ``Endorsements'', provided it contains
fdl.texi(,281) nothing but endorsements of your Modified Version by various
fdl.texi(,282) parties---for example, statements of peer review or that the text has
fdl.texi(,283) been approved by an organization as the authoritative definition of a
fdl.texi(,284) standard.
fdl.texi(,285) 
fdl.texi(,286) You may add a passage of up to five words as a Front-Cover Text, and a
fdl.texi(,287) passage of up to 25 words as a Back-Cover Text, to the end of the list
fdl.texi(,288) of Cover Texts in the Modified Version.  Only one passage of
fdl.texi(,289) Front-Cover Text and one of Back-Cover Text may be added by (or
fdl.texi(,290) through arrangements made by) any one entity.  If the Document already
fdl.texi(,291) includes a cover text for the same cover, previously added by you or
fdl.texi(,292) by arrangement made by the same entity you are acting on behalf of,
fdl.texi(,293) you may not add another; but you may replace the old one, on explicit
fdl.texi(,294) permission from the previous publisher that added the old one.
fdl.texi(,295) 
fdl.texi(,296) The author(s) and publisher(s) of the Document do not by this License
fdl.texi(,297) give permission to use their names for publicity for or to assert or
fdl.texi(,298) imply endorsement of any Modified Version.
fdl.texi(,299) 
fdl.texi(,300) @item
fdl.texi(,301) COMBINING DOCUMENTS
fdl.texi(,302) 
fdl.texi(,303) You may combine the Document with other documents released under this
fdl.texi(,304) License, under the terms defined in section 4 above for modified
fdl.texi(,305) versions, provided that you include in the combination all of the
fdl.texi(,306) Invariant Sections of all of the original documents, unmodified, and
fdl.texi(,307) list them all as Invariant Sections of your combined work in its
fdl.texi(,308) license notice, and that you preserve all their Warranty Disclaimers.
fdl.texi(,309) 
fdl.texi(,310) The combined work need only contain one copy of this License, and
fdl.texi(,311) multiple identical Invariant Sections may be replaced with a single
fdl.texi(,312) copy.  If there are multiple Invariant Sections with the same name but
fdl.texi(,313) different contents, make the title of each such section unique by
fdl.texi(,314) adding at the end of it, in parentheses, the name of the original
fdl.texi(,315) author or publisher of that section if known, or else a unique number.
fdl.texi(,316) Make the same adjustment to the section titles in the list of
fdl.texi(,317) Invariant Sections in the license notice of the combined work.
fdl.texi(,318) 
fdl.texi(,319) In the combination, you must combine any sections Entitled ``History''
fdl.texi(,320) in the various original documents, forming one section Entitled
fdl.texi(,321) ``History''; likewise combine any sections Entitled ``Acknowledgements'',
fdl.texi(,322) and any sections Entitled ``Dedications''.  You must delete all
fdl.texi(,323) sections Entitled ``Endorsements.''
fdl.texi(,324) 
fdl.texi(,325) @item
fdl.texi(,326) COLLECTIONS OF DOCUMENTS
fdl.texi(,327) 
fdl.texi(,328) You may make a collection consisting of the Document and other documents
fdl.texi(,329) released under this License, and replace the individual copies of this
fdl.texi(,330) License in the various documents with a single copy that is included in
fdl.texi(,331) the collection, provided that you follow the rules of this License for
fdl.texi(,332) verbatim copying of each of the documents in all other respects.
fdl.texi(,333) 
fdl.texi(,334) You may extract a single document from such a collection, and distribute
fdl.texi(,335) it individually under this License, provided you insert a copy of this
fdl.texi(,336) License into the extracted document, and follow this License in all
fdl.texi(,337) other respects regarding verbatim copying of that document.
fdl.texi(,338) 
fdl.texi(,339) @item
fdl.texi(,340) AGGREGATION WITH INDEPENDENT WORKS
fdl.texi(,341) 
fdl.texi(,342) A compilation of the Document or its derivatives with other separate
fdl.texi(,343) and independent documents or works, in or on a volume of a storage or
fdl.texi(,344) distribution medium, is called an ``aggregate'' if the copyright
fdl.texi(,345) resulting from the compilation is not used to limit the legal rights
fdl.texi(,346) of the compilation's users beyond what the individual works permit.
fdl.texi(,347) When the Document is included in an aggregate, this License does not
fdl.texi(,348) apply to the other works in the aggregate which are not themselves
fdl.texi(,349) derivative works of the Document.
fdl.texi(,350) 
fdl.texi(,351) If the Cover Text requirement of section 3 is applicable to these
fdl.texi(,352) copies of the Document, then if the Document is less than one half of
fdl.texi(,353) the entire aggregate, the Document's Cover Texts may be placed on
fdl.texi(,354) covers that bracket the Document within the aggregate, or the
fdl.texi(,355) electronic equivalent of covers if the Document is in electronic form.
fdl.texi(,356) Otherwise they must appear on printed covers that bracket the whole
fdl.texi(,357) aggregate.
fdl.texi(,358) 
fdl.texi(,359) @item
fdl.texi(,360) TRANSLATION
fdl.texi(,361) 
fdl.texi(,362) Translation is considered a kind of modification, so you may
fdl.texi(,363) distribute translations of the Document under the terms of section 4.
fdl.texi(,364) Replacing Invariant Sections with translations requires special
fdl.texi(,365) permission from their copyright holders, but you may include
fdl.texi(,366) translations of some or all Invariant Sections in addition to the
fdl.texi(,367) original versions of these Invariant Sections.  You may include a
fdl.texi(,368) translation of this License, and all the license notices in the
fdl.texi(,369) Document, and any Warranty Disclaimers, provided that you also include
fdl.texi(,370) the original English version of this License and the original versions
fdl.texi(,371) of those notices and disclaimers.  In case of a disagreement between
fdl.texi(,372) the translation and the original version of this License or a notice
fdl.texi(,373) or disclaimer, the original version will prevail.
fdl.texi(,374) 
fdl.texi(,375) If a section in the Document is Entitled ``Acknowledgements'',
fdl.texi(,376) ``Dedications'', or ``History'', the requirement (section 4) to Preserve
fdl.texi(,377) its Title (section 1) will typically require changing the actual
fdl.texi(,378) title.
fdl.texi(,379) 
fdl.texi(,380) @item
fdl.texi(,381) TERMINATION
fdl.texi(,382) 
fdl.texi(,383) You may not copy, modify, sublicense, or distribute the Document except
fdl.texi(,384) as expressly provided for under this License.  Any other attempt to
fdl.texi(,385) copy, modify, sublicense or distribute the Document is void, and will
fdl.texi(,386) automatically terminate your rights under this License.  However,
fdl.texi(,387) parties who have received copies, or rights, from you under this
fdl.texi(,388) License will not have their licenses terminated so long as such
fdl.texi(,389) parties remain in full compliance.
fdl.texi(,390) 
fdl.texi(,391) @item
fdl.texi(,392) FUTURE REVISIONS OF THIS LICENSE
fdl.texi(,393) 
fdl.texi(,394) The Free Software Foundation may publish new, revised versions
fdl.texi(,395) of the GNU Free Documentation License from time to time.  Such new
fdl.texi(,396) versions will be similar in spirit to the present version, but may
fdl.texi(,397) differ in detail to address new problems or concerns.  See
fdl.texi(,398) @uref{http://www.gnu.org/copyleft/}.
fdl.texi(,399) 
fdl.texi(,400) Each version of the License is given a distinguishing version number.
fdl.texi(,401) If the Document specifies that a particular numbered version of this
fdl.texi(,402) License ``or any later version'' applies to it, you have the option of
fdl.texi(,403) following the terms and conditions either of that specified version or
fdl.texi(,404) of any later version that has been published (not as a draft) by the
fdl.texi(,405) Free Software Foundation.  If the Document does not specify a version
fdl.texi(,406) number of this License, you may choose any version ever published (not
fdl.texi(,407) as a draft) by the Free Software Foundation.
fdl.texi(,408) @end enumerate
fdl.texi(,409) 
fdl.texi(,410) @page
fdl.texi(,411) @appendixsubsec ADDENDUM: How to use this License for your documents
fdl.texi(,412) 
fdl.texi(,413) To use this License in a document you have written, include a copy of
fdl.texi(,414) the License in the document and put the following copyright and
fdl.texi(,415) license notices just after the title page:
fdl.texi(,416) 
fdl.texi(,417) @smallexample
fdl.texi(,418) @group
fdl.texi(,419)   Copyright (C)  @var{year}  @var{your name}.
fdl.texi(,420)   Permission is granted to copy, distribute and/or modify this document
fdl.texi(,421)   under the terms of the GNU Free Documentation License, Version 1.2
fdl.texi(,422)   or any later version published by the Free Software Foundation;
fdl.texi(,423)   with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
fdl.texi(,424)   Texts.  A copy of the license is included in the section entitled ``GNU
fdl.texi(,425)   Free Documentation License''.
fdl.texi(,426) @end group
fdl.texi(,427) @end smallexample
fdl.texi(,428) 
fdl.texi(,429) If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
fdl.texi(,430) replace the ``with...Texts.'' line with this:
fdl.texi(,431) 
fdl.texi(,432) @smallexample
fdl.texi(,433) @group
fdl.texi(,434)     with the Invariant Sections being @var{list their titles}, with
fdl.texi(,435)     the Front-Cover Texts being @var{list}, and with the Back-Cover Texts
fdl.texi(,436)     being @var{list}.
fdl.texi(,437) @end group
fdl.texi(,438) @end smallexample
fdl.texi(,439) 
fdl.texi(,440) If you have Invariant Sections without Cover Texts, or some other
fdl.texi(,441) combination of the three, merge those two alternatives to suit the
fdl.texi(,442) situation.
fdl.texi(,443) 
fdl.texi(,444) If your document contains nontrivial examples of program code, we
fdl.texi(,445) recommend releasing these examples in parallel under your choice of
fdl.texi(,446) free software license, such as the GNU General Public License,
fdl.texi(,447) to permit their use in free software.
fdl.texi(,448) 
fdl.texi(,449) @c Local Variables:
fdl.texi(,450) @c ispell-local-pdict: "ispell-dict"
fdl.texi(,451) @c End:
fdl.texi(,452) 
tar.texi(,10794) 
tar.texi(,10795) @node Index of Command Line Options
tar.texi(,10796) @appendix Index of Command Line Options
tar.texi(,10797) 
tar.texi(GNUTAR,10798) This appendix contains an index of all tar.texi(GNUTAR,10798) @acronym{GNU} @command{tar} long command line
tar.texi(,10799) options. The options are listed without the preceeding double-dash.
tar.texi(,10800) For a cross-reference of short command line options, @ref{Short Option Summary}.
tar.texi(,10801) 
tar.texi(,10802) @printindex op
tar.texi(,10803) 
tar.texi(,10804) @node Index
tar.texi(,10805) @appendix Index
tar.texi(,10806) 
tar.texi(,10807) @printindex cp
tar.texi(,10808) 
tar.texi(,10809) @summarycontents
tar.texi(,10810) @contents
tar.texi(,10811) @bye
