bsd/man/man2/poll.2

   1 .\"
   2 .\" Copyright (c) 2005 Apple Computer, Inc. All rights reserved.
   3 .\"
   4 .\" @APPLE_LICENSE_OSREFERENCE_HEADER_START@
   5 .\"
   6 .\" This file contains Original Code and/or Modifications of Original Code
   7 .\" as defined in and that are subject to the Apple Public Source License
   8 .\" Version 2.0 (the "License"). You may not use this file except in
   9 .\" compliance with the License.  The rights granted to you under the
  10 .\" License may not be used to create, or enable the creation or
  11 .\" redistribution of, unlawful or unlicensed copies of an Apple operating
  12 .\" system, or to circumvent, violate, or enable the circumvention or
  13 .\" violation of, any terms of an Apple operating system software license
  14 .\" agreement.
  15 .\"
  16 .\" Please obtain a copy of the License at
  17 .\" http://www.opensource.apple.com/apsl/ and read it before using this
  18 .\" file.
  19 .\"
  20 .\" The Original Code and all software distributed under the License are
  21 .\" distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  22 .\" EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  23 .\" INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  24 .\" FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  25 .\" Please see the License for the specific language governing rights and
  26 .\" limitations under the License.
  27 .\"
  28 .\" @APPLE_LICENSE_OSREFERENCE_HEADER_END@
  29 .\"
  30 .\"
  31 .\" Copyright (c) 1996 Charles M. Hannum.  All rights reserved.
  32 .\"
  33 .\" Redistribution and use in source and binary forms, with or without
  34 .\" modification, are permitted provided that the following conditions
  35 .\" are met:
  36 .\" 1. Redistributions of source code must retain the above copyright
  37 .\"    notice, this list of conditions and the following disclaimer.
  38 .\" 2. Redistributions in binary form must reproduce the above copyright
  39 .\"    notice, this list of conditions and the following disclaimer in the
  40 .\"    documentation and/or other materials provided with the distribution.
  41 .\" 3. All advertising materials mentioning features or use of this software
  42 .\"    must display the following acknowledgement:
  43 .\"     This product includes software developed by Charles M. Hannum.
  44 .\" 4. The name of the author may not be used to endorse or promote products
  45 .\"    derived from this software without specific prior written permission.
  46 .\"
  47 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
  48 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  49 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  50 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  51 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  52 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  53 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  54 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  55 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  56 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  57 .\"
  58 .Dd February 27, 2005
  59 .Dt POLL 2
  60 .Os
  61 .Sh NAME
  62 .Nm poll
  63 .Nd synchronous I/O multiplexing
  64 .Sh SYNOPSIS
  65 .In poll.h
  66 .Ft int
  67 .Fn poll "struct pollfd *fds" "nfds_t nfds" "int timeout"
  68 .Sh DESCRIPTION
  69 .Fn Poll
  70 examines a set of file descriptors to see if some of them are ready for
  71 I/O or if certain events have occurred on them.
  72 The
  73 .Fa fds
  74 argument is a pointer to an array of pollfd structures as defined in
  75 .Aq Pa poll.h
  76 (shown below).  The
  77 .Fa nfds
  78 argument determines the size of the
  79 .Fa fds
  80 array.
  81 .Bd -literal
  82 struct pollfd {
  83     int    fd;       /* file descriptor */
  84     short  events;   /* events to look for */
  85     short  revents;  /* events returned */
  86 };
  87 .Ed
  88 .Pp
  89 The fields of
  90 .Fa struct pollfd
  91 are as follows:
  92 .Bl -tag -width XXXrevents
  93 .It fd
  94 File descriptor to poll.
  95 .It events
  96 Events to poll for.  (See below.)
  97 .It revents
  98 Events which may occur or have occurred.  (See below.)
  99 .El
 100 .Pp
 101 The event bitmasks in
 102 .Fa events
 103 and
 104 .Fa revents
 105 have the following bits:
 106 .Bl -tag -width XXXPOLLWRNORM
 107 .It POLLIN
 108 Data other than high priority data may be read without blocking.
 109 This is equivalent to ( POLLRDNORM | POLLRDBAND ).
 110 .It POLLRDNORM
 111 Normal data may be read without blocking.
 112 .It POLLRDBAND
 113 Priority data may be read without blocking.
 114 .It POLLPRI
 115 High priority data may be read without blocking.
 116 .It POLLOUT
 117 .It POLLWRNORM
 118 Normal data may be written without blocking.
 119 .It POLLWRBAND
 120 Priority data may be written without blocking.
 121 .It POLLERR
 122 An exceptional condition has occurred on the device or socket.  This
 123 flag is output only, and ignored if present in the input
 124 .Fa events
 125 bitmask.
 126 .It POLLHUP
 127 The device or socket has been disconnected.  This flag is output only,
 128 and ignored if present in the input
 129 .Fa events
 130 bitmask.  Note that
 131 POLLHUP
 132 and
 133 POLLOUT
 134 are mutually exclusive and should never be present in the
 135 .Fa revents
 136 bitmask at the same time.
 137 .It POLLNVAL
 138 The file descriptor is not open.  This flag is output only, and ignored if present in the input
 139 .Fa events
 140 bitmask.
 141 .El
 142 .Pp
 143 The distinction between normal, priority, and high-priority data is file type
 144 or device specific.
 145 .Pp
 146 If
 147 .Fa timeout
 148 is greater than zero, it specifies a maximum interval to
 149 wait for any file descriptor to become ready, in milliseconds.  If
 150 .Fa timeout
 151 is zero, then
 152 .Fn poll
 153 will return without blocking. If the value of
 154 .Fa timeout
 155 is -1, the poll blocks indefinitely.
 156 .Sh RETURN VALUES
 157 .Fn Poll
 158 returns the number of descriptors that are ready for I/O, or -1 if an
 159 error occured.  If the time limit expires,
 160 .Fn poll
 161 returns 0.
 162 If
 163 .Fn poll
 164 returns with an error,
 165 including one due to an interrupted call,
 166 the
 167 .Fa fds
 168 array will be unmodified.
 169 .Sh ERRORS
 170 An error return from
 171 .Fn poll
 172 indicates:
 173 .Bl -tag -width Er
 174 .It Bq Er EFAULT
 175 .Fa Fds
 176 points outside the process's allocated address space.
 177 .It Bq Er EINTR
 178 A signal was delivered before the time limit expired and
 179 before any of the selected events occurred.
 180 .It Bq Er EINVAL
 181 The
 182 .Fa nfds
 183 argument is greater than OPEN_MAX, or the
 184 .Fa timeout
 185 argument is less than -1.
 186 .El
 187 .Sh BUGS
 188 The
 189 .Fn poll
 190 system call currently does not support devices.
 191 .Sh SEE ALSO
 192 .Xr accept 2 ,
 193 .Xr connect 2 ,
 194 .Xr kevent 2 ,
 195 .Xr read 2 ,
 196 .Xr recv 2 ,
 197 .Xr select 2 ,
 198 .Xr send 2 ,
 199 .Xr write 2
 200 .Sh HISTORY
 201 The
 202 .Fn poll
 203 function call appeared in
 204 .At V .
 205