1 .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
2 .\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date. The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein. The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" 2006-08-02, mtk, Added example program
28 .TH MAKECONTEXT 3 2021-03-22 "GNU" "Linux Programmer's Manual"
30 makecontext, swapcontext \- manipulate user context
33 .B #include <ucontext.h>
35 .BI "void makecontext(ucontext_t *" ucp ", void (*" func ")(), int " argc \
37 .BI "int swapcontext(ucontext_t *restrict " oucp ,
38 .BI " const ucontext_t *restrict " ucp );
41 In a System V-like environment, one has the type
47 and the four functions
53 that allow user-level context switching
54 between multiple threads of control within a process.
58 function modifies the context pointed to
59 by \fIucp\fP (which was obtained from a call to
63 the caller must allocate a new stack
64 for this context and assign its address to \fIucp\->uc_stack\fP,
65 and define a successor context and
66 assign its address to \fIucp\->uc_link\fP.
68 When this context is later activated (using
72 the function \fIfunc\fP is called,
73 and passed the series of integer
77 the caller must specify the number of these arguments in
79 When this function returns, the successor context is activated.
80 If the successor context pointer is NULL, the thread exits.
84 function saves the current context in
85 the structure pointed to by \fIoucp\fP, and then activates the
86 context pointed to by \fIucp\fP.
91 (But we may return later, in case \fIoucp\fP is
92 activated, in which case it looks like
99 to indicate the error.
103 Insufficient stack space left.
108 are provided in glibc since version 2.1.
110 For an explanation of the terms used in this section, see
118 Interface Attribute Value
127 MT-Safe race:oucp race:ucp
135 POSIX.1-2008 removes the specifications of
139 citing portability issues, and
140 recommending that applications be rewritten to use POSIX threads instead.
142 The interpretation of \fIucp\->uc_stack\fP is just as in
144 namely, this struct contains the start and length of a memory area
145 to be used as the stack, regardless of the direction of growth of
147 Thus, it is not necessary for the user program to
148 worry about this direction.
150 On architectures where
152 and pointer types are the same size
153 (e.g., x86-32, where both types are 32 bits),
154 you may be able to get away with passing pointers as arguments to
158 However, doing this is not guaranteed to be portable,
159 is undefined according to the standards,
160 and won't work on architectures where pointers are larger than
162 Nevertheless, starting with version 2.8, glibc makes some changes to
164 to permit this on some 64-bit architectures (e.g., x86-64).
166 The example program below demonstrates the use of
171 Running the program produces the following output:
176 main: swapcontext(&uctx_main, &uctx_func2)
178 func2: swapcontext(&uctx_func2, &uctx_func1)
180 func1: swapcontext(&uctx_func1, &uctx_func2)
189 #include <ucontext.h>
193 static ucontext_t uctx_main, uctx_func1, uctx_func2;
195 #define handle_error(msg) \e
196 do { perror(msg); exit(EXIT_FAILURE); } while (0)
201 printf("func1: started\en");
202 printf("func1: swapcontext(&uctx_func1, &uctx_func2)\en");
203 if (swapcontext(&uctx_func1, &uctx_func2) == \-1)
204 handle_error("swapcontext");
205 printf("func1: returning\en");
211 printf("func2: started\en");
212 printf("func2: swapcontext(&uctx_func2, &uctx_func1)\en");
213 if (swapcontext(&uctx_func2, &uctx_func1) == \-1)
214 handle_error("swapcontext");
215 printf("func2: returning\en");
219 main(int argc, char *argv[])
221 char func1_stack[16384];
222 char func2_stack[16384];
224 if (getcontext(&uctx_func1) == \-1)
225 handle_error("getcontext");
226 uctx_func1.uc_stack.ss_sp = func1_stack;
227 uctx_func1.uc_stack.ss_size = sizeof(func1_stack);
228 uctx_func1.uc_link = &uctx_main;
229 makecontext(&uctx_func1, func1, 0);
231 if (getcontext(&uctx_func2) == \-1)
232 handle_error("getcontext");
233 uctx_func2.uc_stack.ss_sp = func2_stack;
234 uctx_func2.uc_stack.ss_size = sizeof(func2_stack);
235 /* Successor context is f1(), unless argc > 1 */
236 uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1;
237 makecontext(&uctx_func2, func2, 0);
239 printf("main: swapcontext(&uctx_main, &uctx_func2)\en");
240 if (swapcontext(&uctx_main, &uctx_func2) == \-1)
241 handle_error("swapcontext");
243 printf("main: exiting\en");