]>
Commit | Line | Data |
---|---|---|
c63539ff ML |
1 | .. |
2 | Copyright 1988-2022 Free Software Foundation, Inc. | |
3 | This is part of the GCC manual. | |
4 | For copying conditions, see the copyright.rst file. | |
5 | ||
6 | .. index:: nonlocal gotos | |
7 | ||
8 | .. _nonlocal-gotos: | |
9 | ||
10 | Nonlocal Gotos | |
11 | ************** | |
12 | ||
13 | GCC provides the built-in functions ``__builtin_setjmp`` and | |
14 | ``__builtin_longjmp`` which are similar to, but not interchangeable | |
15 | with, the C library functions ``setjmp`` and ``longjmp``. | |
16 | The built-in versions are used internally by GCC's libraries | |
17 | to implement exception handling on some targets. You should use the | |
18 | standard C library functions declared in ``<setjmp.h>`` in user code | |
19 | instead of the builtins. | |
20 | ||
21 | The built-in versions of these functions use GCC's normal | |
22 | mechanisms to save and restore registers using the stack on function | |
23 | entry and exit. The jump buffer argument :samp:`{buf}` holds only the | |
24 | information needed to restore the stack frame, rather than the entire | |
25 | set of saved register values. | |
26 | ||
27 | An important caveat is that GCC arranges to save and restore only | |
28 | those registers known to the specific architecture variant being | |
29 | compiled for. This can make ``__builtin_setjmp`` and | |
30 | ``__builtin_longjmp`` more efficient than their library | |
31 | counterparts in some cases, but it can also cause incorrect and | |
32 | mysterious behavior when mixing with code that uses the full register | |
33 | set. | |
34 | ||
35 | You should declare the jump buffer argument :samp:`{buf}` to the | |
36 | built-in functions as: | |
37 | ||
38 | .. code-block:: c++ | |
39 | ||
40 | #include <stdint.h> | |
41 | intptr_t buf[5]; | |
42 | ||
43 | .. function:: int __builtin_setjmp (intptr_t *buf) | |
44 | ||
45 | This function saves the current stack context in :samp:`{buf}`. | |
46 | ``__builtin_setjmp`` returns 0 when returning directly, | |
47 | and 1 when returning from ``__builtin_longjmp`` using the same | |
48 | :samp:`{buf}`. | |
49 | ||
50 | .. function:: void __builtin_longjmp (intptr_t *buf, int val) | |
51 | ||
52 | This function restores the stack context in :samp:`{buf}`, | |
53 | saved by a previous call to ``__builtin_setjmp``. After | |
54 | ``__builtin_longjmp`` is finished, the program resumes execution as | |
55 | if the matching ``__builtin_setjmp`` returns the value :samp:`{val}`, | |
56 | which must be 1. | |
57 | ||
58 | Because ``__builtin_longjmp`` depends on the function return | |
59 | mechanism to restore the stack context, it cannot be called | |
60 | from the same function calling ``__builtin_setjmp`` to | |
61 | initialize :samp:`{buf}`. It can only be called from a function called | |
3ed1b4ce | 62 | (directly or indirectly) from the function calling ``__builtin_setjmp``. |