man/man3/makecontext.3

   1 .TH MAKECONTEXT 3  "Mar 2, 2010"
   2 .SH NAME
   3 makecontext, swapcontext \- manipulate user contexts
   4 .SH SYNOPSIS
   5 .nf
   6 .ft B
   7 #include <ucontext.h>
   8
   9 void makecontext(ucontext\_t *\fIucp\fP, void \fI(*func)(void)\fP, int \fIargc\fP, ...)
  10 int swapcontext(ucontext\_t *\fIoucp\fP, const ucontext\_t *\fIucp\fP)
  11 .SH DESCRIPTION
  12 The
  13 .BR makecontext (3)
  14 ,
  15 .BR swapcontext (3)
  16 ,
  17 .BR getcontext (3)
  18 , and
  19 .BR setcontext (3)
  20 together form a set of functions that allow user-level context switching between multiple threads of control within a process.
  21 .PP
  22 The
  23 .BR makecontext ()
  24 function modifies the user thread pointed to by
  25 .I ucp
  26 to continue execution by invoking function
  27 .I func
  28 and passing that function a number of
  29 .I argc
  30 integer arguments. The value of
  31 .I argc
  32 must match the number of integer arguments passed to
  33 .I func
  34 , otherwise the behavior is undefined. Context
  35 .I ucp
  36 must have been initialized by a call to
  37 .BR getcontext (3)
  38 and have a stack allocated for it. The address of the stack must be assigned to  \fIucp\->uc_stack.ss_size\fP and the size of the stack to \fIucp\->uc_stack.ss_size\fP. The \fIucp\->uc_link\fP member is used to determine which successor context is run after the context modified by
  39 .BR makecontext ()
  40 returns. If left NULL, the process exits.
  41 .PP
  42 The
  43 .BR swapcontext ()
  44 function saves the current context in the context structure pointed to by
  45 .I oucp
  46 and sets the context to the context structure pointed to by \fIucp\fP.
  47
  48 .SH "RETURN VALUE"
  49 When successful,
  50 .BR swapcontext ()
  51 returns 0. Otherwise, -1 is returned and
  52 .I errno
  53 is set to indicate the error. Note that a succesful call to
  54 .BR swapcontext ()
  55 actually does not return. Only after returning to the context that called
  56 .BR swapcontext ()
  57 , it appears as if
  58 .BR swapcontext ()
  59 returned 0.
  60
  61 .SH "ERRORS"
  62 .TP 15
  63 [EFAULT]
  64 Either the \fIucp\fP or \fIoucp\fP is a NULL pointer.
  65 .TP 15
  66 [EINVAL]
  67 The context is not properly initialized.
  68 .TP 15
  69 [ENOMEM]
  70 The \fIucp\fP argument does not have enough stack left to complete the operation.
  71 .SH "SEE ALSO"
  72 .BR getcontext (3).
  73
  74 .SH "AUTHORS"
  75 Thomas Veerman