original/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 2014-05-28 "GNU" "Linux Programmer's Manual"
  29 .SH NAME
  30 makecontext, swapcontext \- manipulate user context
  31 .SH SYNOPSIS
  32 .B #include <ucontext.h>
  33 .sp
  34 .BI "void makecontext(ucontext_t *" ucp ", void (*" func )(),
  35 .BI "int " argc ", ...);"
  36 .sp
  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 .LP
  50 For the type and the first two functions, see
  51 .BR getcontext (3).
  52 .LP
  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
  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 .LP
  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 .SS Multithreading (see pthreads(7))
 107 The
 108 .BR makecontext ()
 109 and
 110 .BR swapcontext ()
 111 functions are thread-safe.
 112 .SH CONFORMING TO
 113 SUSv2, POSIX.1-2001.
 114 POSIX.1-2008 removes the specifications of
 115 .BR makecontext ()
 116 and
 117 .BR swapcontext (),
 118 citing portability issues, and
 119 recommending that applications be rewritten to use POSIX threads instead.
 120 .SH NOTES
 121 The interpretation of \fIucp\->uc_stack\fP is just as in
 122 .BR sigaltstack (2),
 123 namely, this struct contains the start and length of a memory area
 124 to be used as the stack, regardless of the direction of growth of
 125 the stack.
 126 Thus, it is not necessary for the user program to
 127 worry about this direction.
 128
 129 On architectures where
 130 .I int
 131 and pointer types are the same size
 132 (e.g., x86-32, where both types are 32 bits),
 133 you may be able to get away with passing pointers as arguments to
 134 .BR makecontext ()
 135 following
 136 .IR argc .
 137 However, doing this is not guaranteed to be portable,
 138 is undefined according to the standards,
 139 and won't work on architectures where pointers are larger than
 140 .IR int s.
 141 Nevertheless, starting with version 2.8, glibc makes some changes to
 142 .BR makecontext (),
 143 to permit this on some 64-bit architectures (e.g., x86-64).
 144 .SH EXAMPLE
 145 .PP
 146 The example program below demonstrates the use of
 147 .BR getcontext (3),
 148 .BR makecontext (),
 149 and
 150 .BR swapcontext ().
 151 Running the program produces the following output:
 152 .in +4n
 153 .nf
 154
 155 .RB "$" " ./a.out"
 156 main: swapcontext(&uctx_main, &uctx_func2)
 157 func2: started
 158 func2: swapcontext(&uctx_func2, &uctx_func1)
 159 func1: started
 160 func1: swapcontext(&uctx_func1, &uctx_func2)
 161 func2: returning
 162 func1: returning
 163 main: exiting
 164 .fi
 165 .in
 166 .SS Program source
 167 \&
 168 .nf
 169 #include <ucontext.h>
 170 #include <stdio.h>
 171 #include <stdlib.h>
 172
 173 static ucontext_t uctx_main, uctx_func1, uctx_func2;
 174
 175 #define handle_error(msg) \\
 176     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 177
 178 static void
 179 func1(void)
 180 {
 181     printf("func1: started\\n");
 182     printf("func1: swapcontext(&uctx_func1, &uctx_func2)\\n");
 183     if (swapcontext(&uctx_func1, &uctx_func2) == \-1)
 184         handle_error("swapcontext");
 185     printf("func1: returning\\n");
 186 }
 187
 188 static void
 189 func2(void)
 190 {
 191     printf("func2: started\\n");
 192     printf("func2: swapcontext(&uctx_func2, &uctx_func1)\\n");
 193     if (swapcontext(&uctx_func2, &uctx_func1) == \-1)
 194         handle_error("swapcontext");
 195     printf("func2: returning\\n");
 196 }
 197
 198 int
 199 main(int argc, char *argv[])
 200 {
 201     char func1_stack[16384];
 202     char func2_stack[16384];
 203
 204     if (getcontext(&uctx_func1) == \-1)
 205         handle_error("getcontext");
 206     uctx_func1.uc_stack.ss_sp = func1_stack;
 207     uctx_func1.uc_stack.ss_size = sizeof(func1_stack);
 208     uctx_func1.uc_link = &uctx_main;
 209     makecontext(&uctx_func1, func1, 0);
 210
 211     if (getcontext(&uctx_func2) == \-1)
 212         handle_error("getcontext");
 213     uctx_func2.uc_stack.ss_sp = func2_stack;
 214     uctx_func2.uc_stack.ss_size = sizeof(func2_stack);
 215     /* Successor context is f1(), unless argc > 1 */
 216     uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1;
 217     makecontext(&uctx_func2, func2, 0);
 218
 219     printf("main: swapcontext(&uctx_main, &uctx_func2)\\n");
 220     if (swapcontext(&uctx_main, &uctx_func2) == \-1)
 221         handle_error("swapcontext");
 222
 223     printf("main: exiting\\n");
 224     exit(EXIT_SUCCESS);
 225 }
 226 .fi
 227 .SH SEE ALSO
 228 .BR sigaction (2),
 229 .BR sigaltstack (2),
 230 .BR sigprocmask (2),
 231 .BR getcontext (3),
 232 .BR sigsetjmp (3)
 233 .SH COLOPHON
 234 This page is part of release 3.79 of the Linux
 235 .I man-pages
 236 project.
 237 A description of the project,
 238 information about reporting bugs,
 239 and the latest version of this page,
 240 can be found at
 241 \%http://www.kernel.org/doc/man\-pages/.