man3/sigpause.3

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