Debian Codegraph @

upstream/debian-unstable/man3/getcontext.3

raw
1 '\" t
2 .\" Copyright 2001, Andries E. Brouwer <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH getcontext 3 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 getcontext, setcontext \- get or set the user context
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .B #include <ucontext.h>
16 .P
17 .BI "int getcontext(ucontext_t *" ucp );
18 .BI "int setcontext(const ucontext_t *" ucp );
19 .fi
20 .SH DESCRIPTION
21 In a System V-like environment, one has the two types
22 .I mcontext_t
23 and
24 .I ucontext_t
25 defined in
26 .I <ucontext.h>
27 and the four functions
28 .BR getcontext (),
29 .BR setcontext (),
30 .BR makecontext (3),
31 and
32 .BR swapcontext (3)
33 that allow user-level context switching between multiple
34 threads of control within a process.
35 .P
36 The
37 .I mcontext_t
38 type is machine-dependent and opaque.
39 The
40 .I ucontext_t
41 type is a structure that has at least
42 the following fields:
43 .P
44 .in +4n
45 .EX
46 typedef struct ucontext_t {
47 struct ucontext_t *uc_link;
48 sigset_t uc_sigmask;
49 stack_t uc_stack;
50 mcontext_t uc_mcontext;
51 ...
52 } ucontext_t;
53 .EE
54 .in
55 .P
56 with
57 .I sigset_t
58 and
59 .I stack_t
60 defined in
61 .IR <signal.h> .
62 Here
63 .I uc_link
64 points to the context that will be resumed
65 when the current context terminates (in case the current context
66 was created using
67 .BR makecontext (3)),
68 .I uc_sigmask
69 is the
70 set of signals blocked in this context (see
71 .BR sigprocmask (2)),
72 .I uc_stack
73 is the stack used by this context (see
74 .BR sigaltstack (2)),
75 and
76 .I uc_mcontext
77 is the
78 machine-specific representation of the saved context,
79 that includes the calling thread's machine registers.
80 .P
81 The function
82 .BR getcontext ()
83 initializes the structure
84 pointed to by
85 .I ucp
86 to the currently active context.
87 .P
88 The function
89 .BR setcontext ()
90 restores the user context
91 pointed to by
92 .IR ucp .
93 A successful call does not return.
94 The context should have been obtained by a call of
95 .BR getcontext (),
96 or
97 .BR makecontext (3),
98 or received as the third argument to a signal
99 handler (see the discussion of the
100 .B SA_SIGINFO
101 flag in
102 .BR sigaction (2)).
103 .P
104 If the context was obtained by a call of
105 .BR getcontext (),
106 program execution continues as if this call just returned.
107 .P
108 If the context was obtained by a call of
109 .BR makecontext (3),
110 program execution continues by a call to the function
111 .I func
112 specified as the second argument of that call to
113 .BR makecontext (3).
114 When the function
115 .I func
116 returns, we continue with the
117 .I uc_link
118 member of the structure
119 .I ucp
120 specified as the
121 first argument of that call to
122 .BR makecontext (3).
123 When this member is NULL, the thread exits.
124 .P
125 If the context was obtained by a call to a signal handler,
126 then old standard text says that "program execution continues with the
127 program instruction following the instruction interrupted
128 by the signal".
129 However, this sentence was removed in SUSv2,
130 and the present verdict is "the result is unspecified".
131 .SH RETURN VALUE
132 When successful,
133 .BR getcontext ()
134 returns 0 and
135 .BR setcontext ()
136 does not return.
137 On error, both return \-1 and set
138 .I errno
139 to indicate the error.
140 .SH ERRORS
141 None defined.
142 .SH ATTRIBUTES
143 For an explanation of the terms used in this section, see
144 .BR attributes (7).
145 .TS
146 allbox;
147 lbx lb lb
148 l l l.
149 Interface Attribute Value
150 T{
151 .na
152 .nh
153 .BR getcontext (),
154 .BR setcontext ()
155 T} Thread safety MT-Safe race:ucp
156 .TE
157 .SH STANDARDS
158 None.
159 .SH HISTORY
160 SUSv2, POSIX.1-2001.
161 .P
162 POSIX.1-2008 removes these functions,
163 citing portability issues, and
164 recommending that applications be rewritten to use POSIX threads instead.
165 .SH NOTES
166 The earliest incarnation of this mechanism was the
167 .BR setjmp (3)/\c
168 .BR longjmp (3)
169 mechanism.
170 Since that does not define
171 the handling of the signal context, the next stage was the
172 .BR sigsetjmp (3)/\c
173 .BR siglongjmp (3)
174 pair.
175 The present mechanism gives much more control.
176 On the other hand,
177 there is no easy way to detect whether a return from
178 .BR getcontext ()
179 is from the first call, or via a
180 .BR setcontext ()
181 call.
182 The user has to invent their own bookkeeping device, and a register
183 variable won't do since registers are restored.
184 .P
185 When a signal occurs, the current user context is saved and
186 a new context is created by the kernel for the signal handler.
187 Do not leave the handler using
188 .BR longjmp (3):
189 it is undefined what would happen with contexts.
190 Use
191 .BR siglongjmp (3)
192 or
193 .BR setcontext ()
194 instead.
195 .SH SEE ALSO
196 .BR sigaction (2),
197 .BR sigaltstack (2),
198 .BR sigprocmask (2),
199 .BR longjmp (3),
200 .BR makecontext (3),
201 .BR sigsetjmp (3),
202 .BR signal (7)