'\" te
.\" Copyright (c) 2002, 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 STACK_VIOLATION 3C "Jul 18, 2002"
.SH NAME
stack_violation \- determine stack boundary violation event
.SH SYNOPSIS
.LP
.nf
#include <ucontext.h>

\fBint\fR \fBstack_violation\fR(\fBint\fR \fIsig\fR, \fBconst siginfo_t *\fR\fIsip\fR,
     \fBconst ucontext_t *\fR\fIucp\fR);
.fi

.SH DESCRIPTION
.sp
.LP
The \fBstack_violation()\fR function returns a boolean value indicating whether
the signal, \fIsig\fR, and accompanying signal information, \fIsip\fR, and
saved context, \fIucp\fR, represent a stack boundary violation event or a stack
overflow.
.SH RETURN VALUES
.sp
.LP
The \fBstack_violation()\fR function returns 0 if the signal does not represent
a stack boundary violation event and 1 if the signal does represent a stack
boundary violation event.
.SH ERRORS
.sp
.LP
No errors are defined.
.SH EXAMPLES
.LP
\fBExample 1 \fRSet up a signal handler to run on an alternate stack.
.sp
.LP
The following example sets up a signal handler for \fBSIGSEGV\fR to run on an
alternate signal stack. For each signal it handles, the handler emits a message
to indicate if the signal was produced due to a stack boundary violation.

.sp
.in +2
.nf
#include <stdlib.h>
#include <unistd.h>
#include <ucontext.h>
#include <signal.h>


static void
handler(int sig, siginfo_t *sip, void *p)
{
        ucontext_t *ucp = p;
        const char *str;

        if (stack_violation(sig, sip, ucp))
                str = "stack violation.\en";
        else
                str = "no stack violation.\en";

        (void) write(STDERR_FILENO, str, strlen(str));

        exit(1);
}

int
main(int argc, char **argv)
{
        struct sigaction sa;
        stack_t altstack;

        altstack.ss_size = SIGSTKSZ;
        altstack.ss_sp = malloc(SIGSTKSZ);
        altstack.ss_flags = 0;

        (void) sigaltstack(&altstack, NULL);

        sa.sa_sigaction = handler;
        (void) sigfillset(&sa.sa_mask);
        sa.sa_flags = SA_ONSTACK | SA_SIGINFO;
        (void) sigaction(SIGSEGV, &sa, NULL);

        /*
         * The application is now set up to use stack_violation(3C).
         */

        return (0);
}
.fi
.in -2

.SH USAGE
.sp
.LP
An application typically uses \fBstack_violation()\fR in a signal handler that
has been installed for \fBSIGSEGV\fR using \fBsigaction\fR(2) with the
\fBSA_SIGINFO\fR flag set and is configured to run on an alternate signal
stack.
.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
_
MT-Level	Async-Signal-Safe
.TE

.SH SEE ALSO
.sp
.LP
.BR sigaction (2),
.BR sigaltstack (2),
.BR stack_getbounds (3C),
.BR stack_inbounds (3C),
.BR stack_setbounds (3C),
.BR attributes (7)