 |
Index for
Section 2 |
|
 |
Alphabetical
listing for S |
|
 |
Bottom of
page |
|
sigaction(2)
NAME
sigaction - Specify 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 standards
as follows:
sigaction(): XSH4.0, XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
signal Defines the signal.
action Points to a sigaction structure that describes the action to be
taken upon receipt of the signal specified by the signal parameter.
o_action
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 identifies the signal that is to be
affected.
· Specifying the action parameter, 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.
· Specifying the o_action parameter, if not null, points to a sigaction
structure that contains the action previously attached to the
specified signal.
The XSH specification defines the following members for the sigaction
structure:
void (*sa_handler)(int);
sigset_t sa_mask;
int sa_flags;
[XSH4.2] The following additional member is defined in the sigaction
structure for use by POSIX realtime and UNIX programs that conform to XSH:
void(*) (int, siginfo_t *, void *) sa_sigaction;
These sigaction members are described as follows:
sa_sigaction
[XSH4.2] A pointer to a signal-handling function.
sa_handler
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 actions
are more fully described in <signal.h>.
sa_mask 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 executing.
sa_flags
This field can set the following flags to enable further control
over the actions taken when a signal is delivered:
SA_ONSTACK
[XSH4.2] 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.
SA_RESETHAND
[XSH4.2] Setting this bit causes the signal to be reset to
SIG_DFL. Note that SIGILL, SIGTRAP, and SIGPWR cannot be
automatically reset.
SA_NODEFER
[XSH4.2] Setting this bit causes the signal not to be blocked
automatically by the kernel as it is being caught.
SA_RESTART
[XSH4.2] 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].
SA_SIGINFO
[XSH4.2] If this bit is clear, the signal-catching function
adheres to the following format:
void func ( int signo );
In this format, signo is the only argument to the signal-
catching function. This argument contains the signal number. In
this case, the sa_handler member of the sigaction structure
must be used to describe the signal-catching function, and the
application must not modify the sa_sigaction member.
If the SA_SIGINFO bit is set and the signal is caught, the
signal-catching function adheres to the following format:
void func (
int signo,
siginfo_t *info,
void *context );
In this format, two additional arguments are passed to the
signal-catching function:
· If the info argument is not a null pointer, it points to a
structure of type siginfo_t that explains the reason why
the signal was generated. The si_signo member of this
structure contains the system-generated signal number. If
non-zero, the si_errno member contains an error number
identifying 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 the si_pid and si_uid members
indicate the process ID and the real user ID of the
sender. The values of si_pid and si_uid are otherwise
meaningless.
· The context argument can be cast to a pointer to an object
of type ucontext_t to refer to the receiving process'
context that was interrupted when the signal was
delivered. In this case, the sa_sigaction member of the
sigaction structure must be used to describe the signal
catching function, and the application must not modify the
sa_handler member.
[Tru64 UNIX] In the backward-compatible version of
sigaction(), the second and third arguments available to the
signal are defined as follows:
· If SA_SIGINFO is clear, the second argument is an integer
value providing additional error information for exception
signals (see <machine/signal.h>).
· The third argument points to a sigcontext structure
containing context information in a different format.
SA_NOCLDSTOP
If this bit is set and the signal parameter is equal to
SIGCHLD, a SIGCHLD signal is not sent to the calling process
when child processes terminate.
SA_NOCLDWAIT
[XSH4.2] 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 a wait(),
waitid(), waitpid(), or wait3() call is subsequently issued by
the calling process, it blocks until all of its child processes
terminate. The call 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.
SA_CLDNOTIFY
[Tru64 UNIX] If this bit is set in combination with
SA_SIGINFO, two SIGCHLD signals are queued to the parent for
each abnormal termination of a child process that includes 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
action.
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().
When SA_CLDNOTIFY is used without SA_SIGINFO, the early
notification signal is not sent to the parent.
Once an action is installed for a specific signal, it remains installed
until one of the following occurs:
· Another sigaction() call explicitly requests a different action.
· [XSH4.2] A signal causes the SA_RESETHAND flag to reset the signal
handler.
· A call is made 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
asynchronous signals.
NOTES
Only otherwise noted, sections in this reference page that are marked by
[XSH4.2] also apply to compilation environments conforming to higher
revisions of the XSH specification.
[Tru64 UNIX] When compiled in XSH4.2 and higher compilation environments,
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 or a more current
XSH compilation environment has been defined, use _Esigaction to refer to
the sigaction() call. See standards(5) for information about compilation
macro definitions for industry standards.
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:
[EFAULT]
[Tru64 UNIX] The action or o_action parameter points to a location
outside of the allocated address space of the process.
[EINVAL]
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.
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 shown 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);
}
SEE ALSO
Functions: acct(2), exit(2), kill(2), ptrace(2), sigblock(2),
sigprocmask(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)
|
Index for
Section 2 |
|
|
Alphabetical
listing for S |
|
 |
Top of
page |
|