FreeBSD Manual Pages
signal(3HEAD) Headers signal(3HEAD) NAME 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 invoca- tion 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(3HEAD). Signals can be generated synchronously or asynchronously. Events di- rectly caused by the execution of code by a thread, such as a reference to an unmapped, protected, or bad memory can generate SIGSEGV or SIG- BUS; 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(), or sigsend(). 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 asyn- chronously 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: o The thread is blocked in a call to sigwait(2) whose argument in- cludes the type of signal generated. o The thread has a signal mask that does not include the type of signal generated. A process responds to signals in similar ways whether it is using threads or it is using lightweight processes (LWPs). See thr_create(3THR). Each process may specify a system action to be taken in response to each signal sent to it, called the signal's disposition. All threads or LWPs 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 un- til another disposition is explicitly requested by a call to ei- ther 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 sig- nal(3C). SIGNAL DELIVERY A signal is said to be delivered to a process when a thread or LWP 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 creates a thread to handle the receipt of the signal sigaction() can be used for both synchronously and asynchronously generated signals. sigwait() will only work for asynchronously generated signals, as syn- chronously generated signals are sent to the thread that caused the event. sigwait() is the recommended interface for use with a multi- threaded application. See sigwait(2). SIGNAL MASK Each thread or LWP has a signal mask that defines the set of signals currently blocked from delivery to it. The signal mask of the main thread or LWP is inherited from the signal mask of the thread or LWP that created it in the parent process. The selection of the thread or LWP 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 or LWPs in the receiving process. Signals that are gen- erated by action of a particular thread or LWP such as hardware faults are delivered to the thread or LWP that caused the signal. See thr_sigsetmask(3THR) or sigprocmask(2). See alarm(2) for current seman- tics of delivery of SIGALRM. Signals that are directed to a particular thread or LWP are delivered to the targeted thread or LWP. See thr_kill(3THR) or _lwp_kill(2). If the selected thread or LWP has blocked the signal, it remains pending on the thread or LWP 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 or LWP) one of the threads or LWPs that does not have the signal blocked is selected to process the sig- nal. If all the threads or LWPs within the process block the signal, it remains pending on the process until a thread or LWP in the process un- blocks 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 or LWP within the process, allowing for any changes since the time of generation. This determination is independent of the means by which the signal was orig- inally generated. The signals currently defined by <signal.h> are as follows: Name Value Default Event SIGHUP 1 Exit Hangup (see termio(7I)) SIGINT 2 Exit Interrupt (see termio(7I)) SIGQUIT 3 Core Quit (see termio(7I)) 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(7I)) SIGSTOP 23 Stop Stopped (signal) SIGTSTP 24 Stop Stopped (user) (see termio(7I)) SIGCONT 25 Ignore Continued SIGTTIN 26 Stop Stopped (tty input) (see termio(7I)) SIGTTOU 27 Stop Stopped (tty output) (see termio(7I)) SIGVTALRM 28 Exit Virtual Timer Expired SIGPROF 29 Exit Profiling Timer Expired SIGXCPU 30 Core CPU time limit exceeded (see getr- limit(2)) SIGXFSZ 31 Core File size limit exceeded (see getr- limit(2)) SIGWAITING 32 Ignore Concurrency signal reserved by threads library SIGLWP 33 Ignore Inter-LWP signal reserved by threads library SIGFREEZE 34 Ignore Check point Freeze SIGTHAW 35 Ignore Check point Thaw SIGCANCEL 36 Ignore Cancellation signal reserved by threads library SIGXRES 37 Ignore Resource control exceeded (see setrctl(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 in or- der to permit future configurability. SIGNAL DISPOSITION A process, using a signal(3C), sigset(3C) or sigaction(2) system call, may 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 ac- tion 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 termi- nated with all the consequences outlined in exit(2). Core When it gets the signal, the receiving process is to be termi- nated 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 and LWPs 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 or LWP within the process that is selected to process the signal will execute the signal handler at the specified ad- dress. Normally, the signal handler is passed the signal number as its only argument; if the disposition was set with the sigaction() however, additional arguments may be requested (see sigaction(2)). When the sig- nal handler returns, the receiving process resumes execution at the point it was interrupted, unless the signal handler makes other ar- rangements. 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 or LWP while it is exe- cuting 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. However, if the SA_RESTART flag is set, the function call will be transparently restarted. Some signal-generating functions, such as high resolution timer expira- tion, asynchronous I/O completion, inter-process message arrival, and the sigqueue(3RT) function, 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: Member Member Type Name Description int sigev_notify Notification type int sigev_signo Signal number union sigval sigev_value Signal value The sigval union is defined by <signal.h> and contains at least the following members: Member Member 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 de- fined with the following values: SIGEV_NONE No asynchronous notification is delivered when the event of in- terest occurs. SIGEV_SIGNAL A queued signal, with its value application-defined, is generated when the event of interest occurs. Your implementation may define additional notification mechanisms. The sigev_signo member specifies the signal to be generated. The sigev_value member references the application defined value to be passed to the signal-catching function at the time of the signal deliv- ery as the si_value member of the siginfo_t structure. 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(3RT) 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 ap- plication 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. SEE ALSO intro(2), _lwp_kill(2), alarm(2), exit(2), getrlimit(2), ioctl(2), kill(2), pause(2), setrctl(2), sigaction(2), sigaltstack(2), sigproc- mask(2), sigsend(2), sigsuspend(2), sigwait(2), wait(2), setjmp(3C), siginfo(3HEAD), signal(3C), sigqueue(3RT), sigsetops(3C), thr_cre- ate(3THR), thr_kill(3THR), thr_sigsetmask(3THR), ucontext(3HEAD) NOTES The dispositions of the SIGKILL and SIGSTOP signals cannot be altered from their default values. The system generates an error if this is at- tempted. The SIGKILL and SIGSTOP signals cannot be blocked. The system silently enforces this restriction. 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 dispo- sition, 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. SunOS 5.9 6 Jun 2001 signal(3HEAD)
NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | NOTES
Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=signal&sektion=3head&manpath=SunOS+5.9>