Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SELECT(2)		   Linux Programmer's Manual		     SELECT(2)

NAME
       select,	pselect,  FD_CLR,  FD_ISSET, FD_SET, FD_ZERO - synchronous I/O
       multiplexing

SYNOPSIS
       /* According to POSIX 1003.1-2001 */
       #include	<sys/select.h>

       /* According to earlier standards */
       #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 *ex-
       ceptfds,	const struct timespec *timeout,	const 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  pselect  uses  a	struct
	      timespec (with seconds and nanoseconds).

       (ii)   The select function may update the timeout parameter 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 ps-
	      elect 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 read-
       ing (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  use-
       ful after select	returns.

       n is the	highest-numbered descriptor in any of the three	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	timeout	is NULL	(no timeout), select can block
       indefinitely.

       sigmask is a pointer to a signal	mask (see sigprocmask(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.	(Suppose the signal handler sets a global flag
       and returns. Then a test	of this	global flag followed by	a call of  se-
       lect()  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.

   The timeout
       The time	structures involved are	defined	in _sys/time.h_	and look like

	      struct timeval {
		  long	  tv_sec;	  /* seconds */
		  long	  tv_usec;	  /* microseconds */
	      };

       and

	      struct timespec {
		  long	  tv_sec;	  /* seconds */
		  long	  tv_nsec;	  /* nanoseconds */
	      };

       (However, see below on the POSIX	1003.1-2001 versions.)

       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	preci-
       sion.

       On Linux, the function select modifies timeout to reflect the amount of
       time not	slept; most other implementations do not do this.  This	causes
       problems	both when Linux	code which reads timeout is  ported  to	 other
       operating  systems,  and	 when  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.

RETURN VALUE
       On  success,  select  and pselect return	the number of descriptors con-
       tained in the descriptor	sets, which may	be zero	if the timeout expires
       before anything interesting happens.  On	error, -1 is returned, and er-
       rno 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.

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");

	   return 0;
       }

CONFORMING TO
       4.4BSD  (the select function first appeared in 4.2BSD).	Generally por-
       table to/from non-BSD systems supporting	clones of the BSD socket layer
       (including System V variants).  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),
       and part	of POSIX 1003.1-2001.  It is  found  in	 glibc2.1  and	later.
       Glibc2.0	 has  a	 function with this name, that however does not	take a
       sigmask parameter.

NOTES
       Concerning the types involved, the classical situation is that the  two
       fields  of  a struct timeval are	longs (as shown	above),	and the	struct
       is defined in _sys/time.h_.  The	POSIX 1003.1-2001 situation is

	      struct timeval {
		  time_t	 tv_sec;     /*	seconds	*/
		  suseconds_t	 tv_usec;    /*	microseconds */
	      };

       where the struct	is defined in _sys/select.h_ and the data types	time_t
       and suseconds_t are defined in _sys/types.h_.

       Concerning  prototypes,	the classical situation	is that	one should in-
       clude _time.h_ for select.  The POSIX 1003.1-2001 situation is that one
       should  include _sys/select.h_ for select and pselect.  Libc4 and libc5
       do not have a _sys/select.h_ header; under glibc	 2.0  and  later  this
       header exists.  Under glibc 2.0 it unconditionally gives	the wrong pro-
       totype for  pselect,  under  glibc  2.1-2.2.1  it  gives	 pselect  when
       _GNU_SOURCE  is	defined,  under	 glibc	2.2.2-2.2.4  it	 gives it when
       _XOPEN_SOURCE is	defined	and has	a value	of 600 or larger.   No	doubt,
       since POSIX 1003.1-2001,	it should give the prototype by	default.

SEE ALSO
       For a tutorial with discussion and examples, see	select_tut(2).

       For vaguely related stuff, see accept(2), connect(2), poll(2), read(2),
       recv(2),	send(2), sigprocmask(2), write(2)

Linux 2.4			  2001-02-09			     SELECT(2)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUE | ERRORS | EXAMPLE | CONFORMING TO | NOTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=select&sektion=2&manpath=Red+Hat+9>

home | help