* Error (?) in man page for ppoll(2) @ 2019-07-21 15:32 Alan Stern 2019-07-29 12:07 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 4+ messages in thread From: Alan Stern @ 2019-07-21 15:32 UTC (permalink / raw) To: mtk.manpages, linux-man, Kernel development list Here are two extracts from the man page for ppoll(2) (from the man-pages 4.16 package; the 5.01 version is the same): 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. Alan Stern ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Error (?) in man page for ppoll(2) 2019-07-21 15:32 Error (?) in man page for ppoll(2) Alan Stern @ 2019-07-29 12:07 ` Michael Kerrisk (man-pages) 2019-07-29 13:23 ` Alan Stern 0 siblings, 1 reply; 4+ messages in thread From: Michael Kerrisk (man-pages) @ 2019-07-29 12:07 UTC (permalink / raw) To: Alan Stern, linux-man, Kernel development list; +Cc: mtk.manpages Hello Alan, On 7/21/19 5:32 PM, Alan Stern wrote: > Here are two extracts from the man page for ppoll(2) (from the > man-pages 4.16 package; the 5.01 version is the same): > > 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. Thanks for the report, and the text change suggestions. I've applied the patch below. Thanks, Michael diff --git a/man2/poll.2 b/man2/poll.2 index 0b023e0a5..3eacb88b7 100644 --- 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 (nragtive). +.TP .B ENOMEM There was no space to allocate file descriptor tables. .SH VERSIONS -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply related [flat|nested] 4+ messages in thread
* Re: Error (?) in man page for ppoll(2) 2019-07-29 12:07 ` Michael Kerrisk (man-pages) @ 2019-07-29 13:23 ` Alan Stern 2019-07-29 18:56 ` Michael Kerrisk (man-pages) 0 siblings, 1 reply; 4+ messages in thread From: Alan Stern @ 2019-07-29 13:23 UTC (permalink / raw) To: Michael Kerrisk (man-pages); +Cc: linux-man, Kernel development list On Mon, 29 Jul 2019, Michael Kerrisk (man-pages) wrote: > Hello Alan, > > On 7/21/19 5:32 PM, Alan Stern wrote: > > Here are two extracts from the man page for ppoll(2) (from the > > man-pages 4.16 package; the 5.01 version is the same): > > > > 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. > > Thanks for the report, and the text change suggestions. > I've applied the patch below. > > Thanks, > > Michael > > diff --git a/man2/poll.2 b/man2/poll.2 > index 0b023e0a5..3eacb88b7 100644 > --- 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 (nragtive). ----------------^^^ Typo. Otherwise, I approve of the patch. Thank you, Alan > +.TP > .B ENOMEM > There was no space to allocate file descriptor tables. > .SH VERSIONS ^ permalink raw reply [flat|nested] 4+ messages in thread
* Re: Error (?) in man page for ppoll(2) 2019-07-29 13:23 ` Alan Stern @ 2019-07-29 18:56 ` Michael Kerrisk (man-pages) 0 siblings, 0 replies; 4+ messages in thread From: Michael Kerrisk (man-pages) @ 2019-07-29 18:56 UTC (permalink / raw) To: Alan Stern; +Cc: mtk.manpages, linux-man, Kernel development list >> +The timeout value expressed in >> +.IR *ip >> +is invalid (nragtive). > ----------------^^^ > > Typo. Otherwise, I approve of the patch. Thanks! Fixed. Cheers, Michael -- Michael Kerrisk Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/ Linux/UNIX System Programming Training: http://man7.org/training/ ^ permalink raw reply [flat|nested] 4+ messages in thread
end of thread, other threads:[~2019-07-29 18:56 UTC | newest] Thread overview: 4+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2019-07-21 15:32 Error (?) in man page for ppoll(2) Alan Stern 2019-07-29 12:07 ` Michael Kerrisk (man-pages) 2019-07-29 13:23 ` Alan Stern 2019-07-29 18:56 ` Michael Kerrisk (man-pages)
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).