Signals
=======

There are two varieties of signals available, named & anonymous.  A named signal is one for which there is provided a symbolic name, such as kill or pipe.  Anonymous signals are those that the operating system provided but for which POSIX does not define a symbolic name, only a number, and which may not have meaning on other operating systems.  Named signals preserve their meaning through heap image dumps; anonymous signals may not be dumped in heap images.  (If they are, a warning is signalled, and they are replaced with a special token that denotes a non-portable signal.)  Not all named signals are available from all operating systems, and there may be multiple names for a single operating system signal number.

 -- syntax: signal name returns signal
 -- procedure: name->signal symbol returns signal or #f
 -- procedure: integer->signal integer returns signal
 -- procedure: signal? object returns boolean
 -- procedure: signal-name signal returns symbol or #f
 -- procedure: signal-os-number signal returns integer
 -- procedure: signal=? signala signalb returns boolean
     Signal evaluates to the signal object with the known symbolic name NAME.  It is an error if NAME is not recognized as any signal's name.  Name->signal returns the signal corresponding with the given NAME or #f if no such signal is known. Integer->signal returns a signal, named or anonymous, with the given OS number.  Signal? is the disjoint type predicate for signal objects.  Signal-name returns the symbolic name of SIGNAL if it is a named signal or #f if it is an anonymous signal.  Signal-OS-number returns the operating system's integer value of SIGNAL.  Signal=? tests whether two signals are the same, ie whether their OS numbers are equal equal.

     These are all of the symbols that POSIX defines.

     abrt
          abnormal termination (as by abort(3))

     alrm
          timeout signal (as by alarm(2))

     fpe
          floating point exception

     hup
          hangup on controlling terminal or death of controlling process

     ill
          illegal instruction

     int
          interrupt --- interaction attention

     kill
          termination signal, cannot be caught or ignored

     pipe
          write was attempted on a pipe with no readers

     quit
          interaction termination

     segv
          segmentation violation --- invalid memory reference

     term
          termination signal

     usr1
     usr2
          for use by applications

     chld
          child process stopped or terminated

     cont
          continue if stopped

     stop
          stop immediately, cannot be caught or ignored

     tstp
          interactive stop

     ttin
          read from control terminal attempted by a background process

     ttou
          write to control terminal attempted by a background process

     bus
          bus error --- access to undefined portion of memory

     There are also several other signals whose names are allowed to be passed to signal that are not defined by POSIX, but that are recognized by many operating systems.

     trap
          trace or breakpoint trap

     iot
          synonym for abrt

     emt

     sys
          bad argument to routine (SVID)

     stkflt
          stack fault on coprocessor

     urg
          urgent condition on socket (4.2 BSD)

     io
          I/O now possible (4.2 BSD)

     poll
          synonym for io (System V)

     cld
          synonym for chld

     xcpu
          CPU time limit exceeded (4.2 BSD)

     xfsz
          file size limit exceeded (4.2 BSD)

     vtalrm
          virtual alarm clock (4.2 BSD)

     prof
          profile alarm clock

     pwr
          power failure (System V)

     info
          synonym for pwr

     lock
          file lock lost

     winch
          Window resize signal (4.3 BSD, Sun)

     unused

Sending & receiving signals
---------------------------

 -- procedure: signal-process pid signal returns unspecified
     Sends a signal represented by SIGNAL to the process identified by PID.

Signals received by the Scheme process can be obtained via one or more signal queues.  Each signal queue has a list of monitored signals and a queue of received signals that have yet to be consumed from the queue.  When the Scheme process receives a signal, that signal is added to the signal queues that are currently monitoring the signal received.

 -- procedure: make-signal-queue signal-list returns signal-queue
 -- procedure: signal-queue? object returns boolean
 -- procedure: signal-queue-monitored-signals signal-queue returns signal-list
 -- procedure: dequeue-signal! signal-queue returns signal (may block)
 -- procedure: maybe-dequeue-signal! signal-queue returns signal or #f
     Make-signal-queue returns a new signal queue that will monitor all of the signals in the given list.  Signal-queue? is the disjoint type predicate for signal queues. Signal-queue-monitored-signals returns a freshly-allocated list of the signals currently monitored by SIGNAL-QUEUE. Dequeue-signal! & maybe-dequeue-signal! both access the next signal ready to be read from SIGNAL-QUEUE.  If the signal queue is empty, dequeue-signal! will block until a signal is received, while maybe-dequeue-signal! will immediately return #f.

Note: There is a bug in the current system that causes an erroneous deadlock to occur if threads are blocked waiting for signals and no other threads are available to run.  A workaround is to create a thread that sleeps for a long time, which prevents any deadlock errors (including real ones):

     > ,open threads
     > (spawn (lambda ()
                ;; Sleep for a year.
                (sleep (* 1000 60 60 24 365)))) lisp

      -- procedure: add-signal-queue-signal! signal-queue signal returns unspecified
      -- procedure: remove-signal-queue-signal! signal-queue signal returns unspecified
          These add & remove signals from signal queues' list of signals to
          monitor.  Note that remove-signal-queue-signal! also removes any
          pending signals from the queue, so dequeue-signal! &
          maybe-dequeue-signal! will only ever return signals that are
          on the queue's list of monitored signals when they are called.