packages/net/tcpip/v2_0/doc/select.man

   1 NAME
   2        select,  FD_CLR,  FD_ISSET,  FD_SET, FD_ZERO - synchronous
   3        I/O multiplexing
   4
   5 SYNOPSIS
   6        #include <network.h>
   7
   8        int  select(int  n,  fd_set  *readfds,  fd_set  *writefds,
   9        fd_set *exceptfds, struct timeval *timeout);
  10
  11        FD_CLR(int fd, fd_set *set);
  12        FD_ISSET(int fd, fd_set *set);
  13        FD_SET(int fd, fd_set *set);
  14        FD_ZERO(fd_set *set);
  15
  16 DESCRIPTION
  17        select  waits  for  a number of file descriptors to change
  18        status.
  19
  20        Three independent sets of descriptors are watched.   Those
  21        listed  in  readfds  will  be watched to see if characters
  22        become available for reading, those in  writefds  will  be
  23        watched  to  see if it is ok to immediately write on them,
  24        and those in exceptfds will be watched for exceptions.  On
  25        exit,  the  sets  are  modified in place to indicate which
  26        descriptors actually changed status.
  27
  28        Four macros are provided to manipulate the sets.   FD_ZERO
  29        will clear a set.  FD_SET and FD_CLR add or remove a given
  30        descriptor from  a  set.   FD_ISSET  tests  to  see  if  a
  31        descriptor is part of the set; this is useful after select
  32        returns.
  33
  34        n is the highest-numbered descriptor in any of  the  three
  35        sets, plus 1.
  36
  37        timeout  is  an  upper bound on the amount of time elapsed
  38        before select returns. It may be zero, causing  select  to
  39        return  immediately.  If  timeout  is  NULL  (no timeout),
  40        select can block indefinitely.
  41
  42 RETURN VALUE
  43        On success, select returns the number of descriptors  con-
  44        tained  in  the  descriptor sets, which may be zero if the
  45        timeout expires before anything interesting  happens.   On
  46        error, -1 is returned, and errno is set appropriately; the
  47        sets and timeout become undefined, so do not rely on their
  48        contents after an error.
  49
  50 ERRORS
  51        EBADF   An invalid file descriptor was given in one of the
  52                sets.
  53
  54        EINTR   A non blocked signal was caught.
  55
  56        EINVAL  n is negative.
  57
  58        ENOMEM  select was unable to allocate memory for  internal
  59                tables.
  60
  61 NOTES
  62        Some  code calls select with all three sets empty, n zero,
  63        and a non-null timeout as a fairly portable way  to  sleep
  64        with subsecond precision.
  65
  66 EXAMPLE
  67        #include <stdio.h>
  68        #include <sys/time.h>
  69        #include <sys/types.h>
  70        #include <unistd.h>
  71
  72        int
  73        main(void)
  74        {
  75            fd_set rfds;
  76            struct timeval tv;
  77            int retval;
  78
  79            /* Watch stdin (fd 0) to see when it has input. */
  80            FD_ZERO(&rfds);
  81            FD_SET(0, &rfds);
  82            /* Wait up to five seconds. */
  83            tv.tv_sec = 5;
  84            tv.tv_usec = 0;
  85
  86            retval = select(1, &rfds, NULL, NULL, &tv);
  87            /* Don't rely on the value of tv now! */
  88
  89            if (retval)
  90                printf("Data is available now.\n");
  91                /* FD_ISSET(0, &rfds) will be true. */
  92            else
  93                printf("No data within five seconds.\n");
  94
  95            exit(0);
  96        }
  97
  98        Generally  portable  to/from  non-BSD  systems  supporting
  99        clones  of  the BSD socket layer (including System V vari-
 100        ants).  However, note that the System V variant  typically
 101        sets the timeout variable before exit, but the BSD variant
 102        does not.