man3/getcontext.3

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