swapcontext(3c)

1makecontext(3C)          Standard C Library Functions          makecontext(3C)
2
3
4

NAME

6       makecontext, swapcontext - manipulate user contexts
7

SYNOPSIS

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

DESCRIPTION

19       The makecontext() function modifies the context specified by ucp, which
20       has been initialized using getcontext(2). When this context is  resumed
21       using  swapcontext()  or  setcontext(2), execution continues by calling
22       the function func, passing it the arguments that  follow  argc  in  the
23       makecontext() call. The value of argc must match the number of pointer-
24       sized integer arguments passed to func, otherwise the behavior is unde‐
25       fined.
26
27
28       Before  a  call  is  made  to makecontext(), the context being modified
29       should have a stack allocated for it. The stack is assigned to the con‐
30       text by initializing the uc_stack member.
31
32
33       The  uc_link  member  is  used  to  determine  the context that will be
34       resumed when the context being modified by makecontext() returns.   The
35       uc_link  member  should  be  initialized  prior to the call to makecon‐
36       text(). If the uc_link member is initialized to NULL, the  thread  exe‐
37       cuting func will exit when func returns. See pthread_exit(3C).
38
39
40       The  swapcontext()  function  saves  the current context in the context
41       structure pointed to by oucp and sets the context to the context struc‐
42       ture pointed to by ucp.
43
44
45       If  the ucp or oucp argument points to an invalid address, the behavior
46       is undefined and errno may be set to EFAULT.
47

RETURN VALUES

49       On successful completion, swapcontext() returns  0.  Otherwise,  −1  is
50       returned and errno is set to indicate the error.
51

ERRORS

53       The swapcontext() function will fail if:
54
55       ENOMEM    The  ucp argument does not have enough stack left to complete
56                 the operation.
57
58
59
60       The swapcontext() function may fail if:
61
62       EFAULT    The ucp or oucp argument points to an invalid address.
63
64

EXAMPLES

66       Example 1 Alternate execution context on a stack whose memory was allo‐
67       cated using mmap().
68
69         #include <stdio.h>
70         #include <ucontext.h>
71         #include <sys/mman.h>
72
73         void
74         assign(long a, int *b)
75         {
76                 *b = (int)a;
77         }
78
79         int
80         main(int argc, char **argv)
81         {
82                 ucontext_t uc, back;
83                 size_t sz = 0x10000;
84                 int value = 0;
85
86                 getcontext(&uc);
87
88                 uc.uc_stack.ss_sp = mmap(0, sz,
89                     PROT_READ | PROT_WRITE | PROT_EXEC,
90                     MAP_PRIVATE | MAP_ANON, -1, 0);
91                 uc.uc_stack.ss_size = sz;
92                 uc.uc_stack.ss_flags = 0;
93
94                 uc.uc_link = &back;
95
96                 makecontext(&uc, assign, 2, 100L, &value);
97                 swapcontext(&back, &uc);
98
99                 printf("done %d\n", value);
100
101                 return (0);
102         }
103
104

USAGE

106       These  functions are useful for implementing user-level context switch‐
107       ing between multiple threads of control within a  process  (co-process‐
108       ing).  More  effective  multiple  threads of control can be obtained by
109       using native support for multithreading. See threads(5).
110

ATTRIBUTES

112       See attributes(5) for descriptions of the following attributes:
113
114
115
116
117       ┌─────────────────────────────┬─────────────────────────────┐
118       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
119       ├─────────────────────────────┼─────────────────────────────┤
120       │Interface Stability          │Standard                     │
121       ├─────────────────────────────┼─────────────────────────────┤
122       │MT-Level                     │MT-Safe                      │
123       └─────────────────────────────┴─────────────────────────────┘
124

NOTES

130       The  semantics  of the uc_stack member of the ucontext_t structure have
131       changed as they apply to inputs to makecontext(). Prior to Solaris  10,
132       the  ss_sp member of the uc_stack structure represented the high memory
133       address of the area reserved for the stack. The ss_sp member now repre‐
134       sents  the  base  (low  memory  address), in keeping with other uses of
135       ss_sp.
136
137
138       This change in the meaning of ss_sp is now the  default  behavior.  The
139       -D__MAKECONTEXT_V2_SOURCE  compilation  flag  used  in Solaris 9 update
140       releases to access this behavior is obsolete.
141
142
143       Binary compatibility has been preserved with releases prior to  Solaris
144       10.  Before  recompiling,  applications  that use makecontext() must be
145       updated to reflect this behavior change. The example below  demonstates
146       a typical change that must be applied:
147
148         --- example1_s9.c       Thu Oct  3 11:58:17 2002
149         +++ example1.c  Thu Jun 27 13:28:16 2002
150         @@ -27,12 +27,9 @@
151                 uc.uc_stack.ss_sp = mmap(0, sz,
152                     PROT_READ | PROT_WRITE | PROT_EXEC,
153                     MAP_PRIVATE | MAP_ANON, -1, 0);
154         -       uc.uc_stack.ss_sp = (char *)uc.uc_stack.ss_sp + sz - 8;
155                 uc.uc_stack.ss_size = sz;
156                 uc.uc_stack.ss_flags = 0;
157
158                 uc.uc_link = &back
159
160                 makecontext(&uc, assign, 2, 100L, &value);
161
162
163
164
165SunOS 5.11                        8 Mar 2004                   makecontext(3C)