PC Extra Super CD 1998 January/PCPLUS131.iso/DJGPP/V2/DJLSR201.ZIP/src/libc/go32/dpmiexcp.txh

Text File | 1996-09-11 | 10.1 KB | 296 lines

@c ----------------------------------------------------------------------
@node raise, signal
@subheading Syntax

@example
#include <signal.h>

int    raise(int sig);
@end example

@subheading Description

This function raises the given signal @var{sig}.
@xref{signal, the list of possible signals}.

@subheading Return Value

0 on success, -1 for illegal value of @var{sig}.

@c ----------------------------------------------------------------------

@node signal, signal
@subheading Syntax

@example
#include <signal.h>

void    (*signal(int sig, void (*func)(int)))(int);
@end example

@subheading 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 @code{<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 @var{func} as a signal handler for signal number
@var{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 @code{longjmp} (@pxref{longjmp}).

You may pass SIG_DFL as the value of @var{func} to reset the signal
handling for the signal @var{sig} to default (also
@xref{__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 @code{signal}, assign values to data objects
of type @code{volatile sig_atomic_t} (defined as @code{int} on
@code{<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), @xref{__dpmi_lock_linear_region,
locking memory regions}.  Handlers for software interrupts can also
terminate by calling @code{abort}, @code{exit} or @code{longjmp}.

The following signals are defined on @code{<signal.h>}:

@table @code

@item SIGABRT

The Abort signal.  Currently only used by the @code{assert} macro to
terminate the program when an assertion fails (@pxref{assert}).

@item 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).

@item SIGILL

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

@item SIGINT

The Interrupt signal.  Generated when a @kbd{Ctrl-C} or @kbd{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 @code{setmode}
(@pxref{setmode}), generation of @code{SIGINT} as result of @kbd{Ctrl-C}
key is disabled.  This is so for programs (such as Emacs) which want to
be able to read the @samp{^C} character as any other character.  Use the
library function @code{__djgpp_set_ctrl_c} to restore @code{SIGINT}
generation when @kbd{Ctrl-C} is hit, if you need this.
@xref{__djgpp_set_ctrl_c}, for details on how this should be done.
@kbd{Ctrl-Break} always generates @code{SIGINT}.

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

@item 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.

@item SIGTERM

The Termination Request signal.  Currently unused.


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


@item SIGALRM

The Alarm signal.  Generated after certain time period has passed after
a call to @code{alarm} library function (@pxref{alarm}).

@item SIGHUP

The Hang-up signal.  Currently unused.

@item SIGKILL

The Kill signal.  Currently unused.

@item SIGPIPE

The Broken Pipe signal.  Currently unused.

@item SIGQUIT

The Quit signal.  Currently unused.

@item SIGUSR1

User-defined signal no. 1.

@item 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 @samp{-ansi} or @samp{-posix} options
to @samp{gcc}.


@item SIGTRAP

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

@item SIGNOFP

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

@item SIGTIMR

The Timer signal.  Used by the @code{setitimer} and @code{alarm} functions
(@xref{setitimer}, @xref{alarm}).

@item SIGPROF

The Profiler signal.  Used by the execution profile gathering code in a
program compiled with @samp{-pg} option to @samp{gcc}.

@end table


@subheading Return Value

The previous handler for signal @var{sig}, or @code{SIG_ERR} if the
value of @var{sig} is outside legal limits.

@subheading 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 @code{read} (or
@code{scanf}, or @code{gets}) to read text from the console and press
@kbd{Ctrl-C}, you will have to press @kbd{Enter} to terminate the
@code{read} call to cause the signal handler for @code{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.

@c -------------------------------------------------------------------------

@node __djgpp_set_ctrl_c, signal
@subheading Syntax

@example
#include <sys/exceptn.h>

int __djgpp_set_ctrl_c(int enable);
@end example

@subheading Description

This function sets and resets the bit which controls whether
@code{SIGINT} (@pxref{signal, SIGINT}) will be raised when you press
@kbd{Ctrl-C}.  By default @kbd{Ctrl-C} generates an interrupt signal
which, if uncaught by a signal handler, will abort your program.
However, when you call the @code{setmode} library function to switch the
console reads to binary mode, or open the console in binary mode for
reading, this generation of interrupt signal is turned off, because some
programs want to get the @samp{^C} characters as any other character and
handle them by themselves.

@code{__djgpp_set_ctrl_c} lets you explicitly determine the effect of
@kbd{Ctrl-C}.  When called with non-zero value of @var{enable}, it
arranges for @kbd{Ctrl-C} to generate an interrupt; if you call it with
a zero in @var{enable}, @kbd{Ctrl-C} are treated as normal characters.

Note that the effect of @kbd{Ctrl-Break} key is unaffected by this
function; use the @code{_go32_want_ctrl_break} library function to
control it.

Also note that in DJGPP, the effect of the interrupt signal will only be
seen when the program is in protected mode (@xref{signal, Signal Mechanism},
for more details).  Thus, if you press @kbd{Ctrl-C} while your
program calls DOS (e.g., when reading from the console), the
@code{SIGINT} signal handler will only be called after that call
returns.

@subheading Return Value

The previous state of the @kbd{Ctrl-C} effect: 0 if the generation of
@code{SIGINT} by @kbd{Ctrl-C} was disabled, 1 if it was enabled.

@subheading Example

@example

  setmode(fileno(stdin), O_BINARY);
  if (isatty(fileno(stdin)));
    __djgpp_set_ctrl_c(1);

@end example

@c -------------------------------------------------------------------------

@node __djgpp_exception_toggle, signal
@subheading Syntax

@example

#include <sys/exceptn.h>

void __djgpp_exception_toggle(void);

@end example


@subheading Description

This function is automatically called when the program exits, to restore
handling of all the exceptions to their normal state.  You may also call
it from your program, around the code fragments where you need to
temporarily restore @strong{all} the exceptions to their default
handling.  One example of such case might be a call to a library
functions that spawn child programs, when you don't want to handle
signals generated while the child runs (by default, those signals are
also passed to the parent).

@subheading Example

@example

  __djgpp_exception_toggle();
  system("myprog");
  __djgpp_exception_toggle();

@end example