diff options
Diffstat (limited to 'man2/sigaltstack.2')
| -rw-r--r-- | man2/sigaltstack.2 | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/man2/sigaltstack.2 b/man2/sigaltstack.2 new file mode 100644 index 000000000..21c4597e5 --- /dev/null +++ b/man2/sigaltstack.2 @@ -0,0 +1,185 @@ +'\" t +.\" Copyright (c) 2001, Michael Kerrisk (mtk16@ext.canterbury.ac.nz) +.\" +.\" 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. +.\" +.\" Formatted or processed versions of this manual, if unaccompanied by +.\" the source, must acknowledge the copyright and authors of this work. +.\" +.\" aeb, various minor fixes +.TH SIGALTSTACK 2 2001-09-27 "Linux 2.4" "Linux Programmer's Manual" +.SH NAME +sigaltstack - set and/or get signal stack context +.SH SYNOPSIS +.B #include <signal.h> +.sp +.BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss ); +.SH DESCRIPTION +\fBsigaltstack\fP 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. + +The normal sequence of events for using an alternate signal stack +is the following: +.TP +1. +Allocate an area of memory to be used for the alternate +signal stack. +.TP +2. +Use \fBsigaltstack\fP to inform the system of the existence and +location of the alternate signal stack. +.TP +3. +When establishing a signal handler using \fBsigaction\fP, +inform the system that the signal handler should be executed +on the alternate signal stack by +specifying the \fBSA_ONSTACK\fP flag. +.P +The \fIss\fP argument is used to specify a new +alternate signal stack, while the \fIoss\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. +Each of these arguments is a structure of the following type: +.sp +.RS +.nf +typedef struct { + void *ss_sp; /* Base address of stack */ + int ss_flags; /* Flags */ + size_t ss_size; /* Number of bytes in stack */ +} stack_t; +.fi +.RE + +To establish a new alternate signal stack, +\fIss.ss_flags\fP is set to zero, and \fIss.sp_sp\fP and +\fIss.ss_size\fP specify the starting address and 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. + +To disable an existing stack, specify \fIss.ss_flags\fP +as \fBSS_DISABLE\fP. In this case, the remaining fields +in \fIss\fP are ignored. + +If \fIoss\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 \fBsigaltstack\fP. +The \fIoss.ss_sp\fP and \fIoss.ss_size\fP fields return the starting +address and size of that stack. +The \fIoss.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. + +.SH "RETURN VALUE" +\fBsigaltstack\fP 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 \fIoss\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 \fPss_flags\fP field contains +a non-zero value other than SS_DISABLE. +.TP +.B ENOMEM +The specified size of the new alternate signal stack +(\fIss.ss_size\fP) was less than \fBMINSTKSZ\fP. +.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 NOTES +The following code segment demonstrates the use of \fBsigaltstack\fP: + +.RS +.nf +stack_t ss; + +ss.ss_sp = malloc(SIGSTKSZ); +if (ss.ss_sp == NULL) + /* Handle error */; +ss.ss_size = SIGSTKSZ; +ss.ss_flags = 0; +if (sigaltstack(&ss, NULL) == -1) + /* Handle error */; +.fi +.RE +.P +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. +.P +On most hardware architectures supported by Linux, stacks grow +downwards. \fBsigaltstack\fP automatically takes account +of the direction of stack growth. +.P +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. +.P +A successful call to \fBexecve\fP removes any existing alternate +signal stack. +.P +\fBsigaltstack\fP supersedes the older \fBsigstack\fP call. +For backwards compatibility, glibc also provides \fBsigstack\fP. +All new applications should be written using \fBsigaltstack\fB. + +.SH HISTORY +BSD 4.2 had a \fIsigstack\fP() system call. It used a slightly +different struct, and had as major disadvantage that the caller +had to know the direction of stack growth. + +.SH "CONFORMING TO" +SUSv2, SVr4, POSIX 1003.1-2001. + +.SH "SEE ALSO" +.BR execve (2), +.BR setrlimit (2), +.BR sigaction (2), +.BR siglongjmp (3), +.BR sigsetjmp (3), +.BR signal (7) |