lib/libc/sys/poll.2

   1 .\"     $NetBSD: poll.2,v 1.28 2010/03/22 19:30:55 joerg Exp $
   2 .\"
   3 .\" Copyright (c) 1998, 2005 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Charles M. Hannum.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 8, 2006
  31 .Dt POLL 2
  32 .Os
  33 .Sh NAME
  34 .Nm poll, pollts
  35 .Nd synchronous I/O multiplexing
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In poll.h
  40 .Ft int
  41 .Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout"
  42 .In poll.h
  43 .In signal.h
  44 .In time.h
  45 .Ft int
  46 .Fn pollts "struct pollfd * restrict fds" "nfds_t nfds" "const struct timespec * restrict ts" "const sigset_t * restrict sigmask"
  47 .Sh DESCRIPTION
  48 .Fn poll
  49 and
  50 .Fn pollts
  51 examine a set of file descriptors to see if some of them are ready for
  52 I/O.
  53 The
  54 .Fa fds
  55 argument is a pointer to an array of pollfd structures as defined in
  56 .In poll.h
  57 (shown below).
  58 The
  59 .Fa nfds
  60 argument determines the size of the
  61 .Fa fds
  62 array.
  63 .Bd -literal
  64 struct pollfd {
  65     int    fd;       /* file descriptor */
  66     short  events;   /* events to look for */
  67     short  revents;  /* events returned */
  68 };
  69 .Ed
  70 .Pp
  71 The fields of
  72 .Fa struct pollfd
  73 are as follows:
  74 .Bl -tag -width XXXrevents
  75 .It fd
  76 File descriptor to poll.
  77 If the value in
  78 .Em fd
  79 is negative, the file descriptor is ignored and
  80 .Em revents
  81 is set to 0.
  82 .It events
  83 Events to poll for.
  84 (See below.)
  85 .It revents
  86 Events which may occur.
  87 (See below.)
  88 .El
  89 .Pp
  90 The event bitmasks in
  91 .Fa events
  92 and
  93 .Fa revents
  94 have the following bits:
  95 .Bl -tag -width XXXPOLLWRNORM
  96 .It POLLIN
  97 Data other than high priority data may be read without blocking.
  98 .It POLLRDNORM
  99 Normal data may be read without blocking.
 100 .It POLLRDBAND
 101 Data with a non-zero priority may be read without blocking.
 102 .It POLLPRI
 103 High priority data may be read without blocking.
 104 .It POLLOUT
 105 Normal data may be written without blocking.
 106 .It POLLWRNORM
 107 Equivalent to
 108 POLLOUT.
 109 .It POLLWRBAND
 110 Data with a non-zero priority may be written without blocking.
 111 .It POLLERR
 112 An exceptional condition has occurred on the device or socket.
 113 This flag is always checked, even if not present in the
 114 .Fa events
 115 bitmask.
 116 .It POLLHUP
 117 The device or socket has been disconnected.
 118 This flag is always
 119 checked, even if not present in the
 120 .Fa events
 121 bitmask.
 122 Note that
 123 POLLHUP
 124 and
 125 POLLOUT
 126 should never be present in the
 127 .Fa revents
 128 bitmask at the same time.
 129 If the remote end of a socket is closed,
 130 .Fn poll
 131 returns a
 132 POLLIN
 133 event, rather than a
 134 POLLHUP.
 135 .It POLLNVAL
 136 The file descriptor is not open.
 137 This flag is always checked, even
 138 if not present in the
 139 .Fa events
 140 bitmask.
 141 .El
 142 .Pp
 143 If
 144 .Fa timeout
 145 is neither zero nor INFTIM (\-1), it specifies a maximum interval to
 146 wait for any file descriptor to become ready, in milliseconds.
 147 If
 148 .Fa timeout
 149 is INFTIM (\-1), the poll blocks indefinitely.
 150 If
 151 .Fa timeout
 152 is zero, then
 153 .Fn poll
 154 will return without blocking.
 155 .Pp
 156 If
 157 .Fa ts
 158 is a non-null pointer, it references a timespec structure which specifies a
 159 maximum interval to wait for any file descriptor to become ready.
 160 If
 161 .Fa ts
 162 is a null pointer,
 163 .Fn pollts
 164 blocks indefinitely.
 165 If
 166 .Fa ts
 167 is a non-null pointer, referencing a zero-valued timespec structure, then
 168 .Fn pollts
 169 will return without blocking.
 170 .Pp
 171 If
 172 .Fa sigmask
 173 is a non-null pointer, then the
 174 .Fn pollts
 175 function shall replace the signal mask of the caller by the set of
 176 signals pointed to by
 177 .Fa sigmask
 178 before examining the descriptors, and shall restore the signal mask
 179 of the caller before returning.
 180 .Sh RETURN VALUES
 181 .Fn poll
 182 returns the number of descriptors that are ready for I/O, or \-1 if an
 183 error occurred.
 184 If the time limit expires,
 185 .Fn poll
 186 returns 0.
 187 If
 188 .Fn poll
 189 returns with an error,
 190 including one due to an interrupted call,
 191 the
 192 .Fa fds
 193 array will be unmodified.
 194 .Sh COMPATIBILITY
 195 This implementation differs from the historical one in that a given
 196 file descriptor may not cause
 197 .Fn poll
 198 to return with an error.
 199 In cases where this would have happened in the historical implementation
 200 (e.g. trying to poll a
 201 .Xr revoke 2 Ns d
 202 descriptor), this implementation instead copies the
 203 .Fa events
 204 bitmask to the
 205 .Fa revents
 206 bitmask.
 207 Attempting to perform I/O on this descriptor will then return an error.
 208 This behaviour is believed to be more useful.
 209 .Sh ERRORS
 210 An error return from
 211 .Fn poll
 212 indicates:
 213 .Bl -tag -width Er
 214 .It Bq Er EFAULT
 215 .Fa fds
 216 points outside the process's allocated address space.
 217 .It Bq Er EINTR
 218 A signal was delivered before the time limit expired and
 219 before any of the selected events occurred.
 220 .It Bq Er EINVAL
 221 The specified time limit is negative.
 222 .El
 223 .Sh SEE ALSO
 224 .Xr accept 2 ,
 225 .Xr connect 2 ,
 226 .Xr read 2 ,
 227 .Xr recv 2 ,
 228 .Xr select 2 ,
 229 .Xr send 2 ,
 230 .Xr write 2
 231 .Sh HISTORY
 232 The
 233 .Fn poll
 234 function appeared in
 235 .At V.3 .
 236 The
 237 .Fn pollts
 238 function first appeared in
 239 .Nx 3.0 .
 240 .Sh BUGS
 241 The distinction between some of the fields in the
 242 .Fa events
 243 and
 244 .Fa revents
 245 bitmasks is really not useful without STREAMS.
 246 The fields are defined for compatibility with existing software.