lib/libc/sys/sigtimedwait.2

   1 .\" $NetBSD: sigtimedwait.2,v 1.4 2008/04/30 13:10:51 martin 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 February 10, 2003
  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
  92 .Fa info
  93 is updated with signal information, and the function returns 0.
  94 Otherwise, \-1 is returned and the global variable
  95 .Va errno
  96 indicates the error.
  97 .Sh ERRORS
  98 .Fn sigwaitinfo
  99 and
 100 .Fn sigwait
 101 always succeed.
 102 .Pp
 103 .Fn sigtimedwait
 104 will fail and the
 105 .Fa info
 106 pointer will remain unchanged if:
 107 .Bl -tag -width Er
 108 .It Bq Er EAGAIN
 109 No signal specified in
 110 .Fa set
 111 was generated in the specified
 112 .Fa timeout .
 113 .El
 114 .Pp
 115 .Fn sigtimedwait
 116 may also fail if:
 117 .Bl -tag -width Er
 118 .It Bq Er EINVAL
 119 The specified
 120 .Fa timeout
 121 was invalid.
 122 .El
 123 .Pp
 124 This error is only checked if no signal from
 125 .Fa set
 126 is pending and it would be necessary to wait.
 127 .Sh SEE ALSO
 128 .Xr sigaction 2 ,
 129 .Xr sigprocmask 2 ,
 130 .Xr signal 7
 131 .Sh STANDARDS
 132 The functions
 133 .Fn sigtimedwait ,
 134 .Fn sigwaitinfo ,
 135 and
 136 .Fn sigwait
 137 conform to
 138 .St -p1003.1-2001 .
 139 .Sh HISTORY
 140 The
 141 .Fn sigtimedwait ,
 142 .Fn sigwaitinfo ,
 143 and
 144 .Fn sigwait
 145 functions appeared in
 146 .Nx 2.0 .