lib/libc/sys/sigaltstack.2

   1 .\" Copyright (c) 1983, 1991, 1992, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     @(#)sigaltstack.2       8.2 (Berkeley) 5/1/95
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 6, 2010
  32 .Dt SIGALTSTACK 2
  33 .Os
  34 .Sh NAME
  35 .Nm sigaltstack
  36 .Nd set and/or get signal stack context
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In signal.h
  41 .Bd -literal
  42 typedef struct {
  43         char    *ss_sp;
  44         size_t  ss_size;
  45         int     ss_flags;
  46 } stack_t;
  47 .Ed
  48 .Ft int
  49 .Fn sigaltstack "const stack_t * restrict ss" "stack_t * restrict oss"
  50 .Sh DESCRIPTION
  51 The
  52 .Fn sigaltstack
  53 system call
  54 allows defining an alternate stack on which signals
  55 are to be processed for the current thread.
  56 If
  57 .Fa ss
  58 is non-zero,
  59 it specifies a pointer to and the size of a
  60 .Em "signal stack"
  61 on which to deliver signals.
  62 When a signal's action indicates its handler
  63 should execute on the signal stack (specified with a
  64 .Xr sigaction 2
  65 system call), the system checks to see
  66 if the thread is currently executing on that stack.
  67 If the thread is not currently executing on the signal stack,
  68 the system arranges a switch to the signal stack for the
  69 duration of the signal handler's execution.
  70 .Pp
  71 An active stack cannot be modified.
  72 .Pp
  73 If
  74 .Dv SS_DISABLE
  75 is set in
  76 .Fa ss_flags ,
  77 .Fa ss_sp
  78 and
  79 .Fa ss_size
  80 are ignored and the signal stack will be disabled.
  81 A disabled stack will cause all signals to be
  82 taken on the regular user stack.
  83 If the stack is later re-enabled then all signals that were specified
  84 to be processed on an alternate stack will resume doing so.
  85 .Pp
  86 If
  87 .Fa oss
  88 is non-zero, the current signal stack state is returned.
  89 The
  90 .Fa ss_flags
  91 field will contain the value
  92 .Dv SS_ONSTACK
  93 if the thread is currently on a signal stack and
  94 .Dv SS_DISABLE
  95 if the signal stack is currently disabled.
  96 .Sh NOTES
  97 The value
  98 .Dv SIGSTKSZ
  99 is defined to be the number of bytes/chars that would be used to cover
 100 the usual case when allocating an alternate stack area.
 101 The following code fragment is typically used to allocate an alternate stack.
 102 .Bd -literal -offset indent
 103 if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
 104         /* error return */
 105 sigstk.ss_size = SIGSTKSZ;
 106 sigstk.ss_flags = 0;
 107 if (sigaltstack(&sigstk, NULL) < 0)
 108         perror("sigaltstack");
 109 .Ed
 110 An alternative approach is provided for programs with signal handlers
 111 that require a specific amount of stack space other than the default size.
 112 The value
 113 .Dv MINSIGSTKSZ
 114 is defined to be the number of bytes/chars that is required by
 115 the operating system to implement the alternate stack feature.
 116 In computing an alternate stack size,
 117 programs should add
 118 .Dv MINSIGSTKSZ
 119 to their stack requirements to allow for the operating system overhead.
 120 .Pp
 121 Signal stacks are automatically adjusted for the direction of stack
 122 growth and alignment requirements.
 123 Signal stacks may or may not be protected by the hardware and
 124 are not ``grown'' automatically as is done for the normal stack.
 125 If the stack overflows and this space is not protected
 126 unpredictable results may occur.
 127 .Sh RETURN VALUES
 128 .Rv -std sigaltstack
 129 .Sh ERRORS
 130 The
 131 .Fn sigaltstack
 132 system call
 133 will fail and the signal stack context will remain unchanged
 134 if one of the following occurs.
 135 .Bl -tag -width Er
 136 .It Bq Er EFAULT
 137 Either
 138 .Fa ss
 139 or
 140 .Fa oss
 141 points to memory that is not a valid part of the process
 142 address space.
 143 .It Bq Er EPERM
 144 An attempt was made to modify an active stack.
 145 .It Bq Er EINVAL
 146 The
 147 .Fa ss_flags
 148 field was invalid.
 149 .It Bq Er ENOMEM
 150 Size of alternate stack area is less than or equal to
 151 .Dv MINSIGSTKSZ .
 152 .El
 153 .Sh SEE ALSO
 154 .Xr sigaction 2 ,
 155 .Xr setjmp 3
 156 .Sh HISTORY
 157 The predecessor to
 158 .Fn sigaltstack ,
 159 the
 160 .Fn sigstack
 161 system call, appeared in
 162 .Bx 4.2 .