xref: /dragonfly/lib/libc/sys/poll.2 (revision 36a3d1d6) 
1.\"	$NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $
2.\" $FreeBSD: src/lib/libc/sys/poll.2,v 1.4.2.3 2001/12/14 18:34:01 ru Exp $
3.\" $DragonFly: src/lib/libc/sys/poll.2,v 1.7 2008/05/25 14:04:32 swildner Exp $
4.\"
5.\" Copyright (c) 1996 Charles M. Hannum.  All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
10.\" 1. Redistributions of source code must retain the above copyright
11.\"    notice, this list of conditions and the following disclaimer.
12.\" 2. Redistributions in binary form must reproduce the above copyright
13.\"    notice, this list of conditions and the following disclaimer in the
14.\"    documentation and/or other materials provided with the distribution.
15.\" 3. All advertising materials mentioning features or use of this software
16.\"    must display the following acknowledgement:
17.\"	This product includes software developed by Charles M. Hannum.
18.\" 4. The name of the author may not be used to endorse or promote products
19.\"    derived from this software without specific prior written permission.
20.\"
21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
26.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
27.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
30.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31.\"
32.Dd January 12, 2008
33.Dt POLL 2
34.Os
35.Sh NAME
36.Nm poll
37.Nd synchronous I/O multiplexing
38.Sh LIBRARY
39.Lb libc
40.Sh SYNOPSIS
41.In sys/types.h
42.In poll.h
43.Ft int
44.Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout"
45.Sh DESCRIPTION
46.Fn Poll
47examines a set of file descriptors to see if some of them are ready for
48I/O.
49The
50.Fa fds
51argument is a pointer to an array of pollfd structures as defined in
52.In poll.h
53(shown below).
54The
55.Fa nfds
56argument determines the size of the
57.Fa fds
58array.
59.Bd -literal
60struct pollfd {
61    int    fd;       /* file descriptor */
62    short  events;   /* events to look for */
63    short  revents;  /* events returned */
64};
65.Ed
66.Pp
67The fields of
68.Fa struct pollfd
69are as follows:
70.Bl -tag -offset indent -width ".Fa revents"
71.It Fa fd
72File descriptor to poll.
73If fd is equal to -1 then
74.Fa revents
75is cleared (set to zero), and that pollfd is not checked.
76.It Fa events
77Events to poll for.
78(See below.)
79.It Fa revents
80Events which may occur.
81(See below.)
82.El
83.Pp
84The event bitmasks in
85.Fa events
86and
87.Fa revents
88have the following bits:
89.Bl -tag -offset indent -width ".Dv POLLRDNORM"
90.It Dv POLLIN
91Data other than high priority data may be read without blocking.
92.It Dv POLLRDNORM
93Normal data may be read without blocking.
94.It Dv POLLRDBAND
95Data with a non-zero priority may be read without blocking.
96.It Dv POLLPRI
97High priority data may be read without blocking.
98.It Dv POLLOUT
99.It Dv POLLWRNORM
100Normal data may be written without blocking.
101.It Dv POLLWRBAND
102Data with a non-zero priority may be written without blocking.
103.It Dv POLLERR
104An exceptional condition has occurred on the device or socket.
105This flag is always checked, even if not present in the
106.Fa events
107bitmask.
108.It Dv POLLHUP
109The device or socket has been disconnected.
110This flag is always checked, even if not present in the
111.Fa events
112bitmask.
113Note that
114.Dv POLLHUP
115and
116.Dv POLLOUT
117should never be present in the
118.Fa revents
119bitmask at the same time.
120.It Dv POLLNVAL
121The file descriptor is not open.
122This flag is always checked, even if not present in the
123.Fa events
124bitmask.
125.El
126.Pp
127If
128.Fa timeout
129is neither zero nor
130.Dv INFTIM Pq -1 ,
131it specifies a maximum interval to
132wait for any file descriptor to become ready, in milliseconds.
133If
134.Fa timeout
135is
136.Dv INFTIM Pq -1 ,
137the poll blocks indefinitely.
138If
139.Fa timeout
140is zero, then
141.Fn poll
142will return without blocking.
143.Sh RETURN VALUES
144.Fn Poll
145returns the number of descriptors that are ready for I/O, or -1 if an
146error occurred.
147If the time limit expires,
148.Fn poll
149returns 0.
150If
151.Fn poll
152returns with an error,
153including one due to an interrupted call,
154the
155.Fa fds
156array will be unmodified.
157.Sh COMPATIBILITY
158This implementation differs from the historical one in that a given
159file descriptor may not cause
160.Fn poll
161to return with an error.
162In cases where this would have happened in the historical implementation
163(e.g.\& trying to poll a
164.Xr revoke 2 Ns ed
165descriptor), this implementation instead copies the
166.Fa events
167bitmask to the
168.Fa revents
169bitmask.
170Attempting to perform I/O on this descriptor will then return an error.
171This behaviour is believed to be more useful.
172.Sh ERRORS
173An error return from
174.Fn poll
175indicates:
176.Bl -tag -width Er
177.It Bq Er EFAULT
178.Fa Fds
179points outside the process's allocated address space.
180.It Bq Er EINTR
181A signal was delivered before the time limit expired and
182before any of the selected events occurred.
183.It Bq Er EINVAL
184The specified time limit is negative.
185.El
186.Sh SEE ALSO
187.Xr accept 2 ,
188.Xr connect 2 ,
189.Xr read 2 ,
190.Xr recv 2 ,
191.Xr select 2 ,
192.Xr send 2 ,
193.Xr write 2
194.Sh HISTORY
195The
196.Fn poll
197function call appeared in
198.At V .
199This manual page was taken from
200.Nx .
201.Sh BUGS
202The distinction between some of the fields in the
203.Fa events
204and
205.Fa revents
206bitmasks is really not useful without STREAMS.
207The fields are defined for compatibility with existing software.
208