man3/makecontext.3

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