Manual Page Result
0
Command: sigaction | Section: 2 | Source: Digital UNIX | File: sigaction.2.gz
sigaction(2) System Calls Manual sigaction(2)
NAME
sigaction - Specifies the action to take upon delivery of a signal
SYNOPSIS
#include <signal.h>
int sigaction(
int signal,
const struct sigaction *action,
struct sigaction *o_action);
STANDARDS
Interfaces documented on this reference page conform to industry stan-
dards as follows:
sigaction(): XPG4, XPG4-UNIX
Refer to the standards(5) reference page for more information about in-
dustry standards and associated tags.
PARAMETERS
Defines the signal. Points to a sigaction structure that describes the
action to be taken upon receipt of the signal specified by the signal
parameter. Points to a sigaction structure. When the sigaction()
function returns from a call, the action previously attached to the
specified signal is stored in this structure.
DESCRIPTION
When a process requests the sigaction() function, the process can both
examine or specify what action is to be performed when the specified
signal is delivered. The parameters determine the behavior of the
sigaction() function as follows: Specifying the signal parameter iden-
tifies the signal that is to be affected. Specifying the action para-
meter, if not null, points to a sigaction structure that defines what
action is to be performed when the signal is received. If the action
parameter is null, signal handling remains unchanged; thus the call can
be used to inquire about the current handling of the signal. Specify-
ing the o_action parameter, if not null, points to a sigaction struc-
ture that contains the action previously attached to the specified sig-
nal.
The X/Open Base Standard defines the following members for the sigac-
tion structure: (*sa_handler)(int); sa_mask; sa_flags;
[XPG4-UNIX] The following additional member is defined in the sigac-
tion structure for use by realtime and X/Open UNIX programs: sa_sigac-
tion;
The members are defined as follows: [XPG4-UNIX] A pointer to a signal-
handling function. This field can contain a value of SIG_DFL or
SIG_IGN, or it can point to a function. A SIG_DFL value specifies the
default action is to be taken when the signal is delivered. A value of
SIG_IGN specifies that the signal has no effect on the receiving
process. A pointer to a function requests that the signal be caught;
that is, the signal should cause the function to be called. These ac-
tions are more fully described in the <signal.h> file. This field can
request that individual signals, in addition to those in the current
signal mask, be blocked from being delivered while the signal handler
function specified by the sa_handler or sa_sigaction field is execut-
ing. This field can set the following flags to enable further control
over the actions taken when a signal is delivered: [XPG4-UNIX] Setting
this bit causes the system to run the signal-catching function on the
signal stack specified by the sigaltstack() and sigstack() functions.
If this bit is not set, the function runs on the stack of the process
to which the signal is delivered. [XPG4-UNIX] Setting this bit causes
the signal to be reset to SIG_DFL. Note that SIGILL, SIGTRAP, and SIG-
PWR cannot be automatically reset. [XPG4-UNIX] Setting this bit
causes the signal not to be blocked automatically by the kernel as it
is being caught. [XPG4-UNIX] Setting this bit enables a function that
has been interrupted by the execution of this signal's handler to be
restarted transparently by the system. The affected functions include
wait(), and the read() and write() functions on a slow device (such as
a terminal, but not a regular file). If this bit is not set and one of
the previously mentioned functions is interrupted by a signal which is
caught, the function returns the value -1 and sets errno to [EINTR].
[XPG4-UNIX] If this bit is clear, the signal-catching function is en-
tered as:
void func(int signo);
where signo is the only argument to the signal catching func-
tion. In this case, the sa_handler member must be used to de-
scribe the signal-catching function, and the application must
not modify the sa_sigaction member.
If this bit is set and the signal is caught, the signal-catching
function is entered as:
void func(int signo, siginfo_t *info, void *context);
where two additional arguments are passed to the signal-catching
function. If the second argument is not a null pointer, it
points to an object of type siginfo_t explaining the reason why
the signal was generated. The third argument can be cast to a
pointer to an object of type ucontext_t to refer to the receiv-
ing process' context that was interrupted when the signal was
delivered. In this case, the sa_sigaction member must be used
to describe the signal catching function and the application
must not modify the sa_handler member.
The si_signo member contains the system-generated signal number.
If non-zero, the si_errno member contains an error number iden-
tifying the condition that caused the signal to be generated.
The si_code member contains a code identifying the cause of the
signal. If the value of si_code is less than or equal to 0,
then the signal was generated by a process, and si_pid and
si_uid indicate the process ID and the real user ID of the
sender. The values of si_pid and si_uid are otherwise meaning-
less.
[DIGITAL] In the backward-compatible version of sigaction(),
the second and third arguments available to the signal are de-
fined as follows: If SA_SIGINFO is clear, the second argument is
an integer value providing additional error information for ex-
ception signals (see <machine/signal.h>). The third argument
points to a sigcontext structure containing context information
in a different format. If this bit is set and the signal para-
meter is equal to SIGCHLD, a SIGCHLD signal is not sent to the
calling process when child processes terminate. [XPG4-UNIX] If
this bit is set and the signal parameter is equal to SIGCHLD,
zombie processes are not created by the system when a child
process of the calling process exits. If the wait function is
subsequently issued by the calling process, it blocks until all
of its child processes terminate. It then returns a value of -1
and errno is set to ECHILD to indicate the error. Note: when
this flag is set, exiting child processes do not send SIGCHLD
signals to the parent. [DIGITAL] If this bit is set in combina-
tion with SA_SIGINFO, two SIGCHLD signals are queued to the par-
ent for each abnormal termination of a child process that in-
cludes a core dump: an early notification signal and a final
notification signal.
The early notification signal delivers a siginfo structure with
the si_signo field set to SIGCHLD, the si_code field set to
CLD_SIGEXITING, and the si_pid field set to the process ID of
the child process that is about to write a core file and then
terminate abnormally. This signal tells the parent process that
it can start a failover operation or take other appropriate ac-
tion.
The final notification signal delivers a siginfo structure with
the si_signo field set to SIGCHLD, the si_code field set to
CLD_DUMPED, and the si_pid field set to the process ID of the
child that has terminated abnormally. This signal tells the
parent process that the child process is now a zombie and can be
cleaned up with a call to wait(2).
When SA_CLDNOTIFY is used without SA_SIGINFO, the early notifi-
cation signal is not sent to the parent.
Once an action is installed for a specific signal, it remains installed
until one of the following events occurs: A sigaction() call that ex-
plicitly requests a different action. [XPG4-UNIX] A signal that causes
the SA_RESETHAND flag to reset the signal handler. A call to one of
the exec* functions.
The signal parameter can be any one of the signal values defined in the
signal.h header file, except SIGKILL and SIGSTOP.
In a multithreaded environment, the sigaction() function should only be
used for the synchronous signals. Use the sigwait() function for asyn-
chronous signals.
NOTES
[DIGITAL] When compiled in the X/Open UNIX environment, calls to the
sigaction() function are internally renamed by prepending _E to the
function name. When you are debugging a module that includes the
sigaction() function and for which _XOPEN_SOURCE_EXTENDED has been de-
fined, use _Esigaction to refer to the sigaction() call. See stan-
dards(5) for information on when the _XOPEN_SOURCE_EXTENDED macro is
defined.
EXAMPLE
The following program illustrates the use of the SA_CLDNOTIFY flag:
#include <stdio.h>
#include <sys/types.h>
#include <sys/signal.h>
#include <sys/siginfo.h>
volatile pid_t kid1, kid2;
/*
* Handler for SIGHCLD signal. Note: printf() calls
* are technically unsupported from signal handlers
* and are show for illustrative purposes only.
*/
void
sigchld_handler(int sig, siginfo_t *sip, void *extra)
{
pid_t kid;
kid = sip->si_pid;
if (sip->si_code == CLD_SIGEXITING) {
printf("SIGEXITING: Got signal %d, si_code %d"
" for kid %d\n",
sip->si_signo, sip->si_code, kid);
} else if (sip->si_code == CLD_DUMPED) {
printf("EXITED: Got signal %d, si_code %d"
" for kid %d\n",
sip->si_signo, sip->si_code, kid);
kid = wait(0);
printf("Parent got PID %d exiting\n", kid);
if (kid == kid1)
kid1 = 0;
else if (kid == kid2)
kid2 = 0;
}
}
main()
{
struct sigaction sa;
int ret;
/*
* Set up SIGHCLD handler for early exit
* notification.
*/
sa.sa_sigaction = sigchild_handler;
sigemptyset(&sa.sa_mask);
sa.sa_flags = SA_CLDNOTIFY|SA_SIGINFO;
ret = sigaction(SIGCHLD, &sa, 0);
if (ret) {
perror("sigaction");
exit(1);
}
/*
* Create 2 children to die with SIGABRT
* and create core files.
*/
kid1 = fork();
if (kid1)
printf("Parent forked %d\n", kid1);
else {
/*
* First child...
*/
sleep(1);
printf("Kid %d will now die with core
file...\n",
getpid());
abort();
/*NOTREACHED*/
}
kid2 = fork();
if (kid2)
printf("Parent forked %d\n", kid2);
else {
/*
* Second child...
*/
sleep(1);
printf("Kid %d will now die with core
file...\n",
getpid());
abort();
/*NOTREACHED*/
}
/*
* Parent: keep busy until children exit.
*/
while (kid1 || kid2)
;
/*
* Children have exit: verify by printing zeros.
*/
printf("Parent: done -- kid1 %d, kid2 %d\n", kid1,
kid2);
;
/*
* Children have exit: verify by printing zeros.
*/
printf("Parent: done -- kid1 %d, kid2 %d\n", kid1,
kid2);
}
RETURN VALUES
Upon successful completion of the sigaction() function, a value of zero
(0) is returned. If the sigaction() function fails, a value of -1 is
returned and errno is set to indicate the error.
ERRORS
If the sigaction() function fails, no new signal handler is installed
and errno may be set to one of the following values: [DIGITAL] The ac-
tion or o_action parameter points to a location outside of the allo-
cated address space of the process. The signal parameter is not a
valid signal number.
An attempt was made to ignore or supply a handler for the
SIGKILL and SIGSTOP signals.
RELATED INFORMATION
Functions: acct(2), exit(2), kill(2), ptrace(2), sigblock(2), sigproc-
mask(2), sigstack(2), sigsuspend(2), sigvec(2), umask(2), wait(2),
pause(3), setjmp(3), sigpause(3)
Commands: kill(1)
Files: signal(4)
Standards: standards(5) delim off
sigaction(2)