a205cd83d3913954a2438549ac8008d944bb8c14
[dragonfly.git] / lib / libc / sys / pselect.2
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 BUGS
114 The
115 .Fn pselect
116 implementation in libc_r (user multi-threading) does not mask signals, calls
117 .Fn select ,
118 and restores the original signal mask atomically.  A calling user thread
119 using
120 .Fn pselect
121 to block until either a signal occurs or some descriptor changes may therefore
122 block forever.
123 The
124 .Fn pselect
125 implementations in libthread_xu (kernel multi-threading) and libc
126 (single-threading) operate atomically and are therefore race-free.
127 .Sh HISTORY
128 The
129 .Fn pselect
130 function first appeared in
131 .Dx 1.11 .
132 .Sh AUTHORS
133 This manual page was originally written by
134 .An Garrett Wollman Aq wollman@FreeBSD.org
135 for
136 .Fx
137 and later modified for
138 .Dx .