Date: Sun, 2 Feb 1997 19:14:45 +0200 (IST) From: Eli Zaretskii To: djgpp-workers AT delorie DOT com cc: DJ Delorie Subject: POSIX signal functions (2/2) Message-ID: MIME-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Here's the docs for the POSIX signal functions. ------------------------- sigprocm.txh -------------------------------- @c ---------------------------------------------------------------------- @node sigprocmask, signal @subheading Syntax @example #include 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 #include 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 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 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 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 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 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 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 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.