Document new tail options.

1 files changed, 42 insertions, 8 deletions

diff --git a/doc/textutils.texi b/doc/textutils.texi
index 5e39281a6..765b652ae 100644
--- a/doc/textutils.texi
+++ b/doc/textutils.texi
@@ -1483,13 +1483,13 @@ gets output from a different file, to indicate which file that output is
 from.
 
 There are two ways to specify how you'd like to track files with this option,
-but that difference is noticeable only when a followed file is removed.
+but that difference is noticeable only when a followed file is removed or
+renamed.
 If you'd like to continue to track the end of a growing file even after
 it has been unlinked, use @samp{--follow=descriptor}.  This is the default
 behavior, but it is not useful if you're tracking a log file that may be
-rotated (removed and reopened).  In that case, use @samp{--follow=name} to
-track the named file by reopening it periodically
-@c FIXME: cross reference to the new option name
+rotated (removed or renamed, then reopened).  In that case, use
+@samp{--follow=name} to track the named file by reopening it periodically
 to see if it has been removed and recreated by some other program.
 
 No matter which method you use, if the tracked file is determined to have
@@ -1499,16 +1499,50 @@ and resumes tracking the end of the file from the newly-determined endpoint.
 When a file is removed, @code{tail}'s behavior depends on whether it is
 following the name or the descriptor.  When following by name, tail can
 detect that a file has been removed and gives a message to that effect,
-and if @samp{--allow-missing} has been specified it will continue checking
+and if @samp{--retry} has been specified it will continue checking
 periodically to see if the file reappears.
 When following a descriptor, tail does not detect that the file has
-been unlinked and issues no message.
+been unlinked or renamed and issues no message;  even though the file
+may no longer be accessible via its original name, it may still be
+growing.
 
 The option values @samp{descriptor} and @samp{name} may be specified only
 with the long form of the option, not with @samp{-f}.
 
-@c FIXME-describe --allow-missing  [useful only with --follow]
-@c FIXME-describe --sleep-interval [useful only with --follow]
+@itemx --retry
+@opindex --retry
+This option is meaningful only when following by name.
+Without this option, when tail encounters a file that doesn't
+exist or is otherwise inaccessible, it reports that fact and
+never checks it again.
+
+@itemx --sleep-interval=@var{n}
+@opindex --sleep-interval
+Change the number of seconds to wait between iterations (the default is 1).
+During one iteration, every specified file is checked to see if it has
+changed size.
+
+@itemx --max-consecutive-size-changes=@var{n}
+@opindex --max-consecutive-size-changes
+This option is meaningful only when following by name.
+Use it to control how long @code{tail} follows the descriptor of a file
+that continues growing at a rapid pace even after it is deleted or renamed.
+After detecting @var{n} consecutive size changes for a file,
+@code{open}/@code{fstat} the file to determine if that file name is
+still associated with the same device/inode-number pair as before.
+See the output of @code{tail --help} for the default value.
+
+@itemx --max-unchanged-stats=@var{n}
+@opindex --max-unchanged-stats
+When tailing a file by name, if there have been this many consecutive
+iterations for which the size has remained the same, 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.
+See the output of @code{tail --help} for the default value.
+This option is meaningful only when following by name.
 
 @itemx -n @var{n}
 @itemx --lines=@var{n}