| blob | c7ee6383344c9dcd2bc5b93e1259fc77a2c499a4 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
45 .\" Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved.
46 .\" Copyright (c) 2014, Joyent, Inc.
47 .\"
48 .TH POLL 2 "Aug 23, 2001"
49 .SH NAME
50 poll \- input/output multiplexing
51 .SH SYNOPSIS
52 .LP
53 .nf
54 #include <poll.h>
56 \fBint\fR \fBpoll\fR(\fBstruct pollfd\fR \fIfds[]\fR, \fBnfds_t\fR \fInfds\fR, \fBint\fR \fItimeout\fR);
58 \fBint\fR \fBppoll\fR(\fBstruct pollfd *restrict\fR \fIfds\fR, \fBnfds_t\fR \fInfds\fR,
59 \fBconst struct timespec *restrict\fR \fItsp\fR, \fBconst sigset_t *restrict\fR \fIsigmask\fR);
60 .fi
62 .SH DESCRIPTION
63 .LP
64 The \fBpoll()\fR and \fBppoll()\fR functions provides applications with a
65 mechanism for multiplexing input/output over a set of file descriptors. For
66 each member of the array pointed to by \fIfds\fR, \fBpoll()\fR and \fBppoll()\fR
67 examine the given file descriptor for the event(s) specified in \fIevents\fR.
68 The number of \fBpollfd\fR structures in the \fIfds\fR array is specified by
69 \fInfds\fR. The \fBpoll()\fR and \fBppoll()\fR functions identify those file
70 descriptors on which an application can read or write data, or on which certain
71 events have occurred.
72 .sp
73 .LP
74 The \fBppoll()\fR function behaves identically to \fBpoll()\fR, except as follows:
75 .RS +4
76 .TP
77 .ie t \(bu
78 .el o
79 For the \fBppoll\fR function, the timeout period is given in seconds and
80 nanoseconds in an argument of type \fBstruct timespec\fR, where as \fBpoll()\fR
81 takes a timeout in milliseconds in the form of an integer argument.
82 .RE
83 .RS +4
84 .TP
85 .ie t \(bu
86 .el o
87 The \fBppoll()\fR function takes an optional \fIsigmask\fR argument. When a
88 non-\fBNULL\fR pointer is passed, the calling threads signal mask is replaced by
89 the one specified in \fIsigset\fR before examining file descriptors, and
90 restored before returning.
91 .RE
92 .sp
93 .LP
94 The \fIfds\fR argument specifies the file descriptors to be examined and the
95 events of interest for each file descriptor. It is a pointer to an array with
96 one member for each open file descriptor of interest. The array's members are
97 \fBpollfd\fR structures, which contain the following members:
98 .sp
99 .in +2
100 .nf
101 int fd; /* file descriptor */
102 short events; /* requested events */
103 short revents; /* returned events */
104 .fi
105 .in -2
107 .sp
108 .LP
109 The \fBfd\fR member specifies an open file descriptor and the \fBevents\fR and
110 \fBrevents\fR members are bitmasks constructed by a logical \fBOR\fR operation
111 of any combination of the following event flags:
112 .sp
113 .ne 2
114 .na
115 \fB\fBPOLLIN\fR\fR
116 .ad
117 .RS 14n
118 Data other than high priority data may be read without blocking. For streams,
119 this flag is set in \fBrevents\fR even if the message is of zero length.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fBPOLLRDNORM\fR\fR
126 .ad
127 .RS 14n
128 Normal data (priority band equals 0) may be read without blocking. For streams,
129 this flag is set in \fBrevents\fR even if the message is of zero length.
130 .RE
132 .sp
133 .ne 2
134 .na
135 \fB\fBPOLLRDBAND\fR\fR
136 .ad
137 .RS 14n
138 Data from a non-zero priority band may be read without blocking. For streams,
139 this flag is set in \fBrevents\fR even if the message is of zero length.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fBPOLLPRI\fR\fR
146 .ad
147 .RS 14n
148 High priority data may be received without blocking. For streams, this flag is
149 set in \fBrevents\fR even if the message is of zero length.
150 .RE
152 .sp
153 .ne 2
154 .na
155 \fB\fBPOLLOUT\fR\fR
156 .ad
157 .RS 14n
158 Normal data (priority band equals 0) may be written without blocking.
159 .RE
161 .sp
162 .ne 2
163 .na
164 \fB\fBPOLLWRNORM\fR\fR
165 .ad
166 .RS 14n
167 The same as \fBPOLLOUT\fR.
168 .RE
170 .sp
171 .ne 2
172 .na
173 \fB\fBPOLLWRBAND\fR\fR
174 .ad
175 .RS 14n
176 Priority data (priority band > 0) may be written. This event only examines
177 bands that have been written to at least once.
178 .RE
180 .sp
181 .ne 2
182 .na
183 \fB\fBPOLLERR\fR\fR
184 .ad
185 .RS 14n
186 An error has occurred on the device or stream. This flag is only valid in the
187 \fBrevents\fR bitmask; it is not used in the \fBevents\fR member.
188 .RE
190 .sp
191 .ne 2
192 .na
193 \fB\fBPOLLHUP\fR\fR
194 .ad
195 .RS 14n
196 A hangup has occurred on the stream. This event and \fBPOLLOUT\fR are mutually
197 exclusive; a stream can never be writable if a hangup has occurred. However,
198 this event and \fBPOLLIN\fR, \fBPOLLRDNORM\fR, \fBPOLLRDBAND\fR, or
199 \fBPOLLPRI\fR are not mutually exclusive. This flag is only valid in the
200 \fBrevents\fR bitmask; it is not used in the \fBevents\fR member.
201 .RE
203 .sp
204 .ne 2
205 .na
206 \fB\fBPOLLNVAL\fR\fR
207 .ad
208 .RS 14n
209 The specified \fBfd\fR value does not belong to an open file. This flag is only
210 valid in the \fBrevents\fR member; it is not used in the \fBevents\fR member.
211 .RE
213 .sp
214 .LP
215 If the value \fBfd\fR is less than 0, \fBevents\fR is ignored and \fBrevents\fR
216 is set to 0 in that entry on return from \fBpoll()\fR and \fBppoll()\fR.
217 .sp
218 .LP
219 The results of the \fBpoll()\fR or \fBppoll()\fR query are stored in the
220 \fBrevents\fR member in the \fBpollfd\fR structure. Bits are set in the
221 \fBrevents\fR bitmask to indicate which of the requested events are true. If
222 none are true, none of the specified bits are set in \fBrevents\fR when either
223 the \fBpoll()\fR or \fBppoll()\fR call returns. The event flags \fBPOLLHUP\fR,
224 \fBPOLLERR\fR, and \fBPOLLNVAL\fR are always set in \fBrevents\fR if the
225 conditions they indicate are true; this occurs even though these flags were not
226 present in \fBevents\fR.
227 .sp
228 .LP
229 If none of the defined events have occurred on any selected file descriptor,
230 \fBpoll()\fR and \fBppoll()\fR wait at least \fItimeout\fR milliseconds for an
231 event to occur on any of the selected file descriptors. On a computer where
232 millisecond timing accuracy is not available, \fItimeout\fR is rounded up to the
233 nearest legal value available on that system. If the value \fItimeout\fR is 0,
234 \fBpoll()\fR returns immediately. If the value of \fItimeout\fR is \(mi1,
235 \fBpoll()\fR blocks until a requested event occurs or until the call is
236 interrupted. If the value of \fBtsp\fR is \fBNULL\fR, then \fBppoll()\fR blocks
237 until a requested event occurs or until the call is interrupted. The
238 \fBpoll()\fR and \fBppoll()\fR functions are not affected by the \fBO_NDELAY\fR
239 and \fBO_NONBLOCK\fR flags.
240 .sp
241 .LP
242 The \fBpoll()\fR and \fBppoll()\fR functions support regular files, terminal and
243 pseudo-terminal devices, streams-based files, FIFOs, pipes, and sockets. The
244 behavior of \fBpoll()\fR and \fBppoll()\fR on elements of \fIfds\fR that refer
245 to other types of file is unspecified.
246 .sp
247 .LP
248 A file descriptor for a socket that is listening for connections will indicate
249 that it is ready for reading, once connections are available. A file
250 descriptor for a socket that is connecting asynchronously will indicate that it
251 is ready for writing, once a connection has been established.
252 .sp
253 .LP
254 Regular files always \fBpoll()\fR and \fBppoll()\fR \fBTRUE\fR for reading and
255 writing.
256 .SH RETURN VALUES
257 .LP
258 Upon successful completion, a non-negative value is returned. A positive value
259 indicates the total number of file descriptors that has been selected (that is,
260 file descriptors for which the \fBrevents\fR member is non-zero). A value of
261 \fB0\fR indicates that the call timed out and no file descriptors have been
262 selected. Upon failure, \fB\(mi1\fR is returned and \fBerrno\fR is set to
263 indicate the error.
264 .SH ERRORS
265 .LP
266 The \fBpoll()\fR and \fBppoll()\fR functions will fail if:
267 .sp
268 .ne 2
269 .na
270 \fB\fBEAGAIN\fR\fR
271 .ad
272 .RS 10n
273 Allocation of internal data structures failed, but the request may be attempted
274 again.
275 .RE
277 .sp
278 .ne 2
279 .na
280 \fB\fBEFAULT\fR\fR
281 .ad
282 .RS 10n
283 Some argument points to an illegal address.
284 .RE
286 .sp
287 .ne 2
288 .na
289 \fB\fBEINTR\fR\fR
290 .ad
291 .RS 10n
292 A signal was caught during the \fBpoll()\fR or \fBppoll()\fR function.
293 .RE
295 .sp
296 .ne 2
297 .na
298 \fB\fBEINVAL\fR\fR
299 .ad
300 .RS 10n
301 The argument \fInfds\fR is greater than \fB{OPEN_MAX}\fR, or one of the
302 \fBfd\fR members refers to a stream or multiplexer that is linked (directly or
303 indirectly) downstream from a multiplexer.
304 .RE
306 .SH ATTRIBUTES
307 .LP
308 See \fBattributes\fR(5) for descriptions of the following attributes:
309 .sp
311 .sp
312 .TS
313 box;
314 c | c
315 l | l .
316 ATTRIBUTE TYPE ATTRIBUTE VALUE
317 _
318 Interface Stability Standard
319 .TE
321 .SH SEE ALSO
322 .LP
323 \fBIntro\fR(2), \fBgetmsg\fR(2), \fBgetrlimit\fR(2), \fBputmsg\fR(2),
324 \fBread\fR(2), \fBwrite\fR(2), \fBselect\fR(3C), \fBattributes\fR(5),
325 \fBstandards\fR(5), \fBchpoll\fR(9E)
326 .sp
327 .LP
328 \fISTREAMS Programming Guide\fR
329 .SH NOTES
330 .LP
331 Non-STREAMS drivers use \fBchpoll\fR(9E) to implement \fBpoll()\fR on these
332 devices.