d/freebsd-nq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

MFC r207734: sigaltstack(2): document some modernizations:

Browse Source 
* un-document 'struct sigaltstack' tag for stack_t as this is BSD-specific;
  this doesn't seem useful enough to document as such
* alternate stacks are per thread, not per process
* update error codes to what the kernel does and POSIX requires
This commit is contained in:
Jilles Tjoelker 2010-05-13 15:44:49 +00:00
parent e6ca6764e8
commit 1270ecd86a
1 changed files with 15 additions and 17 deletions

32
lib/libc/sys/sigaltstack.2

@ -28,7 +28,7 @@
.\" @(#)sigaltstack.2 8.2 (Berkeley) 5/1/95 .\" @(#)sigaltstack.2 8.2 (Berkeley) 5/1/95
.\" $FreeBSD$ .\" $FreeBSD$
.\" .\"
.Dd May 1, 1995 .Dd May 6, 2010
.Dt SIGALTSTACK 2 .Dt SIGALTSTACK 2
.Os .Os
.Sh NAME .Sh NAME
@ -39,7 +39,7 @@
.Sh SYNOPSIS .Sh SYNOPSIS
.In signal.h .In signal.h
.Bd -literal .Bd -literal
typedef struct sigaltstack { typedef struct {
char *ss_sp; char *ss_sp;
size_t ss_size; size_t ss_size;
int ss_flags; int ss_flags;
@ -51,25 +51,25 @@ typedef struct sigaltstack {
The The
.Fn sigaltstack .Fn sigaltstack
system call system call
allows users to define an alternate stack on which signals allows defining an alternate stack on which signals
are to be processed. are to be processed for the current thread.
If If
.Fa ss .Fa ss
is non-zero, is non-zero,
it specifies a pointer to and the size of a it specifies a pointer to and the size of a
.Em "signal stack" .Em "signal stack"
on which to deliver signals, on which to deliver signals.
and tells the system if the process is currently executing
on that stack.
When a signal's action indicates its handler When a signal's action indicates its handler
should execute on the signal stack (specified with a should execute on the signal stack (specified with a
.Xr sigaction 2 .Xr sigaction 2
system call), the system checks to see system call), the system checks to see
if the process is currently executing on that stack. if the thread is currently executing on that stack.
If the process is not currently executing on the signal stack, If the thread is not currently executing on the signal stack,
the system arranges a switch to the signal stack for the the system arranges a switch to the signal stack for the
duration of the signal handler's execution. duration of the signal handler's execution.
.Pp .Pp
An active stack cannot be modified.
.Pp
If If
.Dv SS_DISABLE .Dv SS_DISABLE
is set in is set in
@ -78,12 +78,6 @@ is set in
and and
.Fa ss_size .Fa ss_size
are ignored and the signal stack will be disabled. are ignored and the signal stack will be disabled.
Trying to disable an active stack will cause
.Fn sigaltstack
to return -1 with
.Va errno
set to
.Er EINVAL .
A disabled stack will cause all signals to be A disabled stack will cause all signals to be
taken on the regular user stack. taken on the regular user stack.
If the stack is later re-enabled then all signals that were specified If the stack is later re-enabled then all signals that were specified
@ -96,7 +90,7 @@ The
.Fa ss_flags .Fa ss_flags
field will contain the value field will contain the value
.Dv SS_ONSTACK .Dv SS_ONSTACK
if the process is currently on a signal stack and if the thread is currently on a signal stack and
.Dv SS_DISABLE .Dv SS_DISABLE
if the signal stack is currently disabled. if the signal stack is currently disabled.
.Sh NOTES .Sh NOTES
@ -146,8 +140,12 @@ or
.Fa oss .Fa oss
points to memory that is not a valid part of the process points to memory that is not a valid part of the process
address space. address space.
.It Bq Er EPERM
An attempt was made to modify an active stack.
.It Bq Er EINVAL .It Bq Er EINVAL
An attempt was made to disable an active stack. The
.Fa ss_flags
field was invalid.
.It Bq Er ENOMEM .It Bq Er ENOMEM
Size of alternate stack area is less than or equal to Size of alternate stack area is less than or equal to
.Dv MINSIGSTKSZ . .Dv MINSIGSTKSZ .