Merging upstream version 6.8.

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

1 files changed, 332 insertions, 0 deletions

diff --git a/man/man3/setjmp.3 b/man/man3/setjmp.3
new file mode 100644
index 0000000..b42e0d2
--- /dev/null
+++ b/man/man3/setjmp.3
@@ -0,0 +1,332 @@
+'\" t
+.\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
+.\"
+.\" SPDX-License-Identifier: GPL-2.0-or-later
+.\"
+.TH setjmp 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+setjmp, sigsetjmp, longjmp, siglongjmp  \- performing a nonlocal goto
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <setjmp.h>
+.P
+.BI "int setjmp(jmp_buf " env );
+.BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs );
+.P
+.BI "[[noreturn]] void longjmp(jmp_buf " env ", int " val );
+.BI "[[noreturn]] void siglongjmp(sigjmp_buf " env ", int " val );
+.fi
+.P
+.RS -4
+Feature Test Macro Requirements for glibc (see
+.BR feature_test_macros (7)):
+.RE
+.P
+.BR setjmp ():
+see NOTES.
+.P
+.BR sigsetjmp ():
+.nf
+    _POSIX_C_SOURCE
+.fi
+.SH DESCRIPTION
+The functions described on this page are used for performing "nonlocal gotos":
+transferring execution from one function to a predetermined location
+in another function.
+The
+.BR setjmp ()
+function dynamically establishes the target to which control
+will later be transferred, and
+.BR longjmp ()
+performs the transfer of execution.
+.P
+The
+.BR setjmp ()
+function saves various information about the calling environment
+(typically, the stack pointer, the instruction pointer,
+possibly the values of other registers and the signal mask)
+in the buffer
+.I env
+for later use by
+.BR longjmp ().
+In this case,
+.BR setjmp ()
+returns 0.
+.P
+The
+.BR longjmp ()
+function uses the information saved in
+.I env
+to transfer control back to the point where
+.BR setjmp ()
+was called and to restore ("rewind") the stack to its state at the time of the
+.BR setjmp ()
+call.
+In addition, and depending on the implementation (see NOTES),
+the values of some other registers and the process signal mask
+may be restored to their state at the time of the
+.BR setjmp ()
+call.
+.P
+Following a successful
+.BR longjmp (),
+execution continues as if
+.BR setjmp ()
+had returned for a second time.
+This "fake" return can be distinguished from a true
+.BR setjmp ()
+call because the "fake" return returns the value provided in
+.IR val .
+If the programmer mistakenly passes the value 0 in
+.IR val ,
+the "fake" return will instead return 1.
+.SS sigsetjmp() and siglongjmp()
+.BR sigsetjmp ()
+and
+.BR siglongjmp ()
+also perform nonlocal gotos, but provide predictable handling of
+the process signal mask.
+.P
+If, and only if, the
+.I savesigs
+argument provided to
+.BR sigsetjmp ()
+is nonzero, the process's current signal mask is saved in
+.I env
+and will be restored if a
+.BR siglongjmp ()
+is later performed with this
+.IR env .
+.SH RETURN VALUE
+.BR setjmp ()
+and
+.BR sigsetjmp ()
+return 0 when called directly;
+on the "fake" return that occurs after
+.BR longjmp ()
+or
+.BR siglongjmp (),
+the nonzero value specified in
+.I val
+is returned.
+.P
+The
+.BR longjmp ()
+or
+.BR siglongjmp ()
+functions do not return.
+.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 setjmp (),
+.BR sigsetjmp ()
+T}	Thread safety	MT-Safe
+T{
+.na
+.nh
+.BR longjmp (),
+.BR siglongjmp ()
+T}	Thread safety	MT-Safe
+.TE
+.SH STANDARDS
+.TP
+.BR setjmp ()
+.TQ
+.BR longjmp ()
+C11, POSIX.1-2008.
+.TP
+.BR sigsetjmp ()
+.TQ
+.BR siglongjmp ()
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR setjmp ()
+.TQ
+.BR longjmp ()
+POSIX.1-2001, C89.
+.TP
+.BR sigsetjmp ()
+.TQ
+.BR siglongjmp ()
+POSIX.1-2001.
+.P
+POSIX does not specify whether
+.BR setjmp ()
+will save the signal mask
+(to be later restored during
+.BR longjmp ()).
+In System V it will not.
+In 4.3BSD it will, and there
+is a function
+.BR _setjmp ()
+that will not.
+The behavior under Linux depends on the glibc version
+and the setting of feature test macros.
+Before glibc 2.19,
+.BR setjmp ()
+follows the System V behavior by default,
+but the BSD behavior is provided if the
+.B _BSD_SOURCE
+feature test macro is explicitly defined
+.\" so that _FAVOR_BSD is triggered
+and none of
+.BR _POSIX_SOURCE ,
+.BR _POSIX_C_SOURCE ,
+.BR _XOPEN_SOURCE ,
+.\" .BR _XOPEN_SOURCE_EXTENDED ,
+.BR _GNU_SOURCE ,
+or
+.B _SVID_SOURCE
+is defined.
+Since glibc 2.19,
+.I <setjmp.h>
+exposes only the System V version of
+.BR setjmp ().
+Programs that need the BSD semantics should replace calls to
+.BR setjmp ()
+with calls to
+.BR sigsetjmp ()
+with a nonzero
+.I savesigs
+argument.
+.SH NOTES
+.BR setjmp ()
+and
+.BR longjmp ()
+can be useful for dealing with errors inside deeply nested function calls
+or to allow a signal handler to pass control to
+a specific point in the program,
+rather than returning to the point where the handler interrupted
+the main program.
+In the latter case,
+if you want to portably save and restore signal masks, use
+.BR sigsetjmp ()
+and
+.BR siglongjmp ().
+See also the discussion of program readability below.
+.SH CAVEATS
+The compiler may optimize variables into registers, and
+.BR longjmp ()
+may restore the values of other registers in addition to the
+stack pointer and program counter.
+Consequently, the values of automatic variables are unspecified
+after a call to
+.BR longjmp ()
+if they meet all the following criteria:
+.IP \[bu] 3
+they are local to the function that made the corresponding
+.BR setjmp ()
+call;
+.IP \[bu]
+their values are changed between the calls to
+.BR setjmp ()
+and
+.BR longjmp ();
+and
+.IP \[bu]
+they are not declared as
+.IR volatile .
+.P
+Analogous remarks apply for
+.BR siglongjmp ().
+.\"
+.SS Nonlocal gotos and program readability
+While it can be abused,
+the traditional C "goto" statement at least has the benefit that lexical cues
+(the goto statement and the target label)
+allow the programmer to easily perceive the flow of control.
+Nonlocal gotos provide no such cues: multiple
+.BR setjmp ()
+calls might employ the same
+.I jmp_buf
+variable so that the content of the variable may change
+over the lifetime of the application.
+Consequently, the programmer may be forced to perform detailed
+reading of the code to determine the dynamic target of a particular
+.BR longjmp ()
+call.
+(To make the programmer's life easier, each
+.BR setjmp ()
+call should employ a unique
+.I jmp_buf
+variable.)
+.P
+Adding further difficulty, the
+.BR setjmp ()
+and
+.BR longjmp ()
+calls may not even be in the same source code module.
+.P
+In summary, nonlocal gotos can make programs harder to understand
+and maintain, and an alternative should be used if possible.
+.\"
+.SS Undefined Behavior
+If the function which called
+.BR setjmp ()
+returns before
+.BR longjmp ()
+is called, the behavior is undefined.
+Some kind of subtle or unsubtle chaos is sure to result.
+.P
+If, in a multithreaded program, a
+.BR longjmp ()
+call employs an
+.I env
+buffer that was initialized by a call to
+.BR setjmp ()
+in a different thread, the behavior is undefined.
+.\"
+.\" The following statement appeared in versions up to POSIX.1-2008 TC1,
+.\" but is set to be removed in POSIX.1-2008 TC2:
+.\"
+.\"     According to POSIX.1, if a
+.\"     .BR longjmp ()
+.\"     call is performed from a nested signal handler
+.\"     (i.e., from a handler that was invoked in response to a signal that was
+.\"     generated while another signal was already in the process of being
+.\"     handled), the behavior is undefined.
+.P
+POSIX.1-2008 Technical Corrigendum 2 adds
+.\" http://austingroupbugs.net/view.php?id=516#c1195
+.BR longjmp ()
+and
+.BR siglongjmp ()
+to the list of async-signal-safe functions.
+However, the standard recommends avoiding the use of these functions
+from signal handlers and goes on to point out that
+if these functions are called from a signal handler that interrupted
+a call to a non-async-signal-safe function (or some equivalent,
+such as the steps equivalent to
+.BR exit (3)
+that occur upon a return from the initial call to
+.IR main ()),
+the behavior is undefined if the program subsequently makes a call to
+a non-async-signal-safe function.
+The only way of avoiding undefined behavior is to ensure one of the following:
+.IP \[bu] 3
+After long jumping from the signal handler,
+the program does not call any non-async-signal-safe functions
+and does not return from the initial call to
+.IR main ().
+.IP \[bu]
+Any signal whose handler performs a long jump must be blocked during
+.I every
+call to a non-async-signal-safe function and
+no non-async-signal-safe functions are called after
+returning from the initial call to
+.IR main ().
+.SH SEE ALSO
+.BR signal (7),
+.BR signal\-safety (7)