Debian Codegraph @

upstream/debian-unstable/man3/makecontext.3

raw
1 '\" t
2 .\" Copyright 2001, Andries E. Brouwer <[email protected]>
3 .\" Copyright 2006, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH makecontext 3 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 makecontext, swapcontext \- manipulate user context
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <ucontext.h>
17 .P
18 .BI "void makecontext(ucontext_t *" ucp ", typeof(void (int " arg0 ", ...)) *" func ,
19 .BI " int " argc ", ...);"
20 .BI "int swapcontext(ucontext_t *restrict " oucp ,
21 .BI " const ucontext_t *restrict " ucp );
22 .fi
23 .SH DESCRIPTION
24 In a System V-like environment, one has the type
25 .I ucontext_t
26 (defined in
27 .I <ucontext.h>
28 and described in
29 .BR getcontext (3))
30 and the four functions
31 .BR getcontext (3),
32 .BR setcontext (3),
33 .BR makecontext (),
34 and
35 .BR swapcontext ()
36 that allow user-level context switching
37 between multiple threads of control within a process.
38 .P
39 The
40 .BR makecontext ()
41 function modifies the context pointed to
42 by
43 .I ucp
44 (which was obtained from a call to
45 .BR getcontext (3)).
46 Before invoking
47 .BR makecontext (),
48 the caller must allocate a new stack
49 for this context and assign its address to
50 .IR ucp\->uc_stack ,
51 and define a successor context and
52 assign its address to
53 .IR ucp\->uc_link .
54 .P
55 When this context is later activated (using
56 .BR setcontext (3)
57 or
58 .BR swapcontext ())
59 the function
60 .I func
61 is called,
62 and passed the series of integer
63 .RI ( int )
64 arguments that follow
65 .IR argc ;
66 the caller must specify the number of these arguments in
67 .IR argc .
68 When this function returns, the successor context is activated.
69 If the successor context pointer is NULL, the thread exits.
70 .P
71 The
72 .BR swapcontext ()
73 function saves the current context in
74 the structure pointed to by
75 .IR oucp ,
76 and then activates
77 the context pointed to by
78 .IR ucp .
79 .SH RETURN VALUE
80 When successful,
81 .BR swapcontext ()
82 does not return.
83 (But we may return later, in case
84 .I oucp
85 is activated,
86 in which case it looks like
87 .BR swapcontext ()
88 returns 0.)
89 On error,
90 .BR swapcontext ()
91 returns \-1 and sets
92 .I errno
93 to indicate the error.
94 .SH ERRORS
95 .TP
96 .B ENOMEM
97 Insufficient stack space left.
98 .SH ATTRIBUTES
99 For an explanation of the terms used in this section, see
100 .BR attributes (7).
101 .TS
102 allbox;
103 lb lb lbx
104 l l l.
105 Interface Attribute Value
106 T{
107 .na
108 .nh
109 .BR makecontext ()
110 T} Thread safety T{
111 .na
112 .nh
113 MT-Safe race:ucp
114 T}
115 T{
116 .na
117 .nh
118 .BR swapcontext ()
119 T} Thread safety T{
120 .na
121 .nh
122 MT-Safe race:oucp race:ucp
123 T}
124 .TE
125 .SH STANDARDS
126 None.
127 .SH HISTORY
128 glibc 2.1.
129 SUSv2, POSIX.1-2001.
130 Removed in POSIX.1-2008,
131 citing portability issues, and
132 recommending that applications be rewritten to use POSIX threads instead.
133 .SH NOTES
134 The interpretation of
135 .I ucp\->uc_stack
136 is just as in
137 .BR sigaltstack (2),
138 namely, this struct contains the start and length of a memory area
139 to be used as the stack, regardless of the direction of growth of
140 the stack.
141 Thus, it is not necessary for the user program to
142 worry about this direction.
143 .P
144 On architectures where
145 .I int
146 and pointer types are the same size
147 (e.g., x86-32, where both types are 32 bits),
148 you may be able to get away with passing pointers as arguments to
149 .BR makecontext ()
150 following
151 .IR argc .
152 However, doing this is not guaranteed to be portable,
153 is undefined according to the standards,
154 and won't work on architectures where pointers are larger than
155 .IR int s.
156 Nevertheless, starting with glibc 2.8, glibc makes some changes to
157 .BR makecontext (),
158 to permit this on some 64-bit architectures (e.g., x86-64).
159 .SH EXAMPLES
160 The example program below demonstrates the use of
161 .BR getcontext (3),
162 .BR makecontext (),
163 and
164 .BR swapcontext ().
165 Running the program produces the following output:
166 .P
167 .in +4n
168 .EX
169 .RB "$" " ./a.out"
170 main: swapcontext(&uctx_main, &uctx_func2)
171 func2: started
172 func2: swapcontext(&uctx_func2, &uctx_func1)
173 func1: started
174 func1: swapcontext(&uctx_func1, &uctx_func2)
175 func2: returning
176 func1: returning
177 main: exiting
178 .EE
179 .in
180 .SS Program source
181 \&
182 .\" SRC BEGIN (makecontext.c)
183 .EX
184 #include <err.h>
185 #include <stdio.h>
186 #include <stdlib.h>
187 #include <ucontext.h>
188 \&
189 static ucontext_t uctx_main, uctx_func1, uctx_func2;
190 \&
191 static void
192 func1(void)
193 {
194 printf("%s: started\[rs]n", __func__);
195 printf("%s: swapcontext(&uctx_func1, &uctx_func2)\[rs]n", __func__);
196 if (swapcontext(&uctx_func1, &uctx_func2) == \-1)
197 err(EXIT_FAILURE, "swapcontext");
198 printf("%s: returning\[rs]n", __func__);
199 }
200 \&
201 static void
202 func2(void)
203 {
204 printf("%s: started\[rs]n", __func__);
205 printf("%s: swapcontext(&uctx_func2, &uctx_func1)\[rs]n", __func__);
206 if (swapcontext(&uctx_func2, &uctx_func1) == \-1)
207 err(EXIT_FAILURE, "swapcontext");
208 printf("%s: returning\[rs]n", __func__);
209 }
210 \&
211 int
212 main(int argc, char *argv[])
213 {
214 char func1_stack[16384];
215 char func2_stack[16384];
216 \&
217 if (getcontext(&uctx_func1) == \-1)
218 err(EXIT_FAILURE, "getcontext");
219 uctx_func1.uc_stack.ss_sp = func1_stack;
220 uctx_func1.uc_stack.ss_size = sizeof(func1_stack);
221 uctx_func1.uc_link = &uctx_main;
222 makecontext(&uctx_func1, func1, 0);
223 \&
224 if (getcontext(&uctx_func2) == \-1)
225 err(EXIT_FAILURE, "getcontext");
226 uctx_func2.uc_stack.ss_sp = func2_stack;
227 uctx_func2.uc_stack.ss_size = sizeof(func2_stack);
228 /* Successor context is f1(), unless argc > 1 */
229 uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1;
230 makecontext(&uctx_func2, func2, 0);
231 \&
232 printf("%s: swapcontext(&uctx_main, &uctx_func2)\[rs]n", __func__);
233 if (swapcontext(&uctx_main, &uctx_func2) == \-1)
234 err(EXIT_FAILURE, "swapcontext");
235 \&
236 printf("%s: exiting\[rs]n", __func__);
237 exit(EXIT_SUCCESS);
238 }
239 .EE
240 .\" SRC END
241 .SH SEE ALSO
242 .BR sigaction (2),
243 .BR sigaltstack (2),
244 .BR sigprocmask (2),
245 .BR getcontext (3),
246 .BR sigsetjmp (3)