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 .\" 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.
   7 .\"
   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.
  12 .\"
  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
  19 .\" professionally.
  20 .\"
  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
  24 .\"
  25 .TH MAKECONTEXT 3 2008-08-06 "GNU" "Linux Programmer's Manual"
  26 .SH NAME
  27 makecontext, swapcontext \- manipulate user context
  28 .SH SYNOPSIS
  29 .B #include <ucontext.h>
  30 .sp
  31 .BI "void makecontext(ucontext_t *" ucp ", void (*" func )(),
  32 .BI "int " argc ", ...);"
  33 .sp
  34 .BI "int swapcontext(ucontext_t *" oucp ", ucontext_t *" ucp );
  35 .SH DESCRIPTION
  36 In a System V-like environment, one has the type \fIucontext_t\fP defined in
  37 .I <ucontext.h>
  38 and the four functions
  39 .BR getcontext (2),
  40 .BR setcontext (2),
  41 .BR makecontext ()
  42 and
  43 .BR swapcontext ()
  44 that allow user-level context switching
  45 between multiple threads of control within a process.
  46 .LP
  47 For the type and the first two functions, see
  48 .BR getcontext (2).
  49 .LP
  50 The
  51 .BR makecontext ()
  52 function modifies the context pointed to
  53 by \fIucp\fP (which was obtained from a call to
  54 .BR getcontext (2)).
  55 Before invoking
  56 .BR makecontext (),
  57 the caller must allocate a new stack
  58 for this context and assign its address to \fIucp\->uc_stack\fP,
  59 and define a successor context and
  60 assign its address to \fIucp\->uc_link\fP.
  61
  62 When this context is later activated (using
  63 .BR setcontext (2)
  64 or
  65 .BR swapcontext ())
  66 the function \fIfunc\fP is called,
  67 and passed the series of integer
  68 .RI ( int )
  69 arguments that follow
  70 .IR argc ;
  71 the caller must specify the number of these arguments in
  72 .IR argc .
  73 When this function returns, the successor context is activated.
  74 If the successor context pointer is NULL, the thread exits.
  75 .LP
  76 The
  77 .BR swapcontext ()
  78 function saves the current context in
  79 the structure pointed to by \fIoucp\fP, and then activates the
  80 context pointed to by \fIucp\fP.
  81 .SH "RETURN VALUE"
  82 When successful,
  83 .BR swapcontext ()
  84 does not return.
  85 (But we may return later, in case \fIoucp\fP is
  86 activated, in which case it looks like
  87 .BR swapcontext ()
  88 returns 0.)
  89 On error,
  90 .BR swapcontext ()
  91 returns \-1 and
  92 sets \fIerrno\fP appropriately.
  93 .SH ERRORS
  94 .TP
  95 .B ENOMEM
  96 Insufficient stack space left.
  97 .SH VERSIONS
  98 .BR makecontext ()
  99 and
 100 .BR swapcontext ()
 101 are provided in glibc since version 2.1.
 102 .SH "CONFORMING TO"
 103 SUSv2, POSIX.1-2001.
 104 POSIX.1-2008 removes the specifications of
 105 .BR makecontext ()
 106 and
 107 .BR swapcontext ().
 108 .SH NOTES
 109 The interpretation of \fIucp\->uc_stack\fP is just as in
 110 .BR sigaltstack (2),
 111 namely, this struct contains the start and length of a memory area
 112 to be used as the stack, regardless of the direction of growth of
 113 the stack.
 114 Thus, it is not necessary for the user program to
 115 worry about this direction.
 116 .SH EXAMPLE
 117 .PP
 118 The example program below demonstrates the use of
 119 .BR getcontext (2),
 120 .BR makecontext (),
 121 and
 122 .BR swapcontext ().
 123 Running the program produces the following output:
 124 .in +4n
 125 .nf
 126
 127 .RB "$" " ./a.out"
 128 main: swapcontext(&uctx_main, &uctx_func2)
 129 func2: started
 130 func2: swapcontext(&uctx_func2, &uctx_func1)
 131 func1: started
 132 func1: swapcontext(&uctx_func1, &uctx_func2)
 133 func2: returning
 134 func1: returning
 135 main: exiting
 136 .fi
 137 .in
 138 .SS Program source
 139 \&
 140 .nf
 141 #include <ucontext.h>
 142 #include <stdio.h>
 143 #include <stdlib.h>
 144
 145 static ucontext_t uctx_main, uctx_func1, uctx_func2;
 146
 147 #define handle_error(msg) \\
 148     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 149
 150 static void
 151 func1(void)
 152 {
 153     printf("func1: started\\n");
 154     printf("func1: swapcontext(&uctx_func1, &uctx_func2)\\n");
 155     if (swapcontext(&uctx_func1, &uctx_func2) == \-1)
 156         handle_error("swapcontext");
 157     printf("func1: returning\\n");
 158 }
 159
 160 static void
 161 func2(void)
 162 {
 163     printf("func2: started\\n");
 164     printf("func2: swapcontext(&uctx_func2, &uctx_func1)\\n");
 165     if (swapcontext(&uctx_func2, &uctx_func1) == \-1)
 166         handle_error("swapcontext");
 167     printf("func2: returning\\n");
 168 }
 169
 170 int
 171 main(int argc, char *argv[])
 172 {
 173     char func1_stack[16384];
 174     char func2_stack[16384];
 175
 176     if (getcontext(&uctx_func1) == \-1)
 177         handle_error("getcontext");
 178     uctx_func1.uc_stack.ss_sp = func1_stack;
 179     uctx_func1.uc_stack.ss_size = sizeof(func1_stack);
 180     uctx_func1.uc_link = &uctx_main;
 181     makecontext(&uctx_func1, func1, 0);
 182
 183     if (getcontext(&uctx_func2) == \-1)
 184         handle_error("getcontext");
 185     uctx_func2.uc_stack.ss_sp = func2_stack;
 186     uctx_func2.uc_stack.ss_size = sizeof(func2_stack);
 187     /* Successor context is f1(), unless argc > 1 */
 188     uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1;
 189     makecontext(&uctx_func2, func2, 0);
 190
 191     printf("main: swapcontext(&uctx_main, &uctx_func2)\\n");
 192     if (swapcontext(&uctx_main, &uctx_func2) == \-1)
 193         handle_error("swapcontext");
 194
 195     printf("main: exiting\\n");
 196     exit(EXIT_SUCCESS);
 197 }
 198 .fi
 199 .SH "SEE ALSO"
 200 .BR getcontext (2),
 201 .BR sigaction (2),
 202 .BR sigaltstack (2),
 203 .BR sigprocmask (2),
 204 .BR sigsetjmp (3)