.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "SIGHOLD" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" sighold 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.SH NAME
sighold, sigignore, sigpause, sigrelse, sigset \- signal management
.SH SYNOPSIS
.LP
\fB#include <signal.h>
.br
.sp
int sighold(int\fP \fIsig\fP\fB);
.br
int sigignore(int\fP \fIsig\fP\fB);
.br
int sigpause(int\fP \fIsig\fP\fB);
.br
int sigrelse(int\fP \fIsig\fP\fB);
.br
void (*sigset(int\fP \fIsig\fP\fB, void (*\fP\fIdisp\fP\fB)(int)))(int);
\fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
Use of any of these functions is unspecified in a multi-threaded process.
.LP
The \fIsighold\fP(), \fIsigignore\fP(), \fIsigpause\fP(), \fIsigrelse\fP(),
and \fIsigset\fP() functions provide simplified
signal management.
.LP
The \fIsigset\fP() function shall modify signal dispositions. The
\fIsig\fP argument specifies the signal, which may be any
signal except SIGKILL and SIGSTOP. The \fIdisp\fP argument specifies
the signal's disposition, which may be SIG_DFL, SIG_IGN, or
the address of a signal handler. If \fIsigset\fP() is used, and \fIdisp\fP
is the address of a signal handler, the system shall
add \fIsig\fP to the calling process' signal mask before executing
the signal handler; when the signal handler returns, the system
shall restore the calling process' signal mask to its state prior
to the delivery of the signal. In addition, if \fIsigset\fP() is
used, and \fIdisp\fP is equal to SIG_HOLD, \fIsig\fP shall be added
to the calling process' signal mask and \fIsig\fP's
disposition shall remain unchanged. If \fIsigset\fP() is used, and
\fIdisp\fP is not equal to SIG_HOLD, \fIsig\fP shall be
removed from the calling process' signal mask.
.LP
The \fIsighold\fP() function shall add \fIsig\fP to the calling process'
signal mask.
.LP
The \fIsigrelse\fP() function shall remove \fIsig\fP from the calling
process' signal mask.
.LP
The \fIsigignore\fP() function shall set the disposition of \fIsig\fP
to SIG_IGN.
.LP
The \fIsigpause\fP() function shall remove \fIsig\fP from the calling
process' signal mask and suspend the calling process
until a signal is received. The \fIsigpause\fP() function shall restore
the process' signal mask to its original state before
returning.
.LP
If the action for the SIGCHLD signal is set to SIG_IGN, child processes
of the calling processes shall not be transformed into
zombie processes when they terminate. If the calling process subsequently
waits for its children, and the process has no
unwaited-for children that were transformed into zombie processes,
it shall block until all of its children terminate, and \fIwait\fP(),
\fIwaitid\fP(), and \fIwaitpid\fP() shall fail and set \fIerrno\fP
to [ECHILD].
.SH RETURN VALUE
.LP
Upon successful completion, \fIsigset\fP() shall return SIG_HOLD if
the signal had been blocked and the signal's previous
disposition if it had not been blocked. Otherwise, SIG_ERR shall be
returned and \fIerrno\fP set to indicate the error.
.LP
The \fIsigpause\fP() function shall suspend execution of the thread
until a signal is received, whereupon it shall return -1
and set \fIerrno\fP to [EINTR].
.LP
For all other functions, upon successful completion, 0 shall be returned.
Otherwise, -1 shall be returned and \fIerrno\fP set
to indicate the error.
.SH ERRORS
.LP
These functions shall fail if:
.TP 7
.B EINVAL
The \fIsig\fP argument is an illegal signal number.
.sp
.LP
The \fIsigset\fP() and \fIsigignore\fP() functions shall fail if:
.TP 7
.B EINVAL
An attempt is made to catch a signal that cannot be caught, or to
ignore a signal that cannot be ignored.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
The \fIsigaction\fP() function provides a more comprehensive and reliable
mechanism
for controlling signals; new applications should use \fIsigaction\fP()
rather than
\fIsigset\fP().
.LP
The \fIsighold\fP() function, in conjunction with \fIsigrelse\fP()
or \fIsigpause\fP(), may be used to establish critical
regions of code that require the delivery of a signal to be temporarily
deferred.
.LP
The \fIsigsuspend\fP() function should be used in preference to \fIsigpause\fP()
for broader portability.
.SH RATIONALE
.LP
None.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fISignal Concepts\fP, \fIexec\fP(), \fIpause\fP(), \fIsigaction\fP(),
\fIsignal\fP(), \fIsigsuspend\fP(), \fIwaitid\fP(), the Base
Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<signal.h>\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .