@subtitle @value{RENDITION} @value{VERSION}, @value{UPDATED}
@author Melissa Weisshaus, Jay Fenlason,
@author Thomas Bushnell, n/BSG, Amy Gorin
+@author Sergey Poznyakoff
@c he said to remove it: Fran@,{c}ois Pinard
@c i'm thinking about how the author page *should* look. -mew 2may96
this chapter will cover how to use these operations in detail. We will
present the rest of the operations in the next chapter.
-@table @kbd
+@table @option
@item --create
@itemx -c
Create a new @command{tar} archive.
@node file tutorial
@unnumberedsubsec The @option{--file} Option
-@table @kbd
+@table @option
@item --file=@var{archive-name}
@itemx -f @var{archive-name}
Specify the name of an archive file.
@node verbose tutorial
@unnumberedsubsec The @option{--verbose} Option
-@table @kbd
+@table @option
@item --verbose
@itemx -v
Show the files being worked on as @command{tar} is running.
Sometimes, a single instance of @option{--verbose} on the command line
will show a full, @samp{ls} style listing of an archive or files,
-@c FIXME: Describe the exact output format, e.g., how hard links are displayed.
-giving sizes, owners, and similar information. Other times,
-@option{--verbose} will only show files or members that the particular
+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
@node help tutorial
@unnumberedsubsec Getting Help: Using the @option{--help} Option
-@table @kbd
+@table @option
@item --help
The @option{--help} option to @command{tar} prints out a very brief list of
@command{tar}, to avoid errors).
Note that the part of the command which says,
-@w{@kbd{--file=collection.tar}} is considered to be @emph{one} argument.
+@w{@option{--file=collection.tar}} is considered to be @emph{one} argument.
If you substituted any other string of characters for
@kbd{collection.tar}, then that string would become the name of the
archive file you create.
want placed in the archive. If you do not specify any archive
members, @GNUTAR{} will complain.
-If you now list the contents of the working directory (@kbd{ls}), you will
+If you now list the contents of the working directory (@command{ls}), you will
find the archive file listed as well as the files you saw previously:
@smallexample
-rw-rw-rw- myself user 62 1990-05-23 10:55 folk
@end smallexample
+@cindex listing member and file names
+@anchor{listing member and file names}
+It is important to notice that the output of @kbd{tar --list
+--verbose} does not necessarily match that produced by @kbd{tar
+--create --verbose} while creating the archive. It is because
+@GNUTAR{}, unless told explicitly not to do so, removes some directory
+prefixes from file names before storing them in the archive
+(@xref{absolute}, for more information). In other
+words, in verbose mode @GNUTAR{} shows @dfn{file names} when creating
+an archive and @dfn{member names} when listing it. Consider this
+example:
+
+@smallexample
+@group
+$ @kbd{tar cfv archive /etc/mail}
+tar: Removing leading `/' from member names
+/etc/mail/
+/etc/mail/sendmail.cf
+/etc/mail/aliases
+$ @kbd{tar tf archive}
+etc/mail/
+etc/mail/sendmail.cf
+etc/mail/aliases
+@end group
+@end smallexample
+
+@cindex @option{--show-stored-names} described
+ This default behavior can sometimes be inconvenient. You can force
+@GNUTAR{} show member names when creating archive by supplying
+@option{--show-stored-names} option.
+
+@table @option
+@item --show-stored-names
+Print member (not @emph{file}) names when creating the archive.
+@end table
+
@cindex File name arguments, using @option{--list} with
@cindex @option{--list} with file name arguments
You can specify one or more individual member names as arguments when
@node Operation Summary
@subsection Operations
-@table @kbd
+@table @option
@item --append
@itemx -r
@node Option Summary
@subsection @command{tar} Options
-@table @kbd
+@table @option
@item --absolute-names
@itemx -P
@item --null
When @command{tar} is using the @option{--files-from} option, this option
-instructs @command{tar} to expect filenames terminated with @kbd{NUL}, so
+instructs @command{tar} to expect filenames terminated with @option{NUL}, so
@command{tar} can correctly work with file names that contain newlines.
@FIXME-xref{}
from @var{string} after substituting the following meta-characters:
@multitable @columnfractions .30 .70
-@item Meta-character @tab Replaced By
+@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
following character substitutions have been made:
@multitable @columnfractions .30 .70
-@item Meta-character @tab Replaced By
+@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.
Instructs @command{tar} to mention directories its skipping over when
operating on a @command{tar} archive. @FIXME-xref{}
+@item --show-stored-names
+
+This option has effect only 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}.
+
@item --sparse
@itemx -S
Specifies the length of tapes that @command{tar} is writing as being
@w{@var{num} x 1024} bytes long. @FIXME-xref{}
+@item --test-label
+
+Reads the volume label. If an argument is specified, test whether it
+matches the volume label. @xref{--test-label option}.
+
@item --to-stdout
@itemx -O
Here is an alphabetized list of all of the short option forms, matching
them with the equivalent long option.
-@table @kbd
+@table @option
@item -A
The five operations that we will cover in this chapter are:
-@table @kbd
+@table @option
@item --append
@itemx -r
Add new entries to an archive that already exists.
@node Ignore Failed Read
@subsection Ignore Fail Read
-@table @kbd
+@table @option
@item --ignore-failed-read
Do not exit with nonzero on unreadable files or directories.
@end table
@FIXME{need sentence or so of intro here}
-@table @kbd
+@table @option
@item --read-full-records
@item -B
Use in conjunction with @value{op-extract} to read an archive which
does not write after the end of an archive, but seeks to
maintain compatiblity among archiving utilities.
-@table @kbd
+@table @option
@item --ignore-zeros
@itemx -i
To ignore blocks of zeros (ie.@: end-of-archive entries) which may be
@node Overwrite Old Files
@unnumberedsubsubsec Overwrite Old Files
-@table @kbd
+@table @option
@item --overwrite
Overwrite existing files and directory metadata when extracting files
from an archive.
@node Keep Old Files
@unnumberedsubsubsec Keep Old Files
-@table @kbd
+@table @option
@item --keep-old-files
@itemx -k
Do not replace existing files from archive. The
@node Keep Newer Files
@unnumberedsubsubsec Keep Newer Files
-@table @kbd
+@table @option
@item --keep-newer-files
Do not replace existing files that are newer than their archive
copies. This option is meaningless with @value{op-list}.
@node Unlink First
@unnumberedsubsubsec Unlink First
-@table @kbd
+@table @option
@item --unlink-first
@itemx -U
Remove files before extracting over them.
@node Recursive Unlink
@unnumberedsubsubsec Recursive Unlink
-@table @kbd
+@table @option
@item --recursive-unlink
When this option is specified, try removing files and directory hierarchies
before extracting over them. @emph{This is a dangerous option!}
the files were extracted, use the @value{op-touch} option in
conjunction with @value{op-extract}.
-@table @kbd
+@table @option
@item --touch
@itemx -m
Sets the modification time of extracted archive members to the time
in conjunction with the @value{op-extract} operation. @FIXME{Should be
aliased to ignore-umask.}
-@table @kbd
+@table @option
@item --preserve-permission
@itemx --same-permission
@itemx --ignore-umask
they appear on standard output concatenated, in the order they are
found in the archive.
-@table @kbd
+@table @option
@item --to-stdout
@itemx -O
Writes files to the standard output. Used in conjunction with
option goes in this section. i have no idea; i only know it's nowhere
else in the book...}
-@table @kbd
+@table @option
@item --remove-files
Remove files after adding them to the archive.
@end table
@node Starting File
@unnumberedsubsubsec Starting File
-@table @kbd
+@table @option
@item --starting-file=@var{name}
@itemx -K @var{name}
Starts an operation in the middle of an archive. Use in conjunction
@node Same Order
@unnumberedsubsubsec Same Order
-@table @kbd
+@table @option
@item --same-order
@itemx --preserve-order
@itemx -s
option allows you to either specify or name a file to use as the archive
instead of the default archive file location.
-@table @kbd
+@table @option
@item --file=@var{archive-name}
@itemx -f @var{archive-name}
Name the archive to create or operate on. Use in conjunction with
newlines. You will frequently use this option when you have generated
the list of files to archive with the @command{find} utility.
-@table @kbd
+@table @option
@item --files-from=@var{file name}
@itemx -T @var{file name}
Get names to extract or create from file @var{file name}.
@end menu
@node nul
-@subsection @kbd{NUL} Terminated File Names
+@subsection @code{NUL} Terminated File Names
-@cindex File names, terminated by @kbd{NUL}
-@cindex @kbd{NUL} terminated file names
+@cindex File names, terminated by @code{NUL}
+@cindex @code{NUL} terminated file names
The @value{op-null} option causes @value{op-files-from} 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}.
-@table @kbd
+@table @option
@item --null
-Only consider @kbd{NUL} terminated file names, instead of files that
+Only consider @code{NUL} terminated file names, instead of files that
terminate in a newline.
@end table
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 @kbd{NUL}
+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 @kbd{NUL} separator between files.
+@command{tar} to recognize the @code{NUL} separator between files.
@smallexample
$ @kbd{find . -size +800 -print0 > long-files}
To avoid operating on files whose names match a particular pattern,
use the @value{op-exclude} or @value{op-exclude-from} options.
-@table @kbd
+@table @option
@item --exclude=@var{pattern}
Causes @command{tar} to ignore files that match the @var{pattern}.
@end table
You may give multiple @option{--exclude} options.
-@table @kbd
+@table @option
@item --exclude-from=@var{file}
@itemx -X @var{file}
Causes @command{tar} to ignore files that match the patterns listed in
@FIXME{do the exclude options files need to have stuff separated by
newlines the same as the files-from option does?}
-@table @kbd
+@table @option
@item --exclude-caches
Causes @command{tar} to ignore directories containing a cache directory tag.
@end table
specify a particular date against which @command{tar} can compare when
deciding whether or not to archive the files.
-@table @kbd
+@table @option
@item --after-date=@var{date}
@itemx --newer=@var{date}
@itemx -N @var{date}
archive; see @ref{files} for more information on using @command{find} with
@command{tar}, or look.
-@table @kbd
+@table @option
@item --no-recursion
Prevents @command{tar} from recursively descending directories.
@command{tar} will still archive files explicitly named on the command line
or through @value{op-files-from}, regardless of where they reside.
-@table @kbd
+@table @option
@item --one-file-system
@itemx -l
Prevents @command{tar} from crossing file system boundaries when
working directory to the directory @var{directory} after that point in
the list.
-@table @kbd
+@table @option
@item --directory=@var{directory}
@itemx -C @var{directory}
Changes the working directory in the middle of a command line.
@subsection Absolute File Names
@UNREVISED
-@table @kbd
+@table @option
@item -P
@itemx --absolute-names
Do not strip leading slashes from file names, and permit file names
leading slashes from member names when putting members into the
archive. For example, if you ask @command{tar} to add the file
@file{/bin/ls} to an archive, it will do so, but the member name will
-be @file{bin/ls}.
+be @file{bin/ls}.@footnote{A side effect of this is that when
+@option{--create} is used with @option{--verbose} the resulting output
+is not, generally speaking, the same as the one you'd get running
+@kbd{tar --list} command. This may be important if you use some
+scripts for comparing both outputs. @xref{listing member and file names},
+for the information on how to handle this case.}
If you use the @value{op-absolute-names} option, @command{tar} will do
none of these transformations.
@FIXME{Is write access an issue?}
-@table @kbd
+@table @option
@item --absolute-names
Preserves full file names (including superior directory names) when
archiving files. Preserves leading slash when extracting files.
formats:
@multitable @columnfractions .10 .20 .20 .20 .20
-@item Format @tab UID @tab File Size @tab Path Name @tab Devn
+@headitem Format @tab UID @tab File Size @tab Path Name @tab Devn
@item gnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
@item oldgnu @tab 1.8e19 @tab Unlimited @tab Unlimited @tab 63
@item v7 @tab 2097151 @tab 8GB @tab 99 @tab n/a
The following table summarizes compression options used by @GNUTAR{}.
-@table @kbd
+@table @option
@item -z
@itemx --gzip
@itemx --ungzip
@cindex Sparse Files
@UNREVISED
-@table @kbd
+@table @option
@item -S
@itemx --sparse
Handle sparse files efficiently.
@command{tar} ignores the @value{op-sparse} option when reading an archive.
-@table @kbd
+@table @option
@item --sparse
@itemx -S
Files stored sparsely in the file system are represented sparsely in
Handling of file attributes
-@table @kbd
+@table @option
@item --atime-preserve
Preserve access times on files that are read.
This doesn't work for files that
@section Device Selection and Switching
@UNREVISED
-@table @kbd
+@table @option
@item -f [@var{hostname}:]@var{file}
@itemx --file=[@var{hostname}:]@var{file}
Use archive file or device @var{file} on @var{hostname}.
If the file name contains a @samp{:}, it is interpreted as
@samp{hostname:file name}. If the @var{hostname} contains an @dfn{at}
-sign (@kbd{@@}), it is treated as @samp{user@@hostname:file name}. In
+sign (@samp{@@}), it is treated as @samp{user@@hostname:file name}. In
either case, @command{tar} will invoke the command @command{rsh} (or
@command{remsh}) to start up an @command{/usr/libexec/rmt} on the remote
machine. If you give an alternate login name, it will be given to the
too. The installer could also check for @samp{DEFTAPE} in
@file{<sys/mtio.h>}.
-@table @kbd
+@table @option
@item --force-local
Archive file is local even if it contains a colon.
@xref{list}, for more information on the @value{op-list}
operation. @xref{Reading}, for a more detailed explanation of that option.
-@table @kbd
+@table @option
@item --blocking-factor=@var{number}
@itemx -b @var{number}
Specifies the blocking factor of an archive. Can be used with any
Device blocking
-@table @kbd
+@table @option
@item -b @var{blocks}
@itemx --blocking-factor=@var{blocks}
Set record size to @math{@var{blocks} * 512} bytes.
@FIXME{is there any use for record operations?}
-@table @kbd
+@table @option
@item eof
@itemx weof
Writes @var{number} tape marks at the current position on the tape.
successful, 1 if the command was unrecognized, and 2 if an operation
failed.
-@FIXME{New node on how to find an archive?}
-
-If you use @value{op-extract} with the @value{op-label} option specified,
-@command{tar} will read an archive label (the tape head has to be positioned
-on it) and print an error if the archive label doesn't match the
-@var{archive-name} specified. @var{archive-name} can be any regular
-expression. If the labels match, @command{tar} extracts the archive.
-@value{xref-label}.
-@FIXME-xref{Matching Format Parameters}@FIXME{fix cross
-references}@samp{tar --list --label} will cause @command{tar} to print the
-label.
-
-@FIXME{Program to list all the labels on a tape?}
-
@node Using Multiple Tapes
@section Using Multiple Tapes
@UNREVISED
@FIXME{There should be a sample program here, including an exit
before end. Is the exit status even checked in tar? :-(}
-@table @kbd
+@table @option
@item --multi-volume
@itemx -M
Creates a multi-volume archive, when used in conjunction with
@cindex Labels on the archive media
@UNREVISED
-@table @kbd
-@item -V @var{name}
-@itemx --label=@var{name}
-Create archive with volume name @var{name}.
-@end table
-
-This option causes @command{tar} to write out a @dfn{volume header} at
-the beginning of the archive. If @value{op-multi-volume} is used, each
-volume of the archive will have a volume header of @samp{@var{name}
-Volume @var{n}}, where @var{n} is 1 for the first volume, 2 for the
-next, and so on.
-
-@FIXME{Should the arg to --label be a quoted string?? No.}
-
-To avoid problems caused by misplaced paper labels on the archive
+@cindex @option{--label} option introduced
+@cindex @option{-V} option introduced
+ To avoid problems caused by misplaced paper labels on the archive
media, you can include a @dfn{label} entry---an archive member which
contains the name of the archive---in the archive itself. Use the
@value{op-label} option in conjunction with the @value{op-create} operation
to include a label entry in the archive as it is being created.
-If you create an archive using both @value{op-label} and
+@table @option
+@item --label=@var{archive-label}
+@itemx -V @var{archive-label}
+Includes an @dfn{archive-label} at the beginning of the archive when
+the archive is being created, when used in conjunction with the
+@value{op-create} operation. Checks to make sure the archive label
+matches the one specified (when used in conjunction with any other
+operation.
+@end table
+
+ If you create an archive using both @value{op-label} and
@value{op-multi-volume}, each volume of the archive will have an
archive label of the form @samp{@var{archive-label} Volume @var{n}},
where @var{n} is 1 for the first volume, 2 for the next, and so on.
@FIXME-xref{Multi-Volume Archives, for information on creating multiple
volume archives.}
-If you list or extract an archive using @value{op-label}, @command{tar} will
-print an error if the archive label doesn't match the @var{archive-label}
-specified, and will then not list nor extract the archive. In those cases,
-@var{archive-label} argument is interpreted as a globbing-style pattern
-which must match the actual magnetic volume label. @xref{exclude}, for
-a precise description of how match is attempted@footnote{Previous versions
-of @command{tar} used full regular expression matching, or before that, only
-exact string matching, instead of wildcard matchers. We decided for the
-sake of simplicity to use a uniform matching device through @command{tar}.}.
-If the switch @value{op-multi-volume} is being used, the volume label
-matcher will also suffix @var{archive-label} by @w{@samp{ Volume [1-9]*}}
-if the initial match fails, before giving up. Since the volume numbering
-is automatically added in labels at creation time, it sounded logical to
-equally help the user taking care of it when the archive is being read.
-
-The @value{op-label} was once called @option{--volume}, but is not available
-under that name anymore.
-
-To find out an archive's label entry (or to find out if an archive has
-a label at all), use @samp{tar --list --verbose}. @command{tar} will
-print the label first, and then print archive member information, as
-in the example below:
+@cindex Volume label, listing
+@cindex Listing volume label
+ The volume label will be displayed by @option{--list} along with
+the file contents. If verbose display is requested, it will also be
+explicitely marked as in the example below:
@smallexample
+@group
$ @kbd{tar --verbose --list --file=iamanarchive}
V--------- 0 0 0 1992-03-07 12:01 iamalabel--Volume Header--
-rw-rw-rw- ringo user 40 1990-05-21 13:30 iamafilename
+@end group
@end smallexample
-@table @kbd
-@item --label=@var{archive-label}
-@itemx -V @var{archive-label}
-Includes an @dfn{archive-label} at the beginning of the archive when
-the archive is being created, when used in conjunction with the
-@value{op-create} option. Checks to make sure the archive label
-matches the one specified (when used in conjunction with the
-@value{op-extract} option.
-@end table
+@cindex @option{--test-label} option introduced
+@anchor{--test-label option}
+ However, @option{--list} option will cause listing entire
+contents of the archive, which may be undesirable (for example, if the
+archive is stored on a tape). You can request checking only the volume
+by specifying @option{--test-label} option. This option reads only the
+first block of an archive, so it can be used with slow storage
+devices. For example:
+
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive}
+iamalabel
+@end group
+@end smallexample
+
+ If @option{--test-label} is used with a single command line
+argument, @command{tar} compares the volume label with the
+argument. It exits with code 0 if the two strings match, and with code
+2 otherwise. In this case no output is displayed. For example:
-To get a common information on all tapes of a series, use the
-@value{op-label} option. For having this information different in each
+@smallexample
+@group
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable'}
+@result{} 0
+$ @kbd{tar --test-label --file=iamanarchive 'iamalable' alabel}
+@result{} 1
+@end group
+@end smallexample
+
+ If you request any operation, other than @option{--create}, along
+with using @option{--label} option, @command{tar} will first check if
+the archive label matches the one specified and will refuse to proceed
+if it does not. Use this as a safety precaution to avoid accidentally
+overwriting existing archives. For example, if you wish to add files
+to @file{archive}, presumably labelled with string @samp{My volume},
+you will get:
+
+@smallexample
+@group
+$ @kbd{tar -rf archive --label 'My volume' .}
+tar: Archive not labeled to match `My volume'
+@end group
+@end smallexample
+
+@noindent
+in case its label does not match. This will work even if
+@file{archive} is not labelled at all.
+
+ Similarly, @command{tar} will refuse to list or extract the
+archive if its label doesn't match the @var{archive-label}
+specified. In those cases, @var{archive-label} argument is interpreted
+as a globbing-style pattern which must match the actual magnetic
+volume label. @xref{exclude}, for a precise description of how match
+is attempted@footnote{Previous versions of @command{tar} used full
+regular expression matching, or before that, only exact string
+matching, instead of wildcard matchers. We decided for the sake of
+simplicity to use a uniform matching device through
+@command{tar}.}. If the switch @value{op-multi-volume} is being used,
+the volume label matcher will also suffix @var{archive-label} by
+@w{@samp{ Volume [1-9]*}} if the initial match fails, before giving
+up. Since the volume numbering is automatically added in labels at
+creation time, it sounded logical to equally help the user taking care
+of it when the archive is being read.
+
+ The @value{op-label} was once called @option{--volume}, but is not available
+under that name anymore.
+
+ You can also use @option{--label} to get a common information on
+all tapes of a series. For having this information different in each
series created through a single script used on a regular basis, just
manage to get some date string as part of the label. For example:
@smallexample
+@group
$ @kbd{tar cfMV /dev/tape "Daily backup for `date +%Y-%m-%d`"}
$ @kbd{tar --create --file=/dev/tape --multi-volume \
--volume="Daily backup for `date +%Y-%m-%d`"}
+@end group
@end smallexample
-Also note that each label has its own date and time, which corresponds
+ Also note that each label has its own date and time, which corresponds
to when @GNUTAR{} initially attempted to write it,
often soon after the operator launches @command{tar} or types the
carriage return telling that the next tape is ready. Comparing date
rewinding tapes and the operator switching them were negligible, which
is usually not the case.
-@FIXME{was --volume}
-
@node verify
@section Verifying Data as It is Stored
@cindex Verifying a write operation
@cindex Double-checking a write operation
-@table @kbd
+@table @option
@item -W
@itemx --verify
Attempt to verify the archive after writing.
projects / chaz / tar / commitdiff
