Important Notice
The pages on this site contain documentation for very old MS-DOS software,
purely for historical purposes.
If you're looking for up-to-date documentation, particularly for programming,
you should not rely on the information found here, as it will be woefully
out of date.
signal
◄Summary► ◄Example► ◄Up► ◄Contents► ◄Index► ◄Back►
────────────────────────────────────────────────────────────────────────────
The signal function allows a process to choose one of several ways
to handle an interrupt signal from the operating system.
The <sig> argument must be one of the following manifest constants
(defined in SIGNAL.H):
SIGABRT SIGILL SIGTERM SIGUSR2
SIGBREAK SIGINT SIGUSR1 SIGUSR3
SIGFPE SIGSEGV
SIGUSR1, SIGUSR2, and SIGUSR3 are user-defined signals that can be
sent by means of DosFlagProcess.
Note that SIGILL, SIGSEGV, and SIGTERM are not generated under
DOS, and that SIGSEGV is not generated under OS/2. They are
included for ANSI compatibility. Thus you can set signal handlers
for these signals via signal, and you can also explicitly generate
these signals by calling raise.
Note also that signal settings are not preserved in child
processes created by calls to exec or spawn. The signal settings
are reset to the default in the child process.
The action taken when the interrupt signal is received depends on
the value of <func>. The <func> argument must be either a function
address or one of the manifest constants defined in SIGNAL.H and
listed below:
Value Meaning
SIG_ACK Acknowledges receipt of a signal (OS/2 only).
This constant is valid only if a user-defined signal
handler is installed. Once a process receives a given
signal, the operating system does not send any more
signals of this type until it receives a SIG_ACK
acknowledgment from the process. The operating system
does not queue up signals of a given type. Therefore,
if more than one signal of a given type accumulates
before the process returns a SIG_ACK value, only the
most recent signal is sent to the process after the
SIG_ACK value is received by the operating system.
This option has no effect on which handler is
installed for a given signal. The manifest constant
SIG_ACK is not supported for SIGFPE signals.
SIG_DFL Uses system-default response.
The system-default response for all signals except
SIGUSR1, SIGUSR2, and SIGUSR3 is to abort the calling
program. The calling process is terminated with exit
code 3, and control returns to DOS or OS/2. If the
calling program uses stream I/O, buffers created by
the run-time library are not flushed, but buffers
created by the operating system are flushed. The
default response for SIGUSR1, SIGUSR2, and SIGUSR3 is
to ignore the signal.
SIG_ERR Ignores interrupt signal (OS/2 only).
This constant is equivalent to SIG_IGN except that
any process trying to send this signal receives
an error. A process may use the raise function to
send a signal to itself. A different process may send
a signal by means of the function DosFlagProcess (if
the signal is SIGUSR1, SIGUSR2, or SIGUSR3) or by
means of DosKillProcess (if the signal is SIGTERM).
SIG_IGN Ignores interrupt signal. This value should never be
given for SIGFPE, since the floating-point state of
the process is left undefined.
Function Installs the specified function as the handler for
address the given signal.
For all signals except SIGFPE and SIGUSRx, the
function is passed the <sig> argument SIGINT and
executed.
For SIGFPE signals, the function is passed two
arguments: SIGFPE and the floating-point error code
identifying the type of exception that occurred.
For the SIGUSRx signals, the function is passed two
arguments: the signal number and the argument
furnished by the DosFlagProcess function.
For SIGFPE, the function pointed to by <func> is passed two
arguments: SIGFPE and an integer error subcode, FPE_xxx; then the
function is executed. (See the include file FLOAT.H for
definitions of the FPE_xxx subcodes.) The value of <func> is not
reset upon receiving the signal. To recover from floating-point
exceptions, use setjmp in conjunction with longjmp. If the
function returns, the calling process resumes execution with the
floating-point state of the process left undefined.
If the function returns, the calling process resumes execution
immediately following the point at which it received the interrupt
signal. This is true regardless of the type of signal or operating
mode.
Before the specified function is executed under DOS version 3.x or
earlier, the value of <func> is set to SIG_DFL. The next interrupt
signal is treated as described above for SIG_DFL, unless an
intervening call to signal specifies otherwise. This allows the
user to reset signals in the called function if desired.
Under OS/2, the signal handler is not reset to the system-default
response. Instead, no signals of a given type are received by a
process until the process sends a SIG_ACK value to the operating
system. The user can restore the system-default response from the
handler by first sending SIG_DFL and then sending SIG_ACK to the
operating system.
Since signal-handler routines are normally called asynchronously
when an interrupt occurs, it is possible that your signal-
handler function will get control when a C run-time operation is
incomplete and in an unknown state. There are certain restrictions
as to which C functions you can use in your signal-handler
routine. The list below summarizes these restrictions:
1. Do not issue low-level or STDIO.H I/O routines (e.g., printf,
fread, etc.).
2. Do not call heap routines or any routine that uses the heap
routines (e.g., malloc, freect, strdup, putenv, etc.).
3. Do not use any C function that generates a system call (e.g.,
getcwd, time, etc.).
4. Do not use the longjmp function unless the interrupt is caused
by a floating-point exception (i.e., <sig> is SIGFPE). In this
case, the program should first reinitialize the floating-point
package by means of a call to _fpreset.
5. Do not use any overlay routines.
Return Value
The signal function returns the previous value of <func>
associated with the given signal. For example, if the previous
value of <func> was SIG_IGN, the return value will be SIG_IGN. The
one exception is SIG_ACK, which returns the address of the
currently installed handler.
A return value of -1 indicates an error, and errno is set to
EINVAL. The possible error causes are an invalid <sig> value, an
invalid <func> value (that is, a value that is less than SIG_ACK
but not defined), or a <func> value of SIG_ACK used when no
handler is currently installed.
-♦-