Click above to get retro games delivered to your door ever month!

signal
======

Syntax
------

     #include <signal.h>
     
     void       (*signal(int sig, void (*func)(int)))(int);

Description
-----------

Signals are generated in response to some exceptional behavior of the
program, such as division by 0.  A signal can also report some
asynchronous event outside the program, such as someone pressing a
Ctrl-Break key combination.

Signals are numbered 0..255 for software interrupts and 256..287 for
exceptions (exception number plus 256); other implementation-specific
codes are specified in `<signal.h>' (see below).  Every signal is given
a mnemonic which you should use for portable programs.

The default handling for all the signals is to print a traceback (a
stack dump which describes the sequence of function calls leading to the
generation of the signal) and abort the program.

This function allows you to change the default behavior for a specific
signal.  It registers FUNC as a signal handler for signal number SIG.
After you register your function as the handler for a particular
signal, it will be called when that signal occurs.  The execution of
the program will be suspended until the handler returns or calls
`longjmp' (longjmp:.).   

You may pass SIG_DFL as the value of FUNC to reset the signal handling
for the signal SIG to default (also __djgpp_exception_toggle:,   
for a quick way to restore all the signals' handling to default),
SIG_ERR to force an error when that signal happens, or SIG_IGN to
ignore that signal.  Signal handlers that you write are regular C
functions, and may call any function that the ANSI/POSIX specs say are
valid for signal handlers.  For maximum portability, a handler for
hardware interrupts and processor exceptions should only make calls to
`signal', assign values to data objects of type `volatile sig_atomic_t'
(defined as `int' on `<signal.h>') and return.  Handlers for hardware
interrupts need also be locked in memory (so that the operation of
virtual memory mechanism won't swap them out), locking memory
regions: __dpmi_lock_linear_region Handlers for software interrupts
can also terminate by calling `abort', `exit' or `longjmp'.

The following signals are defined on `<signal.h>':

`SIGABRT'
     The Abort signal.  Currently only used by the `assert' macro to
     terminate the program when an assertion fails (assert:.).   

`SIGFPE'
     The Floating Point Error signal.  Generated in case of divide by
     zero exception (Int 00h), overflow exception (Int 04h), and any x87
     co-processor exception, either generated by the CPU (Int 10h), or
     by the co-processor itself (Int 75h).

`SIGILL'
     The Invalid Execution signal.  Currently only generated for
     unknown/invalid exceptions.

`SIGINT'
     The Interrupt signal.  Generated when a `Ctrl-C' or `Ctrl-Break'
     (Int 1Bh) key is hit.  Note that when you open the console in
     binary mode, or switch it to binary mode by a call to `setmode'
     (setmode:.), generation of `SIGINT' as result of `Ctrl-C'   
     key is disabled.  This is so for programs (such as Emacs) which
     want to be able to read the `.character as any other character.
     Use the library function `__djgpp_set_ctrl_c' to restore `SIGINT'
     generation when `Ctrl-C' is hit, if you need this.  *Note
     __djgpp_set_ctrl_c::, for details on how this should be done.
     `Ctrl-Break' always generates `SIGINT'.

     DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to
     generate `SIGINT' in response to `Ctrl-C' key; you should be aware
     of this when you install a handler for the keyboard interrupt.

`SIGSEGV'
     The invalid storage access (Segmentation Violation) signal.
     Generated in response to any of the following exceptions: Bound
     range exceeded in BOUND instruction (Int 05h), Double Exception or
     an exception in the exception handler (Int 08h), Segment Boundary
     violation by co-processor (Int 09h), Segment Not Present (Int
     0Bh), Stack Fault (Int 0Ch), General Protection Violation (Int
     0Dh), or Page Fault (Int 0Eh).  Note that Int 09h is only
     generated on 80386 processor; i486 and later CPUs cause Int 0Dh
     when the co-processor accesses memory out of bounds.

`SIGTERM'
     The Termination Request signal.  Currently unused.

     The signals below this are not defined by ANSI C, and cannot be
     used when compiling under `-ansi' option to `gcc'.

`SIGALRM'
     The Alarm signal.  Generated after certain time period has passed
     after a call to `alarm' library function (alarm:.).   

`SIGHUP'
     The Hang-up signal.  Currently unused.

`SIGKILL'
     The Kill signal.  Currently unused.

`SIGPIPE'
     The Broken Pipe signal.  Currently unused.

`SIGQUIT'
     The Quit signal.  Currently unused.

`SIGUSR1'
     User-defined signal no. 1.

`SIGUSR2'
     User-defined signal no. 2.

     The signals below are not defined by ANSI C and POSIX, and cannot
     be used when compiling under either `-ansi' or `-posix' options to
     `gcc'.

`SIGTRAP'
     The Trap Instruction signal.  Generated in response to the Debugger
     Exception (Int 01h) or Breakpoint Exception (Int 03h).

`SIGNOFP'
     The No Co-processor signal.  Generated if a co-processor
     (floating-point) instruction is encountered when no co-processor
     is installed (Int 07h).

`SIGTIMR'
     The Timer signal.  Used by the `setitimer' and `alarm' functions
     (setitimer:, alarm:).      

`SIGPROF'
     The Profiler signal.  Used by the execution profile gathering code
     in a program compiled with `-pg' option to `gcc'.

Return Value
------------

The previous handler for signal SIG, or `SIG_ERR' if the value of SIG
is outside legal limits.

Signal Mechanism Implementation Notes
-------------------------------------

Due to subtle aspects of protected-mode programs operation under MS-DOS,
signal handlers cannot be safely called from hardware interrupt
handlers.  Therefore, DJGPP exception-handling mechanism arranges for
the signal handler to be called on the first occasion that the program
is in protected mode and touches any of its data.  This means that if
the exception occurs while the processor is in real mode, like when your
program calls some DOS service, the signal handler won't be called until
that call returns.  For instance, if you call `read' (or `scanf', or
`gets') to read text from the console and press `Ctrl-C', you will have
to press `Enter' to terminate the `read' call to cause the signal
handler for `SIGINT' to be called.  Another significant implication of
this implementation is that when the program isn't touching any of its
data (like in very tight loops which only use values in the registers),
it cannot be interrupted.