lib/libc/sys/poll.2

   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 .\"
   4 .\" Copyright (c) 1996 Charles M. Hannum.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by Charles M. Hannum.
  17 .\" 4. The name of the author may not be used to endorse or promote products
  18 .\"    derived from this software without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  21 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  22 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  23 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  24 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  25 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  26 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  27 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  28 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  29 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  30 .\"
  31 .Dd December 1, 2016
  32 .Dt POLL 2
  33 .Os
  34 .Sh NAME
  35 .Nm poll ,
  36 .Nm ppoll
  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 .Fo poll
  45 .Fa "struct pollfd *fds"
  46 .Fa "nfds_t nfds"
  47 .Fa "int timeout"
  48 .Fc
  49 .Ft int
  50 .Fo ppoll
  51 .Fa "struct pollfd *fds"
  52 .Fa "nfds_t nfds"
  53 .Fa "const struct timespec *timeout"
  54 .Fa "const sigset_t *newsigmask"
  55 .Fc
  56 .Sh DESCRIPTION
  57 .Fn Poll
  58 and
  59 .Fn ppoll
  60 examine a set of file descriptors to see if some of them are ready for
  61 I/O.
  62 The
  63 .Fa fds
  64 argument is a pointer to an array of pollfd structures as defined in
  65 .In poll.h
  66 (shown below).
  67 The
  68 .Fa nfds
  69 argument determines the size of the
  70 .Fa fds
  71 array.
  72 .Bd -literal
  73 struct pollfd {
  74     int    fd;       /* file descriptor */
  75     short  events;   /* events to look for */
  76     short  revents;  /* events returned */
  77 };
  78 .Ed
  79 .Pp
  80 The fields of
  81 .Fa struct pollfd
  82 are as follows:
  83 .Bl -tag -offset indent -width ".Fa revents"
  84 .It Fa fd
  85 File descriptor to poll.
  86 If fd is equal to -1 then
  87 .Fa revents
  88 is cleared (set to zero), and that pollfd is not checked.
  89 .It Fa events
  90 Events to poll for.
  91 (See below.)
  92 .It Fa revents
  93 Events which may occur.
  94 (See below.)
  95 .El
  96 .Pp
  97 The event bitmasks in
  98 .Fa events
  99 and
 100 .Fa revents
 101 have the following bits:
 102 .Bl -tag -offset indent -width ".Dv POLLRDNORM"
 103 .It Dv POLLIN
 104 Data other than high priority data may be read without blocking.
 105 .It Dv POLLRDNORM
 106 Normal data may be read without blocking.
 107 .It Dv POLLRDBAND
 108 Data with a non-zero priority may be read without blocking.
 109 .It Dv POLLPRI
 110 High priority data may be read without blocking.
 111 .It Dv POLLOUT
 112 .It Dv POLLWRNORM
 113 Normal data may be written without blocking.
 114 .It Dv POLLWRBAND
 115 Data with a non-zero priority may be written without blocking.
 116 .It Dv POLLERR
 117 An exceptional condition has occurred on the device or socket.
 118 This flag is always checked, even if not present in the
 119 .Fa events
 120 bitmask.
 121 .It Dv POLLHUP
 122 The device or socket has been disconnected.
 123 This flag is always checked, even if not present in the
 124 .Fa events
 125 bitmask.
 126 Note that
 127 .Dv POLLHUP
 128 and
 129 .Dv POLLOUT
 130 should never be present in the
 131 .Fa revents
 132 bitmask at the same time.
 133 .It Dv POLLNVAL
 134 The file descriptor is not open.
 135 This flag is always checked, even if not present in the
 136 .Fa events
 137 bitmask.
 138 .El
 139 .Pp
 140 If
 141 .Fa timeout
 142 is neither zero nor
 143 .Dv INFTIM Pq -1 ,
 144 it specifies a maximum interval to
 145 wait for any file descriptor to become ready, in milliseconds.
 146 If
 147 .Fa timeout
 148 is
 149 .Dv INFTIM Pq -1 ,
 150 the poll blocks indefinitely.
 151 If
 152 .Fa timeout
 153 is zero, then
 154 .Fn poll
 155 will return without blocking.
 156 .Pp
 157 The
 158 .Fn ppoll
 159 system call can be used to safely wait until either a set of file
 160 descriptors becomes ready, or until a signal is caught.
 161 The
 162 .Fa timeout
 163 argument in
 164 .Fn ppoll
 165 points to a
 166 .Vt "const struct timespec"
 167 rather than the
 168 .Vt "int timeout"
 169 used by
 170 .Fn poll .
 171 A null pointer may be passed to indicate that
 172 .Fn ppoll
 173 should wait indefinitely.
 174 Finally,
 175 .Fa newsigmask
 176 specifies a signal mask which is set while waiting for input.
 177 When
 178 .Fn ppoll
 179 returns, the original signal mask is restored.
 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 ed
 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 .Pp
 210 The
 211 .Fn ppoll
 212 implementation uses a precise timeout which is intended to mimic the
 213 behaviour of this syscall in Linux.
 214 .Sh ERRORS
 215 An error return from
 216 .Fn poll
 217 indicates:
 218 .Bl -tag -width Er
 219 .It Bq Er EFAULT
 220 .Fa Fds
 221 points outside the process's allocated address space.
 222 .It Bq Er EINTR
 223 A signal was delivered before the time limit expired and
 224 before any of the selected events occurred.
 225 .It Bq Er EINVAL
 226 The specified time limit is negative.
 227 .El
 228 .Sh SEE ALSO
 229 .Xr accept 2 ,
 230 .Xr connect 2 ,
 231 .Xr pselect 2 ,
 232 .Xr read 2 ,
 233 .Xr recv 2 ,
 234 .Xr select 2 ,
 235 .Xr send 2 ,
 236 .Xr write 2
 237 .Sh HISTORY
 238 The
 239 .Fn poll
 240 function call appeared in
 241 .At V .
 242 This manual page was taken from
 243 .Nx .
 244 The
 245 .Fn ppoll
 246 function first appeared in
 247 .Dx 4.6 .
 248 .Sh BUGS
 249 The distinction between some of the fields in the
 250 .Fa events
 251 and
 252 .Fa revents
 253 bitmasks is really not useful without STREAMS.
 254 The fields are defined for compatibility with existing software.