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, 90 insertions, 0 deletions

diff --git a/usr/src/man/man3ucb/sigstack.3ucb b/usr/src/man/man3ucb/sigstack.3ucb
new file mode 100644
index 0000000000..0964ca461a
--- /dev/null
+++ b/usr/src/man/man3ucb/sigstack.3ucb
@@ -0,0 +1,90 @@
+'\" te
+.\"  Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
+.\"  Copyright (c) 1983 Regents of the University of California.  All rights reserved.  The Berkeley software License Agreement specifies the terms and conditions for redistribution.
+.TH sigstack 3UCB "30 Oct 2007" "SunOS 5.11" "SunOS/BSD Compatibility Library Functions"
+.SH NAME
+sigstack \- set and/or get signal stack context
+.SH SYNOPSIS
+.LP
+.nf
+\fB/usr/ucb/cc\fR [ \fIflag\fR ... ] \fIfile\fR ...
+#include <signal.h>
+
+\fBint\fR \fBsigstack\fR(\fInss\fR, \fIoss\fR)
+\fBstruct sigstack *\fR\fInss\fR, \fB*\fR\fIoss\fR;
+.fi
+
+.SH DESCRIPTION
+.sp
+.LP
+The \fBsigstack()\fR function allows users to define an alternate stack, called
+the "signal stack", on which signals are to be processed.  When a signal's
+action indicates its handler should execute on the signal stack (specified with
+a \fBsigvec\fR(3UCB) call), the system checks to see if the process is
+currently executing on that stack.  If the process is not currently executing
+on the signal stack, the system arranges a switch to the signal stack for the
+duration of the signal handler's execution.
+.sp
+.LP
+A signal stack is specified by a \fBsigstack()\fR structure, which includes the
+following members:
+.sp
+.in +2
+.nf
+char  *ss_sp;        /* signal stack pointer */
+int   ss_onstack;    /* current status */
+.fi
+.in -2
+
+.sp
+.LP
+The \fBss_sp\fR member is the initial value to be assigned to the stack pointer
+when the system switches the process to the signal stack. Note that, on
+machines where the stack grows downwards in memory, this is \fInot\fR the
+address of the beginning of the signal stack area.  The \fBss_onstack\fR member
+is zero or non-zero depending on whether the process is currently executing on
+the signal stack or not.
+.sp
+.LP
+If \fInss\fR is not a null pointer, \fBsigstack()\fR sets the signal stack
+state to the value in the \fBsigstack()\fR structure pointed to by \fInss\fR.
+If \fInss\fR is a \fBnull\fR pointer, the signal stack state will be unchanged.
+If \fIoss\fR is not a \fBnull\fR pointer, the current signal stack state is
+stored in the \fBsigstack()\fR structure pointed to by \fIoss\fR.
+.SH RETURN VALUES
+.sp
+.LP
+Upon successful completion, \fB0\fR is returned.  Otherwise, \fB\(mi1\fR is
+returned and \fBerrno\fR is set to indicate the error.
+.SH ERRORS
+.sp
+.LP
+The \fBsigstack()\fR function will fail and the signal stack context will
+remain unchanged if one of the following occurs.
+.sp
+.ne 2
+.mk
+.na
+\fB\fBEFAULT\fR\fR
+.ad
+.RS 10n
+.rt  
+Either \fInss\fR or \fIoss\fR points to memory that is not a valid part of the
+process address space.
+.RE
+
+.SH SEE ALSO
+.sp
+.LP
+\fBsigaltstack\fR(2), \fBsigvec\fR(3UCB), \fBsignal\fR(3C)
+.SH WARNINGS
+.sp
+.LP
+Signal stacks are not "grown" automatically, as is done for the normal stack.
+If the stack overflows unpredictable results may occur.
+.SH NOTES
+.sp
+.LP
+Use of these interfaces should be restricted to only applications written on
+BSD platforms.  Use of these interfaces with any of the system libraries or in
+multi-threaded applications is unsupported.