.\" $OpenBSD: select.2,v 1.20 2001/09/04 08:04:08 deraadt Exp $
|
.\" $OpenBSD: select.2,v 1.20 2001/09/04 08:04:08 deraadt Exp $
|
.\" $NetBSD: select.2,v 1.5 1995/06/27 22:32:28 cgd Exp $
|
.\" $NetBSD: select.2,v 1.5 1995/06/27 22:32:28 cgd Exp $
|
.\"
|
.\"
|
.\" Copyright (c) 1983, 1991, 1993
|
.\" Copyright (c) 1983, 1991, 1993
|
.\" The Regents of the University of California. All rights reserved.
|
.\" The Regents of the University of California. All rights reserved.
|
.\"
|
.\"
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" Redistribution and use in source and binary forms, with or without
|
.\" modification, are permitted provided that the following conditions
|
.\" modification, are permitted provided that the following conditions
|
.\" are met:
|
.\" are met:
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" 1. Redistributions of source code must retain the above copyright
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" notice, this list of conditions and the following disclaimer.
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" notice, this list of conditions and the following disclaimer in the
|
.\" documentation and/or other materials provided with the distribution.
|
.\" documentation and/or other materials provided with the distribution.
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" 3. All advertising materials mentioning features or use of this software
|
.\" must display the following acknowledgement:
|
.\" must display the following acknowledgement:
|
.\" This product includes software developed by the University of
|
.\" This product includes software developed by the University of
|
.\" California, Berkeley and its contributors.
|
.\" California, Berkeley and its contributors.
|
.\" 4. Neither the name of the University nor the names of its contributors
|
.\" 4. Neither the name of the University nor the names of its contributors
|
.\" may be used to endorse or promote products derived from this software
|
.\" may be used to endorse or promote products derived from this software
|
.\" without specific prior written permission.
|
.\" without specific prior written permission.
|
.\"
|
.\"
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
.\" SUCH DAMAGE.
|
.\" SUCH DAMAGE.
|
.\"
|
.\"
|
.\" @(#)select.2 8.2 (Berkeley) 3/25/94
|
.\" @(#)select.2 8.2 (Berkeley) 3/25/94
|
.\"
|
.\"
|
.Dd March 25, 1994
|
.Dd March 25, 1994
|
.Dt SELECT 2
|
.Dt SELECT 2
|
.Os
|
.Os
|
.Sh NAME
|
.Sh NAME
|
.Nm select
|
.Nm select
|
.Nd synchronous I/O multiplexing
|
.Nd synchronous I/O multiplexing
|
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Fd #include
|
.Ft int
|
.Ft int
|
.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout"
|
.Fn select "int nfds" "fd_set *readfds" "fd_set *writefds" "fd_set *exceptfds" "struct timeval *timeout"
|
.Fn FD_SET fd &fdset
|
.Fn FD_SET fd &fdset
|
.Fn FD_CLR fd &fdset
|
.Fn FD_CLR fd &fdset
|
.Fn FD_ISSET fd &fdset
|
.Fn FD_ISSET fd &fdset
|
.Fn FD_ZERO &fdset
|
.Fn FD_ZERO &fdset
|
.Sh DESCRIPTION
|
.Sh DESCRIPTION
|
.Fn select
|
.Fn select
|
examines the I/O descriptor sets whose addresses are passed in
|
examines the I/O descriptor sets whose addresses are passed in
|
.Fa readfds ,
|
.Fa readfds ,
|
.Fa writefds ,
|
.Fa writefds ,
|
and
|
and
|
.Fa exceptfds
|
.Fa exceptfds
|
to see if some of their descriptors
|
to see if some of their descriptors
|
are ready for reading, are ready for writing, or have an exceptional
|
are ready for reading, are ready for writing, or have an exceptional
|
condition pending, respectively.
|
condition pending, respectively.
|
The first
|
The first
|
.Fa nfds
|
.Fa nfds
|
descriptors are checked in each set;
|
descriptors are checked in each set;
|
i.e., the descriptors from 0 through
|
i.e., the descriptors from 0 through
|
.Fa nfds Ns No -1
|
.Fa nfds Ns No -1
|
in the descriptor sets are examined.
|
in the descriptor sets are examined.
|
On return,
|
On return,
|
.Fn select
|
.Fn select
|
replaces the given descriptor sets
|
replaces the given descriptor sets
|
with subsets consisting of those descriptors that are ready
|
with subsets consisting of those descriptors that are ready
|
for the requested operation.
|
for the requested operation.
|
.Fn select
|
.Fn select
|
returns the total number of ready descriptors in all the sets.
|
returns the total number of ready descriptors in all the sets.
|
.Pp
|
.Pp
|
The descriptor sets are stored as bit fields in arrays of integers.
|
The descriptor sets are stored as bit fields in arrays of integers.
|
The following macros are provided for manipulating such descriptor sets:
|
The following macros are provided for manipulating such descriptor sets:
|
.Fn FD_ZERO &fdset
|
.Fn FD_ZERO &fdset
|
initializes a descriptor set
|
initializes a descriptor set
|
.Fa fdset
|
.Fa fdset
|
to the null set.
|
to the null set.
|
.Fn FD_SET fd &fdset
|
.Fn FD_SET fd &fdset
|
includes a particular descriptor
|
includes a particular descriptor
|
.Fa fd
|
.Fa fd
|
in
|
in
|
.Fa fdset .
|
.Fa fdset .
|
.Fn FD_CLR fd &fdset
|
.Fn FD_CLR fd &fdset
|
removes
|
removes
|
.Fa fd
|
.Fa fd
|
from
|
from
|
.Fa fdset .
|
.Fa fdset .
|
.Fn FD_ISSET fd &fdset
|
.Fn FD_ISSET fd &fdset
|
is non-zero if
|
is non-zero if
|
.Fa fd
|
.Fa fd
|
is a member of
|
is a member of
|
.Fa fdset ,
|
.Fa fdset ,
|
zero otherwise.
|
zero otherwise.
|
The behavior of these macros is undefined if
|
The behavior of these macros is undefined if
|
a descriptor value is less than zero or greater than or equal to
|
a descriptor value is less than zero or greater than or equal to
|
.Dv FD_SETSIZE ,
|
.Dv FD_SETSIZE ,
|
which is normally at least equal
|
which is normally at least equal
|
to the maximum number of descriptors supported by the system.
|
to the maximum number of descriptors supported by the system.
|
.Pp
|
.Pp
|
If
|
If
|
.Fa timeout
|
.Fa timeout
|
is a non-null pointer, it specifies a maximum interval to wait for the
|
is a non-null pointer, it specifies a maximum interval to wait for the
|
selection to complete.
|
selection to complete.
|
If
|
If
|
.Fa timeout
|
.Fa timeout
|
is a null pointer, the select blocks indefinitely.
|
is a null pointer, the select blocks indefinitely.
|
To effect a poll, the
|
To effect a poll, the
|
.Fa timeout
|
.Fa timeout
|
argument should be non-null, pointing to a zero-valued timeval structure.
|
argument should be non-null, pointing to a zero-valued timeval structure.
|
.Fa timeout
|
.Fa timeout
|
is not changed by
|
is not changed by
|
.Fn select ,
|
.Fn select ,
|
and may be reused on subsequent calls; however, it is good style to
|
and may be reused on subsequent calls; however, it is good style to
|
re-initialize it before each invocation of
|
re-initialize it before each invocation of
|
.Fn select .
|
.Fn select .
|
.Pp
|
.Pp
|
Any of
|
Any of
|
.Fa readfds ,
|
.Fa readfds ,
|
.Fa writefds ,
|
.Fa writefds ,
|
and
|
and
|
.Fa exceptfds
|
.Fa exceptfds
|
may be given as null pointers if no descriptors are of interest.
|
may be given as null pointers if no descriptors are of interest.
|
.Sh RETURN VALUES
|
.Sh RETURN VALUES
|
.Fn select
|
.Fn select
|
returns the number of ready descriptors that are contained in
|
returns the number of ready descriptors that are contained in
|
the descriptor sets, or \-1 is an error occurred.
|
the descriptor sets, or \-1 is an error occurred.
|
If the time limit expires,
|
If the time limit expires,
|
.Fn select
|
.Fn select
|
returns 0.
|
returns 0.
|
If
|
If
|
.Fn select
|
.Fn select
|
returns with an error, including one due to an interrupted call,
|
returns with an error, including one due to an interrupted call,
|
the descriptor sets will be unmodified.
|
the descriptor sets will be unmodified.
|
.Sh ERRORS
|
.Sh ERRORS
|
An error return from
|
An error return from
|
.Fn select
|
.Fn select
|
indicates:
|
indicates:
|
.Bl -tag -width Er
|
.Bl -tag -width Er
|
.It Bq Er EFAULT
|
.It Bq Er EFAULT
|
One or more of
|
One or more of
|
.Fa readfds ,
|
.Fa readfds ,
|
.Fa writefds ,
|
.Fa writefds ,
|
or
|
or
|
.Fa exceptfds
|
.Fa exceptfds
|
points outside the process's allocated address space.
|
points outside the process's allocated address space.
|
.It Bq Er EBADF
|
.It Bq Er EBADF
|
One of the descriptor sets specified an invalid descriptor.
|
One of the descriptor sets specified an invalid descriptor.
|
.It Bq Er EINTR
|
.It Bq Er EINTR
|
A signal was delivered before the time limit expired and
|
A signal was delivered before the time limit expired and
|
before any of the selected events occurred.
|
before any of the selected events occurred.
|
.It Bq Er EINVAL
|
.It Bq Er EINVAL
|
The specified time limit is invalid.
|
The specified time limit is invalid.
|
One of its components is negative or too large.
|
One of its components is negative or too large.
|
.El
|
.El
|
.Sh SEE ALSO
|
.Sh SEE ALSO
|
.Xr accept 2 ,
|
.Xr accept 2 ,
|
.Xr connect 2 ,
|
.Xr connect 2 ,
|
.Xr gettimeofday 2 ,
|
.Xr gettimeofday 2 ,
|
.Xr poll 2 ,
|
.Xr poll 2 ,
|
.Xr read 2 ,
|
.Xr read 2 ,
|
.Xr recv 2 ,
|
.Xr recv 2 ,
|
.Xr send 2 ,
|
.Xr send 2 ,
|
.Xr write 2 ,
|
.Xr write 2 ,
|
.Xr getdtablesize 3
|
.Xr getdtablesize 3
|
.Sh BUGS
|
.Sh BUGS
|
Although the provision of
|
Although the provision of
|
.Xr getdtablesize 3
|
.Xr getdtablesize 3
|
was intended to allow user programs to be written independent
|
was intended to allow user programs to be written independent
|
of the kernel limit on the number of open files, the dimension
|
of the kernel limit on the number of open files, the dimension
|
of a sufficiently large bit field for select remains a problem.
|
of a sufficiently large bit field for select remains a problem.
|
The default bit size of
|
The default bit size of
|
.Ft fd_set
|
.Ft fd_set
|
is based on the symbol
|
is based on the symbol
|
.Dv FD_SETSIZE
|
.Dv FD_SETSIZE
|
(currently 256),
|
(currently 256),
|
but that is somewhat smaller than the current kernel limit
|
but that is somewhat smaller than the current kernel limit
|
to the number of open files.
|
to the number of open files.
|
However, in order to accommodate programs which might potentially
|
However, in order to accommodate programs which might potentially
|
use a larger number of open files with select, it is possible
|
use a larger number of open files with select, it is possible
|
to increase this size within a program by providing
|
to increase this size within a program by providing
|
a larger definition of
|
a larger definition of
|
.Dv FD_SETSIZE
|
.Dv FD_SETSIZE
|
before the inclusion of
|
before the inclusion of
|
.Aq Pa sys/types.h .
|
.Aq Pa sys/types.h .
|
The kernel will cope, and the userland libraries provided with the
|
The kernel will cope, and the userland libraries provided with the
|
system are also ready for large numbers of file descriptors.
|
system are also ready for large numbers of file descriptors.
|
.Pp
|
.Pp
|
Alternatively, to be really safe, it is possible to allocate
|
Alternatively, to be really safe, it is possible to allocate
|
.Ft fd_set
|
.Ft fd_set
|
bit-arrays dynamically.
|
bit-arrays dynamically.
|
The idea is to permit a program to work properly even if it is
|
The idea is to permit a program to work properly even if it is
|
.Xr execve 2 Ns 'd
|
.Xr execve 2 Ns 'd
|
with 4000 file descriptors pre-allocated.
|
with 4000 file descriptors pre-allocated.
|
The following illustrates the technique which is used by
|
The following illustrates the technique which is used by
|
userland libraries:
|
userland libraries:
|
.Pp
|
.Pp
|
.Bd -literal -offset indent -compact
|
.Bd -literal -offset indent -compact
|
fd_set *fdsr;
|
fd_set *fdsr;
|
int max = fd;
|
int max = fd;
|
|
|
fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
|
fdsr = (fd_set *)calloc(howmany(max+1, NFDBITS),
|
sizeof(fd_mask));
|
sizeof(fd_mask));
|
if (fdsr == NULL) {
|
if (fdsr == NULL) {
|
...
|
...
|
return (-1);
|
return (-1);
|
}
|
}
|
FD_SET(fd, fdsr);
|
FD_SET(fd, fdsr);
|
n = select(max+1, fdsr, NULL, NULL, &tv);
|
n = select(max+1, fdsr, NULL, NULL, &tv);
|
...
|
...
|
free(fdsr);
|
free(fdsr);
|
.Ed
|
.Ed
|
.Pp
|
.Pp
|
Alternatively, it is possible to use the
|
Alternatively, it is possible to use the
|
.Xr poll 2
|
.Xr poll 2
|
interface.
|
interface.
|
.Xr poll 2
|
.Xr poll 2
|
is more efficient when the size of
|
is more efficient when the size of
|
.Fn select Ns 's
|
.Fn select Ns 's
|
.Ft fd_set
|
.Ft fd_set
|
bit-arrays are very large, and for fixed numbers of
|
bit-arrays are very large, and for fixed numbers of
|
file descriptors one need not size and dynamically allocate a
|
file descriptors one need not size and dynamically allocate a
|
memory object.
|
memory object.
|
.Pp
|
.Pp
|
.Fn select
|
.Fn select
|
should probably have been designed to return the time remaining from the
|
should probably have been designed to return the time remaining from the
|
original timeout, if any, by modifying the time value in place.
|
original timeout, if any, by modifying the time value in place.
|
Even though some systems stupidly act in this different way, it is
|
Even though some systems stupidly act in this different way, it is
|
unlikely this semantic will ever be commonly implemented, as the
|
unlikely this semantic will ever be commonly implemented, as the
|
change causes massive source code compatibility problems.
|
change causes massive source code compatibility problems.
|
Furthermore, recent new standards have dictated the current behaviour.
|
Furthermore, recent new standards have dictated the current behaviour.
|
In general, due to the existence of those brain-damaged
|
In general, due to the existence of those brain-damaged
|
non-conforming systems, it is unwise to assume that the timeout
|
non-conforming systems, it is unwise to assume that the timeout
|
value will be unmodified by the
|
value will be unmodified by the
|
.Fn select
|
.Fn select
|
call, and the caller should reinitialize it on each invocation.
|
call, and the caller should reinitialize it on each invocation.
|
Calculating the delta is easily done by calling
|
Calculating the delta is easily done by calling
|
.Xr gettimeofday 2
|
.Xr gettimeofday 2
|
before and after the call to
|
before and after the call to
|
.Fn select Ns ,
|
.Fn select Ns ,
|
and using
|
and using
|
.Fn timersub
|
.Fn timersub
|
(as described in
|
(as described in
|
.Xr getitimer 2 ) .
|
.Xr getitimer 2 ) .
|
.Pp
|
.Pp
|
Internally to the kernel,
|
Internally to the kernel,
|
.Fn select
|
.Fn select
|
works poorly if multiple processes wait on the same file descriptor.
|
works poorly if multiple processes wait on the same file descriptor.
|
Given that, it is rather surprising to see that many daemons are
|
Given that, it is rather surprising to see that many daemons are
|
written that way (i.e.,
|
written that way (i.e.,
|
.Xr httpd 8 ) .
|
.Xr httpd 8 ) .
|
.Sh HISTORY
|
.Sh HISTORY
|
The
|
The
|
.Fn select
|
.Fn select
|
function call appeared in
|
function call appeared in
|
.Bx 4.2 .
|
.Bx 4.2 .
|
|
|
