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