@c ---------------------------------------------------------------------- @node raise, signal @findex raise @subheading Syntax @example #include 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}. @subheading Portability @portability ansi, posix @c ---------------------------------------------------------------------- @node signal, signal @findex signal @subheading Syntax @example #include 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 @kbd{Ctrl-@key{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{} (see below). Every signal is given a mnemonic which you should use for portable programs. By default, signal @code{SIGQUIT} is discarded. This is so programs ported from other DOS environments, where @code{SIGQUIT} is generally not supported, continue to work as they originally did. If you want @code{SIGQUIT} to abort with a traceback, install @code{__djgpp_traceback_exit} as its handler (@pxref{__djgpp_traceback_exit}). The default handling for the rest of 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 by calling @code{_exit} (@pxref{_exit}). As an exception, the default handler for the signal @code{SIGINT} doesn't print the traceback, and calls @code{exit} instead of @code{_exit}, when the INTR key (@kbd{Ctrl-C} by default) is pressed, so that programs could be shut down safely in this manner. @code{SIGINT} raised by @kbd{Ctrl-@key{BREAK}} does generate the traceback. The function @code{signal} 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}). The state of the floating-point unit (FPU) is not saved, before entering a signal handler. It can be extremely costly to save the FPU state. Most signal handlers do not use floating-point operations, so the overhead of saving FPU state is avoided. An example of a signal handler that saves the FPU state is the function @code{dbgsig} in @file{src/debug/common/dbgcom.c} in the DJGPP sources. You may pass @code{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), @code{SIG_ERR} to force an error when that signal happens, or @code{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{}) 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{}: @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}), and by the @code{abort} function (@pxref{abort}). @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). The co-processor status word is printed by the default handler for this signal. @xref{_status87}, for the definition of the individual bits of the status word. The DJGPP startup code masks all numeric exceptions, so this signal is usually only triggered by an integer divide by zero operation. If you want to unmask some of the numeric exceptions, see @ref{_control87}. @item SIGILL The Invalid Execution signal. Currently only generated for unknown/invalid exceptions. @item SIGINT The Interrupt signal. Generated when an INTR key (@kbd{Ctrl-C} by default) or @kbd{Ctrl-@key{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-@key{BREAK}} always generates @code{SIGINT}. DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to generate @code{SIGINT} in response to the INTR key; you should be aware of this when you install a handler for the keyboard interrupt. Note that the key which generates @code{SIGINT} can be changed with a call to @code{__djgpp_set_sigint_key} function. @xref{__djgpp_set_sigint_key}. @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), Invalid TSS (Int 0Ah), 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. The Double Exception, Invalid TSS, Segment Not Present, Stack Fault, GPF, and Page Fault exceptions will cause an error code to be printed, if it is non-zero. @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. Generated when the QUIT key (@kbd{Ctrl-\} by default) is hit. The key that raises the signal can be changed with a call to @code{__djgpp_set_sigquit_key} function. @xref{__djgpp_set_sigquit_key}. By default, @code{SIGQUIT} is discarded, even if its handler is @code{SIG_DFL}, so that DOS programs which don't expect it do not break. You can change the effect of @code{SIGQUIT} to abort with traceback by installing @code{__djgpp_traceback_exit} as its handler. @xref{__djgpp_traceback_exit}. DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to generate @code{SIGQUIT} in response to the QUIT key; you should be aware of this when you install a handler for the keyboard interrupt. @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}, and @pxref{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. @subheading Portability @portability ansi, posix @c ------------------------------------------------------------------------- @node __djgpp_set_ctrl_c, signal @findex __djgpp_set_ctrl_c @subheading Syntax @example #include int __djgpp_set_ctrl_c(int enable); @end example @subheading Description This function sets and resets the bit which controls whether signals @code{SIGINT} and @code{SIGQUIT} (@pxref{signal}) will be raised when you press the INTR or QUIT keys. By default these generate signals 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 signals is turned off, because some programs want to get the @samp{^C} and @samp{^\} characters as any other character and handle them by themselves. @code{__djgpp_set_ctrl_c} lets you explicitly determine the effect of INTR and QUIT keys. When called with a non-zero, positive value of @var{enable}, it arranges for @code{SIGINT} and @code{SIGQUIT} signals to be generated when the appropriate key is pressed; if you call it with a zero in @var{enable}, these keys are treated as normal characters. If @var{enable} is negative, @code{__djgpp_set_ctrl_c} returns the current state of the signal generation, but doesn't change it. For getting similar effects via the POSIX @code{termios} functions, see @ref{tcsetattr}. Note that the effect of @kbd{Ctrl-@key{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 state of @code{SIGINT} and @code{SIGQUIT} generation before the call: 0 if it was disabled, 1 if it was enabled. If the argument @var{enable} is negative, the state is not altered. @subheading Portability @portability !ansi, !posix @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 @findex __djgpp_exception_toggle @subheading Syntax @example #include 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 function that spawns a child program, when you don't want to handle signals generated while the child runs (by default, those signals are also passed to the parent). @subheading Portability @portability !ansi, !posix @subheading Example @example __djgpp_exception_toggle(); system("myprog"); __djgpp_exception_toggle(); @end example @c ------------------------------------------------------------------------- @node __djgpp_set_sigint_key, signal @findex __djgpp_set_sigint_key @subheading Syntax @example #include void __djgpp_set_sigint_key(int new_key); @end example @subheading Description This function changes the INTR key that generates the signal @code{SIGINT}. By default, @kbd{Ctrl-C} is set as the INTR key. To replace it with another key, put the @emph{scan code} of the new INTR key into the bits 0-7 and the required keyboard status byte into bits 8-15 of @var{new_key}, and call this function. Here's how the keyboard status bits are defined: @example Bit 76543210 Meaning .......X Right Shift key ......X. Left Shift key .....X.. Ctrl key ....X... Alt key ...X.... Scroll Lock key ..X..... Num Lock key .X...... Caps Lock key X....... Insert @end example @noindent A 1 in any of the above bits means that the corresponding key should be pressed; a zero means it should be released. Currently, all but the lower 4 bits are always ignored by the DJGPP keyboard handler when you set the INTR key using this function. For example, the default @kbd{Ctrl-C} key should be passed as @code{0x042e}, since the scan code of the @key{C} key is 2Eh, and when the @key{Ctrl} key is pressed, the keyboard status byte is 04h. To disable @code{SIGINT} generation, pass zero as the argument (since no key has a zero scan code). This function will set things up so that the left @key{Shift} key doesn't affect Ctrl- and Alt-modified keys; the right @key{Shift} key won't affect them either, unless its bit is explicitly set in @var{new_key}. This means that @kbd{Ctrl-C} and @kbd{Ctrl-c} will both trigger @code{SIGINT} if @code{0x042e} is passed to this function. The DJGPP built-in keyboard handler pretends that when the right @key{Shift} key is pressed, so is the left @key{Shift} key (but not vice versa). For getting similar effects via the POSIX @code{termios} functions, see @ref{tcsetattr}. @subheading Return Value The previous INTR key (scan code in bits 0-7, keyboard status in bits 8-15). @subheading Portability @portability !ansi, !posix @subheading Example @example __djgpp_set_sigint_key(0x0422); /* make Ctrl-g generate SIGINT's */ @end example @c ------------------------------------------------------------------------- @node __djgpp_set_sigquit_key, signal @findex __djgpp_set_sigquit_key @subheading Syntax @example #include void __djgpp_set_sigquit_key(int new_key); @end example @subheading Description This function changes the QUIT key that generates the signal @code{SIGQUIT}. By default, @kbd{Ctrl-\} is set as the QUIT key. To replace it with another key, put the @emph{scan code} of the new QUIT key into the bits 0-7 and the required keyboard status byte into bits 8-15 of @var{new_key}, and call this function. Here's how the keyboard status bits are defined: @example Bit 76543210 Meaning .......X Right Shift key ......X. Left Shift key .....X.. Ctrl key ....X... Alt key ...X.... Scroll Lock key ..X..... Num Lock key .X...... Caps Lock key X....... Insert @end example @noindent A 1 in any of the above bits means that the corresponding key should be pressed; a zero means it should be released. Currently, all but the lower 4 bits are always ignored by the DJGPP keyboard handler when you set the QUIT key with this function. For example, the default @kbd{Ctrl-\} key should be passed as @code{0x042b}, since the scan code of @code{\} is 2Bh and when the @key{Ctrl} key is pressed, the keyboard status byte is 04h. To disable @code{SIGQUIT} generation, pass zero as the argument (since no key has a zero scan code). This function will set things up so that the left @key{Shift} key doesn't affect Ctrl- and Alt-modified keys; the right @key{Shift} key won't affect them either, unless its bit is explicitly set in @var{new_key}. This means that @kbd{Ctrl-\} and @kbd{Ctrl-|} will both trigger @code{SIGQUIT} if @code{0x042b} is passed to this function. The DJGPP built-in keyboard handler pretends that when the right @key{Shift} key is pressed, so is the left @key{Shift} key (but not vice versa). For getting similar effects via the POSIX @code{termios} functions, see @ref{tcsetattr}. @subheading Return Value The previous QUIT key (scan code in bits 0-7, keyboard status in bits 8-15). @subheading Portability @portability !ansi, !posix @subheading Example @example __djgpp_set_sigint_key(0); /* disable SIGQUIT's */ @end example @c ------------------------------------------------------------------------- @node __djgpp_traceback_exit, signal @findex __djgpp_traceback_exit @subheading Syntax @example #include void __djgpp_traceback_exit(int signo); @end example @subheading Description This function is a signal handler which will print a traceback and abort the program. It is called by default by the DJGPP signal-handling code when any signal except @code{SIGQUIT} is raised (@code{SIGQUIT} is by default discarded). You can use this function to get the Unix behavior of aborting the program on @code{SIGQUIT} (see the example below). When this function is called directly, pass the signal number as its @var{signo} argument. @subheading Portability @portability !ansi, !posix @subheading Example @example signal(SIGQUIT, __djgpp_traceback_exit); @end example