1 .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .TH GETCONTEXT 3 2021-03-22 "Linux" "Linux Programmer's Manual"
7 getcontext, setcontext \- get or set the user context
10 .RI ( libc ", " \-lc )
13 .B #include <ucontext.h>
15 .BI "int getcontext(ucontext_t *" ucp );
16 .BI "int setcontext(const ucontext_t *" ucp );
19 In a System V-like environment, one has the two types
25 and the four functions
31 that allow user-level context switching between multiple
32 threads of control within a process.
36 type is machine-dependent and opaque.
39 type is a structure that has at least
44 typedef struct ucontext_t {
45 struct ucontext_t *uc_link;
48 mcontext_t uc_mcontext;
62 points to the context that will be resumed
63 when the current context terminates (in case the current context
68 set of signals blocked in this context (see
71 is the stack used by this context (see
76 machine-specific representation of the saved context,
77 that includes the calling thread's machine registers.
81 initializes the structure
84 to the currently active context.
88 restores the user context
91 A successful call does not return.
92 The context should have been obtained by a call of
96 or received as the third argument to a signal
97 handler (see the discussion of the
102 If the context was obtained by a call of
104 program execution continues as if this call just returned.
106 If the context was obtained by a call of
108 program execution continues by a call to the function
110 specified as the second argument of that call to
114 returns, we continue with the
116 member of the structure
119 first argument of that call to
121 When this member is NULL, the thread exits.
123 If the context was obtained by a call to a signal handler,
124 then old standard text says that "program execution continues with the
125 program instruction following the instruction interrupted
127 However, this sentence was removed in SUSv2,
128 and the present verdict is "the result is unspecified".
135 On error, both return \-1 and set
137 to indicate the error.
141 For an explanation of the terms used in this section, see
149 Interface Attribute Value
153 T} Thread safety MT-Safe race:ucp
160 POSIX.1-2008 removes the specification of
162 citing portability issues, and
163 recommending that applications be rewritten to use POSIX threads instead.
165 The earliest incarnation of this mechanism was the
166 .BR setjmp (3)/ longjmp (3)
168 Since that does not define
169 the handling of the signal context, the next stage was the
170 .BR sigsetjmp (3)/ siglongjmp (3)
172 The present mechanism gives much more control.
174 there is no easy way to detect whether a return from
176 is from the first call, or via a
179 The user has to invent their own bookkeeping device, and a register
180 variable won't do since registers are restored.
182 When a signal occurs, the current user context is saved and
183 a new context is created by the kernel for the signal handler.
184 Do not leave the handler using
186 it is undefined what would happen with contexts.