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