makecontext(3)

1MAKECONTEXT(3)             Linux Programmer's Manual            MAKECONTEXT(3)
2
3
4

NAME

6       makecontext, swapcontext - manipulate user context
7

SYNOPSIS

9       #include <ucontext.h>
10
11       void makecontext(ucontext_t *ucp, void *func(), int argc, ...);
12       int swapcontext(ucontext_t *oucp, ucontext_t *ucp);
13

DESCRIPTION

15       In  a System V-like environment, one has the type ucontext_t defined in
16       <ucontext.h> and the four functions getcontext(),  setcontext(),  make‐
17       context()  and  swapcontext()  that  allow user-level context switching
18       between multiple threads of control within a process.
19
20       For the type and the first two functions, see getcontext(2).
21
22       The makecontext() function modifies  the  context  pointed  to  by  ucp
23       (which  was  obtained  from  a  call to getcontext()).  Before invoking
24       makecontext(), the caller must allocate a new stack  for  this  context
25       and assign its address to ucp->uc_stack, and define a successor context
26       and assign its address to ucp->uc_link.
27
28       When this context is later activated (using  setcontext()  or  swapcon‐
29       text())  the  function func is called, and passed the series of integer
30       (int) arguments that follow argc; the caller must specify the number of
31       these  arguments  in  argc.   When this function returns, the successor
32       context is activated.  If the successor context pointer  is  NULL,  the
33       thread exits.
34
35       The  swapcontext()  function saves the current context in the structure
36       pointed to by oucp, and then activates the context pointed to by ucp.
37

RETURN VALUE

39       When successful, swapcontext() does not  return.  (But  we  may  return
40       later,  in case oucp is activated, in which case it looks like swapcon‐
41       text() returns 0.)  On error, swapcontext() returns -1 and  sets  errno
42       appropriately.
43

ERRORS

45       ENOMEM Insufficient stack space left.
46

NOTES

48       The  interpretation  of  ucp->uc_stack  is  just  as in sigaltstack(2),
49       namely, this struct contains the start and length of a memory  area  to
50       be  used  as  the  stack,  regardless of the direction of growth of the
51       stack.  Thus, it is not necessary for the user program to  worry  about
52       this direction.
53

CONFORMING TO

55       SUSv2, POSIX.1-2001.
56

EXAMPLE

58       The  example  program below demonstrates the use of getcontext(), make‐
59       context(), and swapcontext().  Running the program produces the follow‐
60       ing output:
61
62            $ ./a.out
63            main: swapcontext(&uctx_main, &uctx_func2)
64            func2: started
65            func2: swapcontext(&uctx_func2, &uctx_func1)
66            func1: started
67            func1: swapcontext(&uctx_func1, &uctx_func2)
68            func2: returning
69            func1: returning
70            main: exiting
71
72       #include <ucontext.h>
73       #include <stdio.h>
74       #include <stdlib.h>
75
76       static ucontext_t uctx_main, uctx_func1, uctx_func2;
77
78       #define die(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
79
80       static void
81       func1(void)
82       {
83           printf("func1: started\n");
84           printf("func1: swapcontext(&uctx_func1, &uctx_func2)\n");
85           if (swapcontext(&uctx_func1, &uctx_func2) == -1)
86               die("swapcontext");
87           printf("func1: returning\n");
88       }
89
90       static void
91       func2(void)
92       {
93           printf("func2: started\n");
94           printf("func2: swapcontext(&uctx_func2, &uctx_func1)\n");
95           if (swapcontext(&uctx_func2, &uctx_func1) == -1)
96               die("swapcontext");
97           printf("func2: returning\n");
98       }
99
100       int
101       main(int argc, char *argv[])
102       {
103           char func1_stack[16384];
104           char func2_stack[16384];
105
106           if (getcontext(&uctx_func1) == -1)
107               die("getcontext");
108           uctx_func1.uc_stack.ss_sp = func1_stack;
109           uctx_func1.uc_stack.ss_size = sizeof(func1_stack);
110           uctx_func1.uc_link = &uctx_main;
111           makecontext(&uctx_func1, func1, 0);
112
113           if (getcontext(&uctx_func2) == -1)
114               die("getcontext");
115           uctx_func2.uc_stack.ss_sp = func2_stack;
116           uctx_func2.uc_stack.ss_size = sizeof(func2_stack);
117           /* Successor context is f1(), unless argc > 1 */
118           uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1;
119           makecontext(&uctx_func2, func2, 0);
120
121           printf("main: swapcontext(&uctx_main, &uctx_func2)\n");
122           if (swapcontext(&uctx_main, &uctx_func2) == -1)
123               die("swapcontext");
124
125           printf("main: exiting\n");
126           exit(EXIT_SUCCESS);
127       }
128