document. The rest of the menu lists all the lower level nodes.
@end ifnottex
-@c The master menu, created with texinfo-master-menu, goes here.
-@c (However, getdate.texi's menu is interpolated by hand.)
+@c The master menu goes here.
+@c
+@c NOTE: To update it from within Emacs, make sure mastermenu.el is
+@c loaded and run texinfo-master-menu.
+@c To update it from the command line, run
+@c
+@c make master-menu
@menu
* Introduction::
* Changes::
* Configuring Help Summary::
* Genfile::
-* Snapshot Files::
+* Tar Internals::
* Free Software Needs Free Documentation::
* Copying This Manual::
* Index of Command Line Options::
* extracting archives::
* extracting files::
* extract dir::
+* extracting untrusted archives::
* failing commands::
Invoking @GNUTAR{}
* concatenate::
* delete::
* compare::
-* quoting styles::
How to Add Files to Existing Archives: @option{--append}
* Recursive Unlink::
* Data Modification Times::
* Setting Access Permissions::
+* Directory Modification Times and Permissions::
* Writing to Standard Output::
+* Writing to an External Program::
* remove files::
Coping with Scarce Resources
* Selecting Archive Members::
* files:: Reading Names from a File
* exclude:: Excluding Some Files
-* Wildcards:: Wildcards Patterns and Matching
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
* after:: Operating Only on New Files
* recurse:: Descending into Directories
* one:: Crossing File System Boundaries
* problems with exclude::
+Wildcards Patterns and Matching
+
+* controlling pattern-matching::
+
Crossing File System Boundaries
* directory:: Changing Directory
* General date syntax:: Common rules.
* Calendar date items:: 19 Dec 1994.
* Time of day items:: 9:20pm.
-* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}, ...
+* Time zone items:: @sc{est}, @sc{pdt}, @sc{gmt}.
* Day of week items:: Monday and others.
* Relative items in date strings:: next tuesday, 2 years ago.
* Pure numbers in date strings:: 19931219, 1440.
* Seconds since the Epoch:: @@1078100502.
+* Specifying time zone rules:: TZ="America/New_York", TZ="UTC0".
* Authors of get_date:: Bellovin, Eggert, Salz, Berets, et al.
Controlling the Archive Format
* Portability:: Making @command{tar} Archives More Portable
* Compression:: Using Less Space through Compression
* Attributes:: Handling File Attributes
-* Standard:: The Standard Format
-* Extensions:: @acronym{GNU} Extensions to the Archive Format
* cpio:: Comparison of @command{tar} and @command{cpio}
Making @command{tar} Archives More Portable
* Portable Names:: Portable Names
* dereference:: Symbolic Links
* old:: Old V7 Archives
+* ustar:: Ustar Archives
+* gnu:: GNU and old GNU format archives.
* posix:: @acronym{POSIX} archives
* Checksumming:: Checksumming Problems
* Large or Negative Values:: Large files, negative time stamps, etc.
+@GNUTAR{} and @acronym{POSIX} @command{tar}
+
+* PAX keywords:: Controlling Extended Header Keywords.
+
Using Less Space through Compression
* gzip:: Creating and Reading Compressed Archives
* Tape Files:: Tape Files
* Tarcat:: Concatenate Volumes into a Single Archive
-GNU tar internals and development
-* Genfile::
+Genfile
+
+* Generate Mode:: File Generation Mode.
+* Status Mode:: File Status Mode.
+* Exec Mode:: Synchronous Execution mode.
+
+Tar Internals
+
+* Standard:: Basic Tar Format
+* Extensions:: @acronym{GNU} Extensions to the Archive Format
* Snapshot Files::
+* Dumpdir::
Copying This Manual
-* Free Software Needs Free Documentation::
* GNU Free Documentation License:: License for copying this manual
@end detailmenu
Fran@,{c}ois Pinard put version 1.11.8 of the manual together by
taking information from all these sources and merging them. Melissa
Weisshaus finally edited and redesigned the book to create version
-1.12. @FIXME{update version number as necessary; i'm being
-optimistic!} @FIXME{Someone [maybe karl berry? maybe bob chassell?
-maybe melissa? maybe julie sussman?] needs to properly index the
-thing.}
+1.12. The book for versions from 1.14 up to @value{VERSION} were edited
+by the current maintainer, Sergey Poznyakoff.
For version 1.12, Daniel Hagerty contributed a great deal of technical
consulting. In particular, he is the primary author of @ref{Backups}.
clear, and we will give many examples both using and not using
@option{--verbose} to show the differences.
-Sometimes, a single instance of @option{--verbose} on the command line
-will show a full, @samp{ls} style listing of an archive or files,
-giving sizes, owners, and similar information. @FIXME{Describe the
-exact output format, e.g., how hard links are displayed.}
-Other times, @option{--verbose} will only show files or members that the particular
-operation is operating on at the time. In the latter case, you can
-use @option{--verbose} twice in a command to get a listing such as that
-in the former case. For example, instead of saying
+Each instance of @option{--verbose} on the command line increases the
+verbosity level by one, so if you need more details on the output,
+specify it twice.
+
+When reading archives (@option{--list}, @option{--extract},
+@option{--diff}), @command{tar} by default prints only the names of
+the members being extracted. Using @option{--verbose} will show a full,
+@command{ls} style member listing.
+
+In contrast, when writing archives (@option{--create}, @option{--append},
+@option{--update}), @command{tar} does not print file names by
+default. So, a single @option{--verbose} option shows the file names
+being added to the archive, while two @option{--verbose} options
+enable the full listing.
+
+For example, to create an archive in verbose mode:
@smallexample
-@kbd{tar -cvf afiles.tar apple angst aspic}
+$ @kbd{tar -cvf afiles.tar apple angst aspic}
+apple
+angst
+aspic
@end smallexample
@noindent
-above, you might say
+Creating the same archive with the verbosity level 2 could give:
@smallexample
-@kbd{tar -cvvf afiles.tar apple angst aspic}
+$ @kbd{tar -cvvf afiles.tar apple angst aspic}
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+-rw-r--r-- gray/staff 11481 2006-06-09 12:06 angst
+-rw-r--r-- gray/staff 23152 2006-06-09 12:06 aspic
@end smallexample
@noindent
Later in the tutorial, we will give examples using @w{@option{--verbose
--verbose}}.
+The full output consists of six fields:
+
+@itemize @bullet
+@item File type and permissions in symbolic form.
+These are displayed in the same format as the first column of
+@command{ls -l} output (@pxref{What information is listed,
+format=verbose, Verbose listing, fileutils, GNU file utilities}).
+
+@item Owner name and group separated by a slash character.
+If these data are not available (for example, when listing a @samp{v7} format
+archive), numeric ID values are printed instead.
+
+@item Size of the file, in bytes.
+
+@item File modification date in ISO 8601 format.
+
+@item File modification time.
+
+@item File name.
+If the name contains any special characters (white space, newlines,
+etc.) these are displayed in an unambiguous form using so called
+@dfn{quoting style}. For the detailed discussion of available styles
+and on how to use them, see @ref{quoting styles}.
+
+Depending on the file type, the name can be followed by some
+additional information, described in the following table:
+
+@table @samp
+@item -> @var{link-name}
+The file or archive member is a @dfn{symbolic link} and
+@var{link-name} is the name of file it links to.
+
+@item link to @var{link-name}
+The file or archive member is a @dfn{hard link} and @var{link-name} is
+the name of file it links to.
+
+@item --Long Link--
+The archive member is an old GNU format long link. You will normally
+not encounter this.
+
+@item --Long Name--
+The archive member is an old GNU format long name. You will normally
+not encounter this.
+
+@item --Volume Header--
+The archive member is a GNU @dfn{volume header} (@pxref{Tape Files}).
+
+@item --Continued at byte @var{n}--
+Encountered only at the beginning of a multy-volume archive
+(@pxref{Using Multiple Tapes}). This archive member is a continuation
+from the previous volume. The number @var{n} gives the offset where
+the original file was split.
+
+@item --Mangled file names--
+This archive member contains @dfn{mangled file names} declarations,
+a special member type that was used by early versions of @GNUTAR{}.
+You probably will never encounter this, unless you are reading a very
+old archive.
+
+@item unknown file type @var{c}
+An archive member of unknown type. @var{c} is the type character from
+the archive header. If you encounter such a message, it means that
+either your archive contains proprietary member types @GNUTAR{} is not
+able to handle, or the archive is corrupted.
+@end table
+
+@end itemize
+
+For example, here is an archive listing containing most of the special
+suffixes explained above:
+
+@smallexample
+@group
+V--------- 0/0 1536 2006-06-09 13:07 MyVolume--Volume Header--
+-rw-r--r-- gray/staff 456783 2006-06-09 12:06 aspic--Continued at
+byte 32456--
+-rw-r--r-- gray/staff 62373 2006-06-09 12:06 apple
+lrwxrwxrwx gray/staff 0 2006-06-09 13:01 angst -> apple
+-rw-r--r-- gray/staff 35793 2006-06-09 12:06 blues
+hrw-r--r-- gray/staff 0 2006-06-09 12:06 music link to blues
+@end group
+@end smallexample
+
+@smallexample
+@end smallexample
+
@node help tutorial
@unnumberedsubsec Getting Help: Using the @option{--help} Option
(@file{collection.tar}), and @option{--file} is the option which lets
you give it the name you chose. The files, @file{blues}, @file{folk},
and @file{jazz}, are now members of the archive, @file{collection.tar}
-(they are @dfn{file name arguments} to the @option{--create} operation).
-@FIXME{xref here to the discussion of file name args?}Now that they are
+(they are @dfn{file name arguments} to the @option{--create} operation.
+@xref{Choosing}, for the detailed discussion on these.) Now that they are
in the archive, they are called @emph{archive members}, not files.
(@pxref{Definitions,members}).
@end smallexample
@noindent
-will list all members whose name contains @samp{b}. @xref{Wildcards},
+will list all members whose name contains @samp{b}. @xref{wildcards},
for a detailed discussion of globbing patterns and related
@command{tar} command line options.
command line arguments as globbing patterns and @option{--no-anchored}
informs it that the patterns apply to member names after any @samp{/}
delimiter. The use of globbing patterns is discussed in detail in
-@xref{Wildcards}.
+@xref{wildcards}.
You can extract a file to standard output by combining the above options
with the @option{--to-stdout} (@option{-O}) option (@pxref{Writing to Standard
The distinction between file names and archive member names is especially
important when shell globbing is used, and sometimes a source of confusion
-for newcomers. @xref{Wildcards}, for more information about globbing.
+for newcomers. @xref{wildcards}, for more information about globbing.
The problem is that shells may only glob using existing files in the
file system. Only @command{tar} itself may glob on archive members, so when
needed, you must ensure that wildcard characters reach @command{tar} without
@code{bzip2}. @xref{gzip}.
@opindex checkpoint, summary
-@item --checkpoint
+@item --checkpoint[=@var{number}]
-This option directs @command{tar} to print periodic checkpoint messages as it
-reads through the archive. It is intended for when you want a visual
-indication that @command{tar} is still running, but don't want to see
-@option{--verbose} output. @FIXME-xref{}
+This option directs @command{tar} to print periodic checkpoint
+messages as it reads through the archive. It is intended for when you
+want a visual indication that @command{tar} is still running, but
+don't want to see @option{--verbose} output. For a detailed
+description, see @ref{Progress information}.
@opindex check-links, summary
@item --check-links
dumped for each processed file. If this number does not match the
total number of hard links for the file, a warning message will be
output @footnote{Earlier versions of @GNUTAR{} understood @option{-l} as a
-synonym for @option{--one-file-system}. The current semantics, wich
+synonym for @option{--one-file-system}. The current semantics, which
complies to UNIX98, was introduced with version
1.15.91. @xref{Changes}, for more information.}.
@noindent
will add to @file{archive} files from the current working directory,
replacing initial @samp{./} prefix with @samp{usr/}. For the detailed
-discussion, see @FIXME-xref{transform}
+discussion, @xref{transform}.
To see transformed member names in verbose listings, use
@option{--show-transformed-names} option
-(@FIXME-pxref{show-transformed-names}).
+(@pxref{show-transformed-names}).
@opindex quote-chars, summary
@item --quote-chars=@var{string}
@opindex pax-option, summary
@item --pax-option=@var{keyword-list}
-@FIXME{Such a detailed description does not belong there, move it elsewhere.}
This option is meaningful only with @acronym{POSIX.1-2001} archives
(@pxref{posix}). It modifies the way @command{tar} handles the
extended header keywords. @var{Keyword-list} is a comma-separated
-list of keyword options, each keyword option taking one of
-the following forms:
-
-@table @asis
-@item delete=@var{pattern}
-When used with one of archive-creation commands,
-this option instructs @command{tar} to omit from extended header records
-that it produces any keywords matching the string @var{pattern}.
-
-When used in extract or list mode, this option instructs tar
-to ignore any keywords matching the given @var{pattern} in the extended
-header records. In both cases, matching is performed using the pattern
-matching notation described in @acronym{POSIX 1003.2}, 3.13
-(See @cite{glob(7)}). For example:
-
-@smallexample
---pax-option delete=security.*
-@end smallexample
-
-would suppress security-related information.
-
-@item exthdr.name=@var{string}
-
-This keyword allows user control over the name that is written into the
-ustar header blocks for the extended headers. The name is obtained
-from @var{string} after making the following substitutions:
-
-@multitable @columnfractions .30 .70
-@headitem Meta-character @tab Replaced By
-@item %d @tab The directory name of the file, equivalent to the
-result of the @command{dirname} utility on the translated pathname.
-@item %f @tab The filename of the file, equivalent to the result
-of the @command{basename} utility on the translated pathname.
-@item %p @tab The process ID of the @command{tar} process.
-@item %% @tab A @samp{%} character.
-@end multitable
-
-Any other @samp{%} characters in @var{string} produce undefined
-results.
-
-If no option @samp{exthdr.name=string} is specified, @command{tar}
-will use the following default value:
-
-@smallexample
-%d/PaxHeaders.%p/%f
-@end smallexample
-
-@item globexthdr.name=@var{string}
-This keyword allows user control over the name that is written into
-the ustar header blocks for global extended header records. The name
-is obtained from the contents of @var{string}, after making
-the following substitutions:
-
-@multitable @columnfractions .30 .70
-@headitem Meta-character @tab Replaced By
-@item %n @tab An integer that represents the
-sequence number of the global extended header record in the archive,
-starting at 1.
-@item %p @tab The process ID of the @command{tar} process.
-@item %% @tab A @samp{%} character.
-@end multitable
-
-Any other @samp{%} characters in @var{string} produce undefined results.
-
-If no option @samp{globexthdr.name=string} is specified, @command{tar}
-will use the following default value:
-
-@smallexample
-$TMPDIR/GlobalHead.%p.%n
-@end smallexample
-
-@noindent
-where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
-environment variable. If @var{TMPDIR} is not set, @command{tar}
-uses @samp{/tmp}.
-
-@item @var{keyword}=@var{value}
-When used with one of archive-creation commands, these keyword/value pairs
-will be included at the beginning of the archive in a global extended
-header record. When used with one of archive-reading commands,
-@command{tar} will behave as if it has encountered these keyword/value
-pairs at the beginning of the archive in a global extended header
-record.
-
-@item @var{keyword}:=@var{value}
-When used with one of archive-creation commands, these keyword/value pairs
-will be included as records at the beginning of an extended header for
-each file. This is effectively equivalent to @var{keyword}=@var{value}
-form except that it creates no global extended header records.
-
-When used with one of archive-reading commands, @command{tar} will
-behave as if these keyword/value pairs were included as records at the
-end of each extended header; thus, they will override any global or
-file-specific extended header record keywords of the same names.
-For example, in the command:
-
-@smallexample
-tar --format=posix --create \
- --file archive --pax-option gname:=user .
-@end smallexample
-
-the group name will be forced to a new value for all files
-stored in the archive.
-@end table
+list of keyword options. @xref{PAX keywords}, for a detailed
+discussion.
@opindex portability, summary
@item --portability
@itemx --show-stored-names
Display file or member names after applying any transformations
-(@FIXME-pxref{}). In particular, when used in conjunction with one of
+(@pxref{transform}). In particular, when used in conjunction with one of
archive creation operations it instructs tar to list the member names
stored in the archive, as opposed to the actual file
names. @xref{listing member and file names}.
@end smallexample
@noindent
-would extracted this file to file @file{name}.
+would extract this file to file @file{name}.
@opindex suffix, summary
@item --suffix=@var{suffix}
than to the file system. @xref{Writing to Standard Output}.
@opindex totals, summary
-@item --totals
+@item --totals[=@var{signo}]
-Displays the total number of bytes written after creating an archive.
-@xref{verbose}.
+Displays the total number of bytes transferred when processing an
+archive. If an argument is given, these data are displayed on
+request, when signal @var{signo} is delivered to @command{tar}.
+@xref{totals}.
@opindex touch, summary
@item --touch
verbose output to @var{file} rather than to standard output or standard
error.
+@anchor{totals}
@cindex Obtaining total status information
@opindex totals
-The @option{--totals} option---which is only meaningful when used with
-@option{--create} (@option{-c})---causes @command{tar} to print the total
-amount written to the archive, after it has been fully created.
+The @option{--totals} option causes @command{tar} to print on the
+standard error the total amount of bytes transferred when processing
+an archive. When creating or appending to an archive, this option
+prints the number of bytes written to the archive and the average
+speed at which they have been written, e.g.:
+
+@smallexample
+@group
+$ @kbd{tar -c -f archive.tar --totals /home}
+Total bytes written: 7924664320 (7.4GiB, 85MiB/s)
+@end group
+@end smallexample
+
+When reading an archive, this option displays the number of bytes
+read:
+
+@smallexample
+@group
+$ @kbd{tar -x -f archive.tar --totals}
+Total bytes read: 7924664320 (7.4GiB, 95MiB/s)
+@end group
+@end smallexample
+
+Finally, when deleting from an archive, the @option{--totals} option
+displays both numbers plus number of bytes removed from the archive:
+
+@smallexample
+@group
+$ @kbd{tar --delete -f foo.tar --totals --wildcards '*~'}
+Total bytes read: 9543680 (9.2MiB, 201MiB/s)
+Total bytes written: 3829760 (3.7MiB, 81MiB/s)
+Total bytes deleted: 1474048
+@end group
+@end smallexample
+
+You can also obtain this information on request. When
+@option{--totals} is used with an argument, this argument is
+interpreted as a symbolic name of a signal, upon delivery of which the
+statistics is to be printed:
+
+@table @option
+@item --totals=@var{signo}
+Print statistics upon delivery of signal @var{signo}. Valid arguments
+are: @code{SIGHUP}, @code{SIGQUIT}, @code{SIGINT}, @code{SIGUSR1} and
+@code{SIGUSR2}. Shortened names without @samp{SIG} prefix are also
+accepted.
+@end table
+
+Both forms of @option{--totals} option can be used simultaneously.
+Thus, @kbd{tar -x --totals --totals=USR1} instructs @command{tar} to
+extract all members from its default archive and print statistics
+after finishing the extraction, as well as when receiving signal
+@code{SIGUSR1}.
+@anchor{Progress information}
@cindex Progress information
@opindex checkpoint
The @option{--checkpoint} option prints an occasional message
-as @command{tar} reads or writes the archive. In fact, it prints
-a message each 10 records read or written. It is designed for
+as @command{tar} reads or writes the archive. It is designed for
those who don't need the more detailed (and voluminous) output of
@option{--block-number} (@option{-R}), but do want visual confirmation
-that @command{tar} is actually making forward progress.
+that @command{tar} is actually making forward progress. By default it
+prints a message each 10 records read or written. This can be changed
+by giving it a numeric argument after an equal sign:
+
+@smallexample
+$ @kbd{tar -c --checkpoint=1000} /var
+tar: Write checkpoint 1000
+tar: Write checkpoint 2000
+tar: Write checkpoint 3000
+@end smallexample
+
+This example shows the default checkpoint message used by
+@command{tar}. If you place a dot immediately after the equal
+sign, it will print a @samp{.} at each checkpoint. For example:
-@FIXME{There is some confusion here. It seems that -R once wrote a
-message at @samp{every} record read or written.}
+@smallexample
+$ @kbd{tar -c --checkpoint=.1000} /var
+...
+@end smallexample
@opindex show-omitted-dirs
@anchor{show-omitted-dirs}
to be printed for each directory in the archive which is skipped.
This happens regardless of the reason for skipping: the directory might
not have been named on the command line (implicitly or explicitly),
-it might be excluded by the use of the @option{--exclude=@var{pattern}} option, or
-some other reason.
+it might be excluded by the use of the
+@option{--exclude=@var{pattern}} option, or some other reason.
@opindex block-number
@cindex Block number where error occurred
* concatenate::
* delete::
* compare::
-* quoting styles::
@end menu
@node Operations
current state of files on disk, more than validating the integrity of
the archive media. For this later goal, @xref{verify}.
-@node quoting styles
-@subsection Quoting Member Names
-
-When displaying member names, @command{tar} takes care to avoid
-ambiguities caused by certain characters. This is called @dfn{name
-quoting}. The characters in question are:
+@node create options
+@section Options Used by @option{--create}
-@itemize @bullet
-@item Non-printable control characters:
+@opindex create, additional options
+The previous chapter described the basics of how to use
+@option{--create} (@option{-c}) to create an archive from a set of files.
+@xref{create}. This section described advanced options to be used with
+@option{--create}.
-@multitable @columnfractions 0.20 0.10 0.60
-@headitem Character @tab ASCII @tab Character name
-@item \a @tab 7 @tab Audible bell
-@item \b @tab 8 @tab Backspace
-@item \f @tab 12 @tab Form feed
-@item \n @tab 10 @tab New line
-@item \r @tab 13 @tab Carriage return
-@item \t @tab 9 @tab Horizontal tabulation
-@item \v @tab 11 @tab Vertical tabulation
-@end multitable
+@menu
+* Ignore Failed Read::
+@end menu
-@item Space (ASCII 32)
+@node Ignore Failed Read
+@subsection Ignore Fail Read
-@item Single and double quotes (@samp{'} and @samp{"})
+@table @option
+@item --ignore-failed-read
+Do not exit with nonzero on unreadable files or directories.
+@end table
-@item Backslash (@samp{\})
-@end itemize
+@node extract options
+@section Options Used by @option{--extract}
+@UNREVISED
-The exact way @command{tar} uses to quote these characters depends on
-the @dfn{quoting style}. The default quoting style, called
-@dfn{escape} (see below), uses backslash notation to represent control
-characters, space and backslash. Using this quoting style, control
-characters are represented as listed in column @samp{Character} in the
-above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
+@opindex extract, additional options
+The previous chapter showed how to use @option{--extract} to extract
+an archive into the file system. Various options cause @command{tar} to
+extract more information than just file contents, such as the owner,
+the permissions, the modification date, and so forth. This section
+presents options to be used with @option{--extract} when certain special
+considerations arise. You may review the information presented in
+@ref{extract} for more basic information about the
+@option{--extract} operation.
-@GNUTAR{} offers seven distinct quoting styles, which can be selected
-using @option{--quoting-style} option:
+@menu
+* Reading:: Options to Help Read Archives
+* Writing:: Changing How @command{tar} Writes Files
+* Scarce:: Coping with Scarce Resources
+@end menu
-@table @option
-@item --quoting-style=@var{style}
-@opindex quoting-style
+@node Reading
+@subsection Options to Help Read Archives
+@cindex Options when reading archives
+@UNREVISED
-Sets quoting style. Valid values for @var{style} argument are:
-literal, shell, shell-always, c, escape, locale, clocale.
-@end table
-
-These styles are described in detail below. To illustrate their
-effect, we will use an imaginary tar archive @file{arch.tar}
-containing the following members:
-
-@smallexample
-@group
-# 1. Contains horizontal tabulation character.
-a tab
-# 2. Contains newline character
-a
-newline
-# 3. Contains a space
-a space
-# 4. Contains double quotes
-a"double"quote
-# 5. Contains single quotes
-a'single'quote
-# 6. Contains a backslash character:
-a\backslash
-@end group
-@end smallexample
-
-Here is how usual @command{ls} command would have listed them, if they
-had existed in the current working directory:
-
-@smallexample
-@group
-$ @kbd{ls}
-a\ttab
-a\nnewline
-a\ space
-a"double"quote
-a'single'quote
-a\\backslash
-@end group
-@end smallexample
-
-Quoting styles:
-
-@table @samp
-@item literal
-No quoting, display each character as is:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=literal}
-./
-./a space
-./a'single'quote
-./a"double"quote
-./a\backslash
-./a tab
-./a
-newline
-@end group
-@end smallexample
-
-@item shell
-Display characters the same way Bourne shell does:
-control characters, except @samp{\t} and @samp{\n}, are printed using
-backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
-single quote is printed as @samp{\'}. If a name contains any quoted
-characters, it is enclosed in single quotes. In particular, if a name
-contains single quotes, it is printed as several single-quoted strings:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=shell}
-./
-'./a space'
-'./a'\''single'\''quote'
-'./a"double"quote'
-'./a\backslash'
-'./a tab'
-'./a
-newline'
-@end group
-@end smallexample
-
-@item shell-always
-Same as @samp{shell}, but the names are always enclosed in single
-quotes:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=shell-always}
-'./'
-'./a space'
-'./a'\''single'\''quote'
-'./a"double"quote'
-'./a\backslash'
-'./a tab'
-'./a
-newline'
-@end group
-@end smallexample
-
-@item c
-Use the notation of the C programming language. All names are
-enclosed in double quotes. Control characters are quoted using
-backslash notations, double quotes are represented as @samp{\"},
-backslash characters are represented as @samp{\\}. Single quotes and
-spaces are not quoted:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=c}
-"./"
-"./a space"
-"./a'single'quote"
-"./a\"double\"quote"
-"./a\\backslash"
-"./a\ttab"
-"./a\nnewline"
-@end group
-@end smallexample
-
-@item escape
-Control characters are printed using backslash notation, a space is
-printed as @samp{\ } and a backslash as @samp{\\}. This is the
-default quoting style, unless it was changed when configured the
-package.
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=escape}
-./
-./a space
-./a'single'quote
-./a"double"quote
-./a\\backslash
-./a\ttab
-./a\nnewline
-@end group
-@end smallexample
-
-@item locale
-Control characters, single quote and backslash are printed using
-backslash notation. All names are quoted using left and right
-quotation marks, appropriate to the current locale. If it does not
-define quotation marks, use @samp{`} as left and @samp{'} as right
-quotation marks. Any occurrences of the right quotation mark in a
-name are escaped with @samp{\}, for example:
-
-For example:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=locale}
-`./'
-`./a space'
-`./a\'single\'quote'
-`./a"double"quote'
-`./a\\backslash'
-`./a\ttab'
-`./a\nnewline'
-@end group
-@end smallexample
-
-@item clocale
-Same as @samp{locale}, but @samp{"} is used for both left and right
-quotation marks, if not provided by the currently selected locale:
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=clocale}
-"./"
-"./a space"
-"./a'single'quote"
-"./a\"double\"quote"
-"./a\\backslash"
-"./a\ttab"
-"./a\nnewline"
-@end group
-@end smallexample
-@end table
-
-You can specify which characters should be quoted in addition to those
-implied by the current quoting style:
-
-@table @option
-@item --quote-chars=@var{string}
-Always quote characters from @var{string}, even if the selected
-quoting style would not quote them.
-@end table
-
-For example, using @samp{escape} quoting (compare with the usual
-escape listing above):
-
-@smallexample
-@group
-$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
-./
-./a\ space
-./a'single'quote
-./a\"double\"quote
-./a\\backslash
-./a\ttab
-./a\nnewline
-@end group
-@end smallexample
-
-To disable quoting of such additional characters, use the following
-option:
-
-@table @option
-@item --no-quote-chars=@var{string}
-Remove characters listed in @var{string} from the list of quoted
-characters set by the previous @option{--quote-chars} option.
-@end table
-
-This option is particularly useful if you have added
-@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
-and wish to disable it for the current invocation.
-
-Note, that @option{--no-quote-chars} does @emph{not} disable those
-characters that are quoted by default in the selected quoting style.
-
-@node create options
-@section Options Used by @option{--create}
-
-@opindex create, additional options
-The previous chapter described the basics of how to use
-@option{--create} (@option{-c}) to create an archive from a set of files.
-@xref{create}. This section described advanced options to be used with
-@option{--create}.
-
-@menu
-* Ignore Failed Read::
-@end menu
-
-@node Ignore Failed Read
-@subsection Ignore Fail Read
-
-@table @option
-@item --ignore-failed-read
-Do not exit with nonzero on unreadable files or directories.
-@end table
-
-@node extract options
-@section Options Used by @option{--extract}
-@UNREVISED
-
-@opindex extract, additional options
-The previous chapter showed how to use @option{--extract} to extract
-an archive into the file system. Various options cause @command{tar} to
-extract more information than just file contents, such as the owner,
-the permissions, the modification date, and so forth. This section
-presents options to be used with @option{--extract} when certain special
-considerations arise. You may review the information presented in
-@ref{extract} for more basic information about the
-@option{--extract} operation.
-
-@menu
-* Reading:: Options to Help Read Archives
-* Writing:: Changing How @command{tar} Writes Files
-* Scarce:: Coping with Scarce Resources
-@end menu
-
-@node Reading
-@subsection Options to Help Read Archives
-@cindex Options when reading archives
-@UNREVISED
-
-@cindex Reading incomplete records
-@cindex Records, incomplete
-@opindex read-full-records
-Normally, @command{tar} will request data in full record increments from
-an archive storage device. If the device cannot return a full record,
-@command{tar} will report an error. However, some devices do not always
-return full records, or do not require the last record of an archive to
-be padded out to the next record boundary. To keep reading until you
-obtain a full record, or to accept an incomplete record if it contains
-an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option
-in conjunction with the @option{--extract} or @option{--list} operations.
-@xref{Blocking}.
+@cindex Reading incomplete records
+@cindex Records, incomplete
+@opindex read-full-records
+Normally, @command{tar} will request data in full record increments from
+an archive storage device. If the device cannot return a full record,
+@command{tar} will report an error. However, some devices do not always
+return full records, or do not require the last record of an archive to
+be padded out to the next record boundary. To keep reading until you
+obtain a full record, or to accept an incomplete record if it contains
+an end-of-archive marker, specify the @option{--read-full-records} (@option{-B}) option
+in conjunction with the @option{--extract} or @option{--list} operations.
+@xref{Blocking}.
The @option{--read-full-records} (@option{-B}) option is turned on by default when
@command{tar} reads an archive from standard input, or from a remote
where @var{x} is a letter describing the status of the file: @samp{Y}
if the file is present in the archive, @samp{N} if the file is not
included in the archive, or a @samp{D} if the file is a directory (and
-is included in the archive).@FIXME-xref{dumpdir format}. Each such
+is included in the archive). @xref{Dumpdir}, for the detailed
+description of dumpdirs and status codes. Each such
line is terminated by a newline character. The last line is followed
by an additional newline to indicate the end of the data.
restore script is @code{restore}. The following sections describe
their use in detail.
-@emph{Please Note:} The backup and restoration scripts are
-designed to be used together. While it is possible to restore files by
-hand from an archive which was created using a backup script, and to create
-an archive by hand which could then be extracted using the restore script,
-it is easier to use the scripts. @xref{Incremental Dumps}, before
-making such an attempt.
+@emph{Please Note:} The backup and restoration scripts are
+designed to be used together. While it is possible to restore files by
+hand from an archive which was created using a backup script, and to create
+an archive by hand which could then be extracted using the restore script,
+it is easier to use the scripts. @xref{Incremental Dumps}, before
+making such an attempt.
+
+@node Backup Parameters
+@section Setting Parameters for Backups and Restoration
+
+The file @file{backup-specs} specifies backup parameters for the
+backup and restoration scripts provided with @command{tar}. You must
+edit @file{backup-specs} to fit your system configuration and schedule
+before using these scripts.
+
+Syntactically, @file{backup-specs} is a shell script, containing
+mainly variable assignments. However, any valid shell construct
+is allowed in this file. Particularly, you may wish to define
+functions within that script (e.g., see @code{RESTORE_BEGIN} below).
+For more information about shell script syntax, please refer to
+@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
+g_02, the definition of the Shell Command Language}. See also
+@ref{Top,,Bash Features,bashref,Bash Reference Manual}.
+
+The shell variables controlling behavior of @code{backup} and
+@code{restore} are described in the following subsections.
+
+@menu
+* General-Purpose Variables::
+* Magnetic Tape Control::
+* User Hooks::
+* backup-specs example:: An Example Text of @file{Backup-specs}
+@end menu
+
+@node General-Purpose Variables
+@subsection General-Purpose Variables
+
+@defvr {Backup variable} ADMINISTRATOR
+The user name of the backup administrator. @code{Backup} scripts
+sends a backup report to this address.
+@end defvr
+
+@defvr {Backup variable} BACKUP_HOUR
+The hour at which the backups are done. This can be a number from 0
+to 23, or the time specification in form @var{hours}:@var{minutes},
+or the string @samp{now}.
+
+This variable is used by @code{backup}. Its value may be overridden
+using @option{--time} option (@pxref{Scripted Backups}).
+@end defvr
+
+@defvr {Backup variable} TAPE_FILE
+
+The device @command{tar} writes the archive to. If @var{TAPE_FILE}
+is a remote archive (@pxref{remote-dev}), backup script will suppose
+that your @command{mt} is able to access remote devices. If @var{RSH}
+(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
+invocations of @command{mt}.
+@end defvr
+
+@defvr {Backup variable} BLOCKING
+
+The blocking factor @command{tar} will use when writing the dump archive.
+@xref{Blocking Factor}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_DIRS
+
+A list of file systems to be dumped (for @code{backup}), or restored
+(for @code{restore}). You can include any directory
+name in the list --- subdirectories on that file system will be
+included, regardless of how they may look to other networked machines.
+Subdirectories on other file systems will be ignored.
+
+The host name specifies which host to run @command{tar} on, and should
+normally be the host that actually contains the file system. However,
+the host machine must have @GNUTAR{} installed, and
+must be able to access the directory containing the backup scripts and
+their support files using the same file name that is used on the
+machine where the scripts are run (ie. what @command{pwd} will print
+when in that directory on that machine). If the host that contains
+the file system does not have this capability, you can specify another
+host as long as it can access the file system through NFS.
+
+If the list of file systems is very long you may wish to put it
+in a separate file. This file is usually named
+@file{/etc/backup/dirs}, but this name may be overridden in
+@file{backup-specs} using @code{DIRLIST} variable.
+@end defvr
+
+@defvr {Backup variable} DIRLIST
+
+A path to the file containing the list of the file systems to backup
+or restore. By default it is @file{/etc/backup/dirs}.
+@end defvr
+
+@defvr {Backup variable} BACKUP_FILES
+
+A list of individual files to be dumped (for @code{backup}), or restored
+(for @code{restore}). These should be accessible from the machine on
+which the backup script is run.
+
+If the list of file systems is very long you may wish to store it
+in a separate file. This file is usually named
+@file{/etc/backup/files}, but this name may be overridden in
+@file{backup-specs} using @code{FILELIST} variable.
+@end defvr
+
+@defvr {Backup variable} FILELIST
+
+A path to the file containing the list of the individual files to backup
+or restore. By default it is @file{/etc/backup/files}.
+@end defvr
+
+@defvr {Backup variable} MT
+
+Full file name of @command{mt} binary.
+@end defvr
+
+@defvr {Backup variable} RSH
+@anchor{RSH}
+Full file name of @command{rsh} binary or its equivalent. You may wish to
+set it to @code{ssh}, to improve security. In this case you will have
+to use public key authentication.
+@end defvr
+
+@defvr {Backup variable} RSH_COMMAND
+
+Full file name of @command{rsh} binary on remote mashines. This will
+be passed via @option{--rsh-command} option to the remote invocation
+of @GNUTAR{}.
+@end defvr
+
+@defvr {Backup variable} VOLNO_FILE
+
+Name of temporary file to hold volume numbers. This needs to be accessible
+by all the machines which have file systems to be dumped.
+@end defvr
+
+@defvr {Backup variable} XLIST
+
+Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
+located on the remote machine and containing the list of files to
+be excluded from the backup. Exclude file lists are searched in
+/etc/tar-backup directory. A common use for exclude file lists
+is to exclude files containing security-sensitive information
+(e.g., @file{/etc/shadow} from backups).
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} SLEEP_TIME
+
+Time to sleep between dumps of any two successive file systems
+
+This variable affects only @code{backup}.
+@end defvr
+
+@defvr {Backup variable} DUMP_REMIND_SCRIPT
+
+Script to be run when it's time to insert a new tape in for the next
+volume. Administrators may want to tailor this script for their site.
+If this variable isn't set, @GNUTAR{} will display its built-in
+prompt, and will expect confirmation from the console.
+
+The built-in prompt for POSIX locale is:
+
+@smallexample
+Prepare volume #@var{n} for `@var{archive}' and hit return:
+@end smallexample
+
+@noindent
+where @var{n} is the ordinal number of the volume to be created and
+@var{archive} is archive file or device name.
+
+If you run @GNUTAR{} under a different locale, the translation of
+the above prompt to the locale's language will be used.
+
+@end defvr
+
+@defvr {Backup variable} SLEEP_MESSAGE
+
+Message to display on the terminal while waiting for dump time. Usually
+this will just be some literal text.
+@end defvr
+
+@defvr {Backup variable} TAR
+
+Full file name of the @GNUTAR{} executable. If this is not set, backup
+scripts will search @command{tar} in the current shell path.
+@end defvr
+
+@node Magnetic Tape Control
+@subsection Magnetic Tape Control
+
+Backup scripts access tape device using special @dfn{hook functions}.
+These functions take a single argument -- the name of the tape
+device. Their names are kept in the following variables:
+
+@defvr {Backup variable} MT_BEGIN
+The name of @dfn{begin} function. This function is called before
+accessing the drive. By default it retensions the tape:
+
+@smallexample
+MT_BEGIN=mt_begin
+
+mt_begin() @{
+ mt -f "$1" retension
+@}
+@end smallexample
+@end defvr
+
+@defvr {Backup variable} MT_REWIND
+The name of @dfn{rewind} function. The default definition is as
+follows:
+
+@smallexample
+MT_REWIND=mt_rewind
+
+mt_rewind() @{
+ mt -f "$1" rewind
+@}
+@end smallexample
+
+@end defvr
+
+@defvr {Backup variable} MT_OFFLINE
+The name of the function switching the tape off line. By default
+it is defined as follows:
+
+@smallexample
+MT_OFFLINE=mt_offline
+
+mt_offline() @{
+ mt -f "$1" offl
+@}
+@end smallexample
+@end defvr
+
+@defvr {Backup variable} MT_STATUS
+The name of the function used to obtain the status of the archive device,
+including error count. Default definition:
+
+@smallexample
+MT_STATUS=mt_status
+
+mt_status() @{
+ mt -f "$1" status
+@}
+@end smallexample
+@end defvr
+
+@node User Hooks
+@subsection User Hooks
+
+@dfn{User hooks} are shell functions executed before and after
+each @command{tar} invocation. Thus, there are @dfn{backup
+hooks}, which are executed before and after dumping each file
+system, and @dfn{restore hooks}, executed before and
+after restoring a file system. Each user hook is a shell function
+taking four arguments:
-@node Backup Parameters
-@section Setting Parameters for Backups and Restoration
+@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname}
+Its arguments are:
-The file @file{backup-specs} specifies backup parameters for the
-backup and restoration scripts provided with @command{tar}. You must
-edit @file{backup-specs} to fit your system configuration and schedule
-before using these scripts.
+@table @var
+@item level
+Current backup or restore level.
-Syntactically, @file{backup-specs} is a shell script, containing
-mainly variable assignments. However, any valid shell construct
-is allowed in this file. Particularly, you may wish to define
-functions within that script (e.g., see @code{RESTORE_BEGIN} below).
-For more information about shell script syntax, please refer to
-@url{http://www.opengroup.org/onlinepubs/009695399/utilities/xcu_chap02.html#ta
-g_02, the definition of the Shell Command Language}. See also
-@ref{Top,,Bash Features,bashref,Bash Reference Manual}.
+@item host
+Name or IP address of the host machine being dumped or restored.
-The shell variables controlling behavior of @code{backup} and
-@code{restore} are described in the following subsections.
+@item fs
+Full path name to the file system being dumped or restored.
-@menu
-* General-Purpose Variables::
-* Magnetic Tape Control::
-* User Hooks::
-* backup-specs example:: An Example Text of @file{Backup-specs}
-@end menu
+@item fsname
+File system name with directory separators replaced with colons. This
+is useful, e.g., for creating unique files.
+@end table
+@end deffn
-@node General-Purpose Variables
-@subsection General-Purpose Variables
+Following variables keep the names of user hook functions
-@defvr {Backup variable} ADMINISTRATOR
-The user name of the backup administrator. @code{Backup} scripts
-sends a backup report to this address.
+@defvr {Backup variable} DUMP_BEGIN
+Dump begin function. It is executed before dumping the file system.
@end defvr
-@defvr {Backup variable} BACKUP_HOUR
-The hour at which the backups are done. This can be a number from 0
-to 23, or the time specification in form @var{hours}:@var{minutes},
-or the string @samp{now}.
-
-This variable is used by @code{backup}. Its value may be overridden
-using @option{--time} option (@pxref{Scripted Backups}).
+@defvr {Backup variable} DUMP_END
+Executed after dumping the file system.
@end defvr
-@defvr {Backup variable} TAPE_FILE
+@defvr {Backup variable} RESTORE_BEGIN
+Executed before restoring the file system.
+@end defvr
-The device @command{tar} writes the archive to. If @var{TAPE_FILE}
-is a remote archive (@pxref{remote-dev}), backup script will suppose
-that your @command{mt} is able to access remote devices. If @var{RSH}
-(@pxref{RSH}) is set, @option{--rsh-command} option will be added to
-invocations of @command{mt}.
+@defvr {Backup variable} RESTORE_END
+Executed after restoring the file system.
@end defvr
-@defvr {Backup variable} BLOCKING
+@node backup-specs example
+@subsection An Example Text of @file{Backup-specs}
-The blocking factor @command{tar} will use when writing the dump archive.
-@xref{Blocking Factor}.
-@end defvr
+The following is an example of @file{backup-specs}:
-@defvr {Backup variable} BACKUP_DIRS
+@smallexample
+# site-specific parameters for file system backup.
-A list of file systems to be dumped (for @code{backup}), or restored
-(for @code{restore}). You can include any directory
-name in the list --- subdirectories on that file system will be
-included, regardless of how they may look to other networked machines.
-Subdirectories on other file systems will be ignored.
+ADMINISTRATOR=friedman
+BACKUP_HOUR=1
+TAPE_FILE=/dev/nrsmt0
-The host name specifies which host to run @command{tar} on, and should
-normally be the host that actually contains the file system. However,
-the host machine must have @GNUTAR{} installed, and
-must be able to access the directory containing the backup scripts and
-their support files using the same file name that is used on the
-machine where the scripts are run (ie. what @command{pwd} will print
-when in that directory on that machine). If the host that contains
-the file system does not have this capability, you can specify another
-host as long as it can access the file system through NFS.
+# Use @code{ssh} instead of the less secure @code{rsh}
+RSH=/usr/bin/ssh
+RSH_COMMAND=/usr/bin/ssh
-If the list of file systems is very long you may wish to put it
-in a separate file. This file is usually named
-@file{/etc/backup/dirs}, but this name may be overridden in
-@file{backup-specs} using @code{DIRLIST} variable.
-@end defvr
+# Override MT_STATUS function:
+my_status() @{
+ mts -t $TAPE_FILE
+@}
+MT_STATUS=my_status
-@defvr {Backup variable} DIRLIST
+# Disable MT_OFFLINE function
+MT_OFFLINE=:
-A path to the file containing the list of the file systems to backup
-or restore. By default it is @file{/etc/backup/dirs}.
-@end defvr
+BLOCKING=124
+BACKUP_DIRS="
+ albert:/fs/fsf
+ apple-gunkies:/gd
+ albert:/fs/gd2
+ albert:/fs/gp
+ geech:/usr/jla
+ churchy:/usr/roland
+ albert:/
+ albert:/usr
+ apple-gunkies:/
+ apple-gunkies:/usr
+ gnu:/hack
+ gnu:/u
+ apple-gunkies:/com/mailer/gnu
+ apple-gunkies:/com/archive/gnu"
-@defvr {Backup variable} BACKUP_FILES
+BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
-A list of individual files to be dumped (for @code{backup}), or restored
-(for @code{restore}). These should be accessible from the machine on
-which the backup script is run.
+@end smallexample
-If the list of file systems is very long you may wish to store it
-in a separate file. This file is usually named
-@file{/etc/backup/files}, but this name may be overridden in
-@file{backup-specs} using @code{FILELIST} variable.
-@end defvr
+@node Scripted Backups
+@section Using the Backup Scripts
-@defvr {Backup variable} FILELIST
+The syntax for running a backup script is:
-A path to the file containing the list of the individual files to backup
-or restore. By default it is @file{/etc/backup/files}.
-@end defvr
+@smallexample
+backup --level=@var{level} --time=@var{time}
+@end smallexample
-@defvr {Backup variable} MT
+The @option{level} option requests the dump level. Thus, to produce
+a full dump, specify @code{--level=0} (this is the default, so
+@option{--level} may be omitted if its value is @code{0}).
+@footnote{For backward compatibility, the @code{backup} will also
+try to deduce the requested dump level from the name of the
+script itself. If the name consists of a string @samp{level-}
+followed by a single decimal digit, that digit is taken as
+the dump level number. Thus, you may create a link from @code{backup}
+to @code{level-1} and then run @code{level-1} whenever you need to
+create a level one dump.}
-Full file name of @command{mt} binary.
-@end defvr
+The @option{--time} option determines when should the backup be
+run. @var{Time} may take three forms:
-@defvr {Backup variable} RSH
-@anchor{RSH}
-Full file name of @command{rsh} binary or its equivalent. You may wish to
-set it to @code{ssh}, to improve security. In this case you will have
-to use public key authentication.
-@end defvr
+@table @asis
+@item @var{hh}:@var{mm}
-@defvr {Backup variable} RSH_COMMAND
+The dump must be run at @var{hh} hours @var{mm} minutes.
-Full file name of @command{rsh} binary on remote mashines. This will
-be passed via @option{--rsh-command} option to the remote invocation
-of @GNUTAR{}.
-@end defvr
+@item @var{hh}
-@defvr {Backup variable} VOLNO_FILE
+The dump must be run at @var{hh} hours
-Name of temporary file to hold volume numbers. This needs to be accessible
-by all the machines which have file systems to be dumped.
-@end defvr
+@item now
-@defvr {Backup variable} XLIST
+The dump must be run immediately.
+@end table
-Name of @dfn{exclude file list}. An @dfn{exclude file list} is a file
-located on the remote machine and containing the list of files to
-be excluded from the backup. Exclude file lists are searched in
-/etc/tar-backup directory. A common use for exclude file lists
-is to exclude files containing security-sensitive information
-(e.g., @file{/etc/shadow} from backups).
+You should start a script with a tape or disk mounted. Once you
+start a script, it prompts you for new tapes or disks as it
+needs them. Media volumes don't have to correspond to archive
+files --- a multi-volume archive can be started in the middle of a
+tape that already contains the end of another multi-volume archive.
+The @code{restore} script prompts for media by its archive volume,
+so to avoid an error message you should keep track of which tape
+(or disk) contains which volume of the archive (@pxref{Scripted
+Restoration}).
-This variable affects only @code{backup}.
-@end defvr
+The backup scripts write two files on the file system. The first is a
+record file in @file{/etc/tar-backup/}, which is used by the scripts
+to store and retrieve information about which files were dumped. This
+file is not meant to be read by humans, and should not be deleted by
+them. @xref{Snapshot Files}, for a more detailed explanation of this
+file.
-@defvr {Backup variable} SLEEP_TIME
+The second file is a log file containing the names of the file systems
+and files dumped, what time the backup was made, and any error
+messages that were generated, as well as how much space was left in
+the media volume after the last volume of the archive was written.
+You should check this log file after every backup. The file name is
+@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy}
+represents current date, and @var{n} represents current dump level number.
-Time to sleep between dumps of any two successive file systems
+The script also prints the name of each system being dumped to the
+standard output.
-This variable affects only @code{backup}.
-@end defvr
+Following is the full list of options accepted by @code{backup}
+script:
-@defvr {Backup variable} DUMP_REMIND_SCRIPT
+@table @option
+@item -l @var{level}
+@itemx --level=@var{level}
+Do backup level @var{level} (default 0).
-Script to be run when it's time to insert a new tape in for the next
-volume. Administrators may want to tailor this script for their site.
-If this variable isn't set, @GNUTAR{} will display its built-in prompt
-@FIXME-xref{describe it somewhere!}, and will expect confirmation from
-the console.
-@end defvr
+@item -f
+@itemx --force
+Force backup even if today's log file already exists.
-@defvr {Backup variable} SLEEP_MESSAGE
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
+
+@item -t @var{start-time}
+@itemx --time=@var{start-time}
+Wait till @var{time}, then do backup.
-Message to display on the terminal while waiting for dump time. Usually
-this will just be some literal text.
-@end defvr
+@item -h
+@itemx --help
+Display short help message and exit.
-@defvr {Backup variable} TAR
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
-Full file name of the @GNUTAR{} executable. If this is not set, backup
-scripts will search @command{tar} in the current shell path.
-@end defvr
-@node Magnetic Tape Control
-@subsection Magnetic Tape Control
+@node Scripted Restoration
+@section Using the Restore Script
-Backup scripts access tape device using special @dfn{hook functions}.
-These functions take a single argument -- the name of the tape
-device. Their names are kept in the following variables:
+To restore files that were archived using a scripted backup, use the
+@code{restore} script. Its usage is quite straightforward. In the
+simplest form, invoke @code{restore --all}, it will
+then restore all the file systems and files specified in
+@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
-@defvr {Backup variable} MT_BEGIN
-The name of @dfn{begin} function. This function is called before
-accessing the drive. By default it retensions the tape:
+You may select the file systems (and/or files) to restore by
+giving @code{restore} list of @dfn{patterns} in its command
+line. For example, running
@smallexample
-MT_BEGIN=mt_begin
-
-mt_begin() @{
- mt -f "$1" retension
-@}
+restore 'albert:*'
@end smallexample
-@end defvr
-@defvr {Backup variable} MT_REWIND
-The name of @dfn{rewind} function. The default definition is as
-follows:
+@noindent
+will restore all file systems on the machine @samp{albert}. A more
+complicated example:
@smallexample
-MT_REWIND=mt_rewind
-
-mt_rewind() @{
- mt -f "$1" rewind
-@}
+restore 'albert:*' '*:/var'
@end smallexample
-@end defvr
+@noindent
+This command will restore all file systems on the machine @samp{albert}
+as well as @file{/var} file system on all machines.
-@defvr {Backup variable} MT_OFFLINE
-The name of the function switching the tape off line. By default
-it is defined as follows:
+By default @code{restore} will start restoring files from the lowest
+available dump level (usually zero) and will continue through
+all available dump levels. There may be situations where such a
+thorough restore is not necessary. For example, you may wish to
+restore only files from the recent level one backup. To do so,
+use @option{--level} option, as shown in the example below:
@smallexample
-MT_OFFLINE=mt_offline
-
-mt_offline() @{
- mt -f "$1" offl
-@}
+restore --level=1
@end smallexample
-@end defvr
-@defvr {Backup variable} MT_STATUS
-The name of the function used to obtain the status of the archive device,
-including error count. Default definition:
+The full list of options accepted by @code{restore} follows:
-@smallexample
-MT_STATUS=mt_status
+@table @option
+@item -a
+@itemx --all
+Restore all file systems and files specified in @file{backup-specs}
-mt_status() @{
- mt -f "$1" status
-@}
-@end smallexample
-@end defvr
+@item -l @var{level}
+@itemx --level=@var{level}
+Start restoring from the given backup level, instead of the default 0.
-@node User Hooks
-@subsection User Hooks
+@item -v[@var{level}]
+@itemx --verbose[=@var{level}]
+Set verbosity level. The higher the level is, the more debugging
+information will be output during execution. Devault @var{level}
+is 100, which means the highest debugging level.
-@dfn{User hooks} are shell functions executed before and after
-each @command{tar} invocation. Thus, there are @dfn{backup
-hooks}, which are executed before and after dumping each file
-system, and @dfn{restore hooks}, executed before and
-after restoring a file system. Each user hook is a shell function
-taking four arguments:
+@item -h
+@itemx --help
+Display short help message and exit.
-@deffn {User Hook Function} hook @var{level} @var{host} @var{fs} @var{fsname}
-Its arguments are:
+@item -V
+@itemx --version
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
+@end table
-@table @var
-@item level
-Current backup or restore level.
+You should start the restore script with the media containing the
+first volume of the archive mounted. The script will prompt for other
+volumes as they are needed. If the archive is on tape, you don't need
+to rewind the tape to to its beginning---if the tape head is
+positioned past the beginning of the archive, the script will rewind
+the tape as needed. @FIXME-xref{Media, for a discussion of tape
+positioning.}
-@item host
-Name or IP address of the host machine being dumped or restored.
+@quotation
+@strong{Warning:} The script will delete files from the active file
+system if they were not in the file system when the archive was made.
+@end quotation
-@item fs
-Full path name to the file system being dumped or restored.
+@xref{Incremental Dumps}, for an explanation of how the script makes
+that determination.
-@item fsname
-File system name with directory separators replaced with colons. This
-is useful, e.g., for creating unique files.
-@end table
-@end deffn
+@node Choosing
+@chapter Choosing Files and Names for @command{tar}
+@UNREVISED
-Following variables keep the names of user hook functions
+Certain options to @command{tar} enable you to specify a name for your
+archive. Other options let you decide which files to include or exclude
+from the archive, based on when or whether files were modified, whether
+the file names do or don't match specified patterns, or whether files
+are in specified directories.
-@defvr {Backup variable} DUMP_BEGIN
-Dump begin function. It is executed before dumping the file system.
-@end defvr
+This chapter discusses these options in detail.
-@defvr {Backup variable} DUMP_END
-Executed after dumping the file system.
-@end defvr
+@menu
+* file:: Choosing the Archive's Name
+* Selecting Archive Members::
+* files:: Reading Names from a File
+* exclude:: Excluding Some Files
+* wildcards:: Wildcards Patterns and Matching
+* quoting styles:: Ways of Quoting Special Characters in Names
+* transform:: Modifying File and Member Names
+* after:: Operating Only on New Files
+* recurse:: Descending into Directories
+* one:: Crossing File System Boundaries
+@end menu
-@defvr {Backup variable} RESTORE_BEGIN
-Executed before restoring the file system.
-@end defvr
+@node file
+@section Choosing and Naming Archive Files
+@UNREVISED
-@defvr {Backup variable} RESTORE_END
-Executed after restoring the file system.
-@end defvr
+@cindex Naming an archive
+@cindex Archive Name
+@cindex Choosing an archive file
+@cindex Where is the archive?
+By default, @command{tar} uses an archive file name that was compiled when
+it was built on the system; usually this name refers to some physical
+tape drive on the machine. However, the person who installed @command{tar}
+on the system may not have set the default to a meaningful value as far as
+most users are concerned. As a result, you will usually want to tell
+@command{tar} where to find (or create) the archive. The
+@option{--file=@var{archive-name}} (@option{-f @var{archive-name}})
+option allows you to either specify or name a file to use as the archive
+instead of the default archive file location.
-@node backup-specs example
-@subsection An Example Text of @file{Backup-specs}
+@table @option
+@opindex file, short description
+@item --file=@var{archive-name}
+@itemx -f @var{archive-name}
+Name the archive to create or operate on. Use in conjunction with
+any operation.
+@end table
-The following is an example of @file{backup-specs}:
+For example, in this @command{tar} command,
@smallexample
-# site-specific parameters for file system backup.
+$ @kbd{tar -cvf collection.tar blues folk jazz}
+@end smallexample
-ADMINISTRATOR=friedman
-BACKUP_HOUR=1
-TAPE_FILE=/dev/nrsmt0
+@noindent
+@file{collection.tar} is the name of the archive. It must directly
+follow the @option{-f} option, since whatever directly follows @option{-f}
+@emph{will} end up naming the archive. If you neglect to specify an
+archive name, you may end up overwriting a file in the working directory
+with the archive you create since @command{tar} will use this file's name
+for the archive name.
-# Use @code{ssh} instead of the less secure @code{rsh}
-RSH=/usr/bin/ssh
-RSH_COMMAND=/usr/bin/ssh
+An archive can be saved as a file in the file system, sent through a
+pipe or over a network, or written to an I/O device such as a tape,
+floppy disk, or CD write drive.
-# Override MT_STATUS function:
-my_status() @{
- mts -t $TAPE_FILE
-@}
-MT_STATUS=my_status
+@cindex Writing new archives
+@cindex Archive creation
+If you do not name the archive, @command{tar} uses the value of the
+environment variable @env{TAPE} as the file name for the archive. If
+that is not available, @command{tar} uses a default, compiled-in archive
+name, usually that for tape unit zero (ie. @file{/dev/tu00}).
-# Disable MT_OFFLINE function
-MT_OFFLINE=:
+@cindex Standard input and output
+@cindex tar to standard input and output
+If you use @file{-} as an @var{archive-name}, @command{tar} reads the
+archive from standard input (when listing or extracting files), or
+writes it to standard output (when creating an archive). If you use
+@file{-} as an @var{archive-name} when modifying an archive,
+@command{tar} reads the original archive from its standard input and
+writes the entire new archive to its standard output.
-BLOCKING=124
-BACKUP_DIRS="
- albert:/fs/fsf
- apple-gunkies:/gd
- albert:/fs/gd2
- albert:/fs/gp
- geech:/usr/jla
- churchy:/usr/roland
- albert:/
- albert:/usr
- apple-gunkies:/
- apple-gunkies:/usr
- gnu:/hack
- gnu:/u
- apple-gunkies:/com/mailer/gnu
- apple-gunkies:/com/archive/gnu"
+The following example is a convenient way of copying directory
+hierarchy from @file{sourcedir} to @file{targetdir}.
+
+@smallexample
+$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
+@end smallexample
-BACKUP_FILES="/com/mailer/aliases /com/mailer/league*[a-z]"
+The @option{-C} option allows to avoid using subshells:
+@smallexample
+$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
@end smallexample
-@node Scripted Backups
-@section Using the Backup Scripts
+In both examples above, the leftmost @command{tar} invocation archives
+the contents of @file{sourcedir} to the standard output, while the
+rightmost one reads this archive from its standard input and
+extracts it. The @option{-p} option tells it to restore permissions
+of the extracted files.
-The syntax for running a backup script is:
+@cindex Remote devices
+@cindex tar to a remote device
+@anchor{remote-dev}
+To specify an archive file on a device attached to a remote machine,
+use the following:
@smallexample
-backup --level=@var{level} --time=@var{time}
+@kbd{--file=@var{hostname}:/@var{dev}/@var{file-name}}
@end smallexample
-The @option{level} option requests the dump level. Thus, to produce
-a full dump, specify @code{--level=0} (this is the default, so
-@option{--level} may be omitted if its value is @code{0}).
-@footnote{For backward compatibility, the @code{backup} will also
-try to deduce the requested dump level from the name of the
-script itself. If the name consists of a string @samp{level-}
-followed by a single decimal digit, that digit is taken as
-the dump level number. Thus, you may create a link from @code{backup}
-to @code{level-1} and then run @code{level-1} whenever you need to
-create a level one dump.}
-
-The @option{--time} option determines when should the backup be
-run. @var{Time} may take three forms:
+@noindent
+@command{tar} will complete the remote connection, if possible, and
+prompt you for a username and password. If you use
+@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
+will complete the remote connection, if possible, using your username
+as the username on the remote machine.
-@table @asis
-@item @var{hh}:@var{mm}
+@cindex Local and remote archives
+@anchor{local and remote archives}
+If the archive file name includes a colon (@samp{:}), then it is assumed
+to be a file on another machine. If the archive file is
+@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
+host @var{host}. The remote host is accessed using the @command{rsh}
+program, with a username of @var{user}. If the username is omitted
+(along with the @samp{@@} sign), then your user name will be used.
+(This is the normal @command{rsh} behavior.) It is necessary for the
+remote machine, in addition to permitting your @command{rsh} access, to
+have the @file{rmt} program installed (This command is included in
+the @GNUTAR{} distribution and by default is installed under
+@file{@var{prefix}/libexec/rmt}, were @var{prefix} means your
+installation prefix). If you need to use a file whose name includes a
+colon, then the remote tape drive behavior
+can be inhibited by using the @option{--force-local} option.
-The dump must be run at @var{hh} hours @var{mm} minutes.
+When the archive is being created to @file{/dev/null}, @GNUTAR{}
+tries to minimize input and output operations. The Amanda backup
+system, when used with @GNUTAR{}, has an initial sizing pass which
+uses this feature.
-@item @var{hh}
+@node Selecting Archive Members
+@section Selecting Archive Members
+@cindex Specifying files to act on
+@cindex Specifying archive members
-The dump must be run at @var{hh} hours
+@dfn{File Name arguments} specify which files in the file system
+@command{tar} operates on, when creating or adding to an archive, or which
+archive members @command{tar} operates on, when reading or deleting from
+an archive. @xref{Operations}.
-@item now
+To specify file names, you can include them as the last arguments on
+the command line, as follows:
+@smallexample
+@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
+@end smallexample
-The dump must be run immediately.
-@end table
+If a file name begins with dash (@samp{-}), precede it with
+@option{--add-file} option to prevent it from being treated as an
+option.
-You should start a script with a tape or disk mounted. Once you
-start a script, it prompts you for new tapes or disks as it
-needs them. Media volumes don't have to correspond to archive
-files --- a multi-volume archive can be started in the middle of a
-tape that already contains the end of another multi-volume archive.
-The @code{restore} script prompts for media by its archive volume,
-so to avoid an error message you should keep track of which tape
-(or disk) contains which volume of the archive (@pxref{Scripted
-Restoration}).
+If you specify a directory name as a file name argument, all the files
+in that directory are operated on by @command{tar}.
-The backup scripts write two files on the file system. The first is a
-record file in @file{/etc/tar-backup/}, which is used by the scripts
-to store and retrieve information about which files were dumped. This
-file is not meant to be read by humans, and should not be deleted by
-them. @xref{Snapshot Files}, for a more detailed explanation of this
-file.
+If you do not specify files, @command{tar} behavior differs depending
+on the operation mode as described below:
-The second file is a log file containing the names of the file systems
-and files dumped, what time the backup was made, and any error
-messages that were generated, as well as how much space was left in
-the media volume after the last volume of the archive was written.
-You should check this log file after every backup. The file name is
-@file{log-@var{mm-dd-yyyy}-level-@var{n}}, where @var{mm-dd-yyyy}
-represents current date, and @var{n} represents current dump level number.
+When @command{tar} is invoked with @option{--create} (@option{-c}),
+@command{tar} will stop immediately, reporting the following:
-The script also prints the name of each system being dumped to the
-standard output.
+@smallexample
+@group
+$ @kbd{tar cf a.tar}
+tar: Cowardly refusing to create an empty archive
+Try `tar --help' or `tar --usage' for more information.
+@end group
+@end smallexample
-Following is the full list of options accepted by @code{backup}
-script:
+If you specify either @option{--list} (@option{-t}) or
+@option{--extract} (@option{--get}, @option{-x}), @command{tar}
+operates on all the archive members in the archive.
-@table @option
-@item -l @var{level}
-@itemx --level=@var{level}
-Do backup level @var{level} (default 0).
+If run with @option{--diff} option, tar will compare the archive with
+the contents of the current working directory.
-@item -f
-@itemx --force
-Force backup even if today's log file already exists.
+If you specify any other operation, @command{tar} does nothing.
-@item -v[@var{level}]
-@itemx --verbose[=@var{level}]
-Set verbosity level. The higher the level is, the more debugging
-information will be output during execution. Devault @var{level}
-is 100, which means the highest debugging level.
+By default, @command{tar} takes file names from the command line. However,
+there are other ways to specify file or member names, or to modify the
+manner in which @command{tar} selects the files or members upon which to
+operate. In general, these methods work both for specifying the names
+of files and archive members.
-@item -t @var{start-time}
-@itemx --time=@var{start-time}
-Wait till @var{time}, then do backup.
+@node files
+@section Reading Names from a File
-@item -h
-@itemx --help
-Display short help message and exit.
+@cindex Reading file names from a file
+@cindex Lists of file names
+@cindex File Name arguments, alternatives
+Instead of giving the names of files or archive members on the command
+line, you can put the names into a file, and then use the
+@option{--files-from=@var{file-of-names}} (@option{-T
+@var{file-of-names}}) option to @command{tar}. Give the name of the
+file which contains the list of files to include as the argument to
+@option{--files-from}. In the list, the file names should be separated by
+newlines. You will frequently use this option when you have generated
+the list of files to archive with the @command{find} utility.
-@item -V
-@itemx --version
-Display information about the program's name, version, origin and legal
-status, all on standard output, and then exit successfully.
+@table @option
+@opindex files-from
+@item --files-from=@var{file-name}
+@itemx -T @var{file-name}
+Get names to extract or create from file @var{file-name}.
@end table
+If you give a single dash as a file name for @option{--files-from}, (i.e.,
+you specify either @code{--files-from=-} or @code{-T -}), then the file
+names are read from standard input.
-@node Scripted Restoration
-@section Using the Restore Script
+Unless you are running @command{tar} with @option{--create}, you can not use
+both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
+command.
-To restore files that were archived using a scripted backup, use the
-@code{restore} script. Its usage is quite straightforward. In the
-simplest form, invoke @code{restore --all}, it will
-then restore all the file systems and files specified in
-@file{backup-specs} (@pxref{General-Purpose Variables,BACKUP_DIRS}).
+Any number of @option{-T} options can be given in the command line.
-You may select the file systems (and/or files) to restore by
-giving @code{restore} list of @dfn{patterns} in its command
-line. For example, running
+The following example shows how to use @command{find} to generate a list of
+files smaller than 400K in length and put that list into a file
+called @file{small-files}. You can then use the @option{-T} option to
+@command{tar} to specify the files from that file, @file{small-files}, to
+create the archive @file{little.tgz}. (The @option{-z} option to
+@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for
+more information.)
@smallexample
-restore 'albert:*'
+$ @kbd{find . -size -400 -print > small-files}
+$ @kbd{tar -c -v -z -T small-files -f little.tgz}
@end smallexample
@noindent
-will restore all file systems on the machine @samp{albert}. A more
-complicated example:
+In the file list given by @option{-T} option, any file name beginning
+with @samp{-} character is considered a @command{tar} option and is
+processed accordingly.@footnote{Versions of @GNUTAR{} up to 1.15.1
+recognized only @option{-C} option in file lists, and only if the
+option and its argument occupied two consecutive lines.} For example,
+the common use of this feature is to change to another directory by
+specifying @option{-C} option:
+
+@smallexample
+@group
+$ @kbd{cat list}
+-C/etc
+passwd
+hosts
+-C/lib
+libc.a
+$ @kbd{tar -c -f foo.tar --files-from list}
+@end group
+@end smallexample
+
+@noindent
+In this example, @command{tar} will first switch to @file{/etc}
+directory and add files @file{passwd} and @file{hosts} to the
+archive. Then it will change to @file{/lib} directory and will archive
+the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will
+contain:
+
+@smallexample
+@group
+$ @kbd{tar tf foo.tar}
+passwd
+hosts
+libc.a
+@end group
+@end smallexample
+
+@noindent
+@opindex directory, using in @option{--files-from} argument
+Notice that the option parsing algorithm used with @option{-T} is
+stricter than the one used by shell. Namely, when specifying option
+arguments, you should observe the following rules:
+
+@itemize @bullet
+@item
+When using short (single-letter) option form, its argument must
+immediately follow the option letter, without any intervening
+whitespace. For example: @code{-Cdir}.
+
+@item
+When using long option form, the option argument must be separated
+from the option by a single equal sign. No whitespace is allowed on
+any side of the equal sign. For example: @code{--directory=dir}.
+
+@item
+For both short and long option forms, the option argument can be given
+on the next line after the option name, e.g.:
@smallexample
-restore 'albert:*' '*:/var'
+@group
+--directory
+dir
+@end group
@end smallexample
@noindent
-This command will restore all file systems on the machine @samp{albert}
-as well as @file{/var} file system on all machines.
-
-By default @code{restore} will start restoring files from the lowest
-available dump level (usually zero) and will continue through
-all available dump levels. There may be situations where such a
-thorough restore is not necessary. For example, you may wish to
-restore only files from the recent level one backup. To do so,
-use @option{--level} option, as shown in the example below:
+and
@smallexample
-restore --level=1
+@group
+-C
+dir
+@end group
@end smallexample
+@end itemize
-The full list of options accepted by @code{restore} follows:
-
-@table @option
-@item -a
-@itemx --all
-Restore all file systems and files specified in @file{backup-specs}
+@opindex add-file
+If you happen to have a file whose name starts with @samp{-},
+precede it with @option{--add-file} option to prevent it from
+being recognized as an option. For example: @code{--add-file=--my-file}.
-@item -l @var{level}
-@itemx --level=@var{level}
-Start restoring from the given backup level, instead of the default 0.
+@menu
+* nul::
+@end menu
-@item -v[@var{level}]
-@itemx --verbose[=@var{level}]
-Set verbosity level. The higher the level is, the more debugging
-information will be output during execution. Devault @var{level}
-is 100, which means the highest debugging level.
+@node nul
+@subsection @code{NUL} Terminated File Names
-@item -h
-@itemx --help
-Display short help message and exit.
+@cindex File names, terminated by @code{NUL}
+@cindex @code{NUL} terminated file names
+The @option{--null} option causes
+@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}})
+to read file names terminated by a @code{NUL} instead of a newline, so
+files whose names contain newlines can be archived using
+@option{--files-from}.
-@item -V
-@itemx --version
-Display information about the program's name, version, origin and legal
-status, all on standard output, and then exit successfully.
+@table @option
+@opindex null
+@item --null
+Only consider @code{NUL} terminated file names, instead of files that
+terminate in a newline.
@end table
-You should start the restore script with the media containing the
-first volume of the archive mounted. The script will prompt for other
-volumes as they are needed. If the archive is on tape, you don't need
-to rewind the tape to to its beginning---if the tape head is
-positioned past the beginning of the archive, the script will rewind
-the tape as needed. @FIXME-xref{Media, for a discussion of tape
-positioning.}
-
-@quotation
-@strong{Warning:} The script will delete files from the active file
-system if they were not in the file system when the archive was made.
-@end quotation
-
-@xref{Incremental Dumps}, for an explanation of how the script makes
-that determination.
-
-@node Choosing
-@chapter Choosing Files and Names for @command{tar}
-@UNREVISED
+The @option{--null} option is just like the one in @acronym{GNU}
+@command{xargs} and @command{cpio}, and is useful with the
+@option{-print0} predicate of @acronym{GNU} @command{find}. In
+@command{tar}, @option{--null} also disables special handling for
+file names that begin with dash.
-Certain options to @command{tar} enable you to specify a name for your
-archive. Other options let you decide which files to include or exclude
-from the archive, based on when or whether files were modified, whether
-the file names do or don't match specified patterns, or whether files
-are in specified directories.
+This example shows how to use @command{find} to generate a list of files
+larger than 800K in length and put that list into a file called
+@file{long-files}. The @option{-print0} option to @command{find} is just
+like @option{-print}, except that it separates files with a @code{NUL}
+rather than with a newline. You can then run @command{tar} with both the
+@option{--null} and @option{-T} options to specify that @command{tar} get the
+files from that file, @file{long-files}, to create the archive
+@file{big.tgz}. The @option{--null} option to @command{tar} will cause
+@command{tar} to recognize the @code{NUL} separator between files.
-This chapter discusses these options in detail.
+@smallexample
+$ @kbd{find . -size +800 -print0 > long-files}
+$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
+@end smallexample
-@menu
-* file:: Choosing the Archive's Name
-* Selecting Archive Members::
-* files:: Reading Names from a File
-* exclude:: Excluding Some Files
-* Wildcards:: Wildcards Patterns and Matching
-* after:: Operating Only on New Files
-* recurse:: Descending into Directories
-* one:: Crossing File System Boundaries
-@end menu
+@FIXME{say anything else here to conclude the section?}
-@node file
-@section Choosing and Naming Archive Files
+@node exclude
+@section Excluding Some Files
@UNREVISED
-@cindex Naming an archive
-@cindex Archive Name
-@cindex Choosing an archive file
-@cindex Where is the archive?
-By default, @command{tar} uses an archive file name that was compiled when
-it was built on the system; usually this name refers to some physical
-tape drive on the machine. However, the person who installed @command{tar}
-on the system may not have set the default to a meaningful value as far as
-most users are concerned. As a result, you will usually want to tell
-@command{tar} where to find (or create) the archive. The
-@option{--file=@var{archive-name}} (@option{-f @var{archive-name}})
-option allows you to either specify or name a file to use as the archive
-instead of the default archive file location.
+@cindex File names, excluding files by
+@cindex Excluding files by name and pattern
+@cindex Excluding files by file system
+To avoid operating on files whose names match a particular pattern,
+use the @option{--exclude} or @option{--exclude-from} options.
@table @option
-@opindex file, short description
-@item --file=@var{archive-name}
-@itemx -f @var{archive-name}
-Name the archive to create or operate on. Use in conjunction with
-any operation.
+@opindex exclude
+@item --exclude=@var{pattern}
+Causes @command{tar} to ignore files that match the @var{pattern}.
@end table
-For example, in this @command{tar} command,
+@findex exclude
+The @option{--exclude=@var{pattern}} option prevents any file or
+member whose name matches the shell wildcard (@var{pattern}) from
+being operated on.
+For example, to create an archive with all the contents of the directory
+@file{src} except for files whose names end in @file{.o}, use the
+command @samp{tar -cf src.tar --exclude='*.o' src}.
-@smallexample
-$ @kbd{tar -cvf collection.tar blues folk jazz}
-@end smallexample
+You may give multiple @option{--exclude} options.
-@noindent
-@file{collection.tar} is the name of the archive. It must directly
-follow the @option{-f} option, since whatever directly follows @option{-f}
-@emph{will} end up naming the archive. If you neglect to specify an
-archive name, you may end up overwriting a file in the working directory
-with the archive you create since @command{tar} will use this file's name
-for the archive name.
+@table @option
+@opindex exclude-from
+@item --exclude-from=@var{file}
+@itemx -X @var{file}
+Causes @command{tar} to ignore files that match the patterns listed in
+@var{file}.
+@end table
-An archive can be saved as a file in the file system, sent through a
-pipe or over a network, or written to an I/O device such as a tape,
-floppy disk, or CD write drive.
+@findex exclude-from
+Use the @option{--exclude-from} option to read a
+list of patterns, one per line, from @var{file}; @command{tar} will
+ignore files matching those patterns. Thus if @command{tar} is
+called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
+single line @file{*.o}, no files whose names end in @file{.o} will be
+added to the archive.
-@cindex Writing new archives
-@cindex Archive creation
-If you do not name the archive, @command{tar} uses the value of the
-environment variable @env{TAPE} as the file name for the archive. If
-that is not available, @command{tar} uses a default, compiled-in archive
-name, usually that for tape unit zero (ie. @file{/dev/tu00}).
+@table @option
+@opindex exclude-caches
+@item --exclude-caches
+Causes @command{tar} to ignore directories containing a cache directory tag.
+@end table
-@cindex Standard input and output
-@cindex tar to standard input and output
-If you use @file{-} as an @var{archive-name}, @command{tar} reads the
-archive from standard input (when listing or extracting files), or
-writes it to standard output (when creating an archive). If you use
-@file{-} as an @var{archive-name} when modifying an archive,
-@command{tar} reads the original archive from its standard input and
-writes the entire new archive to its standard output.
+@findex exclude-caches
+When creating an archive, the @option{--exclude-caches} option causes
+@command{tar} to exclude all directories that contain a @dfn{cache
+directory tag}. A cache directory tag is a short file with the
+well-known name @file{CACHEDIR.TAG} and having a standard header
+specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
+Various applications write cache directory tags into directories they
+use to hold regenerable, non-precious data, so that such data can be
+more easily excluded from backups.
-The following example is a convenient way of copying directory
-hierarchy from @file{sourcedir} to @file{targetdir}.
+@menu
+* problems with exclude::
+@end menu
-@smallexample
-$ @kbd{(cd sourcedir; tar -cf - .) | (cd targetdir; tar -xpf -)}
-@end smallexample
+@node problems with exclude
+@unnumberedsubsec Problems with Using the @code{exclude} Options
-The @option{-C} option allows to avoid using subshells:
+@opindex exclude, potential problems with
+Some users find @samp{exclude} options confusing. Here are some common
+pitfalls:
-@smallexample
-$ @kbd{tar -C sourcedir -cf - . | tar -C targetdir -xpf -}
-@end smallexample
+@itemize @bullet
+@item
+The main operating mode of @command{tar} does not act on a path name
+explicitly listed on the command line if one of its file name
+components is excluded. In the example above, if
+you create an archive and exclude files that end with @samp{*.o}, but
+explicitly name the file @samp{dir.o/foo} after all the options have been
+listed, @samp{dir.o/foo} will be excluded from the archive.
-In both examples above, the leftmost @command{tar} invocation archives
-the contents of @file{sourcedir} to the standard output, while the
-rightmost one reads this archive from its standard input and
-extracts it. The @option{-p} option tells it to restore permissions
-of the extracted files.
+@item
+You can sometimes confuse the meanings of @option{--exclude} and
+@option{--exclude-from}. Be careful: use @option{--exclude} when files
+to be excluded are given as a pattern on the command line. Use
+@option{--exclude-from} to introduce the name of a file which contains
+a list of patterns, one per line; each of these patterns can exclude
+zero, one, or many files.
+
+@item
+When you use @option{--exclude=@var{pattern}}, be sure to quote the
+@var{pattern} parameter, so @GNUTAR{} sees wildcard characters
+like @samp{*}. If you do not do this, the shell might expand the
+@samp{*} itself using files at hand, so @command{tar} might receive a
+list of files instead of one pattern, or none at all, making the
+command somewhat illegal. This might not correspond to what you want.
-@cindex Remote devices
-@cindex tar to a remote device
-@anchor{remote-dev}
-To specify an archive file on a device attached to a remote machine,
-use the following:
+For example, write:
@smallexample
-@kbd{--file=@var{hostname}:/@var{dev}/@var{file-name}}
+$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
@end smallexample
@noindent
-@command{tar} will complete the remote connection, if possible, and
-prompt you for a username and password. If you use
-@option{--file=@@@var{hostname}:/@var{dev}/@var{file-name}}, @command{tar}
-will complete the remote connection, if possible, using your username
-as the username on the remote machine.
-
-@cindex Local and remote archives
-@anchor{local and remote archives}
-If the archive file name includes a colon (@samp{:}), then it is assumed
-to be a file on another machine. If the archive file is
-@samp{@var{user}@@@var{host}:@var{file}}, then @var{file} is used on the
-host @var{host}. The remote host is accessed using the @command{rsh}
-program, with a username of @var{user}. If the username is omitted
-(along with the @samp{@@} sign), then your user name will be used.
-(This is the normal @command{rsh} behavior.) It is necessary for the
-remote machine, in addition to permitting your @command{rsh} access, to
-have the @file{rmt} program installed (This command is included in
-the @GNUTAR{} distribution and by default is installed under
-@file{@var{prefix}/libexec/rmt}, were @var{prefix} means your
-installation prefix). If you need to use a file whose name includes a
-colon, then the remote tape drive behavior
-can be inhibited by using the @option{--force-local} option.
-
-When the archive is being created to @file{/dev/null}, @GNUTAR{}
-tries to minimize input and output operations. The Amanda backup
-system, when used with @GNUTAR{}, has an initial sizing pass which
-uses this feature.
-
-@node Selecting Archive Members
-@section Selecting Archive Members
-@cindex Specifying files to act on
-@cindex Specifying archive members
-
-@dfn{File Name arguments} specify which files in the file system
-@command{tar} operates on, when creating or adding to an archive, or which
-archive members @command{tar} operates on, when reading or deleting from
-an archive. @xref{Operations}.
+rather than:
-To specify file names, you can include them as the last arguments on
-the command line, as follows:
@smallexample
-@kbd{tar} @var{operation} [@var{option1} @var{option2} @dots{}] [@var{file name-1} @var{file name-2} @dots{}]
+# @emph{Wrong!}
+$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
@end smallexample
-If a file name begins with dash (@samp{-}), precede it with
-@option{--add-file} option to prevent it from being treated as an
-option.
+@item
+You must use use shell syntax, or globbing, rather than @code{regexp}
+syntax, when using exclude options in @command{tar}. If you try to use
+@code{regexp} syntax to describe files to be excluded, your command
+might fail.
-If you specify a directory name as a file name argument, all the files
-in that directory are operated on by @command{tar}.
+@item
+@FIXME{The change in semantics must have occurred before 1.11,
+so I doubt if it is worth mentioning at all. Anyway, should at
+least specify in which version the semantics changed.}
+In earlier versions of @command{tar}, what is now the
+@option{--exclude-from} option was called @option{--exclude} instead.
+Now, @option{--exclude} applies to patterns listed on the command
+line and @option{--exclude-from} applies to patterns listed in a
+file.
-If you do not specify files, @command{tar} behavior differs depending
-on the operation mode as described below:
+@end itemize
-When @command{tar} is invoked with @option{--create} (@option{-c}),
-@command{tar} will stop immediately, reporting the following:
+@node wildcards
+@section Wildcards Patterns and Matching
-@smallexample
-@group
-$ @kbd{tar cf a.tar}
-tar: Cowardly refusing to create an empty archive
-Try `tar --help' or `tar --usage' for more information.
-@end group
-@end smallexample
+@dfn{Globbing} is the operation by which @dfn{wildcard} characters,
+@samp{*} or @samp{?} for example, are replaced and expanded into all
+existing files matching the given pattern. @GNUTAR{} can use wildcard
+patterns for matching (or globbing) archive members when extracting
+from or listing an archive. Wildcard patterns are also used for
+verifying volume labels of @command{tar} archives. This section has the
+purpose of explaining wildcard syntax for @command{tar}.
-If you specify either @option{--list} (@option{-t}) or
-@option{--extract} (@option{--get}, @option{-x}), @command{tar}
-operates on all the archive members in the archive.
+@FIXME{the next few paragraphs need work.}
-If run with @option{--diff} option, tar will compare the archive with
-the contents of the current working directory.
+A @var{pattern} should be written according to shell syntax, using wildcard
+characters to effect globbing. Most characters in the pattern stand
+for themselves in the matched string, and case is significant: @samp{a}
+will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
+pattern matches any single character in the matched string. The character
+@samp{*} in the pattern matches zero, one, or more single characters in
+the matched string. The character @samp{\} says to take the following
+character of the pattern @emph{literally}; it is useful when one needs to
+match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
-If you specify any other operation, @command{tar} does nothing.
+The character @samp{[}, up to the matching @samp{]}, introduces a character
+class. A @dfn{character class} is a list of acceptable characters
+for the next single character of the matched string. For example,
+@samp{[abcde]} would match any of the first five letters of the alphabet.
+Note that within a character class, all of the ``special characters''
+listed above other than @samp{\} lose their special meaning; for example,
+@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
+@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
+the characters @samp{-} and @samp{]} must either come @emph{first} or
+@emph{last} in a character class.)
-By default, @command{tar} takes file names from the command line. However,
-there are other ways to specify file or member names, or to modify the
-manner in which @command{tar} selects the files or members upon which to
-operate. In general, these methods work both for specifying the names
-of files and archive members.
+@cindex Excluding characters from a character class
+@cindex Character class, excluding characters from
+If the first character of the class after the opening @samp{[}
+is @samp{!} or @samp{^}, then the meaning of the class is reversed.
+Rather than listing character to match, it lists those characters which
+are @emph{forbidden} as the next single character of the matched string.
-@node files
-@section Reading Names from a File
+Other characters of the class stand for themselves. The special
+construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
+letters, is meant to represent all characters between @var{a} and
+@var{e}, inclusive.
-@cindex Reading file names from a file
-@cindex Lists of file names
-@cindex File Name arguments, alternatives
-Instead of giving the names of files or archive members on the command
-line, you can put the names into a file, and then use the
-@option{--files-from=@var{file-of-names}} (@option{-T
-@var{file-of-names}}) option to @command{tar}. Give the name of the
-file which contains the list of files to include as the argument to
-@option{--files-from}. In the list, the file names should be separated by
-newlines. You will frequently use this option when you have generated
-the list of files to archive with the @command{find} utility.
+@FIXME{need to add a sentence or so here to make this clear for those
+who don't have dan around.}
-@table @option
-@opindex files-from
-@item --files-from=@var{file-name}
-@itemx -T @var{file-name}
-Get names to extract or create from file @var{file-name}.
-@end table
+Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
+special for wildcard matches. However, if a pattern completely matches
+a directory prefix of a matched string, then it matches the full matched
+string: thus, excluding a directory also excludes all the files beneath it.
-If you give a single dash as a file name for @option{--files-from}, (i.e.,
-you specify either @code{--files-from=-} or @code{-T -}), then the file
-names are read from standard input.
+@menu
+* controlling pattern-matching::
+@end menu
-Unless you are running @command{tar} with @option{--create}, you can not use
-both @code{--files-from=-} and @code{--file=-} (@code{-f -}) in the same
-command.
+@node controlling pattern-matching
+@unnumberedsubsec Controlling Pattern-Matching
-Any number of @option{-T} options can be given in the command line.
+For the purposes of this section, we call @dfn{exclusion members} all
+member names obtained while processing @option{--exclude} and
+@option{--exclude-from} options, and @dfn{inclusion members} those
+member names that were given in the command line or read from the file
+specified with @option{--files-from} option.
-The following example shows how to use @command{find} to generate a list of
-files smaller than 400K in length and put that list into a file
-called @file{small-files}. You can then use the @option{-T} option to
-@command{tar} to specify the files from that file, @file{small-files}, to
-create the archive @file{little.tgz}. (The @option{-z} option to
-@command{tar} compresses the archive with @command{gzip}; @pxref{gzip} for
-more information.)
+These two pairs of member lists are used in the following operations:
+@option{--diff}, @option{--extract}, @option{--list},
+@option{--update}.
-@smallexample
-$ @kbd{find . -size -400 -print > small-files}
-$ @kbd{tar -c -v -z -T small-files -f little.tgz}
-@end smallexample
+There are no inclusion members in create mode (@option{--create} and
+@option{--append}), since in this mode the names obtained from the
+command line refer to @emph{files}, not archive members.
-@noindent
-In the file list given by @option{-T} option, any file name beginning
-with @samp{-} character is considered a @command{tar} option and is
-processed accordingly.@footnote{Versions of @GNUTAR{} up to 1.15.1
-recognized only @option{-C} option in file lists, and only if the
-option and its argument occupied two consecutive lines.} For example,
-the common use of this feature is to change to another directory by
-specifying @option{-C} option:
+By default, inclusion members are compared with archive members
+literally @footnote{Notice that earlier @GNUTAR{} versions used
+globbing for inclusion members, which contradicted to UNIX98
+specification and was not documented. @xref{Changes}, for more
+information on this and other changes.} and exclusion members are
+treated as globbing patterns. For example:
@smallexample
@group
-$ @kbd{cat list}
--C/etc
-passwd
-hosts
--C/lib
-libc.a
-$ @kbd{tar -c -f foo.tar --files-from list}
+$ @kbd{tar tf foo.tar}
+a.c
+b.c
+a.txt
+[remarks]
+# @i{Member names are used verbatim:}
+$ @kbd{tar -xf foo.tar -v '[remarks]'}
+[remarks]
+# @i{Exclude member names are globbed:}
+$ @kbd{tar -xf foo.tar -v --exclude '*.c'}
+a.txt
+[remarks]
@end group
@end smallexample
+This behavior can be altered by using the following options:
+
+@table @option
+@opindex wildcards
+@item --wildcards
+Treat all member names as wildcards.
+
+@opindex no-wildcards
+@item --no-wildcards
+Treat all member names as literal strings.
+@end table
+
+Thus, to extract files whose names end in @samp{.c}, you can use:
+
+@smallexample
+$ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
+a.c
+b.c
+@end smallexample
+
@noindent
-In this example, @command{tar} will first switch to @file{/etc}
-directory and add files @file{passwd} and @file{hosts} to the
-archive. Then it will change to @file{/lib} directory and will archive
-the file @file{libc.a}. Thus, the resulting archive @file{foo.tar} will
-contain:
+Notice quoting of the pattern to prevent the shell from interpreting
+it.
+
+The effect of @option{--wildcards} option is cancelled by
+@option{--no-wildcards}. This can be used to pass part of
+the command line arguments verbatim and other part as globbing
+patterns. For example, the following invocation:
@smallexample
-@group
-$ @kbd{tar tf foo.tar}
-passwd
-hosts
-libc.a
-@end group
+$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
@end smallexample
@noindent
-@opindex directory, using in @option{--files-from} argument
-Notice that the option parsing algorithm used with @option{-T} is
-stricter than the one used by shell. Namely, when specifying option
-arguments, you should observe the following rules:
+instructs @command{tar} to extract from @file{foo.tar} all files whose
+names end in @samp{.txt} and the file named @file{[remarks]}.
-@itemize @bullet
-@item
-When using short (single-letter) option form, its argument must
-immediately follow the option letter, without any intervening
-whitespace. For example: @code{-Cdir}.
+Normally, a pattern matches a name if an initial subsequence of the
+name's components matches the pattern, where @samp{*}, @samp{?}, and
+@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards,
+and wildcards can match @samp{/}.
-@item
-When using long option form, the option argument must be separated
-from the option by a single equal sign. No whitespace is allowed on
-any side of the equal sign. For example: @code{--directory=dir}.
+Other than optionally stripping leading @samp{/} from names
+(@pxref{absolute}), patterns and names are used as-is. For
+example, trailing @samp{/} is not trimmed from a user-specified name
+before deciding whether to exclude it.
-@item
-For both short and long option forms, the option argument can be given
-on the next line after the option name, e.g.:
+However, this matching procedure can be altered by the options listed
+below. These options accumulate. For example:
@smallexample
-@group
---directory
-dir
-@end group
+--ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
@end smallexample
@noindent
-and
+ignores case when excluding @samp{makefile}, but not when excluding
+@samp{readme}.
-@smallexample
-@group
--C
-dir
-@end group
-@end smallexample
-@end itemize
+@table @option
+@opindex anchored
+@opindex no-anchored
+@item --anchored
+@itemx --no-anchored
+If anchored, a pattern must match an initial subsequence
+of the name's components. Otherwise, the pattern can match any
+subsequence. Default is @option{--no-anchored} for exclusion members
+and @option{--anchored} inclusion members.
-@opindex add-file
-If you happen to have a file whose name starts with @samp{-},
-precede it with @option{--add-file} option to prevent it from
-being recognized as an option. For example: @code{--add-file=--my-file}.
+@opindex ignore-case
+@opindex no-ignore-case
+@item --ignore-case
+@itemx --no-ignore-case
+When ignoring case, upper-case patterns match lower-case names and vice versa.
+When not ignoring case (the default), matching is case-sensitive.
-@menu
-* nul::
-@end menu
+@opindex wildcards-match-slash
+@opindex no-wildcards-match-slash
+@item --wildcards-match-slash
+@itemx --no-wildcards-match-slash
+When wildcards match slash (the default for exclusion members), a
+wildcard like @samp{*} in the pattern can match a @samp{/} in the
+name. Otherwise, @samp{/} is matched only by @samp{/}.
-@node nul
-@subsection @code{NUL} Terminated File Names
+@end table
-@cindex File names, terminated by @code{NUL}
-@cindex @code{NUL} terminated file names
-The @option{--null} option causes
-@option{--files-from=@var{file-of-names}} (@option{-T @var{file-of-names}})
-to read file names terminated by a @code{NUL} instead of a newline, so
-files whose names contain newlines can be archived using
-@option{--files-from}.
+The @option{--recursion} and @option{--no-recursion} options
+(@pxref{recurse}) also affect how member patterns are interpreted. If
+recursion is in effect, a pattern matches a name if it matches any of
+the name's parent directories.
-@table @option
-@opindex null
-@item --null
-Only consider @code{NUL} terminated file names, instead of files that
-terminate in a newline.
-@end table
+The following table summarizes pattern-matching default values:
-The @option{--null} option is just like the one in @acronym{GNU}
-@command{xargs} and @command{cpio}, and is useful with the
-@option{-print0} predicate of @acronym{GNU} @command{find}. In
-@command{tar}, @option{--null} also disables special handling for
-file names that begin with dash.
+@multitable @columnfractions .3 .7
+@headitem Members @tab Default settings
+@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash}
+@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash}
+@end multitable
-This example shows how to use @command{find} to generate a list of files
-larger than 800K in length and put that list into a file called
-@file{long-files}. The @option{-print0} option to @command{find} is just
-like @option{-print}, except that it separates files with a @code{NUL}
-rather than with a newline. You can then run @command{tar} with both the
-@option{--null} and @option{-T} options to specify that @command{tar} get the
-files from that file, @file{long-files}, to create the archive
-@file{big.tgz}. The @option{--null} option to @command{tar} will cause
-@command{tar} to recognize the @code{NUL} separator between files.
+@node quoting styles
+@section Quoting Member Names
-@smallexample
-$ @kbd{find . -size +800 -print0 > long-files}
-$ @kbd{tar -c -v --null --files-from=long-files --file=big.tar}
-@end smallexample
+When displaying member names, @command{tar} takes care to avoid
+ambiguities caused by certain characters. This is called @dfn{name
+quoting}. The characters in question are:
-@FIXME{say anything else here to conclude the section?}
+@itemize @bullet
+@item Non-printable control characters:
-@node exclude
-@section Excluding Some Files
-@UNREVISED
+@multitable @columnfractions 0.20 0.10 0.60
+@headitem Character @tab ASCII @tab Character name
+@item \a @tab 7 @tab Audible bell
+@item \b @tab 8 @tab Backspace
+@item \f @tab 12 @tab Form feed
+@item \n @tab 10 @tab New line
+@item \r @tab 13 @tab Carriage return
+@item \t @tab 9 @tab Horizontal tabulation
+@item \v @tab 11 @tab Vertical tabulation
+@end multitable
-@cindex File names, excluding files by
-@cindex Excluding files by name and pattern
-@cindex Excluding files by file system
-To avoid operating on files whose names match a particular pattern,
-use the @option{--exclude} or @option{--exclude-from} options.
+@item Space (ASCII 32)
-@table @option
-@opindex exclude
-@item --exclude=@var{pattern}
-Causes @command{tar} to ignore files that match the @var{pattern}.
-@end table
+@item Single and double quotes (@samp{'} and @samp{"})
-@findex exclude
-The @option{--exclude=@var{pattern}} option prevents any file or
-member whose name matches the shell wildcard (@var{pattern}) from
-being operated on.
-For example, to create an archive with all the contents of the directory
-@file{src} except for files whose names end in @file{.o}, use the
-command @samp{tar -cf src.tar --exclude='*.o' src}.
+@item Backslash (@samp{\})
+@end itemize
-You may give multiple @option{--exclude} options.
+The exact way @command{tar} uses to quote these characters depends on
+the @dfn{quoting style}. The default quoting style, called
+@dfn{escape} (see below), uses backslash notation to represent control
+characters, space and backslash. Using this quoting style, control
+characters are represented as listed in column @samp{Character} in the
+above table, a space is printed as @samp{\ } and a backslash as @samp{\\}.
+
+@GNUTAR{} offers seven distinct quoting styles, which can be selected
+using @option{--quoting-style} option:
@table @option
-@opindex exclude-from
-@item --exclude-from=@var{file}
-@itemx -X @var{file}
-Causes @command{tar} to ignore files that match the patterns listed in
-@var{file}.
+@item --quoting-style=@var{style}
+@opindex quoting-style
+
+Sets quoting style. Valid values for @var{style} argument are:
+literal, shell, shell-always, c, escape, locale, clocale.
@end table
-@findex exclude-from
-Use the @option{--exclude-from} option to read a
-list of patterns, one per line, from @var{file}; @command{tar} will
-ignore files matching those patterns. Thus if @command{tar} is
-called as @w{@samp{tar -c -X foo .}} and the file @file{foo} contains a
-single line @file{*.o}, no files whose names end in @file{.o} will be
-added to the archive.
+These styles are described in detail below. To illustrate their
+effect, we will use an imaginary tar archive @file{arch.tar}
+containing the following members:
-@table @option
-@opindex exclude-caches
-@item --exclude-caches
-Causes @command{tar} to ignore directories containing a cache directory tag.
-@end table
+@smallexample
+@group
+# 1. Contains horizontal tabulation character.
+a tab
+# 2. Contains newline character
+a
+newline
+# 3. Contains a space
+a space
+# 4. Contains double quotes
+a"double"quote
+# 5. Contains single quotes
+a'single'quote
+# 6. Contains a backslash character:
+a\backslash
+@end group
+@end smallexample
-@findex exclude-caches
-When creating an archive, the @option{--exclude-caches} option causes
-@command{tar} to exclude all directories that contain a @dfn{cache
-directory tag}. A cache directory tag is a short file with the
-well-known name @file{CACHEDIR.TAG} and having a standard header
-specified in @url{http://www.brynosaurus.com/cachedir/spec.html}.
-Various applications write cache directory tags into directories they
-use to hold regenerable, non-precious data, so that such data can be
-more easily excluded from backups.
+Here is how usual @command{ls} command would have listed them, if they
+had existed in the current working directory:
+
+@smallexample
+@group
+$ @kbd{ls}
+a\ttab
+a\nnewline
+a\ space
+a"double"quote
+a'single'quote
+a\\backslash
+@end group
+@end smallexample
+
+Quoting styles:
+
+@table @samp
+@item literal
+No quoting, display each character as is:
+
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=literal}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\backslash
+./a tab
+./a
+newline
+@end group
+@end smallexample
-@menu
-* problems with exclude::
-@end menu
+@item shell
+Display characters the same way Bourne shell does:
+control characters, except @samp{\t} and @samp{\n}, are printed using
+backslash escapes, @samp{\t} and @samp{\n} are printed as is, and a
+single quote is printed as @samp{\'}. If a name contains any quoted
+characters, it is enclosed in single quotes. In particular, if a name
+contains single quotes, it is printed as several single-quoted strings:
-@node problems with exclude
-@unnumberedsubsec Problems with Using the @code{exclude} Options
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=shell}
+./
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
+@end group
+@end smallexample
-@opindex exclude, potential problems with
-Some users find @samp{exclude} options confusing. Here are some common
-pitfalls:
+@item shell-always
+Same as @samp{shell}, but the names are always enclosed in single
+quotes:
-@itemize @bullet
-@item
-The main operating mode of @command{tar} does not act on a path name
-explicitly listed on the command line if one of its file name
-components is excluded. In the example above, if
-you create an archive and exclude files that end with @samp{*.o}, but
-explicitly name the file @samp{dir.o/foo} after all the options have been
-listed, @samp{dir.o/foo} will be excluded from the archive.
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=shell-always}
+'./'
+'./a space'
+'./a'\''single'\''quote'
+'./a"double"quote'
+'./a\backslash'
+'./a tab'
+'./a
+newline'
+@end group
+@end smallexample
-@item
-You can sometimes confuse the meanings of @option{--exclude} and
-@option{--exclude-from}. Be careful: use @option{--exclude} when files
-to be excluded are given as a pattern on the command line. Use
-@option{--exclude-from} to introduce the name of a file which contains
-a list of patterns, one per line; each of these patterns can exclude
-zero, one, or many files.
+@item c
+Use the notation of the C programming language. All names are
+enclosed in double quotes. Control characters are quoted using
+backslash notations, double quotes are represented as @samp{\"},
+backslash characters are represented as @samp{\\}. Single quotes and
+spaces are not quoted:
-@item
-When you use @option{--exclude=@var{pattern}}, be sure to quote the
-@var{pattern} parameter, so @GNUTAR{} sees wildcard characters
-like @samp{*}. If you do not do this, the shell might expand the
-@samp{*} itself using files at hand, so @command{tar} might receive a
-list of files instead of one pattern, or none at all, making the
-command somewhat illegal. This might not correspond to what you want.
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=c}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
+@end group
+@end smallexample
-For example, write:
+@item escape
+Control characters are printed using backslash notation, a space is
+printed as @samp{\ } and a backslash as @samp{\\}. This is the
+default quoting style, unless it was changed when configured the
+package.
@smallexample
-$ @kbd{tar -c -f @var{archive.tar} --exclude '*.o' @var{directory}}
+@group
+$ @kbd{tar tf arch.tar --quoting-style=escape}
+./
+./a space
+./a'single'quote
+./a"double"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+@end group
@end smallexample
-@noindent
-rather than:
+@item locale
+Control characters, single quote and backslash are printed using
+backslash notation. All names are quoted using left and right
+quotation marks, appropriate to the current locale. If it does not
+define quotation marks, use @samp{`} as left and @samp{'} as right
+quotation marks. Any occurrences of the right quotation mark in a
+name are escaped with @samp{\}, for example:
+
+For example:
@smallexample
-# @emph{Wrong!}
-$ @kbd{tar -c -f @var{archive.tar} --exclude *.o @var{directory}}
+@group
+$ @kbd{tar tf arch.tar --quoting-style=locale}
+`./'
+`./a space'
+`./a\'single\'quote'
+`./a"double"quote'
+`./a\\backslash'
+`./a\ttab'
+`./a\nnewline'
+@end group
@end smallexample
-@item
-You must use use shell syntax, or globbing, rather than @code{regexp}
-syntax, when using exclude options in @command{tar}. If you try to use
-@code{regexp} syntax to describe files to be excluded, your command
-might fail.
+@item clocale
+Same as @samp{locale}, but @samp{"} is used for both left and right
+quotation marks, if not provided by the currently selected locale:
-@item
-@FIXME{The change in semantics must have occurred before 1.11,
-so I doubt if it is worth mentioning at all. Anyway, should at
-least specify in which version the semantics changed.}
-In earlier versions of @command{tar}, what is now the
-@option{--exclude-from} option was called @option{--exclude} instead.
-Now, @option{--exclude} applies to patterns listed on the command
-line and @option{--exclude-from} applies to patterns listed in a
-file.
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=clocale}
+"./"
+"./a space"
+"./a'single'quote"
+"./a\"double\"quote"
+"./a\\backslash"
+"./a\ttab"
+"./a\nnewline"
+@end group
+@end smallexample
+@end table
-@end itemize
+You can specify which characters should be quoted in addition to those
+implied by the current quoting style:
-@node Wildcards
-@section Wildcards Patterns and Matching
+@table @option
+@item --quote-chars=@var{string}
+Always quote characters from @var{string}, even if the selected
+quoting style would not quote them.
+@end table
-@dfn{Globbing} is the operation by which @dfn{wildcard} characters,
-@samp{*} or @samp{?} for example, are replaced and expanded into all
-existing files matching the given pattern. @GNUTAR{} can use wildcard
-patterns for matching (or globbing) archive members when extracting
-from or listing an archive. Wildcard patterns are also used for
-verifying volume labels of @command{tar} archives. This section has the
-purpose of explaining wildcard syntax for @command{tar}.
+For example, using @samp{escape} quoting (compare with the usual
+escape listing above):
-@FIXME{the next few paragraphs need work.}
+@smallexample
+@group
+$ @kbd{tar tf arch.tar --quoting-style=escape --quote-chars=' "'}
+./
+./a\ space
+./a'single'quote
+./a\"double\"quote
+./a\\backslash
+./a\ttab
+./a\nnewline
+@end group
+@end smallexample
-A @var{pattern} should be written according to shell syntax, using wildcard
-characters to effect globbing. Most characters in the pattern stand
-for themselves in the matched string, and case is significant: @samp{a}
-will match only @samp{a}, and not @samp{A}. The character @samp{?} in the
-pattern matches any single character in the matched string. The character
-@samp{*} in the pattern matches zero, one, or more single characters in
-the matched string. The character @samp{\} says to take the following
-character of the pattern @emph{literally}; it is useful when one needs to
-match the @samp{?}, @samp{*}, @samp{[} or @samp{\} characters, themselves.
+To disable quoting of such additional characters, use the following
+option:
-The character @samp{[}, up to the matching @samp{]}, introduces a character
-class. A @dfn{character class} is a list of acceptable characters
-for the next single character of the matched string. For example,
-@samp{[abcde]} would match any of the first five letters of the alphabet.
-Note that within a character class, all of the ``special characters''
-listed above other than @samp{\} lose their special meaning; for example,
-@samp{[-\\[*?]]} would match any of the characters, @samp{-}, @samp{\},
-@samp{[}, @samp{*}, @samp{?}, or @samp{]}. (Due to parsing constraints,
-the characters @samp{-} and @samp{]} must either come @emph{first} or
-@emph{last} in a character class.)
+@table @option
+@item --no-quote-chars=@var{string}
+Remove characters listed in @var{string} from the list of quoted
+characters set by the previous @option{--quote-chars} option.
+@end table
-@cindex Excluding characters from a character class
-@cindex Character class, excluding characters from
-If the first character of the class after the opening @samp{[}
-is @samp{!} or @samp{^}, then the meaning of the class is reversed.
-Rather than listing character to match, it lists those characters which
-are @emph{forbidden} as the next single character of the matched string.
+This option is particularly useful if you have added
+@option{--quote-chars} to your @env{TAR_OPTIONS} (@pxref{TAR_OPTIONS})
+and wish to disable it for the current invocation.
-Other characters of the class stand for themselves. The special
-construction @samp{[@var{a}-@var{e}]}, using an hyphen between two
-letters, is meant to represent all characters between @var{a} and
-@var{e}, inclusive.
+Note, that @option{--no-quote-chars} does @emph{not} disable those
+characters that are quoted by default in the selected quoting style.
-@FIXME{need to add a sentence or so here to make this clear for those
-who don't have dan around.}
+@node transform
+@section Modifying File and Member Names
+
+@command{Tar} archives contain detailed information about files stored
+in them and full file names are part of that information. When
+storing file to an archive, its file name is recorded in the archive
+along with the actual file contents. When restoring from an archive,
+a file is created on disk with exactly the same name as that stored
+in the archive. In the majority of cases this is the desired behavior
+of a file archiver. However, there are some cases when it is not.
+
+First of all, it is often unsafe to extract archive members with
+absolute file names or those that begin with a @file{../}. @GNUTAR{}
+takes special precautions when extracting such names and provides a
+special option for handling them, which is described in
+@ref{absolute}.
+
+Secondly, you may wish to extract file names without some leading
+directory components, or with otherwise modified names. In other
+cases it is desirable to store files under differing names in the
+archive.
-Periods (@samp{.}) or forward slashes (@samp{/}) are not considered
-special for wildcard matches. However, if a pattern completely matches
-a directory prefix of a matched string, then it matches the full matched
-string: thus, excluding a directory also excludes all the files beneath it.
+@GNUTAR{} provides two options for these needs.
-@menu
-* controlling pattern-matching::
-@end menu
+@table @option
+@opindex strip-components
+@item --strip-components=@var{number}
+Strip given @var{number} of leading components from file names before
+extraction.
+@end table
-@node controlling pattern-matching
-@unnumberedsubsec Controlling Pattern-Matching
+For example, suppose you have archived whole @file{/usr} hierarchy to
+a tar archive named @file{usr.tar}. Among other files, this archive
+contains @file{usr/include/stdlib.h}, which you wish to extract to
+the current working directory. To do so, you type:
-For the purposes of this section, we call @dfn{exclusion members} all
-member names obtained while processing @option{--exclude} and
-@option{--exclude-from} options, and @dfn{inclusion members} those
-member names that were given in the command line or read from the file
-specified with @option{--files-from} option.
+@smallexample
+$ @kbd{tar -xf usr.tar --strip=2 usr/include/stdlib.h}
+@end smallexample
-These two pairs of member lists are used in the following operations:
-@option{--diff}, @option{--extract}, @option{--list},
-@option{--update}.
+The option @option{--strip=2} instructs @command{tar} to strip the
+two leading components (@file{usr/} and @file{include/}) off the file
+name.
-There are no inclusion members in create mode (@option{--create} and
-@option{--append}), since in this mode the names obtained from the
-command line refer to @emph{files}, not archive members.
+If you add to the above invocation @option{--verbose} (@option{-v})
+option, you will note that the verbose listing still contains the
+full file name, with the two removed components still in place. This
+can be inconvenient, so @command{tar} provides a special option for
+altering this behavior:
-By default, inclusion members are compared with archive members
-literally @footnote{Notice that earlier @GNUTAR{} versions used
-globbing for inclusion members, which contradicted to UNIX98
-specification and was not documented. @xref{Changes}, for more
-information on this and other changes} and exclusion members are
-treated as globbing patterns. For example:
+@anchor{show-transformed-names}
+@table @option
+@opindex --show-transformed-names
+@item --show-transformed-names
+Display file or member names with all requested transformations
+applied.
+@end table
+
+@noindent
+For example:
@smallexample
@group
-$ @kbd{tar tf foo.tar}
-a.c
-b.c
-a.txt
-[remarks]
-# @i{Member names are used verbatim:}
-$ @kbd{tar -xf foo.tar -v '[remarks]'}
-[remarks]
-# @i{Exclude member names are globbed:}
-$ @kbd{tar -xf foo.tar -v --exclude '*.c'}
-a.txt
-[remarks]
+$ @kbd{tar -xf usr.tar -v --strip=2 usr/include/stdlib.h}
+usr/include/stdlib.h
+$ @kbd{tar -xf usr.tar -v --strip=2 --show-transformed usr/include/stdlib.h}
+stdlib.h
@end group
@end smallexample
-This behavior can be altered by using the following options:
+Notice that in both cases the file is @file{stdlib.h} extracted to the
+current working directory, @option{--show-transformed-names} affects
+only the way its name is displayed.
-@table @option
-@opindex wildcards
-@item --wildcards
-Treat all member names as wildcards.
+This option is especially useful for verifying whether the invocation
+will have the desired effect. Thus, before running
-@opindex no-wildcards
-@item --no-wildcards
-Treat all member names as literal strings.
-@end table
+@smallexample
+$ @kbd{tar -x --strip=@var{n}}
+@end smallexample
-Thus, to extract files whose names end in @samp{.c}, you can use:
+@noindent
+it is often advisable to run
@smallexample
-$ @kbd{tar -xf foo.tar -v --wildcards '*.c'}
-a.c
-b.c
+$ @kbd{tar -t -v --show-transformed --strip=@var{n}}
@end smallexample
@noindent
-Notice quoting of the pattern to prevent the shell from interpreting
-it.
+to make sure the command will produce the intended results.
-The effect of @option{--wildcards} option is cancelled by
-@option{--no-wildcards}. This can be used to pass part of
-the command line arguments verbatim and other part as globbing
-patterns. For example, the following invocation:
+In case you need to apply more complex modifications to the file name,
+@GNUTAR{} provides a general-purpose transformation option:
+
+@table @option
+@opindex --transform
+@item --transform=@var{expression}
+Modify file names using supplied @var{expression}.
+@end table
+
+@noindent
+The @var{expression} is a @command{sed}-like replace expression of the
+form:
@smallexample
-$ @kbd{tar -xf foo.tar --wildcards '*.txt' --no-wildcards '[remarks]'}
+s/@var{regexp}/@var{replace}/[@var{flags}]
@end smallexample
@noindent
-instructs @command{tar} to extract from @file{foo.tar} all files whose
-names end in @samp{.txt} and the file named @file{[remarks]}.
+where @var{regexp} is a @dfn{regular expression}, @var{replace} is a
+replacement for each file name part that matches @var{regexp}. Both
+@var{regexp} and @var{replace} are described in detail in
+@ref{The "s" Command, The "s" Command, The `s' Command, sed, GNU sed}.
-Normally, a pattern matches a name if an initial subsequence of the
-name's components matches the pattern, where @samp{*}, @samp{?}, and
-@samp{[...]} are the usual shell wildcards, @samp{\} escapes wildcards,
-and wildcards can match @samp{/}.
+Supported @var{flags} are:
-Other than optionally stripping leading @samp{/} from names
-(@pxref{absolute}), patterns and names are used as-is. For
-example, trailing @samp{/} is not trimmed from a user-specified name
-before deciding whether to exclude it.
+@table @samp
+@item g
+Apply the replacement to @emph{all} matches to the @var{regexp}, not
+just the first.
+
+@item i
+Use case-insensitive matching
+
+@item x
+@var{regexp} is an @dfn{extended regular expression} (@pxref{Extended
+regexps, Extended regular expressions, Extended regular expressions,
+sed, GNU sed}).
+
+@item @var{number}
+Only replace the @var{number}th match of the @var{regexp}.
+
+Note: the @var{posix} standard does not specify what should happen
+when you mix the @samp{g} and @var{number} modifiers. @GNUTAR{}
+follows the GNU @command{sed} implementation in this regard, so
+the the interaction is defined to be: ignore matches before the
+@var{number}th, and then match and replace all matches from the
+@var{number}th on.
+
+@end table
-However, this matching procedure can be altered by the options listed
-below. These options accumulate. For example:
+Any delimiter can be used in lieue of @samp{/}, the only requirement being
+that it be used consistently throughout the expression. For example,
+the following two expressions are equivalent:
@smallexample
---ignore-case --exclude='makefile' --no-ignore-case ---exclude='readme'
+@group
+s/one/two/
+s,one,two,
+@end group
@end smallexample
-ignores case when excluding @samp{makefile}, but not when excluding
-@samp{readme}.
+Changing delimiters is often useful when the @var{regex} contains
+slashes. For example, it is more convenient to write @code{s,/,-,} than
+@code{s/\//-/}.
-@table @option
-@opindex anchored
-@opindex no-anchored
-@item --anchored
-@itemx --no-anchored
-If anchored, a pattern must match an initial subsequence
-of the name's components. Otherwise, the pattern can match any
-subsequence. Default is @option{--no-anchored} for exclusion members
-and @option{--anchored} inclusion members.
+Here are several examples of @option{--transform} usage:
-@opindex ignore-case
-@opindex no-ignore-case
-@item --ignore-case
-@itemx --no-ignore-case
-When ignoring case, upper-case patterns match lower-case names and vice versa.
-When not ignoring case (the default), matching is case-sensitive.
+@enumerate
+@item Extract @file{usr/} hierarchy into @file{usr/local/}:
-@opindex wildcards-match-slash
-@opindex no-wildcards-match-slash
-@item --wildcards-match-slash
-@itemx --no-wildcards-match-slash
-When wildcards match slash (the default for exclusion members), a
-wildcard like @samp{*} in the pattern can match a @samp{/} in the
-name. Otherwise, @samp{/} is matched only by @samp{/}.
+@smallexample
+$ @kbd{tar --transform='s,usr/,usr/local/,' -x -f arch.tar}
+@end smallexample
-@end table
+@item Strip two leading directory components (equivalent to
+@option{--strip-components=2}):
-The @option{--recursion} and @option{--no-recursion} options
-(@pxref{recurse}) also affect how member patterns are interpreted. If
-recursion is in effect, a pattern matches a name if it matches any of
-the name's parent directories.
+@smallexample
+$ @kbd{tar --transform='s,/*[^/]*/[^/]*/,,' -x -f arch.tar}
+@end smallexample
-The following table summarizes pattern-matching default values:
+@item Prepend @file{/prefix/} to each file name:
-@multitable @columnfractions .3 .7
-@headitem Members @tab Default settings
-@item Inclusion @tab @option{--no-wildcards --anchored --no-wildcards-match-slash}
-@item Exclusion @tab @option{--wildcards --no-anchored --wildcards-match-slash}
-@end multitable
+@smallexample
+$ @kbd{tar --transform 's,^,/prefix/,' -x -f arch.tar}
+@end smallexample
+
+@item Convert each file name to lower case:
+
+@smallexample
+$ @kbd{tar --transform 's/.*/\L&/' -x -f arch.tar}
+@end smallexample
+
+@end enumerate
+
+Unlike @option{--strip-components}, @option{--transform} can be used
+in any @GNUTAR{} operation mode. For example, the following command
+adds files to the archive while replacing the leading @file{usr/}
+component with @file{var/}:
+@smallexample
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' /}
+@end smallexample
+
+To test @option{--transform} effect we suggest using
+@option{--show-transformed-names} option:
+
+@smallexample
+$ @kbd{tar -cf arch.tar --transform='s,^usr/,var/,' \
+ --verbose --show-transformed-names /}
+@end smallexample
+
+If both @option{--strip-components} and @option{--transform} are used
+together, then @option{--transform} is applied first, and the required
+number of components is then stripped from its result.
+
@node after
@section Operating Only on New Files
@UNREVISED
* Portability:: Making @command{tar} Archives More Portable
* Compression:: Using Less Space through Compression
* Attributes:: Handling File Attributes
-* Standard:: The Standard Format
-* Extensions:: @acronym{GNU} Extensions to the Archive Format
* cpio:: Comparison of @command{tar} and @command{cpio}
@end menu
@cindex POSIX archive format
@cindex PAX archive format
-The version @value{VERSION} of @GNUTAR{} is able
-to read and create archives conforming to @acronym{POSIX.1-2001} standard.
+Starting from version 1.14 @GNUTAR{} features full support for
+@acronym{POSIX.1-2001} archives.
A @acronym{POSIX} conformant archive will be created if @command{tar}
-was given @option{--format=posix} option.
+was given @option{--format=posix} (@option{--format=pax}) option. No
+special option is required to read and extract from a @acronym{POSIX}
+archive.
+
+@menu
+* PAX keywords:: Controlling Extended Header Keywords.
+@end menu
+
+@node PAX keywords
+@subsubsection Controlling Extended Header Keywords
+
+@table @option
+@opindex pax-option
+@item --pax-option=@var{keyword-list}
+Handle keywords in @acronym{PAX} extended headers. This option is
+equivalent to @option{-o} option of the @command{pax} utility.
+@end table
+
+@var{Keyword-list} is a comma-separated
+list of keyword options, each keyword option taking one of
+the following forms:
+
+@table @code
+@item delete=@var{pattern}
+When used with one of archive-creation commands,
+this option instructs @command{tar} to omit from extended header records
+that it produces any keywords matching the string @var{pattern}.
+
+When used in extract or list mode, this option instructs tar
+to ignore any keywords matching the given @var{pattern} in the extended
+header records. In both cases, matching is performed using the pattern
+matching notation described in @acronym{POSIX 1003.2}, 3.13
+(@pxref{wildcards}). For example:
+
+@smallexample
+--pax-option delete=security.*
+@end smallexample
+
+would suppress security-related information.
+
+@item exthdr.name=@var{string}
+
+This keyword allows user control over the name that is written into the
+ustar header blocks for the extended headers. The name is obtained
+from @var{string} after making the following substitutions:
+
+@multitable @columnfractions .25 .55
+@headitem Meta-character @tab Replaced By
+@item %d @tab The directory name of the file, equivalent to the
+result of the @command{dirname} utility on the translated pathname.
+@item %f @tab The filename of the file, equivalent to the result
+of the @command{basename} utility on the translated pathname.
+@item %p @tab The process ID of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in @var{string} produce undefined
+results.
+
+If no option @samp{exthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+%d/PaxHeaders.%p/%f
+@end smallexample
+
+@item globexthdr.name=@var{string}
+This keyword allows user control over the name that is written into
+the ustar header blocks for global extended header records. The name
+is obtained from the contents of @var{string}, after making
+the following substitutions:
+
+@multitable @columnfractions .25 .55
+@headitem Meta-character @tab Replaced By
+@item %n @tab An integer that represents the
+sequence number of the global extended header record in the archive,
+starting at 1.
+@item %p @tab The process ID of the @command{tar} process.
+@item %% @tab A @samp{%} character.
+@end multitable
+
+Any other @samp{%} characters in @var{string} produce undefined results.
+
+If no option @samp{globexthdr.name=string} is specified, @command{tar}
+will use the following default value:
+
+@smallexample
+$TMPDIR/GlobalHead.%p.%n
+@end smallexample
+
+@noindent
+where @samp{$TMPDIR} represents the value of the @var{TMPDIR}
+environment variable. If @var{TMPDIR} is not set, @command{tar}
+uses @samp{/tmp}.
+
+@item @var{keyword}=@var{value}
+When used with one of archive-creation commands, these keyword/value pairs
+will be included at the beginning of the archive in a global extended
+header record. When used with one of archive-reading commands,
+@command{tar} will behave as if it has encountered these keyword/value
+pairs at the beginning of the archive in a global extended header
+record.
+
+@item @var{keyword}:=@var{value}
+When used with one of archive-creation commands, these keyword/value pairs
+will be included as records at the beginning of an extended header for
+each file. This is effectively equivalent to @var{keyword}=@var{value}
+form except that it creates no global extended header records.
+
+When used with one of archive-reading commands, @command{tar} will
+behave as if these keyword/value pairs were included as records at the
+end of each extended header; thus, they will override any global or
+file-specific extended header record keywords of the same names.
+For example, in the command:
+
+@smallexample
+tar --format=posix --create \
+ --file archive --pax-option gname:=user .
+@end smallexample
+
+the group name will be forced to a new value for all files
+stored in the archive.
+@end table
@node Checksumming
@subsection Checksumming Problems
implement your own filters, not necessarily dealing with
compression/decomression. For example, suppose you wish to implement
PGP encryption on top of compression, using @command{gpg} (@pxref{Top,
-gpg, gpg ---- encryption and signing tool, gpg}). The following
-script does that:
+gpg, gpg ---- encryption and signing tool, gpg, GNU Privacy Guard
+Manual}). The following script does that:
@smallexample
@group
@end table
-@node Standard
-@section Basic Tar Format
-@UNREVISED
-
-While an archive may contain many files, the archive itself is a
-single ordinary file. Like any other file, an archive file can be
-written to a storage device such as a tape or disk, sent through a
-pipe or over a network, saved on the active file system, or even
-stored in another archive. An archive file is not easy to read or
-manipulate without using the @command{tar} utility or Tar mode in
-@acronym{GNU} Emacs.
-
-Physically, an archive consists of a series of file entries terminated
-by an end-of-archive entry, which consists of two 512 blocks of zero
-bytes. A file
-entry usually describes one of the files in the archive (an
-@dfn{archive member}), and consists of a file header and the contents
-of the file. File headers contain file names and statistics, checksum
-information which @command{tar} uses to detect file corruption, and
-information about file types.
-
-Archives are permitted to have more than one member with the same
-member name. One way this situation can occur is if more than one
-version of a file has been stored in the archive. For information
-about adding new versions of a file to an archive, see @ref{update}.
-@FIXME-xref{To learn more about having more than one archive member with the
-same name, see -backup node, when it's written.}
-
-In addition to entries describing archive members, an archive may
-contain entries which @command{tar} itself uses to store information.
-@xref{label}, for an example of such an archive entry.
-
-A @command{tar} archive file contains a series of blocks. Each block
-contains @code{BLOCKSIZE} bytes. Although this format may be thought
-of as being on magnetic tape, other media are often used.
-
-Each file archived is represented by a header block which describes
-the file, followed by zero or more blocks which give the contents
-of the file. At the end of the archive file there are two 512-byte blocks
-filled with binary zeros as an end-of-file marker. A reasonable system
-should write such end-of-file marker at the end of an archive, but
-must not assume that such a block exists when reading an archive. In
-particular @GNUTAR{} always issues a warning if it does not encounter it.
-
-The blocks may be @dfn{blocked} for physical I/O operations.
-Each record of @var{n} blocks (where @var{n} is set by the
-@option{--blocking-factor=@var{512-size}} (@option{-b @var{512-size}}) option to @command{tar}) is written with a single
-@w{@samp{write ()}} operation. On magnetic tapes, the result of
-such a write is a single record. When writing an archive,
-the last record of blocks should be written at the full size, with
-blocks after the zero block containing all zeros. When reading
-an archive, a reasonable system should properly handle an archive
-whose last record is shorter than the rest, or which contains garbage
-records after a zero block.
-
-The header block is defined in C as follows. In the @GNUTAR{}
-distribution, this is part of file @file{src/tar.h}:
-
-@smallexample
-@include header.texi
-@end smallexample
-
-All characters in header blocks are represented by using 8-bit
-characters in the local variant of ASCII. Each field within the
-structure is contiguous; that is, there is no padding used within
-the structure. Each character on the archive medium is stored
-contiguously.
-
-Bytes representing the contents of files (after the header block
-of each file) are not translated in any way and are not constrained
-to represent characters in any character set. The @command{tar} format
-does not distinguish text files from binary files, and no translation
-of file contents is performed.
-
-The @code{name}, @code{linkname}, @code{magic}, @code{uname}, and
-@code{gname} are null-terminated character strings. All other fields
-are zero-filled octal numbers in ASCII. Each numeric field of width
-@var{w} contains @var{w} minus 1 digits, and a null.
-
-The @code{name} field is the file name of the file, with directory names
-(if any) preceding the file name, separated by slashes.
-
-@FIXME{how big a name before field overflows?}
-
-The @code{mode} field provides nine bits specifying file permissions
-and three bits to specify the Set UID, Set GID, and Save Text
-(@dfn{sticky}) modes. Values for these bits are defined above.
-When special permissions are required to create a file with a given
-mode, and the user restoring files from the archive does not hold such
-permissions, the mode bit(s) specifying those special permissions
-are ignored. Modes which are not supported by the operating system
-restoring files from the archive will be ignored. Unsupported modes
-should be faked up when creating or updating an archive; e.g., the
-group permission could be copied from the @emph{other} permission.
-
-The @code{uid} and @code{gid} fields are the numeric user and group
-ID of the file owners, respectively. If the operating system does
-not support numeric user or group IDs, these fields should be ignored.
-
-The @code{size} field is the size of the file in bytes; linked files
-are archived with this field specified as zero. @FIXME-xref{Modifiers, in
-particular the @option{--incremental} (@option{-G}) option.}
-
-The @code{mtime} field is the data modification time of the file at
-the time it was archived. It is the ASCII representation of the octal
-value of the last time the file's contents were modified, represented
-as an integer number of
-seconds since January 1, 1970, 00:00 Coordinated Universal Time.
-
-The @code{chksum} field is the ASCII representation of the octal value
-of the simple sum of all bytes in the header block. Each 8-bit
-byte in the header is added to an unsigned integer, initialized to
-zero, the precision of which shall be no less than seventeen bits.
-When calculating the checksum, the @code{chksum} field is treated as
-if it were all blanks.
-
-The @code{typeflag} field specifies the type of file archived. If a
-particular implementation does not recognize or permit the specified
-type, the file will be extracted as if it were a regular file. As this
-action occurs, @command{tar} issues a warning to the standard error.
-
-The @code{atime} and @code{ctime} fields are used in making incremental
-backups; they store, respectively, the particular file's access and
-status change times.
-
-The @code{offset} is used by the @option{--multi-volume} (@option{-M}) option, when
-making a multi-volume archive. The offset is number of bytes into
-the file that we need to restart at to continue the file on the next
-tape, i.e., where we store the location that a continued file is
-continued at.
-
-The following fields were added to deal with sparse files. A file
-is @dfn{sparse} if it takes in unallocated blocks which end up being
-represented as zeros, i.e., no useful data. A test to see if a file
-is sparse is to look at the number blocks allocated for it versus the
-number of characters in the file; if there are fewer blocks allocated
-for the file than would normally be allocated for a file of that
-size, then the file is sparse. This is the method @command{tar} uses to
-detect a sparse file, and once such a file is detected, it is treated
-differently from non-sparse files.
-
-Sparse files are often @code{dbm} files, or other database-type files
-which have data at some points and emptiness in the greater part of
-the file. Such files can appear to be very large when an @samp{ls
--l} is done on them, when in truth, there may be a very small amount
-of important data contained in the file. It is thus undesirable
-to have @command{tar} think that it must back up this entire file, as
-great quantities of room are wasted on empty blocks, which can lead
-to running out of room on a tape far earlier than is necessary.
-Thus, sparse files are dealt with so that these empty blocks are
-not written to the tape. Instead, what is written to the tape is a
-description, of sorts, of the sparse file: where the holes are, how
-big the holes are, and how much data is found at the end of the hole.
-This way, the file takes up potentially far less room on the tape,
-and when the file is extracted later on, it will look exactly the way
-it looked beforehand. The following is a description of the fields
-used to handle a sparse file:
-
-The @code{sp} is an array of @code{struct sparse}. Each @code{struct
-sparse} contains two 12-character strings which represent an offset
-into the file and a number of bytes to be written at that offset.
-The offset is absolute, and not relative to the offset in preceding
-array element.
-
-The header can hold four of these @code{struct sparse} at the moment;
-if more are needed, they are not stored in the header.
-
-The @code{isextended} flag is set when an @code{extended_header}
-is needed to deal with a file. Note that this means that this flag
-can only be set when dealing with a sparse file, and it is only set
-in the event that the description of the file will not fit in the
-allotted room for sparse structures in the header. In other words,
-an extended_header is needed.
-
-The @code{extended_header} structure is used for sparse files which
-need more sparse structures than can fit in the header. The header can
-fit 4 such structures; if more are needed, the flag @code{isextended}
-gets set and the next block is an @code{extended_header}.
-
-Each @code{extended_header} structure contains an array of 21
-sparse structures, along with a similar @code{isextended} flag
-that the header had. There can be an indeterminate number of such
-@code{extended_header}s to describe a sparse file.
-
-@table @asis
-
-@item @code{REGTYPE}
-@itemx @code{AREGTYPE}
-These flags represent a regular file. In order to be compatible
-with older versions of @command{tar}, a @code{typeflag} value of
-@code{AREGTYPE} should be silently recognized as a regular file.
-New archives should be created using @code{REGTYPE}. Also, for
-backward compatibility, @command{tar} treats a regular file whose name
-ends with a slash as a directory.
-
-@item @code{LNKTYPE}
-This flag represents a file linked to another file, of any type,
-previously archived. Such files are identified in Unix by each
-file having the same device and inode number. The linked-to name is
-specified in the @code{linkname} field with a trailing null.
-
-@item @code{SYMTYPE}
-This represents a symbolic link to another file. The linked-to name
-is specified in the @code{linkname} field with a trailing null.
-
-@item @code{CHRTYPE}
-@itemx @code{BLKTYPE}
-These represent character special files and block special files
-respectively. In this case the @code{devmajor} and @code{devminor}
-fields will contain the major and minor device numbers respectively.
-Operating systems may map the device specifications to their own
-local specification, or may ignore the entry.
-
-@item @code{DIRTYPE}
-This flag specifies a directory or sub-directory. The directory
-name in the @code{name} field should end with a slash. On systems where
-disk allocation is performed on a directory basis, the @code{size} field
-will contain the maximum number of bytes (which may be rounded to
-the nearest disk block allocation unit) which the directory may
-hold. A @code{size} field of zero indicates no such limiting. Systems
-which do not support limiting in this manner should ignore the
-@code{size} field.
-
-@item @code{FIFOTYPE}
-This specifies a FIFO special file. Note that the archiving of a
-FIFO file archives the existence of this file and not its contents.
-
-@item @code{CONTTYPE}
-This specifies a contiguous file, which is the same as a normal
-file except that, in operating systems which support it, all its
-space is allocated contiguously on the disk. Operating systems
-which do not allow contiguous allocation should silently treat this
-type as a normal file.
-
-@item @code{A} @dots{} @code{Z}
-These are reserved for custom implementations. Some of these are
-used in the @acronym{GNU} modified format, as described below.
-
-@end table
-
-Other values are reserved for specification in future revisions of
-the P1003 standard, and should not be used by any @command{tar} program.
-
-The @code{magic} field indicates that this archive was output in
-the P1003 archive format. If this field contains @code{TMAGIC},
-the @code{uname} and @code{gname} fields will contain the ASCII
-representation of the owner and group of the file respectively.
-If found, the user and group IDs are used rather than the values in
-the @code{uid} and @code{gid} fields.
-
-For references, see ISO/IEC 9945-1:1990 or IEEE Std 1003.1-1990, pages
-169-173 (section 10.1) for @cite{Archive/Interchange File Format}; and
-IEEE Std 1003.2-1992, pages 380-388 (section 4.48) and pages 936-940
-(section E.4.48) for @cite{pax - Portable archive interchange}.
-
-@node Extensions
-@section @acronym{GNU} Extensions to the Archive Format
-@UNREVISED
-
-The @acronym{GNU} format uses additional file types to describe new types of
-files in an archive. These are listed below.
-
-@table @code
-@item GNUTYPE_DUMPDIR
-@itemx 'D'
-This represents a directory and a list of files created by the
-@option{--incremental} (@option{-G}) option. The @code{size} field gives the total
-size of the associated list of files. Each file name is preceded by
-either a @samp{Y} (the file should be in this archive) or an @samp{N}.
-(The file is a directory, or is not stored in the archive.) Each file
-name is terminated by a null. There is an additional null after the
-last file name.
-
-@item GNUTYPE_MULTIVOL
-@itemx 'M'
-This represents a file continued from another volume of a multi-volume
-archive created with the @option{--multi-volume} (@option{-M}) option. The original
-type of the file is not given here. The @code{size} field gives the
-maximum size of this piece of the file (assuming the volume does
-not end before the file is written out). The @code{offset} field
-gives the offset from the beginning of the file where this part of
-the file begins. Thus @code{size} plus @code{offset} should equal
-the original size of the file.
-
-@item GNUTYPE_SPARSE
-@itemx 'S'
-This flag indicates that we are dealing with a sparse file. Note
-that archiving a sparse file requires special operations to find
-holes in the file, which mark the positions of these holes, along
-with the number of bytes of data to be found after the hole.
-
-@item GNUTYPE_VOLHDR
-@itemx 'V'
-This file type is used to mark the volume header that was given with
-the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option when the archive was created. The @code{name}
-field contains the @code{name} given after the @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) option.
-The @code{size} field is zero. Only the first file in each volume
-of an archive should have this type.
-
-@end table
-
-You may have trouble reading a @acronym{GNU} format archive on a
-non-@acronym{GNU} system if the options @option{--incremental} (@option{-G}),
-@option{--multi-volume} (@option{-M}), @option{--sparse} (@option{-S}), or @option{--label=@var{archive-label}} (@option{-V @var{archive-label}}) were
-used when writing the archive. In general, if @command{tar} does not
-use the @acronym{GNU}-added fields of the header, other versions of
-@command{tar} should be able to read the archive. Otherwise, the
-@command{tar} program will give an error, the most likely one being a
-checksum error.
-
@node cpio
@section Comparison of @command{tar} and @command{cpio}
@UNREVISED
@FIXME{Is there a better way to frob the spacing on the list?}
If you don't specify a @var{tapename}, @command{mt} uses the environment
-variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} uses the device
-@file{/dev/rmt12}.
+variable @env{TAPE}; if @env{TAPE} is not set, @command{mt} will use
+the default device specified in your @file{sys/mtio.h} file
+(@code{DEFTAPE} variable). If this is not defined, the program will
+display a descriptive error message and exit with code 1.
@command{mt} returns a 0 exit status when the operation(s) were
successful, 1 if the command was unrecognized, and 2 if an operation
@vrindex TAR_SUBCOMMAND, info script environment variable
@item TAR_SUBCOMMAND
-Short option describing the operation @command{tar} is executed.
+Short option describing the operation @command{tar} is executing
@xref{Operations}, for a complete list of subcommand options.
@vrindex TAR_FORMAT, info script environment variable
If you want to tar to mimic the behavior of versions prior to 1.15.91,
add this option to your @env{TAR_OPTIONS} variable.
-@xref{Wildcards}, for the detailed discussion of the use of globbing
+@xref{wildcards}, for the detailed discussion of the use of globbing
patterns by @GNUTAR{}.
@item Use of short option @option{-o}.
distribution tarballs. @xref{Formats,v7}, for the detailed discussion
of this issue and its implications.
-@FIXME{Change the first argument to tar-formats if and when Automake
-people accept my patch to the documentation, and the new Automake is
-out --Sergey 2006-05-25}.
+@FIXME{Change the first argument to tar-formats when the new Automake is
+out. The proposition to add @anchor{} to the appropriate place of its
+docs was accepted by Automake people --Sergey 2006-05-25}.
@xref{Options, tar-v7, Changing Automake's Behavior,
automake, GNU Automake}, for a description on how to use various
archive formats with @command{automake}.
@appendix Genfile
@include genfile.texi
-@node Snapshot Files
-@appendix Format of the Incremental Snapshot Files
-@include snapshot.texi
+@node Tar Internals
+@appendix Tar Internals
+@include intern.texi
@node Free Software Needs Free Documentation
@appendix Free Software Needs Free Documentation
projects / chaz / tar / blobdiff