]>
Commit | Line | Data |
---|---|---|
924dca35 | 1 | .\" Copyright (c) 2005 Michael Kerrisk |
c13182ef | 2 | .\" based on earlier work by faith@cs.unc.edu and |
924dca35 MK |
3 | .\" Mike Battersby <mib@deakin.edu.au> |
4 | .\" | |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
924dca35 MK |
6 | .\" |
7 | .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2 | |
8 | .\" | |
4c1c5274 | 9 | .TH sigsuspend 2 (date) "Linux man-pages (unreleased)" |
924dca35 | 10 | .SH NAME |
1edfe5ac | 11 | sigsuspend, rt_sigsuspend \- wait for a signal |
1d52b189 AC |
12 | .SH LIBRARY |
13 | Standard C library | |
8fc3b2cf | 14 | .RI ( libc ", " \-lc ) |
924dca35 | 15 | .SH SYNOPSIS |
c7db92b9 | 16 | .nf |
924dca35 | 17 | .B #include <signal.h> |
68e4db0a | 18 | .PP |
924dca35 | 19 | .BI "int sigsuspend(const sigset_t *" mask ); |
c7db92b9 | 20 | .fi |
68e4db0a | 21 | .PP |
d39ad78f | 22 | .RS -4 |
0f200f07 MK |
23 | Feature Test Macro Requirements for glibc (see |
24 | .BR feature_test_macros (7)): | |
d39ad78f | 25 | .RE |
68e4db0a | 26 | .PP |
0f200f07 | 27 | .BR sigsuspend (): |
9d2adbae MK |
28 | .nf |
29 | _POSIX_C_SOURCE | |
30 | .fi | |
924dca35 MK |
31 | .SH DESCRIPTION |
32 | .BR sigsuspend () | |
2ac1d1e3 | 33 | temporarily replaces the signal mask of the calling thread with the |
c13182ef | 34 | mask given by |
924dca35 | 35 | .I mask |
2ac1d1e3 | 36 | and then suspends the thread until delivery of a signal whose |
924dca35 | 37 | action is to invoke a signal handler or to terminate a process. |
efeece04 | 38 | .PP |
924dca35 MK |
39 | If the signal terminates the process, then |
40 | .BR sigsuspend () | |
41 | does not return. | |
42 | If the signal is caught, then | |
43 | .BR sigsuspend () | |
44 | returns after the signal handler returns, | |
45 | and the signal mask is restored to the state before the call to | |
46 | .BR sigsuspend (). | |
efeece04 | 47 | .PP |
8bd58774 MK |
48 | It is not possible to block |
49 | .B SIGKILL | |
50 | or | |
51 | .BR SIGSTOP ; | |
924dca35 MK |
52 | specifying these signals in |
53 | .IR mask , | |
2ac1d1e3 | 54 | has no effect on the thread's signal mask. |
47297adb | 55 | .SH RETURN VALUE |
924dca35 | 56 | .BR sigsuspend () |
d038a74a MK |
57 | always returns \-1, with |
58 | .I errno | |
48b58f28 | 59 | set to indicate the error (normally, |
d038a74a | 60 | .BR EINTR ). |
924dca35 MK |
61 | .SH ERRORS |
62 | .TP | |
63 | .B EFAULT | |
64 | .I mask | |
65 | points to memory which is not a valid part of the process address space. | |
66 | .TP | |
67 | .B EINTR | |
bb14af39 MK |
68 | The call was interrupted by a signal; |
69 | .BR signal (7). | |
3113c7f3 | 70 | .SH STANDARDS |
7c8f8eaf | 71 | POSIX.1-2001, POSIX.1-2008. |
924dca35 | 72 | .SH NOTES |
c13182ef | 73 | Normally, |
924dca35 MK |
74 | .BR sigsuspend () |
75 | is used in conjunction with | |
0bfa087b | 76 | .BR sigprocmask (2) |
c13182ef | 77 | in order to prevent delivery of a signal during the execution of a |
924dca35 MK |
78 | critical code section. |
79 | The caller first blocks the signals with | |
0bfa087b | 80 | .BR sigprocmask (2). |
924dca35 MK |
81 | When the critical code has completed, the caller then waits for the |
82 | signals by calling | |
83 | .BR sigsuspend () | |
84 | with the signal mask that was returned by | |
0bfa087b | 85 | .BR sigprocmask (2) |
924dca35 | 86 | (in the |
0daa9e92 | 87 | .I oldset |
924dca35 MK |
88 | argument). |
89 | .PP | |
90 | See | |
91 | .BR sigsetops (3) | |
92 | for details on manipulating signal sets. | |
1edfe5ac | 93 | .\" |
0722a578 | 94 | .SS C library/kernel differences |
1edfe5ac MK |
95 | The original Linux system call was named |
96 | .BR sigsuspend (). | |
97 | However, with the addition of real-time signals in Linux 2.2, | |
98 | the fixed-size, 32-bit | |
1ae6b2c7 | 99 | .I sigset_t |
1edfe5ac MK |
100 | type supported by that system call was no longer fit for purpose. |
101 | Consequently, a new system call, | |
102 | .BR rt_sigsuspend (), | |
103 | was added to support an enlarged | |
1ae6b2c7 | 104 | .I sigset_t |
1edfe5ac MK |
105 | type. |
106 | The new system call takes a second argument, | |
107 | .IR "size_t sigsetsize" , | |
108 | which specifies the size in bytes of the signal set in | |
109 | .IR mask . | |
110 | This argument is currently required to have the value | |
1ae6b2c7 | 111 | .I sizeof(sigset_t) |
1edfe5ac MK |
112 | (or the error |
113 | .B EINVAL | |
114 | results). | |
115 | The glibc | |
116 | .BR sigsuspend () | |
117 | wrapper function hides these details from us, transparently calling | |
118 | .BR rt_sigsuspend () | |
119 | when the kernel provides it. | |
120 | .\" | |
47297adb | 121 | .SH SEE ALSO |
924dca35 MK |
122 | .BR kill (2), |
123 | .BR pause (2), | |
124 | .BR sigaction (2), | |
125 | .BR signal (2), | |
126 | .BR sigprocmask (2), | |
127 | .BR sigwaitinfo (2), | |
128 | .BR sigsetops (3), | |
7c85aa6b | 129 | .BR sigwait (3), |
924dca35 | 130 | .BR signal (7) |