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
Appendices
* Changes::
+* Configuring Help Summary::
* Genfile::
* Snapshot Files::
* Free Software Needs Free Documentation::
--show-defaults}, @pxref{defaults}). If there is no tape drive
attached, or the default is not meaningful, then @command{tar} will
print an error message. The error message might look roughly like one
-of the following:
+of the following:
@smallexample
tar: can't open /dev/rmt8 : No such device or address
@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
@option{-x}) operation. As with @option{--create}, specify the name
of the archive with @option{--file} (@option{-f}) option. Extracting
an archive does not modify the archive in any way; you can extract it
-multiple times if you want or need to.
+multiple times if you want or need to.
Using @option{--extract}, you can extract an entire archive, or specific
files. The files can be directories containing other files, or not. As
Output}).
If you give the @option{--verbose} option, then @option{--extract}
-will print the names of the archive members as it extracts them.
+will print the names of the archive members as it extracts them.
@node extract dir
@subsection Extracting Files that are Directories
working directory. @command{tar} will make all file names relative
(by removing leading slashes when archiving or restoring files),
unless you specify otherwise (using the @option{--absolute-names}
-option). @xref{absolute}, for more information about
+option). @xref{absolute}, for more information about
@option{--absolute-names}.
If you give the name of a directory as either a file name or a member
that everything went well, besides maybe innocuous warnings. Nonzero
means that something went wrong. Right now, as of today, ``nonzero''
is almost always 2, except for remote operations, where it may be
-128.
+128.
@node using tar options
@section Using @command{tar} Options
(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
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.
@opindex no-ignore-command-error, summary
@item --no-ignore-command-error
Print warnings about subprocesses terminated with a non-zero exit
-code. @xref{Writing to an External Program}.
+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
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.}
@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
@opindex version, summary
@item --version
-@command{tar} will print an informational message about what version
-it is and a copyright message, some credits, and then exit.
+Print information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
@xref{help}.
@opindex volno-file, summary
@cindex Version of the @command{tar} program
Being careful, the first thing is really checking that you are using
@GNUTAR{}, indeed. The @option{--version} option
-will generate a message giving confirmation that you are using
-@GNUTAR{}, with the precise version of @GNUTAR{}
-you are using. @command{tar} identifies itself and
-prints the version number to the standard output, then immediately
-exits successfully, without doing anything else, ignoring all other
-options. For example, @w{@samp{tar --version}} might return:
+causes @command{tar} to print information about its name, version,
+origin and legal status, all on standard output, and then exit
+successfully. For example, @w{@samp{tar --version}} might print:
@smallexample
-tar (@acronym{GNU} tar) @value{VERSION}
+tar (GNU tar) 1.15.2
+Copyright (C) 2006 Free Software Foundation, Inc.
+This is free software. You may redistribute copies of it under the terms of
+the GNU General Public License <http://www.gnu.org/licenses/gpl.html>.
+There is NO WARRANTY, to the extent permitted by law.
+
+Written by John Gilmore and Jay Fenlason.
@end smallexample
@noindent
contains@footnote{There are plans to merge the @command{cpio} and
@command{tar} packages into a single one which would be called
@code{paxutils}. So, who knows if, one of this days, the
-@option{--version} would not yield @w{@samp{tar (@acronym{GNU}
+@option{--version} would not output @w{@samp{tar (@acronym{GNU}
paxutils) 3.2}}}.
@cindex Obtaining help
@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
(@option{-v}) option causes @command{tar} to print the name of each
file or archive member as it is processed. This and the other options
which make @command{tar} print status information can be useful in
-monitoring @command{tar}.
+monitoring @command{tar}.
With @option{--create} or @option{--extract}, @option{--verbose} used
once just prints the names of the files or members as they are processed.
The basic @command{tar} operations, @option{--create} (@option{-c}),
@option{--list} (@option{-t}) and @option{--extract} (@option{--get},
-@option{-x}), are currently presented and described in the tutorial
+@option{-x}), are currently presented and described in the tutorial
chapter of this manual. This section provides some complementary notes
for these operations.
around the cautiousness of @GNUTAR{} and nevertheless create an
archive with nothing in it, one may still use, as the value for the
@option{--files-from} option, a file with no names in it, as shown in
-the following commands:
+the following commands:
@smallexample
@kbd{tar --create --file=empty-archive.tar --files-from=/dev/null}
@noindent
would extract only the second copy. @xref{Option
Summary,---occurrence}, for the description of @option{--occurrence}
-option.
+option.
@FIXME{ hag -- you might want to incorporate some of the above into the
MMwtSN node; not sure. i didn't know how to make it simpler...
@opindex update
In the previous section, you learned how to use @option{--append} to
-add a file to an existing archive. A related operation is
+add a file to an existing archive. A related operation is
@option{--update} (@option{-u}). The @option{--update} operation
updates a @command{tar} archive by comparing the date of the specified
archive members against the date of the file with the same name. If
the file has been modified more recently than the archive member, then
the newer version of the file is added to the archive (as with
-@option{--append}).
+@option{--append}).
Unfortunately, you cannot use @option{--update} with magnetic tape drives.
The operation will fail.
-rw-r--r-- melissa user 65 1997-01-30 14:15 jazz
@end smallexample
-We can concatenate these two archives with @command{tar}:
+We can concatenate these two archives with @command{tar}:
@smallexample
$ @kbd{cd ..}
read the archive by specifying @option{--read-full-records} (@option{-B}) and
@option{--blocking-factor=@var{512-size}} (@option{-b
@var{512-size}}), using a blocking factor larger than what the archive
-uses. This lets you avoid having to determine the blocking factor
+uses. This lets you avoid having to determine the blocking factor
of an archive. @xref{Blocking Factor}.
@menu
* Recursive Unlink::
* Data Modification Times::
* Setting Access Permissions::
+* Directory Modification Times and Permissions::
* Writing to Standard Output::
* Writing to an External Program::
* remove files::
conjunction with @option{--extract} (@option{--get}, @option{-x}).
@table @option
-@opindex touch
+@opindex touch
@item --touch
@itemx -m
Sets the data modification time of extracted archive members to the time
@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
the contents of the files extracted to its standard output. This may
be useful if you are only extracting the files in order to send them
through a pipe. This option is meaningless with @option{--list}
-(@option{-t}).
+(@option{-t}).
@end table
This can be useful, for example, if you have a tar archive containing
To process large lists of file names on machines with small amounts of
memory. Use in conjunction with @option{--compare} (@option{--diff},
@option{-d}), @option{--list} (@option{-t}) or @option{--extract}
-(@option{--get}, @option{-x}).
+(@option{--get}, @option{-x}).
@end table
The @option{--same-order} (@option{--preserve-order}, @option{-s}) option tells @command{tar} that the list of file
not corrupt the entire archive.)
You will want to use the @option{--label=@var{archive-label}}
-(@option{-V @var{archive-label}}) option to give the archive a
+(@option{-V @var{archive-label}}) option to give the archive a
volume label, so you can tell what this archive is even if the label
falls off the tape, or anything like that.
If you want to dump each file system separately you will need to use
the @option{--one-file-system} (@option{-l}) option to prevent
@command{tar} from crossing file system boundaries when storing
-(sub)directories.
+(sub)directories.
The @option{--incremental} (@option{-G}) (@pxref{Incremental Dumps})
option is not needed, since this is a complete copy of everything in
the file system, and a full restore from this backup would only be
-done onto a completely
+done onto a completely
empty disk.
Unless you are in a hurry, and trust the @command{tar} program (and your
@GNUTAR{} currently offers two options for handling incremental
backups: @option{--listed-incremental=@var{snapshot-file}} (@option{-g
-@var{snapshot-file}}) and @option{--incremental} (@option{-G}).
+@var{snapshot-file}}) and @option{--incremental} (@option{-G}).
@opindex listed-incremental
The option @option{--listed-incremental} instructs tar to operate on
@itemx --help
Display short help message and exit.
-@item -L
-@itemx --license
-Display program license and exit.
-
@item -V
@itemx --version
-Display program version and exit.
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
@end table
@itemx --help
Display short help message and exit.
-@item -L
-@itemx --license
-Display program license and exit.
-
@item -V
@itemx --version
-Display program version and exit.
+Display information about the program's name, version, origin and legal
+status, all on standard output, and then exit successfully.
@end table
You should start the restore script with the media containing the
@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.
+use the @option{--exclude} or @option{--exclude-from} options.
@table @option
@opindex exclude
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.
+more easily excluded from backups.
@menu
* controlling pattern-matching with exclude::
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.
+zero, one, or many files.
@item
When you use @option{--exclude=@var{pattern}}, be sure to quote the @var{pattern}
@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.
+file.
@end itemize
@FIXME{show dan bob's comments, from 2-10-97}
Usually, @command{tar} will recursively explore all directories (either
-those given on the command line or through the @option{--files-from}
+those given on the command line or through the @option{--files-from}
option) for the various files they contain. However, you may not always
want @command{tar} to act this way.
@option{--same-permissions} (@option{--preserve-permissions},
@option{-p}) option does not affect them---while users might really
like it to. Specifying @option{--no-recursion} is a way to tell
-@command{tar} to grab only the directory entries given to it, adding
+@command{tar} to grab only the directory entries given to it, adding
no new files on its own.
The @option{--no-recursion} option also applies when extracting: it
@option{--sparse} is not needed on extraction) any such
files have holes created wherever the continuous stretches of zeros
were found. Thus, if you use @option{--sparse}, @command{tar} archives
-won't take more space than the original.
+won't take more space than the original.
A file is sparse if it contains blocks of zeros whose existence is
recorded, but that have no space allocated on disk. When you specify
@itemx --new-volume-script=@var{file}
Execute @file{file} at end of each tape. This implies
@option{--multi-volume} (@option{-M}). @xref{info-script}, for a detailed
-description of this option.
+description of this option.
@end table
@node Remote Tape Server
@option{--delete} commands will not work on any other kind of file.
Some media simply cannot be backspaced, which means these commands and
options will never be able to work on them. These non-backspacing
-media include pipes and cartridge tape drives.
+media include pipes and cartridge tape drives.
Some other media can be backspaced, and @command{tar} will work on them
once @command{tar} is modified to do so.
@xref{Standard}.) Each file written to the archive uses at least one
full record. As a result, using a larger record size can result in
more wasted space for small files. On the other hand, a larger record
-size can often be read and written much more efficiently.
+size can often be read and written much more efficiently.
Further complicating the problem is that some tape drives ignore the
blocking entirely. For these, a larger record size can still improve
The default blocking factor is typically 20 (i.e., 10240 bytes), but
can be specified at installation. To find out the blocking factor of
an existing archive, use @samp{tar --list --file=@var{archive-name}}.
-This may not work on some devices.
+This may not work on some devices.
Records are separated by gaps, which waste space on the archive media.
If you are archiving on magnetic tape, using a larger blocking factor
If @option{--read-full-records} is used, @command{tar}
will not panic if an attempt to read a record from the archive does
not return a full record. Instead, @command{tar} will keep reading
-until it has obtained a full
+until it has obtained a full
record.
This option is turned on by default when @command{tar} is reading
be a program (or shell script) to be run instead of the normal
prompting procedure. It is executed without any command line
arguments. Additional data is passed to it via the following
-environment variables:
+environment variables:
@table @env
@vrindex TAR_VERSION, info script environment variable
@item TAR_VERSION
@GNUTAR{} version number.
-@vrindex TAR_ARCHIVE, info script environment variable
+@vrindex TAR_ARCHIVE, info script environment variable
@item TAR_ARCHIVE
The name of the archive @command{tar} is processing.
@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 executed.
@xref{Operations}, for a complete list of subcommand options.
@vrindex TAR_FORMAT, info script environment variable
@item TAR_FORMAT
Format of the archive being processed. @xref{Formats}, for a complete
-list of archive format names.
+list of archive format names.
@end table
The info script can instruct @command{tar} to use new archive name,
example).
If the info script fails, @command{tar} exits; otherwise, it begins
-writing the next volume.
+writing the next volume.
The method @command{tar} uses to detect end of tape is not perfect, and
fails on some operating systems or on some devices. You can use the
selects @option{--multi-volume} (@option{-M}) automatically. The
@var{size} argument should then be the usable size of the tape in
units of 1024 bytes. But for many devices, and floppy disks in
-particular, this option is never required for real, as far as we know.
+particular, this option is never required for real, as far as we know.
@cindex Volume number file
@cindex volno file
the @option{--create} option (@pxref{create}). A @dfn{multi-volume}
archive can be manipulated like any other archive (provided the
@option{--multi-volume} option is specified), but is stored on more
-than one tape or disk.
+than one tape or disk.
When you specify @option{--multi-volume}, @command{tar} does not report an
error when it comes to the end of an archive volume (when reading), or
automatically label volumes which are added later. To label
subsequent volumes, specify @option{--label=@var{archive-label}} again
in conjunction with the @option{--append}, @option{--update} or
-@option{--concatenate} operation.
+@option{--concatenate} operation.
@cindex Labeling multi-volume archives
@FIXME{example}
you give, where @var{nnn} is the number of the volume of the archive.
(If you use the @option{--label=@var{volume-label}}) option when
reading an archive, it checks to make sure the label on the tape
-matches the one you give. @xref{label}.
+matches the one you give. @xref{label}.
When @command{tar} writes an archive to tape, it creates a single
tape file. If multiple archives are written to the same tape, one
contains the name of the archive---in the archive itself. Use the
@option{--label=@var{archive-label}} (@option{-V @var{archive-label}})
option in conjunction with the @option{--create} operation to include
-a label entry in the archive as it is being created.
+a label entry in the archive as it is being created.
@table @option
@item --label=@var{archive-label}
One can explicitly compare an already made archive with the file
system by using the @option{--compare} (@option{--diff}, @option{-d})
option, instead of using the more automatic @option{--verify} option.
-@xref{compare}.
+@xref{compare}.
Note that these two options have a slightly different intent. The
@option{--compare} option checks how identical are the logical contents of some
archive with what is on your disks, while the @option{--verify} option is
really for checking if the physical contents agree and if the recording
-media itself is of dependable quality. So, for the @option{--verify}
+media itself is of dependable quality. So, for the @option{--verify}
operation, @command{tar} tries to defeat all in-memory cache pertaining to
the archive, while it lets the speed optimization undisturbed for the
@option{--compare} option. If you nevertheless use @option{--compare} for
conjunction with the @option{--multi-volume} (@option{-M}) option or
the @option{--append} (@option{-r}), @option{--update} (@option{-u})
and @option{--delete} operations. @xref{Operations}, for more
-information on these operations.
+information on these operations.
Also, since @command{tar} normally strips leading @samp{/} from file
names (@pxref{absolute}), a command like @samp{tar --verify -cf
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
@include genfile.texi
@c Local variables:
@c texinfo-column-for-description: 32
@c End:
-
projects / chaz / tar / blobdiff