1GETCONTEXT(3)              Linux Programmer's Manual             GETCONTEXT(3)
2
3
4

NAME

6       getcontext, setcontext - get or set the user context
7

SYNOPSIS

9       #include <ucontext.h>
10
11       int getcontext(ucontext_t *ucp);
12       int setcontext(const ucontext_t *ucp);
13

DESCRIPTION

15       In  a  System  V-like environment, one has the two types mcontext_t and
16       ucontext_t defined in <ucontext.h> and the four functions getcontext(),
17       setcontext(),  makecontext(3), and swapcontext(3) that allow user-level
18       context switching between multiple threads of control within a process.
19
20       The mcontext_t type is machine-dependent and  opaque.   The  ucontext_t
21       type is a structure that has at least the following fields:
22
23           typedef struct ucontext_t {
24               struct ucontext_t *uc_link;
25               sigset_t          uc_sigmask;
26               stack_t           uc_stack;
27               mcontext_t        uc_mcontext;
28               ...
29           } ucontext_t;
30
31       with  sigset_t  and stack_t defined in <signal.h>.  Here uc_link points
32       to the context that will be resumed when the current context terminates
33       (in case the current context was created using makecontext(3)), uc_sig‐
34       mask is the set of  signals  blocked  in  this  context  (see  sigproc‐
35       mask(2)),  uc_stack  is  the  stack  used  by this context (see sigalt‐
36       stack(2)), and uc_mcontext is the  machine-specific  representation  of
37       the  saved  context,  that includes the calling thread's machine regis‐
38       ters.
39
40       The function getcontext() initializes the structure pointed to  by  ucp
41       to the currently active context.
42
43       The  function setcontext() restores the user context pointed to by ucp.
44       A successful call does not return.  The context should  have  been  ob‐
45       tained by a call of getcontext(), or makecontext(3), or received as the
46       third argument to a signal handler (see the discussion of  the  SA_SIG‐
47       INFO flag in sigaction(2)).
48
49       If  the  context was obtained by a call of getcontext(), program execu‐
50       tion continues as if this call just returned.
51
52       If the context was obtained by a call of makecontext(3), program execu‐
53       tion  continues  by a call to the function func specified as the second
54       argument of that call to makecontext(3).  When the  function  func  re‐
55       turns,  we continue with the uc_link member of the structure ucp speci‐
56       fied as the first argument of that call to makecontext(3).   When  this
57       member is NULL, the thread exits.
58
59       If  the  context  was  obtained by a call to a signal handler, then old
60       standard text says that "program execution continues with  the  program
61       instruction following the instruction interrupted by the signal".  How‐
62       ever, this sentence was removed in SUSv2, and the  present  verdict  is
63       "the result is unspecified".
64

RETURN VALUE

66       When  successful,  getcontext() returns 0 and setcontext() does not re‐
67       turn.  On error, both return -1 and set errno to indicate the error.
68

ERRORS

70       None defined.
71

ATTRIBUTES

73       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
74       tributes(7).
75
76       ┌───────────────────────────────────┬───────────────┬──────────────────┐
77Interface                          Attribute     Value            
78       ├───────────────────────────────────┼───────────────┼──────────────────┤
79getcontext(), setcontext()         │ Thread safety │ MT-Safe race:ucp │
80       └───────────────────────────────────┴───────────────┴──────────────────┘
81

CONFORMING TO

83       SUSv2, POSIX.1-2001.  POSIX.1-2008 removes the specification of getcon‐
84       text(), citing portability issues, and recommending  that  applications
85       be rewritten to use POSIX threads instead.
86

NOTES

88       The earliest incarnation of this mechanism was the setjmp(3)/longjmp(3)
89       mechanism.  Since that does not define the handling of the signal  con‐
90       text,  the  next  stage  was  the sigsetjmp(3)/siglongjmp(3) pair.  The
91       present mechanism gives much more control.  On the other hand, there is
92       no  easy  way  to detect whether a return from getcontext() is from the
93       first call, or via a setcontext() call.  The user has to  invent  their
94       own  bookkeeping  device, and a register variable won't do since regis‐
95       ters are restored.
96
97       When a signal occurs, the current user context is saved and a new  con‐
98       text is created by the kernel for the signal handler.  Do not leave the
99       handler using longjmp(3): it is undefined what would happen  with  con‐
100       texts.  Use siglongjmp(3) or setcontext() instead.
101

SEE ALSO

103       sigaction(2),   sigaltstack(2),  sigprocmask(2),  longjmp(3),  makecon‐
104       text(3), sigsetjmp(3), signal(7)
105

COLOPHON

107       This page is part of release 5.12 of the Linux  man-pages  project.   A
108       description  of  the project, information about reporting bugs, and the
109       latest    version    of    this    page,    can     be     found     at
110       https://www.kernel.org/doc/man-pages/.
111
112
113
114Linux                             2021-03-22                     GETCONTEXT(3)
Impressum