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 18, 2015
  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 not a null pointer, it specifies a maximum interval to wait for the
 144 selection to complete.
 145 .Pp
 146 If
 147 .Fa timeout
 148 is a null pointer, the select blocks indefinitely.
 149 .Pp
 150 To effect a poll, the
 151 .Fa timeout
 152 argument should be not be a null pointer,
 153 but it should point to a zero-valued timeval structure.
 154 .Pp
 155 .Fa timeout
 156 is not changed by
 157 .Fn select ,
 158 and may be reused on subsequent calls, however it is good style to re-initialize
 159 it before each invocation of
 160 .Fn select .
 161 .Pp
 162 Any of
 163 .Fa readfds ,
 164 .Fa writefds ,
 165 and
 166 .Fa errorfds
 167 may be given as null pointers if no descriptors are of interest.
 168 .Sh RETURN VALUES
 169 .Fn select
 170 returns the number of ready descriptors that are contained in
 171 the descriptor sets,
 172 or -1 if an error occurred.
 173 If the time limit expires,
 174 .Fn select
 175 returns 0.
 176 If
 177 .Fn select
 178 returns with an error,
 179 including one due to an interrupted call,
 180 the descriptor sets will be unmodified and the global variable
 181 .Va errno
 182 will be set to indicate the error.
 183 .Sh ERRORS
 184 An error return from
 185 .Fn select
 186 indicates:
 187 .Bl -tag -width Er
 188 .\" ===========
 189 .It Bq Er EAGAIN
 190 The kernel was (perhaps temporarily) unable
 191 to allocate the requested number of file descriptors.
 192 .\" ===========
 193 .It Bq Er EBADF
 194 One of the descriptor sets specified an invalid descriptor.
 195 .\" ===========
 196 .It Bq Er EINTR
 197 A signal was delivered before the time limit expired and
 198 before any of the selected events occurred.
 199 .\" ===========
 200 .It Bq Er EINVAL
 201 The specified time limit is invalid.  One of its components is
 202 negative or too large.
 203 .\" ===========
 204 .It Bq Er EINVAL
 205 .Fa ndfs
 206 is greater than FD_SETSIZE and _DARWIN_UNLIMITED_SELECT is not defined.
 207 .El
 208 .Sh LEGACY SYNOPSIS
 209 .Fd #include <sys/select.h>
 210 .D1 "- or -"
 211 .Fd #include <sys/types.h>
 212 .Fd #include <sys/time.h>
 213 .Fd #include <unistd.h>
 214 .Pp
 215 .Fo FD_SET
 216 .Fa fd
 217 .Fa &fdset
 218 .Fc ;
 219 .Pp
 220 .Fo FD_CLR
 221 .Fa fd
 222 .Fa &fdset
 223 .Fc ;
 224 .Pp
 225 .Fo FD_ISSET
 226 .Fa fd
 227 .Fa &fdset
 228 .Fc ;
 229 .Pp
 230 .Fo FD_COPY
 231 .Fa &fdset_orig
 232 .Fa &fdset_copy
 233 .Fc ;
 234 .Pp
 235 .Fo FD_ZERO
 236 .Fa &fdset
 237 .Fc ;
 238 .Sh COMPATIBILITY
 239 .Fn select
 240 now returns with
 241 .Va errno
 242 set to EINVAL when
 243 .Fa nfds
 244 is greater than FD_SETSIZE.
 245 Use a smaller value for
 246 .Fa nfds
 247 or compile with -D_DARWIN_UNLIMITED_SELECT.
 248 .Sh SEE ALSO
 249 .Xr accept 2 ,
 250 .Xr connect 2 ,
 251 .Xr connectx 2 ,
 252 .Xr getdtablesize 2 ,
 253 .Xr gettimeofday 2 ,
 254 .Xr read 2 ,
 255 .Xr recv 2 ,
 256 .Xr send 2 ,
 257 .Xr write 2 ,
 258 .Xr compat 5
 259 .Sh BUGS
 260 Although the provision of
 261 .Xr getdtablesize 2
 262 was intended to allow user programs to be written independent
 263 of the kernel limit on the number of open files, the dimension
 264 of a sufficiently large bit field for select remains a problem.
 265 The default size
 266 .Dv FD_SETSIZE
 267 (currently 1024) is somewhat smaller than
 268 the current kernel limit to the number of open files.
 269 However, in order to accommodate programs which might potentially
 270 use a larger number of open files with select, it is possible
 271 to increase this size within a program by providing
 272 a larger definition of
 273 .Dv FD_SETSIZE
 274 before the inclusion of
 275 .Aq Pa sys/types.h .
 276 .Pp
 277 .Fn select
 278 should probably have been designed to return the time remaining from the
 279 original timeout, if any, by modifying the time value in place.
 280 However, it is unlikely this semantic will ever be implemented, as the
 281 change would cause source code compatibility problems.
 282 In general it is unwise to assume that the timeout value will be
 283 unmodified by the
 284 .Fn select
 285 call, and the caller should reinitialize it on each invocation.
 286 .Sh HISTORY
 287 The
 288 .Fn select
 289 function call appeared in
 290 .Bx 4.2 .