Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 162 insertions, 0 deletions

diff --git a/man/man3/sigqueue.3 b/man/man3/sigqueue.3
new file mode 100644
index 0000000..341d942
--- /dev/null
+++ b/man/man3/sigqueue.3
@@ -0,0 +1,162 @@
+'\" t
+.\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.\" added note on self-signaling, aeb, 2002-06-07
+.\" added note on CAP_KILL, mtk, 2004-06-16
+.\"
+.TH sigqueue 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+sigqueue \- queue a signal and data to a process
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <signal.h>
+.P
+.BI "int sigqueue(pid_t " pid ", int " sig ", const union sigval " value );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR sigqueue ():
+.nf
+    _POSIX_C_SOURCE >= 199309L
+.fi
+.SH DESCRIPTION
+.BR sigqueue ()
+sends the signal specified in
+.I sig
+to the process whose PID is given in
+.IR pid .
+The permissions required to send a signal are the same as for
+.BR kill (2).
+As with
+.BR kill (2),
+the null signal (0) can be used to check if a process with a given
+PID exists.
+.P
+The
+.I value
+argument is used to specify an accompanying item of data (either an integer
+or a pointer value) to be sent with the signal, and has the following type:
+.P
+.in +4n
+.EX
+union sigval {
+    int   sival_int;
+    void *sival_ptr;
+};
+.EE
+.in
+.P
+If the receiving process has installed a handler for this signal using the
+.B SA_SIGINFO
+flag to
+.BR sigaction (2),
+then it can obtain this data via the
+.I si_value
+field of the
+.I siginfo_t
+structure passed as the second argument to the handler.
+Furthermore, the
+.I si_code
+field of that structure will be set to
+.BR SI_QUEUE .
+.SH RETURN VALUE
+On success,
+.BR sigqueue ()
+returns 0, indicating that the signal was successfully
+queued to the receiving process.
+Otherwise, \-1 is returned and
+.I errno
+is set to indicate the error.
+.SH ERRORS
+.TP
+.B EAGAIN
+The limit of signals which may be queued has been reached.
+(See
+.BR signal (7)
+for further information.)
+.TP
+.B EINVAL
+.I sig
+was invalid.
+.TP
+.B EPERM
+The process does not have permission to send the signal
+to the receiving process.
+For the required permissions, see
+.BR kill (2).
+.TP
+.B ESRCH
+No process has a PID matching
+.IR pid .
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lbx lb lb
+l l l.
+Interface	Attribute	Value
+T{
+.na
+.nh
+.BR sigqueue ()
+T}	Thread safety	MT-Safe
+.TE
+.SH VERSIONS
+.SS C library/kernel differences
+On Linux,
+.BR sigqueue ()
+is implemented using the
+.BR rt_sigqueueinfo (2)
+system call.
+The system call differs in its third argument, which is the
+.I siginfo_t
+structure that will be supplied to the receiving process's
+signal handler or returned by the receiving process's
+.BR sigtimedwait (2)
+call.
+Inside the glibc
+.BR sigqueue ()
+wrapper, this argument,
+.IR uinfo ,
+is initialized as follows:
+.P
+.in +4n
+.EX
+uinfo.si_signo = sig;      /* Argument supplied to sigqueue() */
+uinfo.si_code = SI_QUEUE;
+uinfo.si_pid = getpid();   /* Process ID of sender */
+uinfo.si_uid = getuid();   /* Real UID of sender */
+uinfo.si_value = val;      /* Argument supplied to sigqueue() */
+.EE
+.in
+.SH STANDARDS
+POSIX.1-2008.
+.SH HISTORY
+Linux 2.2.
+POSIX.1-2001.
+.SH NOTES
+If this function results in the sending of a signal to the process
+that invoked it, and that signal was not blocked by the calling thread,
+and no other threads were willing to handle this signal (either by
+having it unblocked, or by waiting for it using
+.BR sigwait (3)),
+then at least some signal must be delivered to this thread before this
+function returns.
+.SH SEE ALSO
+.BR kill (2),
+.BR rt_sigqueueinfo (2),
+.BR sigaction (2),
+.BR signal (2),
+.BR pthread_sigqueue (3),
+.BR sigwait (3),
+.BR signal (7)