man-pages/man3p/sigemptyset.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "SIGEMPTYSET" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" sigemptyset 
.SH NAME
sigemptyset \- initialize and empty a signal set
.SH SYNOPSIS
.LP
\fB#include <signal.h>
.br
.sp
int sigemptyset(sigset_t *\fP\fIset\fP\fB); \fP
\fB
.br
\fP
.SH DESCRIPTION
.LP
The \fIsigemptyset\fP() function initializes the signal set pointed
to by \fIset\fP, such that all signals defined in
IEEE\ Std\ 1003.1-2001 are excluded.
.SH RETURN VALUE
.LP
Upon successful completion, \fIsigemptyset\fP() shall return 0; otherwise,
it shall return -1 and set \fIerrno\fP to indicate
the error.
.SH ERRORS
.LP
No errors are defined.
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
None.
.SH RATIONALE
.LP
The implementation of the \fIsigemptyset\fP() (or \fIsigfillset\fP())
function
could quite trivially clear (or set) all the bits in the signal set.
Alternatively, it would be reasonable to initialize part of
the structure, such as a version field, to permit binary-compatibility
between releases where the size of the set varies. For such
reasons, either \fIsigemptyset\fP() or \fIsigfillset\fP() must be
called prior to any
other use of the signal set, even if such use is read-only (for example,
as an argument to \fIsigpending\fP()). This function is not intended
for dynamic allocation.
.LP
The \fIsigfillset\fP() and \fIsigemptyset\fP() functions require that
the resulting
signal set include (or exclude) all the signals defined in this volume
of IEEE\ Std\ 1003.1-2001. Although it is outside
the scope of this volume of IEEE\ Std\ 1003.1-2001 to place this requirement
on signals that are implemented as extensions,
it is recommended that implementation-defined signals also be affected
by these functions. However, there may be a good reason for
a particular signal not to be affected. For example, blocking or ignoring
an implementation-defined signal may have undesirable
side effects, whereas the default action for that signal is harmless.
In such a case, it would be preferable for such a signal to
be excluded from the signal set returned by \fIsigfillset\fP().
.LP
In early proposals there was no distinction between invalid and unsupported
signals (the names of optional signals that were not
supported by an implementation were not defined by that implementation).
The [EINVAL] error was thus specified as a required error
for invalid signals. With that distinction, it is not necessary to
require implementations of these functions to determine whether
an optional signal is actually supported, as that could have a significant
performance impact for little value. The error could
have been required for invalid signals and optional for unsupported
signals, but this seemed unnecessarily complex. Thus, the error
is optional in both cases.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fISignal Concepts\fP , \fIsigaction\fP() , \fIsigaddset\fP() , \fIsigdelset\fP()
, \fIsigfillset\fP() , \fIsigismember\fP() , \fIsigpending\fP() ,
\fIsigprocmask\fP() , \fIsigsuspend\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 .