-
Notifications
You must be signed in to change notification settings - Fork 0
/
getcontext.html
241 lines (192 loc) · 7.24 KB
/
getcontext.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
<!-- Creator : groff version 1.22.4 -->
<!-- CreationDate: Wed Jan 29 11:26:56 2020 -->
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta name="generator" content="groff -Thtml, see www.gnu.org">
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<meta name="Content-Style" content="text/css">
<style type="text/css">
p { margin-top: 0; margin-bottom: 0; vertical-align: top }
pre { margin-top: 0; margin-bottom: 0; vertical-align: top }
table { margin-top: 0; margin-bottom: 0; vertical-align: top }
h1 { text-align: center }
</style>
<title>GETCONTEXT</title>
</head>
<body>
<h1 align="center">GETCONTEXT</h1>
<a href="#NAME">NAME</a><br>
<a href="#SYNOPSIS">SYNOPSIS</a><br>
<a href="#DESCRIPTION">DESCRIPTION</a><br>
<a href="#RETURN VALUE">RETURN VALUE</a><br>
<a href="#ERRORS">ERRORS</a><br>
<a href="#ATTRIBUTES">ATTRIBUTES</a><br>
<a href="#CONFORMING TO">CONFORMING TO</a><br>
<a href="#NOTES">NOTES</a><br>
<a href="#SEE ALSO">SEE ALSO</a><br>
<a href="#COLOPHON">COLOPHON</a><br>
<hr>
<h2>NAME
<a name="NAME"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">getcontext,
setcontext - get or set the user context</p>
<h2>SYNOPSIS
<a name="SYNOPSIS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>#include
<ucontext.h></b></p>
<p style="margin-left:11%; margin-top: 1em"><b>int
getcontext(ucontext_t *</b><i>ucp</i><b>); <br>
int setcontext(const ucontext_t *</b><i>ucp</i><b>);</b></p>
<h2>DESCRIPTION
<a name="DESCRIPTION"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">In a System
V-like environment, one has the two types <i>mcontext_t</i>
and <i>ucontext_t</i> defined in <i><ucontext.h></i>
and the four functions <b>getcontext</b>(),
<b>setcontext</b>(), <b>makecontext</b>(3), and
<b>swapcontext</b>(3) that allow user-level context
switching between multiple threads of control within a
process.</p>
<p style="margin-left:11%; margin-top: 1em">The
<i>mcontext_t</i> type is machine-dependent and opaque. The
<i>ucontext_t</i> type is a structure that has at least the
following fields:</p>
<p style="margin-left:17%; margin-top: 1em">typedef struct
ucontext_t { <br>
struct ucontext_t *uc_link; <br>
sigset_t uc_sigmask; <br>
stack_t uc_stack; <br>
mcontext_t uc_mcontext; <br>
... <br>
} ucontext_t;</p>
<p style="margin-left:11%; margin-top: 1em">with
<i>sigset_t</i> and <i>stack_t</i> defined in
<i><signal.h></i>. Here <i>uc_link</i> points to the
context that will be resumed when the current context
terminates (in case the current context was created using
<b>makecontext</b>(3)), <i>uc_sigmask</i> is the set of
signals blocked in this context (see <b>sigprocmask</b>(2)),
<i>uc_stack</i> is the stack used by this context (see
<b>sigaltstack</b>(2)), and <i>uc_mcontext</i> is the
machine-specific representation of the saved context, that
includes the calling thread’s machine registers.</p>
<p style="margin-left:11%; margin-top: 1em">The function
<b>getcontext</b>() initializes the structure pointed at by
<i>ucp</i> to the currently active context.</p>
<p style="margin-left:11%; margin-top: 1em">The function
<b>setcontext</b>() restores the user context pointed at by
<i>ucp</i>. A successful call does not return. The context
should have been obtained by a call of <b>getcontext</b>(),
or <b>makecontext</b>(3), or passed as third argument to a
signal handler.</p>
<p style="margin-left:11%; margin-top: 1em">If the context
was obtained by a call of <b>getcontext</b>(), program
execution continues as if this call just returned.</p>
<p style="margin-left:11%; margin-top: 1em">If the context
was obtained by a call of <b>makecontext</b>(3), program
execution continues by a call to the function <i>func</i>
specified as the second argument of that call to
<b>makecontext</b>(3). When the function <i>func</i>
returns, we continue with the <i>uc_link</i> member of the
structure <i>ucp</i> specified as the first argument of that
call to <b>makecontext</b>(3). When this member is NULL, the
thread exits.</p>
<p style="margin-left:11%; margin-top: 1em">If the context
was obtained by a call to a signal handler, then old
standard text says that "program execution continues
with the program instruction following the instruction
interrupted by the signal". However, this sentence was
removed in SUSv2, and the present verdict is "the
result is unspecified".</p>
<h2>RETURN VALUE
<a name="RETURN VALUE"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">When
successful, <b>getcontext</b>() returns 0 and
<b>setcontext</b>() does not return. On error, both return
-1 and set <i>errno</i> appropriately.</p>
<h2>ERRORS
<a name="ERRORS"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">None
defined.</p>
<h2>ATTRIBUTES
<a name="ATTRIBUTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">For an
explanation of the terms used in this section, see
<b>attributes</b>(7).</p>
<table width="100%" border="0" rules="none" frame="void"
cellspacing="0" cellpadding="0">
<tr valign="top" align="left">
<td width="8%"></td>
<td width="7%">
</td>
<td width="8%">
</td>
<td width="8%"></td>
<td width="7%"></td>
<td width="62%">
</td></tr>
<tr valign="top" align="left">
<td width="8%"></td>
<td width="7%"></td>
<td width="8%">
</td>
<td width="8%"></td>
<td width="7%"></td>
<td width="62%">
</td></tr>
</table>
<p align="center"><img src="grohtml-546561.png" alt="Image grohtml-546561.png"></p>
<h2>CONFORMING TO
<a name="CONFORMING TO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">SUSv2,
POSIX.1-2001. POSIX.1-2008 removes the specification of
<b>getcontext</b>(), citing portability issues, and
recommending that applications be rewritten to use POSIX
threads instead.</p>
<h2>NOTES
<a name="NOTES"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">The earliest
incarnation of this mechanism was the
<b>setjmp</b>(3)/<b>longjmp</b>(3) mechanism. Since that
does not define the handling of the signal context, the next
stage was the <b>sigsetjmp</b>(3)/<b>siglongjmp</b>(3) pair.
The present mechanism gives much more control. On the other
hand, there is no easy way to detect whether a return from
<b>getcontext</b>() is from the first call, or via a
<b>setcontext</b>() call. The user has to invent their own
bookkeeping device, and a register variable won’t do
since registers are restored.</p>
<p style="margin-left:11%; margin-top: 1em">When a signal
occurs, the current user context is saved and a new context
is created by the kernel for the signal handler. Do not
leave the handler using <b>longjmp</b>(3): it is undefined
what would happen with contexts. Use <b>siglongjmp</b>(3) or
<b>setcontext</b>() instead.</p>
<h2>SEE ALSO
<a name="SEE ALSO"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em"><b>sigaction</b>(2),
<b>sigaltstack</b>(2), <b>sigprocmask</b>(2),
<b>longjmp</b>(3), <b>makecontext</b>(3),
<b>sigsetjmp</b>(3)</p>
<h2>COLOPHON
<a name="COLOPHON"></a>
</h2>
<p style="margin-left:11%; margin-top: 1em">This page is
part of release 5.02 of the Linux <i>man-pages</i> project.
A description of the project, information about reporting
bugs, and the latest version of this page, can be found at
https://www.kernel.org/doc/man-pages/.</p>
<hr>
</body>
</html>