unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



select(2)							    select(2)



NAME
  select - Synchronous I/O multiplexing

SYNOPSIS

  #include <&lt;sys/time.h>&gt;

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

  void FD_CLR(
	  int fd,
	  fd_set *fdset);

  int FD_ISSET(
	  int fd,
	  fd_set *fdset);

  void FD_SET(
	  int fd,
	  fd_set *fdset);

  void FD_ZERO(
	  fd_set *fdset);

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  select():  XSH5.0, XNS5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  nfds	    Specifies the number of open objects that may be ready for read-
	    ing	or writing or that have	exceptions pending.  The nfds parame-
	    ter	cannot be greater than FD_SETSIZE.

  readfds   Points to an I/O descriptor	set consisting of file descriptors of
	    objects opened for reading.	When the readfds parameter is a	null
	    pointer, the read I/O descriptor set is ignored by the select()
	    function.

  writefds  Points to an I/O descriptor	set consisting of file descriptors
	    for	objects	opened for writing.  When the writefds parameter is a
	    null pointer, the write I/O	descriptor set is ignored.

  exceptfds Points to an I/O descriptor	set consisting of file descriptors
	    for	objects	opened for reading or writing that have	an exception
	    pending.  When the exceptfds parameter is a	null pointer, the
	    exception I/O descriptor set is ignored.

  timeout   Points to a	type timeval structure that specifies the maximum
	    time to wait for a response	to a select() function.	 When the
	    timeout parameter has a nonzero value, the maximum time interval
	    to wait for	the select() function to complete is specified by
	    values stored in space reserved by the type	timeval	structure
	    pointed to by the timeout parameter.

	    When the timeout parameter is a null pointer, the select() func-
	    tion blocks	indefinitely.  To poll,	the timeout parameter should
	    be specified as a nonzero value and	point to a zero-valued
	    timeval structure.

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

  fd	    Specifies a	file descriptor.

  fdset	    Points to an I/O descriptor	set.

DESCRIPTION
  The select() function	checks the status of objects identified	by bit masks
  called I/O descriptor	sets.  Each I/O	descriptor set consists	of an array
  of bits whose	relative position and state represent a	file descriptor	and
  the status of	its corresponding object.  There is an I/O descriptor set for
  reading, writing, and	for pending exceptions.	 These I/O descriptor sets
  are pointed to by the	readfds, writefds, and exceptfds parameters, respec-
  tively.  The I/O descriptor sets provide a means of monitoring the read,
  write, and exception status of objects represented by	file descriptors.

  The status of	nfds-1 file descriptors	in each	referenced I/O descriptor set
  is checked when the select() function	is called.  The	select() function
  returns a modified I/O descriptor set, which has the following characteris-
  tics:	for any	selected I/O descriptor	set pointed to by the readfds, wri-
  tefds, and exceptfds parameters, if the state	of any bit corresponding with
  an active file descriptor is set on entry, when the object represented by
  the set bit is ready for reading, writing, or	its exception condition	has
  been satisfied, a corresponding bit position is also set in the returned
  I/O descriptor set pointed to	by the readfds,	writefds, or exceptfds param-
  eters.

  When it returns successfully,	select() does the following: First, it
  replaces the original	I/O descriptor sets with the corresponding I/O
  descriptor sets (that	have a set bit for each	file descriptor	representing
  those	objects	that are ready for the requested operation).  Second, it
  returns the total number of ready objects represented	by set bits in all
  the I/O descriptor sets.

  Note:	 When objects are ready	for the	requested operation, the operation
  will not block.  This	does not necessarily mean, however, that data is
  available for	the operation.	See read(2) and	write(2) for information on
  when these calls would block.

  After	an I/O descriptor set is created, it may be modified with the follow-
  ing macros:

  FD_CLR(fd, &&amp;fdset)
	    Clears the I/O descriptor bit specified by file descriptor fd in
	    the	I/O descriptor set addressed by	fdset.

  FD_ISSET(fd, &&amp;fdset)
	    Returns a nonzero value when the I/O descriptor bit	for fd is
	    included in	the I/O	descriptor set addressed by fdset.  Otherwise
	    0 (zero) is	returned.

  FD_SET(fd, &&amp;fdset)
	    Includes the particular I/O	descriptor bit specified by fd in the
	    I/O	descriptor set addressed by fdset.

  FD_ZERO(&&amp;fdset)
	    Initializes	the I/O	descriptor set addressed by fdset to a null
	    value.

  The behavior of these	macros is undefined when parameter fd has a value
  less than 0 (zero) or	greater	than or	equal to FD_SETSIZE, which is nor-
  mally	at least equal to the maximum number of	file descriptors supported by
  the system.

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

  For sockets, a file descriptor for a socket that is listening	for connec-
  tions	indicates that it is ready for reading when connections	are avail-
  able.	 A file	descriptor for a socket	that is	connecting asynchronously
  indicates that it is ready for writing after a connection is established.

NOTES

  This function	supports up to 64K open	file descriptors per process if	that
  capability is	enabled.  If not already defined, FD_SETSIZE is	set in the
  <&lt;sys/select.h>&gt; header	file to	be 4K.

  New applications can use any of these	features for processes using more
  than 4K open file descriptors.  When they do so, however, they must specify
  an alternate value for FD_SETSIZE--one that does not exceed 64K--before
  they include <&lt;sys/select.h>&gt; in a program to be compiled.

RETURN VALUES

  Upon successful completion, the select() function returns the	number of
  ready	objects	represented by corresponding file descriptor bits in the I/O
  descriptor sets.  When an error occurs, -1 is	returned and errno is set to
  indicate the error.

  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	(zero).

  When select()	returns	an error, including a process interrupt, the I/O
  descriptor sets pointed to by	the readfds, writefds, and exceptfds parame-
  ters remain unmodified.

ERRORS

  The select() function	sets errno to the specified values for the following
  conditions:

  [EBADF]   One	or more	of the I/O descriptor sets specified an	invalid	file
	    descriptor.

  [EINTR]   A signal was delivered before the time limit specified by the
	    timeout parameter expired and before any of	the selected events
	    occurred.

  [EINVAL]  The	time limit specified by	the timeout parameter is invalid.

	    The	nfds parameter is less than 0, or greater than or equal	to
	    FD_SETSIZE.

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

  [EAGAIN]  [Tru64 UNIX]  Allocation of	internal data structures failed.  A
	    later call to the select() function	may complete successfully.

RELATED	INFORMATION

  Functions: accept(2),	connect(2), getdtablesize(2), poll(2) read(2),
  recv(2), send(2), setsysinfo(2), write(2)

  Standards: standards(5)