243 system manual pages should live with the software

Reviewed by: garrett@nexenta.com
Reviewed by: gwr@nexenta.com
Reviewed by: trisk@opensolaris.org
Approved by: gwr@nexenta.com

--HG--
extra : rebase_source : 0c599d0bec0dc8865fbba67721a7a6cd6b1feefb

1 files changed, 245 insertions, 0 deletions

diff --git a/usr/src/man/man2/sigwait.2 b/usr/src/man/man2/sigwait.2
new file mode 100644
index 0000000000..0477de92c1
--- /dev/null
+++ b/usr/src/man/man2/sigwait.2
@@ -0,0 +1,245 @@
+'\" te
+.\"  Copyright (c) 2009, Sun Microsystems, Inc.  All Rights Reserved.
+.\" 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.
+.\"  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
+.\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
+.TH sigwait 2 "16 Apr 2009" "SunOS 5.11" "System Calls"
+.SH NAME
+sigwait \- wait until a signal is posted
+.SH SYNOPSIS
+.LP
+.nf
+#include <signal.h>
+
+\fBint\fR \fBsigwait\fR(\fBsigset_t *\fR\fIset\fR);
+.fi
+
+.SS "Standard conforming"
+.LP
+.nf
+cc [ \fIflag\fR ... ] \fIfile\fR ... \fB-D_POSIX_PTHREAD_SEMANTICS\fR [ \fIlibrary\fR...]
+#include <signal.h>
+
+\fBint\fR \fBsigwait\fR(\fBconst sigset_t *\fR\fIset\fR, \fBint *\fR\fIsig\fR);
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBsigwait()\fR function selects a signal in \fIset\fR that is pending on
+the calling thread. If no signal in \fIset\fR is pending, \fBsigwait()\fR
+blocks until a signal in \fIset\fR becomes pending. The selected signal is
+cleared from the set of signals pending on the calling thread and the number of
+the signal is returned, or in the standard-conforming version (see
+\fBstandards\fR(5)) placed in \fIsig\fR. The selection of a signal in \fIset\fR
+is independent of the signal mask of the calling thread. This means a thread
+can synchronously wait for signals that are being blocked by the signal mask of
+the calling thread \&. To ensure that only the caller receives the signals
+defined in \fIset\fR, all threads should have signals in \fIset\fR masked
+including the calling thread.
+.sp
+.LP
+If more than one thread is using \fBsigwait()\fR to wait for the same signal,
+no more than one of these threads returns from \fBsigwait()\fR with the signal
+number. If more than a single thread is blocked in \fBsigwait()\fR for a signal
+when that signal is generated for the process, it is unspecified which of the
+waiting threads returns from \fBsigwait()\fR. If the signal is generated for a
+specific thread, as by \fBpthread_kill\fR(3C), only that thread returns.
+.sp
+.LP
+Should any of the multiple pending signals in the range \fBSIGRTMIN\fR to
+\fBSIGRTMAX\fR be selected, it will be the lowest numbered one. The selection
+order between realtime and non-realtime signals, or between multiple pending
+non-realtime signals, is unspecified.
+.SH RETURN VALUES
+.sp
+.LP
+Upon successful completion, the default version of \fBsigwait()\fR returns a
+signal number; the standard-conforming version returns \fB0\fR and stores the
+received signal number at the location pointed to by \fIsig\fR. Otherwise, the
+default version returns -1 and sets errno to indicate an error; the
+standard-conforming version returns an error number to indicate the error.
+.SH ERRORS
+.sp
+.LP
+The \fBsigwait()\fR function will fail if:
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEFAULT\fR\fR
+.ad
+.RS 10n
+.rt  
+The \fIset\fR argument points to an invalid address.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEINTR\fR\fR
+.ad
+.RS 10n
+.rt  
+The wait was interrupted by an unblocked, caught signal.
+.RE
+
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEINVAL\fR\fR
+.ad
+.RS 10n
+.rt  
+The \fIset\fR argument contains an unsupported signal number.
+.RE
+
+.SH EXAMPLES
+.LP
+\fBExample 1 \fRCreating a thread to handle receipt of a signal
+.sp
+.LP
+The following sample C code creates a thread to handle the receipt of a signal.
+More specifically, it catches the asynchronously generated signal,
+\fBSIGINT\fR.
+
+.sp
+.in +2
+.nf
+/********************************************************************
+*
+* compile with -D_POSIX_PTHREAD_SEMANTICS switch;
+* required by sigwait()
+*
+* sigint thread handles delivery of signal. uses sigwait(\|) to wait
+* for SIGINT signal.
+*
+********************************************************************/
+#include <pthread.h>
+#include <stdlib.h>
+#include <stdio.h>
+#include <string.h>
+#include <unistd.h>
+#include <signal.h>
+#include <synch.h>
+
+static void    *threadTwo(void *);
+static void    *threadThree(void *);
+static void    *sigint(void *);
+
+sigset_t       signalSet;
+
+void *
+main(void)
+{
+    pthread_t    t;
+    pthread_t    t2;
+    pthread_t    t3;
+    
+    sigfillset ( &signalSet );
+    /*
+     * Block signals in initial thread. New threads will
+     * inherit this signal mask.
+     */
+    pthread_sigmask ( SIG_BLOCK, &signalSet, NULL );
+    
+    printf("Creating threads\en");
+    
+    pthread_create(&t, NULL, sigint, NULL);
+    pthread_create(&t2, NULL, threadTwo, NULL);
+    pthread_create(&t3, NULL, threadThree, NULL);
+    
+    printf("##################\en");
+    printf("press CTRL-C to deliver SIGINT to sigint thread\en");
+    printf("##################\en");
+    
+    pthread_exit((void *)0);
+}
+static void *
+threadTwo(void *arg)
+{
+    printf("hello world, from threadTwo [tid: %d]\en",
+                            pthread_self());
+    printf("threadTwo [tid: %d] is now complete and exiting\en",
+                            pthread_self());
+    pthread_exit((void *)0);
+}
+
+static void *
+threadThree(void *arg)
+{
+    printf("hello world, from threadThree [tid: %d]\en",
+                            pthread_self());
+    printf("threadThree [tid: %d] is now complete and exiting\en",
+                            pthread_self());
+    pthread_exit((void *)0);
+}
+
+void *
+sigint(void *arg)
+{
+    int    sig;
+    int    err;
+    
+    printf("thread sigint [tid: %d] awaiting SIGINT\en",
+                            pthread_self());
+    
+    /*
+    /* use standard-conforming sigwait() -- 2 args: signal set, signum
+     */
+    err = sigwait ( &signalSet, &sig );
+    
+    /* test for SIGINT; could catch other signals */
+    if (err || sig != SIGINT)
+        abort();
+    
+    printf("\enSIGINT signal %d caught by sigint thread [tid: %d]\en",
+                            sig, pthread_self());
+    pthread_exit((void *)0);
+}
+.fi
+.in -2
+
+.SH ATTRIBUTES
+.sp
+.LP
+See \fBattributes\fR(5) for descriptions of the following attributes:
+.sp
+
+.sp
+.TS
+tab() box;
+cw(2.75i) |cw(2.75i) 
+lw(2.75i) |lw(2.75i) 
+.
+ATTRIBUTE TYPEATTRIBUTE VALUE
+_
+Interface StabilityCommitted
+_
+MT-LevelAsync-Signal-Safe
+_
+StandardSee \fBstandards\fR(5).
+.TE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBsigaction\fR(2), \fBsigpending\fR(2), \fBsigprocmask\fR(2),
+\fBsigsuspend\fR(2), \fBpthread_create\fR(3C), \fBpthread_kill\fR(3C),
+\fBpthread_sigmask\fR(3C), \fBsignal.h\fR(3HEAD), \fBattributes\fR(5),
+\fBstandards\fR(5)
+.SH NOTES
+.sp
+.LP
+The \fBsigwait()\fR function cannot be used to wait for signals that cannot be
+caught (see \fBsigaction\fR(2)). This restriction is silently imposed by the
+system.
+.sp
+.LP
+Solaris 2.4 and earlier releases provided a \fBsigwait()\fR facility as
+specified in POSIX.1c Draft 6. The final POSIX.1c standard changed the
+interface as described above. Support for the Draft 6 interface is provided for
+compatibility only and may not be supported in future releases. New
+applications and libraries should use the standard-conforming interface.