man3/sigpause.3

   1 .\" Copyright (C) 2004 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH SIGPAUSE 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
   6 .SH NAME
   7 sigpause \- atomically release blocked signals and wait for interrupt
   8 .SH LIBRARY
   9 Standard C library
  10 .RI ( libc ", " \-lc )
  11 .SH SYNOPSIS
  12 .nf
  13 .B #include <signal.h>
  14 .PP
  15 .BI "int sigpause(int " sigmask ");  /* BSD (but see NOTES) */"
  16 .PP
  17 .BI "int sigpause(int " sig ");      /* System V / UNIX 95 */"
  18 .fi
  19 .SH DESCRIPTION
  20 Don't use this function.
  21 Use
  22 .BR sigsuspend (2)
  23 instead.
  24 .PP
  25 The function
  26 .BR sigpause ()
  27 is designed to wait for some signal.
  28 It changes the process's signal mask (set of blocked signals),
  29 and then waits for a signal to arrive.
  30 Upon arrival of a signal, the original signal mask is restored.
  31 .SH RETURN VALUE
  32 If
  33 .BR sigpause ()
  34 returns, it was interrupted by a signal and the return value is \-1
  35 with
  36 .I errno
  37 set to
  38 .BR EINTR .
  39 .SH ATTRIBUTES
  40 For an explanation of the terms used in this section, see
  41 .BR attributes (7).
  42 .ad l
  43 .nh
  44 .TS
  45 allbox;
  46 lbx lb lb
  47 l l l.
  48 Interface       Attribute       Value
  49 T{
  50 .BR sigpause ()
  51 T}      Thread safety   MT-Safe
  52 .TE
  53 .hy
  54 .ad
  55 .sp 1
  56 .\" FIXME: The marking is different from that in the glibc manual,
  57 .\" marking in glibc manual is more detailed:
  58 .\"
  59 .\" sigpause: MT-Unsafe race:sigprocmask/!bsd!linux
  60 .\"
  61 .\" glibc manual says /!linux!bsd indicate the preceding marker only applies
  62 .\" when the underlying kernel is neither Linux nor a BSD kernel.
  63 .\" So, it is safe in Linux kernel.
  64 .SH STANDARDS
  65 The System V version of
  66 .BR sigpause ()
  67 is standardized in POSIX.1-2001.
  68 It is also specified in POSIX.1-2008, where it is marked obsolete.
  69 .SH NOTES
  70 .SS History
  71 The classical BSD version of this function appeared in 4.2BSD.
  72 It sets the process's signal mask to
  73 .IR sigmask .
  74 UNIX 95 standardized the incompatible System V version of
  75 this function, which removes only the specified signal
  76 .I sig
  77 from the process's signal mask.
  78 .\" __xpg_sigpause: UNIX 95, spec 1170, SVID, SVr4, XPG
  79 The unfortunate situation with two incompatible functions with the
  80 same name was solved by the
  81 .BR \%sigsuspend (2)
  82 function, that takes a
  83 .I "sigset_t\ *"
  84 argument (instead of an
  85 .IR int ).
  86 .SS Linux notes
  87 On Linux, this routine is a system call only on the Sparc (sparc64)
  88 architecture.
  89 .PP
  90 .\" Libc4 and libc5 know only about the BSD version.
  91 .\"
  92 Glibc uses the BSD version if the
  93 .B _BSD_SOURCE
  94 feature test macro is defined and none of
  95 .BR _POSIX_SOURCE ,
  96 .BR _POSIX_C_SOURCE ,
  97 .BR _XOPEN_SOURCE ,
  98 .BR _GNU_SOURCE ,
  99 or
 100 .B _SVID_SOURCE
 101 is defined.
 102 Otherwise, the System V version is used,
 103 and feature test macros must be defined as follows to obtain the declaration:
 104 .IP * 3
 105 Since glibc 2.26:
 106 _XOPEN_SOURCE >= 500
 107 .\" || (_XOPEN_SOURCE && _XOPEN_SOURCE_EXTENDED)
 108 .IP *
 109 Glibc 2.25 and earlier: _XOPEN_SOURCE
 110 .PP
 111 Since glibc 2.19, only the System V version is exposed by
 112 .IR <signal.h> ;
 113 applications that formerly used the BSD
 114 .BR sigpause ()
 115 should be amended to use
 116 .BR sigsuspend (2).
 117 .\"
 118 .\" For the BSD version, one usually uses a zero
 119 .\" .I sigmask
 120 .\" to indicate that no signals are to be blocked.
 121 .SH SEE ALSO
 122 .BR kill (2),
 123 .BR sigaction (2),
 124 .BR sigprocmask (2),
 125 .BR sigsuspend (2),
 126 .BR sigblock (3),
 127 .BR sigvec (3),
 128 .BR feature_test_macros (7)