usr/src/man/man2/sigwait.2

   1 '\" te
   2 .\"  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
   4 .\"  See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with
   5 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SIGWAIT 2 "Apr 16, 2009"
   7 .SH NAME
   8 sigwait \- wait until a signal is posted
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <signal.h>
  13
  14 \fBint\fR \fBsigwait\fR(\fBsigset_t *\fR\fIset\fR);
  15 .fi
  16
  17 .SS "Standard conforming"
  18 .LP
  19 .nf
  20 cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR...]
  21 #include <signal.h>
  22
  23 \fBint\fR \fBsigwait\fR(\fBconst sigset_t *\fR\fIset\fR, \fBint *\fR\fIsig\fR);
  24 .fi
  25
  26 .SH DESCRIPTION
  27 .sp
  28 .LP
  29 The \fBsigwait()\fR function selects a signal in \fIset\fR that is pending on
  30 the calling thread. If no signal in \fIset\fR is pending, \fBsigwait()\fR
  31 blocks until a signal in \fIset\fR becomes pending. The selected signal is
  32 cleared from the set of signals pending on the calling thread and the number of
  33 the signal is returned, or in the standard-conforming version (see
  34 \fBstandards\fR(5)) placed in \fIsig\fR. The selection of a signal in \fIset\fR
  35 is independent of the signal mask of the calling thread. This means a thread
  36 can synchronously wait for signals that are being blocked by the signal mask of
  37 the calling thread \&. To ensure that only the caller receives the signals
  38 defined in \fIset\fR, all threads should have signals in \fIset\fR masked
  39 including the calling thread.
  40 .sp
  41 .LP
  42 If more than one thread is using \fBsigwait()\fR to wait for the same signal,
  43 no more than one of these threads returns from \fBsigwait()\fR with the signal
  44 number. If more than a single thread is blocked in \fBsigwait()\fR for a signal
  45 when that signal is generated for the process, it is unspecified which of the
  46 waiting threads returns from \fBsigwait()\fR. If the signal is generated for a
  47 specific thread, as by \fBpthread_kill\fR(3C), only that thread returns.
  48 .sp
  49 .LP
  50 Should any of the multiple pending signals in the range \fBSIGRTMIN\fR to
  51 \fBSIGRTMAX\fR be selected, it will be the lowest numbered one. The selection
  52 order between realtime and non-realtime signals, or between multiple pending
  53 non-realtime signals, is unspecified.
  54 .SH RETURN VALUES
  55 .sp
  56 .LP
  57 Upon successful completion, the default version of \fBsigwait()\fR returns a
  58 signal number; the standard-conforming version returns \fB0\fR and stores the
  59 received signal number at the location pointed to by \fIsig\fR. Otherwise, the
  60 default version returns -1 and sets errno to indicate an error; the
  61 standard-conforming version returns an error number to indicate the error.
  62 .SH ERRORS
  63 .sp
  64 .LP
  65 The \fBsigwait()\fR function will fail if:
  66 .sp
  67 .ne 2
  68 .na
  69 \fB\fBEFAULT\fR\fR
  70 .ad
  71 .RS 10n
  72 The \fIset\fR argument points to an invalid address.
  73 .RE
  74
  75 .sp
  76 .ne 2
  77 .na
  78 \fB\fBEINTR\fR\fR
  79 .ad
  80 .RS 10n
  81 The wait was interrupted by an unblocked, caught signal.
  82 .RE
  83
  84 .sp
  85 .ne 2
  86 .na
  87 \fB\fBEINVAL\fR\fR
  88 .ad
  89 .RS 10n
  90 The \fIset\fR argument contains an unsupported signal number.
  91 .RE
  92
  93 .SH EXAMPLES
  94 .LP
  95 \fBExample 1 \fRCreating a thread to handle receipt of a signal
  96 .sp
  97 .LP
  98 The following sample C code creates a thread to handle the receipt of a signal.
  99 More specifically, it catches the asynchronously generated signal,
 100 \fBSIGINT\fR.
 101
 102 .sp
 103 .in +2
 104 .nf
 105 /********************************************************************
 106 *
 107 * compile with -D_POSIX_PTHREAD_SEMANTICS switch;
 108 * required by sigwait()
 109 *
 110 * sigint thread handles delivery of signal. uses sigwait(\|) to wait
 111 * for SIGINT signal.
 112 *
 113 ********************************************************************/
 114 #include <pthread.h>
 115 #include <stdlib.h>
 116 #include <stdio.h>
 117 #include <string.h>
 118 #include <unistd.h>
 119 #include <signal.h>
 120 #include <synch.h>
 121
 122 static void    *threadTwo(void *);
 123 static void    *threadThree(void *);
 124 static void    *sigint(void *);
 125
 126 sigset_t       signalSet;
 127
 128 void *
 129 main(void)
 130 {
 131     pthread_t    t;
 132     pthread_t    t2;
 133     pthread_t    t3;
 134
 135     sigfillset ( &signalSet );
 136     /*
 137      * Block signals in initial thread. New threads will
 138      * inherit this signal mask.
 139      */
 140     pthread_sigmask ( SIG_BLOCK, &signalSet, NULL );
 141
 142     printf("Creating threads\en");
 143
 144     pthread_create(&t, NULL, sigint, NULL);
 145     pthread_create(&t2, NULL, threadTwo, NULL);
 146     pthread_create(&t3, NULL, threadThree, NULL);
 147
 148     printf("##################\en");
 149     printf("press CTRL-C to deliver SIGINT to sigint thread\en");
 150     printf("##################\en");
 151
 152     pthread_exit((void *)0);
 153 }
 154 static void *
 155 threadTwo(void *arg)
 156 {
 157     printf("hello world, from threadTwo [tid: %d]\en",
 158                             pthread_self());
 159     printf("threadTwo [tid: %d] is now complete and exiting\en",
 160                             pthread_self());
 161     pthread_exit((void *)0);
 162 }
 163
 164 static void *
 165 threadThree(void *arg)
 166 {
 167     printf("hello world, from threadThree [tid: %d]\en",
 168                             pthread_self());
 169     printf("threadThree [tid: %d] is now complete and exiting\en",
 170                             pthread_self());
 171     pthread_exit((void *)0);
 172 }
 173
 174 void *
 175 sigint(void *arg)
 176 {
 177     int    sig;
 178     int    err;
 179
 180     printf("thread sigint [tid: %d] awaiting SIGINT\en",
 181                             pthread_self());
 182
 183     /*
 184     /* use standard-conforming sigwait() -- 2 args: signal set, signum
 185      */
 186     err = sigwait ( &signalSet, &sig );
 187
 188     /* test for SIGINT; could catch other signals */
 189     if (err || sig != SIGINT)
 190         abort();
 191
 192     printf("\enSIGINT signal %d caught by sigint thread [tid: %d]\en",
 193                             sig, pthread_self());
 194     pthread_exit((void *)0);
 195 }
 196 .fi
 197 .in -2
 198
 199 .SH ATTRIBUTES
 200 .sp
 201 .LP
 202 See \fBattributes\fR(5) for descriptions of the following attributes:
 203 .sp
 204
 205 .sp
 206 .TS
 207 box;
 208 c | c
 209 l | l .
 210 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 211 _
 212 Interface Stability     Committed
 213 _
 214 MT-Level        Async-Signal-Safe
 215 _
 216 Standard        See \fBstandards\fR(5).
 217 .TE
 218
 219 .SH SEE ALSO
 220 .sp
 221 .LP
 222 \fBsigaction\fR(2), \fBsigpending\fR(2), \fBsigprocmask\fR(2),
 223 \fBsigsuspend\fR(2), \fBpthread_create\fR(3C), \fBpthread_kill\fR(3C),
 224 \fBpthread_sigmask\fR(3C), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5),
 225 \fBstandards\fR(5)
 226 .SH NOTES
 227 .sp
 228 .LP
 229 The \fBsigwait()\fR function cannot be used to wait for signals that cannot be
 230 caught (see \fBsigaction\fR(2)). This restriction is silently imposed by the
 231 system.
 232 .sp
 233 .LP
 234 Solaris 2.4 and earlier releases provided a \fBsigwait()\fR facility as
 235 specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
 236 interface as described above. Support for the Draft 6 interface is provided for
 237 compatibility only and may not be supported in future releases. New
 238 applications and libraries should use the standard-conforming interface.