1SIGHOLD(3P)                POSIX Programmer's Manual               SIGHOLD(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       sighold, sigignore, sigpause, sigrelse, sigset — signal management
13

SYNOPSIS

15       #include <signal.h>
16
17       int sighold(int sig);
18       int sigignore(int sig);
19       int sigpause(int sig);
20       int sigrelse(int sig);
21       void (*sigset(int sig, void (*disp)(int)))(int);
22

DESCRIPTION

24       Use of any of  these  functions  is  unspecified  in  a  multi-threaded
25       process.
26
27       The  sighold(), sigignore(), sigpause(), sigrelse(), and sigset() func‐
28       tions provide simplified signal management.
29
30       The sigset() function shall modify signal dispositions. The  sig  argu‐
31       ment  specifies  the signal, which may be any signal except SIGKILL and
32       SIGSTOP. The disp argument specifies the  signal's  disposition,  which
33       may  be  SIG_DFL,  SIG_IGN,  or  the  address  of  a signal handler. If
34       sigset() is used, and disp is the address of a signal handler, the sys‐
35       tem shall add sig to the signal mask of the calling process before exe‐
36       cuting the signal handler; when the signal handler returns, the  system
37       shall restore the signal mask of the calling process to its state prior
38       to the delivery of the signal. In addition, if sigset()  is  used,  and
39       disp is equal to SIG_HOLD, sig shall be added to the signal mask of the
40       calling process  and  sig's  disposition  shall  remain  unchanged.  If
41       sigset()  is  used,  and  disp  is  not equal to SIG_HOLD, sig shall be
42       removed from the signal mask of the calling process.
43
44       The sighold() function shall add sig to the signal mask of the  calling
45       process.
46
47       The  sigrelse()  function  shall remove sig from the signal mask of the
48       calling process.
49
50       The sigignore() function shall set the disposition of sig to SIG_IGN.
51
52       The sigpause() function shall remove sig from the signal  mask  of  the
53       calling  process  and  suspend  the  calling  process until a signal is
54       received. The sigpause() function shall restore the signal mask of  the
55       process to its original state before returning.
56
57       If the action for the SIGCHLD signal is set to SIG_IGN, child processes
58       of the calling processes shall not be transformed into zombie processes
59       when  they terminate. If the calling process subsequently waits for its
60       children, and the process has no unwaited-for children that were trans‐
61       formed  into zombie processes, it shall block until all of its children
62       terminate, and wait(), waitid(), and waitpid() shall fail and set errno
63       to [ECHILD].
64

RETURN VALUE

66       Upon  successful completion, sigset() shall return SIG_HOLD if the sig‐
67       nal had been blocked and the signal's previous disposition  if  it  had
68       not been blocked. Otherwise, SIG_ERR shall be returned and errno set to
69       indicate the error.
70
71       The sigpause() function shall suspend execution of the thread  until  a
72       signal  is  received,  whereupon  it  shall  return -1 and set errno to
73       [EINTR].
74
75       For all  other  functions,  upon  successful  completion,  0  shall  be
76       returned.   Otherwise,  -1  shall be returned and errno set to indicate
77       the error.
78

ERRORS

80       These functions shall fail if:
81
82       EINVAL The sig argument is an illegal signal number.
83
84       The sigset() and sigignore() functions shall fail if:
85
86       EINVAL An attempt is made to catch a signal that cannot be  caught,  or
87              to ignore a signal that cannot be ignored.
88
89       The following sections are informative.
90

EXAMPLES

92       None.
93

APPLICATION USAGE

95       The  sigaction()  function  provides  a more comprehensive and reliable
96       mechanism for controlling signals;  new  applications  should  use  the
97       sigaction() function instead of the obsolescent sigset() function.
98
99       The  sighold()  function, in conjunction with sigrelse() or sigpause(),
100       may be used to establish critical regions  of  code  that  require  the
101       delivery  of a signal to be temporarily deferred. For broader portabil‐
102       ity, the pthread_sigmask() or sigprocmask() functions  should  be  used
103       instead of the obsolescent sighold() and sigrelse() functions.
104
105       For  broader  portability,  the  sigsuspend()  function  should be used
106       instead of the obsolescent sigpause() function.
107

RATIONALE

109       Each of these historic functions has a direct analog in the other func‐
110       tions  which  are required to be per-thread and thread-safe (aside from
111       sigprocmask(), which is replaced by pthread_sigmask()).   The  sigset()
112       function  can  be implemented as a simple wrapper for sigaction().  The
113       sighold() function is equivalent to sigprocmask() or  pthread_sigmask()
114       with  SIG_BLOCK  set.  The sigignore() function is equivalent to sigac‐
115       tion() with SIG_IGN set. The sigpause() function is equivalent to  sig‐
116       suspend().   The  sigrelse() function is equivalent to sigprocmask() or
117       pthread_sigmask() with SIG_UNBLOCK set.
118

FUTURE DIRECTIONS

120       These functions may be removed in a future version.
121

SEE ALSO

123       Section 2.4, Signal Concepts, exec, pause(), pthread_sigmask(),  sigac‐
124       tion(), signal(), sigsuspend(), wait(), waitid()
125
126       The Base Definitions volume of POSIX.1‐2017, <signal.h>
127
129       Portions  of  this text are reprinted and reproduced in electronic form
130       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
131       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
132       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
133       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
134       event of any discrepancy between this version and the original IEEE and
135       The  Open Group Standard, the original IEEE and The Open Group Standard
136       is the referee document. The original Standard can be  obtained  online
137       at http://www.opengroup.org/unix/online.html .
138
139       Any  typographical  or  formatting  errors that appear in this page are
140       most likely to have been introduced during the conversion of the source
141       files  to  man page format. To report such errors, see https://www.ker
142       nel.org/doc/man-pages/reporting_bugs.html .
143
144
145
146IEEE/The Open Group                  2017                          SIGHOLD(3P)
Impressum