1 .\" Copyright (C) 2006, 2019 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\" Additions from Richard Gooch <rgooch@atnf.CSIRO.AU> and aeb, 971207
6 .\" 2006-03-13, mtk, Added ppoll() + various other rewordings
7 .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and
8 .\" formatting changes.
10 .TH POLL 2 2021-03-22 "Linux man-pages (unreleased)"
12 poll, ppoll \- wait for some event on a file descriptor
15 .RI ( libc ", " \-lc )
20 .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
22 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
25 .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ,
26 .BI " const struct timespec *" tmo_p ", const sigset_t *" sigmask );
30 performs a similar task to
32 it waits for one of a set of file descriptors to become ready
36 API performs a similar task, but offers features beyond those found in
39 The set of file descriptors to be monitored is specified in the
41 argument, which is an array of structures of the following form:
46 int fd; /* file descriptor */
47 short events; /* requested events */
48 short revents; /* returned events */
53 The caller should specify the number of items in the
60 contains a file descriptor for an open file.
61 If this field is negative, then the corresponding
63 field is ignored and the
66 (This provides an easy way of ignoring a
67 file descriptor for a single
71 field to its bitwise complement.)
75 is an input parameter, a bit mask specifying the events the application
76 is interested in for the file descriptor
78 This field may be specified as zero,
79 in which case the only events that can be returned in
90 is an output parameter, filled by the kernel with the events that
94 can include any of those specified in
101 (These three bits are meaningless in the
103 field, and will be set in the
105 field whenever the corresponding condition is true.)
107 If none of the events requested (and no error) has occurred for any
108 of the file descriptors, then
110 blocks until one of the events occurs.
114 argument specifies the number of milliseconds that
116 should block waiting for a file descriptor to become ready.
117 The call will block until either:
119 a file descriptor becomes ready;
121 the call is interrupted by a signal handler; or
127 interval will be rounded up to the system clock granularity,
128 and kernel scheduling delays mean that the blocking interval
129 may overrun by a small amount.
130 Specifying a negative value in
132 means an infinite timeout.
137 to return immediately, even if no file descriptors are ready.
139 The bits that may be set/returned in
143 are defined in \fI<poll.h>\fP:
146 There is data to read.
149 There is some exceptional condition on the file descriptor.
150 Possibilities include:
153 There is out-of-band data on a TCP socket (see
156 A pseudoterminal master in packet mode has seen a state change on the slave
162 file has been modified (see
167 Writing is now possible, though a write larger than the available space
168 in a socket or pipe will still block (unless
172 .BR POLLRDHUP " (since Linux 2.6.17)"
173 Stream socket peer closed connection,
174 or shut down writing half of connection.
177 feature test macro must be defined
181 in order to obtain this definition.
184 Error condition (only returned in
188 This bit is also set for a file descriptor referring
189 to the write end of a pipe when the read end has been closed.
192 Hang up (only returned in
196 Note that when reading from a channel such as a pipe or a stream socket,
197 this event merely indicates that the peer closed its end of the channel.
198 Subsequent reads from the channel will return 0 (end of file)
199 only after all outstanding data in the channel has been consumed.
204 not open (only returned in
211 defined, one also has the following,
212 which convey no further information beyond the bits listed above:
219 Priority band data can be read (generally unused on Linux).
220 .\" POLLRDBAND is used in the DECnet protocol.
227 Priority data may be written.
229 Linux also knows about, but does not use
232 The relationship between
236 is analogous to the relationship between
243 allows an application to safely wait until either a file descriptor
244 becomes ready or until a signal is caught.
246 Other than the difference in the precision of the
248 argument, the following
254 ready = ppoll(&fds, nfds, tmo_p, &sigmask);
258 is nearly equivalent to
260 executing the following calls:
267 timeout = (tmo_p == NULL) ? \-1 :
268 (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000);
269 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
270 ready = poll(&fds, nfds, timeout);
271 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
275 The above code segment is described as
277 equivalent because whereas a negative
281 is interpreted as an infinite timeout, a negative value expressed in
283 results in an error from
286 See the description of
288 for an explanation of why
294 argument is specified as NULL, then
295 no signal mask manipulation is performed
300 only in the precision of the
306 argument specifies an upper limit on the amount of time that
309 This argument is a pointer to a
315 is specified as NULL, then
317 can block indefinitely.
321 returns a nonnegative value which is the number of elements in the
325 fields have been set to a nonzero value (indicating an event or an error).
326 A return value of zero indicates that the system call timed out
327 before any file descriptors became ready.
329 On error, \-1 is returned, and
331 is set to indicate the error.
336 points outside the process's accessible address space.
337 The array given as argument was not contained in the calling program's
341 A signal occurred before any requested event; see
353 The timeout value expressed in
355 is invalid (negative).
358 Unable to allocate memory for kernel data structures.
362 system call was introduced in Linux 2.1.23.
363 On older kernels that lack this system call,
366 wrapper function provides emulation using
371 system call was added to Linux in kernel 2.6.16.
374 library call was added in glibc 2.4.
377 conforms to POSIX.1-2001 and POSIX.1-2008.
381 .\" ppoll() is proposed for inclusion in POSIX:
382 .\" https://www.austingroupbugs.net/view.php?id=1263
383 .\" NetBSD 3.0 has a pollts() which is like Linux ppoll().
389 is not affected by the
393 On some other UNIX systems,
394 .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett
396 can fail with the error
398 if the system fails to allocate kernel-internal resources, rather than
401 POSIX permits this behavior.
402 Portable programs may wish to check for
404 and loop, just as with
407 Some implementations define the nonstandard constant
409 with the value \-1 for use as a
413 This constant is not provided in glibc.
415 For a discussion of what may happen if a file descriptor being monitored by
417 is closed in another thread, see
419 .SS C library/kernel differences
422 system call modifies its
425 However, the glibc wrapper function hides this behavior
426 by using a local variable for the timeout argument that
427 is passed to the system call.
430 function does not modify its
436 system call has a fifth argument,
437 .IR "size_t sigsetsize" ,
438 which specifies the size in bytes of the
443 wrapper function specifies this argument as a fixed value
445 .IR sizeof(kernel_sigset_t) ).
448 for a discussion on the differences between the kernel and the libc
449 notion of the sigset.
451 See the discussion of spurious readiness notifications under the
455 The program below opens each of the files named in its command-line
456 arguments and monitors the resulting file descriptors for readiness to read
458 The program loops, repeatedly using
460 to monitor the file descriptors,
461 printing the number of ready file descriptors on return.
462 For each ready file descriptor, the program:
464 displays the returned
466 field in a human-readable form;
468 if the file descriptor is readable, reads some data from it,
469 and displays that data on standard output; and
471 if the file descriptor was not readable,
472 but some other event occurred (presumably
474 closes the file descriptor.
476 Suppose we run the program in one terminal, asking it to open a FIFO:
480 $ \fBmkfifo myfifo\fP
481 $ \fB./poll_input myfifo\fP
485 In a second terminal window, we then open the FIFO for writing,
486 write some data to it, and close the FIFO:
490 $ \fBecho aaaaabbbbbccccc > myfifo\fP
494 In the terminal where we are running the program, we would then see:
498 Opened "myfifo" on fd 3
501 fd=3; events: POLLIN POLLHUP
502 read 10 bytes: aaaaabbbbb
505 fd=3; events: POLLIN POLLHUP
510 fd=3; events: POLLHUP
512 All file descriptors closed; bye
516 In the above output, we see that
518 returned three times:
520 On the first return, the bits returned in the
524 indicating that the file descriptor is readable, and
526 indicating that the other end of the FIFO has been closed.
527 The program then consumed some of the available input.
529 The second return from
535 the program then consumed the last of the available input.
542 at which point the file descriptor was closed and the program terminated.
546 .\" SRC BEGIN (poll_input.c)
550 Licensed under GNU General Public License v2 or later.
558 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
562 main(int argc, char *argv[])
564 int nfds, num_open_fds, ready;
570 fprintf(stderr, "Usage: %s file...\en", argv[0]);
574 num_open_fds = nfds = argc \- 1;
575 pfds = calloc(nfds, sizeof(struct pollfd));
579 /* Open each file on command line, and add it \(aqpfds\(aq array. */
581 for (int j = 0; j < nfds; j++) {
582 pfds[j].fd = open(argv[j + 1], O_RDONLY);
583 if (pfds[j].fd == \-1)
586 printf("Opened \e"%s\e" on fd %d\en", argv[j + 1], pfds[j].fd);
588 pfds[j].events = POLLIN;
591 /* Keep calling poll() as long as at least one file descriptor is
594 while (num_open_fds > 0) {
595 printf("About to poll()\en");
596 ready = poll(pfds, nfds, \-1);
600 printf("Ready: %d\en", ready);
602 /* Deal with array returned by poll(). */
604 for (int j = 0; j < nfds; j++) {
605 if (pfds[j].revents != 0) {
606 printf(" fd=%d; events: %s%s%s\en", pfds[j].fd,
607 (pfds[j].revents & POLLIN) ? "POLLIN " : "",
608 (pfds[j].revents & POLLHUP) ? "POLLHUP " : "",
609 (pfds[j].revents & POLLERR) ? "POLLERR " : "");
611 if (pfds[j].revents & POLLIN) {
612 s = read(pfds[j].fd, buf, sizeof(buf));
615 printf(" read %zd bytes: %.*s\en",
617 } else { /* POLLERR | POLLHUP */
618 printf(" closing fd %d\en", pfds[j].fd);
619 if (close(pfds[j].fd) == \-1)
627 printf("All file descriptors closed; bye\en");
633 .BR restart_syscall (2),