select(2)                                                         select(2)




 NAME
      select - synchronous I/O multiplexing

 SYNOPSIS
      #include <sys/time.h>

      int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set
      *errorfds, struct timeval *timeout);

      void FD_CLR(int fd, fd_set *fdset);

      void FD_SET(int fd, fd_set *fdset);

      void FD_ZERO(fd_set *fdset);

 DESCRIPTION
      The select() function indicates which of the specified  file
      descriptors is ready for reading, ready for writing, or has an error
      condition pending. If the specified condition is false for all of the
      specified file descriptors, select() blocks, up to the specified
      timeout interval, until the specified condition is true for at least
      one  of the specified file descriptors.

      The select() function supports regular files, terminal and pseudo-
      terminal devices, STREAMS-based files, FIFOs and pipes. The behaviour
      of select() on file descriptors that refer to other types of file is
      unspecified.

      The nfds argument specifies the range of file descriptors to be
      tested. The select() function tests file descriptors in the range of 0
      to nfds -1.

      If the readfs argument is not a null pointer, it points to an object
      of type fd_set that on input specifies the file descriptors to be
      checked for being  ready  to read, and on output indicates which file
      descriptors are ready to read.

      If the writefs argument is not a  null  pointer,  it points to an
      object of type fd_set that on input specifies the file descriptors  to
      be  checked  for being  ready to write, and on output indicates which
      file descriptors are ready to write.

      If the errorfds argument is not a null pointer, it points  to  an
      object  of type fd_set that on input specifies the file descriptors to be
      checked for error conditions pending, and on output indicates which
      file  descriptors have error conditions pending.

      On successful completion, the objects pointed to by the readfs,
      writefs, and errorfds arguments are modified to indicate which file
      descriptors are ready for reading, ready for writing, or have an error
      condition pending, respectively. For each file descriptor less than
      nfds, the corresponding bit will be set on successful completion if it
      was set on input and the associated condition is true for that file
      descriptor.

      If the timeout argument is not a null pointer, it points to an object
      of type struct timeval that specifies a maximum interval to wait for
      the selection to complete. If the timeout argument points to an object
      of type struct timeval whose members are 0, select() does not block. If
      the timeout argument is a null pointer, select() blocks until an event
      causes one of the masks to be returned with a valid (non-zero) value.
      If the time limit expires before any event occurs that would cause one
      of the masks to be set to a non-zero value, select() completes
      successfully and returns 0.

      Implementations may place limitations on the maximum timeout interval
      supported. On all implementations, the maximum timeout interval
      supported will be at least 31 days. If the timeout argument specifies
      a timeout interval greater than the implementation- dependent maximum
      value, the maximum value will be used as the actual timeout value.
      Implementations may also place limitations on the granularity of
      timeout intervals. If the requested timeout interval requires a finer
      granularity than the implementation supports, the actual timeout
      interval will be rounded up to the next supported value.

      If the readfs, writefs, and errorfds arguments are all null pointers
      and the timeout argument is not a null pointer, select() blocks for
      the time specified, or until interrupted by a signal.  If the readfs,
      writefs, and errorfds arguments are all null pointers and the timeout
      argument is a null pointer, select() blocks until interrupted by a
      signal.

      File descriptors associated with regular files always select true for
      ready to read, ready to write, and error conditions.

      On failure, the objects pointed to by the readfs, writefs, and
      errorfds arguments are not modified. If the timeout interval expires
      without the specified condition being true for any of the specified
      file descriptors, the objects pointed to by the readfs, writefs, and
      errorfds arguments have all bits set to 0.

      File descriptor masks of type fd_set can be initialised and tested
      with FD_CLR(), FD_ISSET(), FD_SET(), and FD_ZERO().  It is unspecified
      whether each of these is a macro or a function. If a macro definition
      is suppressed in order to access an actual function, or a program
      defines an external identifier with any of these names, the behaviour
      is undefined.

           FD_CLR(fd, &fdset)            Clears the bit for the file
                                         descriptor fd in the file
                                         descriptor set fdset.

           FD_ISSET(fd, &fdset)          Returns a non-zero value if the bit
                                         for the file descriptor fd is set
                                         in the file descriptor set pointed
                                         to by fdset, and 0 otherwise.

           FD_SET(fd, &fdset)            Sets the bit for the file
                                         descriptor fd in the file
                                         descriptor set fdset.

           FD_ZERO(&fdset)               Initialises the file descriptor set
                                         fdset to have zero bits for all
                                         file descriptors. The behaviour of
                                         these macros is undefined if the fd
                                         argument is less than 0 or greater
                                         than or equal to FD_SETSIZE.

 RETURN VALUE
      FD_CLR(), FD_SET(), and FD_ZERO() return  no  value.  FD_ISSET()
      returns a non-zero value if the bit for the file descriptor fd is set
      in the file descriptor set pointed to by fdset, and 0 otherwise.

      On successful completion, select() returns the total number of bits
      set in the bit masks. Otherwise, -1 is returned, and errno is set to
      indicate the error.

 ERRORS
      Under the following conditions, select() fails and sets errno to:

           [EBADF]        One or more of the file descriptor sets specified
                          a file descriptor that is not a valid open file
                          descriptor.

           [EINTR]        The select() function was interrupted  before any
                          of the selected events occurred and before the
                          timeout interval expired. If SA_RESTART has been
                          set for the interrupting signal, it is
                          implementation-dependent whether select() restarts
                          or returns with EINTR.

           [EINVAL]       An invalid timeout interval was specified.

           [EINVAL]       The nfds argument is less than 0, or greater than
                          or equal to FD_SETSIZE.

           [EINVAL]       One of the specified file descriptors refers  o  a
                          STREAM or multiplexer that is linked (directly or
                          indirectly) downstream from a multiplexer.

 APPLICATION USAGE
      The use of a timeout does not affect any pending timers set up by
      alarm(), ualarm(), or settimer().

      On successful completion, the object pointed to  by the timeout
      argument may be modified.

 SEE ALSO
      fcntl(), poll(), read(), write(), <sys/time.h>.

 CHANGE HISTORY
      First released in Issue 4, Version 2.



                                 HP-UX EXTENSIONS



 SYNOPSIS
      #include <time.h>

      int select(
           size_t nfds,
           int *readfds,
           int *writefds,
           int *exceptfds,
           const struct timeval *timeout
      );

 DESCRIPTION
      select() examines the files or devices associated with the file
      descriptors specified by the bit masks readfds, writefds, and
      exceptfds.  The bits from 0 through nfds-1 are examined.  File
      descriptor f is represented by the bit 1<<f in the masks.  More
      formally, a file descriptor is represented by:

           fds[(f / BITS_PER_INT)] & (1 << (f % BITS_PER_INT))

      Ttys and sockets are ready for reading or writing, respectively, if a
      read() or write() would not block for one or more of the following
      reasons:

           o  input data is available.

           o  output data can be accepted.

           o  an error condition exists, such as a broken pipe, no carrier,
              or a lost connection.

      Sockets select true on reads and/or exceptions if out-of-band data is
      available.

      Pipes are ready for reading if there is any data in the pipe, or if
      there are no writers left for the pipe.  Pipes are ready for writing
      if there is room for more data in the pipe AND there are one or more
      readers for the pipe, OR there are no readers left for the pipe.
      select() returns the same results for a pipe whether a file descriptor
      associated with the read-only end or the write-only end of the pipe is
      used, since both file descriptors refer to the same underlying pipe.
      So a select() of a read-only file descriptor that is associated with a
      pipe can return ready to write, even though that particular file
      descriptor cannot be written to.

 ERRORS

           [EFAULT]       One or more of the pointers was invalid.  The
                          reliable detection of this error is implementation
                          dependent.

 EXAMPLES
      The following call to select() checks if any of 4 terminals are ready
      for reading.  select() times out after 5 seconds if no terminals are
      ready for reading.  Note that the code for opening the terminals or
      reading from the terminals is not shown in this example.  Also, note
      that this example must be modified if the calling process has more
      than 32 file descriptors open.  Following this first example is an
      example of select with more than 32 file descriptors.

           #define MASK(f)     (1 << (f))
           #define NTTYS 4

           int tty[NTTYS];
           int ttymask[NTTYS];
           int readmask = 0;
           int readfds;
           int nfound, i;
           struct timeval timeout;

              /* First open each terminal for reading and put the
               * file descriptors into array tty[NTTYS].  The code
               * for opening the terminals is not shown here.
               */

           for (i=0; i < NTTYS; i++) {
              ttymask[i] = MASK(tty[i]);
              readmask |= ttymask[i];
           }

           timeout.tv_sec  = 5;
           timeout.tv_usec = 0;
           readfds = readmask;

           /* select on NTTYS+3 file descriptors if stdin, stdout
            * and stderr are also open
            */
           if ((nfound = select (NTTYS+3, &readfds, 0, 0, &timeout)) == -1)
              perror ("select failed");
           else if (nfound == 0)
              printf ("select timed out \n");
           else for (i=0; i < NTTYS; i++)
              if (ttymask[i] & readfds)
                 /* Read from tty[i].  The code for reading
                  * is not shown here.
                  */
              else printf ("tty[%d] is not ready for reading \n",i);


      The following example is the same as the previous example, except that
      it works for more than 32 open files.  Definitions for howmany,
      fd_set, and NFDBITS are in <sys/types.h>.

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

           #define MASK(f)     (1 << (f))
           #define NTTYS NOFILE - 3
           #define NWORDS  howmany(FD_SETSIZE, NFDBITS)

           int tty[NTTYS];
           int ttymask[NTTYS];
           struct fd_set readmask, readfds;
           int nfound, i, j, k;
           struct timeval timeout;

              /* First open each terminal for reading and put the
               * file descriptors into array tty[NTTYS].  The code
               * for opening the terminals is not shown here.
               */

              for (k=0; k < NWORDS; k++)
                 readmask.fds_bits[k] = 0;

              for (i=0, k=0; i < NTTYS && k < NWORDS; k++)
                 for (j=0; j < NFDBITS && i < NTTYS; j++, i++) {
                    ttymask[i] = MASK(tty[i]);
                    readmask.fds_bits[k] |= ttymask[i];
                 }

              timeout.tv_sec  = 5;
              timeout.tv_usec = 0;
              for (k=0; k < NWORDS; k++)
                 readfds.fds_bits[k] = readmask.fds_bits[k];

              /* select on NTTYS+3 file descriptors if stdin, stdout
               * and stderr are also open
               */
              if ((nfound = select (NTTYS+3, &readfds, 0, 0, &timeout)) == -1)
                 perror ("select failed");
              else if (nfound == 0)
                 printf ("select timed out \n");
              else for (i=0, k=0; i < NTTYS && k < NWORDS; k++)
                 for (j=0; j < NFDBITS && i < NTTYS; j++, i++)
                    if (ttymask[i] & readfds.fds_bits[k])
                       /* Read from tty[i].  The code for reading
                        * is not shown here.
                        */
                    else printf ("tty[%d] is not ready for reading \n",i);


 WARNINGS
      Check all references to signal(5) for appropriateness on systems that
      support sigvector().  sigvector() can affect the behavior described on
      this manpage.

      The file descriptor masks are always modified on return, even if the
      call returns as the result of a timeout.

 DEPENDENCIES
      select() supports the following devices and file types:

                o  pipes
                o  fifo special files (named pipes)
                o  all serial devices
                o  All ITEs (internal terminal emulators) and HP-HIL input
                   devices
                o  hpib(7) special files
                o  lan(7) special files
                o  pty(7) special files
                o  sockets

 AUTHOR
      select() was developed by HP and the University of California,
      Berkeley.

 SEE ALSO
      fcntl(2), read(2), write(2).


 Hewlett-Packard Company            - 4 -    HP-UX Release 10.20:  July 1996