X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Ftar;a=blobdiff_plain;f=doc%2Ftar.texi;h=6323d2181f3c981fe9d44b611c193e9f98ca3fd0;hp=9fde5a0761f41b7b6aff3e76bb840a8926e8fdaa;hb=45ccda119355a1087450039a250359c1d0de0d08;hpb=2c06a80918019471876956eef4ef22f05c9e0571 diff --git a/doc/tar.texi b/doc/tar.texi index 9fde5a0..6323d21 100644 --- a/doc/tar.texi +++ b/doc/tar.texi @@ -3086,6 +3086,19 @@ 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[=@var{dir}] +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. In the absence of @var{dir} argument, the name of the new directory +will be equal to the base name of the archive (file name minus the +archive suffix, if recognized). Any member names that do not begin +with that directory name (after +transformations from @option{--transform} and +@option{--strip-components}) will be prefixed with it. Recognized +file name suffixes are @samp{.tar}, and any compression suffixes +recognizable by @xref{--auto-compress}. + @opsummary{overwrite} @item --overwrite @@ -3614,7 +3627,7 @@ successfully. For example, @w{@samp{tar --version}} might print: @smallexample tar (GNU tar) @value{VERSION} -Copyright (C) 2013 Free Software Foundation, Inc. +Copyright (C) 2013-2014 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. @@ -3961,10 +3974,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: @@ -3975,7 +3988,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 @@ -4002,9 +4062,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 @@ -4019,6 +4093,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