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 46The 47.Fn makecontext 48function modifies the object pointed to by 49.Fa ucp , 50which has been initialized using 51.Xr getcontext 2 . 52When this context is resumed using 53.Fn swapcontext 54or 55.Xr setcontext 2 , 56program execution continues as if 57.Fa func 58had been called with the arguments specified after 59.Fa argc 60in the call of 61.Fn makecontext . 62The value of 63.Fa argc 64must be equal to the number of integer arguments following it, 65and must be equal to the number of integer arguments expected by 66.Fa func ; 67otherwise, the behavior is undefined. 68.Pp 69Before being modified using 70.Fn makecontext , 71a stack must be allocated for the context (in the 72.Fa uc_stack 73member), and a context to resume after 74.Fa func 75has returned must be determined (pointed to by the 76.Fa uc_link 77member); 78otherwise, the behavior is undefined. 79If 80.Fa uc_link 81is a null pointer, then the context is the main context, 82and the process will exit with an exit status of 0 upon return. 83.Pp 84The 85.Fn swapcontext 86function saves the current context in the object pointed to by 87.Fa oucp , 88sets the current context to that specified in the object pointed to by 89.Fa ucp , 90and resumes execution. 91When a context saved by 92.Fn swapcontext 93is restored using 94.Xr setcontext 2 , 95execution will resume as if the corresponding invocation of 96.Fn swapcontext 97had just returned (successfully). 98.Sh RETURN VALUES 99The 100.Fn makecontext 101function returns no value. 102.Pp 103On success, 104.Fn swapcontext 105returns a value of 0, 106Otherwise, \-1 is returned and 107.Va errno 108is set to indicate the error. 109.Sh ERRORS 110The 111.Fn swapcontext 112function will fail if: 113.Bl -tag -width Er 114.It Bq Er EFAULT 115The 116.Fa oucp 117argument or the 118.Fa ucp 119argument points to an invalid address. 120.It Bq Er EINVAL 121The contents of the datum pointed to by 122.Fa ucp 123are 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 131The 132.Fn makecontext 133and 134.Fn swapcontext 135functions conform to 136.St -xsh5 137and 138.St -p1003.1-2001 . 139.Pp 140The 141.St -p1003.1-2004 142revision marked the functions 143.Fn makecontext 144and 145.Fn swapcontext 146as obsolete, citing portability issues and recommending the use of 147.Tn POSIX 148threads instead. 149The 150.St -p1003.1-2008 151revision removed the functions from the specification. 152.Pp 153.Bf -symbolic 154The standard does not clearly define the type of integer arguments 155passed to 156.Fa func 157via 158.Fn makecontext ; 159portable applications should not rely on the implementation detail that 160it may be possible to pass pointer arguments to functions. 161.Ef 162This may be clarified in a future revision of the standard. 163.Sh HISTORY 164The 165.Fn makecontext 166and 167.Fn swapcontext 168functions first appeared in 169.At V.4 . 170.Sh CAVEATS 171Due to limitations in the current pthread implementation, 172.Nm 173should not be used in programs which link against the 174.Xr pthread 3 175library (whether threads are used or not). 176