1 '\" te
2 .\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH POLL 7D "April 9, 2016"
7 .SH NAME
8 poll \- driver for fast poll on many file descriptors
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB#include <sys/devpoll.h>
13 int fd = open("/dev/poll", O_RDWR);
14 ssize_t n = write(int fd, struct pollfd buf[], int bufsize);
15 int n = ioctl(int fd, DP_POLL, struct dvpoll* arg);
16 int n = ioctl(int fd, DP_ISPOLLED, struct pollfd* pfd);\fR
17 .fi
18
19 .SH PARAMETERS
20 .ne 2
21 .na
22 \fB\fIfd\fR \fR
23 .ad
24 .RS 12n
25 Open file descriptor that refers to the \fB/dev/poll\fR driver.
26 .RE
27
28 .sp
29 .ne 2
30 .na
54
55 .sp
56 .ne 2
57 .na
58 \fB\fIarg\fR \fR
59 .ad
60 .RS 12n
61 Pointer to \fBpollcall\fR structure.
62 .RE
63
64 .sp
65 .ne 2
66 .na
67 \fB\fIpfd\fR \fR
68 .ad
69 .RS 12n
70 Pointer to \fBpollfd\fR structure.
71 .RE
72
73 .SH DESCRIPTION
74 .LP
75 The \fB/dev/poll\fR driver is a special driver that enables you to monitor
76 multiple sets of polled file descriptors. By using the \fB/dev/poll\fR
77 driver, you can efficiently poll large numbers of file descriptors. Access to
78 the \fB/dev/poll\fR driver is provided through \fBopen\fR(2), \fBwrite\fR(2),
79 and \fBioctl(2)\fR system calls.
80 .sp
81 .LP
82 Writing an array of \fBpollfd\fR struct to the \fB/dev/poll\fR driver has the
83 effect of adding these file descriptors to the monitored \fBpoll\fR file
84 descriptor set represented by the \fIfd\fR. To monitor multiple file
85 descriptor sets, open the \fB/dev/poll\fR driver multiple times. Each \fBfd\fR
86 corresponds to one set. For each \fBpollfd\fR struct entry (defined in
87 \fBsys/poll.h\fR):
88 .sp
89 .in +2
90 .nf
91 struct pollfd {
92 int fd;
93 short events;
94 short revents;
123 .fi
124 .in -2
125
126 .sp
127 .LP
128 The \fBdp_fds\fR points to a buffer that holds an array of returned
129 \fBpollfd\fR structures. The \fBdp_nfds\fR field specifies the size of the
130 buffer in terms of the number of \fBpollfd\fR entries it contains. The
131 \fBdp_nfds\fR field also indicates the maximum number of file descriptors from
132 which poll information can be obtained. If there is no interested \fBevents\fR
133 on any of the polled file descriptors, the \fBDP_POLL\fR ioctl call will wait
134 \fBdp_timeout\fR milliseconds before returning. If \fBdp_timeout\fR is
135 \fB0\fR, the ioctl call returns immediately. If \fBdp_timeout\fR is \fB-1\fR,
136 the call blocks until an interested \fBpoll\fR \fBevents\fR is available or the
137 call is interrupted. Upon return, if the ioctl call has failed, \fB-1\fR is
138 returned. The memory content pointed by \fBdp_fds\fR is not modified. A return
139 value \fB0\fR means the ioctl is timed out. In this case, the memory content
140 pointed by \fBdp_fds\fR is not modified. If the call is successful, it returns
141 the number of valid \fBpollfd\fR entries in the array pointed by \fBdp_fds\fR;
142 the contents of the rest of the buffer is undefined. For each valid
143 \fBpollfd\fR entry, the \fBfd\fR field indicates the file desciptor on which
144 the polled \fBevents\fR happened. The \fBevents\fR field is the user specified
145 \fBpoll\fR \fBevents\fR. The \fBrevents\fR field contains the \fBevents\fR
146 occurred. \fB-1\fR is returned if the call fails.
147 .sp
148 .LP
149 \fBDP_ISPOLLED\fR ioctl allows you to query if a file descriptor is already in
150 the monitored set represented by \fBfd\fR. The \fBfd\fR field of the
151 \fBpollfd\fR structure indicates the file descriptor of interest. The
152 \fBDP_ISPOLLED\fR ioctl returns \fB1\fR if the file descriptor is in the set.
153 The \fBevents\fR field contains \fB0\fR. The \fBrevents\fR field contains the
154 currently polled \fBevents\fR. The ioctl returns \fB0\fR if the file
155 descriptor is not in the set. The \fBpollfd\fR structure pointed by \fIpfd\fR
156 is not modified. The ioctl returns a \fB-1\fR if the call fails.
157 .SH EXAMPLES
158 .LP
159 The following example shows how \fB/dev/poll\fR may be used.
160 .sp
161 .in +2
162 .nf
163 {
164 ...
165 /*
166 * open the driver
167 */
168 if ((wfd = open("/dev/poll", O_RDWR)) < 0) {
169 exit(-1);
170 }
171 pollfd = (struct pollfd* )malloc(sizeof(struct pollfd) * MAXBUF);
172 if (pollfd == NULL) {
173 close(wfd);
174 exit(-1);
175 }
176 /*
177 * initialize buffer
178 */
318 .RS 11n
319 The request or \fIarg\fR parameter is not valid for this device, or field of
320 the dvpoll struct pointed by \fIarg\fR is not valid (for example, when using
321 write/pwrite dp_nfds is greater than {OPEN_MAX}, or when using the DPPOLL ioctl
322 dp_nfds is greater than or equal to {OPEN_MAX}}.
323 .RE
324
325 .sp
326 .ne 2
327 .na
328 \fB\fBENXIO\fR \fR
329 .ad
330 .RS 11n
331 The \fBO_NONBLOCK\fR flag is set, the named file is a FIFO, the \fBO_WRONLY\fR
332 flag is set, and no process has the file open for reading; or the named file is
333 a character special or block special file and the device associated with this
334 special file does not exist.
335 .RE
336
337 .SH ATTRIBUTES
338 .LP
339 See \fBattributes\fR(5) for a description of the following attributes:
340 .sp
341
342 .sp
343 .TS
344 box;
345 l l
346 l l .
347 ATTRIBUTE TYPE ATTRIBUTE VALUE
348 Architecture SPARC, x86
349 Interface Stability Obsolete
350 MT-Level Safe
351 .TE
352
353 .SH SEE ALSO
354 .LP
355 \fBopen\fR(2), \fBpoll\fR(2), \fBwrite\fR(2), \fBattributes\fR(5)
356 .SH NOTES
357 .LP
358 The \fB/dev/poll\fR API is particularly beneficial to applications that poll a
359 large number of file descriptors repeatedly. Applications will exhibit the
360 best performance gain if the polled file descriptor list rarely change.
361 .sp
362 .LP
363 When using the \fB/dev/poll\fR driver, you should remove a closed file
364 descriptor from a monitored poll set. Failure to do so may result in a
365 \fBPOLLNVAL\fR \fBrevents\fR being returned for the closed file descriptor.
366 When a file descriptor is closed but not removed from the monitored set, and is
367 reused in subsequent open of a different device, you will be polling the device
368 associated with the reused file descriptor. In a multithreaded application,
369 careful coordination among threads doing close and \fBDP_POLL\fR ioctl is
370 recommended for consistent results.
371 .sp
372 .LP
373 The \fB/dev/poll\fR driver caches a list of polled file descriptors, which are
374 specific to a process. Therefore, the \fB/dev/poll\fR file descriptor of a
375 process will be inherited by its child process, just like any other file
376 descriptors. But the child process will have very limited access through this
377 inherited \fB/dev/poll\fR file descriptor. Any attempt to write or do ioctl by
|
1 '\" te
2 .\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH POLL 7D "January 10, 2020"
7 .SH NAME
8 poll \- driver for fast poll on many file descriptors
9 .SH SYNOPSIS
10 .nf
11 \fB#include <sys/devpoll.h>
12 int fd = open("/dev/poll", O_RDWR);
13 ssize_t n = write(int fd, struct pollfd buf[], int bufsize);
14 int n = ioctl(int fd, DP_POLL, struct dvpoll* arg);
15 int n = ioctl(int fd, DP_ISPOLLED, struct pollfd* pfd);\fR
16 .fi
17
18 .SH PARAMETERS
19 .ne 2
20 .na
21 \fB\fIfd\fR \fR
22 .ad
23 .RS 12n
24 Open file descriptor that refers to the \fB/dev/poll\fR driver.
25 .RE
26
27 .sp
28 .ne 2
29 .na
53
54 .sp
55 .ne 2
56 .na
57 \fB\fIarg\fR \fR
58 .ad
59 .RS 12n
60 Pointer to \fBpollcall\fR structure.
61 .RE
62
63 .sp
64 .ne 2
65 .na
66 \fB\fIpfd\fR \fR
67 .ad
68 .RS 12n
69 Pointer to \fBpollfd\fR structure.
70 .RE
71
72 .SH DESCRIPTION
73 The \fB/dev/poll\fR driver is a special driver that enables you to monitor
74 multiple sets of polled file descriptors. By using the \fB/dev/poll\fR
75 driver, you can efficiently poll large numbers of file descriptors. Access to
76 the \fB/dev/poll\fR driver is provided through \fBopen\fR(2), \fBwrite\fR(2),
77 and \fBioctl(2)\fR system calls.
78 .sp
79 .LP
80 Writing an array of \fBpollfd\fR struct to the \fB/dev/poll\fR driver has the
81 effect of adding these file descriptors to the monitored \fBpoll\fR file
82 descriptor set represented by the \fIfd\fR. To monitor multiple file
83 descriptor sets, open the \fB/dev/poll\fR driver multiple times. Each \fBfd\fR
84 corresponds to one set. For each \fBpollfd\fR struct entry (defined in
85 \fBsys/poll.h\fR):
86 .sp
87 .in +2
88 .nf
89 struct pollfd {
90 int fd;
91 short events;
92 short revents;
121 .fi
122 .in -2
123
124 .sp
125 .LP
126 The \fBdp_fds\fR points to a buffer that holds an array of returned
127 \fBpollfd\fR structures. The \fBdp_nfds\fR field specifies the size of the
128 buffer in terms of the number of \fBpollfd\fR entries it contains. The
129 \fBdp_nfds\fR field also indicates the maximum number of file descriptors from
130 which poll information can be obtained. If there is no interested \fBevents\fR
131 on any of the polled file descriptors, the \fBDP_POLL\fR ioctl call will wait
132 \fBdp_timeout\fR milliseconds before returning. If \fBdp_timeout\fR is
133 \fB0\fR, the ioctl call returns immediately. If \fBdp_timeout\fR is \fB-1\fR,
134 the call blocks until an interested \fBpoll\fR \fBevents\fR is available or the
135 call is interrupted. Upon return, if the ioctl call has failed, \fB-1\fR is
136 returned. The memory content pointed by \fBdp_fds\fR is not modified. A return
137 value \fB0\fR means the ioctl is timed out. In this case, the memory content
138 pointed by \fBdp_fds\fR is not modified. If the call is successful, it returns
139 the number of valid \fBpollfd\fR entries in the array pointed by \fBdp_fds\fR;
140 the contents of the rest of the buffer is undefined. For each valid
141 \fBpollfd\fR entry, the \fBfd\fR field indicates the file descriptor on which
142 the polled \fBevents\fR happened. The \fBevents\fR field is the user specified
143 \fBpoll\fR \fBevents\fR. The \fBrevents\fR field contains the \fBevents\fR
144 occurred. \fB-1\fR is returned if the call fails.
145 .sp
146 .LP
147 \fBDP_ISPOLLED\fR ioctl allows you to query if a file descriptor is already in
148 the monitored set represented by \fBfd\fR. The \fBfd\fR field of the
149 \fBpollfd\fR structure indicates the file descriptor of interest. The
150 \fBDP_ISPOLLED\fR ioctl returns \fB1\fR if the file descriptor is in the set.
151 The \fBevents\fR field contains \fB0\fR. The \fBrevents\fR field contains the
152 currently polled \fBevents\fR. The ioctl returns \fB0\fR if the file
153 descriptor is not in the set. The \fBpollfd\fR structure pointed by \fIpfd\fR
154 is not modified. The ioctl returns a \fB-1\fR if the call fails.
155 .SH EXAMPLES
156 The following example shows how \fB/dev/poll\fR may be used.
157 .sp
158 .in +2
159 .nf
160 {
161 ...
162 /*
163 * open the driver
164 */
165 if ((wfd = open("/dev/poll", O_RDWR)) < 0) {
166 exit(-1);
167 }
168 pollfd = (struct pollfd* )malloc(sizeof(struct pollfd) * MAXBUF);
169 if (pollfd == NULL) {
170 close(wfd);
171 exit(-1);
172 }
173 /*
174 * initialize buffer
175 */
315 .RS 11n
316 The request or \fIarg\fR parameter is not valid for this device, or field of
317 the dvpoll struct pointed by \fIarg\fR is not valid (for example, when using
318 write/pwrite dp_nfds is greater than {OPEN_MAX}, or when using the DPPOLL ioctl
319 dp_nfds is greater than or equal to {OPEN_MAX}}.
320 .RE
321
322 .sp
323 .ne 2
324 .na
325 \fB\fBENXIO\fR \fR
326 .ad
327 .RS 11n
328 The \fBO_NONBLOCK\fR flag is set, the named file is a FIFO, the \fBO_WRONLY\fR
329 flag is set, and no process has the file open for reading; or the named file is
330 a character special or block special file and the device associated with this
331 special file does not exist.
332 .RE
333
334 .SH ATTRIBUTES
335 See \fBattributes\fR(5) for a description of the following attributes:
336 .sp
337
338 .sp
339 .TS
340 box;
341 l l
342 l l .
343 ATTRIBUTE TYPE ATTRIBUTE VALUE
344 Architecture SPARC, x86
345 Interface Stability Obsolete
346 MT-Level Safe
347 .TE
348
349 .SH SEE ALSO
350 \fBopen\fR(2), \fBpoll\fR(2), \fBwrite\fR(2), \fBattributes\fR(5)
351 .SH NOTES
352 The \fB/dev/poll\fR API is particularly beneficial to applications that poll a
353 large number of file descriptors repeatedly. Applications will exhibit the
354 best performance gain if the polled file descriptor list rarely change.
355 .sp
356 .LP
357 When using the \fB/dev/poll\fR driver, you should remove a closed file
358 descriptor from a monitored poll set. Failure to do so may result in a
359 \fBPOLLNVAL\fR \fBrevents\fR being returned for the closed file descriptor.
360 When a file descriptor is closed but not removed from the monitored set, and is
361 reused in subsequent open of a different device, you will be polling the device
362 associated with the reused file descriptor. In a multithreaded application,
363 careful coordination among threads doing close and \fBDP_POLL\fR ioctl is
364 recommended for consistent results.
365 .sp
366 .LP
367 The \fB/dev/poll\fR driver caches a list of polled file descriptors, which are
368 specific to a process. Therefore, the \fB/dev/poll\fR file descriptor of a
369 process will be inherited by its child process, just like any other file
370 descriptors. But the child process will have very limited access through this
371 inherited \fB/dev/poll\fR file descriptor. Any attempt to write or do ioctl by
|