Debian Codegraph @

upstream/debian-unstable/man2/poll.2

raw
1 .\" Copyright 2006-2019, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH poll 2 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 poll, ppoll \- wait for some event on a file descriptor
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <poll.h>
15 .P
16 .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
17 .P
18 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
19 .B #include <poll.h>
20 .P
21 .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ,
22 .BI " const struct timespec *_Nullable " tmo_p ,
23 .BI " const sigset_t *_Nullable " sigmask );
24 .fi
25 .SH DESCRIPTION
26 .BR poll ()
27 performs a similar task to
28 .BR select (2):
29 it waits for one of a set of file descriptors to become ready
30 to perform I/O.
31 The Linux-specific
32 .BR epoll (7)
33 API performs a similar task, but offers features beyond those found in
34 .BR poll ().
35 .P
36 The set of file descriptors to be monitored is specified in the
37 .I fds
38 argument, which is an array of structures of the following form:
39 .P
40 .in +4n
41 .EX
42 struct pollfd {
43 int fd; /* file descriptor */
44 short events; /* requested events */
45 short revents; /* returned events */
46 };
47 .EE
48 .in
49 .P
50 The caller should specify the number of items in the
51 .I fds
52 array in
53 .IR nfds .
54 .P
55 The field
56 .I fd
57 contains a file descriptor for an open file.
58 If this field is negative, then the corresponding
59 .I events
60 field is ignored and the
61 .I revents
62 field returns zero.
63 (This provides an easy way of ignoring a
64 file descriptor for a single
65 .BR poll ()
66 call: simply set the
67 .I fd
68 field to its bitwise complement.)
69 .P
70 The field
71 .I events
72 is an input parameter, a bit mask specifying the events the application
73 is interested in for the file descriptor
74 .IR fd .
75 This field may be specified as zero,
76 in which case the only events that can be returned in
77 .I revents
78 are
79 .BR POLLHUP ,
80 .BR POLLERR ,
81 and
82 .B POLLNVAL
83 (see below).
84 .P
85 The field
86 .I revents
87 is an output parameter, filled by the kernel with the events that
88 actually occurred.
89 The bits returned in
90 .I revents
91 can include any of those specified in
92 .IR events ,
93 or one of the values
94 .BR POLLERR ,
95 .BR POLLHUP ,
96 or
97 .BR POLLNVAL .
98 (These three bits are meaningless in the
99 .I events
100 field, and will be set in the
101 .I revents
102 field whenever the corresponding condition is true.)
103 .P
104 If none of the events requested (and no error) has occurred for any
105 of the file descriptors, then
106 .BR poll ()
107 blocks until one of the events occurs.
108 .P
109 The
110 .I timeout
111 argument specifies the number of milliseconds that
112 .BR poll ()
113 should block waiting for a file descriptor to become ready.
114 The call will block until either:
115 .IP \[bu] 3
116 a file descriptor becomes ready;
117 .IP \[bu]
118 the call is interrupted by a signal handler;
119 or
120 .IP \[bu]
121 the timeout expires.
122 .P
123 Being "ready" means that the requested operation will not block;
124 thus,
125 .BR poll ()ing
126 regular files,
127 block devices,
128 and other files with no reasonable polling semantic
129 .I always
130 returns instantly as ready to read and write.
131 .P
132 Note that the
133 .I timeout
134 interval will be rounded up to the system clock granularity,
135 and kernel scheduling delays mean that the blocking interval
136 may overrun by a small amount.
137 Specifying a negative value in
138 .I timeout
139 means an infinite timeout.
140 Specifying a
141 .I timeout
142 of zero causes
143 .BR poll ()
144 to return immediately, even if no file descriptors are ready.
145 .P
146 The bits that may be set/returned in
147 .I events
148 and
149 .I revents
150 are defined in
151 .IR <poll.h> :
152 .TP
153 .B POLLIN
154 There is data to read.
155 .TP
156 .B POLLPRI
157 There is some exceptional condition on the file descriptor.
158 Possibilities include:
159 .RS
160 .IP \[bu] 3
161 There is out-of-band data on a TCP socket (see
162 .BR tcp (7)).
163 .IP \[bu]
164 A pseudoterminal master in packet mode has seen a state change on the slave
165 (see
166 .BR ioctl_tty (2)).
167 .IP \[bu]
168 A
169 .I cgroup.events
170 file has been modified (see
171 .BR cgroups (7)).
172 .RE
173 .TP
174 .B POLLOUT
175 Writing is now possible, though a write larger than the available space
176 in a socket or pipe will still block (unless
177 .B O_NONBLOCK
178 is set).
179 .TP
180 .BR POLLRDHUP " (since Linux 2.6.17)"
181 Stream socket peer closed connection,
182 or shut down writing half of connection.
183 The
184 .B _GNU_SOURCE
185 feature test macro must be defined
186 (before including
187 .I any
188 header files)
189 in order to obtain this definition.
190 .TP
191 .B POLLERR
192 Error condition (only returned in
193 .IR revents ;
194 ignored in
195 .IR events ).
196 This bit is also set for a file descriptor referring
197 to the write end of a pipe when the read end has been closed.
198 .TP
199 .B POLLHUP
200 Hang up (only returned in
201 .IR revents ;
202 ignored in
203 .IR events ).
204 Note that when reading from a channel such as a pipe or a stream socket,
205 this event merely indicates that the peer closed its end of the channel.
206 Subsequent reads from the channel will return 0 (end of file)
207 only after all outstanding data in the channel has been consumed.
208 .TP
209 .B POLLNVAL
210 Invalid request:
211 .I fd
212 not open (only returned in
213 .IR revents ;
214 ignored in
215 .IR events ).
216 .P
217 When compiling with
218 .B _XOPEN_SOURCE
219 defined, one also has the following,
220 which convey no further information beyond the bits listed above:
221 .TP
222 .B POLLRDNORM
223 Equivalent to
224 .BR POLLIN .
225 .TP
226 .B POLLRDBAND
227 Priority band data can be read (generally unused on Linux).
228 .\" POLLRDBAND is used in the DECnet protocol.
229 .TP
230 .B POLLWRNORM
231 Equivalent to
232 .BR POLLOUT .
233 .TP
234 .B POLLWRBAND
235 Priority data may be written.
236 .P
237 Linux also knows about, but does not use
238 .BR POLLMSG .
239 .SS ppoll()
240 The relationship between
241 .BR poll ()
242 and
243 .BR ppoll ()
244 is analogous to the relationship between
245 .BR select (2)
246 and
247 .BR pselect (2):
248 like
249 .BR pselect (2),
250 .BR ppoll ()
251 allows an application to safely wait until either a file descriptor
252 becomes ready or until a signal is caught.
253 .P
254 Other than the difference in the precision of the
255 .I timeout
256 argument, the following
257 .BR ppoll ()
258 call:
259 .P
260 .in +4n
261 .EX
262 ready = ppoll(&fds, nfds, tmo_p, &sigmask);
263 .EE
264 .in
265 .P
266 is nearly equivalent to
267 .I atomically
268 executing the following calls:
269 .P
270 .in +4n
271 .EX
272 sigset_t origmask;
273 int timeout;
274 \&
275 timeout = (tmo_p == NULL) ? \-1 :
276 (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000);
277 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
278 ready = poll(&fds, nfds, timeout);
279 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
280 .EE
281 .in
282 .P
283 The above code segment is described as
284 .I nearly
285 equivalent because whereas a negative
286 .I timeout
287 value for
288 .BR poll ()
289 is interpreted as an infinite timeout, a negative value expressed in
290 .I *tmo_p
291 results in an error from
292 .BR ppoll ().
293 .P
294 See the description of
295 .BR pselect (2)
296 for an explanation of why
297 .BR ppoll ()
298 is necessary.
299 .P
300 If the
301 .I sigmask
302 argument is specified as NULL, then
303 no signal mask manipulation is performed
304 (and thus
305 .BR ppoll ()
306 differs from
307 .BR poll ()
308 only in the precision of the
309 .I timeout
310 argument).
311 .P
312 The
313 .I tmo_p
314 argument specifies an upper limit on the amount of time that
315 .BR ppoll ()
316 will block.
317 This argument is a pointer to a
318 .BR timespec (3)
319 structure.
320 .P
321 If
322 .I tmo_p
323 is specified as NULL, then
324 .BR ppoll ()
325 can block indefinitely.
326 .SH RETURN VALUE
327 On success,
328 .BR poll ()
329 returns a nonnegative value which is the number of elements in the
330 .I pollfds
331 whose
332 .I revents
333 fields have been set to a nonzero value (indicating an event or an error).
334 A return value of zero indicates that the system call timed out
335 before any file descriptors became ready.
336 .P
337 On error, \-1 is returned, and
338 .I errno
339 is set to indicate the error.
340 .SH ERRORS
341 .TP
342 .B EFAULT
343 .I fds
344 points outside the process's accessible address space.
345 The array given as argument was not contained in the calling program's
346 address space.
347 .TP
348 .B EINTR
349 A signal occurred before any requested event;
350 see
351 .BR signal (7).
352 .TP
353 .B EINVAL
354 The
355 .I nfds
356 value exceeds the
357 .B RLIMIT_NOFILE
358 value.
359 .TP
360 .B EINVAL
361 .RB ( ppoll ())
362 The timeout value expressed in
363 .I *tmo_p
364 is invalid (negative).
365 .TP
366 .B ENOMEM
367 Unable to allocate memory for kernel data structures.
368 .SH VERSIONS
369 On some other UNIX systems,
370 .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett
371 .BR poll ()
372 can fail with the error
373 .B EAGAIN
374 if the system fails to allocate kernel-internal resources, rather than
375 .B ENOMEM
376 as Linux does.
377 POSIX permits this behavior.
378 Portable programs may wish to check for
379 .B EAGAIN
380 and loop, just as with
381 .BR EINTR .
382 .P
383 Some implementations define the nonstandard constant
384 .B INFTIM
385 with the value \-1 for use as a
386 .I timeout
387 for
388 .BR poll ().
389 This constant is not provided in glibc.
390 .SS C library/kernel differences
391 The Linux
392 .BR ppoll ()
393 system call modifies its
394 .I tmo_p
395 argument.
396 However, the glibc wrapper function hides this behavior
397 by using a local variable for the timeout argument that
398 is passed to the system call.
399 Thus, the glibc
400 .BR ppoll ()
401 function does not modify its
402 .I tmo_p
403 argument.
404 .P
405 The raw
406 .BR ppoll ()
407 system call has a fifth argument,
408 .IR "size_t sigsetsize" ,
409 which specifies the size in bytes of the
410 .I sigmask
411 argument.
412 The glibc
413 .BR ppoll ()
414 wrapper function specifies this argument as a fixed value
415 (equal to
416 .IR sizeof(kernel_sigset_t) ).
417 See
418 .BR sigprocmask (2)
419 for a discussion on the differences between the kernel and the libc
420 notion of the sigset.
421 .SH STANDARDS
422 POSIX.1-2024.
423 .SH HISTORY
424 .TP
425 .BR poll ()
426 POSIX.1-2001.
427 Linux 2.1.23.
428 .IP
429 On older kernels that lack this system call,
430 the glibc
431 .BR poll ()
432 wrapper function provides emulation using
433 .BR select (2).
434 .TP
435 .BR ppoll ()
436 POSIX.1-2024.
437 Linux 2.6.16,
438 glibc 2.4.
439 .SH NOTES
440 The operation of
441 .BR poll ()
442 and
443 .BR ppoll ()
444 is not affected by the
445 .B O_NONBLOCK
446 flag.
447 .P
448 For a discussion of what may happen if a file descriptor being monitored by
449 .BR poll ()
450 is closed in another thread, see
451 .BR select (2).
452 .SH BUGS
453 See the discussion of spurious readiness notifications under the
454 BUGS section of
455 .BR select (2).
456 .SH EXAMPLES
457 The program below opens each of the files named in its command-line
458 arguments and monitors the resulting file descriptors for readiness to read
459 .RB ( POLLIN ).
460 The program loops, repeatedly using
461 .BR poll ()
462 to monitor the file descriptors,
463 printing the number of ready file descriptors on return.
464 For each ready file descriptor, the program:
465 .IP \[bu] 3
466 displays the returned
467 .I revents
468 field in a human-readable form;
469 .IP \[bu]
470 if the file descriptor is readable, reads some data from it,
471 and displays that data on standard output;
472 and
473 .IP \[bu]
474 if the file descriptor was not readable,
475 but some other event occurred (presumably
476 .BR POLLHUP ),
477 closes the file descriptor.
478 .P
479 Suppose we run the program in one terminal, asking it to open a FIFO:
480 .P
481 .in +4n
482 .EX
483 .RB $ " mkfifo myfifo" ;
484 .RB $ " ./poll_input myfifo" ;
485 .EE
486 .in
487 .P
488 In a second terminal window, we then open the FIFO for writing,
489 write some data to it, and close the FIFO:
490 .P
491 .in +4n
492 .EX
493 .RB $ " echo aaaaabbbbbccccc > myfifo" ;
494 .EE
495 .in
496 .P
497 In the terminal where we are running the program, we would then see:
498 .P
499 .in +4n
500 .EX
501 Opened "myfifo" on fd 3
502 About to poll()
503 Ready: 1
504 fd=3; events: POLLIN POLLHUP
505 read 10 bytes: aaaaabbbbb
506 About to poll()
507 Ready: 1
508 fd=3; events: POLLIN POLLHUP
509 read 6 bytes: ccccc
510 \&
511 About to poll()
512 Ready: 1
513 fd=3; events: POLLHUP
514 closing fd 3
515 All file descriptors closed. Bye.
516 .EE
517 .in
518 .P
519 In the above output, we see that
520 .BR poll ()
521 returned three times:
522 .IP \[bu] 3
523 On the first return, the bits returned in the
524 .I revents
525 field were
526 .BR POLLIN ,
527 indicating that the file descriptor is readable, and
528 .BR POLLHUP ,
529 indicating that the other end of the FIFO has been closed.
530 The program then consumed some of the available input.
531 .IP \[bu]
532 The second return from
533 .BR poll ()
534 also indicated
535 .B POLLIN
536 and
537 .BR POLLHUP ;
538 the program then consumed the last of the available input.
539 .IP \[bu]
540 On the final return,
541 .BR poll ()
542 indicated only
543 .B POLLHUP
544 on the FIFO,
545 at which point the file descriptor was closed and the program terminated.
546 .\"
547 .SS Program source
548 \&
549 .\" SRC BEGIN (poll_input.c)
550 .EX
551 /* poll_input.c
552 \&
553 Licensed under GNU General Public License v2 or later.
554 */
555 #include <err.h>
556 #include <fcntl.h>
557 #include <poll.h>
558 #include <stdio.h>
559 #include <stdlib.h>
560 #include <sys/types.h>
561 #include <unistd.h>
562 \&
563 int
564 main(int argc, char *argv[])
565 {
566 int ready;
567 char buf[10];
568 nfds_t num_open_fds, nfds;
569 ssize_t s;
570 struct pollfd *pfds;
571 \&
572 if (argc < 2) {
573 fprintf(stderr, "Usage: %s file...\[rs]n", argv[0]);
574 exit(EXIT_FAILURE);
575 }
576 \&
577 num_open_fds = nfds = argc \- 1;
578 pfds = calloc(nfds, sizeof(struct pollfd));
579 if (pfds == NULL)
580 err(EXIT_FAILURE, "malloc");
581 \&
582 /* Open each file on command line, and add it to \[aq]pfds\[aq] array. */
583 \&
584 for (nfds_t j = 0; j < nfds; j++) {
585 pfds[j].fd = open(argv[j + 1], O_RDONLY);
586 if (pfds[j].fd == \-1)
587 err(EXIT_FAILURE, "open");
588 \&
589 printf("Opened \[rs]"%s\[rs]" on fd %d\[rs]n", argv[j + 1], pfds[j].fd);
590 \&
591 pfds[j].events = POLLIN;
592 }
593 \&
594 /* Keep calling poll() as long as at least one file descriptor is
595 open. */
596 \&
597 while (num_open_fds > 0) {
598 printf("About to poll()\[rs]n");
599 ready = poll(pfds, nfds, \-1);
600 if (ready == \-1)
601 err(EXIT_FAILURE, "poll");
602 \&
603 printf("Ready: %d\[rs]n", ready);
604 \&
605 /* Deal with array returned by poll(). */
606 \&
607 for (nfds_t j = 0; j < nfds; j++) {
608 if (pfds[j].revents != 0) {
609 printf(" fd=%d; events: %s%s%s\[rs]n", pfds[j].fd,
610 (pfds[j].revents & POLLIN) ? "POLLIN " : "",
611 (pfds[j].revents & POLLHUP) ? "POLLHUP " : "",
612 (pfds[j].revents & POLLERR) ? "POLLERR " : "");
613 \&
614 if (pfds[j].revents & POLLIN) {
615 s = read(pfds[j].fd, buf, sizeof(buf));
616 if (s == \-1)
617 err(EXIT_FAILURE, "read");
618 printf(" read %zd bytes: %.*s\[rs]n",
619 s, (int) s, buf);
620 } else { /* POLLERR | POLLHUP */
621 printf(" closing fd %d\[rs]n", pfds[j].fd);
622 if (close(pfds[j].fd) == \-1)
623 err(EXIT_FAILURE, "close");
624 num_open_fds\-\-;
625 }
626 }
627 }
628 }
629 \&
630 printf("All file descriptors closed. Bye.\[rs]n");
631 exit(EXIT_SUCCESS);
632 }
633 .EE
634 .\" SRC END
635 .SH SEE ALSO
636 .BR restart_syscall (2),
637 .BR select (2),
638 .BR select_tut (2),
639 .BR timespec (3),
640 .BR epoll (7),
641 .BR time (7)