1.\" $NetBSD: makecontext.3,v 1.5 2008/04/30 13:10:50 martin Exp $ 2.\" 3.\" Copyright (c) 2001 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 June 13, 2001 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 points to an invalid address. 118.It Bq Er EFAULT 119The 120.Fa ucp 121argument points to an invalid address. 122.It Bq Er EINVAL 123The contents of the datum pointed to by 124.Fa ucp 125are invalid. 126.El 127.Sh SEE ALSO 128.Xr _exit 2 , 129.Xr getcontext 2 , 130.Xr setcontext 2 , 131.Xr ucontext 2 132.Sh STANDARDS 133The 134.Fn makecontext 135and 136.Fn swapcontext 137functions conform to 138.St -xsh5 . 139.Pp 140.Bf -symbolic 141The standard does not clearly define the type of integer arguments 142passed to 143.Fa func 144via 145.Fn makecontext ; 146portable applications should not rely on the implementation detail that 147it may be possible to pass pointer arguments to functions. 148.Ef 149This may be clarified in a future revision of the standard. 150.Sh HISTORY 151The 152.Fn makecontext 153and 154.Fn swapcontext 155functions first appeared in 156.At V.4 . 157