diff options
Diffstat (limited to 'doc/coreutils.texi')
-rw-r--r-- | doc/coreutils.texi | 152 |
1 files changed, 76 insertions, 76 deletions
diff --git a/doc/coreutils.texi b/doc/coreutils.texi index 9a27cb109..a13c6e7be 100644 --- a/doc/coreutils.texi +++ b/doc/coreutils.texi @@ -2777,22 +2777,22 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -c @var{k} -@itemx --bytes=@var{k} +@item -c [-]@var{num} +@itemx --bytes=[-]@var{num} @opindex -c @opindex --bytes -Print the first @var{k} bytes, instead of initial lines. -However, if @var{k} starts with a @samp{-}, -print all but the last @var{k} bytes of each file. -@multiplierSuffixes{k} +Print the first @var{num} bytes, instead of initial lines. +However, if @var{num} is prefixed with a @samp{-}, +print all but the last @var{num} bytes of each file. +@multiplierSuffixes{num} -@item -n @var{k} -@itemx --lines=@var{k} +@item -n [-]@var{num} +@itemx --lines=[-]@var{num} @opindex -n @opindex --lines -Output the first @var{k} lines. -However, if @var{k} starts with a @samp{-}, -print all but the last @var{k} lines of each file. +Output the first @var{num} lines. +However, if @var{num} is prefixed with a @samp{-}, +print all but the last @var{num} lines of each file. Size multiplier suffixes are the same as with the @option{-c} option. @item -q @@ -2812,12 +2812,12 @@ Always print file name headers. @end table For compatibility @command{head} also supports an obsolete option syntax -@option{-@var{count}@var{options}}, which is recognized only if it is -specified first. @var{count} is a decimal number optionally followed +@option{-[@var{num}][bkm][cqv]}, which is recognized only if it is +specified first. @var{num} is a decimal number optionally followed by a size letter (@samp{b}, @samp{k}, @samp{m}) as in @option{-c}, or @samp{l} to mean count by lines, or other option letters (@samp{cqv}). -Scripts intended for standard hosts should use @option{-c @var{count}} -or @option{-n @var{count}} instead. If your script must also run on +Scripts intended for standard hosts should use @option{-c @var{num}} +or @option{-n @var{num}} instead. If your script must also run on hosts that support only the obsolete syntax, it is usually simpler to avoid @command{head}, e.g., by using @samp{sed 5q} instead of @samp{head -5}. @@ -2870,14 +2870,14 @@ The program accepts the following options. Also see @ref{Common options}. @table @samp -@item -c @var{k} -@itemx --bytes=@var{k} +@item -c [+]@var{num} +@itemx --bytes=[+]@var{num} @opindex -c @opindex --bytes -Output the last @var{k} bytes, instead of final lines. -However, if @var{k} starts with a @samp{+}, start printing with the -@var{k}th byte from the start of each file, instead of from the end. -@multiplierSuffixes{k} +Output the last @var{num} bytes, instead of final lines. +However, if @var{num} is prefixed with a @samp{+}, start printing with +byte @var{num} from the start of each file, instead of from the end. +@multiplierSuffixes{num} @item -f @itemx --follow[=@var{how}] @@ -2944,36 +2944,27 @@ This option is the same as @option{--follow=name --retry}. That is, tail will attempt to reopen a file when it is removed. Should this fail, tail will keep trying until it becomes accessible again. -@item --retry -@opindex --retry -Indefinitely try to open the specified file. -This option is useful mainly when following (and otherwise issues a warning). - -When following by file descriptor (i.e., with @option{--follow=descriptor}), -this option only affects the initial open of the file, as after a successful -open, @command{tail} will start following the file descriptor. - -When following by name (i.e., with @option{--follow=name}), @command{tail} -infinitely retries to re-open the given files until killed. - -Without this option, when @command{tail} encounters a file that doesn't -exist or is otherwise inaccessible, it reports that fact and -never checks it again. +@item --max-unchanged-stats=@var{n} +@opindex --max-unchanged-stats +When tailing a file by name, if there have been @var{n} (default +n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive +iterations for which the file has not changed, then +@code{open}/@code{fstat} the file to determine if that file name is +still associated with the same device/inode-number pair as before. +When following a log file that is rotated, this is approximately the +number of seconds between when tail prints the last pre-rotation lines +and when it prints the lines that have accumulated in the new log file. +This option is meaningful only when polling (i.e., without inotify) +and when following by name. -@item -s @var{number} -@itemx --sleep-interval=@var{number} -@opindex -s -@opindex --sleep-interval -Change the number of seconds to wait between iterations (the default is 1.0). -During one iteration, every specified file is checked to see if it has -changed size. -Historical implementations of @command{tail} have required that -@var{number} be an integer. However, GNU @command{tail} accepts -an arbitrary floating point number. @xref{Floating point}. -When @command{tail} uses inotify, this polling-related option -is usually ignored. However, if you also specify @option{--pid=@var{p}}, -@command{tail} checks whether process @var{p} is alive at least -every @var{number} seconds. +@item -n [+]@var{num} +@itemx --lines=[+]@var{} +@opindex -n +@opindex --lines +Output the last @var{num} lines. +However, if @var{num} is prefixed with a @samp{+}, start printing with +line @var{num} from the start of each file, instead of from the end. +Size multiplier suffixes are the same as with the @option{-c} option. @item --pid=@var{pid} @opindex --pid @@ -2998,28 +2989,6 @@ terminate until long after the real writer has terminated. Note that @option{--pid} cannot be supported on some systems; @command{tail} will print a warning if this is the case. -@item --max-unchanged-stats=@var{n} -@opindex --max-unchanged-stats -When tailing a file by name, if there have been @var{n} (default -n=@value{DEFAULT_MAX_N_UNCHANGED_STATS_BETWEEN_OPENS}) consecutive -iterations for which the file has not changed, then -@code{open}/@code{fstat} the file to determine if that file name is -still associated with the same device/inode-number pair as before. -When following a log file that is rotated, this is approximately the -number of seconds between when tail prints the last pre-rotation lines -and when it prints the lines that have accumulated in the new log file. -This option is meaningful only when polling (i.e., without inotify) -and when following by name. - -@item -n @var{k} -@itemx --lines=@var{k} -@opindex -n -@opindex --lines -Output the last @var{k} lines. -However, if @var{k} starts with a @samp{+}, start printing with the -@var{k}th line from the start of each file, instead of from the end. -Size multiplier suffixes are the same as with the @option{-c} option. - @item -q @itemx --quiet @itemx --silent @@ -3028,6 +2997,37 @@ Size multiplier suffixes are the same as with the @option{-c} option. @opindex --silent Never print file name headers. +@item --retry +@opindex --retry +Indefinitely try to open the specified file. +This option is useful mainly when following (and otherwise issues a warning). + +When following by file descriptor (i.e., with @option{--follow=descriptor}), +this option only affects the initial open of the file, as after a successful +open, @command{tail} will start following the file descriptor. + +When following by name (i.e., with @option{--follow=name}), @command{tail} +infinitely retries to re-open the given files until killed. + +Without this option, when @command{tail} encounters a file that doesn't +exist or is otherwise inaccessible, it reports that fact and +never checks it again. + +@item -s @var{number} +@itemx --sleep-interval=@var{number} +@opindex -s +@opindex --sleep-interval +Change the number of seconds to wait between iterations (the default is 1.0). +During one iteration, every specified file is checked to see if it has +changed size. +Historical implementations of @command{tail} have required that +@var{number} be an integer. However, GNU @command{tail} accepts +an arbitrary floating point number. @xref{Floating point}. +When @command{tail} uses inotify, this polling-related option +is usually ignored. However, if you also specify @option{--pid=@var{p}}, +@command{tail} checks whether process @var{p} is alive at least +every @var{number} seconds. + @item -v @itemx --verbose @opindex -v @@ -3037,10 +3037,10 @@ Always print file name headers. @end table For compatibility @command{tail} also supports an obsolete usage -@samp{tail -[@var{count}][bcl][f] [@var{file}]}, which is recognized +@samp{tail -[@var{num}][bcl][f] [@var{file}]}, which is recognized only if it does not conflict with the usage described above. This obsolete form uses exactly one option and at most one -file. In the option, @var{count} is an optional decimal number optionally +file. In the option, @var{num} is an optional decimal number optionally followed by a size letter (@samp{b}, @samp{c}, @samp{l}) to mean count by 512-byte blocks, bytes, or lines, optionally followed by @samp{f} which has the same meaning as @option{-f}. @@ -3054,8 +3054,8 @@ This obsolete behavior can be enabled or disabled with the conformance}). Scripts intended for use on standard hosts should avoid obsolete -syntax and should use @option{-c @var{count}[b]}, @option{-n -@var{count}}, and/or @option{-f} instead. If your script must also +syntax and should use @option{-c @var{num}[b]}, @option{-n +@var{num}}, and/or @option{-f} instead. If your script must also run on hosts that support only the obsolete syntax, you can often rewrite it to avoid problematic usages, e.g., by using @samp{sed -n '$p'} rather than @samp{tail -1}. If that's not possible, the script |