man3/getcontext.3

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