Go to main content

man pages section 3: Library Interfaces and Headers

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

signal(3HEAD)

Name

signal.h, signal - base signals

Synopsis

#include <signal.h>

Description

A signal is an asynchronous notification of an event. A signal is said to be generated for (or sent to) a process when the event associated with that signal first occurs. Examples of such events include hardware faults, timer expiration and terminal activity, as well as the invocation of the kill(2) or sigsend(2) functions. In some circumstances, the same event generates signals for multiple processes. A process may request a detailed notification of the source of the signal and the reason why it was generated. See siginfo.h(3HEAD).

Signals can be generated synchronously or asynchronously. Events directly caused by the execution of code by a thread, such as a reference to an unmapped, protected, or bad memory address can generate SIGSEGV or SIGBUS; a floating-point exception can generate SIGFPE; and the execution of an illegal instruction can generate SIGILL. Such events are referred to as traps; signals generated by traps are said to be synchronously generated. Synchronously generated signals are initiated by a specific thread and are delivered to and handled by that thread.

Signals may also be generated by calling kill(), sigqueue(), sigsend(), pthread_kill(), or pthread_sigqueue(). Events such as keyboard interrupts generate signals, such as SIGINT, which are sent to the target process. Such events are referred to as interrupts; signals generated by interrupts are said to be asynchronously generated. Asynchronously generated signals are not directed to a particular thread but are handled by an arbitrary thread that meets either of the following conditions:

  • The thread is blocked in a call to sigwait(2) whose argument includes the type of signal generated.

  • The thread has a signal mask that does not include the type of signal generated. See pthread_sigmask(3C). Each process can specify a system action to be taken in response to each signal sent to it, called the signal's disposition. All threads in the process share the disposition. The set of system signal actions for a process is initialized from that of its parent. Once an action is installed for a specific signal, it usually remains installed until another disposition is explicitly requested by a call to either sigaction(), signal() or sigset(), or until the process execs(). See sigaction(2) and signal(3C). When a process execs, all signals whose disposition has been set to catch the signal will be set to SIG_DFL. Alternatively, a process may request that the system automatically reset the disposition of a signal to SIG_DFL after it has been caught. See sigaction(2) and signal(3C).

SIGNAL DELIVERY

A signal is said to be delivered to a process when a thread within the process takes the appropriate action for the disposition of the signal. Delivery of a signal can be blocked. There are two methods for handling delivery of a signal in a multithreaded application. The first method specifies a signal handler function to execute when the signal is received by the process. See sigaction(2). The second method uses sigwait(2) to create a thread to handle the receipt of the signal. The sigaction() function can be used for both synchronously and asynchronously generated signals. The sigwait() function will work only for asynchronously generated signals, as synchronously generated signals are sent to the thread that caused the event. The sigwait() function is the recommended for use with a multithreaded application.

SIGNAL MASK

Each thread has a signal mask that defines the set of signals currently blocked from delivery to it. The signal mask of the main thread is inherited from the signal mask of the thread that created it in the parent process. The selection of the thread within the process that is to take the appropriate action for the signal is based on the method of signal generation and the signal masks of the threads in the receiving process. Signals that are generated by action of a particular thread such as hardware faults are delivered to the thread that caused the signal. See pthread_sigmask(3C) or sigprocmask(2). See alarm(2) for current semantics of delivery of SIGALRM. Signals that are directed to a particular thread are delivered to the targeted thread. See pthread_kill(3C). If the selected thread has blocked the signal, it remains pending on the thread until it is unblocked. For all other types of signal generation (for example, kill(2), sigsend(2), terminal activity, and other external events not ascribable to a particular thread) one of the threads that does not have the signal blocked is selected to process the signal. If all the threads within the process block the signal, it remains pending on the process until a thread in the process unblocks it. If the action associated with a signal is set to ignore the signal then both currently pending and subsequently generated signals of this type are discarded immediately for this process.

The determination of which action is taken in response to a signal is made at the time the signal is delivered to a thread within the process, allowing for any changes since the time of generation. This determination is independent of the means by which the signal was originally generated.

The signals currently defined by <signal.h> are as follows:

Name
Value
Default
Event
SIGHUP
1
Exit
Hangup (see termio(4I))
SIGINT
2
Exit
Interrupt (see termio(4I))
SIGQUIT
3
Core
Quit (see termio(4I))
SIGILL
4
Core
Illegal Instruction
SIGTRAP
5
Core
Trace or Breakpoint Trap
SIGABRT
6
Core
Abort
SIGEMT
7
Core
Emulation Trap
SIGFPE
8
Core
Arithmetic Exception
SIGKILL
9
Exit
Killed
SIGBUS
10
Core
Bus Error
SIGSEGV
11
Core
Segmentation Fault
SIGSYS
12
Core
Bad System Call
SIGPIPE
13
Exit
Broken Pipe
SIGALRM
14
Exit
Alarm Clock
SIGTERM
15
Exit
Terminated
SIGUSR1
16
Exit
User Signal 1
SIGUSR2
17
Exit
User Signal 2
SIGCHLD
18
Ignore
Child Status Changed
SIGPWR
19
Ignore
Power Fail or Restart
SIGWINCH
20
Ignore
Window Size Change
SIGURG
21
Ignore
Urgent Socket Condition
SIGPOLL
22
Exit
Pollable Event (see streamio(4I))
SIGSTOP
23
Stop
Stopped (signal)
SIGTSTP
24
Stop
Stopped (user) (see termio(4I))
SIGCONT
25
Ignore
Continued
SIGTTIN
26
Stop
Stopped (tty input) (see termio(4I))
SIGTTOU
27
Stop
Stopped (tty output) (see termio(4I))
SIGVTALRM
28
Exit
Virtual Timer Expired
SIGPROF
29
Exit
Profiling Timer Expired
SIGXCPU
30
Core
CPU time limit exceeded (see getrlimit(2))
SIGXFSZ
31
Core
File size limit exceeded (see getrlimit(2))
SIGWAITING
32
Ignore
Reserved
SIGLWP
33
Ignore
Reserved
SIGFREEZE
34
Ignore
Check point Freeze
SIGTHAW
35
Ignore
Check point Thaw
SIGCANCEL
36
Ignore
Reserved for threading support
SIGLOST
37
Exit
Resource lost (for example, record–lock lost)
SIGXRES
38
Ignore
Resource control exceeded (see setrctl(2))
SIGJVM1
39
Ignore
Reserved for Java Virtual Machine 1
SIGJVM2
40
Ignore
Reserved for Java Virtual Machine 2
SIGRTMIN
*
Exit
First real time signal
(SIGRTMIN+1)
*
Exit
Second real time signal
 . . .
(SIGRTMAX-1)
*
Exit
Second-to-last real time signal
SIGRTMAX
*
Exit
Last real time signal

The symbols SIGRTMIN through SIGRTMAX are evaluated dynamically to permit future configurability.

Applications should not use any of the signals marked “reserved” in the above table for any purpose, to avoid interfering with their use by the system.

SIGNAL DISPOSITION

A process using a signal(3C), sigset(3C) or sigaction(2) system call can specify one of three dispositions for a signal: take the default action for the signal, ignore the signal, or catch the signal.

Default Action: SIG_DFL

A disposition of SIG_DFL specifies the default action. The default action for each signal is listed in the table above and is selected from the following:

Exit

When it gets the signal, the receiving process is to be terminated with all the consequences outlined in exit(2).

Core

When it gets the signal, the receiving process is to be terminated with all the consequences outlined in exit(2). In addition, a core image of the process is constructed in the current working directory.

Stop

When it gets the signal, the receiving process is to stop. When a process is stopped, all the threads within the process also stop executing.

Ignore

When it gets the signal, the receiving process is to ignore it. This is identical to setting the disposition to SIG_IGN.

Ignore Signal: SIG_IGN

A disposition of SIG_IGN specifies that the signal is to be ignored. Setting a signal action to SIG_IGN for a signal that is pending causes the pending signal to be discarded, whether or not it is blocked. Any queued values pending are also discarded, and the resources used to queue them are released and made available to queue other signals.

Catch Signal: function address

A disposition that is a function address specifies that, when it gets the signal, the thread within the process that is selected to process the signal will execute the signal handler at the specified address. Normally, the signal handler is passed the signal number as its only argument. If the disposition was set with the sigaction(2) function, however, additional arguments can be requested. When the signal handler returns, the receiving process resumes execution at the point it was interrupted, unless the signal handler makes other arrangements. If an invalid function address is specified, results are undefined.

If the disposition has been set with the sigset() or sigaction(), the signal is automatically blocked in the thread while it is executing the signal catcher. If a longjmp() is used to leave the signal catcher, then the signal must be explicitly unblocked by the user. See setjmp(3C), signal(3C) and sigprocmask(2).

If execution of the signal handler interrupts a blocked function call, the handler is executed and the interrupted function call returns −1 to the calling process with errno set to EINTR. If the SA_RESTART flag is set, however, certain function calls will be transparently restarted.

Some signal-generating functions, such as high resolution timer expiration, asynchronous I/O completion, inter-process message arrival, and the sigqueue(3C) and pthread_sigqueue(3C) functions, support the specification of an application defined value, either explicitly as a parameter to the function, or in a sigevent structure parameter. The sigevent structure is defined by signal.h and contains at least the following members:

Type
Name
Description
int
sigev_notify
Notification type
int
sigev_signo
Signal number
union sigval
sigev_value
Signal value
void(*)(union sigval)
sigev_notify_function
Notification function
(pthread_attr_t *)
sigev_notify_attributes
Notification attributes

The sigval union is defined by signal.h and contains at least the following members:

Type
Name
Description
int
sival_int
Integer signal value
void *
sival_ptr
Pointer signal value

The sigev_notify member specifies the notification mechanism to use when an asynchronous event occurs. The sigev_notify member may be defined with the following values:

SIGEV_MEM

An asynchronous notification is provided by updating memory location when the event of interest occurs. Currently, supported only for aio_read(3C) and aio_write(3C) APIs. The memory location to be updated will be specified by the API that supports it.

SIGEV_NONE

No asynchronous notification is delivered when the event of interest occurs.

SIGEV_PORT

An asynchronous notification is delivered to an event port when the event of interest occurs. The sigev_value.sival_ptr member points to a port_notify_t structure defined in port.h (see port_associate(3C)). The event port identifier as well as an application-defined cookie are part of the port_notify_t structure.

SIGEV_SIGNAL

A queued signal, with its value equal to sigev_signo, is generated when the event of interest occurs.

SIGEV_SIGNAL_THR

A queued signal directed to the requesting thread, with its value equal to sigev_signo, is generated when the event of interest occurs.

SIGEV_THREAD

The sigev_notify_function is called, with sigev_value as its argument, to perform notification when the asynchronous event occurs. The function is executed in an environment as if it were the start routine for a newly created thread with thread attributes sigev_notify_attributes. If sigev_notify_attributes is NULL, the thread runs as a detached thread with default attributes. Otherwise, the thread runs with the specified attributes, but as a detached thread regardless. The thread runs with all blockable signals blocked.

The sigev_value member contains the application-defined value to be passed to the signal-catching function (for notification type SIGEV_SIGNAL and SIGEV_SIGNAL_THR) at the time of the signal delivery as the si_value member of the siginfo_t structure, or as the argument to the notification function (for notification type SIGEV_THREAD) that is called when the asynchronous event occurs. For notification type SIGEV_PORT, sigev_value.sival_ptr points to a port_notify_t structure that specifies the port and an application-defined cookie.

The sival_int member is used when the application defined value is of type int, and the sival_ptr member is used when the application defined value is a pointer.

When a signal is generated by sigqueue(3C), pthread_sigqueue(3C), or any signal−generating function which supports the specification of an application defined value, the signal is marked pending and, if the SA_SIGINFO flag is set for that signal, the signal is queued to the process along with the application specified signal value. Multiple occurrences of signals so generated are queued in FIFO order. If the SA_SIGINFO flag is not set for that signal, later occurrences of that signal's generation, when a signal is already queued, are silently discarded.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Interface Stability
Committed
Standard

See Also

alarm(2), exit(2), fcntl(2), getrlimit(2), Intro(2), ioctl(2), kill(2), pause(2), setrctl(2), sigaction(2), sigaltstack(2), sigprocmask(2), sigsend(2), sigsuspend(2), sigwait(2), port_associate(3C), pthread_create(3C), pthread_kill(3C), pthread_sigmask(3C), pthread_sigqueue(3C), setjmp(3C), signal(3C), sigqueue(3C), sigsetops(3C), timer_create(3C), wait(3C), siginfo.h(3HEAD), ucontext.h(3HEAD), attributes(7), standards(7), lockd(8)

Notes

The dispositions of the SIGKILL and SIGSTOP signals cannot be altered from their default values. The system generates an error if this is attempted.

The SIGKILL, SIGSTOP, and SIGCANCEL signals cannot be blocked. The system silently enforces this restriction.

The SIGCANCEL signal cannot be directed to an individual thread using pthread_kill(3C) or pthread_sigqueue(3C), but it can be sent to a process using kill(2), sigsend(2), or sigqueue(3C).

Whenever a process receives a SIGSTOP, SIGTSTP, SIGTTIN, or SIGTTOU signal, regardless of its disposition, any pending SIGCONT signal are discarded.

Whenever a process receives a SIGCONT signal, regardless of its disposition, any pending SIGSTOP, SIGTSTP, SIGTTIN, and SIGTTOU signals is discarded. In addition, if the process was stopped, it is continued.

SIGPOLL is issued when a file descriptor corresponding to a STREAMS file has a “selectable” event pending. See Intro(2). A process must specifically request that this signal be sent using the I_SETSIG ioctl call. Otherwise, the process will never receive SIGPOLL.

If the disposition of the SIGCHLD signal has been set with signal() or sigset(), or with sigaction() and the SA_NOCLDSTOP flag has been specified, it will only be sent to the calling process when its children exit; otherwise, it will also be sent when the calling process's children are stopped or continued due to job control.

The name SIGCLD is also defined in this header and identifies the same signal as SIGCHLD. SIGCLD is provided for backward compatibility, new applications should use SIGCHLD.

The disposition of signals that are inherited as SIG_IGN should not be changed.

Signals which are generated synchronously should not be masked. If such a signal is blocked and delivered, the receiving process is killed.