lib/libc/sys/poll.2

   1 .\"     $NetBSD: poll.2,v 1.3 1996/09/07 21:53:08 mycroft Exp $
   2 .\"
   3 .\" Copyright (c) 1996 Charles M. Hannum.  All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\" 3. All advertising materials mentioning features or use of this software
  14 .\"    must display the following acknowledgement:
  15 .\"     This product includes software developed by Charles M. Hannum.
  16 .\" 4. The name of the author may not be used to endorse or promote products
  17 .\"    derived from this software without specific prior written permission.
  18 .\"
  19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  22 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd April 27, 2021
  31 .Dt POLL 2
  32 .Os
  33 .Sh NAME
  34 .Nm poll
  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 .Ft int
  43 .Fo ppoll
  44 .Fa "struct pollfd fds[]"
  45 .Fa "nfds_t nfds"
  46 .Fa "const struct timespec * restrict timeout"
  47 .Fa "const sigset_t * restrict newsigmask"
  48 .Fc
  49 .Sh DESCRIPTION
  50 The
  51 .Fn poll
  52 system call
  53 examines a set of file descriptors to see if some of them are ready for
  54 I/O.
  55 The
  56 .Fa fds
  57 argument is a pointer to an array of pollfd structures as defined in
  58 .In poll.h
  59 (shown below).
  60 The
  61 .Fa nfds
  62 argument determines the size of the
  63 .Fa fds
  64 array.
  65 .Bd -literal
  66 struct pollfd {
  67     int    fd;       /* file descriptor */
  68     short  events;   /* events to look for */
  69     short  revents;  /* events returned */
  70 };
  71 .Ed
  72 .Pp
  73 The fields of
  74 .Fa struct pollfd
  75 are as follows:
  76 .Bl -tag -width XXXrevents
  77 .It fd
  78 File descriptor to poll.
  79 If fd is equal to -1 then
  80 .Fa revents
  81 is cleared (set to zero), and that pollfd is not checked.
  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 .It POLLWRNORM
 106 Normal data may be written without blocking.
 107 .It POLLWRBAND
 108 Data with a non-zero priority may be written without blocking.
 109 .It POLLERR
 110 An exceptional condition has occurred on the device or socket.
 111 This
 112 flag is always checked, even if not present in the
 113 .Fa events
 114 bitmask.
 115 .It POLLHUP
 116 The device or socket has been disconnected.
 117 This flag is always
 118 checked, even if not present in the
 119 .Fa events
 120 bitmask.
 121 Note that
 122 POLLHUP
 123 and
 124 POLLOUT
 125 should never be present in the
 126 .Fa revents
 127 bitmask at the same time.
 128 .It POLLRDHUP
 129 Remote peer closed connection, or shut down writing.
 130 Unlike
 131 POLLHUP,
 132 POLLRDHUP
 133 must be present in the
 134 .Fa events
 135 bitmask to be reported.
 136 Applies only to stream sockets.
 137 .It POLLNVAL
 138 The file descriptor is not open,
 139 or in capability mode the file descriptor has insufficient rights.
 140 This flag is always checked, even
 141 if not present in the
 142 .Fa events
 143 bitmask.
 144 .El
 145 .Pp
 146 If
 147 .Fa timeout
 148 is neither zero nor INFTIM (-1), it specifies a maximum interval to
 149 wait for any file descriptor to become ready, in milliseconds.
 150 If
 151 .Fa timeout
 152 is INFTIM (-1), the poll blocks indefinitely.
 153 If
 154 .Fa timeout
 155 is zero, then
 156 .Fn poll
 157 will return without blocking.
 158 .Pp
 159 The
 160 .Fn ppoll
 161 system call, unlike
 162 .Fn poll ,
 163 is used to safely wait until either a set of file descriptors becomes
 164 ready or until a signal is caught.
 165 The
 166 .Fa fds
 167 and
 168 .Fa nfds
 169 arguments are identical to the analogous arguments of
 170 .Fn poll .
 171 The
 172 .Fa timeout
 173 argument in
 174 .Fn ppoll
 175 points to a
 176 .Vt "const struct timespec"
 177 which is defined in
 178 .In sys/timespec.h
 179 (shown below) rather than the
 180 .Vt "int timeout"
 181 used by
 182 .Fn poll .
 183 A null pointer may be passed to indicate that
 184 .Fn ppoll
 185 should wait indefinitely.
 186 Finally,
 187 .Fa newsigmask
 188 specifies a signal mask which is set while waiting for input.
 189 When
 190 .Fn ppoll
 191 returns, the original signal mask is restored.
 192 .Bd -literal
 193 struct timespec {
 194         time_t  tv_sec;         /* seconds */
 195         long    tv_nsec;        /* and nanoseconds */
 196 };
 197 .Ed
 198 .Sh RETURN VALUES
 199 The
 200 .Fn poll
 201 system call
 202 returns the number of descriptors that are ready for I/O, or -1 if an
 203 error occurred.
 204 If the time limit expires,
 205 .Fn poll
 206 returns 0.
 207 If
 208 .Fn poll
 209 returns with an error,
 210 including one due to an interrupted system call,
 211 the
 212 .Fa fds
 213 array will be unmodified.
 214 .Sh COMPATIBILITY
 215 This implementation differs from the historical one in that a given
 216 file descriptor may not cause
 217 .Fn poll
 218 to return with an error.
 219 In cases where this would have happened in
 220 the historical implementation (e.g.\& trying to poll a
 221 .Xr revoke 2 Ns ed
 222 descriptor), this implementation instead copies the
 223 .Fa events
 224 bitmask to the
 225 .Fa revents
 226 bitmask.
 227 Attempting to perform I/O on this descriptor will then
 228 return an error.
 229 This behaviour is believed to be more useful.
 230 .Sh ERRORS
 231 An error return from
 232 .Fn poll
 233 indicates:
 234 .Bl -tag -width Er
 235 .It Bq Er EFAULT
 236 The
 237 .Fa fds
 238 argument
 239 points outside the process's allocated address space.
 240 .It Bq Er EINTR
 241 A signal was delivered before the time limit expired and
 242 before any of the selected events occurred.
 243 .It Bq Er EINVAL
 244 The specified time limit is invalid.
 245 One of its components is negative or too large.
 246 .It Bq Er EINVAL
 247 The number of pollfd structures specified by
 248 .Fa nfds
 249 exceeds the system tunable
 250 .Va kern.maxfilesperproc
 251 and
 252 .Dv FD_SETSIZE .
 253 .El
 254 .Sh SEE ALSO
 255 .Xr accept 2 ,
 256 .Xr connect 2 ,
 257 .Xr kqueue 2 ,
 258 .Xr pselect 2 ,
 259 .Xr read 2 ,
 260 .Xr recv 2 ,
 261 .Xr select 2 ,
 262 .Xr send 2 ,
 263 .Xr write 2
 264 .Sh STANDARDS
 265 The
 266 .Fn poll
 267 function conforms to
 268 .St -p1003.1-2001 .
 269 The
 270 .Fn ppoll
 271 is not specified by POSIX.
 272 The
 273 POLLRDHUP
 274 flag is not specified by POSIX, but is compatible with Linux and illumos.
 275 .Sh HISTORY
 276 The
 277 .Fn poll
 278 function appeared in
 279 .At V .
 280 This manual page and the core of the implementation was taken from
 281 .Nx .
 282 The
 283 .Fn ppoll
 284 function first appeared in
 285 .Fx 11.0
 286 .Sh BUGS
 287 The distinction between some of the fields in the
 288 .Fa events
 289 and
 290 .Fa revents
 291 bitmasks is really not useful without STREAMS.
 292 The fields are
 293 defined for compatibility with existing software.