1 .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
2 .\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
23 .\" 2006-08-02, mtk, Added example program
25 .\" Japanese Version Copyright (c) 2001 NAKANO Takeo all rights reserved.
26 .\" Translated Sat Dec 15 2001 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
27 .\" Updated 2008-12-24, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v3.15
29 .TH MAKECONTEXT 3 2009-03-31 "GNU" "Linux Programmer's Manual"
31 .\"O makecontext, swapcontext \- manipulate user context
33 makecontext, swapcontext \- ¥æ¡¼¥¶¥³¥ó¥Æ¥¥¹¥È¤òÁàºî¤¹¤ë
36 .B #include <ucontext.h>
38 .BI "void makecontext(ucontext_t *" ucp ", void (*" func )(),
39 .BI "int " argc ", ...);"
41 .BI "int swapcontext(ucontext_t *" oucp ", ucontext_t *" ucp );
44 .\"O In a System V-like environment, one has the type \fIucontext_t\fP defined in
46 .\"O and the four functions
47 .\"O .BR getcontext (2),
48 .\"O .BR setcontext (2),
49 .\"O .BR makecontext ()
51 .\"O .BR swapcontext ()
52 .\"O that allow user-level context switching
53 .\"O between multiple threads of control within a process.
54 System V Ū¤Ê´Ä¶¤Ç¤Ï¡¢
55 \fBmcontext_t\fP ¤ª¤è¤Ó \fBucontext_t\fP ¤È¤¤¤¦ 2 ¤Ä¤Î·¿¤È¡¢
62 ¤ÇÄêµÁ¤µ¤ì¤Æ¤ª¤ê¡¢¤¢¤ë¥×¥í¥»¥¹ÆâÉô¤ÇÀ©¸æ²¼¤Ë¤¢¤ëÊ£¿ô¤Î¥¹¥ì¥Ã¥É´Ö¤Ç¡¢
63 ¥æ¡¼¥¶¥ì¥Ù¥ë¤Î¥³¥ó¥Æ¥¥¹¥ÈÀÚÂؤ¨¤¬¤Ç¤¤ë¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤ë¡£
65 .\"O For the type and the first two functions, see
66 .\"O .BR getcontext (2).
67 ¤³¤ì¤é¤Î·¿¤È¡¢ºÇ½é¤Î 2 ¤Ä¤Î´Ø¿ô¤Ë¤Ä¤¤¤Æ¤Ï¡¢
72 .\"O .BR makecontext ()
73 .\"O function modifies the context pointed to
74 .\"O by \fIucp\fP (which was obtained from a call to
75 .\"O .BR getcontext (2)).
77 .\"O .BR makecontext (),
78 .\"O the caller must allocate a new stack
79 .\"O for this context and assign its address to \fIucp\->uc_stack\fP,
80 .\"O and define a successor context and
81 .\"O assign its address to \fIucp\->uc_link\fP.
83 ´Ø¿ô¤Ï¡¢¥Ý¥¤¥ó¥¿ \fIucp\fP ¤¬»Ø¤¹¥³¥ó¥Æ¥¥¹¥È¤òÊѹ¹¤¹¤ë
86 ¸Æ¤Ó½Ð¤·¤ÇÆÀ¤é¤ì¤¿¤â¤Î¤Ç¤¢¤ë)¡£
88 ¤òµ¯Æ°¤¹¤ëÁ°¤Ë¤Ï¡¢¸Æ¤Ó½Ð¤·¼Ô¤Ï¡¢¤³¤Î¥³¥ó¥Æ¥¥¹¥ÈÍѤË
89 ¿·¤·¤¤¥¹¥¿¥Ã¥¯¤ò³ÎÊݤ·¡¢¤½¤Î¥¢¥É¥ì¥¹¤ò \fIucp\->uc_stack\fP ¤ËÂåÆþ¤·¡¢
90 ¤µ¤é¤Ë¸å·Ñ¤Î¥³¥ó¥Æ¥¥¹¥È¤òÄêµÁ¤·¡¢¤½¤Î¥¢¥É¥ì¥¹¤ò \fIucp\->uc_link\fP ¤Ë
91 ÂåÆþ¤·¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
93 .\"O When this context is later activated (using
94 .\"O .BR setcontext (2)
96 .\"O .BR swapcontext ())
97 .\"O the function \fIfunc\fP is called,
98 .\"O and passed the series of integer
100 .\"O arguments that follow
102 .\"O the caller must specify the number of these arguments in
104 .\"O When this function returns, the successor context is activated.
105 .\"O If the successor context pointer is NULL, the thread exits.
106 ¤³¤Î¥³¥ó¥Æ¥¥¹¥È¤¬¾Íè
111 ͸ú¤Ë¤µ¤ì¤ë¤È¡¢´Ø¿ô \fIfunc\fP ¤¬¸Æ¤Ð¤ì¡¢
116 °ú¤¿ô¤ÎÎó¤¬ÅϤµ¤ì¤ë¡£
119 ¤Ë¤³¤ì¤é¤Î°ú¤¿ô¤Î¸Ä¿ô¤ò»ØÄꤷ¤Ê¤±¤ì¤Ð¤Ê¤é¤Ê¤¤¡£
120 ¤³¤Î´Ø¿ô¤¬Ìá¤ë¤È¡¢¸å·Ñ¤Î¥³¥ó¥Æ¥¥¹¥È¤¬Í¸ú¤Ë¤Ê¤ë¡£
121 ¸å·Ñ¥³¥ó¥Æ¥¥¹¥È¤Î¥Ý¥¤¥ó¥¿¤¬ NULL ¤Î¾ì¹ç¡¢¤½¤Î¥¹¥ì¥Ã¥É¤¬½ªÎ»¤¹¤ë¡£
124 .\"O .BR swapcontext ()
125 .\"O function saves the current context in
126 .\"O the structure pointed to by \fIoucp\fP, and then activates the
127 .\"O context pointed to by \fIucp\fP.
129 ´Ø¿ô¤Ï¸½ºß¤Î¥³¥ó¥Æ¥¥¹¥È¤ò
130 ¥Ý¥¤¥ó¥¿ \fIoucp\fP ¤¬»Ø¤¹¹½Â¤ÂΤËÊݸ¤·¡¢
131 ¥Ý¥¤¥ó¥¿ \fIucp\fP ¤¬»Ø¤¹¥³¥ó¥Æ¥¥¹¥È¤ò͸ú¤Ë¤¹¤ë¡£
132 .\"O .SH "RETURN VALUE"
134 .\"O When successful,
135 .\"O .BR swapcontext ()
136 .\"O does not return.
137 .\"O (But we may return later, in case \fIoucp\fP is
138 .\"O activated, in which case it looks like
139 .\"O .BR swapcontext ()
142 .\"O .BR swapcontext ()
144 .\"O sets \fIerrno\fP appropriately.
148 (¤·¤«¤·¸å¤Ë \fIoucp\fP ¤¬Í¸ú¤Ë¤Ê¤Ã¤¿¾ì¹ç¤Ë¤ÏÊ֤뤳¤È¤¬¤¢¤ë¡£
151 ¤Ï 0 ¤òÊÖ¤¹¤è¤¦¤Ë¸«¤¨¤ë¡£)
155 \fIerrno\fP ¤ò¥¨¥é¡¼¤Ë±þ¤¸¤ÆÀßÄꤹ¤ë¡£
160 .\"O Insufficient stack space left.
161 ¥¹¥¿¥Ã¥¯¤Ë³ä¤êÅö¤Æ¤ë¶õ´Ö¤¬»Ä¤Ã¤Æ¤¤¤Ê¤¤¡£
164 .\"O .BR makecontext ()
166 .\"O .BR swapcontext ()
167 .\"O are provided in glibc since version 2.1.
171 ¤Ï¡¢¥Ð¡¼¥¸¥ç¥ó 2.1 °Ê¹ß¤Î glibc ¤ÇÄ󶡤µ¤ì¤Æ¤¤¤ë¡£
172 .\"O .SH "CONFORMING TO"
175 .\"O POSIX.1-2008 removes the specifications of
176 .\"O .BR makecontext ()
178 .\"O .BR swapcontext (),
179 .\"O citing portability issues, and
180 .\"O recommending that applications be rewritten to use POSIX threads instead.
181 POSIX.1-2008 ¤Ç¤Ï¡¢°Ü¿¢À¤ÎÌäÂ꤫¤é
185 ¤Î»ÅÍͤ¬ºï½ü¤µ¤ì¤Æ¤¤¤ë¡£
186 Âå¤ï¤ê¤Ë¡¢¥¢¥×¥ê¥±¡¼¥·¥ç¥ó¤ò POSIX ¥¹¥ì¥Ã¥É¤ò»È¤Ã¤Æ½ñ¤Ä¾¤¹¤³¤È¤¬
190 .\"O The interpretation of \fIucp\->uc_stack\fP is just as in
191 .\"O .BR sigaltstack (2),
192 .\"O namely, this struct contains the start and length of a memory area
193 .\"O to be used as the stack, regardless of the direction of growth of
195 .\"O Thus, it is not necessary for the user program to
196 .\"O worry about this direction.
197 \fIucp\->uc_stack\fP ¤Î²ò¼á¤Ï
200 ¤¹¤Ê¤ï¤Á¤³¤Î¹½Â¤ÂΤˤϡ¢
201 ¥¹¥¿¥Ã¥¯¤È¤·¤ÆÍѤ¤¤é¤ì¤ë¥á¥â¥êÎΰè¤Î³«»Ï¥¢¥É¥ì¥¹¤ÈŤµ¤¬´Þ¤Þ¤ì¡¢
202 ¤³¤ì¤Ï¥¹¥¿¥Ã¥¯¤¬¿¤Ó¤ëÊý¸þ¤¬¤É¤Á¤é¤Ç¤¢¤ë¤«¤Ë¤Ï´Ø·¸¤·¤Ê¤¤¡£
203 ¤·¤¿¤¬¤Ã¤Æ¡¢¥æ¡¼¥¶¥×¥í¥°¥é¥à¤Ï¤³¤Î·ï¤Ë¤Ä¤¤¤Æ¤Ï¿´ÇÛ¤·¤Ê¤¯¤Æ¤è¤¤¡£
205 .\"O On architectures where
207 .\"O and pointer types are the same size
208 .\"O (e.g., x86-32, where both types are 32 bits),
209 .\"O you may be able to get away with passing pointers as arguments to
210 .\"O .BR makecontext ()
213 .\"O However, doing this is not guaranteed to be portable,
214 .\"O is undefined according to the standards,
215 .\"O and won't work on architectures where pointers are larger than
217 .\"O Nevertheless, starting with version 2.8, glibc makes some changes to
218 .\"O .BR makecontext (3),
219 .\"O to permit this on some 64-bit architectures (e.g., x86-64).
221 ¤È¥Ý¥¤¥ó¥¿·¿¤¬Æ±¤¸Â礤µ¤Ç¤¢¤ë¥¢¡¼¥¥Æ¥¯¥Á¥ã¤Ç¤Ï
222 (x86-32 ¤Ï¤½¤ÎÎã¤Ç¤¢¤ê¡¢Î¾Êý¤Î·¿¤È¤â 32 ¥Ó¥Ã¥È¤Ç¤¢¤ë)¡¢
226 °Ê¹ß¤Î°ú¤¿ô¤È¤·¤Æ¥Ý¥¤¥ó¥¿¤òÅϤ·¤Æ¤â¤¦¤Þ¤¯Æ°¤¯¤«¤â¤·¤ì¤Ê¤¤¡£
227 ¤·¤«¤·¤Ê¤¬¤é¡¢¤³¤Î¤è¤¦¤Ë¤¹¤ë¤È¡¢°Ü¿¢À¤ÏÊݾڤµ¤ì¤º¡¢
228 ɸ½à¤Ë½¾¤¨¤ÐÆ°ºî¤Ï̤ÄêµÁ¤Ç¤¢¤ê¡¢¥Ý¥¤¥ó¥¿¤¬
230 ¤è¤ê¤âÂ礤¤¥¢¡¼¥¥Æ¥¯¥Á¥ã¤Ç¤ÏÀµ¤·¤¯Æ°ºî¤·¤Ê¤¤¤³¤È¤À¤í¤¦¡£
231 ¤½¤ì¤Ë¤â´Ø¤ï¤é¤º¡¢¥Ð¡¼¥¸¥ç¥ó 2.8 °Ê¹ß¤Î glibc ¤Ç¤Ï¡¢
233 ¤ËÊѹ¹¤¬¹Ô¤ï¤ì¡¢(x86-64 ¤Ê¤É¤Î) ¤¤¤¯¤Ä¤«¤Î 64 ¥Ó¥Ã¥È¥¢¡¼¥¥Æ¥¯¥Á¥ã¤Ç
234 °ú¤¿ô¤È¤·¤Æ¥Ý¥¤¥ó¥¿¤òÅϤ¹¤³¤È¤¬¤Ç¤¤ë¤è¤¦¤Ë¤Ê¤Ã¤Æ¤¤¤ë¡£
238 .\"O The example program below demonstrates the use of
239 .\"O .BR getcontext (2),
240 .\"O .BR makecontext (),
242 .\"O .BR swapcontext ().
243 .\"O Running the program produces the following output:
244 °Ê²¼¤Î¥µ¥ó¥×¥ë¡¦¥×¥í¥°¥é¥à¤Ï¡¢
248 ¤Î»ÈÍÑÊýË¡¤ÎÎã¤ò¼¨¤¹¤â¤Î¤Ç¤¢¤ë¡£
249 ¤³¤Î¥×¥í¥°¥é¥à¤ò¼Â¹Ô¤¹¤ë¤È¡¢°Ê²¼¤Î¤è¤¦¤Ê½ÐÎϤ¬ÆÀ¤é¤ì¤ë:
254 main: swapcontext(&uctx_main, &uctx_func2)
256 func2: swapcontext(&uctx_func2, &uctx_func1)
258 func1: swapcontext(&uctx_func1, &uctx_func2)
264 .\"O .SS Program source
265 .SS ¥×¥í¥°¥é¥à¤Î¥½¡¼¥¹
268 #include <ucontext.h>
272 static ucontext_t uctx_main, uctx_func1, uctx_func2;
274 #define handle_error(msg) \\
275 do { perror(msg); exit(EXIT_FAILURE); } while (0)
280 printf("func1: started\\n");
281 printf("func1: swapcontext(&uctx_func1, &uctx_func2)\\n");
282 if (swapcontext(&uctx_func1, &uctx_func2) == \-1)
283 handle_error("swapcontext");
284 printf("func1: returning\\n");
290 printf("func2: started\\n");
291 printf("func2: swapcontext(&uctx_func2, &uctx_func1)\\n");
292 if (swapcontext(&uctx_func2, &uctx_func1) == \-1)
293 handle_error("swapcontext");
294 printf("func2: returning\\n");
298 main(int argc, char *argv[])
300 char func1_stack[16384];
301 char func2_stack[16384];
303 if (getcontext(&uctx_func1) == \-1)
304 handle_error("getcontext");
305 uctx_func1.uc_stack.ss_sp = func1_stack;
306 uctx_func1.uc_stack.ss_size = sizeof(func1_stack);
307 uctx_func1.uc_link = &uctx_main;
308 makecontext(&uctx_func1, func1, 0);
310 if (getcontext(&uctx_func2) == \-1)
311 handle_error("getcontext");
312 uctx_func2.uc_stack.ss_sp = func2_stack;
313 uctx_func2.uc_stack.ss_size = sizeof(func2_stack);
314 /* Successor context is f1(), unless argc > 1 */
315 uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1;
316 makecontext(&uctx_func2, func2, 0);
318 printf("main: swapcontext(&uctx_main, &uctx_func2)\\n");
319 if (swapcontext(&uctx_main, &uctx_func2) == \-1)
320 handle_error("swapcontext");
322 printf("main: exiting\\n");