]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl) |
c11b1abf | 2 | .\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
c13182ef | 13 | .\" |
fea681da MK |
14 | .\" Since the Linux kernel and libraries are constantly changing, this |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
c13182ef | 21 | .\" |
fea681da MK |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
fea681da MK |
25 | .\" |
26 | .\" Additions from Richard Gooch <rgooch@atnf.CSIRO.AU> and aeb, 971207 | |
e755a587 | 27 | .\" 2006-03-13, mtk, Added ppoll() + various other rewordings |
23cb3cb5 MK |
28 | .\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and |
29 | .\" formatting changes. | |
4b9d4c1a | 30 | .\" |
4b8c67d9 | 31 | .TH POLL 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 32 | .SH NAME |
e755a587 | 33 | poll, ppoll \- wait for some event on a file descriptor |
fea681da | 34 | .SH SYNOPSIS |
e755a587 | 35 | .nf |
23cb3cb5 | 36 | .B #include <poll.h> |
68e4db0a | 37 | .PP |
e755a587 | 38 | .BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout ); |
f90f031e | 39 | |
b80f966b | 40 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
da30ae71 | 41 | .B #include <signal.h> |
23cb3cb5 | 42 | .B #include <poll.h> |
68e4db0a | 43 | .PP |
e755a587 | 44 | .BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", " |
0bf502fc | 45 | .BI " const struct timespec *" tmo_p ", const sigset_t *" sigmask ); |
e755a587 | 46 | .fi |
fea681da | 47 | .SH DESCRIPTION |
96296ef0 | 48 | .BR poll () |
e755a587 MK |
49 | performs a similar task to |
50 | .BR select (2): | |
51 | it waits for one of a set of file descriptors to become ready | |
52 | to perform I/O. | |
efeece04 | 53 | .PP |
e755a587 MK |
54 | The set of file descriptors to be monitored is specified in the |
55 | .I fds | |
d8dfbff9 | 56 | argument, which is an array of structures of the following form: |
e646a1ba | 57 | .PP |
088a639b | 58 | .in +4n |
e646a1ba | 59 | .EX |
a08ea57c MK |
60 | struct pollfd { |
61 | int fd; /* file descriptor */ | |
62 | short events; /* requested events */ | |
63 | short revents; /* returned events */ | |
64 | }; | |
b8302363 | 65 | .EE |
e646a1ba | 66 | .in |
d8dfbff9 MK |
67 | .PP |
68 | The caller should specify the number of items in the | |
69 | .I fds | |
70 | array in | |
71 | .IR nfds . | |
efeece04 | 72 | .PP |
fea681da MK |
73 | The field |
74 | .I fd | |
75 | contains a file descriptor for an open file. | |
096ca08a MK |
76 | If this field is negative, then the corresponding |
77 | .I events | |
78 | field is ignored and the | |
79 | .I revents | |
80 | field returns zero. | |
81 | (This provides an easy way of ignoring a | |
82 | file descriptor for a single | |
83 | .BR poll () | |
84 | call: simply negate the | |
85 | .I fd | |
e2cfd90e MK |
86 | field. |
87 | Note, however, that this technique can't be used to ignore file descriptor 0.) | |
efeece04 | 88 | .PP |
fea681da MK |
89 | The field |
90 | .I events | |
10f5f294 | 91 | is an input parameter, a bit mask specifying the events the application |
b857fda5 MK |
92 | is interested in for the file descriptor |
93 | .IR fd . | |
210cded6 MK |
94 | This field may be specified as zero, |
95 | in which case the only events that can be returned in | |
b857fda5 | 96 | .I revents |
210cded6 MK |
97 | are |
98 | .BR POLLHUP , | |
99 | .BR POLLERR , | |
100 | and | |
101 | .B POLLNVAL | |
102 | (see below). | |
efeece04 | 103 | .PP |
fea681da MK |
104 | The field |
105 | .I revents | |
106 | is an output parameter, filled by the kernel with the events that | |
e755a587 MK |
107 | actually occurred. |
108 | The bits returned in | |
109 | .I revents | |
c13182ef | 110 | can include any of those specified in |
e755a587 MK |
111 | .IR events , |
112 | or one of the values | |
113 | .BR POLLERR , | |
114 | .BR POLLHUP , | |
fea681da MK |
115 | or |
116 | .BR POLLNVAL . | |
117 | (These three bits are meaningless in the | |
118 | .I events | |
119 | field, and will be set in the | |
120 | .I revents | |
121 | field whenever the corresponding condition is true.) | |
efeece04 | 122 | .PP |
fea681da | 123 | If none of the events requested (and no error) has occurred for any |
e755a587 MK |
124 | of the file descriptors, then |
125 | .BR poll () | |
126 | blocks until one of the events occurs. | |
efeece04 | 127 | .PP |
c13182ef | 128 | The |
e755a587 | 129 | .I timeout |
0d9101c4 | 130 | argument specifies the number of milliseconds that |
e755a587 | 131 | .BR poll () |
0d9101c4 | 132 | should block waiting for a file descriptor to become ready. |
40df3d00 MK |
133 | The call will block until either: |
134 | .IP * 3 | |
135 | a file descriptor becomes ready; | |
136 | .IP * | |
137 | the call is interrupted by a signal handler; or | |
138 | .IP * | |
216b9e61 | 139 | the timeout expires. |
40df3d00 MK |
140 | .PP |
141 | Note that the | |
142 | .I timeout | |
143 | interval will be rounded up to the system clock granularity, | |
19257d8f | 144 | and kernel scheduling delays mean that the blocking interval |
0d9101c4 | 145 | may overrun by a small amount. |
e755a587 MK |
146 | Specifying a negative value in |
147 | .I timeout | |
148 | means an infinite timeout. | |
77e74cf1 MK |
149 | Specifying a |
150 | .I timeout | |
151 | of zero causes | |
152 | .BR poll () | |
01d8b73f | 153 | to return immediately, even if no file descriptors are ready. |
efeece04 | 154 | .PP |
23cb3cb5 MK |
155 | The bits that may be set/returned in |
156 | .I events | |
157 | and | |
158 | .I revents | |
c84371c6 | 159 | are defined in \fI<poll.h>\fP: |
23cb3cb5 MK |
160 | .TP |
161 | .B POLLIN | |
162 | There is data to read. | |
163 | .TP | |
164 | .B POLLPRI | |
e629dd78 MK |
165 | There is some exceptional condition on the file descriptor. |
166 | Possibilities include: | |
167 | .RS | |
168 | .IP * 3 | |
169 | There is out-of-band data on a TCP socket (see | |
170 | .BR tcp (7)). | |
171 | .IP * | |
172 | A pseudoterminal master in packet mode has seen a state change on the slave | |
173 | (see | |
174 | .BR ioctl_tty (2)). | |
175 | .IP * | |
176 | A | |
177 | .I cgroup.events | |
178 | file has been modified (see | |
179 | .BR cgroups (7)). | |
180 | .RE | |
23cb3cb5 MK |
181 | .TP |
182 | .B POLLOUT | |
d2e7d1bb RR |
183 | Writing is now possible, though a write larger that the available space |
184 | in a socket or pipe will still block (unless | |
185 | .B O_NONBLOCK | |
186 | is set). | |
23cb3cb5 MK |
187 | .TP |
188 | .BR POLLRDHUP " (since Linux 2.6.17)" | |
c13182ef | 189 | Stream socket peer closed connection, |
23cb3cb5 | 190 | or shut down writing half of connection. |
c13182ef | 191 | The |
23cb3cb5 | 192 | .B _GNU_SOURCE |
e417acb0 MK |
193 | feature test macro must be defined |
194 | (before including | |
195 | .I any | |
196 | header files) | |
197 | in order to obtain this definition. | |
23cb3cb5 MK |
198 | .TP |
199 | .B POLLERR | |
b09322c4 MK |
200 | Error condition (only returned in |
201 | .IR revents ; | |
202 | ignored in | |
203 | .IR events ). | |
b3da9249 MK |
204 | This bit is also set for a file descriptor referring |
205 | to the write end of a pipe when the read end has been closed. | |
23cb3cb5 MK |
206 | .TP |
207 | .B POLLHUP | |
b09322c4 MK |
208 | Hang up (only returned in |
209 | .IR revents ; | |
210 | ignored in | |
211 | .IR events ). | |
7e8924ba MK |
212 | Note that when reading from a channel such as a pipe or a stream socket, |
213 | this event merely indicates that the peer closed its end of the channel. | |
214 | Subsequent reads from the channel will return 0 (end of file) | |
215 | only after all outstanding data in the channel has been consumed. | |
23cb3cb5 MK |
216 | .TP |
217 | .B POLLNVAL | |
c13182ef | 218 | Invalid request: |
23cb3cb5 | 219 | .I fd |
b09322c4 MK |
220 | not open (only returned in |
221 | .IR revents ; | |
222 | ignored in | |
223 | .IR events ). | |
23cb3cb5 | 224 | .PP |
c13182ef | 225 | When compiling with |
23cb3cb5 | 226 | .B _XOPEN_SOURCE |
c13182ef | 227 | defined, one also has the following, |
23cb3cb5 | 228 | which convey no further information beyond the bits listed above: |
23cb3cb5 MK |
229 | .TP |
230 | .B POLLRDNORM | |
231 | Equivalent to | |
232 | .BR POLLIN . | |
233 | .TP | |
234 | .B POLLRDBAND | |
235 | Priority band data can be read (generally unused on Linux). | |
236 | .\" POLLRDBAND is used in the DECnet protocol. | |
237 | .TP | |
238 | .B POLLWRNORM | |
239 | Equivalent to | |
240 | .BR POLLOUT . | |
241 | .TP | |
242 | .B POLLWRBAND | |
243 | Priority data may be written. | |
23cb3cb5 | 244 | .PP |
c13182ef | 245 | Linux also knows about, but does not use |
23cb3cb5 | 246 | .BR POLLMSG . |
e755a587 | 247 | .SS ppoll() |
c13182ef | 248 | The relationship between |
e755a587 | 249 | .BR poll () |
c13182ef MK |
250 | and |
251 | .BR ppoll () | |
e755a587 | 252 | is analogous to the relationship between |
0bfa087b | 253 | .BR select (2) |
e755a587 | 254 | and |
0bfa087b | 255 | .BR pselect (2): |
e755a587 | 256 | like |
0bfa087b | 257 | .BR pselect (2), |
e755a587 MK |
258 | .BR ppoll () |
259 | allows an application to safely wait until either a file descriptor | |
260 | becomes ready or until a signal is caught. | |
261 | .PP | |
b8c599cb | 262 | Other than the difference in the precision of the |
39c05c26 YK |
263 | .I timeout |
264 | argument, the following | |
e755a587 MK |
265 | .BR ppoll () |
266 | call: | |
408731d4 MK |
267 | .PP |
268 | .in +4n | |
269 | .EX | |
270 | ready = ppoll(&fds, nfds, tmo_p, &sigmask); | |
271 | .EE | |
272 | .in | |
273 | .PP | |
e755a587 MK |
274 | is equivalent to |
275 | .I atomically | |
276 | executing the following calls: | |
408731d4 MK |
277 | .PP |
278 | .in +4n | |
279 | .EX | |
280 | sigset_t origmask; | |
281 | int timeout; | |
e755a587 | 282 | |
408731d4 MK |
283 | timeout = (tmo_p == NULL) ? \-1 : |
284 | (tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000); | |
285 | pthread_sigmask(SIG_SETMASK, &sigmask, &origmask); | |
286 | ready = poll(&fds, nfds, timeout); | |
287 | pthread_sigmask(SIG_SETMASK, &origmask, NULL); | |
288 | .EE | |
289 | .in | |
e755a587 MK |
290 | .PP |
291 | See the description of | |
292 | .BR pselect (2) | |
293 | for an explanation of why | |
294 | .BR ppoll () | |
295 | is necessary. | |
efeece04 | 296 | .PP |
3ee89512 MK |
297 | If the |
298 | .I sigmask | |
299 | argument is specified as NULL, then | |
300 | no signal mask manipulation is performed | |
301 | (and thus | |
302 | .BR ppoll () | |
303 | differs from | |
304 | .BR poll () | |
79fd50e6 YK |
305 | only in the precision of the |
306 | .I timeout | |
307 | argument). | |
efeece04 | 308 | .PP |
e755a587 | 309 | The |
0bf502fc | 310 | .I tmo_p |
c13182ef | 311 | argument specifies an upper limit on the amount of time that |
e755a587 MK |
312 | .BR ppoll () |
313 | will block. | |
314 | This argument is a pointer to a structure of the following form: | |
e646a1ba | 315 | .PP |
088a639b | 316 | .in +4n |
e646a1ba | 317 | .EX |
e755a587 MK |
318 | struct timespec { |
319 | long tv_sec; /* seconds */ | |
320 | long tv_nsec; /* nanoseconds */ | |
321 | }; | |
b8302363 | 322 | .EE |
a08ea57c | 323 | .in |
efeece04 | 324 | .PP |
e755a587 | 325 | If |
0bf502fc | 326 | .I tmo_p |
c13182ef | 327 | is specified as NULL, then |
e755a587 MK |
328 | .BR ppoll () |
329 | can block indefinitely. | |
47297adb | 330 | .SH RETURN VALUE |
96296ef0 | 331 | On success, a positive number is returned; this is |
c7094399 | 332 | the number of structures which have nonzero |
fea681da MK |
333 | .I revents |
334 | fields (in other words, those descriptors with events or errors reported). | |
335 | A value of 0 indicates that the call timed out and no file | |
c13182ef MK |
336 | descriptors were ready. |
337 | On error, \-1 is returned, and | |
fea681da MK |
338 | .I errno |
339 | is set appropriately. | |
340 | .SH ERRORS | |
341 | .TP | |
fea681da MK |
342 | .B EFAULT |
343 | The array given as argument was not contained in the calling program's | |
344 | address space. | |
345 | .TP | |
346 | .B EINTR | |
01538d0d MK |
347 | A signal occurred before any requested event; see |
348 | .BR signal (7). | |
fea681da MK |
349 | .TP |
350 | .B EINVAL | |
351 | The | |
352 | .I nfds | |
682edefb MK |
353 | value exceeds the |
354 | .B RLIMIT_NOFILE | |
355 | value. | |
fea681da MK |
356 | .TP |
357 | .B ENOMEM | |
358 | There was no space to allocate file descriptor tables. | |
e755a587 | 359 | .SH VERSIONS |
b5cc2ffb | 360 | The |
c13182ef | 361 | .BR poll () |
b5cc2ffb | 362 | system call was introduced in Linux 2.1.23. |
6f0b2c8c MK |
363 | On older kernels that lack this system call, |
364 | .\" library call was introduced in libc 5.4.28 | |
365 | the glibc (and the old Linux libc) | |
1e321034 | 366 | .BR poll () |
6f0b2c8c MK |
367 | wrapper function provides emulation using |
368 | .BR select (2). | |
efeece04 | 369 | .PP |
e755a587 MK |
370 | The |
371 | .BR ppoll () | |
372 | system call was added to Linux in kernel 2.6.16. | |
373 | The | |
374 | .BR ppoll () | |
375 | library call was added in glibc 2.4. | |
47297adb | 376 | .SH CONFORMING TO |
a1d5f77c | 377 | .BR poll () |
a2dcc3bb | 378 | conforms to POSIX.1-2001 and POSIX.1-2008. |
a1d5f77c | 379 | .BR ppoll () |
8382f16d | 380 | is Linux-specific. |
a1d5f77c | 381 | .\" NetBSD 3.0 has a pollts() which is like Linux ppoll(). |
e755a587 | 382 | .SH NOTES |
15e68be6 MK |
383 | The operation of |
384 | .BR poll () | |
385 | and | |
386 | .BR ppoll () | |
387 | is not affected by the | |
388 | .BR O_NONBLOCK | |
389 | flag. | |
390 | .PP | |
f1463757 MK |
391 | On some other UNIX systems, |
392 | .\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett | |
393 | .BR poll () | |
394 | can fail with the error | |
395 | .B EAGAIN | |
396 | if the system fails to allocate kernel-internal resources, rather than | |
397 | .B ENOMEM | |
398 | as Linux does. | |
399 | POSIX permits this behavior. | |
400 | Portable programs may wish to check for | |
401 | .B EAGAIN | |
402 | and loop, just as with | |
403 | .BR EINTR . | |
efeece04 | 404 | .PP |
c8f2dd47 | 405 | Some implementations define the nonstandard constant |
c1164764 MK |
406 | .B INFTIM |
407 | with the value \-1 for use as a | |
b8c599cb MK |
408 | .IR timeout |
409 | for | |
ba2e3e9a | 410 | .BR poll (). |
c1164764 | 411 | This constant is not provided in glibc. |
efeece04 | 412 | .PP |
f33050d6 MK |
413 | For a discussion of what may happen if a file descriptor being monitored by |
414 | .BR poll () | |
415 | is closed in another thread, see | |
416 | .BR select (2). | |
0722a578 | 417 | .SS C library/kernel differences |
4fb31341 MK |
418 | The Linux |
419 | .BR ppoll () | |
420 | system call modifies its | |
0bf502fc | 421 | .I tmo_p |
4fb31341 | 422 | argument. |
d9bfdb9c | 423 | However, the glibc wrapper function hides this behavior |
4fb31341 MK |
424 | by using a local variable for the timeout argument that |
425 | is passed to the system call. | |
426 | Thus, the glibc | |
427 | .BR ppoll () | |
428 | function does not modify its | |
0bf502fc | 429 | .I tmo_p |
4fb31341 | 430 | argument. |
efeece04 | 431 | .PP |
361ec688 MK |
432 | The raw |
433 | .BR ppoll () | |
434 | system call has a fifth argument, | |
435 | .IR "size_t sigsetsize" , | |
436 | which specifies the size in bytes of the | |
437 | .IR sigmask | |
438 | argument. | |
439 | The glibc | |
440 | .BR ppoll () | |
441 | wrapper function specifies this argument as a fixed value | |
442 | (equal to | |
f8dcca84 MK |
443 | .IR sizeof(kernel_sigset_t) ). |
444 | See | |
445 | .BR sigprocmask (2) | |
f25ea51b N |
446 | for a discussion on the differences between the kernel and the libc |
447 | notion of the sigset. | |
a1d5f77c MK |
448 | .SH BUGS |
449 | See the discussion of spurious readiness notifications under the | |
450 | BUGS section of | |
451 | .BR select (2). | |
47297adb | 452 | .SH SEE ALSO |
d806bc05 | 453 | .BR restart_syscall (2), |
fea681da | 454 | .BR select (2), |
50e5322c | 455 | .BR select_tut (2), |
9755c034 | 456 | .BR epoll (7), |
1d7c4d16 | 457 | .BR time (7) |