X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=48e8c3cc002a57f0f5a5e9893f7b578088febc75;hb=51b272f5723b782fb079b1cd55daf934331596b6;hp=2c259ff965489d58822700a1f39342f56b93fad6;hpb=777042e024d4bf7357ffd060ad05763d463fe441;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 2c259ff..48e8c3c 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -1022,13 +1022,12 @@ 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 +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 @@ -1421,7 +1420,7 @@ above would look like: @smallexample $ @kbd{tar --list --verbose --file=collection.tar folk} --rw-r--r-- myself user 62 1990-05-23 10:55 folk +-rw-r--r-- myself/user 62 1990-05-23 10:55 folk @end smallexample @cindex listing member and file names @@ -1513,11 +1512,11 @@ $ @kbd{tar --list --verbose --file=music.tar practice} @command{tar} responds: @smallexample -drwxrwxrwx myself user 0 1990-05-31 21:49 practice/ --rw-r--r-- myself user 42 1990-05-21 13:29 practice/blues --rw-r--r-- myself user 62 1990-05-23 10:55 practice/folk --rw-r--r-- myself user 40 1990-05-21 13:30 practice/jazz --rw-r--r-- myself user 10240 1990-05-31 21:49 practice/collection.tar +drwxrwxrwx myself/user 0 1990-05-31 21:49 practice/ +-rw-r--r-- myself/user 42 1990-05-21 13:29 practice/blues +-rw-r--r-- myself/user 62 1990-05-23 10:55 practice/folk +-rw-r--r-- myself/user 40 1990-05-21 13:30 practice/jazz +-rw-r--r-- myself/user 10240 1990-05-31 21:49 practice/collection.tar @end smallexample When you use a directory name as a file name argument, @command{tar} acts on @@ -1567,9 +1566,9 @@ $ @kbd{tar -xvf collection.tar} produces this: @smallexample --rw-r--r-- me user 28 1996-10-18 16:31 jazz --rw-r--r-- me user 21 1996-09-23 16:44 blues --rw-r--r-- me user 20 1996-09-23 16:44 folk +-rw-r--r-- me/user 28 1996-10-18 16:31 jazz +-rw-r--r-- me/user 21 1996-09-23 16:44 blues +-rw-r--r-- me/user 20 1996-09-23 16:44 folk @end smallexample @node extracting files @@ -1683,8 +1682,8 @@ in the example below: @smallexample $ @kbd{tar -xvvf music.tar practice/folk practice/jazz} --rw-r--r-- me user 28 1996-10-18 16:31 practice/jazz --rw-r--r-- me user 20 1996-09-23 16:44 practice/folk +-rw-r--r-- me/user 28 1996-10-18 16:31 practice/jazz +-rw-r--r-- me/user 20 1996-09-23 16:44 practice/folk @end smallexample @noindent @@ -2118,12 +2117,20 @@ end up overwriting files. @subsection Old Option Style @cindex options, old style @cindex old option style +@cindex option syntax, traditional -Like short options, @dfn{old options} are single letters. However, old options +As far as we know, all @command{tar} programs, @acronym{GNU} and +non-@acronym{GNU}, support @dfn{old options}: that is, if the first +argument does not start with @samp{-}, it is assumed to specify option +letters. @GNUTAR{} supports old options not only for historical +reasons, but also because many people are used to them. If the first +argument does not start with a dash, you are announcing the old option +style instead of the short option style; old options are decoded +differently. + +Like short options, old options are single letters. However, old options must be written together as a single clumped set, without spaces separating -them or dashes preceding them@footnote{Beware that if you precede options -with a dash, you are announcing the short option style instead of the -old option style; short options are decoded differently.}. This set +them or dashes preceding them. This set of letters must be the first to appear on the command line, after the @command{tar} program name and some white space; old options cannot appear anywhere else. The letter of an old option is exactly the same letter as @@ -2147,7 +2154,7 @@ $ @kbd{tar cvbf 20 /dev/rmt0} Here, @samp{20} is the argument of @option{-b} and @samp{/dev/rmt0} is the argument of @option{-f}. -On the other hand, this old style syntax makes it difficult to match +The old style syntax can make it difficult to match option letters with their corresponding arguments, and is often confusing. In the command @w{@samp{tar cvbf 20 /dev/rmt0}}, for example, @samp{20} is the argument for @option{-b}, @samp{/dev/rmt0} is the @@ -2173,8 +2180,6 @@ the value for option @samp{f} and recognizes the option @samp{z}. The second example, however, uses @file{z} as the value for option @samp{f} --- probably not what was intended. -Old options are kept for compatibility with old versions of @command{tar}. - This second example could be corrected in many ways, among which the following are equivalent: @@ -2184,16 +2189,6 @@ following are equivalent: @kbd{tar cf archive.tar.gz -z file} @end smallexample -@cindex option syntax, traditional -As far as we know, all @command{tar} programs, @acronym{GNU} and -non-@acronym{GNU}, support old options. @GNUTAR{} -supports them not only for historical reasons, but also because many -people are used to them. For compatibility with Unix @command{tar}, -the first argument is always treated as containing command and option -letters even if it doesn't start with @samp{-}. Thus, @samp{tar c} is -equivalent to @w{@samp{tar -c}:} both of them specify the -@option{--create} (@option{-c}) command to create an archive. - @node Mixing @subsection Mixing Option Styles @@ -2718,9 +2713,9 @@ tutorial}). @item --group=@var{group} Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, -rather than the group from the source file. @var{group} is first decoded -as a group symbolic name, but if this interpretation fails, it has to be -a decimal numeric group @acronym{ID}. @xref{override}. +rather than the group from the source file. @var{group} can specify a +symbolic name, or a numeric @acronym{ID}, or both as +@var{name}:@var{id}. @xref{override}. Also see the comments for the @option{--owner=@var{user}} option. @@ -3087,8 +3082,8 @@ from an archive. @xref{Overwrite Old Files}. Specifies that @command{tar} should use @var{user} as the owner of members when creating archives, instead of the user associated with the source -file. @var{user} is first decoded as a user symbolic name, but if -this interpretation fails, it has to be a decimal numeric user @acronym{ID}. +file. @var{user} can specify a symbolic name, or a numeric +@acronym{ID}, or both as @var{name}:@var{id}. @xref{override}. This option does not affect extraction from archives. @@ -3733,7 +3728,7 @@ $ @kbd{tar xvvf archive.tar} Verbose output appears on the standard output except when an archive is being written to the standard output, as with @samp{tar --create ---file=- --verbose} (@samp{tar cfv -}, or even @samp{tar cv}---if the +--file=- --verbose} (@samp{tar cvf -}, or even @samp{tar cv}---if the installer let standard output be the default archive). In that case @command{tar} writes verbose output to the standard error stream. @@ -4168,7 +4163,7 @@ Disable all warning messages. @samp{Ignoring unknown extended header keyword `%s'} @kwindex decompress-program @item decompress-program -Controls verbose messages describing execution failures when trying +Controls verbose description of failures occurring when trying to run alternative decompressor programs (@pxref{alternative decompression programs}). This warning is disabled by default (unless @option{--verbose} is used). A common example of what you can get @@ -4313,7 +4308,7 @@ the following commands: @smallexample @kbd{tar --create --file=empty-archive.tar --files-from=/dev/null} -@kbd{tar cfT empty-archive.tar /dev/null} +@kbd{tar -cf empty-archive.tar -T /dev/null} @end smallexample @xopindex{extract, complementary notes} @@ -4534,10 +4529,10 @@ If you now use the @option{--list} (@option{-t}) operation, you will see that @smallexample $ @kbd{tar --list --file=collection.tar} --rw-r--r-- me user 28 1996-10-18 16:31 jazz --rw-r--r-- me user 21 1996-09-23 16:44 blues --rw-r--r-- me user 20 1996-09-23 16:44 folk --rw-r--r-- me user 20 1996-09-23 16:44 rock +-rw-r--r-- me/user 28 1996-10-18 16:31 jazz +-rw-r--r-- me/user 21 1996-09-23 16:44 blues +-rw-r--r-- me/user 20 1996-09-23 16:44 folk +-rw-r--r-- me/user 20 1996-09-23 16:44 rock @end smallexample @node multiple @@ -4581,11 +4576,11 @@ list the contents of the archive: @smallexample $ @kbd{tar --list --verbose --file=collection.tar} --rw-r--r-- me user 28 1996-10-18 16:31 jazz --rw-r--r-- me user 21 1996-09-23 16:44 blues --rw-r--r-- me user 20 1996-09-23 16:44 folk --rw-r--r-- me user 20 1996-09-23 16:44 rock --rw-r--r-- me user 58 1996-10-24 18:30 blues +-rw-r--r-- me/user 28 1996-10-18 16:31 jazz +-rw-r--r-- me/user 21 1996-09-23 16:44 blues +-rw-r--r-- me/user 20 1996-09-23 16:44 folk +-rw-r--r-- me/user 20 1996-09-23 16:44 rock +-rw-r--r-- me/user 58 1996-10-24 18:30 blues @end smallexample @noindent @@ -4601,7 +4596,7 @@ the following example: @smallexample $ @kbd{tar --extract -vv --occurrence --file=collection.tar blues} --rw-r--r-- me user 21 1996-09-23 16:44 blues +-rw-r--r-- me/user 21 1996-09-23 16:44 blues @end smallexample @xref{Writing}, for more information on @option{--extract} and @@ -4728,11 +4723,11 @@ contain what they are supposed to: @smallexample $ @kbd{tar -tvf bluesrock.tar} --rw-r--r-- melissa user 105 1997-01-21 19:42 blues --rw-r--r-- melissa user 33 1997-01-20 15:34 rock +-rw-r--r-- melissa/user 105 1997-01-21 19:42 blues +-rw-r--r-- melissa/user 33 1997-01-20 15:34 rock $ @kbd{tar -tvf jazzfolk.tar} --rw-r--r-- melissa user 20 1996-09-23 16:44 folk --rw-r--r-- melissa user 65 1997-01-30 14:15 jazz +-rw-r--r-- melissa/user 20 1996-09-23 16:44 folk +-rw-r--r-- melissa/user 65 1997-01-30 14:15 jazz @end smallexample We can concatenate these two archives with @command{tar}: @@ -4952,8 +4947,22 @@ tar: Option --mtime: Treating date `yesterday' as 2006-06-20 Specifies that @command{tar} should use @var{user} as the owner of members when creating archives, instead of the user associated with the source -file. The argument @var{user} can be either an existing user symbolic -name, or a decimal numeric user @acronym{ID}. +file. + +If @var{user} contains a colon, it is taken to be of the form +@var{name}:@var{id} where a nonempty @var{name} specifies the user +name and a nonempty @var{id} specifies the decimal numeric user +@acronym{ID}. If @var{user} does not contain a colon, it is taken to +be a user number if it is one or more decimal digits; otherwise it is +taken to be a user name. + +If a name is given but no number, the number is inferred from the +current host's user database if possible, and the file's user number +is used otherwise. If a number is given but no name, the name is +inferred from the number if possible, and an empty name is used +otherwise. If both name and number are given, the user database is +not consulted, and the name and number need not be valid on the +current host. There is no value indicating a missing number, and @samp{0} usually means @code{root}. Some people like to force @samp{0} as the value to offer in @@ -4976,8 +4985,9 @@ $ @kbd{tar -c -f archive.tar --owner=root .} @opindex group Files added to the @command{tar} archive will have a group @acronym{ID} of @var{group}, -rather than the group from the source file. The argument @var{group} -can be either an existing group symbolic name, or a decimal numeric group @acronym{ID}. +rather than the group from the source file. As with @option{--owner}, +the argument @var{group} can be an existing group symbolic name, or a +decimal numeric group @acronym{ID}, or @var{name}:@var{id}. @end table @node Ignore Failed Read @@ -8731,7 +8741,7 @@ archive, @option{--lzop} to create an @asis{LSOP} archive, and For example: @smallexample -$ @kbd{tar cfz archive.tar.gz .} +$ @kbd{tar czf archive.tar.gz .} @end smallexample You can also let @GNUTAR{} select the compression program based on @@ -8741,14 +8751,14 @@ example, the following invocation will use @command{bzip2} for compression: @smallexample -$ @kbd{tar cfa archive.tar.bz2 .} +$ @kbd{tar caf archive.tar.bz2 .} @end smallexample @noindent whereas the following one will use @command{lzma}: @smallexample -$ @kbd{tar cfa archive.tar.lzma .} +$ @kbd{tar caf archive.tar.lzma .} @end smallexample For a complete list of file name suffixes recognized by @GNUTAR{}, @@ -8783,7 +8793,7 @@ tried@footnote{To verbosely trace the decompressor selection, use the @option{--warning=decompress-program} option (@pxref{warnings,decompress-program}).}: -@multitable @columnfractions 0.3 0.3 0.3 +@multitable @columnfractions 0.3 0.3 0.3 @headitem Format @tab Main decompressor @tab Alternatives @item compress @tab compress @tab gzip @item lzma @tab lzma @tab xz @@ -8805,7 +8815,7 @@ If you see such diagnostics, just add the suggested option to the invocation of @GNUTAR{}: @smallexample -$ @kbd{cat archive.tar.gz | tar tfz -} +$ @kbd{cat archive.tar.gz | tar tzf -} @end smallexample Notice also, that there are several restrictions on operations on @@ -8876,7 +8886,7 @@ environment variable. For example, when using @command{gzip} you can use @env{GZIP} as in the example below: @smallexample -$ @kbd{GZIP=--best tar cfz archive.tar.gz subdir} +$ @kbd{GZIP=--best tar czf archive.tar.gz subdir} @end smallexample @noindent @@ -9387,9 +9397,9 @@ once. For example, consider the following two files: @smallexample @group -$ ls --rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one --rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden +$ ls -l +-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 one +-rw-r--r-- 2 gray staff 4 2007-10-30 15:11 jeden @end group @end smallexample @@ -9398,7 +9408,7 @@ directory with a verbose level 2, you will get an output similar to the following: @smallexample -$ tar cfvv ../archive.tar . +$ tar cvvf ../archive.tar . drwxr-xr-x gray/staff 0 2007-10-30 15:13 ./ -rw-r--r-- gray/staff 4 2007-10-30 15:11 ./jeden hrw-r--r-- gray/staff 0 2007-10-30 15:11 ./one link to ./jeden @@ -11368,7 +11378,7 @@ second tape, and then back to the first tape, etc., just do either of: @smallexample $ @kbd{tar --create --multi-volume --file=/dev/tape0 --file=/dev/tape1 @var{files}} -$ @kbd{tar cMff /dev/tape0 /dev/tape1 @var{files}} +$ @kbd{tar -cM -f /dev/tape0 -f /dev/tape1 @var{files}} @end smallexample The second method is to use the @samp{n} response to the tape-change @@ -11551,8 +11561,8 @@ explicitly 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-r--r-- ringo user 40 1990-05-21 13:30 iamafilename +V--------- 0/0 0 1992-03-07 12:01 iamalabel--Volume Header-- +-rw-r--r-- ringo/user 40 1990-05-21 13:30 iamafilename @end group @end smallexample @@ -11647,7 +11657,7 @@ 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 -cM -f /dev/tape -V "Daily backup for `date +%Y-%m-%d`"} $ @kbd{tar --create --file=/dev/tape --multi-volume \ --label="Daily backup for `date +%Y-%m-%d`"} @end group