Bug 61911 - incorrect sentence in the description of struct pollfd's events field
Summary: incorrect sentence in the description of struct pollfd's events field
Status: RESOLVED CODE_FIX
Alias: None
Product: Documentation
Classification: Unclassified
Component: man-pages (show other bugs)
Hardware: All Linux
: P1 normal
Assignee: documentation_man-pages@kernel-bugs.osdl.org
URL:
Keywords:
Depends on:
Blocks:
 
Reported: 2013-09-23 11:45 UTC by Paolo Bonzini
Modified: 2013-11-07 18:19 UTC (History)
1 user (show)

See Also:
Kernel Version:
Subsystem:
Regression: No
Bisected commit-id:


Attachments

Description Paolo Bonzini 2013-09-23 11:45:00 UTC
The manual page says:

The field events is an input parameter, a bit mask specifying the events the application is interested  in  for  the  file descriptor fd.  If this field is specified as zero, then all events are ignored for fd and revents returns zero.


However, this is not what happens.  POLLHUP and POLLERR are always reported (as one would expect, actually).

Test case 1:

#include <poll.h>
int main(void)
{
	struct pollfd pfd = { .fd = 0 };
	sleep(1);
	poll(&pfd, 1, 0);
}

$ echo x > fifo & strace -e poll ./a.out < fifo
poll([{fd=0, events=0}], 1, 0) = 1 ([{fd=0, revents=POLLHUP}])


Test case 2:

#include <poll.h>
int main(void)
{
	struct pollfd pfd = { .fd = 1 };
	sleep(1);
	poll(&pfd, 1, 0);
}


$ :< fifo & strace -e poll ./a.out > fifo
poll([{fd=1, events=0}], 1, 0) = 1 ([{fd=1, revents=POLLERR}])
Comment 1 Michael Kerrisk 2013-11-07 18:19:24 UTC
Thanks, Paolo. I'm not sure what I was thinking of when I wrote that text. I applied the patch below.

diff --git a/man2/poll.2 b/man2/poll.2
index b0159d2..0a70065 100644
--- a/man2/poll.2
+++ b/man2/poll.2
@@ -89,12 +89,15 @@ The field
 is an input parameter, a bit mask specifying the events the application
 is interested in for the file descriptor
 .IR fd .
-If this field is specified as zero,
-then all events are ignored for
-.IR fd
-and
+This field may be specified as zero,
+in which case the only events that can be returned in
 .I revents
-returns zero.
+are
+.BR POLLHUP ,
+.BR POLLERR ,
+and
+.B POLLNVAL
+(see below).
 
 The field
 .I revents

Note You need to log in before you can comment on or make changes to this bug.