original/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 2009-03-15 "Linux" "Linux Programmer's Manual"
  26 .SH NAME
  27 getcontext, setcontext \- get or set the user context
  28 .SH SYNOPSIS
  29 .B #include <ucontext.h>
  30 .sp
  31 .BI "int getcontext(ucontext_t *" ucp );
  32 .br
  33 .BI "int setcontext(const ucontext_t *" ucp );
  34 .SH DESCRIPTION
  35 In a System V-like environment, one has the two types
  36 .I mcontext_t
  37 and
  38 .I ucontext_t
  39 defined in
  40 .I <ucontext.h>
  41 and the four functions
  42 .BR getcontext (),
  43 .BR setcontext (),
  44 .BR makecontext (3)
  45 and
  46 .BR swapcontext (3)
  47 that allow user-level context switching between multiple
  48 threads of control within a process.
  49 .LP
  50 The
  51 .I mcontext_t
  52 type is machine-dependent and opaque.
  53 The
  54 .I ucontext_t
  55 type is a structure that has at least
  56 the following fields:
  57 .in +4
  58 .nf
  59
  60 typedef struct ucontext {
  61     struct ucontext *uc_link;
  62     sigset_t         uc_sigmask;
  63     stack_t          uc_stack;
  64     mcontext_t       uc_mcontext;
  65     ...
  66 } ucontext_t;
  67
  68 .fi
  69 .in
  70 with
  71 .IR sigset_t
  72 and
  73 .I stack_t
  74 defined in
  75 .IR <signal.h> .
  76 Here
  77 .I uc_link
  78 points to the context that will be resumed
  79 when the current context terminates (in case the current context
  80 was created using
  81 .BR makecontext (3)),
  82 .I uc_sigmask
  83 is the
  84 set of signals blocked in this context (see
  85 .BR sigprocmask (2)),
  86 .I uc_stack
  87 is the stack used by this context (see
  88 .BR sigaltstack (2)),
  89 and
  90 .I uc_mcontext
  91 is the
  92 machine-specific representation of the saved context,
  93 that includes the calling thread's machine registers.
  94 .LP
  95 The function
  96 .BR getcontext ()
  97 initializes the structure
  98 pointed at by
  99 .I ucp
 100 to the currently active context.
 101 .LP
 102 The function
 103 .BR setcontext ()
 104 restores the user context
 105 pointed at by
 106 .IR ucp .
 107 A successful call does not return.
 108 The context should have been obtained by a call of
 109 .BR getcontext (),
 110 or
 111 .BR makecontext (3),
 112 or passed as third argument to a signal
 113 handler.
 114 .LP
 115 If the context was obtained by a call of
 116 .BR getcontext (),
 117 program execution continues as if this call just returned.
 118 .LP
 119 If the context was obtained by a call of
 120 .BR makecontext (3),
 121 program execution continues by a call to the function
 122 .I func
 123 specified as the second argument of that call to
 124 .BR makecontext (3).
 125 When the function
 126 .I func
 127 returns, we continue with the
 128 .I uc_link
 129 member of the structure
 130 .I ucp
 131 specified as the
 132 first argument of that call to
 133 .BR makecontext (3).
 134 When this member is NULL, the thread exits.
 135 .LP
 136 If the context was obtained by a call to a signal handler,
 137 then old standard text says that "program execution continues with the
 138 program instruction following the instruction interrupted
 139 by the signal".
 140 However, this sentence was removed in SUSv2,
 141 and the present verdict is "the result is unspecified".
 142 .SH RETURN VALUE
 143 When successful,
 144 .BR getcontext ()
 145 returns 0 and
 146 .BR setcontext ()
 147 does not return.
 148 On error, both return \-1 and set
 149 .I errno
 150 appropriately.
 151 .SH ERRORS
 152 None defined.
 153 .SH CONFORMING TO
 154 SUSv2, POSIX.1-2001.
 155 POSIX.1-2008 removes the specification of
 156 .BR getcontext (),
 157 citing portability issues, and
 158 recommending that applications be rewritten to use POSIX threads instead.
 159 .SH NOTES
 160 The earliest incarnation of this mechanism was the
 161 .BR setjmp (3)/ longjmp (3)
 162 mechanism.
 163 Since that does not define
 164 the handling of the signal context, the next stage was the
 165 .BR sigsetjmp (3)/ siglongjmp (3)
 166 pair.
 167 The present mechanism gives much more control.
 168 On the other hand,
 169 there is no easy way to detect whether a return from
 170 .BR getcontext ()
 171 is from the first call, or via a
 172 .BR setcontext ()
 173 call.
 174 The user has to invent her own bookkeeping device, and a register
 175 variable won't do since registers are restored.
 176 .LP
 177 When a signal occurs, the current user context is saved and
 178 a new context is created by the kernel for the signal handler.
 179 Do not leave the handler using
 180 .BR longjmp (3):
 181 it is undefined what would happen with contexts.
 182 Use
 183 .BR siglongjmp (3)
 184 or
 185 .BR setcontext ()
 186 instead.
 187 .SH SEE ALSO
 188 .BR sigaction (2),
 189 .BR sigaltstack (2),
 190 .BR sigprocmask (2),
 191 .BR longjmp (3),
 192 .BR makecontext (3),
 193 .BR sigsetjmp (3)
 194 .SH COLOPHON
 195 This page is part of release 3.64 of the Linux
 196 .I man-pages
 197 project.
 198 A description of the project,
 199 and information about reporting bugs,
 200 can be found at
 201 \%http://www.kernel.org/doc/man\-pages/.