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
93       instead.
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
98       context,  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
103       registers are restored.
104
105       When a signal occurs, the current user  context  is  saved  and  a  new
106       context  is created by the kernel for the signal handler.  Do not leave
107       the handler using longjmp(3): it is undefined what  would  happen  with
108       contexts.  Use siglongjmp(3) or setcontext() instead.
109