man3p/sigemptyset.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "SIGEMPTYSET" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" sigemptyset
   4 .SH NAME
   5 sigemptyset \- initialize and empty a signal set
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <signal.h>
   9 .br
  10 .sp
  11 int sigemptyset(sigset_t *\fP\fIset\fP\fB); \fP
  12 \fB
  13 .br
  14 \fP
  15 .SH DESCRIPTION
  16 .LP
  17 The \fIsigemptyset\fP() function initializes the signal set pointed
  18 to by \fIset\fP, such that all signals defined in
  19 IEEE\ Std\ 1003.1-2001 are excluded.
  20 .SH RETURN VALUE
  21 .LP
  22 Upon successful completion, \fIsigemptyset\fP() shall return 0; otherwise,
  23 it shall return -1 and set \fIerrno\fP to indicate
  24 the error.
  25 .SH ERRORS
  26 .LP
  27 No errors are defined.
  28 .LP
  29 \fIThe following sections are informative.\fP
  30 .SH EXAMPLES
  31 .LP
  32 None.
  33 .SH APPLICATION USAGE
  34 .LP
  35 None.
  36 .SH RATIONALE
  37 .LP
  38 The implementation of the \fIsigemptyset\fP() (or \fIsigfillset\fP())
  39 function
  40 could quite trivially clear (or set) all the bits in the signal set.
  41 Alternatively, it would be reasonable to initialize part of
  42 the structure, such as a version field, to permit binary-compatibility
  43 between releases where the size of the set varies. For such
  44 reasons, either \fIsigemptyset\fP() or \fIsigfillset\fP() must be
  45 called prior to any
  46 other use of the signal set, even if such use is read-only (for example,
  47 as an argument to \fIsigpending\fP()). This function is not intended
  48 for dynamic allocation.
  49 .LP
  50 The \fIsigfillset\fP() and \fIsigemptyset\fP() functions require that
  51 the resulting
  52 signal set include (or exclude) all the signals defined in this volume
  53 of IEEE\ Std\ 1003.1-2001. Although it is outside
  54 the scope of this volume of IEEE\ Std\ 1003.1-2001 to place this requirement
  55 on signals that are implemented as extensions,
  56 it is recommended that implementation-defined signals also be affected
  57 by these functions. However, there may be a good reason for
  58 a particular signal not to be affected. For example, blocking or ignoring
  59 an implementation-defined signal may have undesirable
  60 side effects, whereas the default action for that signal is harmless.
  61 In such a case, it would be preferable for such a signal to
  62 be excluded from the signal set returned by \fIsigfillset\fP().
  63 .LP
  64 In early proposals there was no distinction between invalid and unsupported
  65 signals (the names of optional signals that were not
  66 supported by an implementation were not defined by that implementation).
  67 The [EINVAL] error was thus specified as a required error
  68 for invalid signals. With that distinction, it is not necessary to
  69 require implementations of these functions to determine whether
  70 an optional signal is actually supported, as that could have a significant
  71 performance impact for little value. The error could
  72 have been required for invalid signals and optional for unsupported
  73 signals, but this seemed unnecessarily complex. Thus, the error
  74 is optional in both cases.
  75 .SH FUTURE DIRECTIONS
  76 .LP
  77 None.
  78 .SH SEE ALSO
  79 .LP
  80 \fISignal Concepts\fP , \fIsigaction\fP() , \fIsigaddset\fP() , \fIsigdelset\fP()
  81 , \fIsigfillset\fP() , \fIsigismember\fP() , \fIsigpending\fP() ,
  82 \fIsigprocmask\fP() , \fIsigsuspend\fP() , the Base Definitions volume
  83 of IEEE\ Std\ 1003.1-2001, \fI<signal.h>\fP
  84 .SH COPYRIGHT
  85 Portions of this text are reprinted and reproduced in electronic form
  86 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
  87 -- Portable Operating System Interface (POSIX), The Open Group Base
  88 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
  89 Electrical and Electronics Engineers, Inc and The Open Group. In the
  90 event of any discrepancy between this version and the original IEEE and
  91 The Open Group Standard, the original IEEE and The Open Group Standard
  92 is the referee document. The original Standard can be obtained online at
  93 http://www.opengroup.org/unix/online.html .