select,  pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO - syn­
       chronous I/O multiplexing


SYNOPSIS

       #include <sys/time.h>
       #include <sys/types.h>
       #include <unistd.h>

       int  select(int  n,  fd_set  *readfds,  fd_set  *writefds,
       fd_set *exceptfds, struct timeval *timeout);

       int  pselect(int  n,  fd_set  *readfds,  fd_set *writefds,
       fd_set  *exceptfds,  const   struct   timespec   *timeout,
       sigset_t * sigmask);

       FD_CLR(int fd, fd_set *set);
       FD_ISSET(int fd, fd_set *set);
       FD_SET(int fd, fd_set *set);
       FD_ZERO(fd_set *set);


DESCRIPTION

       The functions select and pselect wait for a number of file
       descriptors to change status.

       Their function is identical, with three differences:

       (i)    The select function uses a timeout that is a struct
              timeval (with seconds and microseconds), while pse­
              lect uses  a  struct  timespec  (with  seconds  and
              nanoseconds).

       (ii)   The  select function may update the timeout parame­
              ter to indicate how much time was left. The pselect
              function does not change this parameter.

       (iii)  The  select  function has no sigmask parameter, and
              behaves as pselect called with NULL sigmask.

       Three independent sets of descriptors are watched.   Those
       listed  in  readfds  will  be watched to see if characters
       become available for reading (more precisely, to see if  a
       read  will not block - in particular, a file descriptor is
       also ready on end-of-file),  those  in  writefds  will  be
       watched  to  see  if  a write will not block, and those in
       exceptfds will be watched for exceptions.   On  exit,  the
       sets  are  modified in place to indicate which descriptors
       actually changed status.

       Four macros are provided to manipulate the sets.   FD_ZERO
       will clear a set.  FD_SET and FD_CLR add or remove a given
       descriptor from  a  set.   FD_ISSET  tests  to  see  if  a
       descriptor is part of the set; this is useful after select
       returns.

       sets, plus 1.

       timeout  is  an  upper bound on the amount of time elapsed
       before select returns. It may be zero, causing  select  to
       return immediately. (This is useful for polling.) If time­
       out is NULL (no timeout), select can block indefinitely.

       sigmask is a  pointer  to  a  signal  mask  (see  sigproc­
       mask(2));  if  it is not NULL, then pselect first replaces
       the current signal mask by the one pointed to by  sigmask,
       then  does  the  `select'  function, and then restores the
       original signal mask again.

       The idea of pselect is that if one wants to  wait  for  an
       event,  either a signal or something on a file descriptor,
       an atomic test is needed to prevent race conditions. (Sup­
       pose  the  signal  handler sets a global flag and returns.
       Then a test of this global flag  followed  by  a  call  of
       select()  could  hang  indefinitely  if the signal arrived
       just after the test but just before the call. On the other
       hand,  pselect  allows  one to first block signals, handle
       the signals that have come in, then  call  pselect()  with
       the  desired  sigmask,  avoiding  the  race.)  Since Linux
       today does not have a pselect() system call,  the  current
       glibc2 routine still contains this race.


RETURN VALUE

       On  success,  select  and  pselect  return  the  number of
       descriptors contained in the descriptor sets, which may be
       zero  if  the  timeout expires before anything interesting
       happens.  On error, -1  is  returned,  and  errno  is  set
       appropriately;  the  sets and timeout become undefined, so
       do not rely on their contents after an error.


ERRORS

       EBADF  An invalid file descriptor was given in one of  the
              sets.

       EINTR  A non blocked signal was caught.

       EINVAL n is negative.

       ENOMEM select  was  unable to allocate memory for internal
              tables.


NOTES

       Some code calls select with all three sets empty, n  zero,
       and  a  non-null timeout as a fairly portable way to sleep
       with subsecond precision.

       On Linux, timeout is modified to  reflect  the  amount  of
       time not slept; most other implementations do not do this.
       This causes problems both  when  Linux  code  which  reads

       code is ported to Linux that reuses a struct  timeval  for
       multiple  selects  in  a  loop  without reinitializing it.
       Consider timeout to be undefined after select returns.


EXAMPLE

       #include <stdio.h>
       #include <sys/time.h>
       #include <sys/types.h>
       #include <unistd.h>

       int
       main(void) {
           fd_set rfds;
           struct timeval tv;
           int retval;

           /* Watch stdin (fd 0) to see when it has input. */
           FD_ZERO(&rfds);
           FD_SET(0, &rfds);
           /* Wait up to five seconds. */
           tv.tv_sec = 5;
           tv.tv_usec = 0;

           retval = select(1, &rfds, NULL, NULL, &tv);
           /* Don't rely on the value of tv now! */

           if (retval)
               printf("Data is available now.\n");
               /* FD_ISSET(0, &rfds) will be true. */
           else
               printf("No data within five seconds.\n");

           exit(0);
       }


CONFORMING TO

       4.4BSD (the select function  first  appeared  in  4.2BSD).
       Generally  portable  to/from  non-BSD  systems  supporting
       clones of the BSD socket layer (including System  V  vari­
       ants).   However, note that the System V variant typically
       sets the timeout variable before exit, but the BSD variant
       does not.

       The  pselect  function is defined in IEEE Std 1003.1g-2000
       (POSIX.1g).  It is found in glibc2.1 and later.   Glibc2.0
       has  a function with this name, that however does not take
       a sigmask parameter.


SEE ALSO

       accept(2), connect(2), poll(2), read(2), recv(2), send(2),
       sigprocmask(2), write(2)


Man(1) output converted with man2html