gitweb.dragonflybsd.org Git - dragonfly.git/blame_incremental

... / ...

Commit	Line	Data
	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	.\" $DragonFly: src/lib/libc/sys/pselect.2,v 1.2 2008/01/12 07:09:41 swildner Exp $
	30	.\"
	31	.Dd December 24, 2007
	32	.Dt PSELECT 2
	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 sys/select.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 exceptfds"
	47	.Fa "const struct timespec * restrict timeout"
	48	.Fa "const sigset_t * restrict newsigmask"
	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 exceptfds
	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 newsigmask
	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 RETURN VALUES
	92	The
	93	.Fn pselect
	94	function returns the same values and under the same conditions as
	95	.Fn select .
	96	.Sh ERRORS
	97	The
	98	.Fn pselect
	99	function may fail for any of the reasons documented for
	100	.Xr select 2
	101	and (if a signal mask is provided)
	102	.Xr sigprocmask 2 .
	103	.Sh SEE ALSO
	104	.Xr kqueue 2 ,
	105	.Xr poll 2 ,
	106	.Xr select 2 ,
	107	.Xr sigprocmask 2
	108	.Sh STANDARDS
	109	The
	110	.Fn pselect
	111	function conforms to
	112	.St -p1003.1-2001 .
	113	.Sh HISTORY
	114	The
	115	.Fn pselect
	116	function first appeared in
	117	.Dx 1.11 .
	118	.Sh AUTHORS
	119	This manual page was originally written by
	120	.An Garrett Wollman Aq wollman@FreeBSD.org
	121	for
	122	.Fx
	123	and later modified for
	124	.Dx .
	125	.Sh BUGS
	126	The
	127	.Fn pselect
	128	implementation in libc_r (user multi-threading) does not mask signals, calls
	129	.Fn select ,
	130	and restores the original signal mask atomically. A calling user thread
	131	using
	132	.Fn pselect
	133	to block until either a signal occurs or some descriptor changes may therefore
	134	block forever.
	135	The
	136	.Fn pselect
	137	implementations in libthread_xu (kernel multi-threading) and libc
	138	(single-threading) operate atomically and are therefore race-free.