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 September 7, 1996
  32 .Dt POLL 2
  33 .Os
  34 .Sh NAME
  35 .Nm poll
  36 .Nd synchronous I/O multiplexing
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/types.h
  41 .In poll.h
  42 .Ft int
  43 .Fn poll "struct pollfd *fds" "unsigned int nfds" "int timeout"
  44 .Sh DESCRIPTION
  45 .Fn Poll
  46 examines a set of file descriptors to see if some of them are ready for
  47 I/O.
  48 The
  49 .Fa fds
  50 argument is a pointer to an array of pollfd structures as defined in
  51 .Aq Pa poll.h
  52 (shown below).  The
  53 .Fa nfds
  54 argument determines the size of the
  55 .Fa fds
  56 array.
  57 .Bd -literal
  58 struct pollfd {
  59     int    fd;       /* file descriptor */
  60     short  events;   /* events to look for */
  61     short  revents;  /* events returned */
  62 };
  63 .Ed
  64 .Pp
  65 The fields of
  66 .Fa struct pollfd
  67 are as follows:
  68 .Bl -tag -width XXXrevents
  69 .It fd
  70 File descriptor to poll.  If fd is equal to -1 then
  71 .Fa revents
  72 is cleared (set to zero), and that pollfd is not checked.
  73 .It events
  74 Events to poll for.  (See below.)
  75 .It revents
  76 Events which may occur.  (See below.)
  77 .El
  78 .Pp
  79 The event bitmasks in
  80 .Fa events
  81 and
  82 .Fa revents
  83 have the following bits:
  84 .Bl -tag -width XXXPOLLWRNORM
  85 .It POLLIN
  86 Data other than high priority data may be read without blocking.
  87 .It POLLRDNORM
  88 Normal data may be read without blocking.
  89 .It POLLRDBAND
  90 Data with a non-zero priority may be read without blocking.
  91 .It POLLPRI
  92 High priority data may be read without blocking.
  93 .It POLLOUT
  94 .It POLLWRNORM
  95 Normal data may be written without blocking.
  96 .It POLLWRBAND
  97 Data with a non-zero priority may be written without blocking.
  98 .It POLLERR
  99 An exceptional condition has occurred on the device or socket.  This
 100 flag is always checked, even if not present in the
 101 .Fa events
 102 bitmask.
 103 .It POLLHUP
 104 The device or socket has been disconnected.  This flag is always
 105 checked, even if not present in the
 106 .Fa events
 107 bitmask.  Note that
 108 POLLHUP
 109 and
 110 POLLOUT
 111 should never be present in the
 112 .Fa revents
 113 bitmask at the same time.
 114 .It POLLNVAL
 115 The file descriptor is not open.  This flag is always checked, even
 116 if not present in the
 117 .Fa events
 118 bitmask.
 119 .El
 120 .Pp
 121 If
 122 .Fa timeout
 123 is neither zero nor INFTIM (-1), it specifies a maximum interval to
 124 wait for any file descriptor to become ready, in milliseconds.  If
 125 .Fa timeout
 126 is INFTIM (-1), the poll blocks indefinitely.  If
 127 .Fa timeout
 128 is zero, then
 129 .Fn poll
 130 will return without blocking.
 131 .Sh RETURN VALUES
 132 .Fn Poll
 133 returns the number of descriptors that are ready for I/O, or -1 if an
 134 error occured.  If the time limit expires,
 135 .Fn poll
 136 returns 0.
 137 If
 138 .Fn poll
 139 returns with an error,
 140 including one due to an interrupted call,
 141 the
 142 .Fa fds
 143 array will be unmodified.
 144 .Sh COMPATIBILITY
 145 This implementation differs from the historical one in that a given
 146 file descriptor may not cause
 147 .Fn poll
 148 to return with an error.  In cases where this would have happened in
 149 the historical implementation (e.g. trying to poll a
 150 .Xr revoke 2 Ns ed
 151 descriptor), this implementation instead copies the
 152 .Fa events
 153 bitmask to the
 154 .Fa revents
 155 bitmask.  Attempting to perform I/O on this descriptor will then
 156 return an error.  This behaviour is believed to be more useful.
 157 .Sh ERRORS
 158 An error return from
 159 .Fn poll
 160 indicates:
 161 .Bl -tag -width Er
 162 .It Bq Er EFAULT
 163 .Fa Fds
 164 points outside the process's allocated address space.
 165 .It Bq Er EINTR
 166 A signal was delivered before the time limit expired and
 167 before any of the selected events occurred.
 168 .It Bq Er EINVAL
 169 The specified time limit is negative.
 170 .El
 171 .Sh SEE ALSO
 172 .Xr accept 2 ,
 173 .Xr connect 2 ,
 174 .Xr read 2 ,
 175 .Xr recv 2 ,
 176 .Xr select 2 ,
 177 .Xr send 2 ,
 178 .Xr write 2
 179 .Sh BUGS
 180 The distinction between some of the fields in the
 181 .Fa events
 182 and
 183 .Fa revents
 184 bitmasks is really not useful without STREAMS.  The fields are
 185 defined for compatibility with existing software.
 186 .Sh HISTORY
 187 The
 188 .Fn poll
 189 function call appeared in
 190 .At V .
 191 This manual page and the core of the implementation was taken from
 192 .Nx .