man3/makecontext.3

   1 .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .TH MAKECONTEXT 3 2001-11-15 "Linux 2.4" "Linux Programmer's Manual"
  24 .SH NAME
  25 makecontext, swapcontext \- manipulate user context
  26 .SH SYNOPSIS
  27 .B #include <ucontext.h>
  28 .sp
  29 .BI "void makecontext(ucontext_t *" ucp ", void *" func (),
  30 .BI "int " argc ", ...);"
  31 .br
  32 .BI "int swapcontext(ucontext_t *" oucp ", ucontext_t *" ucp );
  33 .SH DESCRIPTION
  34 In a System V-like environment, one has the type \fIucontext_t\fP defined in
  35 .I <ucontext.h>
  36 and the four functions
  37 \fBgetcontext\fP(), \fBsetcontext\fP(), \fBmakecontext\fP()
  38 and \fBswapcontext\fP() that allow user-level context switching
  39 between multiple threads of control within a process.
  40 .LP
  41 For the type and the first two functions, see
  42 .BR getcontext (2).
  43 .LP
  44 The \fBmakecontext\fP() function modifies the context pointed to
  45 by \fIucp\fP (which was obtained from a call to \fBgetcontext\fP()).
  46 Before invoking \fBmakecontext\fP(), the caller must allocate a new stack
  47 for this context and assign its address to \fIucp->uc_stack\fP,
  48 and define a successor context and
  49 assign its address to \fIucp->uc_link\fP.
  50
  51 When this context is later activated (using \fBsetcontext\fP() or
  52 \fBswapcontext\fP()) the function \fIfunc\fP is called,
  53 and passed the series of integer
  54 .RI ( int )
  55 arguments that follow
  56 .IR argc ;
  57 the caller must specify the number of these arguments in
  58 .IR argc .
  59 When this function returns, the successor context is activated.
  60 If the successor context pointer is NULL, the thread exits.
  61 .LP
  62 The \fBswapcontext\fP() function saves the current context in
  63 the structure pointed to by \fIoucp\fP, and then activates the
  64 context pointed to by \fIucp\fP.
  65 .SH "RETURN VALUE"
  66 When successful, \fBswapcontext\fP()
  67 does not return.
  68 (But we may return later, in case \fIoucp\fP is
  69 activated, in which case it looks like \fBswapcontext\fP() returns 0.)
  70 On error, \fBswapcontext\fP() returns \-1 and
  71 sets \fIerrno\fP appropriately.
  72 .SH ERRORS
  73 .TP
  74 .B ENOMEM
  75 Insufficient stack space left.
  76 .SH NOTES
  77 The interpretation of \fIucp->uc_stack\fP is just as in
  78 .BR sigaltstack (2),
  79 namely, this struct contains the start and length of a memory area
  80 to be used as the stack, regardless of the direction of growth of
  81 the stack.
  82 Thus, it is not necessary for the user program to
  83 worry about this direction.
  84 .SH "CONFORMING TO"
  85 SUSv2, POSIX.1-2001.
  86 .SH EXAMPLE
  87 .PP
  88 The example program below demonstrates the use of
  89 .BR getcontext (),
  90 .BR makecontext (),
  91 and
  92 .BR swapcontext ().
  93 Running the program produces the following output:
  94 .in +0.5i
  95 .nf
  96
  97 $ ./a.out
  98 main: swapcontext(&uctx_main, &uctx_func2)
  99 func2: started
 100 func2: swapcontext(&uctx_func2, &uctx_func1)
 101 func1: started
 102 func1: swapcontext(&uctx_func1, &uctx_func2)
 103 func2: returning
 104 func1: returning
 105 main: exiting
 106
 107 .fi
 108 .in -0.5i
 109 .nf
 110 #include <ucontext.h>
 111 #include <stdio.h>
 112 #include <stdlib.h>
 113
 114 static ucontext_t uctx_main, uctx_func1, uctx_func2;
 115
 116 #define die(msg) do { perror(msg); exit(EXIT_FAILURE); } while (0)
 117
 118 static void
 119 func1(void)
 120 {
 121     printf("func1: started\\n");
 122     printf("func1: swapcontext(&uctx_func1, &uctx_func2)\\n");
 123     if (swapcontext(&uctx_func1, &uctx_func2) == -1)
 124         die("swapcontext");
 125     printf("func1: returning\\n");
 126 }
 127
 128 static void
 129 func2(void)
 130 {
 131     printf("func2: started\\n");
 132     printf("func2: swapcontext(&uctx_func2, &uctx_func1)\\n");
 133     if (swapcontext(&uctx_func2, &uctx_func1) == -1)
 134         die("swapcontext");
 135     printf("func2: returning\\n");
 136 }
 137
 138 int
 139 main(int argc, char *argv[])
 140 {
 141     char func1_stack[16384];
 142     char func2_stack[16384];
 143
 144     if (getcontext(&uctx_func1) == -1)
 145         die("getcontext");
 146     uctx_func1.uc_stack.ss_sp = func1_stack;
 147     uctx_func1.uc_stack.ss_size = sizeof(func1_stack);
 148     uctx_func1.uc_link = &uctx_main;
 149     makecontext(&uctx_func1, func1, 0);
 150
 151     if (getcontext(&uctx_func2) == -1)
 152         die("getcontext");
 153     uctx_func2.uc_stack.ss_sp = func2_stack;
 154     uctx_func2.uc_stack.ss_size = sizeof(func2_stack);
 155     /* Successor context is f1(), unless argc > 1 */
 156     uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1;
 157     makecontext(&uctx_func2, func2, 0);
 158
 159     printf("main: swapcontext(&uctx_main, &uctx_func2)\\n");
 160     if (swapcontext(&uctx_main, &uctx_func2) == -1)
 161         die("swapcontext");
 162
 163     printf("main: exiting\\n");
 164     exit(EXIT_SUCCESS);
 165 }
 166 .fi
 167 .SH "SEE ALSO"
 168 .BR getcontext (2),
 169 .BR sigaction (2),
 170 .BR sigaltstack (2),
 171 .BR sigprocmask (2),
 172 .BR sigsetjmp (3)