bsd/man/man2/select.2

   1 .\"     $NetBSD: select.2,v 1.5 1995/06/27 22:32:28 cgd Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1991, 1993
   4 .\"     The Regents of the University of California.  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 the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)select.2    8.2 (Berkeley) 3/25/94
  35 .\"
  36 .Dd March 25, 1994
  37 .Dt SELECT 2
  38 .Os BSD 4.2
  39 .Sh NAME
  40 .Nm FD_CLR ,
  41 .Nm FD_COPY ,
  42 .Nm FD_ISSET ,
  43 .Nm FD_SET ,
  44 .Nm FD_ZERO ,
  45 .Nm select
  46 .Nd synchronous I/O multiplexing
  47 .Sh SYNOPSIS
  48 .Fd #include <sys/select.h>
  49 .\"
  50 .Ft void
  51 .Fo FD_CLR
  52 .Fa fd
  53 .Fa "fd_set *fdset"
  54 .Fc
  55 .Ft void
  56 .Fo FD_COPY
  57 .Fa "fd_set *fdset_orig"
  58 .Fa "fd_set *fdset_copy"
  59 .Fc
  60 .Ft int
  61 .Fo FD_ISSET
  62 .Fa fd
  63 .Fa "fd_set *fdset"
  64 .Fc
  65 .Ft void
  66 .Fo FD_SET
  67 .Fa fd
  68 .Fa "fd_set *fdset"
  69 .Fc
  70 .Ft void
  71 .Fo FD_ZERO
  72 .Fa "fd_set *fdset"
  73 .Fc
  74 .Ft int
  75 .Fo select
  76 .Fa "int nfds"
  77 .Fa "fd_set *restrict readfds"
  78 .Fa "fd_set *restrict writefds"
  79 .Fa "fd_set *restrict errorfds"
  80 .Fa "struct timeval *restrict timeout"
  81 .Fc
  82 .Sh DESCRIPTION
  83 .Fn Select
  84 examines the I/O descriptor sets whose addresses are passed in
  85 .Fa readfds ,
  86 .Fa writefds ,
  87 and
  88 .Fa errorfds
  89 to see if some of their descriptors
  90 are ready for reading, are ready for writing, or have an exceptional
  91 condition pending, respectively.
  92 The first
  93 .Fa nfds
  94 descriptors are checked in each set;
  95 i.e., the descriptors from 0 through
  96 .Fa nfds Ns No -1
  97 in the descriptor sets are examined.  (Example: If you have set two file descriptors "4" and "17",
  98 .Fa nfds
  99 should  not be "2", but rather "17 + 1" or "18".)
 100 On return,
 101 .Fn select
 102 replaces the given descriptor sets
 103 with subsets consisting of those descriptors that are ready
 104 for the requested operation.
 105 .Fn Select
 106 returns the total number of ready descriptors in all the sets.
 107 .Pp
 108 The descriptor sets are stored as bit fields in arrays of integers.
 109 The following macros are provided for manipulating such descriptor sets:
 110 .Fn FD_ZERO &fdset
 111 initializes a descriptor set
 112 .Fa fdset
 113 to the null set.
 114 .Fn FD_SET fd &fdset
 115 includes a particular descriptor
 116 .Fa fd
 117 in
 118 .Fa fdset .
 119 .Fn FD_CLR fd &fdset
 120 removes
 121 .Fa fd
 122 from
 123 .Fa fdset .
 124 .Fn FD_ISSET fd &fdset
 125 is non-zero if
 126 .Fa fd
 127 is a member of
 128 .Fa fdset ,
 129 zero otherwise.
 130 .Fn FD_COPY &fdset_orig &fdset_copy
 131 replaces an already allocated
 132 .Fa &fdset_copy
 133 file descriptor set with a copy of
 134 .Fa &fdset_orig .
 135 The behavior of these macros is undefined if
 136 a descriptor value is less than zero or greater than or equal to
 137 .Dv FD_SETSIZE ,
 138 which is normally at least equal
 139 to the maximum number of descriptors supported by the system.
 140 .Pp
 141 If
 142 .Fa timeout
 143 is a non-nil pointer, it specifies a maximum interval to wait for the
 144 selection to complete.  If
 145 .Fa timeout
 146 is a nil pointer, the select blocks indefinitely.  To effect a poll, the
 147 .Fa timeout
 148 argument should be non-nil, pointing to a zero-valued timeval structure.
 149 .Fa Timeout
 150 is not changed by
 151 .Fn select ,
 152 and may be reused on subsequent calls, however it is good style to re-initialize
 153 it before each invocation of
 154 .Fn select .
 155 .Pp
 156 Any of
 157 .Fa readfds ,
 158 .Fa writefds ,
 159 and
 160 .Fa errorfds
 161 may be given as nil pointers if no descriptors are of interest.
 162 .Sh RETURN VALUES
 163 .Fn Select
 164 returns the number of ready descriptors that are contained in
 165 the descriptor sets,
 166 or -1 if an error occurred.
 167 If the time limit expires,
 168 .Fn select
 169 returns 0.
 170 If
 171 .Fn select
 172 returns with an error,
 173 including one due to an interrupted call,
 174 the descriptor sets will be unmodified and the global variable
 175 .Va errno
 176 will be set to indicate the error.
 177 .Sh ERRORS
 178 An error return from
 179 .Fn select
 180 indicates:
 181 .Bl -tag -width Er
 182 .\" ===========
 183 .It Bq Er EAGAIN
 184 The kernel was (perhaps temporarily) unable
 185 to allocate the requested number of file descriptors.
 186 .\" ===========
 187 .It Bq Er EBADF
 188 One of the descriptor sets specified an invalid descriptor.
 189 .\" ===========
 190 .It Bq Er EINTR
 191 A signal was delivered before the time limit expired and
 192 before any of the selected events occurred.
 193 .\" ===========
 194 .It Bq Er EINVAL
 195 The specified time limit is invalid.  One of its components is
 196 negative or too large.
 197 .\" ===========
 198 .It Bq Er EINVAL
 199 .Fa ndfs
 200 is greater than FD_SETSIZE and _DARWIN_UNLIMITED_SELECT is not defined.
 201 .El
 202 .Sh LEGACY SYNOPSIS
 203 .Fd #include <sys/select.h>
 204 .D1 "- or -"
 205 .Fd #include <sys/types.h>
 206 .Fd #include <sys/time.h>
 207 .Fd #include <unistd.h>
 208 .Pp
 209 .Fo FD_SET
 210 .Fa fd
 211 .Fa &fdset
 212 .Fc ;
 213 .Pp
 214 .Fo FD_CLR
 215 .Fa fd
 216 .Fa &fdset
 217 .Fc ;
 218 .Pp
 219 .Fo FD_ISSET
 220 .Fa fd
 221 .Fa &fdset
 222 .Fc ;
 223 .Pp
 224 .Fo FD_COPY
 225 .Fa &fdset_orig
 226 .Fa &fdset_copy
 227 .Fc ;
 228 .Pp
 229 .Fo FD_ZERO
 230 .Fa &fdset
 231 .Fc ;
 232 .Sh COMPATIBILITY
 233 .Fn select
 234 now returns with
 235 .Va errno
 236 set to EINVAL when
 237 .Fa nfds
 238 is greater than FD_SETSIZE.
 239 Use a smaller value for
 240 .Fa nfds
 241 or compile with -D_DARWIN_UNLIMITED_SELECT.
 242 .Sh SEE ALSO
 243 .Xr accept 2 ,
 244 .Xr connect 2 ,
 245 .Xr getdtablesize 2 ,
 246 .Xr gettimeofday 2 ,
 247 .Xr read 2 ,
 248 .Xr recv 2 ,
 249 .Xr send 2 ,
 250 .Xr write 2 ,
 251 .Xr compat 5
 252 .Sh BUGS
 253 Although the provision of
 254 .Xr getdtablesize 2
 255 was intended to allow user programs to be written independent
 256 of the kernel limit on the number of open files, the dimension
 257 of a sufficiently large bit field for select remains a problem.
 258 The default size
 259 .Dv FD_SETSIZE
 260 (currently 1024) is somewhat smaller than
 261 the current kernel limit to the number of open files.
 262 However, in order to accommodate programs which might potentially
 263 use a larger number of open files with select, it is possible
 264 to increase this size within a program by providing
 265 a larger definition of
 266 .Dv FD_SETSIZE
 267 before the inclusion of
 268 .Aq Pa sys/types.h .
 269 .Pp
 270 .Fn Select
 271 should probably have been designed to return the time remaining from the
 272 original timeout, if any, by modifying the time value in place.
 273 However, it is unlikely this semantic will ever be implemented, as the
 274 change would cause source code compatibility problems.
 275 In general it is unwise to assume that the timeout value will be
 276 unmodified by the
 277 .Fn select
 278 call, and the caller should reinitialize it on each invocation.
 279 .Sh HISTORY
 280 The
 281 .Fn select
 282 function call appeared in
 283 .Bx 4.2 .