usr/src/man/man3c/stack_violation.3c

   1 '\" te
   2 .\" Copyright (c) 2002, 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.
   4 .\" 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.
   5 .\" 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]
   6 .TH STACK_VIOLATION 3C "Jul 18, 2002"
   7 .SH NAME
   8 stack_violation \- determine stack boundary violation event
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 #include <ucontext.h>
  13
  14 \fBint\fR \fBstack_violation\fR(\fBint\fR \fIsig\fR, \fBconst siginfo_t *\fR\fIsip\fR,
  15      \fBconst ucontext_t *\fR\fIucp\fR);
  16 .fi
  17
  18 .SH DESCRIPTION
  19 .sp
  20 .LP
  21 The \fBstack_violation()\fR function returns a boolean value indicating whether
  22 the signal, \fIsig\fR, and accompanying signal information, \fIsip\fR, and
  23 saved context, \fIucp\fR, represent a stack boundary violation event or a stack
  24 overflow.
  25 .SH RETURN VALUES
  26 .sp
  27 .LP
  28 The \fBstack_violation()\fR function returns 0 if the signal does not represent
  29 a stack boundary violation event and 1 if the signal does represent a stack
  30 boundary violation event.
  31 .SH ERRORS
  32 .sp
  33 .LP
  34 No errors are defined.
  35 .SH EXAMPLES
  36 .LP
  37 \fBExample 1 \fRSet up a signal handler to run on an alternate stack.
  38 .sp
  39 .LP
  40 The following example sets up a signal handler for \fBSIGSEGV\fR to run on an
  41 alternate signal stack. For each signal it handles, the handler emits a message
  42 to indicate if the signal was produced due to a stack boundary violation.
  43
  44 .sp
  45 .in +2
  46 .nf
  47 #include <stdlib.h>
  48 #include <unistd.h>
  49 #include <ucontext.h>
  50 #include <signal.h>
  51
  52
  53 static void
  54 handler(int sig, siginfo_t *sip, void *p)
  55 {
  56         ucontext_t *ucp = p;
  57         const char *str;
  58
  59         if (stack_violation(sig, sip, ucp))
  60                 str = "stack violation.\en";
  61         else
  62                 str = "no stack violation.\en";
  63
  64         (void) write(STDERR_FILENO, str, strlen(str));
  65
  66         exit(1);
  67 }
  68
  69 int
  70 main(int argc, char **argv)
  71 {
  72         struct sigaction sa;
  73         stack_t altstack;
  74
  75         altstack.ss_size = SIGSTKSZ;
  76         altstack.ss_sp = malloc(SIGSTKSZ);
  77         altstack.ss_flags = 0;
  78
  79         (void) sigaltstack(&altstack, NULL);
  80
  81         sa.sa_sigaction = handler;
  82         (void) sigfillset(&sa.sa_mask);
  83         sa.sa_flags = SA_ONSTACK | SA_SIGINFO;
  84         (void) sigaction(SIGSEGV, &sa, NULL);
  85
  86         /*
  87          * The application is now set up to use stack_violation(3C).
  88          */
  89
  90         return (0);
  91 }
  92 .fi
  93 .in -2
  94
  95 .SH USAGE
  96 .sp
  97 .LP
  98 An application typically uses \fBstack_violation()\fR in a signal handler that
  99 has been installed for \fBSIGSEGV\fR using \fBsigaction\fR(2) with the
 100 \fBSA_SIGINFO\fR flag set and is configured to run on an alternate signal
 101 stack.
 102 .SH ATTRIBUTES
 103 .sp
 104 .LP
 105 See \fBattributes\fR(5) for descriptions of the following attributes:
 106 .sp
 107
 108 .sp
 109 .TS
 110 box;
 111 c | c
 112 l | l .
 113 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 114 _
 115 Interface Stability     Evolving
 116 _
 117 MT-Level        Async-Signal-Safe
 118 .TE
 119
 120 .SH SEE ALSO
 121 .sp
 122 .LP
 123 \fBsigaction\fR(2), \fBsigaltstack\fR(2), \fBstack_getbounds\fR(3C),
 124 \fBstack_inbounds\fR(3C), \fBstack_setbounds\fR(3C), \fBattributes\fR(5)