Mail Archives: djgpp-workers/1997/02/02/12:16:07
Here's the docs for the POSIX signal functions.
------------------------- sigprocm.txh --------------------------------
@c ----------------------------------------------------------------------
@node sigprocmask, signal
@subheading Syntax
@example
#include <signal.h>
int sigprocmask (int how, const sigset_t *new_set, sigset_t *old_set)
@end example
@subheading Description
This function is used to examine and/or change the program's current
signal mask. The current signal mask determines which signals are
blocked from being delivered to the program. A signal is blocked if its
bit in the mask is set. (@xref{sigismember}, @xref{sigaddset},
@xref{sigdelset}, @xref{sigemptyset}, @xref{sigfillset}, for information
about functions to manipulate the signal masks.) When a blocked signal
happens, it is not delivered to the program until such time as that
signal is unblocked by another call to @code{sigprocmask}. Thus
blocking a signal is an alternative to ignoring it (by setting its
handler to @code{SIG_IGN}, @xref{signal}), but has an advantage of not
missing the signal entirely.
The value of the argument @var{how} determines the operation: if it is
@code{SIG_BLOCK}, the set pointed to by the argument @var{new_set} is
@emph{added} to the current signal mask. If the value is
@code{SIG_UNBLOCK}, the set pointed to by @var{new_set} is
@emph{removed} from the current signal mask. If the value is
@code{SIG_SETMASK}, the current mask is @emph{replaced} by the set
pointed to by @var{new_set}.
If the argument @var{old_set} is not @code{NULL}, the previous mask is
stored in the space pointed to by @var{old_set}. If the value of the
argument @var{new_set} is @code{NULL}, the value of @var{how} is not
significant and the process signal mask is unchanged; thus, the call
with a zero @var{new_set} can be used to inquire about currently blocked
signals, without changing the current set.
If the new set defined by the call causes some pending signals to be
unblocked, they are all delivered (by calling @code{raise}) before the
call to @code{sigprocmask} returns.
The DJGPP implementation only records a single occurrence of any given
signal, so when the signal is unblocked, its handler will be called at
most once.
It is not possible to block CPU exceptions such as Page Fault, General
Protection Fault etc. (mapped to @code{SIGSEGV} signal); for these,
@code{sigprocmask} will behave as if the call succeeded, but when an
exception happens, the signal handler will be called anyway (the default
handler will abort the program).
Also note that there are no provisions to save and restore any
additional info about the signal beyond the fact that it happened. A
signal handler might need such info to handle the signal intelligently.
For example, a handler for @code{SIGFPE} might need to examine the
status word of the FPU to see what exactly went wrong. But if the
signal was blocked and is delivered after a call to @code{sigprocmask}
has unblocked it, that information is lost. Therefore, if you need
access to such auxiliary information in the signal handler, don't block
that signal.
@subheading Return Value
0 on success, -1 for illegal value of @var{sig} or illegal address in
@var{new_set} or @var{old_set}.
@subheading Example
@example
#include <conio.h>
#include <signal.h>
static void
sig_catcher (int signo)
@{
cprintf ("\r\nGot signal %d\r\n", signo);
@}
int
main (void)
@{
sigset_t sigmask, prevmask;
signal (SIGINT, sig_catcher);
sigemptyset (&sigmask);
sigaddset (&sigmask, SIGINT);
if (sigprocmask (SIG_SETMASK, &sigmask, &prevmask) == 0)
cputs ("SIGINT blocked. Try to interrupt me now.\r\n");
while (!kbhit ())
;
cputs ("See? I wasn't interrupted.\r\n");
cputs ("But now I will unblock SIGINT, and then get the signal.\r\n");
sigprocmask (SIG_UNBLOCK, &sigmask, &prevmask);
return 0;
@}
@end example
@c ----------------------------------------------------------------
@node sigpending, signal
@subheading Syntax
@example
#include <signal.h>
int sigpending (sigset_t *set)
@end example
@subheading Description
This function retrieves the signals that have been sent to the program,
but are being blocked from delivery by the program's signal mask
(@pxref{sigprocmask}). The bit-mapped value which describes the pending
signals is stored in the structure pointed to by @var{set}. You can use
the @code{sigismember} function (@pxref{sigismember}) to see what
individual signals are pending.
@subheading Return Value
0 on success, -1 on failure (and errno set to @code{EFAULT}).
@subheading Example
@example
#include <signal.h>
sigset_t pending_signals;
/* If SIGINT is pending, force it to be raised. */
if (sigpending (&pending_signals) == 0
&& sigismember (&pending_signals, SIGINT))
@{
sigset_t new_set, old_set;
sigemptyset (&new_set);
sigaddset (&new_set, SIGINT);
sigprocmask (SIG_UNBLOCK, &new_set, &old_set); /* will raise SIGINT */
sigprocmask (SIG_SETMASK, &old_set, &new_set); /* restore mask */
@}
@end example
@c -------------------------------------------------------------------
@node sigemptyset, signal
@subheading Syntax
@example
#include <signal.h>
int sigemptyset (sigset_t *set)
@end example
@subheading Description
This function initializes the set of signals pointed to by @var{set} to
exclude all signals known to the DJGPP runtime system. Such an empty
set, if passed to @code{sigprocmask} (@pxref{sigprocmask}), will cause
all signals to be passed immediately to their handlers.
@subheading Return Value
0 upon success, -1 if @var{set} is a NULL pointer.
@c -------------------------------------------------------------------
@node sigfillset, signal
@subheading Syntax
@example
#include <signal.h>
int sigfillset (sigset_t *set)
@end example
@subheading Description
This function initializes the set of signals pointed to by @var{set} to
include all signals known to the DJGPP runtime system. Such a full
set, if set by @code{sigprocmask} (@pxref{sigprocmask}), will cause
all signals to be blocked from delivery to their handlers. Note that
the set returned by this function only includes signals in the range
@code{SIGABRT..SIGTRAP}; software interrupts and/or user-defined signals
aren't included.
@subheading Return Value
0 upon success, -1 if @var{set} is a NULL pointer.
@subheading Example
@example
sigset_t full_set, prev_set;
sigfillset (&full_set);
sigprocmask (SIG_UNBLOCK, &full_set, &prev_set);
@end example
@c -------------------------------------------------------------------
@node sigaddset, signal
@subheading Syntax
@example
#include <signal.h>
int sigaddset (sigset_t *set, int signo)
@end example
@subheading Description
This function adds the individual signal specified by @var{signo} the
set of signals pointed to by @var{set}.
@subheading Return Value
0 upon success, -1 if @var{set} is a NULL pointer, or if @var{signo} is
specifies an unknown signal.
@c -------------------------------------------------------------------
@node sigdelset, signal
@subheading Syntax
@example
#include <signal.h>
int sigdelset (sigset_t *set, int signo)
@end example
@subheading Description
This function removess the individual signal specified by @var{signo}
from the set of signals pointed to by @var{set}.
@subheading Return Value
0 upon success, -1 if @var{set} is a NULL pointer, or if @var{signo} is
specifies an unknown signal.
@c -------------------------------------------------------------------
@node sigismember, signal
@subheading Syntax
@example
#include <signal.h>
int sigismember (sigset_t *set, int signo)
@end example
@subheading Description
This function checks whether the signal specified by @var{signo} is a
member of the set of signals pointed to by @var{set}.
@subheading Return Value
1 if the specified signal is a member of the set, 0 if it isn't, or if
@var{signo} specifies an unknown signal, -1 if @var{set} is a NULL
pointer.
- Raw text -