[PATCH] doc: tail/inotify does use --sleep-interval=S, with --pid=P

[Jim Meyering]

In fixing the recent tail --follow=name bug, I noticed that
--sleep-interval=S *is* used in inotify mode, so adjusted the
documentation:

>From 249d9a3ca429e508958e87c636c1b6a4a8d75f12 Mon Sep 17 00:00:00 2001
From: Jim Meyering <address@hidden>
Date: Sat, 23 Apr 2011 16:08:08 +0200
Subject: [PATCH] doc: tail/inotify does use --sleep-interval=S, with --pid=P

* doc/coreutils.texi (tail invocation): Mention it.
* src/tail.c (usage): Likewise.
(tail_forever_inotify): Clarify comment.
---
 doc/coreutils.texi |    5 ++++-
 src/tail.c         |   10 ++++++----
 2 files changed, 10 insertions(+), 5 deletions(-)

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index b7ccf38..d2377f4 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -2852,7 +2852,10 @@ tail invocation
 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 ignored.
+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.

 @itemx --pid=@var{pid}
 @opindex --pid
diff --git a/src/tail.c b/src/tail.c
index bcd2d99..88fbd10 100644
--- a/src/tail.c
+++ b/src/tail.c
@@ -302,7 +302,8 @@ Mandatory arguments to long options are mandatory for short 
options too.\n\
      fputs (_("\
   -s, --sleep-interval=N   with -f, sleep for approximately N seconds\n\
                              (default 1.0) between iterations.\n\
-                             With inotify, this option is rarely useful.\n\
+                             With inotify and --pid=P, check process P at\n\
+                             least once every N seconds.\n\
   -v, --verbose            always output headers giving file names\n\
 "), stdout);
      fputs (HELP_OPTION_DESCRIPTION, stdout);
@@ -1422,9 +1423,10 @@ tail_forever_inotify (int wd, struct File_spec *f, 
size_t n_files,
   evlen += sizeof (struct inotify_event) + 1;
   evbuf = xmalloc (evlen);

-  /* Wait for inotify events and handle them.  Events on directories make sure
-     that watched files can be re-added when -F is used.
-     This loop sleeps on the `safe_read' call until a new event is notified.  
*/
+  /* Wait for inotify events and handle them.  Events on directories
+     ensure that watched files can be re-added when following by name.
+     This loop blocks on the `safe_read' call until a new event is notified.
+     But when --pid=P is specified, tail usually waits via the select.  */
   while (1)
     {
       struct File_spec *fspec;
--
1.7.5.rc3.316.gd1ff9