diff options
Diffstat (limited to 'man2/poll.2')
| -rw-r--r-- | man2/poll.2 | 74 |
1 files changed, 37 insertions, 37 deletions
diff --git a/man2/poll.2 b/man2/poll.2 index 2b024d3..36e89f8 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -7,7 +7,7 @@ .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and .\" formatting changes. .\" -.TH poll 2 2023-07-08 "Linux man-pages 6.05.01" +.TH poll 2 2023-10-31 "Linux man-pages 6.7" .SH NAME poll, ppoll \- wait for some event on a file descriptor .SH LIBRARY @@ -16,12 +16,12 @@ Standard C library .SH SYNOPSIS .nf .B #include <poll.h> -.PP +.P .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout ); -.PP +.P .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" .B #include <poll.h> -.PP +.P .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds , .BI " const struct timespec *_Nullable " tmo_p , .BI " const sigset_t *_Nullable " sigmask ); @@ -36,11 +36,11 @@ The Linux-specific .BR epoll (7) API performs a similar task, but offers features beyond those found in .BR poll (). -.PP +.P The set of file descriptors to be monitored is specified in the .I fds argument, which is an array of structures of the following form: -.PP +.P .in +4n .EX struct pollfd { @@ -50,12 +50,12 @@ struct pollfd { }; .EE .in -.PP +.P The caller should specify the number of items in the .I fds array in .IR nfds . -.PP +.P The field .I fd contains a file descriptor for an open file. @@ -70,7 +70,7 @@ file descriptor for a single call: simply set the .I fd field to its bitwise complement.) -.PP +.P The field .I events is an input parameter, a bit mask specifying the events the application @@ -85,7 +85,7 @@ are and .B POLLNVAL (see below). -.PP +.P The field .I revents is an output parameter, filled by the kernel with the events that @@ -104,12 +104,12 @@ or field, and will be set in the .I revents field whenever the corresponding condition is true.) -.PP +.P If none of the events requested (and no error) has occurred for any of the file descriptors, then .BR poll () blocks until one of the events occurs. -.PP +.P The .I timeout argument specifies the number of milliseconds that @@ -122,7 +122,7 @@ a file descriptor becomes ready; the call is interrupted by a signal handler; or .IP \[bu] the timeout expires. -.PP +.P Being "ready" means that the requested operation will not block; thus, .BR poll ()ing regular files, @@ -130,7 +130,7 @@ block devices, and other files with no reasonable polling semantic .I always returns instantly as ready to read and write. -.PP +.P Note that the .I timeout interval will be rounded up to the system clock granularity, @@ -144,7 +144,7 @@ Specifying a of zero causes .BR poll () to return immediately, even if no file descriptors are ready. -.PP +.P The bits that may be set/returned in .I events and @@ -214,7 +214,7 @@ not open (only returned in .IR revents ; ignored in .IR events ). -.PP +.P When compiling with .B _XOPEN_SOURCE defined, one also has the following, @@ -234,7 +234,7 @@ Equivalent to .TP .B POLLWRBAND Priority data may be written. -.PP +.P Linux also knows about, but does not use .BR POLLMSG . .SS ppoll() @@ -251,23 +251,23 @@ like .BR ppoll () allows an application to safely wait until either a file descriptor becomes ready or until a signal is caught. -.PP +.P Other than the difference in the precision of the .I timeout argument, the following .BR ppoll () call: -.PP +.P .in +4n .EX ready = ppoll(&fds, nfds, tmo_p, &sigmask); .EE .in -.PP +.P is nearly equivalent to .I atomically executing the following calls: -.PP +.P .in +4n .EX sigset_t origmask; @@ -280,7 +280,7 @@ ready = poll(&fds, nfds, timeout); pthread_sigmask(SIG_SETMASK, &origmask, NULL); .EE .in -.PP +.P The above code segment is described as .I nearly equivalent because whereas a negative @@ -291,13 +291,13 @@ is interpreted as an infinite timeout, a negative value expressed in .I *tmo_p results in an error from .BR ppoll (). -.PP +.P See the description of .BR pselect (2) for an explanation of why .BR ppoll () is necessary. -.PP +.P If the .I sigmask argument is specified as NULL, then @@ -309,7 +309,7 @@ differs from only in the precision of the .I timeout argument). -.PP +.P The .I tmo_p argument specifies an upper limit on the amount of time that @@ -318,7 +318,7 @@ will block. This argument is a pointer to a .BR timespec (3) structure. -.PP +.P If .I tmo_p is specified as NULL, then @@ -334,7 +334,7 @@ whose fields have been set to a nonzero value (indicating an event or an error). A return value of zero indicates that the system call timed out before any file descriptors became ready. -.PP +.P On error, \-1 is returned, and .I errno is set to indicate the error. @@ -379,7 +379,7 @@ Portable programs may wish to check for .B EAGAIN and loop, just as with .BR EINTR . -.PP +.P Some implementations define the nonstandard constant .B INFTIM with the value \-1 for use as a @@ -401,7 +401,7 @@ Thus, the glibc function does not modify its .I tmo_p argument. -.PP +.P The raw .BR ppoll () system call has a fifth argument, @@ -452,7 +452,7 @@ and is not affected by the .B O_NONBLOCK flag. -.PP +.P For a discussion of what may happen if a file descriptor being monitored by .BR poll () is closed in another thread, see @@ -482,27 +482,27 @@ if the file descriptor was not readable, but some other event occurred (presumably .BR POLLHUP ), closes the file descriptor. -.PP +.P Suppose we run the program in one terminal, asking it to open a FIFO: -.PP +.P .in +4n .EX $ \fBmkfifo myfifo\fP $ \fB./poll_input myfifo\fP .EE .in -.PP +.P In a second terminal window, we then open the FIFO for writing, write some data to it, and close the FIFO: -.PP +.P .in +4n .EX $ \fBecho aaaaabbbbbccccc > myfifo\fP .EE .in -.PP +.P In the terminal where we are running the program, we would then see: -.PP +.P .in +4n .EX Opened "myfifo" on fd 3 @@ -522,7 +522,7 @@ Ready: 1 All file descriptors closed; bye .EE .in -.PP +.P In the above output, we see that .BR poll () returned three times: |