]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
c13182ef | 11 | .\" |
fea681da MK |
12 | .\" Since the Linux kernel and libraries are constantly changing, this |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
c13182ef | 19 | .\" |
fea681da MK |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .TH GETCONTEXT 2 2001-11-15 "Linux 2.4" "Linux Programmer's Manual" | |
24 | .SH NAME | |
25 | getcontext, setcontext \- get or set the user context | |
26 | .SH SYNOPSIS | |
27 | .B #include <ucontext.h> | |
28 | .sp | |
29 | .BI "int getcontext(ucontext_t *" ucp ); | |
30 | .br | |
31 | .BI "int setcontext(const ucontext_t *" ucp ); | |
32 | .SH DESCRIPTION | |
aa651b39 | 33 | In a System V-like environment, one has the two types |
ef0b8171 | 34 | \fImcontext_t\fP and \fIucontext_t\fP defined in |
fea681da MK |
35 | .I <ucontext.h> |
36 | and the four functions | |
63aa9df0 MK |
37 | \fBgetcontext\fP(), \fBsetcontext\fP(), \fBmakecontext\fP() |
38 | and \fBswapcontext\fP() | |
fea681da MK |
39 | that allow user-level context switching between multiple |
40 | threads of control within a process. | |
41 | .LP | |
53560326 MK |
42 | The \fImcontext_t\fP type is machine-dependent and opaque. |
43 | The \fIucontext_t\fP type is a structure that has at least | |
fea681da MK |
44 | the following fields: |
45 | .RS | |
46 | .nf | |
68ed2733 | 47 | |
fea681da | 48 | typedef struct ucontext { |
68ed2733 MK |
49 | struct ucontext *uc_link; |
50 | sigset_t uc_sigmask; | |
51 | stack_t uc_stack; | |
52 | mcontext_t uc_mcontext; | |
53 | ... | |
fea681da | 54 | } ucontext_t; |
68ed2733 | 55 | |
fea681da MK |
56 | .fi |
57 | .RE | |
68ed2733 | 58 | with \fIsigset_t\fP and \fIstack_t\fP defined in |
fea681da MK |
59 | .IR <signal.h> . |
60 | Here \fIuc_link\fP points to the context that will be resumed | |
61 | when the current context terminates (in case the current context | |
63aa9df0 | 62 | was created using \fBmakecontext\fP()), \fIuc_sigmask\fP is the |
fea681da MK |
63 | set of signals blocked in this context (see |
64 | .BR sigprocmask (2)), | |
65 | \fIuc_stack\fP is the stack used by this context (see | |
66 | .BR sigaltstack (2)), | |
67 | and \fIuc_mcontext\fP is the | |
68 | machine-specific representation of the saved context, | |
69 | that includes the calling thread's machine registers. | |
70 | .LP | |
63aa9df0 | 71 | The function \fBgetcontext\fP() initializes the structure |
fea681da MK |
72 | pointed at by \fIucp\fP to the currently active context. |
73 | .LP | |
63aa9df0 | 74 | The function \fBsetcontext\fP() restores the user context |
c13182ef MK |
75 | pointed at by \fIucp\fP. |
76 | A successful call does not return. | |
63aa9df0 MK |
77 | The context should have been obtained by a call of \fBgetcontext\fP(), |
78 | or \fBmakecontext\fP(), or passed as third argument to a signal | |
fea681da MK |
79 | handler. |
80 | .LP | |
63aa9df0 | 81 | If the context was obtained by a call of \fBgetcontext\fP(), |
fea681da MK |
82 | program execution continues as if this call just returned. |
83 | .LP | |
63aa9df0 | 84 | If the context was obtained by a call of \fBmakecontext\fP(), |
fea681da | 85 | program execution continues by a call to the function \fIfunc\fP |
63aa9df0 | 86 | specified as the second argument of that call to \fBmakecontext\fP(). |
fea681da MK |
87 | When the function \fIfunc\fP returns, we continue with the |
88 | \fIuc_link\fP member of the structure \fIucp\fP specified as the | |
63aa9df0 | 89 | first argument of that call to \fBmakecontext\fP(). |
fea681da MK |
90 | When this member is NULL, the thread exits. |
91 | .LP | |
92 | If the context was obtained by a call to a signal handler, | |
93 | then old standard text says that "program execution continues with the | |
94 | program instruction following the instruction interrupted | |
c13182ef MK |
95 | by the signal". |
96 | However, this sentence was removed in SUSv2, | |
fea681da MK |
97 | and the present verdict is "the result is unspecified". |
98 | .SH "RETURN VALUE" | |
63aa9df0 | 99 | When successful, \fBgetcontext\fP() returns 0 and \fBsetcontext\fP() |
c13182ef MK |
100 | does not return. |
101 | On error, both return \-1 and set \fIerrno\fP | |
fea681da MK |
102 | appropriately. |
103 | .SH ERRORS | |
104 | None defined. | |
105 | .SH NOTES | |
106 | The earliest incarnation of this mechanism was the | |
c13182ef MK |
107 | \fIsetjmp\fP()/\fIlongjmp\fP() mechanism. |
108 | Since that does not define | |
fea681da | 109 | the handling of the signal context, the next stage was the |
63aa9df0 | 110 | \fIsigsetjmp\fP()/\fIsiglongjmp\fP() pair. |
c13182ef MK |
111 | The present mechanism gives much more control. |
112 | On the other hand, | |
63aa9df0 MK |
113 | there is no easy way to detect whether a return from \fBgetcontext\fP() |
114 | is from the first call, or via a \fBsetcontext\fP() call. | |
fea681da MK |
115 | The user has to invent her own bookkeeping device, and a register |
116 | variable won't do since registers are restored. | |
117 | .LP | |
118 | When a signal occurs, the current user context is saved and | |
119 | a new context is created by the kernel for the signal handler. | |
63aa9df0 | 120 | Do not leave the handler using \fIlongjmp\fP(): it is undefined |
c13182ef MK |
121 | what would happen with contexts. |
122 | Use \fIsiglongjmp\fP() or | |
63aa9df0 | 123 | \fIsetcontext\fP() instead. |
fea681da | 124 | .SH "CONFORMING TO" |
97c1eac8 | 125 | SUSv2, POSIX.1-2001. |
fea681da MK |
126 | .SH "SEE ALSO" |
127 | .BR sigaction (2), | |
128 | .BR sigaltstack (2), | |
129 | .BR sigprocmask (2), | |
130 | .BR longjmp (3), | |
131 | .BR makecontext (3), | |
132 | .BR sigsetjmp (3) |