diff options
author | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:40:15 +0000 |
---|---|---|
committer | Daniel Baumann <daniel.baumann@progress-linux.org> | 2024-04-15 19:40:15 +0000 |
commit | 399644e47874bff147afb19c89228901ac39340e (patch) | |
tree | 1c4c0b733f4c16b5783b41bebb19194a9ef62ad1 /man2/sigwaitinfo.2 | |
parent | Initial commit. (diff) | |
download | manpages-399644e47874bff147afb19c89228901ac39340e.tar.xz manpages-399644e47874bff147afb19c89228901ac39340e.zip |
Adding upstream version 6.05.01.upstream/6.05.01
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man2/sigwaitinfo.2')
-rw-r--r-- | man2/sigwaitinfo.2 | 231 |
1 files changed, 231 insertions, 0 deletions
diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2 new file mode 100644 index 0000000..a5703fc --- /dev/null +++ b/man2/sigwaitinfo.2 @@ -0,0 +1,231 @@ +.\" Copyright (c) 2002 Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH sigwaitinfo 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +sigwaitinfo, sigtimedwait, rt_sigtimedwait \- synchronously wait +for queued signals +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <signal.h> +.PP +.BI "int sigwaitinfo(const sigset_t *restrict " set , +.BI " siginfo_t *_Nullable restrict " info ); +.BI "int sigtimedwait(const sigset_t *restrict " set , +.BI " siginfo_t *_Nullable restrict " info , +.BI " const struct timespec *restrict " timeout ); +.fi +.PP +.RS -4 +Feature Test Macro Requirements for glibc (see +.BR feature_test_macros (7)): +.RE +.PP +.BR sigwaitinfo (), +.BR sigtimedwait (): +.nf + _POSIX_C_SOURCE >= 199309L +.fi +.SH DESCRIPTION +.BR sigwaitinfo () +suspends execution of the calling thread until one of the signals in +.I set +is pending +(If one of the signals in +.I set +is already pending for the calling thread, +.BR sigwaitinfo () +will return immediately.) +.PP +.BR sigwaitinfo () +removes the signal from the set of pending +signals and returns the signal number as its function result. +If the +.I info +argument is not NULL, +then the buffer that it points to is used to return a structure of type +.I siginfo_t +(see +.BR sigaction (2)) +containing information about the signal. +.PP +If multiple signals in +.I set +are pending for the caller, the signal that is retrieved by +.BR sigwaitinfo () +is determined according to the usual ordering rules; see +.BR signal (7) +for further details. +.PP +.BR sigtimedwait () +operates in exactly the same way as +.BR sigwaitinfo () +except that it has an additional argument, +.IR timeout , +which specifies the interval for which +the thread is suspended waiting for a signal. +(This interval will be rounded up to the system clock granularity, +and kernel scheduling delays mean that the interval +may overrun by a small amount.) +This argument is a +.BR timespec (3) +structure. +.PP +If both fields of this structure are specified as 0, a poll is performed: +.BR sigtimedwait () +returns immediately, either with information about a signal that +was pending for the caller, or with an error +if none of the signals in +.I set +was pending. +.SH RETURN VALUE +On success, both +.BR sigwaitinfo () +and +.BR sigtimedwait () +return a signal number (i.e., a value greater than zero). +On failure both calls return \-1, with +.I errno +set to indicate the error. +.SH ERRORS +.TP +.B EAGAIN +No signal in +.I set +became pending within the +.I timeout +period specified to +.BR sigtimedwait (). +.TP +.B EINTR +The wait was interrupted by a signal handler; see +.BR signal (7). +(This handler was for a signal other than one of those in +.IR set .) +.TP +.B EINVAL +.I timeout +was invalid. +.SH VERSIONS +.SS C library/kernel differences +On Linux, +.BR sigwaitinfo () +is a library function implemented on top of +.BR sigtimedwait (). +.PP +The glibc wrapper functions for +.BR sigwaitinfo () +and +.BR sigtimedwait () +silently ignore attempts to wait for the two real-time signals that +are used internally by the NPTL threading implementation. +See +.BR nptl (7) +for details. +.PP +The original Linux system call was named +.BR sigtimedwait (). +However, with the addition of real-time signals in Linux 2.2, +the fixed-size, 32-bit +.I sigset_t +type supported by that system call was no longer fit for purpose. +Consequently, a new system call, +.BR rt_sigtimedwait (), +was added to support an enlarged +.I sigset_t +type. +The new system call takes a fourth argument, +.IR "size_t sigsetsize" , +which specifies the size in bytes of the signal set in +.IR set . +This argument is currently required to have the value +.I sizeof(sigset_t) +(or the error +.B EINVAL +results). +The glibc +.BR sigtimedwait () +wrapper function hides these details from us, transparently calling +.BR rt_sigtimedwait () +when the kernel provides it. +.\" +.SH STANDARDS +POSIX.1-2008. +.SH HISTORY +POSIX.1-2001. +.SH NOTES +In normal usage, the calling program blocks the signals in +.I set +via a prior call to +.BR sigprocmask (2) +(so that the default disposition for these signals does not occur if they +become pending between successive calls to +.BR sigwaitinfo () +or +.BR sigtimedwait ()) +and does not establish handlers for these signals. +In a multithreaded program, +the signal should be blocked in all threads, in order to prevent +the signal being treated according to its default disposition in +a thread other than the one calling +.BR sigwaitinfo () +or +.BR sigtimedwait ()). +.PP +The set of signals that is pending for a given thread is the +union of the set of signals that is pending specifically for that thread +and the set of signals that is pending for the process as a whole (see +.BR signal (7)). +.PP +Attempts to wait for +.B SIGKILL +and +.B SIGSTOP +are silently ignored. +.PP +If multiple threads of a process are blocked +waiting for the same signal(s) in +.BR sigwaitinfo () +or +.BR sigtimedwait (), +then exactly one of the threads will actually receive the +signal if it becomes pending for the process as a whole; +which of the threads receives the signal is indeterminate. +.PP +.BR sigwaitinfo () +or +.BR sigtimedwait (), +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. +.PP +POSIX leaves the meaning of a NULL value for the +.I timeout +argument of +.BR sigtimedwait () +unspecified, permitting the possibility that this has the same meaning +as a call to +.BR sigwaitinfo (), +and indeed this is what is done on Linux. +.SH SEE ALSO +.BR kill (2), +.BR sigaction (2), +.BR signal (2), +.BR signalfd (2), +.BR sigpending (2), +.BR sigprocmask (2), +.BR sigqueue (3), +.BR sigsetops (3), +.BR sigwait (3), +.BR timespec (3), +.BR signal (7), +.BR time (7) |