man3/getcontext.3

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