| blob | f91d8b017d1b4730bcdf54d798ae75d72e9bca34 |
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" 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.
8 .\" 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.
9 .\" 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]
10 .TH POLL 2 "Aug 23, 2001"
11 .SH NAME
12 poll \- input/output multiplexing
13 .SH SYNOPSIS
14 .LP
15 .nf
16 #include <poll.h>
18 \fBint\fR \fBpoll\fR(\fBstruct pollfd\fR \fIfds[]\fR, \fBnfds_t\fR \fInfds\fR, \fBint\fR \fItimeout\fR);
19 .fi
21 .SH DESCRIPTION
22 .sp
23 .LP
24 The \fBpoll()\fR function provides applications with a mechanism for
25 multiplexing input/output over a set of file descriptors. For each member of
26 the array pointed to by \fIfds\fR, \fBpoll()\fR examines the given file
27 descriptor for the event(s) specified in \fIevents\fR. The number of
28 \fBpollfd\fR structures in the \fIfds\fR array is specified by \fInfds\fR. The
29 \fBpoll()\fR function identifies those file descriptors on which an application
30 can read or write data, or on which certain events have occurred.
31 .sp
32 .LP
33 The \fIfds\fR argument specifies the file descriptors to be examined and the
34 events of interest for each file descriptor. It is a pointer to an array with
35 one member for each open file descriptor of interest. The array's members are
36 \fBpollfd\fR structures, which contain the following members:
37 .sp
38 .in +2
39 .nf
40 int fd; /* file descriptor */
41 short events; /* requested events */
42 short revents; /* returned events */
43 .fi
44 .in -2
46 .sp
47 .LP
48 The \fBfd\fR member specifies an open file descriptor and the \fBevents\fR and
49 \fBrevents\fR members are bitmasks constructed by a logical \fBOR\fR operation
50 of any combination of the following event flags:
51 .sp
52 .ne 2
53 .na
54 \fB\fBPOLLIN\fR\fR
55 .ad
56 .RS 14n
57 Data other than high priority data may be read without blocking. For streams,
58 this flag is set in \fBrevents\fR even if the message is of zero length.
59 .RE
61 .sp
62 .ne 2
63 .na
64 \fB\fBPOLLRDNORM\fR\fR
65 .ad
66 .RS 14n
67 Normal data (priority band equals 0) may be read without blocking. For streams,
68 this flag is set in \fBrevents\fR even if the message is of zero length.
69 .RE
71 .sp
72 .ne 2
73 .na
74 \fB\fBPOLLRDBAND\fR\fR
75 .ad
76 .RS 14n
77 Data from a non-zero priority band may be read without blocking. For streams,
78 this flag is set in \fBrevents\fR even if the message is of zero length.
79 .RE
81 .sp
82 .ne 2
83 .na
84 \fB\fBPOLLPRI\fR\fR
85 .ad
86 .RS 14n
87 High priority data may be received without blocking. For streams, this flag is
88 set in \fBrevents\fR even if the message is of zero length.
89 .RE
91 .sp
92 .ne 2
93 .na
94 \fB\fBPOLLOUT\fR\fR
95 .ad
96 .RS 14n
97 Normal data (priority band equals 0) may be written without blocking.
98 .RE
100 .sp
101 .ne 2
102 .na
103 \fB\fBPOLLWRNORM\fR\fR
104 .ad
105 .RS 14n
106 The same as \fBPOLLOUT\fR.
107 .RE
109 .sp
110 .ne 2
111 .na
112 \fB\fBPOLLWRBAND\fR\fR
113 .ad
114 .RS 14n
115 Priority data (priority band > 0) may be written. This event only examines
116 bands that have been written to at least once.
117 .RE
119 .sp
120 .ne 2
121 .na
122 \fB\fBPOLLERR\fR\fR
123 .ad
124 .RS 14n
125 An error has occurred on the device or stream. This flag is only valid in the
126 \fBrevents\fR bitmask; it is not used in the \fBevents\fR member.
127 .RE
129 .sp
130 .ne 2
131 .na
132 \fB\fBPOLLHUP\fR\fR
133 .ad
134 .RS 14n
135 A hangup has occurred on the stream. This event and \fBPOLLOUT\fR are mutually
136 exclusive; a stream can never be writable if a hangup has occurred. However,
137 this event and \fBPOLLIN\fR, \fBPOLLRDNORM\fR, \fBPOLLRDBAND\fR, or
138 \fBPOLLPRI\fR are not mutually exclusive. This flag is only valid in the
139 \fBrevents\fR bitmask; it is not used in the \fBevents\fR member.
140 .RE
142 .sp
143 .ne 2
144 .na
145 \fB\fBPOLLNVAL\fR\fR
146 .ad
147 .RS 14n
148 The specified \fBfd\fR value does not belong to an open file. This flag is only
149 valid in the \fBrevents\fR member; it is not used in the \fBevents\fR member.
150 .RE
152 .sp
153 .LP
154 If the value \fBfd\fR is less than 0, \fBevents\fR is ignored and \fBrevents\fR
155 is set to 0 in that entry on return from \fBpoll()\fR.
156 .sp
157 .LP
158 The results of the \fBpoll()\fR query are stored in the \fBrevents\fR member in
159 the \fBpollfd\fR structure. Bits are set in the \fBrevents\fR bitmask to
160 indicate which of the requested events are true. If none are true, none of the
161 specified bits are set in \fBrevents\fR when the \fBpoll()\fR call returns. The
162 event flags \fBPOLLHUP\fR, \fBPOLLERR\fR, and \fBPOLLNVAL\fR are always set
163 in \fBrevents\fR if the conditions they indicate are true; this occurs even
164 though these flags were not present in \fBevents\fR.
165 .sp
166 .LP
167 If none of the defined events have occurred on any selected file descriptor,
168 \fBpoll()\fR waits at least \fItimeout\fR milliseconds for an event to occur on
169 any of the selected file descriptors. On a computer where millisecond timing
170 accuracy is not available, \fItimeout\fR is rounded up to the nearest legal
171 value available on that system. If the value \fItimeout\fR is 0, \fBpoll()\fR
172 returns immediately. If the value of \fItimeout\fR is \(mi1, \fBpoll()\fR
173 blocks until a requested event occurs or until the call is interrupted. The
174 \fBpoll()\fR function is not affected by the \fBO_NDELAY\fR and
175 \fBO_NONBLOCK\fR flags.
176 .sp
177 .LP
178 The \fBpoll()\fR function supports regular files, terminal and pseudo-terminal
179 devices, streams-based files, FIFOs and pipes. The behavior of \fBpoll()\fR on
180 elements of \fIfds\fR that refer to other types of file is unspecified.
181 .sp
182 .LP
183 The \fBpoll()\fR function supports sockets.
184 .sp
185 .LP
186 A file descriptor for a socket that is listening for connections will indicate
187 that it is ready for reading, once connections are available. A file
188 descriptor for a socket that is connecting asynchronously will indicate that it
189 is ready for writing, once a connection has been established.
190 .sp
191 .LP
192 Regular files always \fBpoll()\fR \fBTRUE\fR for reading and writing.
193 .SH RETURN VALUES
194 .sp
195 .LP
196 Upon successful completion, a non-negative value is returned. A positive value
197 indicates the total number of file descriptors that has been selected (that is,
198 file descriptors for which the \fBrevents\fR member is non-zero). A value of
199 \fB0\fR indicates that the call timed out and no file descriptors have been
200 selected. Upon failure, \fB\(mi1\fR is returned and \fBerrno\fR is set to
201 indicate the error.
202 .SH ERRORS
203 .sp
204 .LP
205 The \fBpoll()\fR function will fail if:
206 .sp
207 .ne 2
208 .na
209 \fB\fBEAGAIN\fR\fR
210 .ad
211 .RS 10n
212 Allocation of internal data structures failed, but the request may be attempted
213 again.
214 .RE
216 .sp
217 .ne 2
218 .na
219 \fB\fBEFAULT\fR\fR
220 .ad
221 .RS 10n
222 Some argument points to an illegal address.
223 .RE
225 .sp
226 .ne 2
227 .na
228 \fB\fBEINTR\fR\fR
229 .ad
230 .RS 10n
231 A signal was caught during the \fBpoll()\fR function.
232 .RE
234 .sp
235 .ne 2
236 .na
237 \fB\fBEINVAL\fR\fR
238 .ad
239 .RS 10n
240 The argument \fInfds\fR is greater than \fB{OPEN_MAX}\fR, or one of the
241 \fBfd\fR members refers to a stream or multiplexer that is linked (directly or
242 indirectly) downstream from a multiplexer.
243 .RE
245 .SH ATTRIBUTES
246 .sp
247 .LP
248 See \fBattributes\fR(5) for descriptions of the following attributes:
249 .sp
251 .sp
252 .TS
253 box;
254 c | c
255 l | l .
256 ATTRIBUTE TYPE ATTRIBUTE VALUE
257 _
258 Interface Stability Standard
259 .TE
261 .SH SEE ALSO
262 .sp
263 .LP
264 \fBIntro\fR(2), \fBgetmsg\fR(2), \fBgetrlimit\fR(2), \fBputmsg\fR(2),
265 \fBread\fR(2), \fBwrite\fR(2), \fBselect\fR(3C), \fBattributes\fR(5),
266 \fBstandards\fR(5), \fBchpoll\fR(9E)
267 .sp
268 .LP
269 \fISTREAMS Programming Guide\fR
270 .SH NOTES
271 .sp
272 .LP
273 Non-STREAMS drivers use \fBchpoll\fR(9E) to implement \fBpoll()\fR on these
274 devices.