[apple/libc.git] / gen / FreeBSD / pselect.3

.\"
.\" Copyright 2002 Massachusetts Institute of Technology
.\"
.\" Permission to use, copy, modify, and distribute this software and
.\" its documentation for any purpose and without fee is hereby
.\" granted, provided that both the above copyright notice and this
.\" permission notice appear in all copies, that both the above
.\" copyright notice and this permission notice appear in all
.\" supporting documentation, and that the name of M.I.T. not be used
.\" in advertising or publicity pertaining to distribution of the
.\" software without specific, written prior permission.  M.I.T. makes
.\" no representations about the suitability of this software for any
.\" purpose.  It is provided "as is" without express or implied
.\" warranty.
.\"
.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''.  M.I.T. DISCLAIMS
.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 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
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc/gen/pselect.3,v 1.4 2002/12/18 10:13:54 ru Exp $
.\"
.Dd June 16, 2002
.Dt PSELECT 3
.Os
.Sh NAME
.Nm pselect
.Nd synchronous I/O multiplexing a la POSIX.1g
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In unistd.h
.Ft int
.Fo pselect
.Fa "int nfds"
.Fa "fd_set *restrict readfds"
.Fa "fd_set *restrict writefds"
.Fa "fd_set *restrict errorfds"
.Fa "const struct timespec *restrict timeout"
.Fa "const sigset_t *restrict sigmask"
.Fc
.Sh DESCRIPTION
The
.Fn pselect
function was introduced by
.St -p1003.1g-2000
as a slightly stronger version of
.Xr select 2 .
The
.Fa nfds , readfds , writefds ,
and
.Fa errorfds
arguments are all identical to the analogous arguments of
.Fn select .
The
.Fa timeout
argument in
.Fn pselect
points to a
.Vt "const struct timespec" ,
rather than the (modifiable)
.Vt "struct timeval"
used by
.Fn select ;
as in
.Fn select ,
a null pointer may be passed to indicate that
.Fn pselect
should wait indefinitely.
Finally,
.Fa sigmask
specifies a signal mask which is set while waiting for input.
When
.Fn pselect
returns, the original signal mask is restored.
.Pp
See
.Xr select 2
for a more detailed discussion of the semantics of this interface, and
for macros used to manipulate the
.Vt "fd_set"
data type.
.Sh IMPLEMENTATION NOTES
The
.Fn pselect
function is implemented in the C library as a wrapper around
.Fn select .
.Sh RETURN VALUES
The
.Fn pselect
function returns the same values and under the same conditions as
.Fn select .
.Sh ERRORS
The
.Fn pselect
function may fail for any of the reasons documented for
.Xr select 2
and (if a signal mask is provided)
.Xr sigprocmask 2 .
.Sh SEE ALSO
.Xr kqueue 2 ,
.Xr poll 2 ,
.Xr select 2 ,
.Xr sigprocmask 2
.Sh STANDARDS
The
.Fn pselect
function conforms to
.St -p1003.1-2001 .
.Sh HISTORY
The
.Fn pselect
function first appeared in
.Fx 5.0 .
.Sh AUTHORS
The
.Fn pselect
function and this manual page were written by
.An Garrett Wollman Aq wollman@FreeBSD.org .
Commit	Line	Data
9385eb3d A	1	.\"
	2	.\" Copyright 2002 Massachusetts Institute of Technology
	3	.\"
	4	.\" Permission to use, copy, modify, and distribute this software and
	5	.\" its documentation for any purpose and without fee is hereby
	6	.\" granted, provided that both the above copyright notice and this
	7	.\" permission notice appear in all copies, that both the above
	8	.\" copyright notice and this permission notice appear in all
	9	.\" supporting documentation, and that the name of M.I.T. not be used
	10	.\" in advertising or publicity pertaining to distribution of the
	11	.\" software without specific, written prior permission. M.I.T. makes
	12	.\" no representations about the suitability of this software for any
	13	.\" purpose. It is provided "as is" without express or implied
	14	.\" warranty.
	15	.\"
	16	.\" THIS SOFTWARE IS PROVIDED BY M.I.T. ``AS IS''. M.I.T. DISCLAIMS
	17	.\" ALL EXPRESS OR IMPLIED WARRANTIES WITH REGARD TO THIS SOFTWARE,
	18	.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
	19	.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT
	20	.\" SHALL M.I.T. BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
	21	.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
	22	.\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
	23	.\" USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
	24	.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
	25	.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
	26	.\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	27	.\" SUCH DAMAGE.
	28	.\"
	29	.\" $FreeBSD: src/lib/libc/gen/pselect.3,v 1.4 2002/12/18 10:13:54 ru Exp $
	30	.\"
	31	.Dd June 16, 2002
	32	.Dt PSELECT 3
	33	.Os
	34	.Sh NAME
	35	.Nm pselect
	36	.Nd synchronous I/O multiplexing a la POSIX.1g
	37	.Sh LIBRARY
	38	.Lb libc
	39	.Sh SYNOPSIS
ad3c9f2a	40	.In unistd.h
9385eb3d A	41	.Ft int
	42	.Fo pselect
	43	.Fa "int nfds"
ad3c9f2a A	44	.Fa "fd_set *restrict readfds"
	45	.Fa "fd_set *restrict writefds"
	46	.Fa "fd_set *restrict errorfds"
	47	.Fa "const struct timespec *restrict timeout"
	48	.Fa "const sigset_t *restrict sigmask"
9385eb3d A	49	.Fc
	50	.Sh DESCRIPTION
	51	The
	52	.Fn pselect
	53	function was introduced by
	54	.St -p1003.1g-2000
	55	as a slightly stronger version of
	56	.Xr select 2 .
	57	The
	58	.Fa nfds , readfds , writefds ,
	59	and
ad3c9f2a	60	.Fa errorfds
9385eb3d A	61	arguments are all identical to the analogous arguments of
	62	.Fn select .
	63	The
	64	.Fa timeout
	65	argument in
	66	.Fn pselect
	67	points to a
ad3c9f2a	68	.Vt "const struct timespec" ,
9385eb3d A	69	rather than the (modifiable)
	70	.Vt "struct timeval"
	71	used by
	72	.Fn select ;
	73	as in
	74	.Fn select ,
	75	a null pointer may be passed to indicate that
	76	.Fn pselect
	77	should wait indefinitely.
	78	Finally,
ad3c9f2a	79	.Fa sigmask
9385eb3d A	80	specifies a signal mask which is set while waiting for input.
	81	When
	82	.Fn pselect
	83	returns, the original signal mask is restored.
	84	.Pp
	85	See
	86	.Xr select 2
	87	for a more detailed discussion of the semantics of this interface, and
	88	for macros used to manipulate the
	89	.Vt "fd_set"
	90	data type.
	91	.Sh IMPLEMENTATION NOTES
	92	The
	93	.Fn pselect
	94	function is implemented in the C library as a wrapper around
	95	.Fn select .
	96	.Sh RETURN VALUES
	97	The
	98	.Fn pselect
	99	function returns the same values and under the same conditions as
	100	.Fn select .
	101	.Sh ERRORS
	102	The
	103	.Fn pselect
	104	function may fail for any of the reasons documented for
	105	.Xr select 2
	106	and (if a signal mask is provided)
	107	.Xr sigprocmask 2 .
	108	.Sh SEE ALSO
	109	.Xr kqueue 2 ,
	110	.Xr poll 2 ,
	111	.Xr select 2 ,
	112	.Xr sigprocmask 2
	113	.Sh STANDARDS
	114	The
	115	.Fn pselect
	116	function conforms to
	117	.St -p1003.1-2001 .
	118	.Sh HISTORY
	119	The
	120	.Fn pselect
	121	function first appeared in
	122	.Fx 5.0 .
	123	.Sh AUTHORS
	124	The
	125	.Fn pselect
	126	function and this manual page were written by
	127	.An Garrett Wollman Aq wollman@FreeBSD.org .