Merging upstream version 6.8.

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

1 files changed, 0 insertions, 525 deletions

diff --git a/man2/signalfd.2 b/man2/signalfd.2
deleted file mode 100644
index fba622c..0000000
--- a/man2/signalfd.2
+++ /dev/null
@@ -1,525 +0,0 @@
-.\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
-.\" starting from a version by Davide Libenzi <davidel@xmailserver.org>
-.\"
-.\" SPDX-License-Identifier: GPL-2.0-or-later
-.\"
-.TH signalfd 2 2023-10-31 "Linux man-pages 6.7"
-.SH NAME
-signalfd \- create a file descriptor for accepting signals
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.B #include <sys/signalfd.h>
-.P
-.BI "int signalfd(int " fd ", const sigset_t *" mask ", int " flags );
-.fi
-.SH DESCRIPTION
-.BR signalfd ()
-creates a file descriptor that can be used to accept signals
-targeted at the caller.
-This provides an alternative to the use of a signal handler or
-.BR sigwaitinfo (2),
-and has the advantage that the file descriptor may be monitored by
-.BR select (2),
-.BR poll (2),
-and
-.BR epoll (7).
-.P
-The
-.I mask
-argument specifies the set of signals that the caller
-wishes to accept via the file descriptor.
-This argument is a signal set whose contents can be initialized
-using the macros described in
-.BR sigsetops (3).
-Normally, the set of signals to be received via the
-file descriptor should be blocked using
-.BR sigprocmask (2),
-to prevent the signals being handled according to their default
-dispositions.
-It is not possible to receive
-.B SIGKILL
-or
-.B SIGSTOP
-signals via a signalfd file descriptor;
-these signals are silently ignored if specified in
-.IR mask .
-.P
-If the
-.I fd
-argument is \-1,
-then the call creates a new file descriptor and associates the
-signal set specified in
-.I mask
-with that file descriptor.
-If
-.I fd
-is not \-1,
-then it must specify a valid existing signalfd file descriptor, and
-.I mask
-is used to replace the signal set associated with that file descriptor.
-.P
-Starting with Linux 2.6.27, the following values may be bitwise ORed in
-.I flags
-to change the behavior of
-.BR signalfd ():
-.TP 14
-.B SFD_NONBLOCK
-Set the
-.B O_NONBLOCK
-file status flag on the open file description (see
-.BR open (2))
-referred to by the new file descriptor.
-Using this flag saves extra calls to
-.BR fcntl (2)
-to achieve the same result.
-.TP
-.B SFD_CLOEXEC
-Set the close-on-exec
-.RB ( FD_CLOEXEC )
-flag on the new file descriptor.
-See the description of the
-.B O_CLOEXEC
-flag in
-.BR open (2)
-for reasons why this may be useful.
-.P
-Up to Linux 2.6.26, the
-.I flags
-argument is unused, and must be specified as zero.
-.P
-.BR signalfd ()
-returns a file descriptor that supports the following operations:
-.TP
-.BR read (2)
-If one or more of the signals specified in
-.I mask
-is pending for the process, then the buffer supplied to
-.BR read (2)
-is used to return one or more
-.I signalfd_siginfo
-structures (see below) that describe the signals.
-The
-.BR read (2)
-returns information for as many signals as are pending and will
-fit in the supplied buffer.
-The buffer must be at least
-.I "sizeof(struct signalfd_siginfo)"
-bytes.
-The return value of the
-.BR read (2)
-is the total number of bytes read.
-.IP
-As a consequence of the
-.BR read (2),
-the signals are consumed,
-so that they are no longer pending for the process
-(i.e., will not be caught by signal handlers,
-and cannot be accepted using
-.BR sigwaitinfo (2)).
-.IP
-If none of the signals in
-.I mask
-is pending for the process, then the
-.BR read (2)
-either blocks until one of the signals in
-.I mask
-is generated for the process,
-or fails with the error
-.B EAGAIN
-if the file descriptor has been made nonblocking.
-.TP
-.BR poll (2)
-.TQ
-.BR select (2)
-.TQ
-(and similar)
-The file descriptor is readable
-(the
-.BR select (2)
-.I readfds
-argument; the
-.BR poll (2)
-.B POLLIN
-flag)
-if one or more of the signals in
-.I mask
-is pending for the process.
-.IP
-The signalfd file descriptor also supports the other file-descriptor
-multiplexing APIs:
-.BR pselect (2),
-.BR ppoll (2),
-and
-.BR epoll (7).
-.TP
-.BR close (2)
-When the file descriptor is no longer required it should be closed.
-When all file descriptors associated with the same signalfd object
-have been closed, the resources for object are freed by the kernel.
-.SS The signalfd_siginfo structure
-The format of the
-.I signalfd_siginfo
-structure(s) returned by
-.BR read (2)s
-from a signalfd file descriptor is as follows:
-.P
-.in +4n
-.EX
-struct signalfd_siginfo {
-    uint32_t ssi_signo;    /* Signal number */
-    int32_t  ssi_errno;    /* Error number (unused) */
-    int32_t  ssi_code;     /* Signal code */
-    uint32_t ssi_pid;      /* PID of sender */
-    uint32_t ssi_uid;      /* Real UID of sender */
-    int32_t  ssi_fd;       /* File descriptor (SIGIO) */
-    uint32_t ssi_tid;      /* Kernel timer ID (POSIX timers)
-    uint32_t ssi_band;     /* Band event (SIGIO) */
-    uint32_t ssi_overrun;  /* POSIX timer overrun count */
-    uint32_t ssi_trapno;   /* Trap number that caused signal */
-.\" ssi_trapno is unused on most arches
-    int32_t  ssi_status;   /* Exit status or signal (SIGCHLD) */
-    int32_t  ssi_int;      /* Integer sent by sigqueue(3) */
-    uint64_t ssi_ptr;      /* Pointer sent by sigqueue(3) */
-    uint64_t ssi_utime;    /* User CPU time consumed (SIGCHLD) */
-    uint64_t ssi_stime;    /* System CPU time consumed
-                              (SIGCHLD) */
-    uint64_t ssi_addr;     /* Address that generated signal
-                              (for hardware\-generated signals) */
-    uint16_t ssi_addr_lsb; /* Least significant bit of address
-                              (SIGBUS; since Linux 2.6.37) */
-.\" ssi_addr_lsb: commit b8aeec34175fc8fe8b0d40efea4846dfc1ba663e
-    uint8_t  pad[\fIX\fP];       /* Pad size to 128 bytes (allow for
-                              additional fields in the future) */
-};
-.EE
-.in
-.P
-Each of the fields in this structure
-is analogous to the similarly named field in the
-.I siginfo_t
-structure.
-The
-.I siginfo_t
-structure is described in
-.BR sigaction (2).
-Not all fields in the returned
-.I signalfd_siginfo
-structure will be valid for a specific signal;
-the set of valid fields can be determined from the value returned in the
-.I ssi_code
-field.
-This field is the analog of the
-.I siginfo_t
-.I si_code
-field; see
-.BR sigaction (2)
-for details.
-.SS fork(2) semantics
-After a
-.BR fork (2),
-the child inherits a copy of the signalfd file descriptor.
-A
-.BR read (2)
-from the file descriptor in the child will return information
-about signals queued to the child.
-.SS Semantics of file descriptor passing
-As with other file descriptors,
-signalfd file descriptors can be passed to another process
-via a UNIX domain socket (see
-.BR unix (7)).
-In the receiving process, a
-.BR read (2)
-from the received file descriptor will return information
-about signals queued to that process.
-.SS execve(2) semantics
-Just like any other file descriptor,
-a signalfd file descriptor remains open across an
-.BR execve (2),
-unless it has been marked for close-on-exec (see
-.BR fcntl (2)).
-Any signals that were available for reading before the
-.BR execve (2)
-remain available to the newly loaded program.
-(This is analogous to traditional signal semantics,
-where a blocked signal that is pending remains pending across an
-.BR execve (2).)
-.SS Thread semantics
-The semantics of signalfd file descriptors in a multithreaded program
-mirror the standard semantics for signals.
-In other words,
-when a thread reads from a signalfd file descriptor,
-it will read the signals that are directed to the thread
-itself and the signals that are directed to the process
-(i.e., the entire thread group).
-(A thread will not be able to read signals that are directed
-to other threads in the process.)
-.\"
-.SS epoll(7) semantics
-If a process adds (via
-.BR epoll_ctl (2))
-a signalfd file descriptor to an
-.BR epoll (7)
-instance, then
-.BR epoll_wait (2)
-returns events only for signals sent to that process.
-In particular, if the process then uses
-.BR fork (2)
-to create a child process, then the child will be able to
-.BR read (2)
-signals that are sent to it using the signalfd file descriptor, but
-.BR epoll_wait (2)
-will
-.B not
-indicate that the signalfd file descriptor is ready.
-In this scenario, a possible workaround is that after the
-.BR fork (2),
-the child process can close the signalfd file descriptor that it inherited
-from the parent process and then create another signalfd file descriptor
-and add it to the epoll instance.
-Alternatively, the parent and the child could delay creating their
-(separate) signalfd file descriptors and adding them to the
-epoll instance until after the call to
-.BR fork (2).
-.SH RETURN VALUE
-On success,
-.BR signalfd ()
-returns a signalfd file descriptor;
-this is either a new file descriptor (if
-.I fd
-was \-1), or
-.I fd
-if
-.I fd
-was a valid signalfd file descriptor.
-On error, \-1 is returned and
-.I errno
-is set to indicate the error.
-.SH ERRORS
-.TP
-.B EBADF
-The
-.I fd
-file descriptor is not a valid file descriptor.
-.TP
-.B EINVAL
-.I fd
-is not a valid signalfd file descriptor.
-.\" or, the
-.\" .I sizemask
-.\" argument is not equal to
-.\" .IR sizeof(sigset_t) ;
-.TP
-.B EINVAL
-.I flags
-is invalid;
-or, in Linux 2.6.26 or earlier,
-.I flags
-is nonzero.
-.TP
-.B EMFILE
-The per-process limit on the number of open file descriptors has been reached.
-.TP
-.B ENFILE
-The system-wide limit on the total number of open files has been
-reached.
-.TP
-.B ENODEV
-Could not mount (internal) anonymous inode device.
-.TP
-.B ENOMEM
-There was insufficient memory to create a new signalfd file descriptor.
-.SH VERSIONS
-.SS C library/kernel differences
-The underlying Linux system call requires an additional argument,
-.IR "size_t sizemask" ,
-which specifies the size of the
-.I mask
-argument.
-The glibc
-.BR signalfd ()
-wrapper function does not include this argument,
-since it provides the required value for the underlying system call.
-.P
-There are two underlying Linux system calls:
-.BR signalfd ()
-and the more recent
-.BR signalfd4 ().
-The former system call does not implement a
-.I flags
-argument.
-The latter system call implements the
-.I flags
-values described above.
-Starting with glibc 2.9, the
-.BR signalfd ()
-wrapper function will use
-.BR signalfd4 ()
-where it is available.
-.SH STANDARDS
-Linux.
-.SH HISTORY
-.TP
-.BR signalfd ()
-Linux 2.6.22,
-glibc 2.8.
-.\" signalfd() is in glibc 2.7, but reportedly does not build
-.TP
-.BR signalfd4 ()
-Linux 2.6.27.
-.SH NOTES
-A process can create multiple signalfd file descriptors.
-This makes it possible to accept different signals
-on different file descriptors.
-(This may be useful if monitoring the file descriptors using
-.BR select (2),
-.BR poll (2),
-or
-.BR epoll (7):
-the arrival of different signals will make different file descriptors ready.)
-If a signal appears in the
-.I mask
-of more than one of the file descriptors, then occurrences
-of that signal can be read (once) from any one of the file descriptors.
-.P
-Attempts to include
-.B SIGKILL
-and
-.B SIGSTOP
-in
-.I mask
-are silently ignored.
-.P
-The signal mask employed by a signalfd file descriptor can be viewed
-via the entry for the corresponding file descriptor in the process's
-.IR /proc/ pid /fdinfo
-directory.
-See
-.BR proc (5)
-for further details.
-.\"
-.SS Limitations
-The signalfd mechanism can't be used to receive signals that
-are synchronously generated, such as the
-.B SIGSEGV
-signal that results from accessing an invalid memory address
-or the
-.B SIGFPE
-signal that results from an arithmetic error.
-Such signals can be caught only via signal handler.
-.P
-As described above,
-in normal usage one blocks the signals that will be accepted via
-.BR signalfd ().
-If spawning a child process to execute a helper program
-(that does not need the signalfd file descriptor),
-then, after the call to
-.BR fork (2),
-you will normally want to unblock those signals before calling
-.BR execve (2),
-so that the helper program can see any signals that it expects to see.
-Be aware, however,
-that this won't be possible in the case of a helper program spawned
-behind the scenes by any library function that the program may call.
-In such cases, one must fall back to using a traditional signal
-handler that writes to a file descriptor monitored by
-.BR select (2),
-.BR poll (2),
-or
-.BR epoll (7).
-.SH BUGS
-Before Linux 2.6.25, the
-.I ssi_ptr
-and
-.I ssi_int
-fields are not filled in with the data accompanying a signal sent by
-.BR sigqueue (3).
-.\" The fix also was put into Linux 2.6.24.5
-.SH EXAMPLES
-The program below accepts the signals
-.B SIGINT
-and
-.B SIGQUIT
-via a signalfd file descriptor.
-The program terminates after accepting a
-.B SIGQUIT
-signal.
-The following shell session demonstrates the use of the program:
-.P
-.in +4n
-.EX
-.RB "$" " ./signalfd_demo"
-.BR "\[ha]C" "                   # Control\-C generates SIGINT"
-Got SIGINT
-.B \[ha]C
-Got SIGINT
-\fB\[ha]\e\fP                    # Control\-\e generates SIGQUIT
-Got SIGQUIT
-$
-.EE
-.in
-.SS Program source
-\&
-.\" SRC BEGIN (signalfd.c)
-.EX
-#include <err.h>
-#include <signal.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <sys/signalfd.h>
-#include <unistd.h>
-\&
-int
-main(void)
-{
-    int                      sfd;
-    ssize_t                  s;
-    sigset_t                 mask;
-    struct signalfd_siginfo  fdsi;
-\&
-    sigemptyset(&mask);
-    sigaddset(&mask, SIGINT);
-    sigaddset(&mask, SIGQUIT);
-\&
-    /* Block signals so that they aren\[aq]t handled
-       according to their default dispositions. */
-\&
-    if (sigprocmask(SIG_BLOCK, &mask, NULL) == \-1)
-        err(EXIT_FAILURE, "sigprocmask");
-\&
-    sfd = signalfd(\-1, &mask, 0);
-    if (sfd == \-1)
-        err(EXIT_FAILURE, "signalfd");
-\&
-    for (;;) {
-        s = read(sfd, &fdsi, sizeof(fdsi));
-        if (s != sizeof(fdsi))
-            err(EXIT_FAILURE, "read");
-\&
-        if (fdsi.ssi_signo == SIGINT) {
-            printf("Got SIGINT\en");
-        } else if (fdsi.ssi_signo == SIGQUIT) {
-            printf("Got SIGQUIT\en");
-            exit(EXIT_SUCCESS);
-        } else {
-            printf("Read unexpected signal\en");
-        }
-    }
-}
-.EE
-.\" SRC END
-.SH SEE ALSO
-.BR eventfd (2),
-.BR poll (2),
-.BR read (2),
-.BR select (2),
-.BR sigaction (2),
-.BR sigprocmask (2),
-.BR sigwaitinfo (2),
-.BR timerfd_create (2),
-.BR sigsetops (3),
-.BR sigwait (3),
-.BR epoll (7),
-.BR signal (7)