1 .\" Copyright (C) 2006, 2019 Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" %%%LICENSE_START(VERBATIM)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" Additions from Richard Gooch <rgooch@atnf.CSIRO.AU> and aeb, 971207
26 .\" 2006-03-13, mtk, Added ppoll() + various other rewordings
27 .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and
28 .\" formatting changes.
30 .TH POLL 2 2020-04-11 "Linux" "Linux Programmer's Manual"
32 poll, ppoll \- wait for some event on a file descriptor
37 .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
39 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
40 .B #include <signal.h>
43 .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", "
44 .BI " const struct timespec *" tmo_p ", const sigset_t *" sigmask );
48 performs a similar task to
50 it waits for one of a set of file descriptors to become ready
54 API performs a similar task, but offers features beyond those found in
57 The set of file descriptors to be monitored is specified in the
59 argument, which is an array of structures of the following form:
64 int fd; /* file descriptor */
65 short events; /* requested events */
66 short revents; /* returned events */
71 The caller should specify the number of items in the
78 contains a file descriptor for an open file.
79 If this field is negative, then the corresponding
81 field is ignored and the
84 (This provides an easy way of ignoring a
85 file descriptor for a single
87 call: simply negate the
90 Note, however, that this technique can't be used to ignore file descriptor 0.)
94 is an input parameter, a bit mask specifying the events the application
95 is interested in for the file descriptor
97 This field may be specified as zero,
98 in which case the only events that can be returned in
109 is an output parameter, filled by the kernel with the events that
113 can include any of those specified in
120 (These three bits are meaningless in the
122 field, and will be set in the
124 field whenever the corresponding condition is true.)
126 If none of the events requested (and no error) has occurred for any
127 of the file descriptors, then
129 blocks until one of the events occurs.
133 argument specifies the number of milliseconds that
135 should block waiting for a file descriptor to become ready.
136 The call will block until either:
138 a file descriptor becomes ready;
140 the call is interrupted by a signal handler; or
146 interval will be rounded up to the system clock granularity,
147 and kernel scheduling delays mean that the blocking interval
148 may overrun by a small amount.
149 Specifying a negative value in
151 means an infinite timeout.
156 to return immediately, even if no file descriptors are ready.
158 The bits that may be set/returned in
162 are defined in \fI<poll.h>\fP:
165 There is data to read.
168 There is some exceptional condition on the file descriptor.
169 Possibilities include:
172 There is out-of-band data on a TCP socket (see
175 A pseudoterminal master in packet mode has seen a state change on the slave
181 file has been modified (see
186 Writing is now possible, though a write larger that the available space
187 in a socket or pipe will still block (unless
191 .BR POLLRDHUP " (since Linux 2.6.17)"
192 Stream socket peer closed connection,
193 or shut down writing half of connection.
196 feature test macro must be defined
200 in order to obtain this definition.
203 Error condition (only returned in
207 This bit is also set for a file descriptor referring
208 to the write end of a pipe when the read end has been closed.
211 Hang up (only returned in
215 Note that when reading from a channel such as a pipe or a stream socket,
216 this event merely indicates that the peer closed its end of the channel.
217 Subsequent reads from the channel will return 0 (end of file)
218 only after all outstanding data in the channel has been consumed.
223 not open (only returned in
230 defined, one also has the following,
231 which convey no further information beyond the bits listed above:
238 Priority band data can be read (generally unused on Linux).
239 .\" POLLRDBAND is used in the DECnet protocol.
246 Priority data may be written.
248 Linux also knows about, but does not use
251 The relationship between
255 is analogous to the relationship between
262 allows an application to safely wait until either a file descriptor
263 becomes ready or until a signal is caught.
265 Other than the difference in the precision of the
267 argument, the following
273 ready = ppoll(&fds, nfds, tmo_p, &sigmask);
277 is nearly equivalent to
279 executing the following calls:
286 timeout = (tmo_p == NULL) ? \-1 :
287 (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000);
288 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
289 ready = poll(&fds, nfds, timeout);
290 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
294 The above code segment is described as
296 equivalent because whereas a negative
300 is interpreted as an infinite timeout, a negative value expressed in
302 results in an error from
305 See the description of
307 for an explanation of why
313 argument is specified as NULL, then
314 no signal mask manipulation is performed
319 only in the precision of the
325 argument specifies an upper limit on the amount of time that
328 This argument is a pointer to a structure of the following form:
333 long tv_sec; /* seconds */
334 long tv_nsec; /* nanoseconds */
341 is specified as NULL, then
343 can block indefinitely.
347 returns a nonnegative value which is the number of elements in the
351 fields have been set to a nonzero value (indicating an event or an error).
352 A return value of zero indicates that the system call timed out
353 before any file descriptors became read.
355 On error, \-1 is returned, and
357 is set to indicate the cause of the error.
362 points outside the process's accessible address space.
363 The array given as argument was not contained in the calling program's
367 A signal occurred before any requested event; see
379 The timeout value expressed in
381 is invalid (negative).
384 Unable to allocate memory for kernel data structures.
388 system call was introduced in Linux 2.1.23.
389 On older kernels that lack this system call,
392 wrapper function provides emulation using
397 system call was added to Linux in kernel 2.6.16.
400 library call was added in glibc 2.4.
403 conforms to POSIX.1-2001 and POSIX.1-2008.
406 .\" NetBSD 3.0 has a pollts() which is like Linux ppoll().
412 is not affected by the
416 On some other UNIX systems,
417 .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett
419 can fail with the error
421 if the system fails to allocate kernel-internal resources, rather than
424 POSIX permits this behavior.
425 Portable programs may wish to check for
427 and loop, just as with
430 Some implementations define the nonstandard constant
432 with the value \-1 for use as a
436 This constant is not provided in glibc.
438 For a discussion of what may happen if a file descriptor being monitored by
440 is closed in another thread, see
442 .SS C library/kernel differences
445 system call modifies its
448 However, the glibc wrapper function hides this behavior
449 by using a local variable for the timeout argument that
450 is passed to the system call.
453 function does not modify its
459 system call has a fifth argument,
460 .IR "size_t sigsetsize" ,
461 which specifies the size in bytes of the
466 wrapper function specifies this argument as a fixed value
468 .IR sizeof(kernel_sigset_t) ).
471 for a discussion on the differences between the kernel and the libc
472 notion of the sigset.
474 See the discussion of spurious readiness notifications under the
478 The program below opens each of the files named in its command-line
479 arguments and monitors the resulting file descriptors for readiness to read
481 The program loops, repeatedly using
483 to monitor the file descriptors,
484 printing the number of ready file descriptors on return.
485 For each ready file descriptor, the program:
487 displays the returned
489 field in a human-readable form;
491 if the file descriptor is readable, reads some data from it,
492 and displays that data on standard output; and
494 if the file descriptors was not readable,
495 but some other event occurred (presumably
497 closes the file descriptor.
499 Suppose we run the program in one terminal, asking it to open a FIFO:
503 $ \fBmkfifo myfifo\fP
504 $ \fB./poll_input myfifo\fP
508 In a second terminal window, we then open the FIFO for writing,
509 write some data to it, and close the FIFO:
513 $ \fBecho aaaaabbbbbccccc > myfifo\fP
517 In the terminal where we are running the program, we would then see:
521 Opened "myfifo" on fd 3
524 fd=3; events: POLLIN POLLHUP
525 read 10 bytes: aaaaabbbbb
528 fd=3; events: POLLIN POLLHUP
533 fd=3; events: POLLHUP
535 All file descriptors closed; bye
539 In the above output, we see that
541 returned three times:
543 On the first return, the bits returned in the
547 indicating that the file descriptor is readable, and
549 indicating that the other end of the FIFO has been closed.
550 The program then consumed some of the available input.
552 The second return from
558 the program then consumed the last of the available input.
565 at which point the file descriptor was closed and the program terminated.
572 Licensed under GNU General Public License v2 or later.
576 #include <sys/types.h>
581 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
585 main(int argc, char *argv[])
587 int nfds, num_open_fds;
591 fprintf(stderr, "Usage: %s file...\en", argv[0]);
595 num_open_fds = nfds = argc \- 1;
596 pfds = calloc(nfds, sizeof(struct pollfd));
600 /* Open each file on command line, and add it \(aqpfds\(aq array */
602 for (int j = 0; j < nfds; j++) {
603 pfds[j].fd = open(argv[j + 1], O_RDONLY);
604 if (pfds[j].fd == \-1)
607 printf("Opened \e"%s\e" on fd %d\en", argv[j + 1], pfds[j].fd);
609 pfds[j].events = POLLIN;
612 /* Keep calling poll() as long as at least one file descriptor is
615 while (num_open_fds > 0) {
618 printf("About to poll()\en");
619 ready = poll(pfds, nfds, \-1);
623 printf("Ready: %d\en", ready);
625 /* Deal with array returned by poll() */
627 for (int j = 0; j < nfds; j++) {
630 if (pfds[j].revents != 0) {
631 printf(" fd=%d; events: %s%s%s\en", pfds[j].fd,
632 (pfds[j].revents & POLLIN) ? "POLLIN " : "",
633 (pfds[j].revents & POLLHUP) ? "POLLHUP " : "",
634 (pfds[j].revents & POLLERR) ? "POLLERR " : "");
636 if (pfds[j].revents & POLLIN) {
637 ssize_t s = read(pfds[j].fd, buf, sizeof(buf));
640 printf(" read %zd bytes: %.*s\en",
642 } else { /* POLLERR | POLLHUP */
643 printf(" closing fd %d\en", pfds[j].fd);
644 if (close(pfds[j].fd) == \-1)
652 printf("All file descriptors closed; bye\en");
657 .BR restart_syscall (2),