lib/libc/gen/makecontext.3

   1 .\"     $NetBSD: makecontext.3,v 1.6 2009/04/16 18:37:30 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2001, 2009 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Klaus Klein.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd April 16, 2009
  31 .Dt MAKECONTEXT 3
  32 .Os
  33 .Sh NAME
  34 .Nm makecontext ,
  35 .Nm swapcontext
  36 .Nd manipulate user contexts
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In ucontext.h
  41 .Ft void
  42 .Fn makecontext "ucontext_t *ucp" "void (*func)()" "int argc" ...
  43 .Ft int
  44 .Fn swapcontext "ucontext_t * restrict oucp" "ucontext_t * restrict ucp"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn makecontext
  48 function modifies the object pointed to by
  49 .Fa ucp ,
  50 which has been initialized using
  51 .Xr getcontext 2 .
  52 When this context is resumed using
  53 .Fn swapcontext
  54 or
  55 .Xr setcontext 2 ,
  56 program execution continues as if
  57 .Fa func
  58 had been called with the arguments specified after
  59 .Fa argc
  60 in the call of
  61 .Fn makecontext .
  62 The value of
  63 .Fa argc
  64 must be equal to the number of integer arguments following it,
  65 and must be equal to the number of integer arguments expected by
  66 .Fa func ;
  67 otherwise, the behavior is undefined.
  68 .Pp
  69 Before being modified using
  70 .Fn makecontext ,
  71 a stack must be allocated for the context (in the
  72 .Fa uc_stack
  73 member), and a context to resume after
  74 .Fa func
  75 has returned must be determined (pointed to by the
  76 .Fa uc_link
  77 member);
  78 otherwise, the behavior is undefined.
  79 If
  80 .Fa uc_link
  81 is a null pointer, then the context is the main context,
  82 and the process will exit with an exit status of 0 upon return.
  83 .Pp
  84 The
  85 .Fn swapcontext
  86 function saves the current context in the object pointed to by
  87 .Fa oucp ,
  88 sets the current context to that specified in the object pointed to by
  89 .Fa ucp ,
  90 and resumes execution.
  91 When a context saved by
  92 .Fn swapcontext
  93 is restored using
  94 .Xr setcontext 2 ,
  95 execution will resume as if the corresponding invocation of
  96 .Fn swapcontext
  97 had just returned (successfully).
  98 .Sh RETURN VALUES
  99 The
 100 .Fn makecontext
 101 function returns no value.
 102 .Pp
 103 On success,
 104 .Fn swapcontext
 105 returns a value of 0,
 106 Otherwise, \-1 is returned and
 107 .Va errno
 108 is set to indicate the error.
 109 .Sh ERRORS
 110 The
 111 .Fn swapcontext
 112 function will fail if:
 113 .Bl -tag -width Er
 114 .It Bq Er EFAULT
 115 The
 116 .Fa oucp
 117 argument or the
 118 .Fa ucp
 119 argument points to an invalid address.
 120 .It Bq Er EINVAL
 121 The contents of the datum pointed to by
 122 .Fa ucp
 123 are invalid.
 124 .El
 125 .Sh SEE ALSO
 126 .Xr _exit 2 ,
 127 .Xr getcontext 2 ,
 128 .Xr setcontext 2 ,
 129 .Xr ucontext 2
 130 .Sh STANDARDS
 131 The
 132 .Fn makecontext
 133 and
 134 .Fn swapcontext
 135 functions conform to
 136 .St -xsh5 .
 137 .Pp
 138 .Bf -symbolic
 139 The standard does not clearly define the type of integer arguments
 140 passed to
 141 .Fa func
 142 via
 143 .Fn makecontext ;
 144 portable applications should not rely on the implementation detail that
 145 it may be possible to pass pointer arguments to functions.
 146 .Ef
 147 This may be clarified in a future revision of the standard.
 148 .Sh HISTORY
 149 The
 150 .Fn makecontext
 151 and
 152 .Fn swapcontext
 153 functions first appeared in
 154 .At V.4 .
 155 .Sh CAVEATS
 156 Due to limitations in the current pthread implementation,
 157 .Nm
 158 should not be used in programs which link against the
 159 .Xr pthread 3
 160 library (whether threads are used or not).