1POLL(2) Linux Programmer's Manual POLL(2)
2
6 poll, ppoll - wait for some event on a file descriptor
7
9 #include <poll.h>
10 int poll(struct pollfd *fds, nfds_t nfds, int timeout);
12 #define _GNU_SOURCE
14 #include <poll.h>
15 int ppoll(struct pollfd *fds, nfds_t nfds,
17 const struct timespec *timeout_ts, 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.
22 The set of file descriptors to be monitored is specified in the fds
24 argument, which is an array of structures of the following form:
25 struct pollfd {
27 int fd; /* file descriptor */
28 short events; /* requested events */
29 short revents; /* returned events */
30 };
31 The caller should specify the number of items in the fds array in nfds.
33 The field fd contains a file descriptor for an open file.
35 The field events is an input parameter, a bit mask specifying the
37 events the application is interested in.
38 The field revents is an output parameter, filled by the kernel with the
40 events that actually occurred. The bits returned in revents can
41 include any of those specified in events, or one of the values POLLERR,
42 POLLHUP, or POLLNVAL. (These three bits are meaningless in the events
43 field, and will be set in the revents field whenever the corresponding
44 condition is true.)
45 If none of the events requested (and no error) has occurred for any of
47 the file descriptors, then poll() blocks until one of the events
48 occurs.
49 The timeout argument specifies an upper limit on the time for which
51 poll() will block, in milliseconds. Specifying a negative value in
52 timeout means an infinite timeout.
53 The bits that may be set/returned in events and revents are defined in
55 <poll.h>:
56 POLLIN There is data to read.
58 POLLPRI
60 There is urgent data to read (e.g., out-of-band data on
61 TCP socket; pseudo-terminal master in packet mode has
62 seen state change in slave).
63 POLLOUT
65 Writing now will not block.
66 POLLRDHUP (since Linux 2.6.17)
68 Stream socket peer closed connection, or shut down writ‐
69 ing half of connection. The _GNU_SOURCE feature test
70 macro must be defined in order to obtain this definition.
71 POLLERR
73 Error condition (output only).
74 POLLHUP
76 Hang up (output only).
77 POLLNVAL
79 Invalid request: fd not open (output only).
80 When compiling with _XOPEN_SOURCE defined, one also has the following,
82 which convey no further information beyond the bits listed above:
83 POLLRDNORM
85 Equivalent to POLLIN.
86 POLLRDBAND
88 Priority band data can be read (generally unused on
89 Linux).
90 POLLWRNORM
92 Equivalent to POLLOUT.
93 POLLWRBAND
95 Priority data may be written.
96 Linux also knows about, but does not use POLLMSG.
98 ppoll()
100 The relationship between poll() and ppoll() is analogous to the rela‐
101 tionship between select(2) and pselect(2): like pselect(2), ppoll()
102 allows an application to safely wait until either a file descriptor
103 becomes ready or until a signal is caught.
104 Other than the difference in the precision of the timeout argument, the
106 following ppoll() call:
107 ready = ppoll(&fds, nfds, timeout_ts, &sigmask);
109 is equivalent to atomically executing the following calls:
111 sigset_t origmask;
113 int timeout;
114 timeout = (timeout_ts == NULL) ? -1 :
116 (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
117 sigprocmask(SIG_SETMASK, &sigmask, &origmask);
118 ready = poll(&fds, nfds, timeout);
119 sigprocmask(SIG_SETMASK, &origmask, NULL);
120 See the description of pselect(2) for an explanation of why ppoll() is
122 necessary.
123 If the sigmask argument is specified as NULL, then no signal mask
125 manipulation is performed (and thus ppoll() differs from poll() only in
126 the precision of the timeout argument).
127 The timeout_ts argument specifies an upper limit on the amount of time
129 that ppoll() will block. This argument is a pointer to a structure of
130 the following form:
131 struct timespec {
133 long tv_sec; /* seconds */
134 long tv_nsec; /* nanoseconds */
135 };
136 If timeout_ts is specified as NULL, then ppoll() can block indefi‐
138 nitely.
139
141 On success, a positive number is returned; this is the number of struc‐
142 tures which have nonzero revents fields (in other words, those descrip‐
143 tors with events or errors reported). A value of 0 indicates that the
144 call timed out and no file descriptors were ready. On error, -1 is
145 returned, and errno is set appropriately.
146
148 EFAULT The array given as argument was not contained in the calling
149 program's address space.
150 EINTR A signal occurred before any requested event; see signal(7).
152 EINVAL The nfds value exceeds the RLIMIT_NOFILE value.
154 ENOMEM There was no space to allocate file descriptor tables.
156
158 The poll() system call was introduced in Linux 2.1.23. The poll()
159 library call was introduced in libc 5.4.28 (and provides emulation
160 using select(2) if your kernel does not have a poll() system call).
161 The ppoll() system call was added to Linux in kernel 2.6.16. The
163 ppoll() library call was added in glibc 2.4.
164
166 poll() conforms to POSIX.1-2001. ppoll() is Linux-specific.
167
169 Some implementations define the nonstandard constant INFTIM with the
170 value -1 for use as a timeout for poll().. This constant is not pro‐
171 vided in glibc.
172 Linux Notes
174 The Linux ppoll() system call modifies its timeout_ts argument. How‐
175 ever, the glibc wrapper function hides this behavior by using a local
176 variable for the timeout argument that is passed to the system call.
177 Thus, the glibc ppoll() function does not modify its timeout_ts argu‐
178 ment.
179
181 See the discussion of spurious readiness notifications under the BUGS
182 section of select(2).
183
185 select(2), select_tut(2), feature_test_macros(7), time(7)
186
188 This page is part of release 3.25 of the Linux man-pages project. A
189 description of the project, and information about reporting bugs, can
190 be found at http://www.kernel.org/doc/man-pages/.
191Linux 2010-06-12 POLL(2)