X-Git-Url: https://git.dogcows.com/gitweb?a=blobdiff_plain;f=doc%2Ftar.texi;h=ece40f4e7cf3903ae1811e33210c6b5cf4c70e0e;hb=2af87fa2776c8125a587a9b0c2c4fae3bf921ff7;hp=5df61b1481f3cc087fa1be37e6a8b852aff00599;hpb=f92cb1fe1655ff29a19e1c978303284c3b36159a;p=chaz%2Ftar

diff --git a/doc/tar.texi b/doc/tar.texi
index 5df61b1..ece40f4 100644
--- a/doc/tar.texi
+++ b/doc/tar.texi
@@ -2804,6 +2804,21 @@ Specifies that @command{tar} should ask the user for confirmation before
 performing potentially destructive options, such as overwriting files.
 @xref{interactive}.
 
+@opsummary{--keep-directory-symlink}
+@item --keep-directory-symlink
+
+This option changes the behavior of tar when it encounters a symlink
+with the same name as the directory that it is about to extract.  By
+default, in this case tar would first remove the symlink and then
+proceed extracting the directory.
+
+The @option{--keep-directory-symlink} option disables this behavior
+and instructs tar to follow symlinks to directories when extracting
+from the archive.
+
+It is mainly intended to provide compatibility with the Slackware
+installation scripts.
+
 @opsummary{keep-newer-files}
 @item --keep-newer-files
 
@@ -3071,6 +3086,17 @@ Used when creating an archive.  Prevents @command{tar} from recursing into
 directories that are on different file systems from the current
 directory.
 
+@opsummary{one-top-level}
+@item --one-top-level
+Tells @command{tar} to create a new directory beneath the extraction directory
+(or the one passed to @option{-C}) and use it to guard against tarbombs.  The
+name of the new directory will be equal to the name of the archive with the
+extension stripped off.  If any archive names (after transformations from
+@option{--transform} and @option{--strip-components}) do not already begin with
+it, the new directory will be prepended to the names immediately before
+extraction.  Recognized extensions are @samp{.tar}, @samp{.taz}, @samp{.tbz},
+@samp{.tb2}, @samp{.tgz}, @samp{.tlz} and @samp{.txz}.
+
 @opsummary{overwrite}
 @item --overwrite
 
@@ -3251,7 +3277,7 @@ $ @kbd{tar --show-defaults}
 
 @noindent
 Notice, that this option outputs only one line.  The example output
-above has been split to fit page boundaries.
+above has been split to fit page boundaries. @xref{defaults}.
 
 @opsummary{show-omitted-dirs}
 @item --show-omitted-dirs
@@ -3259,6 +3285,13 @@ above has been split to fit page boundaries.
 Instructs @command{tar} to mention the directories it is skipping when
 operating on a @command{tar} archive.  @xref{show-omitted-dirs}.
 
+@opsummary{show-snapshot-field-ranges}
+@item --show-snapshot-field-ranges
+
+Displays the range of values allowed by this version of @command{tar}
+for each field in the snapshot file, then exits successfully.
+@xref{Snapshot Files}.
+
 @opsummary{show-transformed-names}
 @opsummary{show-stored-names}
 @item --show-transformed-names
@@ -3939,10 +3972,10 @@ e.g.:
 @end smallexample
 
 The @samp{%s} and @samp{%u} in the above example are
-@dfn{meta-characters}.  The @samp{%s} meta-character is replaced with
+@dfn{format specifiers}.  The @samp{%s} specifier is replaced with
 the @dfn{type} of the checkpoint: @samp{write} or
 @samp{read} (or a corresponding translated version in locales other
-than @acronym{POSIX}).  The @samp{%u} meta-character is replaced with
+than @acronym{POSIX}).  The @samp{%u} specifier is replaced with
 the ordinal number of the checkpoint.  Thus, the above example could
 produce the following output when used with the @option{--create}
 option:
@@ -3953,7 +3986,54 @@ tar: Hit write checkpoint #20
 tar: Hit write checkpoint #30
 @end smallexample
 
-Aside from meta-character expansion, the message string is subject to
+The complete list of available format specifiers follows.  Some of
+them can take optional arguments.  These arguments, if given, are
+supplied in curly braces between the percent sign and the specifier
+letter.
+
+@table @samp
+@item %s
+Print type of the checkpoint (@samp{write} or @samp{read}).
+
+@item %u
+Print number of the checkpoint.
+
+@item %@{r,w,d@}T
+Print number of bytes transferred so far and approximate transfer
+speed.  Optional arguments supply prefixes to be used before number
+of bytes read, written and deleted, correspondingly.  If absent,
+they default to @samp{R}. @samp{W}, @samp{D}.  Any or all of them can
+be omitted, so, that e.g. @samp{%@{@}T} means to print corresponding
+statistics without any prefixes.  Any surplus arguments, if present,
+are silently ignored.
+
+@example
+$ @kbd{tar --delete -f f.tar --checkpoint-action=echo="#%u: %T" main.c}
+tar: #1: R: 0 (0B, 0B/s),W: 0 (0B, 0B/s),D: 0
+tar: #2: R: 10240 (10KiB, 19MiB/s),W: 0 (0B, 0B/s),D: 10240
+@end example
+
+@noindent
+See also the @samp{totals} action, described below.
+
+@item %@{@var{fmt}@}t
+Output current local time using @var{fmt} as format for @command{strftime}
+(@pxref{strftime, strftime,,strftime(3), strftime(3) man page}).  The
+@samp{@{@var{fmt}@}} part is optional.  If not present, the default
+format is @samp{%c}, i.e. the preferred date and time representation
+for the current locale.
+
+@item %@{@var{n}@}*
+Pad output with spaces to the @var{n}th column.  If the
+@samp{@{@var{n}@}} part is omitted, the current screen width
+is assumed.
+
+@item %@var{c}
+This is a shortcut for @samp{%@{%Y-%m-%d %H:%M:%S@}t: %ds, %@{read,wrote@}T%*\r},
+intended mainly for use with @samp{ttyout} action (see below).
+@end table
+
+Aside from format expansion, the message string is subject to
 @dfn{unquoting}, during which the backslash @dfn{escape sequences} are
 replaced with their corresponding @acronym{ASCII} characters
 (@pxref{escape sequences}).  E.g. the following action will produce an
@@ -3980,9 +4060,23 @@ following action will print the checkpoint message at the same screen
 line, overwriting any previous message:
 
 @smallexample
---checkpoint-action="ttyout=\rHit %s checkpoint #%u"
+--checkpoint-action="ttyout=Hit %s checkpoint #%u%*\r"
+@end smallexample
+
+@noindent
+Notice the use of @samp{%*} specifier to clear out any eventual
+remains of the prior output line.  As as more complex example,
+consider this:
+
+@smallexample
+--checkpoint-action=ttyout='%@{%Y-%m-%d %H:%M:%S@}t (%d sec): #%u, %T%*\r'
 @end smallexample
 
+@noindent
+This prints the current local time, number of seconds expired since
+tar was started, the checkpoint ordinal number, transferred bytes and
+average computed I/O speed.
+
 @cindex @code{dot}, checkpoint action
 Another available checkpoint action is @samp{dot} (or @samp{.}).  It
 instructs @command{tar} to print a single dot on the standard listing
@@ -3997,6 +4091,12 @@ For compatibility with previous @GNUTAR{} versions, this action can
 be abbreviated by placing a dot in front of the checkpoint frequency,
 as shown in the previous section.
 
+@cindex @code{totals}, checkpoint action
+The @samp{totals} action prints the total number of bytes transferred
+so far.  The format of the data is the same as for the
+@option{--totals} option (@pxref{totals}).  See also @samp{%T} format
+specifier of the @samp{echo} or @samp{ttyout} action.
+
 @cindex @code{sleep}, checkpoint action
 Yet another action, @samp{sleep}, pauses @command{tar} for a specified
 amount of seconds.  The following example will stop for 30 seconds at each
@@ -4214,6 +4314,10 @@ tar (child): trying gzip
 This means that @command{tar} first tried to decompress
 @file{archive.Z} using @command{compress}, and, when that
 failed, switched to @command{gzip}.
+@kwindex record-size
+@cindex @samp{Record size = %lu blocks}, warning message
+@item record-size
+@samp{Record size = %lu blocks}
 @end table
 
 @subheading Keywords controlling incremental extraction:
@@ -7120,45 +7224,6 @@ libc.a
 @end group
 @end smallexample
 
-@noindent
-@xopindex{directory, using in @option{--files-from} argument}
-Notice that the option parsing algorithm used with @option{-T} is
-stricter than the one used by shell.  Namely, when specifying option
-arguments, you should observe the following rules:
-
-@itemize @bullet
-@item
-When using short (single-letter) option form, its argument must
-immediately follow the option letter, without any intervening
-whitespace.  For example: @code{-Cdir}.
-
-@item
-When using long option form, the option argument must be separated
-from the option by a single equal sign.  No whitespace is allowed on
-any side of the equal sign.  For example: @code{--directory=dir}.
-
-@item
-For both short and long option forms, the option argument can be given
-on the next line after the option name, e.g.:
-
-@smallexample
-@group
---directory
-dir
-@end group
-@end smallexample
-
-@noindent
-and
-
-@smallexample
-@group
--C
-dir
-@end group
-@end smallexample
-@end itemize
-
 @opindex add-file
 If you happen to have a file whose name starts with @samp{-},
 precede it with @option{--add-file} option to prevent it from
@@ -7226,10 +7291,11 @@ $ @kbd{find . -size +800 -print0 |
 This example uses short options for typographic reasons, to avoid
 very long lines.
 
-@GNUTAR is able to automatically detect @code{NUL}-terminated file lists, so
-it is safe to use them even without the @option{--null} option.  In
-this case @command{tar} will print a warning and continue reading such
-a file as if @option{--null} were actually given:
+@GNUTAR is tries to automatically detect @code{NUL}-terminated file
+lists, so in many cases it is safe to use them even without the
+@option{--null} option.  In this case @command{tar} will print a
+warning and continue reading such a file as if @option{--null} were
+actually given:
 
 @smallexample
 @group
@@ -10737,15 +10803,16 @@ When reading an archive, @command{tar} can usually figure out the
 record size on itself.  When this is the case, and a non-standard
 record size was used when the archive was created, @command{tar} will
 print a message about a non-standard blocking factor, and then operate
-normally.  On some tape devices, however, @command{tar} cannot figure
-out the record size itself.  On most of those, you can specify a
-blocking factor (with @option{--blocking-factor}) larger than the
-actual blocking factor, and then use the @option{--read-full-records}
-(@option{-B}) option.  (If you specify a blocking factor with
-@option{--blocking-factor} and don't use the
-@option{--read-full-records} option, then @command{tar} will not
-attempt to figure out the recording size itself.)  On some devices,
-you must always specify the record size exactly with
+normally@footnote{If this message is not needed, you can turn it off
+using the @option{--warning=no-record-size} option.}.  On some tape
+devices, however, @command{tar} cannot figure out the record size
+itself.  On most of those, you can specify a blocking factor (with
+@option{--blocking-factor}) larger than the actual blocking factor,
+and then use the @option{--read-full-records} (@option{-B}) option.
+(If you specify a blocking factor with @option{--blocking-factor} and
+don't use the @option{--read-full-records} option, then @command{tar}
+will not attempt to figure out the recording size itself.)  On some
+devices, you must always specify the record size exactly with
 @option{--blocking-factor} when reading, because @command{tar} cannot
 figure it out.  In any case, use @option{--list} (@option{-t}) before
 doing any extractions to see whether @command{tar} is reading the archive