Standard Signals

This section lists the names for various standard kinds of signals and describes what kind of event they mean. Each signal name is a macro which stands for a positive integer--the signal number for that kind of signal. Your programs should never make assumptions about the numeric code for a particular kind of signal, but rather refer to them always by the names defined here. This is because the number for a given kind of signal can vary from system to system, but the meanings of the names are standardized and fairly uniform.

The signal names are defined in the header file signal.h.

int function>NSIG/function> The value of this symbolic constant is the total number of signals defined. Since the signal numbers are allocated consecutively, NSIG is also one greater than the largest defined signal number.

Program Error Signals

The following signals are generated when a serious program error is detected by the operating system or the computer itself. In general, all of these signals are indications that your program is seriously broken in some way, and there's usually no way to continue the computation which encountered the error.

Some programs handle program error signals in order to tidy up before terminating; for example, programs that turn off echoing of terminal input should handle program error signals in order to turn echoing back on. The handler should end by specifying the default action for the signal that happened and then reraising it; this will cause the program to terminate with that signal, as if it had not had a handler. (the section called “Handlers That Terminate the Process”.)

Termination is the sensible ultimate outcome from a program error in most programs. However, programming systems such as Lisp that can load compiled user programs might need to keep executing even if a user program incurs an error. These programs have handlers which use longjmp to return control to the command level.

The default action for all of these signals is to cause the process to terminate. If you block or ignore these signals or establish handlers for them that return normally, your program will probably break horribly when such signals happen, unless they are generated by raise or kill instead of a real error.

When one of these program error signals terminates a process, it also writes a core dump file which records the state of the process at the time of termination. The core dump file is named core and is written in whichever directory is current in the process at the time. (On the GNU system, you can specify the file name for core dumps with the environment variable COREFILE.) The purpose of core dump files is so that you can examine them with a debugger to investigate what caused the error.

int function>SIGFPE/function> The SIGFPE signal reports a fatal arithmetic error. Although the name is derived from "floating-point exception", this signal actually covers all arithmetic errors, including division by zero and overflow. If a program stores integer data in a location which is then used in a floating-point operation, this often causes an "invalid operation" exception, because the processor cannot recognize the data as a floating-point number. Actual floating-point exceptions are a complicated subject because there are many types of exceptions with subtly different meanings, and the SIGFPE signal doesn't distinguish between them. The [IEEE Standard for Binary Floating-Point Arithmetic (ANSI/IEEE Std 754-1985 and ANSI/IEEE Std 854-1987)] defines various floating-point exceptions and requires conforming computer systems to report their occurrences. However, this standard does not specify how the exceptions are reported, or what kinds of handling and control the operating system can offer to the programmer.

BSD systems provide the SIGFPE handler with an extra argument that distinguishes various causes of the exception. In order to access this argument, you must define the handler to accept two arguments, which means you must cast it to a one-argument function type in order to establish the handler. The GNU library does provide this extra argument, but the value is meaningful only on operating systems that provide the information (BSD systems and GNU systems).

FPE_INTOVF_TRAP

Integer overflow (impossible in a C program unless you enable overflow trapping in a hardware-specific fashion).

FPE_INTDIV_TRAP

Integer division by zero.

FPE_SUBRNG_TRAP

Subscript-range (something that C programs never check for).

FPE_FLTOVF_TRAP

Floating overflow trap.

FPE_FLTDIV_TRAP

Floating/decimal division by zero.

FPE_FLTUND_TRAP

Floating underflow trap. (Trapping on floating underflow is not normally enabled.)

FPE_DECOVF_TRAP

Decimal overflow trap. (Only a few machines have decimal arithmetic and C never uses it.)

int function>SIGILL/function> The name of this signal is derived from "illegal instruction"; it usually means your program is trying to execute garbage or a privileged instruction. Since the C compiler generates only valid instructions, SIGILL typically indicates that the executable file is corrupted, or that you are trying to execute data. Some common ways of getting into the latter situation are by passing an invalid object where a pointer to a function was expected, or by writing past the end of an automatic array (or similar problems with pointers to automatic variables) and corrupting other data on the stack such as the return address of a stack frame.

SIGILL can also be generated when the stack overflows, or when the system has trouble running the handler for a signal. int function>SIGSEGV/function> This signal is generated when a program tries to read or write outside the memory that is allocated for it, or to write memory that can only be read. (Actually, the signals only occur when the program goes far enough outside to be detected by the system's memory protection mechanism.) The name is an abbreviation for "segmentation violation".

Common ways of getting a SIGSEGV condition include dereferencing a null or uninitialized pointer, or when you use a pointer to step through an array, but fail to check for the end of the array. It varies among systems whether dereferencing a null pointer generates SIGSEGV or SIGBUS.

int function>SIGBUS/function> This signal is generated when an invalid pointer is dereferenced. Like SIGSEGV, this signal is typically the result of dereferencing an uninitialized pointer. The difference between the two is that SIGSEGV indicates an invalid access to valid memory, while SIGBUS indicates an access to an invalid address. In particular, SIGBUS signals often result from dereferencing a misaligned pointer, such as referring to a four-word integer at an address not divisible by four. (Each kind of computer has its own requirements for address alignment.)

The name of this signal is an abbreviation for "bus error". int function>SIGABRT/function> This signal indicates an error detected by the program itself and reported by calling abort. the section called “Aborting a Program ”.

int function>SIGIOT/function> Generated by the PDP-11 "iot" instruction. On most machines, this is just another name for SIGABRT.

int function>SIGTRAP/function> Generated by the machine's breakpoint instruction, and possibly other trap instructions. This signal is used by debuggers. Your program will probably only see SIGTRAP if it is somehow executing bad instructions.

int function>SIGEMT/function> Emulator trap; this results from certain unimplemented instructions which might be emulated in software, or the operating system's failure to properly emulate them.

int function>SIGSYS/function> Bad system call; that is to say, the instruction to trap to the operating system was executed, but the code number for the system call to perform was invalid.

Termination Signals

These signals are all used to tell a process to terminate, in one way or another. They have different names because they're used for slightly different purposes, and programs might want to handle them differently.

The reason for handling these signals is usually so your program can tidy up as appropriate before actually terminating. For example, you might want to save state information, delete temporary files, or restore the previous terminal modes. Such a handler should end by specifying the default action for the signal that happened and then reraising it; this will cause the program to terminate with that signal, as if it had not had a handler. (the section called “Handlers That Terminate the Process”.)

The (obvious) default action for all of these signals is to cause the process to terminate.

int function>SIGTERM/function> The SIGTERM signal is a generic signal used to cause program termination. Unlike SIGKILL, this signal can be blocked, handled, and ignored. It is the normal way to politely ask a program to terminate.

The shell command kill generates SIGTERM by default. int function>SIGINT/function> The SIGINT ("program interrupt") signal is sent when the user types the INTR character (normally C-c). the section called “Special Characters”, for information about terminal driver support for C-c.

int function>SIGQUIT/function> The SIGQUIT signal is similar to SIGINT, except that it's controlled by a different key--the QUIT character, usually C-\--and produces a core dump when it terminates the process, just like a program error signal. You can think of this as a program error condition "detected" by the user.

the section called “Program Error Signals”, for information about core dumps. the section called “Special Characters”, for information about terminal driver support.

Certain kinds of cleanups are best omitted in handling SIGQUIT. For example, if the program creates temporary files, it should handle the other termination requests by deleting the temporary files. But it is better for SIGQUIT not to delete them, so that the user can examine them in conjunction with the core dump.

int function>SIGKILL/function> The SIGKILL signal is used to cause immediate program termination. It cannot be handled or ignored, and is therefore always fatal. It is also not possible to block this signal.

This signal is usually generated only by explicit request. Since it cannot be handled, you should generate it only as a last resort, after first trying a less drastic method such as C-c or SIGTERM. If a process does not respond to any other termination signals, sending it a SIGKILL signal will almost always cause it to go away.

In fact, if SIGKILL fails to terminate a process, that by itself constitutes an operating system bug which you should report.

The system will generate SIGKILL for a process itself under some unusual conditions where the program cannot possibly continue to run (even to run a signal handler). int function>SIGHUP/function> The SIGHUP ("hang-up") signal is used to report that the user's terminal is disconnected, perhaps because a network or telephone connection was broken. For more information about this, see the section called “Control Modes”.

This signal is also used to report the termination of the controlling process on a terminal to jobs associated with that session; this termination effectively disconnects all processes in the session from the controlling terminal. For more information, see the section called “Termination Internals”.

Alarm Signals

These signals are used to indicate the expiration of timers. the section called “Setting an Alarm”, for information about functions that cause these signals to be sent.

The default behavior for these signals is to cause program termination. This default is rarely useful, but no other default would be useful; most of the ways of using these signals would require handler functions in any case.

int function>SIGALRM/function> This signal typically indicates expiration of a timer that measures real or clock time. It is used by the alarm function, for example. int function>SIGVTALRM/function> This signal typically indicates expiration of a timer that measures CPU time used by the current process. The name is an abbreviation for "virtual time alarm". int function>SIGPROF/function> This signal typically indicates expiration of a timer that measures both CPU time used by the current process, and CPU time expended on behalf of the process by the system. Such a timer is used to implement code profiling facilities, hence the name of this signal.

Asynchronous I/O Signals

The signals listed in this section are used in conjunction with asynchronous I/O facilities. You have to take explicit action by calling fcntl to enable a particular file descriptor to generate these signals (the section called “Interrupt-Driven Input”). The default action for these signals is to ignore them.

int function>SIGIO/function> This signal is sent when a file descriptor is ready to perform input or output.

On most operating systems, terminals and sockets are the only kinds of files that can generate SIGIO; other kinds, including ordinary files, never generate SIGIO even if you ask them to.

In the GNU system SIGIO will always be generated properly if you successfully set asynchronous mode with fcntl.

int function>SIGURG/function> This signal is sent when "urgent" or out-of-band data arrives on a socket. the section called “Out-of-Band Data”.

int function>SIGPOLL/function> This is a System V signal name, more or less similar to SIGIO. It is defined only for compatibility.

Job Control Signals

These signals are used to support job control. If your system doesn't support job control, then these macros are defined but the signals themselves can't be raised or handled.

You should generally leave these signals alone unless you really understand how job control works. Chapter 28.

int function>SIGCHLD/function> This signal is sent to a parent process whenever one of its child processes terminates or stops.

The default action for this signal is to ignore it. If you establish a handler for this signal while there are child processes that have terminated but not reported their status via wait or waitpid (the section called “Process Completion”), whether your new handler applies to those processes or not depends on the particular operating system.

int function>SIGCLD/function> This is an obsolete name for SIGCHLD.

int function>SIGCONT/function> You can send a SIGCONT signal to a process to make it continue. This signal is special--it always makes the process continue if it is stopped, before the signal is delivered. The default behavior is to do nothing else. You cannot block this signal. You can set a handler, but SIGCONT always makes the process continue regardless.

Most programs have no reason to handle SIGCONT; they simply resume execution without realizing they were ever stopped. You can use a handler for SIGCONT to make a program do something special when it is stopped and continued--for example, to reprint a prompt when it is suspended while waiting for input.

int function>SIGSTOP/function> The SIGSTOP signal stops the process. It cannot be handled, ignored, or blocked. int function>SIGTSTP/function> The SIGTSTP signal is an interactive stop signal. Unlike SIGSTOP, this signal can be handled and ignored.

Your program should handle this signal if you have a special need to leave files or system tables in a secure state when a process is stopped. For example, programs that turn off echoing should handle SIGTSTP so they can turn echoing back on before stopping.

This signal is generated when the user types the SUSP character (normally C-z). For more information about terminal driver support, see the section called “Special Characters”. int function>SIGTTIN/function> A process cannot read from the user's terminal while it is running as a background job. When any process in a background job tries to read from the terminal, all of the processes in the job are sent a SIGTTIN signal. The default action for this signal is to stop the process. For more information about how this interacts with the terminal driver, see the section called “Access to the Controlling Terminal”. int function>SIGTTOU/function> This is similar to SIGTTIN, but is generated when a process in a background job attempts to write to the terminal or set its modes. Again, the default action is to stop the process. SIGTTOU is only generated for an attempt to write to the terminal if the TOSTOP output mode is set; the section called “Output Modes”. While a process is stopped, no more signals can be delivered to it until it is continued, except SIGKILL signals and (obviously) SIGCONT signals. The signals are marked as pending, but not delivered until the process is continued. The SIGKILL signal always causes termination of the process and can't be blocked, handled or ignored. You can ignore SIGCONT, but it always causes the process to be continued anyway if it is stopped. Sending a SIGCONT signal to a process causes any pending stop signals for that process to be discarded. Likewise, any pending SIGCONT signals for a process are discarded when it receives a stop signal.

When a process in an orphaned process group (the section called “Orphaned Process Groups”) receives a SIGTSTP, SIGTTIN, or SIGTTOU signal and does not handle it, the process does not stop. Stopping the process would probably not be very useful, since there is no shell program that will notice it stop and allow the user to continue it. What happens instead depends on the operating system you are using. Some systems may do nothing; others may deliver another signal instead, such as SIGKILL or SIGHUP. In the GNU system, the process dies with SIGKILL; this avoids the problem of many stopped, orphaned processes lying around the system.

Operation Error Signals

These signals are used to report various errors generated by an operation done by the program. They do not necessarily indicate a programming error in the program, but an error that prevents an operating system call from completing. The default action for all of them is to cause the process to terminate.

int function>SIGPIPE/function> Broken pipe. If you use pipes or FIFOs, you have to design your application so that one process opens the pipe for reading before another starts writing. If the reading process never starts, or terminates unexpectedly, writing to the pipe or FIFO raises a SIGPIPE signal. If SIGPIPE is blocked, handled or ignored, the offending call fails with EPIPE instead.

Pipes and FIFO special files are discussed in more detail in Chapter 16.

Another cause of SIGPIPE is when you try to output to a socket that isn't connected. the section called “Sending Data”.

int function>SIGLOST/function> Resource lost. This signal is generated when you have an advisory lock on an NFS file, and the NFS server reboots and forgets about your lock.

In the GNU system, SIGLOST is generated when any server program dies unexpectedly. It is usually fine to ignore the signal; whatever call was made to the server that died just returns an error.

int function>SIGXCPU/function> CPU time limit exceeded. This signal is generated when the process exceeds its soft resource limit on CPU time. the section called “Limiting Resource Usage”.

int function>SIGXFSZ/function> File size limit exceeded. This signal is generated when the process attempts to extend a file so it exceeds the process's soft resource limit on file size. the section called “Limiting Resource Usage”.

Miscellaneous Signals

These signals are used for various other purposes. In general, they will not affect your program unless it explicitly uses them for something.

int function>SIGUSR1/function> int function>SIGUSR2/function> The SIGUSR1 and SIGUSR2 signals are set aside for you to use any way you want. They're useful for simple interprocess communication, if you write a signal handler for them in the program that receives the signal.

There is an example showing the use of SIGUSR1 and SIGUSR2 in the section called “Signaling Another Process”.

The default action is to terminate the process.

int function>SIGWINCH/function> Window size change. This is generated on some systems (including GNU) when the terminal driver's record of the number of rows and columns on the screen is changed. The default action is to ignore it.

If a program does full-screen display, it should handle SIGWINCH. When the signal arrives, it should fetch the new screen size and reformat its display accordingly.

int function>SIGINFO/function> Information request. In 4.4 BSD and the GNU system, this signal is sent to all the processes in the foreground process group of the controlling terminal when the user types the STATUS character in canonical mode; the section called “Characters that Cause Signals”.

If the process is the leader of the process group, the default action is to print some status information about the system and what the process is doing. Otherwise the default is to do nothing.

Signal Messages

We mentioned above that the shell prints a message describing the signal that terminated a child process. The clean way to print a message describing a signal is to use the functions strsignal and psignal. These functions use a signal number to specify which kind of signal to describe. The signal number may come from the termination status of a child process (the section called “Process Completion”) or it may come from a signal handler in the same process.

char * function>strsignal/function> (int signum) This function returns a pointer to a statically-allocated string containing a message describing the signal signum. You should not modify the contents of this string; and, since it can be rewritten on subsequent calls, you should save a copy of it if you need to reference it later.

This function is a GNU extension, declared in the header file string.h.

void function>psignal/function> (int signum, const char *message) This function prints a message describing the signal signum to the standard error output stream stderr; see the section called “Standard Streams”.

If you call psignal with a message that is either a null pointer or an empty string, psignal just prints the message corresponding to signum, adding a trailing newline.

If you supply a non-null message argument, then psignal prefixes its output with this string. It adds a colon and a space character to separate the message from the string corresponding to signum.

This function is a BSD feature, declared in the header file signal.h.

There is also an array sys_siglist which contains the messages for the various signal codes. This array exists on BSD systems, unlike strsignal.