SIGNAL(3)                        System Calls                        SIGNAL(3)




NAME

       signal - simplified software signal facilities


SYNOPSIS

       #include <signal.h>

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

       or in GNO's equivalent but easier to read typedef'd version:

       typedef void (*sig_t) (int, int)

       sig_t signal(int sig, sig_t func);


DESCRIPTION

       Signals  allow the manipulation of a process from outside its domain as
       well as allowing the process to manipulate itself or copies  of  itself
       (children).  There  are  two general types of signals: those that cause
       termination of a process and those that do not.   Signals  which  cause
       termination  of  a  program might result from an irrecoverable error or
       might be the result of a user at  a  terminal  typing  the  'interrupt'
       character.   Signals  are  used  when  a  process is stopped because it
       wishes to access its control terminal  while  in  the  background  (see
       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 result in the termination of the process receiving them 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.  The signal function allows for  a  signal  to  be
       caught,  to be ignored, or to generate an interrupt, except for SIGCONT
       (which cannot be blocked), and SIGKILL and  SIGSTOP  (which  cannot  be
       caught, blocked, or ignored).

       These signals are defined in the file <signal.h>:

              Name      Default Action Description

              SIGHUP    termination    terminal line hangup
              SIGINT    termination    interrupt program
              SIGQUIT   termination    quit program
              SIGILL    termination    illegal instruction
              SIGTRAP   termination    trace trap
              SIGABRT   termination    abort (generated by abort(3))
              SIGEMT    termination    emulator trap
              SIGFPE    termination    arithmetic exception
              SIGKILL   termination    kill program
              SIGBUS    termination    bus error
              SIGSEGV   termination    segmentation fault
              SIGSYS    termination    bad argument to system call
              SIGPIPE   termination    write on a socket with no readers
              SIGALRM   termination    real-time timer expired
              SIGTERM   termination    software termination
              SIGURG    discarded      urgent condition present on socket
              SIGSTOP   stop           stop
              SIGTSTP   stop           stop signal from keyboard
              SIGCONT   discarded      continue after stop
              SIGCHLD   discarded      child status has changed
              SIGCLD    discarded      SYSV name for SIGCHLD
              SIGTTIN   stop           background read attempted
              SIGTTOU   stop           background write attempted
              SIGIO     discarded      input/output possible on a file descriptor
              SIGPOLL   discarded      SYSV name for SIGIO
              SIGXCPU   termination    exceeded CPU time limit
              SIGUSR1   termination    user defined signal 1
              SIGUSR2   termination    user defined signal 2

       The func procedure allows a user to choose the action upon receipt of a
       signal.  To set the default action of the signal  to  occur  as  listed
       above,  func  should  be SIG_DFL.  A SIG_DFL resets the default action.
       To ignore the signal func should be SIG_IGN.  This  will  cause  subse-
       quent instances of the signal to be ignored and pending instances to be
       discarded. If SIG_IGN is not used, further occurrences  of  the  signal
       are automatically blocked and func is called.

       The  handled signal is unblocked with the function returns and the pro-
       cess continues from where it left off when the signal occurred.  Unlike
       previous  Unix  signal facilities, the handler func() remains installed
       after a signal has been delivered.   This  behavior  remains  unchanged
       from GNO v2.0.4.

       For  some system calls, if a signal is caught while the call is execut-
       ing and the call is prematurely terminated, the call  is  automatically
       restarted.   The  affected  system  calls  include  read(2),  write(2),
       sendto(2), recvfrom(2), sendmsg(2) and recvmsg(2) on  a  communications
       channel  or  a low speed device and during a ioctl(2) or wait(2).  How-
       ever, calls that have already committed are not restarted, but  instead
       return a partial success (for example, a short read count).

       When  a  process  which  has installed signal handlers forks, the child
       process inherits the signals.  All caught  signals  will  be  reset  to
       their  default action by a call to one of the execve(2) family of func-
       tions; ignored signals remain ignored.


NOTES

       As can be surmised from the prototype above, func should be defined  as
       follows:

              void func(int sig, int code)

       sig  is the signal that will invoke the handler, and code is additional
       information about the interrupt condition.  Currently, code  is  always
       zero.   The  handler should probably also be compiled using the #pragma
       databank 1 directive, in the event func is not in the same bank as  the
       C  global  data segment (func is called with the data bank equal to the
       program bank).

       ORCA/C already provides a signal function, but it doesn't do very much.
       GNO's <signal.h> file replaces the one that comes with ORCA/C.


RETURN VALUES

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


ERRORS

       Signal will fail and no action will take place if one of the  following
       occur:

              EINVAL Sig is not a valid signal number.

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

              EINVAL An attempt is made to ignore SIGCONT (by default  SIGCONT
                     is ignored).


SEE ALSO

       kill(1),   execve(2),  fork(2),  kill(2),  sigblock(2),  sigsetmask(2),
       wait(2), tty(4)


HISTORY

       A signal facility appeared in 4.0BSD.



GNO                             19 January 1997                      SIGNAL(3)

Man(1) output converted with man2html