+++ /dev/null
-'\" t
-.\" Copyright (c) 2001, 2017 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
-.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein. The author(s) may not
-.\" have taken the same level of care in the production of this manual,
-.\" which is licensed free of charge, as they might when working
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.\" %%%LICENSE_END
-.\"
-.\" aeb, various minor fixes
-.TH SIGALTSTACK 2 2017-11-08 "Linux" "Linux Programmer's Manual"
-.SH NAME
-sigaltstack \- set and/or get signal stack context
-.SH SYNOPSIS
-.B #include <signal.h>
-.PP
-.BI "int sigaltstack(const stack_t *" ss ", stack_t *" old_ss );
-.PP
-.in -4n
-Feature Test Macro Requirements for glibc (see
-.BR feature_test_macros (7)):
-.in
-.PP
-.BR sigaltstack ():
-.ad l
-.RS 4
-.PD 0
-_XOPEN_SOURCE\ >=\ 500
-.\" || _XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
- || /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
- || /* Glibc versions <= 2.19: */ _BSD_SOURCE
-.PD
-.RE
-.ad
-.SH DESCRIPTION
-.BR sigaltstack ()
-allows a process to define a new alternate
-signal stack and/or retrieve the state of an existing
-alternate signal stack.
-An alternate signal stack is used during the
-execution of a signal handler if the establishment of that handler (see
-.BR sigaction (2))
-requested it.
-.PP
-The normal sequence of events for using an alternate signal stack
-is the following:
-.TP 3
-1.
-Allocate an area of memory to be used for the alternate
-signal stack.
-.TP
-2.
-Use
-.BR sigaltstack ()
-to inform the system of the existence and
-location of the alternate signal stack.
-.TP
-3.
-When establishing a signal handler using
-.BR sigaction (2),
-inform the system that the signal handler should be executed
-on the alternate signal stack by
-specifying the \fBSA_ONSTACK\fP flag.
-.PP
-The \fIss\fP argument is used to specify a new
-alternate signal stack, while the \fIold_ss\fP argument
-is used to retrieve information about the currently
-established signal stack.
-If we are interested in performing just one
-of these tasks, then the other argument can be specified as NULL.
-.PP
-The
-.I stack_t
-type used to type the arguments of this function is defined as follows:
-.PP
-.in +4n
-.EX
-typedef struct {
- void *ss_sp; /* Base address of stack */
- int ss_flags; /* Flags */
- size_t ss_size; /* Number of bytes in stack */
-} stack_t;
-.EE
-.in
-.PP
-To establish a new alternate signal stack,
-the fields of this structure are set as follows:
-.TP
-.I ss.ss_flags
-This field contains either 0, or the following flag:
-.RS
-.TP
-.BR SS_AUTODISARM " (since Linux 4.7)"
-.\" commit 2a74213838104a41588d86fd5e8d344972891ace
-.\" See tools/testing/selftests/sigaltstack/sas.c in kernel sources
-Clear the alternate signal stack settings on entry to the signal handler.
-When the signal handler returns,
-the previous alternate signal stack settings are restored.
-.IP
-This flag was added in order make it safe
-to switch away from the signal handler with
-.BR swapcontext (3).
-Without this flag, a subsequently handled signal will corrupt
-the state of the switched-away signal handler.
-On kernels where this flag is not supported,
-.BR sigaltstack ()
-fails with the error
-.BR EINVAL
-when this flag is supplied.
-.RE
-.TP
-.I ss.ss_sp
-This field specifies the starting address of the stack.
-When a signal handler is invoked on the alternate stack,
-the kernel automatically aligns the address given in \fIss.ss_sp\fP
-to a suitable address boundary for the underlying hardware architecture.
-.TP
-.I ss.ss_size
-This field specifies the size of the stack.
-The constant \fBSIGSTKSZ\fP is defined to be large enough
-to cover the usual size requirements for an alternate signal stack,
-and the constant \fBMINSIGSTKSZ\fP defines the minimum
-size required to execute a signal handler.
-.PP
-To disable an existing stack, specify \fIss.ss_flags\fP
-as \fBSS_DISABLE\fP.
-In this case, the kernel ignores any other flags in
-.IR ss.ss_flags
-and the remaining fields
-in \fIss\fP.
-.PP
-If \fIold_ss\fP is not NULL, then it is used to return information about
-the alternate signal stack which was in effect prior to the
-call to
-.BR sigaltstack ().
-The \fIold_ss.ss_sp\fP and \fIold_ss.ss_size\fP fields return the starting
-address and size of that stack.
-The \fIold_ss.ss_flags\fP may return either of the following values:
-.TP
-.B SS_ONSTACK
-The process is currently executing on the alternate signal stack.
-(Note that it is not possible
-to change the alternate signal stack if the process is
-currently executing on it.)
-.TP
-.B SS_DISABLE
-The alternate signal stack is currently disabled.
-.IP
-Alternatively, this value is returned if the process is currently
-executing on an alternate signal stack that was established using the
-.B SS_AUTODISARM
-flag.
-In this case, it is safe to switch away from the signal handler with
-.BR swapcontext (3).
-It is also possible to set up a different alternative signal stack
-using a further call to
-.BR sigaltstack ().
-.\" FIXME Was it intended that one can set up a different alternative
-.\" signal stack in this scenario? (In passing, if one does this, the
-.\" sigaltstack(NULL, &old_ss) now returns old_ss.ss_flags==SS_AUTODISARM
-.\" rather than old_ss.ss_flags==SS_DISABLE. The API design here seems
-.\" confusing...
-.TP
-.B SS_AUTODISARM
-The alternate signal stack has been marked to be autodisarmed
-as described above.
-.PP
-By specifying
-.I ss
-as NULL, and
-.I old_ss
-as a non-NULL value, one can obtain the current settings for
-the alternate signal stack without changing them.
-.SH RETURN VALUE
-.BR sigaltstack ()
-returns 0 on success, or \-1 on failure with
-\fIerrno\fP set to indicate the error.
-.SH ERRORS
-.TP
-.B EFAULT
-Either \fIss\fP or \fIold_ss\fP is not NULL and points to an area
-outside of the process's address space.
-.TP
-.B EINVAL
-\fIss\fP is not NULL and the \fIss_flags\fP field contains
-an invalid flag.
-.TP
-.B ENOMEM
-The specified size of the new alternate signal stack
-.I ss.ss_size
-was less than
-.BR MINSTKSZ .
-.TP
-.B EPERM
-An attempt was made to change the alternate signal stack while
-it was active (i.e., the process was already executing
-on the current alternate signal stack).
-.SH ATTRIBUTES
-For an explanation of the terms used in this section, see
-.BR attributes (7).
-.TS
-allbox;
-lb lb lb
-l l l.
-Interface Attribute Value
-T{
-.BR sigaltstack ()
-T} Thread safety MT-Safe
-.TE
-.SH CONFORMING TO
-POSIX.1-2001, POSIX.1-2009, SUSv2, SVr4.
-.PP
-The
-.B SS_AUTODISARM
-flag is a Linux extension.
-.SH NOTES
-The most common usage of an alternate signal stack is to handle the
-.B SIGSEGV
-signal that is generated if the space available for the
-normal process stack is exhausted: in this case, a signal handler for
-.B SIGSEGV
-cannot be invoked on the process stack; if we wish to handle it,
-we must use an alternate signal stack.
-.PP
-Establishing an alternate signal stack is useful if a process
-expects that it may exhaust its standard stack.
-This may occur, for example, because the stack grows so large
-that it encounters the upwardly growing heap, or it reaches a
-limit established by a call to \fBsetrlimit(RLIMIT_STACK, &rlim)\fP.
-If the standard stack is exhausted, the kernel sends
-the process a \fBSIGSEGV\fP signal.
-In these circumstances the only way to catch this signal is
-on an alternate signal stack.
-.PP
-On most hardware architectures supported by Linux, stacks grow
-downward.
-.BR sigaltstack ()
-automatically takes account
-of the direction of stack growth.
-.PP
-Functions called from a signal handler executing on an alternate
-signal stack will also use the alternate signal stack.
-(This also applies to any handlers invoked for other signals while
-the process is executing on the alternate signal stack.)
-Unlike the standard stack, the system does not
-automatically extend the alternate signal stack.
-Exceeding the allocated size of the alternate signal stack will
-lead to unpredictable results.
-.PP
-A successful call to
-.BR execve (2)
-removes any existing alternate
-signal stack.
-A child process created via
-.BR fork (2)
-inherits a copy of its parent's alternate signal stack settings.
-.PP
-.BR sigaltstack ()
-supersedes the older
-.BR sigstack ()
-call.
-For backward compatibility, glibc also provides
-.BR sigstack ().
-All new applications should be written using
-.BR sigaltstack ().
-.SS History
-4.2BSD had a
-.BR sigstack ()
-system call.
-It used a slightly
-different struct, and had the major disadvantage that the caller
-had to know the direction of stack growth.
-.SH EXAMPLE
-The following code segment demonstrates the use of
-.BR sigaltstack ()
-(and
-.BR sigaction (2))
-to install an alternate signal stack that is employed by a handler
-for the
-.BR SIGSEGV
-signal:
-.PP
-.in +4n
-.EX
-stack_t ss;
-
-ss.ss_sp = malloc(SIGSTKSZ);
-if (ss.ss_sp == NULL) {
- perror("malloc");
- exit(EXIT_FAILURE);
-}
-
-ss.ss_size = SIGSTKSZ;
-ss.ss_flags = 0;
-if (sigaltstack(&ss, NULL) == \-1)
- perror("sigaltstack");
- exit(EXIT_FAILURE);
-}
-
-sa.sa_flags = SA_ONSTACK;
-sa.sa_handler = handler(); /* Address of a signal handler */
-sigemptyset(&sa.sa_mask);
-if (sigaction(SIGSEGV, &sa, NULL) == -1) {
- perror("sigaction");
- exit(EXIT_FAILURE);
-}
-.EE
-.in
-.SH BUGS
-In Linux 2.2 and earlier, the only flag that could be specified
-in
-.I ss.sa_flags
-was
-.BR SS_DISABLE .
-In the lead up to the release of the Linux 2.4 kernel,
-.\" Linux 2.3.40
-.\" After quite a bit of web and mail archive searching,
-.\" I could not find the patch on any mailing list, and I
-.\" could find no place where the rationale for this change
-.\" explained -- mtk
-a change was made to allow
-.BR sigaltstack ()
-to allow
-.I ss.ss_flags==SS_ONSTACK
-with the same meaning as
-.IR "ss.ss_flags==0"
-(i.e., the inclusion of
-.B SS_ONSTACK
-in
-.I ss.ss_flags
-is a no-op).
-On other implementations, and according to POSIX.1,
-.B SS_ONSTACK
-appears only as a reported flag in
-.IR old_ss.ss_flags .
-On Linux, there is no need ever to specify
-.B SS_ONSTACK
-in
-.IR ss.ss_flags ,
-and indeed doing so should be avoided on portability grounds:
-various other systems
-.\" See the source code of Illumos and FreeBSD, for example.
-give an error if
-.B SS_ONSTACK
-is specified in
-.IR ss.ss_flags .
-.SH SEE ALSO
-.BR execve (2),
-.BR setrlimit (2),
-.BR sigaction (2),
-.BR siglongjmp (3),
-.BR sigsetjmp (3),
-.BR signal (7)
projects / thirdparty / man-pages.git / blobdiff