]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one. | |
c13182ef | 12 | .\" |
fea681da MK |
13 | .\" Since the Linux kernel and libraries are constantly changing, this |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
16 | .\" the use of the information contained herein. The author(s) may not | |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
c13182ef | 20 | .\" |
fea681da MK |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da | 24 | .\" |
4b8c67d9 | 25 | .TH GETCONTEXT 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da MK |
26 | .SH NAME |
27 | getcontext, setcontext \- get or set the user context | |
28 | .SH SYNOPSIS | |
29 | .B #include <ucontext.h> | |
68e4db0a | 30 | .PP |
fea681da MK |
31 | .BI "int getcontext(ucontext_t *" ucp ); |
32 | .br | |
33 | .BI "int setcontext(const ucontext_t *" ucp ); | |
34 | .SH DESCRIPTION | |
aa651b39 | 35 | In a System V-like environment, one has the two types |
c6fa0841 MK |
36 | .I mcontext_t |
37 | and | |
38 | .I ucontext_t | |
39 | defined in | |
fea681da MK |
40 | .I <ucontext.h> |
41 | and the four functions | |
60a90ecd MK |
42 | .BR getcontext (), |
43 | .BR setcontext (), | |
9af134cd | 44 | .BR makecontext (3), |
60a90ecd MK |
45 | and |
46 | .BR swapcontext (3) | |
fea681da MK |
47 | that allow user-level context switching between multiple |
48 | threads of control within a process. | |
dd3568a1 | 49 | .PP |
c6fa0841 MK |
50 | The |
51 | .I mcontext_t | |
52 | type is machine-dependent and opaque. | |
53 | The | |
54 | .I ucontext_t | |
55 | type is a structure that has at least | |
fea681da | 56 | the following fields: |
207050fa | 57 | .PP |
187339e6 | 58 | .in +4 |
207050fa | 59 | .EX |
0d4f6d6f CD |
60 | typedef struct ucontext_t { |
61 | struct ucontext_t *uc_link; | |
62 | sigset_t uc_sigmask; | |
63 | stack_t uc_stack; | |
64 | mcontext_t uc_mcontext; | |
68ed2733 | 65 | ... |
fea681da | 66 | } ucontext_t; |
e646a1ba | 67 | .EE |
187339e6 | 68 | .in |
e646a1ba | 69 | .PP |
c6fa0841 | 70 | with |
51700fd7 | 71 | .IR sigset_t |
c6fa0841 MK |
72 | and |
73 | .I stack_t | |
74 | defined in | |
fea681da | 75 | .IR <signal.h> . |
c6fa0841 MK |
76 | Here |
77 | .I uc_link | |
78 | points to the context that will be resumed | |
fea681da | 79 | when the current context terminates (in case the current context |
60a90ecd MK |
80 | was created using |
81 | .BR makecontext (3)), | |
c6fa0841 MK |
82 | .I uc_sigmask |
83 | is the | |
fea681da MK |
84 | set of signals blocked in this context (see |
85 | .BR sigprocmask (2)), | |
c6fa0841 MK |
86 | .I uc_stack |
87 | is the stack used by this context (see | |
fea681da | 88 | .BR sigaltstack (2)), |
c6fa0841 MK |
89 | and |
90 | .I uc_mcontext | |
91 | is the | |
fea681da MK |
92 | machine-specific representation of the saved context, |
93 | that includes the calling thread's machine registers. | |
dd3568a1 | 94 | .PP |
60a90ecd MK |
95 | The function |
96 | .BR getcontext () | |
97 | initializes the structure | |
c6fa0841 MK |
98 | pointed at by |
99 | .I ucp | |
100 | to the currently active context. | |
dd3568a1 | 101 | .PP |
60a90ecd MK |
102 | The function |
103 | .BR setcontext () | |
104 | restores the user context | |
c6fa0841 MK |
105 | pointed at by |
106 | .IR ucp . | |
c13182ef | 107 | A successful call does not return. |
60a90ecd MK |
108 | The context should have been obtained by a call of |
109 | .BR getcontext (), | |
110 | or | |
111 | .BR makecontext (3), | |
112 | or passed as third argument to a signal | |
fea681da | 113 | handler. |
dd3568a1 | 114 | .PP |
60a90ecd MK |
115 | If the context was obtained by a call of |
116 | .BR getcontext (), | |
fea681da | 117 | program execution continues as if this call just returned. |
dd3568a1 | 118 | .PP |
60a90ecd MK |
119 | If the context was obtained by a call of |
120 | .BR makecontext (3), | |
c6fa0841 MK |
121 | program execution continues by a call to the function |
122 | .I func | |
60a90ecd MK |
123 | specified as the second argument of that call to |
124 | .BR makecontext (3). | |
c6fa0841 MK |
125 | When the function |
126 | .I func | |
127 | returns, we continue with the | |
128 | .I uc_link | |
129 | member of the structure | |
130 | .I ucp | |
131 | specified as the | |
60a90ecd MK |
132 | first argument of that call to |
133 | .BR makecontext (3). | |
fea681da | 134 | When this member is NULL, the thread exits. |
dd3568a1 | 135 | .PP |
fea681da MK |
136 | If the context was obtained by a call to a signal handler, |
137 | then old standard text says that "program execution continues with the | |
138 | program instruction following the instruction interrupted | |
c13182ef MK |
139 | by the signal". |
140 | However, this sentence was removed in SUSv2, | |
fea681da | 141 | and the present verdict is "the result is unspecified". |
47297adb | 142 | .SH RETURN VALUE |
60a90ecd MK |
143 | When successful, |
144 | .BR getcontext () | |
145 | returns 0 and | |
146 | .BR setcontext () | |
c13182ef | 147 | does not return. |
c6fa0841 MK |
148 | On error, both return \-1 and set |
149 | .I errno | |
fea681da MK |
150 | appropriately. |
151 | .SH ERRORS | |
152 | None defined. | |
9ac2ef83 | 153 | .SH ATTRIBUTES |
9f9d1e7d MK |
154 | For an explanation of the terms used in this section, see |
155 | .BR attributes (7). | |
156 | .TS | |
157 | allbox; | |
158 | lbw26 lb lb | |
159 | l l l. | |
160 | Interface Attribute Value | |
161 | T{ | |
162 | .BR getcontext (), | |
9ac2ef83 | 163 | .BR setcontext () |
0532163b | 164 | T} Thread safety MT-Safe race:ucp |
9f9d1e7d | 165 | .TE |
47297adb | 166 | .SH CONFORMING TO |
a1d5f77c | 167 | SUSv2, POSIX.1-2001. |
bd314baf MK |
168 | POSIX.1-2008 removes the specification of |
169 | .BR getcontext (), | |
170 | citing portability issues, and | |
171 | recommending that applications be rewritten to use POSIX threads instead. | |
fea681da MK |
172 | .SH NOTES |
173 | The earliest incarnation of this mechanism was the | |
988db661 | 174 | .BR setjmp (3)/ longjmp (3) |
d9c1ae64 | 175 | mechanism. |
c13182ef | 176 | Since that does not define |
fea681da | 177 | the handling of the signal context, the next stage was the |
988db661 | 178 | .BR sigsetjmp (3)/ siglongjmp (3) |
d9c1ae64 | 179 | pair. |
c13182ef MK |
180 | The present mechanism gives much more control. |
181 | On the other hand, | |
60a90ecd MK |
182 | there is no easy way to detect whether a return from |
183 | .BR getcontext () | |
184 | is from the first call, or via a | |
185 | .BR setcontext () | |
186 | call. | |
fea681da MK |
187 | The user has to invent her own bookkeeping device, and a register |
188 | variable won't do since registers are restored. | |
dd3568a1 | 189 | .PP |
fea681da MK |
190 | When a signal occurs, the current user context is saved and |
191 | a new context is created by the kernel for the signal handler. | |
d9c1ae64 MK |
192 | Do not leave the handler using |
193 | .BR longjmp (3): | |
194 | it is undefined what would happen with contexts. | |
195 | Use | |
196 | .BR siglongjmp (3) | |
197 | or | |
198 | .BR setcontext () | |
199 | instead. | |
47297adb | 200 | .SH SEE ALSO |
fea681da MK |
201 | .BR sigaction (2), |
202 | .BR sigaltstack (2), | |
203 | .BR sigprocmask (2), | |
204 | .BR longjmp (3), | |
205 | .BR makecontext (3), | |
206 | .BR sigsetjmp (3) |