signal(3)						     Library Functions Manual							 signal(3)

Name
       signal - simplified software signal facilities

Syntax
       #include <signal.h>

       (*signal(sig, func))()
       void (*func)();

Description
       The subroutine is a simplified interface to the more general sigvec(2) facility.

       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.   For  further information, see Signals are optionally generated when a process resumes after being stopped, when the status of
       child process 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, the call allows signals either to be ignored or to cause an interrupt	to
       a specified location.  The following is a list of all signals with names as in the include file
       < signal.h >:

       SIGHUP	 1    Hangup
       SIGINT	 2    Interrupt
       SIGQUIT	 3*   Quit
       SIGILL	 4*   Illegal instruction
       SIGTRAP	 5*   Trace trap
       SIGIOT	 6*   IOT instruction
       SIGEMT	 7*   EMT instruction
       SIGFPE	 8*   Floating point exception
       SIGKILL	 9    Kill (cannot be caught 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
       SIGURG	 16o  Urgent condition present on socket
       SIGSTOP	 17+  Stop (cannot be caught or ignored)
       SIGTSTP	 18+  Stop signal generated from keyboard
       SIGCONT	 19o  Continue after stop
       SIGCHLD	 20o  Child status has changed
       SIGTTIN	 21+  Background read attempted from control terminal
       SIGTTOU	 22+  Background write attempted to control terminal
       SIGIO	 23o  I/O is possible on a descriptor (see fcntl(2))
       SIGXCPU	 24   Cpu time limit exceeded (see setrlimit(2))
       SIGXFSZ	 25   File size limit exceeded (see setrlimit(2))
       SIGVTALRM 26   Virtual time alarm (see setitimer(2))
       SIGPROF	 27   Profiling timer alarm (see setitimer(2))
       SIGWINCH  28o  Window size change
       SIGLOST	 29   lock not reclaimed after server recovery
       SIGUSR1	 30   User defined signal
       SIGUSR2	 31   User defined signal
       SIGCLD	      System V name for SIGCHLD
       SIGABRT	      X/OPEN name for SIGIOT

       The starred signals in the list above cause a core image if not caught or ignored.

       If  func  is  SIG_DFL, the default action for signal sig is reinstated; this default is termination (with a core image for starred signals)
       except for signals marked with o or +.  Signals marked with o are discarded if the action is SIG_DFL;  signals  marked  with  +	cause  the
       process to stop.  If func is SIG_IGN the signal is subsequently ignored and pending instances of the signal are discarded.  Otherwise, when
       the signal occurs further occurrences of the signal are automatically blocked and func is called.

       A return from the function unblocks the handled signal and continues the process at the point it was interrupted.  Unlike  previous  signal
       facilities, the handler func remains installed after a signal has been delivered.

       If  a caught signal occurs during certain system calls, causing the call to terminate prematurely, the call is automatically restarted.	In
       particular this can occur during a read or on a slow device (such as a terminal; but not a file) and during a

       The value of is the previous (or initial) value of func for the particular signal.

       After a or the child inherits all signals.  The system call resets all caught  signals  to  the	default  action;  ignored  signals  remain
       ignored.

Environment
       When  your  program  is	compiled  using  the System V environment the handler function does NOT remain installed after the signal has been
       delivered.

       Also, when a signal which is to be caught occurs during a read,	write, or ioctl to a slow device (like a terminal, but	not  a	file);	or
       during  a   pause;  or wait that does not return immediately,  the  signal  handler  function is executed, and then the interrupted  system
       call  may return  a -1 to the calling process with errno set to EINTR.

Notes
       The handler routine can be declared as follows:

	   handler(sig, code, scp)
	   int sig, code;
	   struct sigcontext *scp;

       Here sig is the signal number.  The MIPS hardware exceptions are mapped to specific signals as defined by the table below.   The  parameter
       code is either a constant as given below or zero.  The parameter scp is a pointer to the sigcontext structure (defined in <signal.h>), that
       is the context at the time of the signal and is used to restore the context if the signal handler returns.

       The following defines the mapping of MIPS hardware exceptions to signals and codes.  All of these symbols are defined in either	<signal.h>
       or <mips/cpu.h>:

       Hardware exception			   Signal	Code
       Integer overflow 			   SIGFPE	EXC_OV
       Segmentation violation			   SIGSEGV	SEXC_SEGV
       Illegal Instruction			   SIGILL	EXC_II
       Coprocessor Unusable			   SIGILL	SEXC_CPU
       Data Bus Error				   SIGBUS	EXC_DBE
       Instruction Bus Error			   SIGBUS	EXC_IBE
       Read Address Error			   SIGBUS	EXC_RADE
       Write Address Error			   SIGBUS	EXC_WADE
       User Breakpoint (used by debuggers)	   SIGTRAP	BRK_USERBP
       Kernel Breakpoint (used by prom) 	   SIGTRAP	BRK_KERNELBP
       Taken Branch Delay Emulation		   SIGTRAP	BRK_BD_TAKEN
       Not Taken Branch Delay Emulation 	   SIGTRAP	BRK_BD_NOTTAKEN
       User Single Step (used by debuggers)	   SIGTRAP	BRK_SSTEPBP
       Overflow Check				   SIGTRAP	BRK_OVERFLOW
       Divide by Zero Check			   SIGTRAP	BRK_DIVZERO
       Range Error Check			   SIGTRAP	BRK_RANGE

       When  a	signal	handler  is reached, the program counter in the signal context structure (sc_pc) points at the instruction that caused the
       exception as modified by the branch delay bit in the cause register.  The cause register at the time of the exception is also saved in  the
       sigcontext structure (sc_cause).  If the instruction that caused the exception is at a valid user address it can be retrieved with the fol-
       lowing code sequence:

	   if(scp->sc_cause & CAUSE_BD){
	       branch_instruction = *(unsigned long *)(scp->sc_pc);
	       exception_instruction = *(unsigned long *)(scp->sc_pc + 4);
	   }
	   else
	       exception_instruction = *(unsigned long *)(scp->sc_pc);

       Where CAUSE_BD is defined in <mips/cpu.h>.

       The signal handler may fix the cause of the exception and re-execute the instruction, emulate the instruction and then step over it or per-
       form some non-local goto such as a longjump() or an exit().

       If  corrective action is performed in the signal handler and the instruction that caused the exception would then execute without a further
       exception, the signal handler simply returns and re-executes the instruction (even when the branch delay bit is set).

       If execution is to continue after stepping over the instruction that caused the exception the program counter must  be  advanced.   If  the
       branch delay bit is set the program counter is set to the target of the branch else it is incremented by 4.

       This can be done with the following code sequence:

	   if(scp->sc_cause & CAUSE_BD)
	       emulate_branch(scp, branch_instruction);
	   else
	       scp->sc_pc += 4;

       Emulate_branch()  modifies  the	program  counter  value  in  the  sigcontext  structure to the target of the branch instruction.  See emu-
       late_branch(3) for more details.

       For SIGFPE's generated by floating-point instructions (code == 0) the floating-point control and status register at the time of the  excep-
       tion  is also saved in the sigcontext structure (sc_fpc_csr).  This register has the information on which exceptions have occurred.  When a
       signal handler is entered the register contains the value at the time of the exception but with the exceptions bits cleared.  On  a  return
       from  the  signal handler the exception bits in the floating-point control and status register are also cleared so that another SIGFPE does
       not occur (all other bits are restored from sc_fpc_csr).

       For SIGSEGV and SIGBUS errors the faulting virtual address is saved in sc_badvaddr in the signal context structure.

       The SIGTRAP's caused by break instructions noted in the above table and all other yet to be defined break instructions fill the code param-
       eter with the first argument to the break instruction (bits 25-16 of the instruction).

Return Values
       The previous action is returned on a successful call.  Otherwise, -1 is returned and errno is set to indicate the error.

Diagnostics
       The subroutine fails and action is not taken if one of the following occurs:

       [EINVAL]       The sig is not a valid signal number.

       [EINVAL]       An attempt is made to ignore or supply a handler for SIGKILL or SIGSTOP.

See Also
       kill(1), kill(2), ptrace(2), sigblock(2), sigpause(2), sigsetmask(2), sigstack(2), sigvec(2), setjmp(3), tty(4)

								       RISC								 signal(3)