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