SIGSYS(2J) UNIX Programmer's Manual SIGSYS(2J) NAME sigsys - catch or ignore signals SYNOPSIS #include (*sigsys(sig, func))() void (*func)(); int (*func)(); (_i_f _v_o_i_d _i_s _n_o_t _s_u_p_p_o_r_t_e_d) cc ... -ljobs DESCRIPTION _N._B.: The system currently supports two signal implementa- tions. The one described in _s_i_g_n_a_l(2) is standard in ver- sion 7 UNIX systems, and retained for backward compatibility as it is different in a number of ways. The one described here (with the interface in _s_i_g_s_e_t(3J)) provides for the needs of the job control mechanisms (see _i_n_t_r_o(3J)) used by _c_s_h(1), and corrects the bugs in the standard implementation of signals, allowing programs which process interrupts to be written reliably. The routine _s_i_g_s_y_s is not normally called directly; rather the routines of _s_i_g_s_e_t(3J) should be used. These routines are kept in the ``jobs'' library, accessible by giving the loader option -ljobs. The features described here are less portable then those of _s_i_g_n_a_l(2) and should not be used in programs which are to be moved to other versions of UNIX. A signal is generated by some abnormal event, initiated by a user at a terminal (quit, interrupt, stop), by a program error (bus error, etc.), by request of another program (kill), or when a process is stopped because it wishes to access its control terminal while in the background (see _t_t_y(4)). Signals are optionally generated when a process resumes after being stopped, when the status of child processes changes, or when input is ready at the control terminal. Most signals cause termination of the receiving process if no action is taken; some signals instead cause the process receiving them to be stopped, or are simply dis- carded if the process has not requested otherwise. Except for the SIGKILL and SIGSTOP signals which cannot be blocked, the _s_i_g_s_y_s call allows signals either to be ignored, held until a later time (protecting critical sections in the pro- cess), or to cause an interrupt to a specified location. Here is the list of all signals with names as in the include file. SIGHUP 1 hangup SIGINT 2 interrupt SIGQUIT 3* quit Printed 5/27/83 1 SIGSYS(2J) UNIX Programmer's Manual SIGSYS(2J) SIGILL 4* illegal instruction (not reset when caught) SIGTRAP 5* trace trap (not reset when caught) SIGIOT 6* IOT instruction SIGEMT 7* EMT instruction SIGFPE 8* floating point exception SIGKILL 9 kill (cannot be caught, held or ignored) SIGBUS 10* bus error SIGSEGV 11* segmentation violation SIGSYS 12* bad argument to system call SIGPIPE 13 write on a pipe with no one to read it SIGALRM 14 alarm clock SIGTERM 15 software termination signal 16 unassigned SIGSTOP 17'|+'stop (cannot be caught, held or ignored) SIGTSTP 18'|+'stop signal generated from keyboard SIGCONT 19@ continue after stop SIGCHLD 20@ child status has changed SIGTTIN 21'|+'background read attempted from control terminal SIGTTOU 22'|+'background write attempted to control terminal SIGTINT 23@ input record is available at control terminal SIGXCPU 24 cpu time limit exceeded (see _v_l_i_m_i_t(2)) (_V_A_X-_1_1 _o_n_l_y) SIGXFSZ 25 file size limit exceeded (see _v_l_i_m_i_t(2)) (_V_A_X-_1_1 _o_n_l_y) The starred signals in the list above cause a core image if not caught, held or ignored. If _f_u_n_c is SIG_DFL, the default action for signal _s_i_g is reinstated; this default is termination (with a core image for starred signals) except for signals marked with @ or '|+'. Signals marked with @ are discarded if the action is SIG_DFL; signals marked with '|+' cause the process to stop. If _f_u_n_c is SIG_HOLD the signal is remembered if it occurs, but not presented to the process; it may be presented later if the process changes the action for the signal. If _f_u_n_c is SIG_IGN the signal is subsequently ignored, and pending instances of the signal are discarded (i.e. if the action was previously SIG_HOLD.) Otherwise when the signal occurs _f_u_n_c will be called. A return from the function will continue the process at the point it was interrupted. Except as indicated, a signal, set with _s_i_g_s_y_s, is reset to SIG_DFL after being caught. However by specifying DEFERSIG(func) as the last argument to _s_i_g_s_y_s, one causes the action to be set to SIG_HOLD before the interrupt is taken, so that recursive instances of the signal cannot occur during handling of the signal. When a caught signal occurs during certain system calls, the call terminates prematurely. In particular this can occur during a _r_e_a_d or _w_r_i_t_e(2) on a slow device (like a terminal; but not a file) and during a _p_a_u_s_e or _w_a_i_t(2). When a sig- nal occurs during one of these calls, the saved user status Printed 5/27/83 2 SIGSYS(2J) UNIX Programmer's Manual SIGSYS(2J) is arranged in such a way that, when return from the signal-catching takes place, it will appear that the system call returned an error status. The user's program may then, if it wishes, re-execute the call. _R_e_a_d and _w_r_i_t_e calls which have done no I/O, _i_o_c_t_ls blocked with SIGTTOU, and _w_a_i_t_2 or _w_a_i_t_3 calls are restarted. The value of _s_i_g_s_y_s is the previous (or initial) value of _f_u_n_c for the particular signal. The system provides two other functions by oring bits into the signal number: SIGDOPAUSE causes the process to _p_a_u_s_e after changing the signal action. It can be used to atomi- cally re-enable a held signal which was being processed and wait for another instance of the signal. SIGDORTI causes the system to simulate an _r_e_i instruction clearing the mark the system placed on the stack at the point of interrupt before checking for further signals to be presented due to the specified change in signal actions. This allows a sig- nal package such as _s_i_g_s_e_t(3J) to dismiss from interrupts cleanly removing the old state from the stack before another instance of the interrupt is presented. After a _f_o_r_k(2) or _v_f_o_r_k(2) the child inherits all signals. _E_x_e_c(2) resets all caught signals to default action; held signals remain held and ignored signals remain ignored. RETURN VALUE The value BADSIG is returned if the given signal is out of range. ERRORS _S_i_g_s_y_s will fail if: [EINVAL] _S_i_g is an illegal signal number, includ- ing SIGKILL and SIGSTOP. SEE ALSO kill(1), kill(2), ptrace(2), intro(3J), sigset(3J), setjmp(3), tty(4) BUGS The job control facilities are not available in standard version 7 UNIX. These facilities are still under develop- ment and may change in future releases of the system as better inter-process communication facilities and support for virtual terminals become available. The options and specifications of this facility and the system calls sup- porting it are thus subject to change. Since only one signal action can be changed at a time, it is not possible to get the effect of SIGDOPAUSE for more than Printed 5/27/83 3 SIGSYS(2J) UNIX Programmer's Manual SIGSYS(2J) one signal at a time. The traps (listed below) should be distinguishable by extra arguments to the signal handler, and all hardware supplied parameters should be made available to the signal routine. ASSEMBLER (PDP-11) (signal = 48.) sys signal; sig; label (old label in r0) If _l_a_b_e_l is 0, default action is reinstated. If _l_a_b_e_l is 1, the signal is ignored. If _l_a_b_e_l is 3, the signal is held. Any other even _l_a_b_e_l specifies an address in the process where an interrupt is simulated. If label is otherwise odd, the signal is sent to the function whose address is the label with the low bit cleared with the action set to SIG_HOLD. (Thus DEFERSIG is indicated by the low bit of a signal catch address. An RTI or RTT instruction will return from the interrupt.) NOTES (VAX-11) The handler routine can be declared: handler(signo, param, xx, pc, psl) Here _s_i_g_n_o is the signal name, into which the hardware faults and traps are mapped as defined below. Param is the parameter which is either a constant as given below or, for compatibility mode faults, the code provided by the hardware. Compatibility mode faults are distinguished from the other SIGILL traps by having PSL_CM set in the psl. The routine is actually called with only 3 parameters speci- fied in the _c_a_l_l_s or _c_a_l_l_g instruction. After return from the signal handler the _p_c and _p_s_l are popped off of the stack with an _r_e_i, so they act as ``value-result'' parame- ters unlike normal C value parameters. The following defines the mapping of hardware traps to sig- nals and codes. All of these symbols are defined in : Hardware condition Signal Code Arithmetic traps: Integer overflow SIGFPE FPE_INTOVF_TRAP Integer division by zero SIGFPE FPE_INTDIV_TRAP Floating overflow trap SIGFPE FPE_FLTOVF_TRAP Floating/decimal division by zero SIGFPE FPE_FLTDIV_TRAP Floating underflow trap SIGFPE FPE_FLTUND_TRAP Decimal overflow trap SIGFPE FPE_DECOVF_TRAP Printed 5/27/83 4 SIGSYS(2J) UNIX Programmer's Manual SIGSYS(2J) Subscript-range SIGFPE FPE_SUBRNG_TRAP Floating overflow fault SIGFPE FPE_FLTOVF_FAULT Floating divide by zero fault SIGFPE FPE_FLTDIV_FAULT Floating underflow fault SIGFPE FPE_FLTUND_FAULT Length access control SIGSEGV Protection violation SIGBUS Reserved instruction SIGILL ILL_RESAD_FAULT Customer-reserved instr. SIGEMT Reserved operand SIGILL ILL_PRIVIN_FAULT Reserved addressing SIGILL ILL_RESOP_FAULT Trace pending SIGTRAP Bpt instruction SIGTRAP Compatibility-mode SIGILL hardware supplied code Chme SIGSEGV Chms SIGSEGV Chmu SIGSEGV Printed 5/27/83 5