doc/html/ref/net-common-tcpip-manpages-select.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >select</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="TCP/IP Library Reference"
  23 HREF="tcpip-library-reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="poll"
  26 HREF="net-common-tcpip-manpages-poll.html"><LINK
  27 REL="NEXT"
  28 TITLE="send"
  29 HREF="net-common-tcpip-manpages-send.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-common-tcpip-manpages-poll.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 38. TCP/IP Library Reference</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-common-tcpip-manpages-send.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-COMMON-TCPIP-MANPAGES-SELECT">select</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >SELECT(2)                     System Calls Manual                    SELECT(2)
  95
  96 NAME
  97      select - synchronous I/O multiplexing
  98
  99 SYNOPSIS
 100      #include &lt;sys/types.h&#62;
 101      #include &lt;sys/time.h&#62;
 102      #include &lt;unistd.h&#62;
 103
 104      int
 105      select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds,
 106              struct timeval *timeout);
 107
 108      FD_SET(fd, &amp;fdset);
 109
 110      FD_CLR(fd, &amp;fdset);
 111
 112      FD_ISSET(fd, &amp;fdset);
 113
 114      FD_ZERO(&amp;fdset);
 115
 116 DESCRIPTION
 117      select() examines the I/O descriptor sets whose addresses are passed in
 118      readfds, writefds, and exceptfds to see if some of their descriptors are
 119      ready for reading, are ready for writing, or have an exceptional condi-
 120      tion pending, respectively.  The first nfds descriptors are checked in
 121      each set; i.e., the descriptors from 0 through nfds-1 in the descriptor
 122      sets are examined.  On return, select() replaces the given descriptor
 123      sets with subsets consisting of those descriptors that are ready for the
 124      requested operation.  select() returns the total number of ready descrip-
 125      tors in all the sets.
 126
 127      The descriptor sets are stored as bit fields in arrays of integers.  The
 128      following macros are provided for manipulating such descriptor sets:
 129      FD_ZERO(&amp;fdset) initializes a descriptor set fdset to the null set.
 130      FD_SET(fd, &amp;fdset) includes a particular descriptor fd in fdset.
 131      FD_CLR(fd, &amp;fdset) removes fd from fdset.  FD_ISSET(fd, &amp;fdset) is non-
 132      zero if fd is a member of fdset, zero otherwise.  The behavior of these
 133      macros is undefined if a descriptor value is less than zero or greater
 134      than or equal to FD_SETSIZE, which is normally at least equal to the max-
 135      imum number of descriptors supported by the system.
 136
 137      If timeout is a non-null pointer, it specifies a maximum interval to wait
 138      for the selection to complete.  If timeout is a null pointer, the select
 139      blocks indefinitely.  To effect a poll, the timeout argument should be
 140      non-null, pointing to a zero-valued timeval structure.  timeout is not
 141      changed by select(), and may be reused on subsequent calls; however, it
 142      is good style to re-initialize it before each invocation of select().
 143
 144      Any of readfds, writefds, and exceptfds may be given as null pointers if
 145      no descriptors are of interest.
 146
 147 RETURN VALUES
 148      select() returns the number of ready descriptors that are contained in
 149      the descriptor sets, or -1 is an error occurred.  If the time limit
 150      expires, select() returns 0.  If select() returns with an error, includ-
 151      ing one due to an interrupted call, the descriptor sets will be unmodi-
 152      fied.
 153
 154 ERRORS
 155      An error return from select() indicates:
 156
 157      [EFAULT]           One or more of readfds, writefds, or exceptfds points
 158                         outside the process's allocated address space.
 159
 160      [EBADF]            One of the descriptor sets specified an invalid
 161                         descriptor.
 162
 163      [EINTR]            A signal was delivered before the time limit expired
 164                         and before any of the selected events occurred.
 165
 166      [EINVAL]           The specified time limit is invalid.  One of its com-
 167                         ponents is negative or too large.
 168
 169 SEE ALSO
 170      accept(2), connect(2), gettimeofday(2), poll(2), read(2), recv(2),
 171      send(2), write(2), getdtablesize(3)
 172
 173 BUGS
 174      Although the provision of getdtablesize(3) was intended to allow user
 175      programs to be written independent of the kernel limit on the number of
 176      open files, the dimension of a sufficiently large bit field for select
 177      remains a problem.  The default bit size of fd_set is based on the symbol
 178      FD_SETSIZE (currently 256), but that is somewhat smaller than the current
 179      kernel limit to the number of open files.  However, in order to accommo-
 180      date programs which might potentially use a larger number of open files
 181      with select, it is possible to increase this size within a program by
 182      providing a larger definition of FD_SETSIZE before the inclusion of
 183      &lt;sys/types.h&#62;.  The kernel will cope, and the userland libraries provided
 184      with the system are also ready for large numbers of file descriptors.
 185
 186      Alternatively, to be really safe, it is possible to allocate fd_set bit-
 187      arrays dynamically.  The idea is to permit a program to work properly
 188      even if it is execve(2)'d with 4000 file descriptors pre-allocated.  The
 189      following illustrates the technique which is used by userland libraries:
 190
 191                    fd_set *fdsr;
 192                    int max = fd;
 193
 194                    fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
 195                        sizeof(fd_mask));
 196                    if (fdsr == NULL) {
 197                            ...
 198                            return (-1);
 199                    }
 200                    FD_SET(fd, fdsr);
 201                    n = select(max+1, fdsr, NULL, NULL, &amp;tv);
 202                    ...
 203                    free(fdsr);
 204
 205      Alternatively, it is possible to use the poll(2) interface.  poll(2) is
 206      more efficient when the size of select()'s fd_set bit-arrays are very
 207      large, and for fixed numbers of file descriptors one need not size and
 208      dynamically allocate a memory object.
 209
 210      select() should probably have been designed to return the time remaining
 211      from the original timeout, if any, by modifying the time value in place.
 212      Even though some systems stupidly act in this different way, it is
 213      unlikely this semantic will ever be commonly implemented, as the change
 214      causes massive source code compatibility problems.  Furthermore, recent
 215      new standards have dictated the current behaviour.  In general, due to
 216      the existence of those brain-damaged non-conforming systems, it is unwise
 217      to assume that the timeout value will be unmodified by the select() call,
 218      and the caller should reinitialize it on each invocation.  Calculating
 219      the delta is easily done by calling gettimeofday(2) before and after the
 220      call to select(), and using timersub() (as described in getitimer(2)).
 221
 222      Internally to the kernel, select() works poorly if multiple processes
 223      wait on the same file descriptor.  Given that, it is rather surprising to
 224      see that many daemons are written that way (i.e., httpd(8)).
 225
 226 HISTORY
 227      The select() function call appeared in 4.2BSD.
 228
 229 BSD                             March 25, 1994                             BSD
 230     </PRE
 231 ></TD
 232 ></TR
 233 ></TABLE
 234 ></DIV
 235 ><DIV
 236 CLASS="NAVFOOTER"
 237 ><HR
 238 ALIGN="LEFT"
 239 WIDTH="100%"><TABLE
 240 SUMMARY="Footer navigation table"
 241 WIDTH="100%"
 242 BORDER="0"
 243 CELLPADDING="0"
 244 CELLSPACING="0"
 245 ><TR
 246 ><TD
 247 WIDTH="33%"
 248 ALIGN="left"
 249 VALIGN="top"
 250 ><A
 251 HREF="net-common-tcpip-manpages-poll.html"
 252 ACCESSKEY="P"
 253 >Prev</A
 254 ></TD
 255 ><TD
 256 WIDTH="34%"
 257 ALIGN="center"
 258 VALIGN="top"
 259 ><A
 260 HREF="ecos-ref.html"
 261 ACCESSKEY="H"
 262 >Home</A
 263 ></TD
 264 ><TD
 265 WIDTH="33%"
 266 ALIGN="right"
 267 VALIGN="top"
 268 ><A
 269 HREF="net-common-tcpip-manpages-send.html"
 270 ACCESSKEY="N"
 271 >Next</A
 272 ></TD
 273 ></TR
 274 ><TR
 275 ><TD
 276 WIDTH="33%"
 277 ALIGN="left"
 278 VALIGN="top"
 279 >poll</TD
 280 ><TD
 281 WIDTH="34%"
 282 ALIGN="center"
 283 VALIGN="top"
 284 ><A
 285 HREF="tcpip-library-reference.html"
 286 ACCESSKEY="U"
 287 >Up</A
 288 ></TD
 289 ><TD
 290 WIDTH="33%"
 291 ALIGN="right"
 292 VALIGN="top"
 293 >send</TD
 294 ></TR
 295 ></TABLE
 296 ></DIV
 297 ></BODY
 298 ></HTML
 299 >