sigaction, sigvec, or signal Subroutine

Purpose

Specifies the action to take upon delivery of a signal.

Libraries

Berkeley Compatibility Library (libbsd.a)

Syntax

Description

The sigaction subroutine allows a calling process to examine and change the action to be taken when a specific signal is delivered to the process issuing this subroutine.

In multi-threaded applications using the threads library (libpthreads.a), signal actions are common to all threads within the process. Any thread calling the sigaction subroutine changes the action to be taken when a specific signal is delivered to the threads process, that is, to any thread within the process.

The signal parameter specifies the signal. If the action parameter is not null, it points to a sigaction structure that describes the action to be taken on receipt of the signal parameter signal. If the oaction parameter is not null, it points to a sigaction structure in which the signal action data in effect at the time of the sigaction subroutine call is returned. If the action parameter is null, signal handling is unchanged; thus, the call can be used to inquire about the current handling of a given signal.

The sigaction structure has the following fields:

The sa_handler field can have a SIG_DFL or SIG_IGN value, or it can be a pointer to a function. A SIG_DFL value requests default action to be taken when a signal is delivered. A value of SIG_IGN requests that the signal have 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 "Parameters".

When a signal is delivered to a thread, if the action of that signal specifies termination, stop, or continue, the entire process is terminated, stopped, or continued, respectively.

If the SA_SIGINFO flag (see below) is cleared in the sa_flags field of the sigaction structure, the sa_handler field identifies the action to be associated with the specified signal. If the SA_SIGINFO flag is set in the sa_flags field, the sa_sigaction field specifies a signal-catching function. If the SA_SIGINFO bit is cleared and the sa_handler field specifies a signal-catching function, or if the SA_SIGINFO bit is set, the sa_mask field identifies a set of signals that will be added to the signal mask of the thread before the signal-catching function is invoked.

The sa_mask field can be used to specify that individual signals, in addition to those in the process signal mask, be blocked from being delivered while the signal handler function specified in the sa_handler field is operating. The sa_flags field can have the SA_ONSTACK, SA_OLDSTYLE, or SA_NOCLDSTOP bits set to specify further control over the actions taken on delivery of a signal.

If the SA_ONSTACK bit is set, the system runs the signal-catching function on the signal stack specified by the sigstack subroutine. If this bit is not set, the function runs on the stack of the process to which the signal is delivered.

If the SA_OLDSTYLE bit is set, the signal action is set to SIG_DFL label prior to calling the signal-catching function. This is supported for compatibility with old applications, and is not recommended since the same signal can recur before the signal-catching subroutine is able to reset the signal action and the default action (normally termination) is taken in that case.

If a signal for which a signal-catching function exists is sent to a process while that process is executing certain subroutines, the call can be restarted if the SA_RESTART bit is set for each signal. The only affected subroutines are the following:

• read,readx, readv, or readvx (read, readx, read64x, readv, readvx, eread, ereadv, pread, or preadv Subroutine)
• write,writex, writev, or writevx (write, writex, write64x, writev, writevx, ewrite, ewritev, pwrite, or pwritev Subroutine)
• ioctl or ioctlx
• fcntl, lockf, or flock
• wait, wait3, or waitpid (wait, waitpid, wait3, wait364, and wait4 Subroutine)

Other subroutines do not restart and return EINTR label, independent of the setting of the SA_RESTART bit.

If SA_SIGINFO is cleared and the signal is caught, the signal-catching function will be entered as: void func(int signo);

Where signo is the only argument to the signal catching function. In this case the sa_handler member must be used to describe the signal catching function and the application must not modify the sa_sigaction member. If SA_SIGINFO is set and the signal is caught, the signal-catching function will be entered as: void func(int signo, siginfo_t * info, void * context); where two additional arguments are passed to the signal catching function.

The second argument will point 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 receiving 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. The si_errno member may contain implementation-dependent additional error information. If nonzero, it 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, the signal was generated by a process and si_pid and si_uid respectively indicate the process ID and the real user ID of the sender.

The signal.h header description contains information about the signal specific contents of the elements of the siginfo_t type. If SA_NOCLDWAIT is set and sig equals SIGCHLD, child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and wait, wait3, waitid and waitpid will fail and set errno to ECHILD. Otherwise, terminating child processes will be transformed into zombie processes, unless SIGCHLD is set to SIG_IGN. When SIGCHLD is set to SIG_IGN, the signal is ignored and any zombie children of the process will be cleaned up.

If SA_RESETHAND is set, the disposition of the signal will be reset to SIG_DFL and the SA_SIGINFO flag will be cleared on entry to the signal handler.

If SA_NODEFER is set and sig is caught, sig will not be added to the process' signal mask on entry to the signal handler unless it is included in sa_mask. Otherwise, sig will always be added to the process' signal mask on entry to the signal handler. If sig is SIGCHLD, the SA_NOCLDSTOP flag is not set in sa_flags, and the implementation supports the SIGCHLD signal, a SIGCHLD signal will be generated for the calling process whenever any of its child processes stop.

If sig is SIGCHLD and the SA_NOCLDSTOP flag is set in sa_flags, the implementation will not generate a SIGCHLD signal in this way. When a signal is caught by a signal-catching function installed by sigaction, a new signal mask is calculated and installed for the duration of the signal-catching function (or until a call to either sigprocmask orsigsuspend is made).

This mask is formed by taking the union of the current signal mask and the value of the sa_mask for the signal being delivered unless SA_NODEFER or SA_RESETHAND is set, and including the signal being delivered. If the user's signal handler returns normally, the original signal mask is restored.

Once an action is installed for a specific signal, it remains installed until another action is explicitly requested (by another call to sigaction), until the SA_RESETHAND flag causes resetting of the handler, or until one of the exec functions is called.

If the previous action for sig had been established by signal, the values of the fields returned in the structure pointed to by oact are unspecified, and in particular oact->sa_handler is not necessarily the same value passed to signal.

However, if a pointer to the same structure or a copy thereof is passed to a subsequent call to sigaction through the act argument, handling of the signal will be as if the original call to signal were repeated.

If sigaction fails, no new signal handler is installed. It is unspecified whether an attempt to set the action for a signal that cannot be caught or ignored to SIG_DFL is ignored or causes an error to be returned with errno set to EINVAL.

If SA_SIGINFO is not set in sa_flags, then the disposition of subsequent occurrences of sig when it is already pending is implementation-dependent; the signal-catching function will be invoked with a single argument.

The sigvec and signal subroutines are provided for compatibility to older operating systems. Their function is a subset of that available with sigaction.

The sigvec subroutine uses the sigvec structure instead of the sigaction structure. The sigvec structure specifies a mask as an int instead of a sigset_t. The mask for the sigvec subroutine is constructed by setting the i-th bit in the mask if signal i is to be blocked. Therefore, the sigvec subroutine only allows signals between the values of 1 and 31 to be blocked when a signal-handling function is called. The other signals are not blocked by the signal-handler mask.

The sigvec structure has the following members:

int  (*sv_handler)();
/* signal handler */
int  sv_mask;
/* signal mask    */
int  sv_flags;
/* flags          */

The sigvec subroutine in the libbsd.a library interprets the SV_INTERRUPT flag and inverts it to the SA_RESTART flag of the sigaction subroutine. The sigvec subroutine in the libc.a library always sets the SV_INTERRUPT flag regardless of what was passed in the sigvec structure.

The signal subroutine in the libc.a library allows an action to be associated with a signal. The action parameter can have the same values that are described for the sv_handler field in the sigaction structure of thesigaction subroutine. However, no signal handler mask or flags can be specified; the signal subroutine implicitly sets the signal handler mask to additional signals and the flags to be SA_OLDSTYLE.

Upon successful completion of a signal call, the value of the previous signal action is returned. If the call fails, a value of -1 is returned and the errno global variable is set to indicate the error as in the sigaction call.

The signal in libc.a does not set the SA_RESTART flag. It sets the signal mask to the signal whose action is being specified, and sets flags to SA_OLDSTYLE. The Berkeley Software Distribution (BSD) version of signal sets the SA_RESTART flag and preserves the current settings of the signal mask and flags. The BSD version can be used by compiling with the Berkeley Compatibility Library (libbsd.a).

Parameters

signal

Defines the signal. The following list describes signal names and the specification for each. The value of the signal parameter can be any signal name from this list or its corresponding number except the SIGKILL name. If you use the signal name, you must include the signal.h file, because the name is correlated in the file with its corresponding number.

Note: The symbols in the following list of signals represent these actions:

*

Specifies the default action that includes creating a core dump file.

@

Specifies the default action that stops the process receiving these signals.

!

Specifies the default action that restarts or continues the process receiving these signals.

+

Specifies the default action that ignores these signals.

%

Indicates a likely shortage of paging space.

#

See Terminal Programming for more information on the use of these signals.

reserved

(26)

reserved

(37-58)

SIGALRM

Alarm clock. (14)

SIGBUS

Specification exception. (10*)

SIGCHLD

To parent on child stop or exit. (20+)

SIGCONT

Continue if stopped. (19!)

SIGDANGER

Paging space low. (33+%)

SIGEMT

EMT instruction. (7*)

SIGFPE

Arithmetic exception, integer divide by 0, or floating-point exception. (8*)

SIGHUP

Hang-up. (1)

SIGILL

Invalid instruction (not reset when caught). (4*)

SIGINT

Interrupt. (2)

SIGIO

Input/output possible or completed. (23+)

SIGGRANT

Monitor access wanted. (60#)

SIGMIGRATE

Migrate process. (35)

SIGMSG

Input data has been stored into the input ring buffer. (27#)

SIGPRE

Programming exception (user defined). (36)

SIGPROF

Profiling timer expired. (see the setitimer subroutine).(32)

SIGPWR

Power-fail restart. (29+)

SIGQUIT

Quit. (3*)

SIGIOT

End process (see the abort subroutine). (6*)

SIGKILL

Kill (cannot be caught or ignored). (9)

SIGPIPE

Write on a pipe when there is no process to read it. (13)

SIGRETRACT

Monitor access should be relinquished. (61#)

SIGSAK

Secure attention key. (63)

SIGSEGV

Segmentation violation. (11*)

SIGSOUND

A sound control has completed execution. (62#)

SIGSTOP

Stop (cannot be caught or ignored). (17@)

SIGSYS

Parameter not valid to subroutine. (12*)

SIGTALRM

Thread alarm clock. (38)

SIGTERM

Software termination signal. (15)

SIGTRAP

Trace trap (not reset when caught). (5*)

SIGTSTP

Interactive stop. (18@)

SIGTTIN

Background read attempted from control terminal. (21@)

SIGTTOU

Background write attempted from control terminal. (22@)

SIGURG

Urgent condition on I/O channel. (16+)

SIGUSR1

User-defined signal 1. (30)

SIGUSR2

User-defined signal 2. (31)

SIGVTALRM

Virtual time alarm (see the setitimer subroutine). (34)

SIGWINCH

Window size change. (28+)

SIGXCPU

CPU time limit exceeded (see the setrlimit subroutine). (24)

SIGXFSZ

File size limit exceeded (see the setrlimit subroutine).(25)

 

 

action

Points to a sigaction structure that describes the action to be taken upon receipt of the signal parameter signal.

The three types of actions that can be associated with a signal (SIG_DFL, SIG_IGN, or a pointer to a function) are described as follows:

• SIG_DFL Default action: signal-specific default action.

  Except for those signal numbers marked with a + (plus sign), @ (at sign), or ! (exclamation point), the default action for a signal ends the receiving process with all of the consequences described in the _exit subroutine. In addition, a memory image file is created in the current directory of the receiving process if an asterisk appears with a signal parameter and the following conditions are met:

  • All dumped cores are in the context of the running process. They are dumped with an owner and a group matching the effective user ID (UID) and group ID (GID) of the process. If this UID/GID pair does not have permission to write to the target directory that is determined according to the standard core path procedures, no core file is dumped.
  • If the real user ID (RUID) is root, the core file is dumped, with a mode of 0600.
  • If the effective user ID (EUID) matches the real user ID (RUID), and the effective group ID (EGID) matches any group in the credential's group list, the core file is dumped with permissions of 0600.
  • If the EUID matches the RUID, but the EGID does not match any group in the credential's group list, the core file cannot be dumped. The effective user cannot see data that they do not have access to.
  • If the EUID does not match the RUID, the core file can be dumped only if you have set a core directory using the syscorepath command. This avoids dumping the core file into either the current working directory or a user-specific core directory in such a way that you cannot remove the core file. Core is dumped with a mode of 0600. If you have not used the syscorepath command to set a core directory, no core is dumped.
  For signal numbers marked with a ! (exclamation point), the default action restarts the receiving process if it has stopped, or continues to run the receiving process.

  For signal numbers marked with a @ (at sign), the default action stops the execution of the receiving process temporarily. When a process stops, a SIGCHLD signal is sent to its parent process, unless the parent process has set the SA_NOCLDSTOP bit. While a process has stopped, any additional signals that are sent are not delivered until the process has started again. An exception to this is the SIGKILL signal, which always terminates the receiving process. Another exception is the SIGCONT signal, which always causes the receiving process to restart or continue running. A process whose parent process has ended is sent a SIGKILL signal if the SIGTSTP, SIGTTIN, or SIGTTOU signals are generated for that process.

  For signal numbers marked with a +, the default action ignores the signal. In this case, the delivery of a signal does not affect the receiving process.

  If a signal action is set to SIG_DFL while the signal is pending, the signal remains pending.

• SIG_IGN Ignore signal.

  Delivery of the signal does not affect the receiving process. If a signal action is set to the SIG_IGN action while the signal is pending, the pending signal is discarded.

  An exception to this is the SIGCHLD signal whose SIG_DFL action ignores the signal. If the action for the SIGCHLD signal is set to SIG_IGN, child processes of the calling processes will not be transformed into zombie processes when they terminate. If the calling process subsequently waits for its children, and the process has no unwaited for children that were transformed into zombie processes, it will block until all of its children terminate, and wait, wait3, waitid and waitpid will fail and set errno to ECHILD.

  Note: The SIGKILL and SIGSTOP signals cannot be ignored.
• Pointer to a function, catch signal.

  Upon delivery of the signal, the receiving process runs the signal-catching function specified by the pointer to function. The signal-handler subroutine can be declared as follows:

  handler(signal, Code, SCP)
  int signal, Code;
  struct sigcontext *SCP;

  The signal parameter is the signal number. The Code parameter is provided only for compatibility with other UNIX-compatible systems. The Code parameter value is always 0. The SCP parameter points to the sigcontext structure that is later used to restore the previous execution context of the process. The sigcontext structure is defined in the signal.h file.

  A new signal mask is calculated and installed for the duration of the signal-catching function (or until sigprocmask orsigsuspend subroutine is made). This mask is formed by joining the process-signal mask (the mask associated with the action for the signal being delivered) and the mask corresponding to the signal being delivered. The mask associated with the signal-catching function is not allowed to block those signals that cannot be ignored. This is enforced by the kernel without causing an error to be indicated. If and when the signal-catching function returns, the original signal mask is restored (modified by any sigprocmask calls that were made since the signal-catching function was called) and the receiving process resumes execution at the point it was interrupted.

  The signal-catching function can cause the process to resume in a different context by calling the longjmp subroutine. When the longjmp subroutine is called, the process leaves the signal stack, if it is currently on the stack, and restores the process signal mask to the state when the corresponding setjmp subroutine was made.

  Once an action is installed for a specific signal, it remains installed until another action is explicitly requested (by another call to the sigaction subroutine), or until one of the exec subroutines is called. An exception to this is when the SA_OLDSTYLE bit is set. In this case the action of a caught signal gets set to the SIG_DFL action before the signal-catching function for that signal is called.

  If a signal action is set to a pointer to a function while the signal is pending, the signal remains pending.

  The signal handler should not wait directly or indirectly on the input from a different thread in the form of a variable, pipe or anything similar. This will cause a deadlock in the case of a multithreaded application. As this will be a programmer initiated deadlock, the application will not handle it.

  When signal-catching functions are invoked asynchronously with process execution, the behavior of some of the functions defined by this standard is unspecified if they are called from a signal-catching function. The following set of functions are reentrant with respect to signals; that is, applications can invoke them, without restriction, from signal-catching functions:

  _exit

  access

  alarm

  cfgetispeed

  cfgetospeed

  cfsetispeed

  cfsetospeed

  chdir

  chmod

  chown

  close

  creat

  dup

  dup2

  exec

  execle

  execve

  fcntl

  fork

  fpathconf

  fstat

  getegid

  geteuid

  getgid

  getgroups

  getpgrp

  getpid

  getppid

  getuid

  kill

  link

  lseek

  mkdir

  mkfifo

  open

  pathconf

  pause

  pipe

  pread

  pwrite

  raise

  read

  readx

  rename

  rmdir

  setgid

  setpgid

  setpgrp

  setsid

  setuid

  sigaction

  sigaddset

  sigdelset

  sigemptyset

  sigismember

  signal

  sigpending

  sigprocmask

  sigsuspend

  sleep

  stat

  statx

  sysconf

  tcdrain

  tcflow

  tcflush

  tcgetattr

  tcgetpgrp

  tcsendbreak

  tcsetattr

  tcsetpgrp

  time

  times

  umask

  uname

  unlink

  ustat

  utime

  wait

  waitpid

  write

  All other subroutines should not be called from signal-catching functions since their behavior is undefined.

 

oaction

Points to a sigaction structure in which the signal action data in effect at the time of the sigaction subroutine is returned.

invec

Points to a sigvec structure that describes the action to be taken upon receipt of the signal parameter signal.

outvec

Points to a sigvec structure in which the signal action data in effect at the time of the sigvec subroutine is returned.

action

Specifies the action associated with a signal.

Return Values

Upon successful completion, the sigaction subroutine returns a value of 0. Otherwise, a value of SIG_ERR is returned and the errno global variable is set to indicate the error.

Error Codes

The sigaction subroutine is unsuccessful and no new signal handler is installed if one of the following occurs: