lib/libc/sys/sigtimedwait.2

   1 .\" $NetBSD: sigtimedwait.2,v 1.8 2012/04/02 22:06:47 agc Exp $
   2 .\"
   3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Jaromir Dolecek.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd April 2, 2012
  31 .Dt SIGTIMEDWAIT 2
  32 .Os
  33 .Sh NAME
  34 .Nm sigtimedwait ,
  35 .Nm sigwaitinfo ,
  36 .Nm sigwait
  37 .Nd wait for queued signals
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In signal.h
  42 .Ft int
  43 .Fn sigtimedwait "const sigset_t * restrict set" "siginfo_t * restrict info" "const struct timespec * restrict timeout"
  44 .Ft int
  45 .Fn sigwaitinfo "const sigset_t * restrict set" "siginfo_t * restrict info"
  46 .Ft int
  47 .Fn sigwait "const sigset_t * restrict set" "int * restrict sig"
  48 .Sh DESCRIPTION
  49 .Fn sigwaitinfo
  50 and
  51 .Fn sigwait
  52 return the first pending signal from the set specified by
  53 .Fa set .
  54 Should multiple signals from
  55 .Fa set
  56 be pending, the lowest numbered one is returned.
  57 The selection order between realtime and non-realtime signals is unspecified.
  58 If there is no signal from
  59 .Ar set
  60 pending at the time of the call, the calling thread
  61 is suspended until one of the specified signals is generated.
  62 .Pp
  63 .Fn sigtimedwait
  64 is exactly equal to
  65 .Fn sigwaitinfo ,
  66 except
  67 .Fa timeout
  68 specifies the maximum time interval for which the calling thread will
  69 be suspended.
  70 If
  71 .Fa timeout
  72 is zero (tv_sec == tv_nsec == 0),
  73 .Fn sigtimedwait
  74 only checks the currently pending signals and returns immediately.
  75 If
  76 .Dv NULL
  77 is used for
  78 .Fa timeout ,
  79 .Fn sigtimedwait
  80 behaves exactly like
  81 .Fn sigwaitinfo
  82 in all regards.
  83 .Pp
  84 If several threads are waiting for a given signal, exactly one of them
  85 returns from the signal wait when the signal is generated.
  86 .Pp
  87 Behaviour of these functions is unspecified if any of the signals in
  88 .Fa set
  89 are unblocked at the time these functions are called.
  90 .Sh RETURN VALUES
  91 Upon successful completion of
  92 .Fn sigtimedwait
  93 or
  94 .Fn sigwaitinfo
  95 .Fa info
  96 is updated with signal information, and the function returns the signal number.
  97 Otherwise, \-1 is returned and the global variable
  98 .Va errno
  99 indicates the error.
 100 Upon successful completion of
 101 .Fn sigwait
 102 .Fa sig
 103 is updated with the signal number, and the function returns 0.
 104 Otherwise, a non-zero error code is returned.
 105 .Sh ERRORS
 106 .Fn sigwaitinfo
 107 and
 108 .Fn sigwait
 109 always succeed.
 110 .Pp
 111 .Fn sigtimedwait
 112 will fail and the
 113 .Fa info
 114 pointer will remain unchanged if:
 115 .Bl -tag -width Er
 116 .It Bq Er EAGAIN
 117 No signal specified in
 118 .Fa set
 119 was generated in the specified
 120 .Fa timeout .
 121 .El
 122 .Pp
 123 .Fn sigtimedwait
 124 may also fail if:
 125 .Bl -tag -width Er
 126 .It Bq Er EINVAL
 127 The specified
 128 .Fa timeout
 129 was invalid.
 130 .El
 131 .Pp
 132 This error is only checked if no signal from
 133 .Fa set
 134 is pending and it would be necessary to wait.
 135 .Sh SEE ALSO
 136 .Xr sigaction 2 ,
 137 .Xr sigprocmask 2 ,
 138 .Xr signal 7
 139 .Sh STANDARDS
 140 The functions
 141 .Fn sigtimedwait ,
 142 .Fn sigwaitinfo ,
 143 and
 144 .Fn sigwait
 145 conform to
 146 .St -p1003.1-2001 .
 147 .Sh HISTORY
 148 The
 149 .Fn sigtimedwait ,
 150 .Fn sigwaitinfo ,
 151 and
 152 .Fn sigwait
 153 functions appeared in
 154 .Nx 2.0 .