[apple/libc.git] / gen / 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
224c7076 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
	40	.In unistd.h
	41	.Ft int
	42	.Fo pselect
	43	.Fa "int nfds"
	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"
	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
	60	.Fa errorfds
	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
68	.Vt "const struct timespec" ,
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,
79	.Fa sigmask
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 .