man2/sigpending.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 SIGPENDING 2 2021-03-22 "Linux man-pages (unreleased)"
  10 .SH NAME
  11 sigpending, rt_sigpending \- examine pending signals
  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 sigpending(sigset_t *" set );
  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 sigpending ():
  28 .nf
  29     _POSIX_C_SOURCE
  30 .fi
  31 .SH DESCRIPTION
  32 .BR sigpending ()
  33 returns the set of signals that are pending for delivery to the calling
  34 thread (i.e., the signals which have been raised while blocked).
  35 The mask of pending signals is returned in
  36 .IR set .
  37 .SH RETURN VALUE
  38 .BR sigpending ()
  39 returns 0 on success.
  40 On failure, \-1 is returned and
  41 .I errno
  42 is set to indicate the error.
  43 .SH ERRORS
  44 .TP
  45 .B EFAULT
  46 .I set
  47 points to memory which is not a valid part of the process address space.
  48 .SH STANDARDS
  49 POSIX.1-2001, POSIX.1-2008.
  50 .SH NOTES
  51 See
  52 .BR sigsetops (3)
  53 for details on manipulating signal sets.
  54 .PP
  55 If a signal is both blocked and has a disposition of "ignored", it is
  56 .I not
  57 added to the mask of pending signals when generated.
  58 .PP
  59 The set of signals that is pending for a thread
  60 is the union of the set of signals that is pending for that thread
  61 and the set of signals that is pending for the process as a whole; see
  62 .BR signal (7).
  63 .PP
  64 A child created via
  65 .BR fork (2)
  66 initially has an empty pending signal set;
  67 the pending signal set is preserved across an
  68 .BR execve (2).
  69 .\"
  70 .SS C library/kernel differences
  71 The original Linux system call was named
  72 .BR sigpending ().
  73 However, with the addition of real-time signals in Linux 2.2,
  74 the fixed-size, 32-bit
  75 .I sigset_t
  76 argument supported by that system call was no longer fit for purpose.
  77 Consequently, a new system call,
  78 .BR rt_sigpending (),
  79 was added to support an enlarged
  80 .I sigset_t
  81 type.
  82 The new system call takes a second argument,
  83 .IR "size_t sigsetsize" ,
  84 which specifies the size in bytes of the signal set in
  85 .IR set .
  86 .\" This argument is currently required to be less than or equal to
  87 .\" .IR sizeof(sigset_t)
  88 .\" (or the error
  89 .\" .B EINVAL
  90 .\" results).
  91 The glibc
  92 .BR sigpending ()
  93 wrapper function hides these details from us, transparently calling
  94 .BR rt_sigpending ()
  95 when the kernel provides it.
  96 .\"
  97 .SH BUGS
  98 In versions of glibc up to and including 2.2.1,
  99 there is a bug in the wrapper function for
 100 .BR sigpending ()
 101 which means that information about pending real-time signals
 102 is not correctly returned.
 103 .SH SEE ALSO
 104 .BR kill (2),
 105 .BR sigaction (2),
 106 .BR signal (2),
 107 .BR sigprocmask (2),
 108 .BR sigsuspend (2),
 109 .BR sigsetops (3),
 110 .BR signal (7)