2004-11-03 13:51:07 +00:00
|
|
|
'\" t
|
2007-09-20 06:52:22 +00:00
|
|
|
.\" Copyright (c) 2001, Michael Kerrisk (mtk.manpages@gmail.com)
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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
|
2008-03-18 14:47:54 +00:00
|
|
|
.\" 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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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
|
chdir.2, chmod.2, chown.2, gethostname.2, getsid.2, pread.2, setpgid.2, sigaltstack.2, truncate.2, wait.2, dirfd.3, getsubopt.3, mkdtemp.3, mkstemp.3, siginterrupt.3, strdup.3: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-26 15:43:00 +00:00
|
|
|
.TH SIGALTSTACK 2 2010-09-26 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2005-07-06 06:54:27 +00:00
|
|
|
sigaltstack \- set and/or get signal stack context
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <signal.h>
|
|
|
|
.sp
|
|
|
|
.BI "int sigaltstack(const stack_t *" ss ", stack_t *" oss );
|
2007-07-08 12:11:40 +00:00
|
|
|
.sp
|
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
|
|
|
.sp
|
|
|
|
.BR sigaltstack ():
|
2010-09-17 15:42:21 +00:00
|
|
|
.ad l
|
|
|
|
.RS 4
|
2010-09-19 16:36:32 +00:00
|
|
|
.PD 0
|
brk.2, chroot.2, faccessat.2, fchmodat.2, fchownat.2, fstatat.2, futimesat.2, getdtablesize.2, getpagesize.2, getsid.2, linkat.2, mkdirat.2, mknodat.2, openat.2, pread.2, readlinkat.2, renameat.2, setpgid.2, sigaltstack.2, symlinkat.2, sync.2, timer_create.2, timer_delete.2, timer_getoverrun.2, timer_settime.2, unlinkat.2, utimensat.2, vfork.2, acosh.3, asinh.3, atanh.3, dirfd.3, dprintf.3, ecvt.3, expm1.3, fexecve.3, fmemopen.3, gcvt.3, getcwd.3, gethostid.3, getpass.3, getsubopt.3, getw.3, mbsnrtowcs.3, mkfifoat.3, mkstemp.3, mktemp.3, opendir.3, posix_memalign.3, rint.3, siginterrupt.3, stpcpy.3, stpncpy.3, strdup.3, strerror.3, strnlen.3, strsignal.3, strtol.3, strtoul.3, ualarm.3, usleep.3, wcpcpy.3, wcpncpy.3, wcscasecmp.3, wcsdup.3, wcsncasecmp.3, wcsnlen.3, wcsnrtombs.3: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-19 06:02:38 +00:00
|
|
|
_BSD_SOURCE || _XOPEN_SOURCE\ >=\ 500 ||
|
|
|
|
_XOPEN_SOURCE\ &&\ _XOPEN_SOURCE_EXTENDED
|
chdir.2, chmod.2, chown.2, gethostname.2, getsid.2, pread.2, setpgid.2, sigaltstack.2, stat.2, truncate.2, wait.2, dirfd.3, getsubopt.3, mkdtemp.3, mkstemp.3, siginterrupt.3, strdup.3: Simplify feature test macro requirements
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-26 15:16:57 +00:00
|
|
|
.br
|
|
|
|
|| /* Since glibc 2.12: */ _POSIX_C_SOURCE\ >=\ 200809L
|
2010-09-19 16:36:32 +00:00
|
|
|
.PD
|
2010-09-17 15:42:21 +00:00
|
|
|
.RE
|
|
|
|
.ad
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR sigaltstack ()
|
|
|
|
allows a process to define a new alternate
|
2004-11-03 13:51:07 +00:00
|
|
|
signal stack and/or retrieve the state of an existing
|
2007-04-12 22:42:49 +00:00
|
|
|
alternate signal stack.
|
|
|
|
An alternate signal stack is used during the
|
2004-11-03 13:51:07 +00:00
|
|
|
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:
|
2007-12-23 22:24:54 +00:00
|
|
|
.TP 3
|
2004-11-03 13:51:07 +00:00
|
|
|
1.
|
|
|
|
Allocate an area of memory to be used for the alternate
|
|
|
|
signal stack.
|
|
|
|
.TP
|
|
|
|
2.
|
2007-05-12 09:06:04 +00:00
|
|
|
Use
|
|
|
|
.BR sigaltstack ()
|
|
|
|
to inform the system of the existence and
|
2004-11-03 13:51:07 +00:00
|
|
|
location of the alternate signal stack.
|
|
|
|
.TP
|
|
|
|
3.
|
2007-05-12 09:06:04 +00:00
|
|
|
When establishing a signal handler using
|
|
|
|
.BR sigaction (2),
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-12-19 06:16:04 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
2007-12-19 06:16:04 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
To establish a new alternate signal stack,
|
2005-10-25 15:35:08 +00:00
|
|
|
\fIss.ss_flags\fP is set to zero, and \fIss.ss_sp\fP and
|
2004-11-03 13:51:07 +00:00
|
|
|
\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.
|
|
|
|
|
2007-04-12 22:42:49 +00:00
|
|
|
When a signal handler is invoked on the alternate stack,
|
|
|
|
the kernel automatically aligns the address given in \fIss.ss_sp\fP
|
2006-03-20 00:52:31 +00:00
|
|
|
to a suitable address boundary for the underlying hardware architecture.
|
2005-10-25 15:35:08 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
To disable an existing stack, specify \fIss.ss_flags\fP
|
2007-04-12 22:42:49 +00:00
|
|
|
as \fBSS_DISABLE\fP.
|
|
|
|
In this case, the remaining fields
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-05-12 09:06:04 +00:00
|
|
|
call to
|
|
|
|
.BR sigaltstack ().
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-04-12 22:42:49 +00:00
|
|
|
The process is currently executing on the alternate signal stack.
|
|
|
|
(Note that it is not possible
|
2004-11-03 13:51:07 +00:00
|
|
|
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"
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR sigaltstack ()
|
|
|
|
returns 0 on success, or \-1 on failure with
|
2004-11-03 13:51:07 +00:00
|
|
|
\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
|
2007-12-14 17:42:25 +00:00
|
|
|
\fIss\fP is not NULL and the \fIss_flags\fP field contains
|
intro.1, time.1, adjtimex.2, capget.2, eventfd.2, fcntl.2, getrlimit.2, getsockopt.2, gettimeofday.2, intro.2, ioctl_list.2, ioperm.2, mlock.2, pivot_root.2, poll.2, prctl.2, ptrace.2, sched_setscheduler.2, select_tut.2, semget.2, sigaltstack.2, signalfd.2, sysctl.2, timer_settime.2, timerfd_create.2, wait.2, CPU_SET.3, argz_add.3, assert_perror.3, atexit.3, backtrace.3, bcmp.3, clearenv.3, ctime.3, dl_iterate_phdr.3, dlopen.3, ecvt.3, errno.3, error.3, ether_aton.3, exit.3, fenv.3, ferror.3, finite.3, flockfile.3, fnmatch.3, fpathconf.3, fpclassify.3, ftime.3, ftok.3, ftw.3, fwide.3, getaddrinfo.3, gethostbyname.3, getlogin.3, getnameinfo.3, getnetent.3, getopt.3, getprotoent.3, getrpcent.3, getservent.3, glob.3, hsearch.3, inet.3, isalpha.3, iswalnum.3, iswalpha.3, iswblank.3, iswcntrl.3, iswctype.3, iswdigit.3, iswgraph.3, iswlower.3, iswprint.3, iswpunct.3, iswspace.3, iswupper.3, iswxdigit.3, longjmp.3, lsearch.3, malloc.3, matherr.3, mblen.3, mbsinit.3, mbtowc.3, on_exit.3, printf.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstack.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_equal.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, ptsname.3, putenv.3, putgrent.3, raise.3, rcmd.3, regex.3, rexec.3, rpc.3, rpmatch.3, rtnetlink.3, scandir.3, sem_init.3, setaliasent.3, setbuf.3, setenv.3, setjmp.3, signbit.3, stdio_ext.3, strtod.3, strtol.3, strtoul.3, system.3, termios.3, timeradd.3, tzset.3, ualarm.3, wctomb.3, xdr.3, st.4, tty_ioctl.4, core.5, elf.5, proc.5, bootparam.7, capabilities.7, icmp.7, ip.7, ipv6.7, math_error.7, mdoc.samples.7, mq_overview.7, pthreads.7, raw.7, regex.7, socket.7, tcp.7, tzselect.8: Global fix: s/non-zero/nonzero/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "non-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 16:40:55 +00:00
|
|
|
a nonzero value other than
|
2007-06-22 19:42:52 +00:00
|
|
|
.BR SS_DISABLE .
|
2004-11-03 13:51:07 +00:00
|
|
|
.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).
|
2007-05-18 16:30:46 +00:00
|
|
|
.SH "CONFORMING TO"
|
|
|
|
SUSv2, SVr4, POSIX.1-2001.
|
2007-05-18 11:59:14 +00:00
|
|
|
.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.
|
2004-11-03 13:51:07 +00:00
|
|
|
.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
|
Changes.old, clone.2, execve.2, fcntl.2, futex.2, getitimer.2, getpriority.2, mmap.2, mount.2, mprotect.2, sched_setscheduler.2, select_tut.2, setuid.2, sigaltstack.2, vfork.2, div.3, fenv.3, fmod.3, memchr.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_getattr_np.3, queue.3, scanf.3, trunc.3, st.4, proc.5, services.5, utmp.5, bootparam.7, capabilities.7, feature_test_macros.7, futex.7, glob.7, man.7, netlink.7, unicode.7: Switch to American usage: "-wards" ==> "-ward"
American English uses "afterward" in preference to "afterwards",
and so on
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-26 05:34:47 +00:00
|
|
|
downward.
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR sigaltstack ()
|
|
|
|
automatically takes account
|
2004-11-03 13:51:07 +00:00
|
|
|
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
|
2007-05-12 09:06:04 +00:00
|
|
|
A successful call to
|
|
|
|
.BR execve (2)
|
|
|
|
removes any existing alternate
|
2004-11-03 13:51:07 +00:00
|
|
|
signal stack.
|
2008-10-04 04:58:36 +00:00
|
|
|
A child process created via
|
Changes, clone.2, mount.2, nanosleep.2, sigaltstack.2, statfs.2, timer_settime.2, ctime.3, fmemopen.3, nl_langinfo.3, posix_memalign.3, pthread_attr_init.3, pthread_setaffinity_np.3, pthread_setschedprio.3, pthread_testcancel.3, setjmp.3, sigwait.3, tty_ioctl.4, epoll.7, posixoptions.7, unix.7: Add section number to references to functions documented in other pages
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-11-01 07:07:28 +00:00
|
|
|
.BR fork (2)
|
2008-10-04 04:58:36 +00:00
|
|
|
inherits a copy of its parent's alternate signal stack settings.
|
2004-11-03 13:51:07 +00:00
|
|
|
.P
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR sigaltstack ()
|
|
|
|
supersedes the older
|
|
|
|
.BR sigstack ()
|
|
|
|
call.
|
Changes.old, clone.2, execve.2, fcntl.2, futex.2, getitimer.2, getpriority.2, mmap.2, mount.2, mprotect.2, sched_setscheduler.2, select_tut.2, setuid.2, sigaltstack.2, vfork.2, div.3, fenv.3, fmod.3, memchr.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_getattr_np.3, queue.3, scanf.3, trunc.3, st.4, proc.5, services.5, utmp.5, bootparam.7, capabilities.7, feature_test_macros.7, futex.7, glob.7, man.7, netlink.7, unicode.7: Switch to American usage: "-wards" ==> "-ward"
American English uses "afterward" in preference to "afterwards",
and so on
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-09-26 05:34:47 +00:00
|
|
|
For backward compatibility, glibc also provides
|
2007-05-12 09:06:04 +00:00
|
|
|
.BR sigstack ().
|
|
|
|
All new applications should be written using
|
|
|
|
.BR sigaltstack ().
|
2007-05-18 11:59:14 +00:00
|
|
|
.SS History
|
2007-05-12 13:12:02 +00:00
|
|
|
4.2BSD had a
|
|
|
|
.BR sigstack ()
|
|
|
|
system call.
|
2007-04-12 22:42:49 +00:00
|
|
|
It used a slightly
|
2005-10-25 15:35:08 +00:00
|
|
|
different struct, and had the major disadvantage that the caller
|
2004-11-03 13:51:07 +00:00
|
|
|
had to know the direction of stack growth.
|
2007-05-19 04:30:20 +00:00
|
|
|
.SH EXAMPLE
|
|
|
|
The following code segment demonstrates the use of
|
|
|
|
.BR sigaltstack ():
|
|
|
|
|
2007-12-19 06:16:04 +00:00
|
|
|
.in +4n
|
2007-05-19 04:30:20 +00:00
|
|
|
.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
|
2007-12-19 06:16:04 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR execve (2),
|
|
|
|
.BR setrlimit (2),
|
|
|
|
.BR sigaction (2),
|
|
|
|
.BR siglongjmp (3),
|
|
|
|
.BR sigsetjmp (3),
|
|
|
|
.BR signal (7)
|