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