From 3af6d22bb3850ab2bac67287e3a3d3b0e32868e5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 15 Apr 2024 21:41:07 +0200 Subject: Merging upstream version 6.7. Signed-off-by: Daniel Baumann --- man2/sigaction.2 | 111 +++++++++++++++++++++++++++++-------------------------- 1 file changed, 59 insertions(+), 52 deletions(-) (limited to 'man2/sigaction.2') diff --git a/man2/sigaction.2 b/man2/sigaction.2 index 8edde42..bbe4d5a 100644 --- a/man2/sigaction.2 +++ b/man2/sigaction.2 @@ -25,7 +25,7 @@ .\" 2015-01-17, Kees Cook .\" Added notes on ptrace SIGTRAP and SYS_SECCOMP. .\" -.TH sigaction 2 2023-05-03 "Linux man-pages 6.05.01" +.TH sigaction 2 2024-02-25 "Linux man-pages 6.7" .SH NAME sigaction, rt_sigaction \- examine and change a signal action .SH LIBRARY @@ -34,22 +34,22 @@ Standard C library .SH SYNOPSIS .nf .B #include -.PP +.P .BI "int sigaction(int " signum , .BI " const struct sigaction *_Nullable restrict " act , .BI " struct sigaction *_Nullable restrict " oldact ); .fi -.PP +.P .RS -4 Feature Test Macro Requirements for glibc (see .BR feature_test_macros (7)): .RE -.PP +.P .BR sigaction (): .nf _POSIX_C_SOURCE .fi -.PP +.P .IR siginfo_t : .nf _POSIX_C_SOURCE >= 199309L @@ -62,13 +62,13 @@ receipt of a specific signal. (See .BR signal (7) for an overview of signals.) -.PP +.P .I signum specifies the signal and can be any valid signal except .B SIGKILL and .BR SIGSTOP . -.PP +.P If .I act is non-NULL, the new action for signal @@ -79,11 +79,11 @@ If .I oldact is non-NULL, the previous action is saved in .IR oldact . -.PP +.P The .I sigaction structure is defined as something like: -.PP +.P .in +4n .EX struct sigaction { @@ -95,12 +95,12 @@ struct sigaction { }; .EE .in -.PP +.P On some architectures a union is involved: do not assign to both .I sa_handler and .IR sa_sigaction . -.PP +.P The .I sa_restorer field is not intended for application use. @@ -109,7 +109,7 @@ field is not intended for application use. field.) Some further details of the purpose of this field can be found in .BR sigreturn (2). -.PP +.P .I sa_handler specifies the action to be associated with .I signum @@ -123,7 +123,7 @@ to ignore this signal. .IP \[bu] A pointer to a signal handling function. This function receives the signal number as its only argument. -.PP +.P If .B SA_SIGINFO is specified in @@ -135,7 +135,7 @@ then specifies the signal-handling function for .IR signum . This function receives three arguments, as described below. -.PP +.P .I sa_mask specifies a mask of signals which should be blocked (i.e., added to the signal mask of the thread in which @@ -145,7 +145,7 @@ In addition, the signal which triggered the handler will be blocked, unless the .B SA_NODEFER flag is used. -.PP +.P .I sa_flags specifies a set of flags which modify the behavior of the signal. It is formed by the bitwise OR of zero or more of the following: @@ -292,7 +292,7 @@ the signal handler address is passed via the .I act.sa_sigaction field. This handler takes three arguments, as follows: -.PP +.P .in +4n .EX void @@ -302,7 +302,7 @@ handler(int sig, siginfo_t *info, void *ucontext) } .EE .in -.PP +.P These three arguments are as follows .TP .I sig @@ -329,11 +329,11 @@ structure can be found in and .BR signal (7). Commonly, the handler function doesn't make any use of the third argument. -.PP +.P The .I siginfo_t data type is a structure with the following fields: -.PP +.P .in +4n .EX siginfo_t { @@ -380,7 +380,7 @@ siginfo_t { } .EE .in -.PP +.P .IR si_signo ", " si_errno " and " si_code are defined for all signals. .RI ( si_errno @@ -595,13 +595,13 @@ event, will contain .B SIGTRAP and have the ptrace event in the high byte: -.PP +.P .in +4n .EX (SIGTRAP | PTRACE_EVENT_foo << 8). .EE .in -.PP +.P For a .RB non- ptrace (2) event, the values that can appear in @@ -624,12 +624,12 @@ or .IP \[bu] .B _POSIX_C_SOURCE with the value 200809L or greater. -.PP +.P For the .B TRAP_* constants, the symbol definitions are provided only in the first two cases. Before glibc 2.20, no feature test macros were required to obtain these symbols. -.PP +.P For a regular signal, the following list shows the values which can be placed in .I si_code @@ -672,7 +672,7 @@ or .\" It appears to have been an idea that was tried during 2.5.6 .\" through to Linux 2.5.24 and then was backed out. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -704,7 +704,7 @@ Coprocessor error. .B ILL_BADSTK Internal stack error. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -736,7 +736,7 @@ Floating-point invalid operation. .B FPE_FLTSUB Subscript out of range. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -762,7 +762,7 @@ See The protection key which applied to this access is available via .IR si_pkey . .RE -.PP +.P The following values can be placed in .I si_code for a @@ -785,7 +785,7 @@ Hardware memory error consumed on a machine check; action required. .BR BUS_MCEERR_AO " (since Linux 2.6.32)" Hardware memory error detected in process but not consumed; action optional. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -805,7 +805,7 @@ Process taken branch trap. .BR TRAP_HWBKPT " (since Linux 2.4, IA64 only)" Hardware breakpoint/watchpoint. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -831,7 +831,7 @@ Child has stopped. .BR CLD_CONTINUED " (since Linux 2.6.9)" Stopped child has continued. .RE -.PP +.P The following values can be placed in .I si_code for a @@ -857,7 +857,7 @@ High priority input available. .B POLL_HUP Device disconnected. .RE -.PP +.P The following value can be placed in .I si_code for a @@ -884,7 +884,7 @@ However, historically, a second .BR sigaction () call would typically leave those bits set in .IR oldact\->sa_flags . -.PP +.P This means that support for new flags cannot be detected simply by testing for a flag in .IR sa_flags , @@ -892,7 +892,7 @@ and a program must test that .B SA_UNSUPPORTED has been cleared before relying on the contents of .IR sa_flags . -.PP +.P Since the behavior of the signal handler cannot be guaranteed unless the check passes, it is wise to either block the affected signal @@ -901,12 +901,12 @@ or where this is not possible, for example if the signal is synchronous, to issue the second .BR sigaction () in the signal handler itself. -.PP +.P In kernels that do not support a specific flag, the kernel's behavior is as if the flag was not set, even if the flag was set in .IR act\->sa_flags . -.PP +.P The flags .BR SA_NOCLDSTOP , .BR SA_NOCLDWAIT , @@ -922,7 +922,7 @@ because they were introduced before Linux 5.11. However, in general, programs may assume that these flags are supported, since they have all been supported since Linux 2.6, which was released in the year 2003. -.PP +.P See EXAMPLES below for a demonstration of the use of .BR SA_UNSUPPORTED . .SH RETURN VALUE @@ -953,7 +953,7 @@ used internally by the NPTL threading implementation. See .BR nptl (7) for details. -.PP +.P On architectures where the signal trampoline resides in the C library, the glibc wrapper function for .BR sigaction () @@ -966,7 +966,7 @@ flag in the field. See .BR sigreturn (2). -.PP +.P The original Linux system call was named .BR sigaction (). However, with the addition of real-time signals in Linux 2.2, @@ -999,7 +999,7 @@ POSIX.1-2008. .SH HISTORY POSIX.1-2001, SVr4. .\" SVr4 does not document the EINTR condition. -.PP +.P POSIX.1-1990 disallowed setting the action for .B SIGCHLD to @@ -1016,27 +1016,34 @@ terminated children do not become zombies is to catch the signal and perform a .BR wait (2) or similar. -.PP +.P POSIX.1-1990 specified only .BR SA_NOCLDSTOP . POSIX.1-2001 added -.BR SA_NOCLDSTOP , .BR SA_NOCLDWAIT , .BR SA_NODEFER , .BR SA_ONSTACK , .BR SA_RESETHAND , .BR SA_RESTART , and -.BR SA_SIGINFO . +.B SA_SIGINFO +as XSI extensions. +POSIX.1-2008 moved +.BR SA_NODEFER , +.BR SA_RESETHAND , +.BR SA_RESTART , +and +.B SA_SIGINFO +to the base specifications. Use of these latter values in .I sa_flags may be less portable in applications intended for older UNIX implementations. -.PP +.P The .B SA_RESETHAND flag is compatible with the SVr4 flag of the same name. -.PP +.P The .B SA_NODEFER flag is compatible with the SVr4 flag of the same name under kernels @@ -1054,7 +1061,7 @@ During an .BR execve (2), the dispositions of handled signals are reset to the default; the dispositions of ignored signals are left unchanged. -.PP +.P According to POSIX, the behavior of a process is undefined after it ignores a .BR SIGFPE , @@ -1072,23 +1079,23 @@ signal. (Also dividing the most negative integer by \-1 may generate .BR SIGFPE .) Ignoring this signal might lead to an endless loop. -.PP +.P .BR sigaction () can be called with a NULL second argument to query the current signal handler. It can also be used to check whether a given signal is valid for the current machine by calling it with NULL second and third arguments. -.PP +.P It is not possible to block .BR SIGKILL " or " SIGSTOP (by specifying them in .IR sa_mask ). Attempts to do so are silently ignored. -.PP +.P See .BR sigsetops (3) for details on manipulating signal sets. -.PP +.P See .BR signal\-safety (7) for a list of the async-signal-safe functions that can be @@ -1119,7 +1126,7 @@ the kernel does not always provide meaningful values for all of the fields of the .I siginfo_t that are relevant for that signal. -.PP +.P Up to and including Linux 2.6.13, specifying .B SA_NODEFER in @@ -1140,7 +1147,7 @@ if is determined to be supported, and .B EXIT_FAILURE otherwise. -.PP +.P .\" SRC BEGIN (sigaction.c) .EX #include -- cgit v1.2.3