1poll(7d) Devices poll(7d)
2
6 poll - driver for fast poll on many file descriptors
7
9 #include <sys/devpoll.h>
10 int fd = open("/dev/poll", O_RDWR);
11 ssize_t n = write(int fd, struct pollfd buf[], int bufsize);
12 int n = ioctl(int fd, DP_POLL, struct dvpoll* arg);
13 int n = ioctl(int fd, DP_ISPOLLED, struct pollfd* pfd);
14
17 fd Open file descriptor that refers to the /dev/poll driver.
18 path /dev/poll
21 buf Array of pollfd structures.
24 bufsize Size of buf in bytes.
27 arg Pointer to pollcall structure.
30 pfd Pointer to pollfd structure.
33
36 Note -
37 The /dev/poll device, associated driver and corresponding manpages
39 may be removed in a future Solaris release. For similar functionality
40 in the event ports framework, see port_create(3C).
41 The /dev/poll driver is a special driver that enables you to monitor
44 multiple sets of polled file descriptors. By using the /dev/poll
45 driver, you can efficiently poll large numbers of file descriptors.
46 Access to the /dev/poll driver is provided through open(2), write(2),
47 and ioctl(2) system calls.
48 Writing an array of pollfd struct to the /dev/poll driver has the
51 effect of adding these file descriptors to the monitored poll file
52 descriptor set represented by the fd. To monitor multiple file
53 descriptor sets, open the /dev/poll driver multiple times. Each fd cor‐
54 responds to one set. For each pollfd struct entry (defined in
55 sys/poll.h):
56 struct pollfd {
58 int fd;
59 short events;
60 short revents;
61 }
62 The fd field specifies the file descriptor being polled. The events
66 field indicates the interested poll events on the file descriptor. If a
67 pollfd array contains multiple pollfd entries with the same fd field,
68 the "events" field in each pollfd entry is OR'ed. A special POLLREMOVE
69 event in the events field of the pollfd structure removes the fd from
70 the monitored set. The revents field is not used. Write returns the
71 number of bytes written successfully or -1 when write fails.
72 The DP_POLL ioctl is used to retrieve returned poll events occured on
75 the polled file descriptors in the monitored set represented by fd.
76 arg is a pointer to the devpoll structures which are defined as fol‐
77 lows:
78 struct dvpoll {
80 struct pollfd* dp_fds;
81 int dp_nfds;
82 int dp_timeout;
83 }
84 The dp_fds points to a buffer that holds an array of returned pollfd
88 structures. The dp_nfds field specifies the size of the buffer in terms
89 of the number of pollfd entries it contains. The dp_nfds field also
90 indicates the maximum number of file descriptors from which poll infor‐
91 mation can be obtained. If there is no interested events on any of the
92 polled file descriptors, the DP_POLL ioctl call will wait dp_timeout
93 milliseconds before returning. If dp_timeout is 0, the ioctl call
94 returns immediately. If dp_timeout is -1, the call blocks until an
95 interested poll events is available or the call is interrupted. Upon
96 return, if the ioctl call has failed, -1 is returned. The memory con‐
97 tent pointed by dp_fds is not modified. A return value 0 means the
98 ioctl is timed out. In this case, the memory content pointed by dp_fds
99 is not modified. If the call is successful, it returns the number of
100 valid pollfd entries in the array pointed by dp_fds; the contents of
101 the rest of the buffer is undefined. For each valid pollfd entry, the
102 fd field indicates the file desciptor on which the polled events hap‐
103 pened. The events field is the user specified poll events. The revents
104 field contains the events occurred. -1 is returned if the call fails.
105 DP_ISPOLLED ioctl allows you to query if a file descriptor is already
108 in the monitored set represented by fd. The fd field of the pollfd
109 structure indicates the file descriptor of interest. The DP_ISPOLLED
110 ioctl returns 1 if the file descriptor is in the set. The events field
111 contains 0. The revents field contains the currently polled events.
112 The ioctl returns 0 if the file descriptor is not in the set. The
113 pollfd structure pointed by pfd is not modified. The ioctl returns a
114 -1 if the call fails.
115
117 The following example shows how /dev/poll may be used.
118 {
120 ...
121 /*
122 * open the driver
123 */
124 if ((wfd = open("/dev/poll", O_RDWR)) < 0) {
125 exit(-1);
126 }
127 pollfd = (struct pollfd* )malloc(sizeof(struct pollfd) * MAXBUF);
128 if (pollfd == NULL) {
129 close(wfd);
130 exit(-1);
131 }
132 /*
133 * initialize buffer
134 */
135 for (i = 0; i < MAXBUF; i++) {
136 pollfd[i].fd = fds[i];
137 pollfd[i].events = POLLIN;
138 pollfd[i].revents = 0;
139 }
140 if (write(wfd, &pollfd[0], sizeof(struct pollfd) * MAXBUF) !=
141 sizeof(struct pollfd) * MAXBUF) {
142 perror("failed to write all pollfds");
143 close (wfd);
144 free(pollfd);
145 exit(-1);
146 }
147 /*
148 * read from the devpoll driver
149 */
150 dopoll.dp_timeout = -1;
151 dopoll.dp_nfds = MAXBUF;
152 dopoll.dp_fds = pollfd;
153 result = ioctl(wfd, DP_POLL, &dopoll);
154 if (result < 0) {
155 perror("/dev/poll ioctl DP_POLL failed");
156 close (wfd);
157 free(pollfd);
158 exit(-1);
159 }
160 for (i = 0; i < result; i++) {
161 read(dopoll.dp_fds[i].fd, rbuf, STRLEN);
162 }
163 ...
164 }
165 The following example is part of a test program which shows how
169 DP_ISPOLLED() ioctl may be used.
170 {
172 ...
173 loopcnt = 0;
175 while (loopcnt < ITERATION) {
176 rn = random();
177 rn %= RANGE;
178 if (write(fds[rn], TESTSTRING, strlen(TESTSTRING)) !=
179 strlen(TESTSTRING)) {
180 perror("write to fifo failed.");
181 close (wfd);
182 free(pollfd);
183 error = 1;
184 goto out1;
185 }
186 dpfd.fd = fds[rn];
187 dpfd.events = 0;
188 dpfd.revents = 0;
189 result = ioctl(wfd, DP_ISPOLLED, &dpfd);
190 if (result < 0) {
191 perror("/dev/poll ioctl DP_ISPOLLED failed");
192 printf("errno = %d0, errno);
193 close (wfd);
194 free(pollfd);
195 error = 1;
196 goto out1;
197 }
198 if (result != 1) {
199 printf("DP_ISPOLLED returned incorrect result: %d.0,
200 result);
201 close (wfd);
202 free(pollfd);
203 error = 1;
204 goto out1;
205 }
206 if (dpfd.fd != fds[rn]) {
207 printf("DP_ISPOLLED returned wrong fd %d, expect %d0,
208 dpfd.fd, fds[rn]);
209 close (wfd);
210 free(pollfd);
211 error = 1;
212 goto out1;
213 }
214 if (dpfd.revents != POLLIN) {
215 printf("DP_ISPOLLED returned unexpected revents %d0,
216 dpfd.revents);
217 close (wfd);
218 free(pollfd);
219 error = 1;
220 goto out1;
221 }
222 if (read(dpfd.fd, rbuf, strlen(TESTSTRING)) !=
223 strlen(TESTSTRING)) {
224 perror("read from fifo failed");
225 close (wfd);
226 free(pollfd);
227 error = 1;
228 goto out1;
229 }
230 loopcnt++;
231 }
232
236 EACCES A process does not have permission to access the content
237 cached in /dev/poll.
238 EINTR A signal was caught during the execution of the ioctl(2)
241 function.
242 EFAULT The request argument requires a data transfer to or from a
245 buffer pointed to by arg, but arg points to an illegal
246 address.
247 EINVAL The request or arg parameter is not valid for this device,
250 or field of the dvpoll struct pointed by arg is not valid
251 (for example, when using write/pwrite dp_nfds is greater
252 than {OPEN_MAX}, or when using the DPPOLL ioctl dp_nfds is
253 greater than or equal to {OPEN_MAX}}.
254 ENXIO The O_NONBLOCK flag is set, the named file is a FIFO, the
257 O_WRONLY flag is set, and no process has the file open for
258 reading; or the named file is a character special or block
259 special file and the device associated with this special
260 file does not exist.
261
264 See attributes(5) for a description of the following attributes:
265 ┌────────────────────────────────────────────────────────────────┐
270 │ATTRIBUTE TYPE ATTRIBUTE VALUE │
271 │Architecture SPARC, x86 │
272 │Availability SUNWcar ( Solaris) │
273 │ SUNWcsr, SUNWcsu (Solaris on x86) │
274 │ SUNWhea (header files) │
275 │Interface Stability Obsolete │
276 │MT-Level Safe │
277 └────────────────────────────────────────────────────────────────┘
278
280 open(2), poll(2), write(2), attributes(5)
281
283 The /dev/poll API is particularly beneficial to applications that poll
284 a large number of file descriptors repeatedly. Applications will
285 exhibit the best performance gain if the polled file descriptor list
286 rarely change.
287 When using the /dev/poll driver, you should remove a closed file
290 descriptor from a monitored poll set. Failure to do so may result in a
291 POLLNVAL revents being returned for the closed file descriptor. When a
292 file descriptor is closed but not removed from the monitored set, and
293 is reused in subsequent open of a different device, you will be polling
294 the device associated with the reused file descriptor. In a multi‐
295 threaded application, careful coordination among threads doing close
296 and DP_POLL ioctl is recommended for consistent results.
297 The /dev/poll driver caches a list of polled file descriptors, which
300 are specific to a process. Therefore, the /dev/poll file descriptor
301 of a process will be inherited by its child process, just like any
302 other file descriptors. But the child process will have very limited
303 access through this inherited /dev/poll file descriptor. Any attempt to
304 write or do ioctl by the child process will result in an EACCES error.
305 The child process should close the inherited /dev/poll file descriptor
306 and open its own if desired.
307 The /dev/poll driver does not yet support polling. Polling on a
310 /dev/poll file descriptor will result in POLLERR being returned in the
311 revents field of pollfd structure.
312SunOS 5.11 28 Mar 2007 poll(7d)