1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
3 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
4 .\" http://www.opengroup.org/bookstore/.
5 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
6 .\" This notice shall appear on any product containing this material.
7 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
8 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
9 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
10 .TH GETCONTEXT 2 "Feb 5, 2001"
11 .SH NAME
12 getcontext, setcontext \- get and set current user context
13 .SH SYNOPSIS
14 .LP
15 .nf
16 #include <ucontext.h>
17
18 \fBint\fR \fBgetcontext\fR(\fBucontext_t *\fR\fIucp\fR);
19 .fi
20
21 .LP
22 .nf
23 \fBint\fR \fBsetcontext\fR(\fBconst ucontext_t *\fR\fIucp\fR);
24 .fi
25
26 .SH DESCRIPTION
27 .sp
28 .LP
29 The \fBgetcontext()\fR function initializes the structure pointed to by
30 \fIucp\fR to the current user context of the calling process. The
31 \fBucontext_t\fR type that \fIucp\fR points to defines the user context and
32 includes the contents of the calling process' machine registers, the signal
33 mask, and the current execution stack.
34 .sp
35 .LP
36 The \fBsetcontext()\fR function restores the user context pointed to by
37 \fIucp\fR. A successful call to \fBsetcontext()\fR does not return; program
38 execution resumes at the point specified by the \fIucp\fR argument passed to
39 \fBsetcontext()\fR. The \fIucp\fR argument should be created either by a prior
40 call to \fBgetcontext()\fR, or by being passed as an argument to a signal
41 handler. If the \fIucp\fR argument was created with \fBgetcontext()\fR, program
42 execution continues as if the corresponding call of \fBgetcontext()\fR had just
43 returned. If the \fIucp\fR argument was created with \fBmakecontext\fR(3C),
44 program execution continues with the function passed to \fBmakecontext\fR(3C).
45 When that function returns, the process continues as if after a call to
46 \fBsetcontext()\fR with the \fIucp\fR argument that was input to
47 \fBmakecontext\fR(3C). If the \fIucp\fR argument was passed to a signal
48 handler, program execution continues with the program instruction following the
49 instruction interrupted by the signal. If the \fBuc_link\fR member of the
50 \fBucontext_t\fR structure pointed to by the \fIucp\fR argument is equal to 0,
51 then this context is the main context, and the process will exit when this
52 context returns. The effects of passing a \fIucp\fR argument obtained from any
53 other source are unspecified.
54 .SH RETURN VALUES
55 .sp
56 .LP
57 On successful completion, \fBsetcontext()\fR does not return and
58 \fBgetcontext()\fR returns \fB0\fR. Otherwise, \fB\(mi1\fR is returned.
59 .SH ERRORS
60 .sp
61 .LP
62 No errors are defined.
63 .SH USAGE
64 .sp
65 .LP
66 When a signal handler is executed, the current user context is saved and a new
67 context is created. If the thread leaves the signal handler via
68 \fBlongjmp\fR(3UCB), then it is unspecified whether the context at the time of
69 the corresponding \fBsetjmp\fR(3UCB) call is restored and thus whether future
70 calls to \fBgetcontext()\fR will provide an accurate representation of the
71 current context, since the context restored by \fBlongjmp\fR(3UCB) may not
72 contain all the information that \fBsetcontext()\fR requires. Signal handlers
73 should use \fBsiglongjmp\fR(3C) instead.
74 .sp
75 .LP
76 Portable applications should not modify or access the \fBuc_mcontext\fR member
77 of \fBucontext_t\fR. A portable application cannot assume that context
78 includes any process-wide static data, possibly including \fBerrno\fR. Users
79 manipulating contexts should take care to handle these explicitly when
80 required.
81 .SH ATTRIBUTES
82 .sp
83 .LP
84 See \fBattributes\fR(5) for descriptions of the following attributes:
85 .sp
86
87 .sp
88 .TS
89 box;
90 c | c
91 l | l .
92 ATTRIBUTE TYPE ATTRIBUTE VALUE
93 _
94 Interface Stability Standard
95 .TE
96
97 .SH SEE ALSO
98 .sp
99 .LP
100 \fBsigaction\fR(2), \fBsigaltstack\fR(2), \fBsigprocmask\fR(2),
101 \fBbsd_signal\fR(3C), \fBmakecontext\fR(3C), \fBsetjmp\fR(3UCB),
102 \fBsigsetjmp\fR(3C), \fBucontext.h\fR(3HEAD), \fBattributes\fR(5),
103 \fBstandards\fR(5)
|
1 .\" Copyright 1989 AT&T Copyright (c) 2001, Sun Microsystems, Inc. All Rights Reserved Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
3 .\" http://www.opengroup.org/bookstore/.
4 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
5 .\" This notice shall appear on any product containing this material.
6 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
8 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
9 .Dd "Jul 20, 2014"
10 .Dt GETCONTEXT 2
11 .Os
12 .Sh NAME
13 .Nm getcontext, setcontext
14 .Nd get and set current user context
15 .Sh SYNOPSIS
16 .In ucontext.h
17 .Ft int
18 .Fn getcontext "ucontext_t *ucp"
19 .Ft int
20 .Fn setcontext "const ucontext_t *ucp"
21 .Sh DESCRIPTION
22 The
23 .Fn getcontext
24 function initializes the structure pointed to by
25 .Fa ucp
26 to the current user context of the calling process. The
27 .Fa ucontext_t
28 type that
29 .Fa ucp
30 points to defines the user context and
31 includes the contents of the calling process' machine registers, the signal
32 mask, and the current execution stack.
33 .Lp
34 The
35 .Fn setcontext
36 function restores the user context pointed to by
37 .Fa ucp .
38 A successful call to
39 .Fn setcontext
40 does not return; program
41 execution resumes at the point specified by the
42 .Fa ucp
43 argument passed to
44 .Fn setcontext .
45 The
46 .Fa ucp
47 argument should be created either by a prior
48 call to
49 .Fn getcontext ,
50 or by being passed as an argument to a signal
51 handler.
52 .Lp
53 If the
54 .Fa ucp
55 argument was created with
56 .Fn getcontext ,
57 program execution continues as if the corresponding call of
58 .Fn getcontext
59 had just returned.
60 .Lp
61 If the
62 .Fa ucp
63 argument was created with
64 .Xr makecontext 3C ,
65 program execution continues with the function passed to
66 .Xr makecontext 3C .
67 When that function returns, the process continues as if after a call to
68 .Fn setcontext
69 with the
70 .Fa ucp
71 argument that was input to
72 .Xr makecontext 3C .
73 .Lp
74 If the
75 .Fa ucp
76 argument was passed to a signal
77 handler, program execution continues with the program instruction following the
78 instruction interrupted by the signal.
79 .Lp
80 If the
81 .Fa uc_link
82 member of the
83 .Ft ucontext_t
84 structure pointed to by the
85 .Fa ucp
86 argument is equal to 0,
87 then this context is the main context, and the process will exit when this
88 context returns. The effects of passing a
89 .Fa ucp
90 argument obtained from any other source are unspecified.
91 .Sh RETURN VALUES
92 On successful completion,
93 .Fn setcontext
94 does not return and
95 .Fn getcontext()
96 returns 0. Otherwise, -1 is returned.
97 .Sh ERRORS
98 No errors are defined.
99 .Sh USAGE
100 When a signal handler is executed, the current user context is saved and a new
101 context is created. If the thread leaves the signal handler via
102 .Xr longjmp 3C ,
103 then it is unspecified whether the context at the time of
104 the corresponding
105 .Xr setjmp 3C
106 call is restored and thus whether future
107 calls to
108 .Fn getcontext
109 will provide an accurate representation of the
110 current context, since the context restored by
111 .Xr longjmp 3C
112 may not contain all the information that
113 .Fn setcontext
114 requires. Signal handlers
115 should use
116 .Xr siglongjmp 3C
117 instead.
118 .Lp
119 Portable applications should not modify or access the
120 .Fa uc_mcontext
121 member
122 of
123 .Ft ucontext_t .
124 A portable application cannot assume that context
125 includes any process-wide static data, possibly including
126 .Va errno .
127 Users manipulating contexts should take care to handle these explicitly when
128 required.
129 .Lp
130 Portable applications should make use of the
131 .Xr pthreads 5
132 routines for co-processing instead of these routines.
133 .Sh INTERFACE STABILITY
134 .Sy Obsolete Standard .
135 .Sh SEE ALSO
136 .Xr sigaction 2 ,
137 .Xr sigaltstack 2 ,
138 .Xr sigprocmask 2 ,
139 .Xr bsd_signal 3C ,
140 .Xr makecontext 3C ,
141 .Xr setjmp 3C ,
142 .Xr sigsetjmp 3C ,
143 .Xr ucontext.h 3HEAD ,
144 .Xr pthreads 5 ,
145 .Xr standards 5
146 .Sh STANDARDS
147 These routines were introduced in
148 .St -xpg4.2
149 and subsequently removed in
150 .St -p1003.1-2008 .
|