Debian Codegraph @

upstream/debian-trixie/man2/poll.2

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