]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
fea681da MK |
2 | .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
fea681da | 5 | .\" |
4c1c5274 | 6 | .TH getcontext 3 (date) "Linux man-pages (unreleased)" |
fea681da MK |
7 | .SH NAME |
8 | getcontext, setcontext \- get or set the user context | |
cfba38f4 AC |
9 | .SH LIBRARY |
10 | Standard C library | |
11 | .RI ( libc ", " \-lc ) | |
fea681da | 12 | .SH SYNOPSIS |
c7db92b9 | 13 | .nf |
fea681da | 14 | .B #include <ucontext.h> |
c6d039a3 | 15 | .P |
fea681da | 16 | .BI "int getcontext(ucontext_t *" ucp ); |
fea681da | 17 | .BI "int setcontext(const ucontext_t *" ucp ); |
c7db92b9 | 18 | .fi |
fea681da | 19 | .SH DESCRIPTION |
aa651b39 | 20 | In a System V-like environment, one has the two types |
c6fa0841 MK |
21 | .I mcontext_t |
22 | and | |
23 | .I ucontext_t | |
24 | defined in | |
fea681da MK |
25 | .I <ucontext.h> |
26 | and the four functions | |
60a90ecd MK |
27 | .BR getcontext (), |
28 | .BR setcontext (), | |
9af134cd | 29 | .BR makecontext (3), |
60a90ecd MK |
30 | and |
31 | .BR swapcontext (3) | |
fea681da MK |
32 | that allow user-level context switching between multiple |
33 | threads of control within a process. | |
c6d039a3 | 34 | .P |
c6fa0841 MK |
35 | The |
36 | .I mcontext_t | |
37 | type is machine-dependent and opaque. | |
38 | The | |
39 | .I ucontext_t | |
40 | type is a structure that has at least | |
fea681da | 41 | the following fields: |
c6d039a3 | 42 | .P |
161b8eda | 43 | .in +4n |
207050fa | 44 | .EX |
0d4f6d6f CD |
45 | typedef struct ucontext_t { |
46 | struct ucontext_t *uc_link; | |
47 | sigset_t uc_sigmask; | |
48 | stack_t uc_stack; | |
49 | mcontext_t uc_mcontext; | |
68ed2733 | 50 | ... |
fea681da | 51 | } ucontext_t; |
e646a1ba | 52 | .EE |
187339e6 | 53 | .in |
c6d039a3 | 54 | .P |
c6fa0841 | 55 | with |
1ae6b2c7 | 56 | .I sigset_t |
c6fa0841 MK |
57 | and |
58 | .I stack_t | |
59 | defined in | |
fea681da | 60 | .IR <signal.h> . |
c6fa0841 MK |
61 | Here |
62 | .I uc_link | |
63 | points to the context that will be resumed | |
fea681da | 64 | when the current context terminates (in case the current context |
60a90ecd MK |
65 | was created using |
66 | .BR makecontext (3)), | |
c6fa0841 MK |
67 | .I uc_sigmask |
68 | is the | |
fea681da MK |
69 | set of signals blocked in this context (see |
70 | .BR sigprocmask (2)), | |
c6fa0841 MK |
71 | .I uc_stack |
72 | is the stack used by this context (see | |
fea681da | 73 | .BR sigaltstack (2)), |
c6fa0841 MK |
74 | and |
75 | .I uc_mcontext | |
76 | is the | |
fea681da MK |
77 | machine-specific representation of the saved context, |
78 | that includes the calling thread's machine registers. | |
c6d039a3 | 79 | .P |
60a90ecd MK |
80 | The function |
81 | .BR getcontext () | |
82 | initializes the structure | |
1680bd6e | 83 | pointed to by |
c6fa0841 MK |
84 | .I ucp |
85 | to the currently active context. | |
c6d039a3 | 86 | .P |
60a90ecd MK |
87 | The function |
88 | .BR setcontext () | |
89 | restores the user context | |
1680bd6e | 90 | pointed to by |
c6fa0841 | 91 | .IR ucp . |
c13182ef | 92 | A successful call does not return. |
60a90ecd MK |
93 | The context should have been obtained by a call of |
94 | .BR getcontext (), | |
95 | or | |
96 | .BR makecontext (3), | |
2f296977 | 97 | or received as the third argument to a signal |
e7a5700f | 98 | handler (see the discussion of the |
1ae6b2c7 | 99 | .B SA_SIGINFO |
2f296977 MK |
100 | flag in |
101 | .BR sigaction (2)). | |
c6d039a3 | 102 | .P |
60a90ecd MK |
103 | If the context was obtained by a call of |
104 | .BR getcontext (), | |
fea681da | 105 | program execution continues as if this call just returned. |
c6d039a3 | 106 | .P |
60a90ecd MK |
107 | If the context was obtained by a call of |
108 | .BR makecontext (3), | |
c6fa0841 MK |
109 | program execution continues by a call to the function |
110 | .I func | |
60a90ecd MK |
111 | specified as the second argument of that call to |
112 | .BR makecontext (3). | |
c6fa0841 MK |
113 | When the function |
114 | .I func | |
115 | returns, we continue with the | |
116 | .I uc_link | |
117 | member of the structure | |
118 | .I ucp | |
119 | specified as the | |
60a90ecd MK |
120 | first argument of that call to |
121 | .BR makecontext (3). | |
fea681da | 122 | When this member is NULL, the thread exits. |
c6d039a3 | 123 | .P |
fea681da MK |
124 | If the context was obtained by a call to a signal handler, |
125 | then old standard text says that "program execution continues with the | |
126 | program instruction following the instruction interrupted | |
c13182ef MK |
127 | by the signal". |
128 | However, this sentence was removed in SUSv2, | |
fea681da | 129 | and the present verdict is "the result is unspecified". |
47297adb | 130 | .SH RETURN VALUE |
60a90ecd MK |
131 | When successful, |
132 | .BR getcontext () | |
133 | returns 0 and | |
134 | .BR setcontext () | |
c13182ef | 135 | does not return. |
c6fa0841 MK |
136 | On error, both return \-1 and set |
137 | .I errno | |
f6a4078b | 138 | to indicate the error. |
fea681da MK |
139 | .SH ERRORS |
140 | None defined. | |
9ac2ef83 | 141 | .SH ATTRIBUTES |
9f9d1e7d MK |
142 | For an explanation of the terms used in this section, see |
143 | .BR attributes (7). | |
144 | .TS | |
145 | allbox; | |
c466875e | 146 | lbx lb lb |
9f9d1e7d MK |
147 | l l l. |
148 | Interface Attribute Value | |
149 | T{ | |
9e54434e BR |
150 | .na |
151 | .nh | |
9f9d1e7d | 152 | .BR getcontext (), |
9ac2ef83 | 153 | .BR setcontext () |
0532163b | 154 | T} Thread safety MT-Safe race:ucp |
9f9d1e7d | 155 | .TE |
3113c7f3 | 156 | .SH STANDARDS |
4131356c AC |
157 | None. |
158 | .SH HISTORY | |
a1d5f77c | 159 | SUSv2, POSIX.1-2001. |
c6d039a3 | 160 | .P |
4131356c | 161 | POSIX.1-2008 removes these functions, |
bd314baf MK |
162 | citing portability issues, and |
163 | recommending that applications be rewritten to use POSIX threads instead. | |
fea681da MK |
164 | .SH NOTES |
165 | The earliest incarnation of this mechanism was the | |
998e8717 AC |
166 | .BR setjmp (3)/\c |
167 | .BR longjmp (3) | |
d9c1ae64 | 168 | mechanism. |
c13182ef | 169 | Since that does not define |
fea681da | 170 | the handling of the signal context, the next stage was the |
998e8717 AC |
171 | .BR sigsetjmp (3)/\c |
172 | .BR siglongjmp (3) | |
d9c1ae64 | 173 | pair. |
c13182ef MK |
174 | The present mechanism gives much more control. |
175 | On the other hand, | |
60a90ecd MK |
176 | there is no easy way to detect whether a return from |
177 | .BR getcontext () | |
178 | is from the first call, or via a | |
179 | .BR setcontext () | |
180 | call. | |
60ae21db | 181 | The user has to invent their own bookkeeping device, and a register |
fea681da | 182 | variable won't do since registers are restored. |
c6d039a3 | 183 | .P |
fea681da MK |
184 | When a signal occurs, the current user context is saved and |
185 | a new context is created by the kernel for the signal handler. | |
d9c1ae64 MK |
186 | Do not leave the handler using |
187 | .BR longjmp (3): | |
188 | it is undefined what would happen with contexts. | |
189 | Use | |
190 | .BR siglongjmp (3) | |
191 | or | |
192 | .BR setcontext () | |
193 | instead. | |
47297adb | 194 | .SH SEE ALSO |
fea681da MK |
195 | .BR sigaction (2), |
196 | .BR sigaltstack (2), | |
197 | .BR sigprocmask (2), | |
198 | .BR longjmp (3), | |
199 | .BR makecontext (3), | |
3a382549 MK |
200 | .BR sigsetjmp (3), |
201 | .BR signal (7) |