diff options
Diffstat (limited to 'man/man3/setjmp.3')
| -rw-r--r-- | man/man3/setjmp.3 | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/man/man3/setjmp.3 b/man/man3/setjmp.3 new file mode 100644 index 000000000..2319feb47 --- /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 (date) "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) |