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