getcontext(3)

1getcontext(3)              Library Functions Manual              getcontext(3)
2
3
4

NAME

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

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <ucontext.h>
13
14       int getcontext(ucontext_t *ucp);
15       int setcontext(const ucontext_t *ucp);
16

DESCRIPTION

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

RETURN VALUE

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

ERRORS

73       None defined.
74

ATTRIBUTES

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

STANDARDS

86       None.
87

HISTORY

89       SUSv2, POSIX.1-2001.
90
91       POSIX.1-2008  removes  these  functions, citing portability issues, and
92       recommending that applications be rewritten to use  POSIX  threads  in‐
93       stead.
94

NOTES

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