Debian Codegraph @

upstream/debian-trixie/man3/makecontext.3

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