lib/libc/gen/makecontext.3

   1 .\"     $NetBSD: makecontext.3,v 1.9 2010/04/29 06:07:35 jruoho 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 29, 2010
  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 and
 138 .St -p1003.1-2001 .
 139 .Pp
 140 The
 141 .St -p1003.1-2004
 142 revision marked the functions
 143 .Fn makecontext
 144 and
 145 .Fn swapcontext
 146 as obsolete, citing portability issues and recommending the use of
 147 .Tn POSIX
 148 threads instead.
 149 The
 150 .St -p1003.1-2008
 151 revision removed the functions from the specification.
 152 .Pp
 153 .Bf -symbolic
 154 The standard does not clearly define the type of integer arguments
 155 passed to
 156 .Fa func
 157 via
 158 .Fn makecontext ;
 159 portable applications should not rely on the implementation detail that
 160 it may be possible to pass pointer arguments to functions.
 161 .Ef
 162 This may be clarified in a future revision of the standard.
 163 .Sh HISTORY
 164 The
 165 .Fn makecontext
 166 and
 167 .Fn swapcontext
 168 functions first appeared in
 169 .At V.4 .
 170 .Sh CAVEATS
 171 Due to limitations in the current pthread implementation,
 172 .Nm
 173 should not be used in programs which link against the
 174 .Xr pthread 3
 175 library (whether threads are used or not).