X-Git-Url: https://git.brokenzipper.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=e95a3ad2d573f93335f57fb4b61a3393c03d8a50;hb=ab8a1843361ad1b48fecb670ac94978602c60914;hp=09c5f1ab98af68b4f38c5f99c92cadda24d31405;hpb=67770b89f241608b9ff105fd3ea82c6568249b07;p=chaz%2Ftar diff --git a/doc/tar.texi b/doc/tar.texi index 09c5f1a..e95a3ad 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -28,7 +28,7 @@ This manual is for @acronym{GNU} @command{tar} (version from archives. Copyright @copyright{} 1992, 1994, 1995, 1996, 1997, 1999, 2000, 2001, -2003, 2004 Free Software Foundation, Inc. +2003, 2004, 2005, 2006 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -96,6 +96,8 @@ document. The rest of the menu lists all the lower level nodes. Appendices +* Changes:: +* Configuring Help Summary:: * Genfile:: * Snapshot Files:: * Free Software Needs Free Documentation:: @@ -112,7 +114,6 @@ Introduction * Definitions:: Some Definitions * What tar Does:: What @command{tar} Does * Naming tar Archives:: How @command{tar} Archives are Named -* Current status:: Current development status of @GNUTAR{} * Authors:: @GNUTAR{} Authors * Reports:: Reporting bugs or suggestions @@ -349,6 +350,7 @@ GNU tar internals and development Copying This Manual +* Free Software Needs Free Documentation:: * GNU Free Documentation License:: License for copying this manual @end detailmenu @@ -369,7 +371,6 @@ archives need not (and these days, typically do not) reside on tapes. * Definitions:: Some Definitions * What tar Does:: What @command{tar} Does * Naming tar Archives:: How @command{tar} Archives are Named -* Current status:: Current development status of @GNUTAR{} * Authors:: @GNUTAR{} Authors * Reports:: Reporting bugs or suggestions @end menu @@ -537,63 +538,6 @@ the operation of @command{tar}, this causes no difficulty. However, in this manual, we consistently refer to ``archives'' and ``archive members'' to make learning to use @command{tar} easier for novice users. -@node Current status -@section Current development status of @GNUTAR{} - -@GNUTAR{} is currently in the process of active development, whose -primary aims are: - -@itemize @bullet -@item Improve compatibility between @GNUTAR{} and other @command{tar} -implementations. -@item Switch to using @acronym{POSIX} archives. -@item Revise sparse file handling and multiple volume processing. -@item Merge with the @acronym{GNU} @code{paxutils} project. -@end itemize - -Some of these aims are already attained, while others are still -being worked upon. From the point of view of an end user, the -following issues need special mentioning: - -@table @asis -@item Use of short option @option{-o}. - -Earlier versions of @GNUTAR{} understood @option{-o} command line -option as a synonym for @option{--old-archive}. - -@GNUTAR{} starting from version 1.13.90 understands this option as -a synonym for @option{--no-same-owner}. This is compatible with -UNIX98 @command{tar} implementations. - -However, to facilitate transition, @option{-o} option retains its -old semantics when it is used with one of archive-creation commands. -Users are encouraged to use @option{--format=oldgnu} instead. - -It is especially important, since versions of @acronym{GNU} Automake -up to and including 1.8.4 invoke tar with this option to produce -distribution tarballs. @xref{Formats,v7}, for the detailed discussion -of this issue and its implications. - -Future versions of @GNUTAR{} will understand @option{-o} only as a -synonym for @option{--no-same-owner}. - -@item Use of short option @option{-l} - -Earlier versions of @GNUTAR{} understood @option{-l} option as a -synonym for @option{--one-file-system}. Such usage is deprecated. -For compatibility with other implementations future versions of -@GNUTAR{} will understand this option as a synonym for -@option{--check-links}. - -@item Use of options @option{--portability} and @option{--old-archive} - -These options are deprecated. Please use @option{--format=v7} instead. - -@item Use of option @option{--posix} - -This option is deprecated. Please use @option{--format=posix} instead. -@end table - @node Authors @section @GNUTAR{} Authors @@ -1368,7 +1312,7 @@ etc/mail/aliases @table @option @item --show-stored-names -Print member (not @emph{file}) names when creating the archive. +Print member (as opposed to @emph{file}) names when creating the archive. @end table @cindex File name arguments, using @option{--list} with @@ -2343,7 +2287,7 @@ Future versions will take @option{-l} as a short version of @option{--check-links}. However, current release still retains the old semantics for @option{-l}. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @opindex compress, summary @opindex uncompress, summary @@ -2360,6 +2304,12 @@ while saving space. @xref{gzip}. (See @option{--interactive}.) @xref{interactive}. +@opindex delay-directory-restore, summary +@item --delay-directory-restore + +Delay setting modification times and permissions of extracted +directories until the end of extraction. @xref{Directory Modification Times and Permissions}. + @opindex dereference, summary @item --dereference @itemx -h @@ -2624,6 +2574,13 @@ also back up files for which any status information has changed). An exclude pattern can match any subsequence of the name's components. @xref{controlling pattern-matching with exclude}. +@opindex no-delay-directory-restore, summary +@item --no-delay-directory-restore + +Setting modification times and permissions of extracted +directories when all files from this directory has been +extracted. This is the default. @xref{Directory Modification Times and Permissions}. + @opindex no-ignore-case, summary @item --no-ignore-case Use case-sensitive matching when excluding files. @@ -2634,6 +2591,11 @@ Use case-sensitive matching when excluding files. Print warnings about subprocesses terminated with a non-zero exit code. @xref{Writing to an External Program}. +@opindex no-quote-chars, summary +@item --no-quote-chars=@var{string} +Do not quote characters from @var{string}, even if the selected +quoting style implies they should be quoted (@FIXME-pxref{Quoting Styles}). + @opindex no-recursion, summary @item --no-recursion @@ -2690,7 +2652,7 @@ When creating an archive, @option{-o} is a synonym for with previous versions of @GNUTAR{}, and will be removed in the future releases. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @opindex occurrence, summary @item --occurrence[=@var{number}] @@ -2728,7 +2690,7 @@ allowed in the present version, it is @emph{strongly discouraged}. The future versions of @GNUTAR{} will use @option{-l} as a synonym for @option{--check-links}. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @opindex overwrite, summary @item --overwrite @@ -2758,6 +2720,20 @@ anonymous anyway, so that might as well be the owner of anonymous archives. This option does not affect extraction from archives. +@opindex quote-chars, summary +@item --quote-chars=@var{string} +Always quote characters from @var{string}, even if the selected +quoting style would not quote them (@FIXME-pxref{Quoting Styles}). + +@opindex quoting-style, summary +@item --quoting-style=@var{style} +Set quoting style to use when printing member and file names +(@FIXME-pxref{Quoting Styles}). Valid @var{style} values are: +@code{literal}, @code{shell}, @code{shell-always}, @code{c}, +@code{escape}, @code{locale}, and @code{clocale}. Default quoting +style is @code{escape}, unless overridden while configuring the +package. + @opindex pax-option, summary @item --pax-option=@var{keyword-list} @FIXME{Such a detailed description does not belong there, move it elsewhere.} @@ -2984,7 +2960,8 @@ Here is an example of what you can see using this option: @smallexample $ tar --show-defaults ---format=gnu -f- -b20 +--format=gnu -f- -b20 --quoting-style=escape \ +--rmt-command=/usr/libexec/rmt --rsh-command=/usr/bin/rsh @end smallexample @opindex show-omitted-dirs, summary @@ -3272,7 +3249,7 @@ them with the equivalent long option. is retained for compatibility with the earlier versions of GNU @command{tar}, and will be changed in future releases. -@xref{Current status}, for more information. +@xref{Changes}, for more information. @item -m @@ -3389,6 +3366,9 @@ for getting only the pertinent lines. Notice, however, that some @command{tar} options have long description lines and the above command will list only the first of them. +The exact look of the option summary displayed by @kbd{tar --help} is +configurable. @xref{Configuring Help Summary}, for a detailed description. + @opindex usage If you only wish to check the spelling of an option, running @kbd{tar --usage} may be a better choice. This will display a terse list of @@ -4350,6 +4330,7 @@ encountered while reading an archive. Use in conjunction with * Recursive Unlink:: * Data Modification Times:: * Setting Access Permissions:: +* Directory Modification Times and Permissions:: * Writing to Standard Output:: * Writing to an External Program:: * remove files:: @@ -4536,6 +4517,85 @@ archive, instead of current umask settings. Use in conjunction with @option{--extract} (@option{--get}, @option{-x}). @end table +@node Directory Modification Times and Permissions +@unnumberedsubsubsec Directory Modification Times and Permissions + +After sucessfully extracting a file member, @GNUTAR{} normally +restores its permissions and modification times, as described in the +previous sections. This cannot be done for directories, because +after extracting a directory @command{tar} will almost certainly +extract files into that directory and this will cause the directory +modification time to be updated. Moreover, restoring that directory +permissions may not permit file creation within it. Thus, restoring +directory permissions and modification times must be delayed at least +until all files have been extracted into that directory. @GNUTAR{} +restores directories using the following approach. + +The extracted directories are created with the mode specified in the +archive, as modified by the umask of the user, which gives sufficient +permissions to allow file creation. The meta-information about the +directory is recorded in the temporary list of directories. When +preparing to extract next archive member, @GNUTAR{} checks if the +directory prefix of this file contains the remembered directory. If +it does not, the program assumes that all files have been extracted +into that directory, restores its modification time and permissions +and removes its entry from the internal list. This approach allows +to correctly restore directory meta-information in the majority of +cases, while keeping memory requirements sufficiently small. It is +based on the fact, that most @command{tar} archives use the predefined +order of members: first the directory, then all the files and +subdirectories in that directory. + +However, this is not always true. The most important exception are +incremental archives (@pxref{Incremental Dumps}). The member order in +an incremental archive is reversed: first all directory members are +stored, followed by other (non-directory) members. So, when extracting +from incremental archives, @GNUTAR{} alters the above procedure. It +remebers all restored directories, and restores their meta-data +only after the entire archive has been processed. Notice, that you do +not need to specity any special options for that, as @GNUTAR{} +automatically detects archives in incremental format. + +There may be cases, when such processing is required for normal archives +too. Consider the following example: + +@smallexample +@group +$ @kbd{tar --no-recursion -cvf archive \ + foo foo/file1 bar bar/file foo/file2} +foo/ +foo/file1 +bar/ +bar/file +foo/file2 +@end group +@end smallexample + +During the normal operation, after encountering @file{bar} +@GNUTAR{} will assume that all files from the directory @file{foo} +were already extracted and will therefore restore its timestamp and +permission bits. However, after extracting @file{foo/file2} the +directory timestamp will be offset again. + +To correctly restore directory meta-information in such cases, use +@option{delay-directory-restore} command line option: + +@table @option +@opindex delay-directory-restore +@item --delay-directory-restore +Delays restoring of the modification times and permissions of extracted +directories until the end of extraction. This way, correct +meta-information is restored even if the archive has unusual member +ordering. + +@opindex no-delay-directory-restore +@item --no-delay-directory-restore +Cancel the effect of the previous @option{--delay-directory-restore}. +Use this option if you have used @option{--delay-directory-restore} in +@env{TAR_OPTIONS} variable (@pxref{TAR_OPTIONS}) and wish to +temporarily disable it. +@end table + @node Writing to Standard Output @unnumberedsubsubsec Writing to Standard Output @@ -7097,40 +7157,36 @@ a @command{tar} able to read the good archives they receive. @cindex large values @cindex future time stamps @cindex negative time stamps - -@acronym{POSIX} @command{tar} format uses fixed-sized unsigned octal strings -to represent numeric values. User and group IDs and device major and -minor numbers have unsigned 21-bit representations, and file sizes and -times have unsigned 33-bit representations. @GNUTAR{} -generates @acronym{POSIX} representations when possible, but for values -outside the @acronym{POSIX} range it generates two's-complement base-256 -strings: uids, gids, and device numbers have signed 57-bit -representations, and file sizes and times have signed 89-bit -representations. These representations are an extension to @acronym{POSIX} -@command{tar} format, so they are not universally portable. - -The most common portability problems with out-of-range numeric values -are large files and future or negative time stamps. - -Portable archives should avoid members of 8 GB or larger, as @acronym{POSIX} -@command{tar} format cannot represent them. - -Portable archives should avoid time stamps from the future. @acronym{POSIX} -@command{tar} format can represent time stamps in the range 1970-01-01 -00:00:00 through 2242-03-16 12:56:31 @sc{utc}. However, many current -hosts use a signed 32-bit @code{time_t}, or internal time stamp format, -and cannot represent time stamps after 2038-01-19 03:14:07 @sc{utc}; so -portable archives must avoid these time stamps for many years to come. - -Portable archives should also avoid time stamps before 1970. These time -stamps are a common @acronym{POSIX} extension but their @code{time_t} -representations are negative. Many traditional @command{tar} -implementations generate a two's complement representation for negative -time stamps that assumes a signed 32-bit @code{time_t}; hence they -generate archives that are not portable to hosts with differing -@code{time_t} representations. @GNUTAR{} recognizes this -situation when it is run on host with a signed 32-bit @code{time_t}, but -it issues a warning, as these time stamps are nonstandard and unportable. +@UNREVISED{} + +The above sections suggest to use @samp{oldest possible} archive +format if in doubt. However, sometimes it is not possible. If you +attempt to archive a file whose metadata cannot be represented using +required format, @GNUTAR{} will print error message and ignore such a +file. You will than have to switch to a format that is able to +handle such values. The format summary table (@pxref{Formats}) will +help you to do so. + +In particular, when trying to archive files larger than 8GB or with +timestamps not in the range 1970-01-01 00:00:00 through 2242-03-16 +12:56:31 @sc{utc}, you will have to chose between @acronym{GNU} and +@acronym{POSIX} archive formats. When considering which format to +choose, bear in mind that the @acronym{GNU} format uses +two's-complement base-256 notation to store values that do not fit +into standard @acronym{ustar} range. Such archives can generally be +read only by a @GNUTAR{} implementation. Moreover, they sometimes +cannot be correctly restored on another hosts even by @GNUTAR{}. For +example, using two's complement representation for negative time +stamps that assumes a signed 32-bit @code{time_t} generates archives +that are not portable to hosts with differing @code{time_t} +representations. + +On the other hand, @acronym{POSIX} archives, generally speaking, can +be extracted by any tar implementation that understands older +@acronym{ustar} format. The only exception are files larger than 8GB. + +@FIXME{Describe how @acronym{POSIX} archives are extracted by non +POSIX-aware tars.} @node Compression @section Using Less Space through Compression @@ -9405,9 +9461,266 @@ disabled) switch, a notch which can be popped out or covered, a ring which can be removed from the center of a tape reel, or some other changeable feature. -@node Free Software Needs Free Documentation -@appendix Free Software Needs Free Documentation -@include freemanuals.texi +@node Changes +@appendix Changes + +This appendix lists some important user-visible changes between +version @GNUTAR{} @value{VERSION} and previous versions. An up-to-date +version of this document is available at +@uref{http://www.gnu.org/@/software/@/tar/manual/changes.html,the +@GNUTAR{} documentation page}. + +@table @asis +@item Use of short option @option{-o}. + +Earlier versions of @GNUTAR{} understood @option{-o} command line +option as a synonym for @option{--old-archive}. + +@GNUTAR{} starting from version 1.13.90 understands this option as +a synonym for @option{--no-same-owner}. This is compatible with +UNIX98 @command{tar} implementations. + +However, to facilitate transition, @option{-o} option retains its +old semantics when it is used with one of archive-creation commands. +Users are encouraged to use @option{--format=oldgnu} instead. + +It is especially important, since versions of @acronym{GNU} Automake +up to and including 1.8.4 invoke tar with this option to produce +distribution tarballs. @xref{Formats,v7}, for the detailed discussion +of this issue and its implications. + +Future versions of @GNUTAR{} will understand @option{-o} only as a +synonym for @option{--no-same-owner}. + +@item Use of short option @option{-l} + +Earlier versions of @GNUTAR{} understood @option{-l} option as a +synonym for @option{--one-file-system}. Such usage is deprecated. +For compatibility with other implementations future versions of +@GNUTAR{} will understand this option as a synonym for +@option{--check-links}. + +@item Use of options @option{--portability} and @option{--old-archive} + +These options are deprecated. Please use @option{--format=v7} instead. + +@item Use of option @option{--posix} + +This option is deprecated. Please use @option{--format=posix} instead. +@end table + +@node Configuring Help Summary +@appendix Configuring Help Summary + +Running @kbd{tar --help} displays the short @command{tar} option +summary (@pxref{help}). This summary is organised by @dfn{groups} of +semantically close options. The options within each group are printed +in the following order: a short option, eventually followed by a list +of corresponding long option names, followed by a short description of +the option. For example, here is an excerpt from the actual @kbd{tar +--help} output: + +@verbatim + Main operation mode: + + -A, --catenate, --concatenate append tar files to an archive + -c, --create create a new archive + -d, --diff, --compare find differences between archive and + file system + --delete delete from the archive +@end verbatim + +@vrindex ARGP_HELP_FMT, environment variable +The exact visual representation of the help output is configurable via +@env{ARGP_HELP_FMT} environment variable. The value of this variable +is a comma-separated list of @dfn{format variable} assignments. There +are two kinds of format variables. An @dfn{offset variable} keeps the +offset of some part of help output text from the leftmost column on +the screen. A @dfn{boolean} variable is a flag that toggles some +output feature on or off. Depending on the type of the corresponding +variable, there are two kinds of assignments: + +@table @asis +@item Offset assignment + +The assignment to an offset variable has the following syntax: + +@smallexample +@var{variable}=@var{value} +@end smallexample + +@noindent +where @var{variable} is the variable name, and @var{value} is a +numeric value to be assigned to the variable. + +@item Boolean assignment + +To assign @code{true} value to a variable, simply put this variable name. To +assign @code{false} value, prefix the variable name with @samp{no-}. For +example: + +@smallexample +@group +# Assign @code{true} value: +dup-args +# Assign @code{false} value: +no-dup-args +@end group +@end smallexample +@end table + +Following variables are declared: + +@deftypevr {Help Output} boolean dup-args +If true, arguments for an option are shown with both short and long +options, even when a given option has both forms, for example: + +@smallexample + -f ARCHIVE, --file=ARCHIVE use archive file or device ARCHIVE +@end smallexample + +If false, then if an option has both short and long forms, the +argument is only shown with the long one, for example: + +@smallexample + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end smallexample + +@noindent +and a message indicating that the argument is applicable to both +forms is printed below the options. This message can be disabled +using @code{dup-args-note} (see below). + +The default is false. +@end deftypevr + +@deftypevr {Help Output} boolean dup-args-note +If this variable is true, which is the default, the following notice +is displayed at the end of the help output: + +@quotation +Mandatory or optional arguments to long options are also mandatory or +optional for any corresponding short options. +@end quotation + +Setting @code{no-dup-args-note} inhibits this message. Normally, only one of +variables @code{dup-args} or @code{dup-args-note} should be set. +@end deftypevr + +@deftypevr {Help Output} offset short-opt-col +Column in which short options start. Default is 2. + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=short-opt-col=6 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset long-opt-col +Column in which long options start. Default is 6. For example: + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=long-opt-col=16 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset doc-opt-col +Column in which @dfn{doc options} start. A doc option isn't actually +an option, but rather an arbitrary piece of documentation that is +displayed in much the same manner as the options. For example, in +the description of @option{--format} option: + +@smallexample +@group + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format +@end group +@end smallexample + +@noindent +the format names are doc options. Thus, if you set +@kbd{ARGP_HELP_FMT=doc-opt-col=6} the above part of the help output +will look as follows: + +@smallexample +@group + -H, --format=FORMAT create archive of the given format. + + FORMAT is one of the following: + + gnu GNU tar 1.13.x format + oldgnu GNU format as per tar <= 1.12 + pax POSIX 1003.1-2001 (pax) format + posix same as pax + ustar POSIX 1003.1-1988 (ustar) format + v7 old V7 tar format +@end group +@end smallexample +@end deftypevr + +@deftypevr {Help Output} offset opt-doc-col +Column in which option description starts. Default is 29. + +@smallexample +@group +$ @kbd{tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=opt-doc-col=19 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE use archive file or device ARCHIVE +$ @kbd{ARGP_HELP_FMT=opt-doc-col=9 tar --help|grep ARCHIVE} + -f, --file=ARCHIVE + use archive file or device ARCHIVE +@end group +@end smallexample + +@noindent +Notice, that the description starts on a separate line if +@code{opt-doc-col} value is too small. +@end deftypevr + +@deftypevr {Help Output} offset header-col +Column in which @dfn{group headers} are printed. A group header is a +descriptive text preceding an option group. For example, in the +following text: + +@verbatim + Main operation mode: + + -A, --catenate, --concatenate append tar files to + an archive + -c, --create create a new archive +@end verbatim +@noindent +@samp{Main operation mode:} is the group header. + +The default value is 1. +@end deftypevr + +@deftypevr {Help Output} offset usage-indent +Indentation of wrapped usage lines. Affects @option{--usage} +output. Default is 12. +@end deftypevr + +@deftypevr {Help Output} offset rmargin +Right margin of the text output. Used for wrapping. +@end deftypevr @node Genfile @appendix Genfile @@ -9417,6 +9730,10 @@ changeable feature. @appendix Format of the Incremental Snapshot Files @include snapshot.texi +@node Free Software Needs Free Documentation +@appendix Free Software Needs Free Documentation +@include freemanuals.texi + @node Copying This Manual @appendix Copying This Manual