poll.2: Note that poll() equivalent code for ppoll() is not quite equivalent

As reported by Alan Stern:

Here are two extracts from the man page for ppoll(2):

     Specifying a negative value in timeout means an infinite
     timeout.

     Other than the difference in the precision of the timeout
     argument, the following ppoll() call:

       ready = ppoll(&fds, nfds, tmo_p, &sigmask);

     is equivalent to atomically executing the following calls:

       sigset_t origmask;
       int timeout;

       timeout = (tmo_p == NULL) ? -1 :
                 (tmo_p->tv_sec * 1000 + tmo_p->tv_nsec / 1000000);
       pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
       ready = poll(&fds, nfds, timeout);
       pthread_sigmask(SIG_SETMASK, &origmask, NULL);

But if tmo_p->tv_sec is negative, the ppoll() call is not
equivalent to the corresponding poll() call.  The kernel rejects
negative values of tv_sec with an EINVAL error; it does not
interpret the value as meaning an infinite timeout.

(Yes, the kernel interprets tmo_p == NULL as an infinite timeout,
but the man page is still wrong for the case tmo_p->tv_sec < 0.)

Suggested fix: Following the end of the second extract above, add:

    except that negative time values in tmo_p are not
    interpreted as an infinite timeout.

Also, in the ERRORS section, change the text for EINVAL to:

    EINVAL The nfds value exceeds the RLIMIT_NOFILE value or
    *tmo_p contains an invalid (negative) time value.

Reported-by: Alan Stern <stern@rowland.harvard.edu>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

diff --git a/man2/poll.2 b/man2/poll.2
index 0b023e0a5f8938ac17941647a2392f4a5efb0438..2799f56ac77b5204ba1430e626d6d275e30aa15d 100644 (file)
--- a/man2/poll.2
+++ b/man2/poll.2
@@ -271,7 +271,7 @@ ready = ppoll(&fds, nfds, tmo_p, &sigmask);
 .EE
 .in
 .PP
-is equivalent to
+is nearly equivalent to
 .I atomically
 executing the following calls:
 .PP
@@ -288,6 +288,17 @@ pthread_sigmask(SIG_SETMASK, &origmask, NULL);
 .EE
 .in
 .PP
+The above code segment is described as
+.I nearly
+equivalent because whereas a negative
+.I timeout
+value for
+.BR poll ()
+is interpreted as an infinite timeout, a negative value expressed in
+.IR *tmo_p
+results in an error from
+.BR ppoll ().
+.PP
 See the description of
 .BR pselect (2)
 for an explanation of why
@@ -354,6 +365,12 @@ value exceeds the
 .B RLIMIT_NOFILE
 value.
 .TP
+.B EINVAL
+.RB ( ppoll ())
+The timeout value expressed in
+.IR *ip
+is invalid (negative).
+.TP
 .B ENOMEM
 There was no space to allocate file descriptor tables.
 .SH VERSIONS