dlerror.3: wfix

[thirdparty/man-pages.git] / man2 / select_tut.2

.\" This manpage is copyright (C) 2001 Paul Sheer.
.\"
.\" %%%LICENSE_START(VERBATIM)
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" very minor changes, aeb
.\"
.\" Modified 5 June 2002, Michael Kerrisk <mtk.manpages@gmail.com>
.\" 2006-05-13, mtk, removed much material that is redundant with select.2
.\"             various other changes
.\" 2008-01-26, mtk, substantial changes and rewrites
.\"
.TH SELECT_TUT 2 2013-12-30 "Linux" "Linux Programmer's Manual"
.SH NAME
select, pselect, FD_CLR, FD_ISSET, FD_SET, FD_ZERO \-
synchronous I/O multiplexing
.SH SYNOPSIS
.nf
/* According to POSIX.1-2001, POSIX.1-2008 */
.br
.B #include <sys/select.h>
.sp
/* According to earlier standards */
.br
.B #include <sys/time.h>
.br
.B #include <sys/types.h>
.br
.B #include <unistd.h>
.sp
.BI "int select(int " nfds ", fd_set *" readfds ", fd_set *" writefds ,
.BI "           fd_set *" exceptfds ", struct timeval *" utimeout );
.sp
.BI "void FD_CLR(int " fd ", fd_set *" set );
.br
.BI "int  FD_ISSET(int " fd ", fd_set *" set );
.br
.BI "void FD_SET(int " fd ", fd_set *" set );
.br
.BI "void FD_ZERO(fd_set *" set );
.sp
.B #include <sys/select.h>
.sp
.BI "int pselect(int " nfds ", fd_set *" readfds ", fd_set *" writefds ,
.BI "            fd_set *" exceptfds ", const struct timespec *" ntimeout ,
.BI "            const sigset_t *" sigmask );
.fi
.sp
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.sp
.BR pselect ():
_POSIX_C_SOURCE\ >=\ 200112L || _XOPEN_SOURCE\ >=\ 600
.SH DESCRIPTION
.BR select ()
(or
.BR pselect ())
is used to efficiently monitor multiple file descriptors,
to see if any of them is, or becomes, "ready";
that is, to see whether I/O becomes possible,
or an "exceptional condition" has occurred on any of the descriptors.

Its principal arguments are three "sets" of file descriptors:
\fIreadfds\fP, \fIwritefds\fP, and \fIexceptfds\fP.
Each set is declared as type
.IR fd_set ,
and its contents can be manipulated with the macros
.BR FD_CLR (),
.BR FD_ISSET (),
.BR FD_SET (),
and
.BR FD_ZERO ().
A newly declared set should first be cleared using
.BR FD_ZERO ().
.BR select ()
modifies the contents of the sets according to the rules
described below; after calling
.BR select ()
you can test if a file descriptor is still present in a set with the
.BR FD_ISSET ()
macro.
.BR FD_ISSET ()
returns nonzero if a specified file descriptor is present in a set
and zero if it is not.
.BR FD_CLR ()
removes a file descriptor from a set.
.SS Arguments
.TP
\fIreadfds\fP
This set is watched to see if data is available for reading from any of
its file descriptors.
After
.BR select ()
has returned, \fIreadfds\fP will be
cleared of all file descriptors except for those that
are immediately available for reading.
.TP
\fIwritefds\fP
This set is watched to see if there is space to write data to any of
its file descriptors.
After
.BR select ()
has returned, \fIwritefds\fP will be
cleared of all file descriptors except for those that
are immediately available for writing.
.TP
\fIexceptfds\fP
This set is watched for "exceptional conditions".
In practice, only one such exceptional condition is common:
the availability of \fIout-of-band\fP (OOB) data for reading
from a TCP socket.
See
.BR recv (2),
.BR send (2),
and
.BR tcp (7)
for more details about OOB data.
(One other less common case where
.BR select (2)
indicates an exceptional condition occurs with pseudoterminals
in packet mode; see
.BR tty_ioctl (4).)
After
.BR select ()
has returned,
\fIexceptfds\fP will be cleared of all file descriptors except for those
for which an exceptional condition has occurred.
.TP
\fInfds\fP
This is an integer one more than the maximum of any file descriptor in
any of the sets.