man2/sigsuspend.2

   1 .\" Copyright (c) 2005 Michael Kerrisk
   2 .\" based on earlier work by faith@cs.unc.edu and
   3 .\" Mike Battersby <mib@deakin.edu.au>
   4 .\"
   5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   6 .\"
   7 .\" 2005-09-15, mtk, Created new page by splitting off from sigaction.2
   8 .\"
   9 .TH SIGSUSPEND 2 2021-03-22 "Linux" "Linux Programmer's Manual"
  10 .SH NAME
  11 sigsuspend, rt_sigsuspend \- wait for a signal
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <signal.h>
  18 .PP
  19 .BI "int sigsuspend(const sigset_t *" mask );
  20 .fi
  21 .PP
  22 .RS -4
  23 Feature Test Macro Requirements for glibc (see
  24 .BR feature_test_macros (7)):
  25 .RE
  26 .PP
  27 .BR sigsuspend ():
  28 .nf
  29     _POSIX_C_SOURCE
  30 .fi
  31 .SH DESCRIPTION
  32 .BR sigsuspend ()
  33 temporarily replaces the signal mask of the calling thread with the
  34 mask given by
  35 .I mask
  36 and then suspends the thread until delivery of a signal whose
  37 action is to invoke a signal handler or to terminate a process.
  38 .PP
  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 ().
  47 .PP
  48 It is not possible to block
  49 .B SIGKILL
  50 or
  51 .BR SIGSTOP ;
  52 specifying these signals in
  53 .IR mask ,
  54 has no effect on the thread's signal mask.
  55 .SH RETURN VALUE
  56 .BR sigsuspend ()
  57 always returns \-1, with
  58 .I errno
  59 set to indicate the error (normally,
  60 .BR EINTR ).
  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
  68 The call was interrupted by a signal;
  69 .BR signal (7).
  70 .SH STANDARDS
  71 POSIX.1-2001, POSIX.1-2008.
  72 .SH NOTES
  73 Normally,
  74 .BR sigsuspend ()
  75 is used in conjunction with
  76 .BR sigprocmask (2)
  77 in order to prevent delivery of a signal during the execution of a
  78 critical code section.
  79 The caller first blocks the signals with
  80 .BR sigprocmask (2).
  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
  85 .BR sigprocmask (2)
  86 (in the
  87 .I oldset
  88 argument).
  89 .PP
  90 See
  91 .BR sigsetops (3)
  92 for details on manipulating signal sets.
  93 .\"
  94 .SS C library/kernel differences
  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
  99 .I sigset_t
 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
 104 .I sigset_t
 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
 111 .I sizeof(sigset_t)
 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 .\"
 121 .SH SEE ALSO
 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),
 129 .BR sigwait (3),
 130 .BR signal (7)