Annotation of src/lib/libc/gen/makecontext.3, Revision 1.9
1.9 ! jruoho 1: .\" $NetBSD: makecontext.3,v 1.8 2010/04/28 14:07:03 jruoho Exp $
1.1 wiz 2: .\"
1.6 wiz 3: .\" Copyright (c) 2001, 2009 The NetBSD Foundation, Inc.
1.1 wiz 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: .\"
1.9 ! jruoho 30: .Dd April 29, 2010
1.1 wiz 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
1.2 wiz 40: .In ucontext.h
1.1 wiz 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
1.4 uwe 48: function modifies the object pointed to by
1.1 wiz 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
1.6 wiz 117: argument or the
1.1 wiz 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 ,
1.3 wiz 129: .Xr ucontext 2
1.1 wiz 130: .Sh STANDARDS
131: The
132: .Fn makecontext
133: and
134: .Fn swapcontext
135: functions conform to
1.8 jruoho 136: .St -xsh5
137: and
138: .St -p1003.1-2001 .
139: .Pp
140: The
1.9 ! jruoho 141: .St -p1003.1-2004
1.8 jruoho 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.
1.9 ! jruoho 149: The
! 150: .St -p1003.1-2008
! 151: revision removed the functions from the specification.
1.1 wiz 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 .
1.6 wiz 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).
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to makecontext.3 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / gen