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 select
  41 .Nd synchronous I/O multiplexing
  42 .Sh SYNOPSIS
  43 .Fd #include <sys/types.h>
  44 .Fd #include <sys/time.h>
  45 .Fd #include <unistd.h>
  46 .Ft int
  47 .Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout"
  48 .Fn FD_SET fd &fdset
  49 .Fn FD_CLR fd &fdset
  50 .Fn FD_ISSET fd &fdset
  51 .Fn FD_ZERO &fdset
  52 .Sh DESCRIPTION
  53 .Fn Select
  54 examines the I/O descriptor sets whose addresses are passed in
  55 .Fa readfds ,
  56 .Fa writefds ,
  57 and
  58 .Fa exceptfds
  59 to see if some of their descriptors
  60 are ready for reading, are ready for writing, or have an exceptional
  61 condition pending, respectively.
  62 The first
  63 .Fa nfds
  64 descriptors are checked in each set;
  65 i.e., the descriptors from 0 through
  66 .Fa nfds Ns No -1
  67 in the descriptor sets are examined.
  68 On return,
  69 .Fn select
  70 replaces the given descriptor sets
  71 with subsets consisting of those descriptors that are ready
  72 for the requested operation.
  73 .Fn Select
  74 returns the total number of ready descriptors in all the sets.
  75 .Pp
  76 The descriptor sets are stored as bit fields in arrays of integers.
  77 The following macros are provided for manipulating such descriptor sets:
  78 .Fn FD_ZERO &fdset
  79 initializes a descriptor set
  80 .Fa fdset
  81 to the null set.
  82 .Fn FD_SET fd &fdset
  83 includes a particular descriptor
  84 .Fa fd
  85 in
  86 .Fa fdset .
  87 .Fn FD_CLR fd &fdset
  88 removes
  89 .Fa fd
  90 from
  91 .Fa fdset .
  92 .Fn FD_ISSET fd &fdset
  93 is non-zero if
  94 .Fa fd
  95 is a member of
  96 .Fa fdset ,
  97 zero otherwise.
  98 The behavior of these macros is undefined if
  99 a descriptor value is less than zero or greater than or equal to
 100 .Dv FD_SETSIZE ,
 101 which is normally at least equal
 102 to the maximum number of descriptors supported by the system.
 103 .Pp
 104 If
 105 .Fa timeout
 106 is a non-nil pointer, it specifies a maximum interval to wait for the
 107 selection to complete.  If
 108 .Fa timeout
 109 is a nil pointer, the select blocks indefinitely.  To effect a poll, the
 110 .Fa timeout
 111 argument should be non-nil, pointing to a zero-valued timeval structure.
 112 .Fa Timeout
 113 is not changed by
 114 .Fn select ,
 115 and may be reused on subsequent calls, however it is good style to re-initialize
 116 it before each invocation of
 117 .Fn select .
 118 .Pp
 119 Any of
 120 .Fa readfds ,
 121 .Fa writefds ,
 122 and
 123 .Fa exceptfds
 124 may be given as nil pointers if no descriptors are of interest.
 125 .Sh RETURN VALUES
 126 .Fn Select
 127 returns the number of ready descriptors that are contained in
 128 the descriptor sets,
 129 or -1 if an error occurred.
 130 If the time limit expires,
 131 .Fn select
 132 returns 0.
 133 If
 134 .Fn select
 135 returns with an error,
 136 including one due to an interrupted call,
 137 the descriptor sets will be unmodified.
 138 .Sh ERRORS
 139 An error return from
 140 .Fn select
 141 indicates:
 142 .Bl -tag -width Er
 143 .It Bq Er EBADF
 144 One of the descriptor sets specified an invalid descriptor.
 145 .It Bq Er EINTR
 146 A signal was delivered before the time limit expired and
 147 before any of the selected events occurred.
 148 .It Bq Er EINVAL
 149 The specified time limit is invalid.  One of its components is
 150 negative or too large.
 151 .El
 152 .Sh SEE ALSO
 153 .Xr accept 2 ,
 154 .Xr connect 2 ,
 155 .Xr getdtablesize 2 ,
 156 .Xr gettimeofday 2 ,
 157 .Xr read 2 ,
 158 .Xr recv 2 ,
 159 .Xr send 2 ,
 160 .Xr write 2
 161 .Sh BUGS
 162 Although the provision of
 163 .Xr getdtablesize 2
 164 was intended to allow user programs to be written independent
 165 of the kernel limit on the number of open files, the dimension
 166 of a sufficiently large bit field for select remains a problem.
 167 The default size
 168 .Dv FD_SETSIZE
 169 (currently 1024) is somewhat smaller than
 170 the current kernel limit to the number of open files.
 171 However, in order to accommodate programs which might potentially
 172 use a larger number of open files with select, it is possible
 173 to increase this size within a program by providing
 174 a larger definition of
 175 .Dv FD_SETSIZE
 176 before the inclusion of
 177 .Aq Pa sys/types.h .
 178 .Pp
 179 .Fn Select
 180 should probably have been designed to return the time remaining from the
 181 original timeout, if any, by modifying the time value in place.
 182 However, it is unlikely this semantic will ever be implemented, as the
 183 change would cause source code compatibility problems.
 184 In general it is unwise to assume that the timeout value will be
 185 unmodified by the
 186 .Fn select
 187 call, and the caller should reinitialize it on each invocation.
 188 .Sh HISTORY
 189 The
 190 .Fn select
 191 function call appeared in
 192 .Bx 4.2 .