1POLL(2) Linux Programmer's Manual POLL(2)
2
3
4
6 poll, ppoll - wait for some event on a file descriptor
7
9 #include <poll.h>
10
11 int poll(struct pollfd *fds, nfds_t nfds, int timeout);
12
13 #define _GNU_SOURCE /* See feature_test_macros(7) */
14 #include <poll.h>
15
16 int ppoll(struct pollfd *fds, nfds_t nfds,
17 const struct timespec *tmo_p, const sigset_t *sigmask);
18
20 poll() performs a similar task to select(2): it waits for one of a set
21 of file descriptors to become ready to perform I/O. The Linux-specific
22 epoll(7) API performs a similar task, but offers features beyond those
23 found in poll().
24
25 The set of file descriptors to be monitored is specified in the fds ar‐
26 gument, which is an array of structures of the following form:
27
28 struct pollfd {
29 int fd; /* file descriptor */
30 short events; /* requested events */
31 short revents; /* returned events */
32 };
33
34 The caller should specify the number of items in the fds array in nfds.
35
36 The field fd contains a file descriptor for an open file. If this
37 field is negative, then the corresponding events field is ignored and
38 the revents field returns zero. (This provides an easy way of ignoring
39 a file descriptor for a single poll() call: simply negate the fd field.
40 Note, however, that this technique can't be used to ignore file de‐
41 scriptor 0.)
42
43 The field events is an input parameter, a bit mask specifying the
44 events the application is interested in for the file descriptor fd.
45 This field may be specified as zero, in which case the only events that
46 can be returned in revents are POLLHUP, POLLERR, and POLLNVAL (see be‐
47 low).
48
49 The field revents is an output parameter, filled by the kernel with the
50 events that actually occurred. The bits returned in revents can in‐
51 clude any of those specified in events, or one of the values POLLERR,
52 POLLHUP, or POLLNVAL. (These three bits are meaningless in the events
53 field, and will be set in the revents field whenever the corresponding
54 condition is true.)
55
56 If none of the events requested (and no error) has occurred for any of
57 the file descriptors, then poll() blocks until one of the events oc‐
58 curs.
59
60 The timeout argument specifies the number of milliseconds that poll()
61 should block waiting for a file descriptor to become ready. The call
62 will block until either:
63
64 • a file descriptor becomes ready;
65
66 • the call is interrupted by a signal handler; or
67
68 • the timeout expires.
69
70 Note that the timeout interval will be rounded up to the system clock
71 granularity, and kernel scheduling delays mean that the blocking inter‐
72 val may overrun by a small amount. Specifying a negative value in
73 timeout means an infinite timeout. Specifying a timeout of zero causes
74 poll() to return immediately, even if no file descriptors are ready.
75
76 The bits that may be set/returned in events and revents are defined in
77 <poll.h>:
78
79 POLLIN There is data to read.
80
81 POLLPRI
82 There is some exceptional condition on the file descriptor.
83 Possibilities include:
84
85 • There is out-of-band data on a TCP socket (see tcp(7)).
86
87 • A pseudoterminal master in packet mode has seen a state change
88 on the slave (see ioctl_tty(2)).
89
90 • A cgroup.events file has been modified (see cgroups(7)).
91
92 POLLOUT
93 Writing is now possible, though a write larger than the avail‐
94 able space in a socket or pipe will still block (unless O_NON‐
95 BLOCK is set).
96
97 POLLRDHUP (since Linux 2.6.17)
98 Stream socket peer closed connection, or shut down writing half
99 of connection. The _GNU_SOURCE feature test macro must be de‐
100 fined (before including any header files) in order to obtain
101 this definition.
102
103 POLLERR
104 Error condition (only returned in revents; ignored in events).
105 This bit is also set for a file descriptor referring to the
106 write end of a pipe when the read end has been closed.
107
108 POLLHUP
109 Hang up (only returned in revents; ignored in events). Note
110 that when reading from a channel such as a pipe or a stream
111 socket, this event merely indicates that the peer closed its end
112 of the channel. Subsequent reads from the channel will return 0
113 (end of file) only after all outstanding data in the channel has
114 been consumed.
115
116 POLLNVAL
117 Invalid request: fd not open (only returned in revents; ignored
118 in events).
119
120 When compiling with _XOPEN_SOURCE defined, one also has the following,
121 which convey no further information beyond the bits listed above:
122
123 POLLRDNORM
124 Equivalent to POLLIN.
125
126 POLLRDBAND
127 Priority band data can be read (generally unused on Linux).
128
129 POLLWRNORM
130 Equivalent to POLLOUT.
131
132 POLLWRBAND
133 Priority data may be written.
134
135 Linux also knows about, but does not use POLLMSG.
136
137 ppoll()
138 The relationship between poll() and ppoll() is analogous to the rela‐
139 tionship between select(2) and pselect(2): like pselect(2), ppoll() al‐
140 lows an application to safely wait until either a file descriptor be‐
141 comes ready or until a signal is caught.
142
143 Other than the difference in the precision of the timeout argument, the
144 following ppoll() call:
145
146 ready = ppoll(&fds, nfds, tmo_p, &sigmask);
147
148 is nearly equivalent to atomically executing the following calls:
149
150 sigset_t origmask;
151 int timeout;
152
153 timeout = (tmo_p == NULL) ? -1 :
154 (tmo_p->tv_sec * 1000 + tmo_p->tv_nsec / 1000000);
155 pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
156 ready = poll(&fds, nfds, timeout);
157 pthread_sigmask(SIG_SETMASK, &origmask, NULL);
158
159 The above code segment is described as nearly equivalent because
160 whereas a negative timeout value for poll() is interpreted as an infi‐
161 nite timeout, a negative value expressed in *tmo_p results in an error
162 from ppoll().
163
164 See the description of pselect(2) for an explanation of why ppoll() is
165 necessary.
166
167 If the sigmask argument is specified as NULL, then no signal mask ma‐
168 nipulation is performed (and thus ppoll() differs from poll() only in
169 the precision of the timeout argument).
170
171 The tmo_p argument specifies an upper limit on the amount of time that
172 ppoll() will block. This argument is a pointer to a structure of the
173 following form:
174
175 struct timespec {
176 long tv_sec; /* seconds */
177 long tv_nsec; /* nanoseconds */
178 };
179
180 If tmo_p is specified as NULL, then ppoll() can block indefinitely.
181
183 On success, poll() returns a nonnegative value which is the number of
184 elements in the pollfds whose revents fields have been set to a nonzero
185 value (indicating an event or an error). A return value of zero indi‐
186 cates that the system call timed out before any file descriptors became
187 read.
188
189 On error, -1 is returned, and errno is set to indicate the error.
190
192 EFAULT fds points outside the process's accessible address space. The
193 array given as argument was not contained in the calling pro‐
194 gram's address space.
195
196 EINTR A signal occurred before any requested event; see signal(7).
197
198 EINVAL The nfds value exceeds the RLIMIT_NOFILE value.
199
200 EINVAL (ppoll()) The timeout value expressed in *ip is invalid (nega‐
201 tive).
202
203 ENOMEM Unable to allocate memory for kernel data structures.
204
206 The poll() system call was introduced in Linux 2.1.23. On older ker‐
207 nels that lack this system call, the glibc poll() wrapper function pro‐
208 vides emulation using select(2).
209
210 The ppoll() system call was added to Linux in kernel 2.6.16. The
211 ppoll() library call was added in glibc 2.4.
212
214 poll() conforms to POSIX.1-2001 and POSIX.1-2008. ppoll() is Linux-
215 specific.
216
218 The operation of poll() and ppoll() is not affected by the O_NONBLOCK
219 flag.
220
221 On some other UNIX systems, poll() can fail with the error EAGAIN if
222 the system fails to allocate kernel-internal resources, rather than
223 ENOMEM as Linux does. POSIX permits this behavior. Portable programs
224 may wish to check for EAGAIN and loop, just as with EINTR.
225
226 Some implementations define the nonstandard constant INFTIM with the
227 value -1 for use as a timeout for poll(). This constant is not pro‐
228 vided in glibc.
229
230 For a discussion of what may happen if a file descriptor being moni‐
231 tored by poll() is closed in another thread, see select(2).
232
233 C library/kernel differences
234 The Linux ppoll() system call modifies its tmo_p argument. However,
235 the glibc wrapper function hides this behavior by using a local vari‐
236 able for the timeout argument that is passed to the system call. Thus,
237 the glibc ppoll() function does not modify its tmo_p argument.
238
239 The raw ppoll() system call has a fifth argument, size_t sigsetsize,
240 which specifies the size in bytes of the sigmask argument. The glibc
241 ppoll() wrapper function specifies this argument as a fixed value
242 (equal to sizeof(kernel_sigset_t)). See sigprocmask(2) for a discus‐
243 sion on the differences between the kernel and the libc notion of the
244 sigset.
245
247 See the discussion of spurious readiness notifications under the BUGS
248 section of select(2).
249
251 The program below opens each of the files named in its command-line ar‐
252 guments and monitors the resulting file descriptors for readiness to
253 read (POLLIN). The program loops, repeatedly using poll() to monitor
254 the file descriptors, printing the number of ready file descriptors on
255 return. For each ready file descriptor, the program:
256
257 • displays the returned revents field in a human-readable form;
258
259 • if the file descriptor is readable, reads some data from it, and dis‐
260 plays that data on standard output; and
261
262 • if the file descriptors was not readable, but some other event oc‐
263 curred (presumably POLLHUP), closes the file descriptor.
264
265 Suppose we run the program in one terminal, asking it to open a FIFO:
266
267 $ mkfifo myfifo
268 $ ./poll_input myfifo
269
270 In a second terminal window, we then open the FIFO for writing, write
271 some data to it, and close the FIFO:
272
273 $ echo aaaaabbbbbccccc > myfifo
274
275 In the terminal where we are running the program, we would then see:
276
277 Opened "myfifo" on fd 3
278 About to poll()
279 Ready: 1
280 fd=3; events: POLLIN POLLHUP
281 read 10 bytes: aaaaabbbbb
282 About to poll()
283 Ready: 1
284 fd=3; events: POLLIN POLLHUP
285 read 6 bytes: ccccc
286
287 About to poll()
288 Ready: 1
289 fd=3; events: POLLHUP
290 closing fd 3
291 All file descriptors closed; bye
292
293 In the above output, we see that poll() returned three times:
294
295 • On the first return, the bits returned in the revents field were
296 POLLIN, indicating that the file descriptor is readable, and POLLHUP,
297 indicating that the other end of the FIFO has been closed. The pro‐
298 gram then consumed some of the available input.
299
300 • The second return from poll() also indicated POLLIN and POLLHUP; the
301 program then consumed the last of the available input.
302
303 • On the final return, poll() indicated only POLLHUP on the FIFO, at
304 which point the file descriptor was closed and the program termi‐
305 nated.
306
307 Program source
308
309 /* poll_input.c
310
311 Licensed under GNU General Public License v2 or later.
312 */
313 #include <poll.h>
314 #include <fcntl.h>
315 #include <sys/types.h>
316 #include <stdio.h>
317 #include <stdlib.h>
318 #include <unistd.h>
319
320 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
321 } while (0)
322
323 int
324 main(int argc, char *argv[])
325 {
326 int nfds, num_open_fds;
327 struct pollfd *pfds;
328
329 if (argc < 2) {
330 fprintf(stderr, "Usage: %s file...\n", argv[0]);
331 exit(EXIT_FAILURE);
332 }
333
334 num_open_fds = nfds = argc - 1;
335 pfds = calloc(nfds, sizeof(struct pollfd));
336 if (pfds == NULL)
337 errExit("malloc");
338
339 /* Open each file on command line, and add it 'pfds' array. */
340
341 for (int j = 0; j < nfds; j++) {
342 pfds[j].fd = open(argv[j + 1], O_RDONLY);
343 if (pfds[j].fd == -1)
344 errExit("open");
345
346 printf("Opened \"%s\" on fd %d\n", argv[j + 1], pfds[j].fd);
347
348 pfds[j].events = POLLIN;
349 }
350
351 /* Keep calling poll() as long as at least one file descriptor is
352 open. */
353
354 while (num_open_fds > 0) {
355 int ready;
356
357 printf("About to poll()\n");
358 ready = poll(pfds, nfds, -1);
359 if (ready == -1)
360 errExit("poll");
361
362 printf("Ready: %d\n", ready);
363
364 /* Deal with array returned by poll(). */
365
366 for (int j = 0; j < nfds; j++) {
367 char buf[10];
368
369 if (pfds[j].revents != 0) {
370 printf(" fd=%d; events: %s%s%s\n", pfds[j].fd,
371 (pfds[j].revents & POLLIN) ? "POLLIN " : "",
372 (pfds[j].revents & POLLHUP) ? "POLLHUP " : "",
373 (pfds[j].revents & POLLERR) ? "POLLERR " : "");
374
375 if (pfds[j].revents & POLLIN) {
376 ssize_t s = read(pfds[j].fd, buf, sizeof(buf));
377 if (s == -1)
378 errExit("read");
379 printf(" read %zd bytes: %.*s\n",
380 s, (int) s, buf);
381 } else { /* POLLERR | POLLHUP */
382 printf(" closing fd %d\n", pfds[j].fd);
383 if (close(pfds[j].fd) == -1)
384 errExit("close");
385 num_open_fds--;
386 }
387 }
388 }
389 }
390
391 printf("All file descriptors closed; bye\n");
392 exit(EXIT_SUCCESS);
393 }
394
396 restart_syscall(2), select(2), select_tut(2), epoll(7), time(7)
397
399 This page is part of release 5.13 of the Linux man-pages project. A
400 description of the project, information about reporting bugs, and the
401 latest version of this page, can be found at
402 https://www.kernel.org/doc/man-pages/.
403
404
405
406Linux 2021-03-22 POLL(2)