.TH SIGSYS 2J .UC .ie t .ds d \(dg .el .ds d \z'|+' .ie t .ds b \(bu .el .ds b @ .SH NAME sigsys \- catch or ignore signals .SH SYNOPSIS .nf .B #include .PP .B (*sigsys(sig, func))() .B void (*func)(); .BI "int (*func)();" " (if void is not supported)" .PP .B cc ... \-ljobs .fi .SH DESCRIPTION .IR N.B. : The system currently supports two signal implementations. The one described in .IR signal (2) is standard in version 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 .IR sigset (3J)) provides for the needs of the job control mechanisms (see .IR intro (3J)) used by .IR csh (1), and corrects the bugs in the standard implementation of signals, allowing programs which process interrupts to be written reliably. .PP The routine .I sigsys is not normally called directly; rather the routines of .IR sigset (3J) should be used. These routines are kept in the ``jobs'' library, accessible by giving the loader option .B \-ljobs. The features described here are less portable then those of .IR signal (2) and should not be used in programs which are to be moved to other versions of UNIX. .PP 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 .IR tty (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 discarded if the process has not requested otherwise. Except for the SIGKILL and SIGSTOP signals which cannot be blocked, the .I sigsys call allows signals either to be ignored, held until a later time (protecting critical sections in the process), or to cause an interrupt to a specified location. Here is the list of all signals with names as in the include file. .LP .nf .ta \w'SIGMMMM 'u +\w'15* 'u SIGHUP 1 hangup SIGINT 2 interrupt SIGQUIT 3* quit 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\*d stop (cannot be caught, held or ignored) SIGTSTP 18\*d stop signal generated from keyboard SIGCONT 19\*b continue after stop SIGCHLD 20\*b child status has changed SIGTTIN 21\*d background read attempted from control terminal SIGTTOU 22\*d background write attempted to control terminal SIGTINT 23\*b input record is available at control terminal SIGXCPU 24 cpu time limit exceeded (see \fIvlimit\fP\|(2)) (\fIVAX-11 only\fP) SIGXFSZ 25 file size limit exceeded (see \fIvlimit\fP\|(2)) (\fIVAX-11 only\fP) .fi .PP The starred signals in the list above cause a core image if not caught, held or ignored. .PP If .I func is SIG_DFL, the default action for signal .I sig is reinstated; this default is termination (with a core image for starred signals) except for signals marked with \*b or \*d. Signals marked with \*b are discarded if the action is SIG_DFL; signals marked with \*d cause the process to stop. If .I func 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 .I func 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 .I func will be called. .PP A return from the function will continue the process at the point it was interrupted. Except as indicated, a signal, set with .I sigsys, is reset to SIG_DFL after being caught. However by specifying DEFERSIG(func) as the last argument to .I sigsys, 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. .PP When a caught signal occurs during certain system calls, the call terminates prematurely. In particular this can occur during a .I read or .IR write (2) on a slow device (like a terminal; but not a file) and during a .I pause or .IR wait (2). When a signal occurs during one of these calls, the saved user status 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. .I Read and .I write calls which have done no I/O, .IR ioctl s blocked with SIGTTOU, and .I wait2 or .I wait3 calls are restarted. .PP The value of .I sigsys is the previous (or initial) value of .I func for the particular signal. .PP The system provides two other functions by oring bits into the signal number: SIGDOPAUSE causes the process to .I pause after changing the signal action. It can be used to atomically re-enable a held signal which was being processed and wait for another instance of the signal. SIGDORTI causes the system to simulate an .I rei 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 signal package such as .IR sigset (3J) to dismiss from interrupts cleanly removing the old state from the stack before another instance of the interrupt is presented. .PP After a .IR fork (2) or .IR vfork (2) the child inherits all signals. .IR Exec (2) resets all caught signals to default action; held signals remain held and ignored signals remain ignored. .SH RETURN VALUE The value BADSIG is returned if the given signal is out of range. .SH ERRORS .I Sigsys will fail if: .TP 20 [EINVAL] .I Sig is an illegal signal number, including SIGKILL and SIGSTOP. .SH "SEE ALSO" kill(1), kill(2), ptrace(2), intro(3J), sigset(3J), setjmp(3), tty(4) .SH BUGS The job control facilities are not available in standard version 7 UNIX. These facilities are still under development 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 supporting it are thus subject to change. .PP Since only one signal action can be changed at a time, it is not possible to get the effect of SIGDOPAUSE for more than one signal at a time. .PP 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. .SH "ASSEMBLER (PDP-11)" (signal = 48.) .br .B sys signal; sig; label .br (old label in r0) .PP If .I label is 0, default action is reinstated. If .I label is 1, the signal is ignored. If .I label is 3, the signal is held. Any other even .I label 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.) .SH "NOTES (VAX-11)" The handler routine can be declared: .PP handler(signo, param, xx, pc, psl) .PP Here .I signo 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. .PP The routine is actually called with only 3 parameters specified in the \fIcalls\fP or \fIcallg\fP instruction. After return from the signal handler the \fIpc\fP and \fIpsl\fP are popped off of the stack with an \fIrei\fP, so they act as ``value-result'' parameters unlike normal C value parameters. .PP The following defines the mapping of hardware traps to signals and codes. All of these symbols are defined in : .LP .ta \w' Floating/decimal divide by zero 'u +\w'15* 'u +8n .nf 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 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 .fi