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 .