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

FreeBSD Manual Pages

  
 
  

home | help
select(3C)		 Standard C Library Functions		    select(3C)

NAME
       select,	FD_SET,	FD_CLR,	FD_ISSET, FD_ZERO - synchronous	I/O multiplex-
       ing

SYNOPSIS
       #include	<sys/time.h>

       int select(int nfds, fd_set *readfds,  fd_set  *writefds,  fd_set  *er-
       rorfds, struct timeval *timeout);

       void FD_SET(int fd, fd_set *fdset);

       void FD_CLR(int fd, fd_set *fdset);

       int FD_ISSET(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	inter-
       val,  until  the	 specified  condition  is true for at least one	of the
       specified file descriptors.

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

       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 de-
       scriptors 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 success-
       fully and returns 0.

       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 sig-
       nal.

       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 de-
       scriptors, the objects pointed to by the	readfs,	writefs, and  errorfds
       arguments have all bits set to 0.

       A  file	descriptor for a socket	that is	listening for connections will
       indicate	that it	is ready for reading, when connections are  available.
       A  file	descriptor for a socket	that is	connecting asynchronously will
       indicate	that it	is ready for writing, when a connection	has  been  es-
       tablished.

       Selecting  true	for  reading  on a socket descriptor upon which	a lis-
       ten(3SOCKET) call has been performed indicates that  a  subsequent  ac-
       cept(3SOCKET) call on that descriptor will not block.

       File descriptor masks of	type fd_set can	be initialized and tested with
       the macros FD_CLR(), FD_ISSET(),	FD_SET(), and FD_ZERO().

       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	other-
	     wise.

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

       FD_ZERO(&fdset)
	     Initializes the file descriptor set fdset to have zero  bits  for
	     all file descriptors.

       The  behavior  of  these	macros is undefined if the fd argument is less
       than 0 or greater than or equal to FD_SETSIZE.

RETURN VALUES
       The FD_CLR(), FD_SET(), and FD_ZERO()  macros  return  no  value.   The
       FD_ISSET()  macro  returns a non-zero value if the bit for the file de-
       scriptor	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	 indi-
       cate the	error.

ERRORS
       The select() function will fail if:

       EBADF One or more of the	file descriptor	sets specified a file descrip-
	     tor 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 im-
	     plementation-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 FD_SETSIZE.

       EINVAL
	     One  of the specified file	descriptors refers to a	STREAM or mul-
	     tiplexer that is linked (directly or indirectly) downstream  from
	     a multiplexer.

       EINVAL
	     A	component  of the pointed-to time limit	is outside the accept-
	     able range: t_sec must  be	 between  0  and  10 **8 ,  inclusive.
	     t_usec must be greater than or equal to 0,	and less than 10**6.

USAGE
       The  poll(2)  function is preferred over	this function. It must be used
       when the	number of file descriptors exceeds  FD_SETSIZE.

       The use of a timeout does not affect  any  pending  timers  set	up  by
       alarm(2), ualarm(3C) or setitimer(2).

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

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |MT-Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       alarm(2),  fcntl(2),  poll(2),  read(2),	 setitimer(2),	write(2),  ac-
       cept(3SOCKET), listen(3SOCKET), ualarm(3C), attributes(5)

NOTES
       The  default  value  for	FD_SETSIZE (currently 1024) is larger than the
       default limit on	the number of open files. To accommodate 32-bit	appli-
       cations	that  wish to use a larger number of open files	with select(),
       it is possible to increase this size at compile	time  by  providing  a
       larger definition of FD_SETSIZE before the inclusion of any system-sup-
       plied header. The maximum supported size	for FD_SETSIZE is  65536.  The
       default value is	already	65536 for 64-bit applications.

SunOS 5.9			  31 Oct 2000			    select(3C)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | USAGE | ATTRIBUTES | SEE ALSO | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=select&sektion=3c&manpath=SunOS+5.9>

home | help