X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=4a49282c60e7f609eb3f475a302cacabab9c6e08;hb=cd7bdd4076ca154575bbef85eb2157e59befcfe2;hp=48e8c3cc002a57f0f5a5e9893f7b578088febc75;hpb=1f9b376c90f50836b1ca2517cda0bfcab75ad8ae;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 48e8c3c..4a49282 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -13,9 +13,9 @@ @c Maintenance notes: @c 1. Pay attention to @FIXME{}s and @UNREVISED{}s @c 2. Before creating final variant: -@c 2.1. Run `make check-options' to make sure all options are properly +@c 2.1. Run 'make check-options' to make sure all options are properly @c documented; -@c 2.2. Run `make master-menu' (see comment before the master menu). +@c 2.2. Run 'make master-menu' (see comment before the master menu). @include rendition.texi @include value.texi @@ -36,21 +36,20 @@ This manual is for @acronym{GNU} @command{tar} (version @value{VERSION}, @value{UPDATED}), which creates and extracts files from archives. -Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, -2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 Free Software Foundation, Inc. +Copyright @copyright{} 1992, 1994--1997, 1999--2001, 2003--2013 Free +Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with the Front-Cover Texts being ``A GNU Manual'', -and with the Back-Cover Texts as in (a) below. A copy of the license -is included in the section entitled ``GNU Free Documentation -License''. +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'', with the +Front-Cover Texts being ``A GNU Manual'', and with the Back-Cover Texts +as in (a) below. A copy of the license is included in the section +entitled ``GNU Free Documentation License''. (a) The FSF's Back-Cover Text is: ``You have the freedom to -copy and modify this GNU manual. Buying copies from the FSF -supports it in developing GNU and promoting software freedom.'' +copy and modify this GNU manual.'' @end quotation @end copying @@ -1438,7 +1437,7 @@ example: @smallexample @group $ @kbd{tar --create --verbose --file archive /etc/mail} -tar: Removing leading `/' from member names +tar: Removing leading '/' from member names /etc/mail/ /etc/mail/sendmail.cf /etc/mail/aliases @@ -1881,6 +1880,7 @@ The other operations of @command{tar} (@option{--list}, @option{--extract}, @option{--compare}, and @option{--update}) will act on the entire contents of the archive. +@anchor{exit status} @cindex exit status @cindex return status Besides successful exits, @GNUTAR{} may fail for @@ -2362,8 +2362,9 @@ exist in the archive. @xref{update}. @itemx -P Normally when creating an archive, @command{tar} strips an initial -@samp{/} from member names. This option disables that behavior. -@xref{absolute}. +@samp{/} from member names, and when extracting from an archive @command{tar} +treats names specially if they have initial @samp{/} or internal +@samp{..}. This option disables that behavior. @xref{absolute}. @opsummary{after-date} @item --after-date @@ -2758,7 +2759,7 @@ Ignore exit codes of subprocesses. @xref{Writing to an External Program}. @item --ignore-failed-read Do not exit unsuccessfully merely because an unreadable file was encountered. -@xref{Reading}. +@xref{Ignore Failed Read}. @opsummary{ignore-zeros} @item --ignore-zeros @@ -2811,7 +2812,10 @@ when extracting files from an archive. @item --keep-old-files @itemx -k -Do not overwrite existing files when extracting files from an archive. +Do not overwrite existing files when extracting files from an +archive. Return error if such files exist. See also +@ref{--skip-old-files}. + @xref{Keep Old Files}. @opsummary{label} @@ -3264,6 +3268,20 @@ the archive creation operations it instructs @command{tar} to list the member names stored in the archive, as opposed to the actual file names. @xref{listing member and file names}. +@opsummary{skip-old-files} +@item --skip-old-files + +Do not overwrite existing files when extracting files from an +archive. @xref{Keep Old Files}. + +This option differs from @option{--keep-old-files} in that it does not +treat such files as an error, instead it just silently avoids +overwriting them. + +The @option{--warning=existing-file} option can be used together with +this option to produce warning messages about existing old files +(@pxref{warnings}). + @opsummary{sparse} @item --sparse @itemx -S @@ -3572,8 +3590,7 @@ successfully. For example, @w{@samp{tar --version}} might print: @smallexample tar (GNU tar) @value{VERSION} -Copyright (C) 2010 Free Software Foundation, Inc. -Copyright (C) 2010 Free Software Foundation, Inc. +Copyright (C) 2013 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later . This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. @@ -4150,17 +4167,17 @@ Disable all warning messages. @item symlink-cast @samp{Attempting extraction of symbolic links as hard links} @kwindex unknown-cast -@cindex @samp{Unknown file type `%c', extracted as normal file}, warning message +@cindex @samp{Unknown file type '%c', extracted as normal file}, warning message @item unknown-cast -@samp{%s: Unknown file type `%c', extracted as normal file} +@samp{%s: Unknown file type '%c', extracted as normal file} @kwindex ignore-newer @cindex @samp{Current %s is newer or same age}, warning message @item ignore-newer @samp{Current %s is newer or same age} @kwindex unknown-keyword -@cindex @samp{Ignoring unknown extended header keyword `%s'}, warning message +@cindex @samp{Ignoring unknown extended header keyword '%s'}, warning message @item unknown-keyword -@samp{Ignoring unknown extended header keyword `%s'} +@samp{Ignoring unknown extended header keyword '%s'} @kwindex decompress-program @item decompress-program Controls verbose description of failures occurring when trying to run @@ -4439,11 +4456,11 @@ in the archive; the most recently archived members will be extracted last. Additionally, an extracted member will @emph{replace} a file of the same name which existed in the directory already, and @command{tar} will not prompt you about this@footnote{Unless you give it -@option{--keep-old-files} option, or the disk copy is newer than -the one in the archive and you invoke @command{tar} with -@option{--keep-newer-files} option.}. Thus, only the most recently archived -member will end up being extracted, as it will replace the one -extracted before it, and so on. +@option{--keep-old-files} (or @option{--skip-old-files}) option, or +the disk copy is newer than the one in the archive and you invoke +@command{tar} with @option{--keep-newer-files} option.}. Thus, only +the most recently archived member will end up being extracted, as it +will replace the one extracted before it, and so on. @cindex extracting @var{n}th copy of the file @xopindex{occurrence, described} @@ -4937,7 +4954,7 @@ For example: @smallexample $ @kbd{tar -c -f archive.tar -v --mtime=yesterday .} -tar: Option --mtime: Treating date `yesterday' as 2006-06-20 +tar: Option --mtime: Treating date 'yesterday' as 2006-06-20 13:06:29.152478 @dots{} @end smallexample @@ -5134,10 +5151,25 @@ such a directory, use the @option{--no-overwrite-dir} option. @cindex Overwriting old files, prevention @xopindex{keep-old-files, introduced} To be even more cautious and prevent existing files from being replaced, use -the @option{--keep-old-files} (@option{-k}) option. It causes @command{tar} to refuse -to replace or update a file that already exists, i.e., a file with the -same name as an archive member prevents extraction of that archive -member. Instead, it reports an error. +the @option{--keep-old-files} (@option{-k}) option. It causes +@command{tar} to refuse to replace or update a file that already +exists, i.e., a file with the same name as an archive member prevents +extraction of that archive member. Instead, it reports an error. For +example: + +@example +$ @kbd{ls} +blues +$ @kbd{tar -x -k -f archive.tar} +tar: blues: Cannot open: File exists +tar: Exiting with failure status due to previous errors +@end example + +@xopindex{skip-old-files, introduced} +If you wish to preserve old files untouched, but don't want +@command{tar} to treat them as errors, use the +@option{--skip-old-files} option. This option causes @command{tar} to +silently skip extracting over existing files. @xopindex{overwrite, introduced} To be more aggressive about altering existing files, use the @@ -5203,16 +5235,24 @@ archive, but remove other files before extracting. @node Keep Old Files @unnumberedsubsubsec Keep Old Files +@GNUTAR{} provides two options to control its actions in a situation +when it is about to extract a file which already exists on disk. + @table @option @opindex keep-old-files @item --keep-old-files @itemx -k -Do not replace existing files from archive. The -@option{--keep-old-files} (@option{-k}) option prevents @command{tar} -from replacing existing files with files with the same name from the -archive. The @option{--keep-old-files} option is meaningless with -@option{--list} (@option{-t}). Prevents @command{tar} from replacing -files in the file system during extraction. +Do not replace existing files from archive. When such a file is +encountered, @command{tar} issues an error message. Upon end of +extraction, @command{tar} exits with code 2 (@pxref{exit status}). + +@item --skip-old-files +Do not replace existing files from archive, but do not treat that +as error. Such files are silently skipped and do not affect +@command{tar} exit status. + +Additional verbosity can be obtained using @option{--warning=existing-file} +together with that option (@pxref{warnings}). @end table @node Keep Newer Files @@ -6907,7 +6947,7 @@ When @command{tar} is invoked with @option{--create} (@option{-c}), @group $ @kbd{tar cf a.tar} tar: Cowardly refusing to create an empty archive -Try `tar --help' or `tar --usage' for more information. +Try 'tar --help' or 'tar --usage' for more information. @end group @end smallexample @@ -7798,7 +7838,7 @@ $ @kbd{tar tf arch.tar --quoting-style=escape} 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 +define quotation marks, use @samp{'} as left and as right quotation marks. Any occurrences of the right quotation mark in a name are escaped with @samp{\}, for example: @@ -7807,13 +7847,13 @@ 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' +'./' +'./a space' +'./a\'single\'quote' +'./a"double"quote' +'./a\\backslash' +'./a\ttab' +'./a\nnewline' @end group @end smallexample @@ -8260,7 +8300,7 @@ ensure he is using the right date. For example: @smallexample @group $ @kbd{tar -c -f archive.tar --after-date='10 days ago' .} -tar: Option --after-date: Treating date `10 days ago' as 2006-06-11 +tar: Option --after-date: Treating date '10 days ago' as 2006-06-11 13:19:37.232434 @end group @end smallexample @@ -8535,6 +8575,10 @@ is not, generally speaking, the same as the one you'd get running scripts for comparing both outputs. @xref{listing member and file names}, for the information on how to handle this case.}. +Symbolic links containing @file{..} or leading @samp{/} can also cause +problems when extracting, so @command{tar} normally extracts them last; +it may create empty files as placeholders during extraction. + If you use the @option{--absolute-names} (@option{-P}) option, @command{tar} will do none of these transformations. @@ -8558,7 +8602,7 @@ to transfer files between systems.} @table @option @item --absolute-names Preserves full file names (including superior directory names) when -archiving files. Preserves leading slash when extracting files. +archiving and extracting files. @end table @@ -8881,39 +8925,30 @@ etc.) and remote files as well as on normal files; data to or from such devices or remote files is reblocked by another copy of the @command{tar} program to enforce the specified (or default) record size. The default compression parameters are used. Most compression -programs allow to override these by setting a program-specific -environment variable. For example, when using @command{gzip} you can -use @env{GZIP} as in the example below: +programs let you override these by setting a program-specific +environment variable. For example, with @command{gzip} you can set +@env{GZIP}: @smallexample -$ @kbd{GZIP=--best tar czf archive.tar.gz subdir} +$ @kbd{GZIP='-9 -n' tar czf archive.tar.gz subdir} @end smallexample @noindent -Another way would be to use the @option{-I} option instead (see -below), e.g.: +The traditional way to do this is to use a pipe: @smallexample -$ @kbd{tar -cf archive.tar.gz -I 'gzip --best' subdir} -@end smallexample - -@noindent -Finally, the third, traditional, way to achieve the same result is to -use pipe: - -@smallexample -$ @kbd{tar cf - subdir | gzip --best -c - > archive.tar.gz} +$ @kbd{tar cf - subdir | gzip -9 -n > archive.tar.gz} @end smallexample @cindex corrupted archives -About corrupted compressed archives: compressed files have no -redundancy, for maximum compression. The adaptive nature of the +Compressed archives are easily corrupted, because compressed files +have little redundancy. The adaptive nature of the compression scheme means that the compression tables are implicitly spread all over the archive. If you lose a few blocks, the dynamic construction of the compression tables becomes unsynchronized, and there is little chance that you could recover later in the archive. -Another compression options provide a better control over creating +Other compression options provide better control over creating compressed archives. These are: @table @option @@ -8948,13 +8983,12 @@ suffix. The following suffixes are recognized: Use external compression program @var{prog}. Use this option if you are not happy with the compression program associated with the suffix at compile time or if you have a compression program that @GNUTAR{} -does not support. There are two requirements to which @var{prog} -should comply: +does not support. The program should follow two conventions: -First, when called without options, it should read data from standard +First, when invoked without options, it should read data from standard input, compress it and output it on standard output. -Secondly, if called with @option{-d} argument, it should do exactly +Secondly, if invoked with the @option{-d} option, it should do exactly the opposite, i.e., read the compressed data from the standard input and produce uncompressed data on the standard output. @end table @@ -9436,7 +9470,7 @@ produces the following diagnostics: @smallexample $ tar -c -f ../archive.tar -l jeden -tar: Missing links to `jeden'. +tar: Missing links to 'jeden'. @end smallexample Although creating special records for hard links helps keep a faithful @@ -9448,7 +9482,7 @@ archive created in previous examples produces, in the absense of file @smallexample $ tar xf archive.tar ./one -tar: ./one: Cannot hard link to `./jeden': No such file or directory +tar: ./one: Cannot hard link to './jeden': No such file or directory tar: Error exit delayed from previous errors @end smallexample @@ -9988,8 +10022,8 @@ run mode is enabled by @option{-n} command line argument: @group $ @kbd{xsparse -n /home/gray/GNUSparseFile.6058/sparsefile} Reading v.1.0 sparse map -Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to -`/home/gray/sparsefile' +Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to +'/home/gray/sparsefile' Finished dry run @end group @end smallexample @@ -10010,8 +10044,8 @@ similar to that from the dry run mode, use @option{-v} option: @group $ @kbd{xsparse -v /home/gray/GNUSparseFile.6058/sparsefile} Reading v.1.0 sparse map -Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to -`/home/gray/sparsefile' +Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to +'/home/gray/sparsefile' Done @end group @end smallexample @@ -10032,8 +10066,8 @@ Found variable GNU.sparse.minor = 0 Found variable GNU.sparse.name = sparsefile Found variable GNU.sparse.realsize = 217481216 Reading v.1.0 sparse map -Expanding file `/home/gray/GNUSparseFile.6058/sparsefile' to -`/home/gray/sparsefile' +Expanding file '/home/gray/GNUSparseFile.6058/sparsefile' to +'/home/gray/sparsefile' Done @end group @end smallexample @@ -10135,7 +10169,7 @@ Found variable GNU.sparse.size = 217481216 Found variable GNU.sparse.numblocks = 208 Found variable GNU.sparse.name = sparsefile Found variable GNU.sparse.map = 0,2048,1050624,2048,@dots{} -Expanding file `GNUSparseFile.28124/sparsefile' to `sparsefile' +Expanding file 'GNUSparseFile.28124/sparsefile' to 'sparsefile' Done @end group @end smallexample @@ -10449,9 +10483,8 @@ want to use. @command{tar} calls @command{rmt} by running an @command{rsh} or @command{remsh} to the remote machine, optionally using a different login name if one is supplied. -A copy of the source for the remote tape server is provided. It is -Copyright @copyright{} 1983 by the Regents of the University of -California, but can be freely distributed. It is compiled and +A copy of the source for the remote tape server is provided. Its +source code can be freely distributed. It is compiled and installed by default. @cindex absolute file names @@ -11257,7 +11290,7 @@ is@footnote{If you run @GNUTAR{} under a different locale, the translation to the locale's language will be used.}: @smallexample -Prepare volume #@var{n} for `@var{archive}' and hit return: +Prepare volume #@var{n} for '@var{archive}' and hit return: @end smallexample @noindent @@ -11393,7 +11426,10 @@ archive being created (as given by @option{--file} option) and @smallexample @group -#! /bin/sh +#! /bin/bash +# For this script it's advisable to use a shell, such as Bash, +# that supports a TAR_FD value greater than 9. + echo Preparing volume $TAR_VOLUME of $TAR_ARCHIVE. name=`expr $TAR_ARCHIVE : '\(.*\)-.*'` @@ -11626,7 +11662,7 @@ you will get: @smallexample @group $ @kbd{tar -rf archive --label 'My volume' .} -tar: Archive not labeled to match `My volume' +tar: Archive not labeled to match 'My volume' @end group @end smallexample @@ -11936,11 +11972,16 @@ lets the archive overwrite any file in your system that you can write, the @option{--absolute-names} (@option{-P}) option should be used only for trusted archives. -Conversely, with the @option{--keep-old-files} (@option{-k}) option, -@command{tar} refuses to replace existing files when extracting; and -with the @option{--no-overwrite-dir} option, @command{tar} refuses to -replace the permissions or ownership of already-existing directories. -These options may help when extracting from untrusted archives. +Conversely, with the @option{--keep-old-files} (@option{-k}) and +@option{--skip-old-files} options, @command{tar} refuses to replace +existing files when extracting. The difference between the two +options is that the former treats existing files as errors whereas the +latter just silently ignores them. + +Finally, with the @option{--no-overwrite-dir} option, @command{tar} +refuses to replace the permissions or ownership of already-existing +directories. These options may help when extracting from untrusted +archives. @node Live untrusted data @subsection Dealing with Live Untrusted Data