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.
407 .\" ppoll() is proposed for inclusion in POSIX:
408 .\" https://www.austingroupbugs.net/view.php?id=1263
409 .\" NetBSD 3.0 has a pollts() which is like Linux ppoll().
415 is not affected by the
419 On some other UNIX systems,
420 .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett
422 can fail with the error
424 if the system fails to allocate kernel-internal resources, rather than
427 POSIX permits this behavior.
428 Portable programs may wish to check for
430 and loop, just as with
433 Some implementations define the nonstandard constant
435 with the value \-1 for use as a
439 This constant is not provided in glibc.
441 For a discussion of what may happen if a file descriptor being monitored by
443 is closed in another thread, see
445 .SS C library/kernel differences
448 system call modifies its
451 However, the glibc wrapper function hides this behavior
452 by using a local variable for the timeout argument that
453 is passed to the system call.
456 function does not modify its
462 system call has a fifth argument,
463 .IR "size_t sigsetsize" ,
464 which specifies the size in bytes of the
469 wrapper function specifies this argument as a fixed value
471 .IR sizeof(kernel_sigset_t) ).
474 for a discussion on the differences between the kernel and the libc
475 notion of the sigset.
477 See the discussion of spurious readiness notifications under the
481 The program below opens each of the files named in its command-line
482 arguments and monitors the resulting file descriptors for readiness to read
484 The program loops, repeatedly using
486 to monitor the file descriptors,
487 printing the number of ready file descriptors on return.
488 For each ready file descriptor, the program:
490 displays the returned
492 field in a human-readable form;
494 if the file descriptor is readable, reads some data from it,
495 and displays that data on standard output; and
497 if the file descriptors was not readable,
498 but some other event occurred (presumably
500 closes the file descriptor.
502 Suppose we run the program in one terminal, asking it to open a FIFO:
506 $ \fBmkfifo myfifo\fP
507 $ \fB./poll_input myfifo\fP
511 In a second terminal window, we then open the FIFO for writing,
512 write some data to it, and close the FIFO:
516 $ \fBecho aaaaabbbbbccccc > myfifo\fP
520 In the terminal where we are running the program, we would then see:
524 Opened "myfifo" on fd 3
527 fd=3; events: POLLIN POLLHUP
528 read 10 bytes: aaaaabbbbb
531 fd=3; events: POLLIN POLLHUP
536 fd=3; events: POLLHUP
538 All file descriptors closed; bye
542 In the above output, we see that
544 returned three times:
546 On the first return, the bits returned in the
550 indicating that the file descriptor is readable, and
552 indicating that the other end of the FIFO has been closed.
553 The program then consumed some of the available input.
555 The second return from
561 the program then consumed the last of the available input.
568 at which point the file descriptor was closed and the program terminated.
575 Licensed under GNU General Public License v2 or later.
579 #include <sys/types.h>
584 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
588 main(int argc, char *argv[])
590 int nfds, num_open_fds;
594 fprintf(stderr, "Usage: %s file...\en", argv[0]);
598 num_open_fds = nfds = argc \- 1;
599 pfds = calloc(nfds, sizeof(struct pollfd));
603 /* Open each file on command line, and add it \(aqpfds\(aq array */
605 for (int j = 0; j < nfds; j++) {
606 pfds[j].fd = open(argv[j + 1], O_RDONLY);
607 if (pfds[j].fd == \-1)
610 printf("Opened \e"%s\e" on fd %d\en", argv[j + 1], pfds[j].fd);
612 pfds[j].events = POLLIN;
615 /* Keep calling poll() as long as at least one file descriptor is
618 while (num_open_fds > 0) {
621 printf("About to poll()\en");
622 ready = poll(pfds, nfds, \-1);
626 printf("Ready: %d\en", ready);
628 /* Deal with array returned by poll() */
630 for (int j = 0; j < nfds; j++) {
633 if (pfds[j].revents != 0) {
634 printf(" fd=%d; events: %s%s%s\en", pfds[j].fd,
635 (pfds[j].revents & POLLIN) ? "POLLIN " : "",
636 (pfds[j].revents & POLLHUP) ? "POLLHUP " : "",
637 (pfds[j].revents & POLLERR) ? "POLLERR " : "");
639 if (pfds[j].revents & POLLIN) {
640 ssize_t s = read(pfds[j].fd, buf, sizeof(buf));
643 printf(" read %zd bytes: %.*s\en",
645 } else { /* POLLERR | POLLHUP */
646 printf(" closing fd %d\en", pfds[j].fd);
647 if (close(pfds[j].fd) == \-1)
655 printf("All file descriptors closed; bye\en");
660 .BR restart_syscall (2),