6/lib/libc/sys/select.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)select.2    8.2 (Berkeley) 3/25/94
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd November 17, 2002
  36 .Dt SELECT 2
  37 .Os
  38 .Sh NAME
  39 .Nm select
  40 .Nd synchronous I/O multiplexing
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In sys/select.h
  45 .Ft int
  46 .Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout"
  47 .Fn FD_SET fd &fdset
  48 .Fn FD_CLR fd &fdset
  49 .Fn FD_ISSET fd &fdset
  50 .Fn FD_ZERO &fdset
  51 .Sh DESCRIPTION
  52 The
  53 .Fn select
  54 system call
  55 examines the I/O descriptor sets whose addresses are passed in
  56 .Fa readfds ,
  57 .Fa writefds ,
  58 and
  59 .Fa exceptfds
  60 to see if some of their descriptors
  61 are ready for reading, are ready for writing, or have an exceptional
  62 condition pending, respectively.
  63 The only exceptional condition detectable is out-of-band
  64 data received on a socket.
  65 The first
  66 .Fa nfds
  67 descriptors are checked in each set;
  68 i.e., the descriptors from 0 through
  69 .Fa nfds Ns No -1
  70 in the descriptor sets are examined.
  71 On return,
  72 .Fn select
  73 replaces the given descriptor sets
  74 with subsets consisting of those descriptors that are ready
  75 for the requested operation.
  76 The
  77 .Fn select
  78 system call
  79 returns the total number of ready descriptors in all the sets.
  80 .Pp
  81 The descriptor sets are stored as bit fields in arrays of integers.
  82 The following macros are provided for manipulating such descriptor sets:
  83 .Fn FD_ZERO &fdset
  84 initializes a descriptor set
  85 .Fa fdset
  86 to the null set.
  87 .Fn FD_SET fd &fdset
  88 includes a particular descriptor
  89 .Fa fd
  90 in
  91 .Fa fdset .
  92 .Fn FD_CLR fd &fdset
  93 removes
  94 .Fa fd
  95 from
  96 .Fa fdset .
  97 .Fn FD_ISSET fd &fdset
  98 is non-zero if
  99 .Fa fd
 100 is a member of
 101 .Fa fdset ,
 102 zero otherwise.
 103 The behavior of these macros is undefined if
 104 a descriptor value is less than zero or greater than or equal to
 105 .Dv FD_SETSIZE ,
 106 which is normally at least equal
 107 to the maximum number of descriptors supported by the system.
 108 .Pp
 109 If
 110 .Fa timeout
 111 is not a null pointer, it specifies the maximum interval to wait for the
 112 selection to complete.
 113 System activity can lengthen the interval by
 114 an indeterminate amount.
 115 .Pp
 116 If
 117 .Fa timeout
 118 is a null pointer, the select blocks indefinitely.
 119 .Pp
 120 To effect a poll, the
 121 .Fa timeout
 122 argument should not be a null pointer,
 123 but it should point to a zero-valued timeval structure.
 124 .Pp
 125 Any of
 126 .Fa readfds ,
 127 .Fa writefds ,
 128 and
 129 .Fa exceptfds
 130 may be given as null pointers if no descriptors are of interest.
 131 .Sh RETURN VALUES
 132 The
 133 .Fn select
 134 system call
 135 returns the number of ready descriptors that are contained in
 136 the descriptor sets,
 137 or -1 if an error occurred.
 138 If the time limit expires,
 139 .Fn select
 140 returns 0.
 141 If
 142 .Fn select
 143 returns with an error,
 144 including one due to an interrupted system call,
 145 the descriptor sets will be unmodified.
 146 .Sh ERRORS
 147 An error return from
 148 .Fn select
 149 indicates:
 150 .Bl -tag -width Er
 151 .It Bq Er EBADF
 152 One of the descriptor sets specified an invalid descriptor.
 153 .It Bq Er EFAULT
 154 One of the arguments
 155 .Fa readfds , writefds , exceptfds ,
 156 or
 157 .Fa timeout
 158 points to an invalid address.
 159 .It Bq Er EINTR
 160 A signal was delivered before the time limit expired and
 161 before any of the selected events occurred.
 162 .It Bq Er EINVAL
 163 The specified time limit is invalid.
 164 One of its components is
 165 negative or too large.
 166 .It Bq Er EINVAL
 167 The
 168 .Fa nfds
 169 argument
 170 was invalid.
 171 .El
 172 .Sh SEE ALSO
 173 .Xr accept 2 ,
 174 .Xr connect 2 ,
 175 .Xr getdtablesize 2 ,
 176 .Xr gettimeofday 2 ,
 177 .Xr kqueue 2 ,
 178 .Xr poll 2 ,
 179 .Xr read 2 ,
 180 .Xr recv 2 ,
 181 .Xr send 2 ,
 182 .Xr write 2 ,
 183 .Xr clocks 7
 184 .Sh NOTES
 185 The default size of
 186 .Dv FD_SETSIZE
 187 is currently 1024.
 188 In order to accommodate programs which might potentially
 189 use a larger number of open files with
 190 .Fn select ,
 191 it is possible
 192 to increase this size by having the program define
 193 .Dv FD_SETSIZE
 194 before the inclusion of any header which includes
 195 .In sys/types.h .
 196 .Pp
 197 If
 198 .Fa nfds
 199 is greater than the number of open files,
 200 .Fn select
 201 is not guaranteed to examine the unused file descriptors.
 202 For historical
 203 reasons,
 204 .Fn select
 205 will always examine the first 256 descriptors.
 206 .Sh STANDARDS
 207 The
 208 .Fn select
 209 system call and
 210 .Fn FD_CLR ,
 211 .Fn FD_ISSET ,
 212 .Fn FD_SET ,
 213 and
 214 .Fn FD_ZERO
 215 macros conform with
 216 .St -p1003.1-2001 .
 217 .Sh HISTORY
 218 The
 219 .Fn select
 220 system call appeared in
 221 .Bx 4.2 .
 222 .Sh BUGS
 223 .St -susv2
 224 allows systems to modify the original timeout in place.
 225 Thus, it is unwise to assume that the timeout value will be unmodified
 226 by the
 227 .Fn select
 228 system call.