man2/getcontext.2

   1 .\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.  The author(s) may not
  16 .\" have taken the same level of care in the production of this manual,
  17 .\" which is licensed free of charge, as they might when working
  18 .\" professionally.
  19 .\"
  20 .\" Formatted or processed versions of this manual, if unaccompanied by
  21 .\" the source, must acknowledge the copyright and authors of this work.
  22 .\"
  23 .TH GETCONTEXT 2 2001-11-15 "Linux" "Linux Programmer's Manual"
  24 .SH NAME
  25 getcontext, setcontext \- get or set the user context
  26 .SH SYNOPSIS
  27 .B #include <ucontext.h>
  28 .sp
  29 .BI "int getcontext(ucontext_t *" ucp );
  30 .br
  31 .BI "int setcontext(const ucontext_t *" ucp );
  32 .SH DESCRIPTION
  33 In a System V-like environment, one has the two types
  34 \fImcontext_t\fP and \fIucontext_t\fP defined in
  35 .I <ucontext.h>
  36 and the four functions
  37 .BR getcontext (),
  38 .BR setcontext (),
  39 .BR makecontext (3)
  40 and
  41 .BR swapcontext (3)
  42 that allow user-level context switching between multiple
  43 threads of control within a process.
  44 .LP
  45 The \fImcontext_t\fP type is machine-dependent and opaque.
  46 The \fIucontext_t\fP type is a structure that has at least
  47 the following fields:
  48 .RS
  49 .nf
  50
  51 typedef struct ucontext {
  52     struct ucontext *uc_link;
  53     sigset_t         uc_sigmask;
  54     stack_t          uc_stack;
  55     mcontext_t       uc_mcontext;
  56     ...
  57 } ucontext_t;
  58
  59 .fi
  60 .RE
  61 with \fIsigset_t\fP and \fIstack_t\fP defined in
  62 .IR <signal.h> .
  63 Here \fIuc_link\fP 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 \fIuc_sigmask\fP is the
  68 set of signals blocked in this context (see
  69 .BR sigprocmask (2)),
  70 \fIuc_stack\fP is the stack used by this context (see
  71 .BR sigaltstack (2)),
  72 and \fIuc_mcontext\fP is the
  73 machine-specific representation of the saved context,
  74 that includes the calling thread's machine registers.
  75 .LP
  76 The function
  77 .BR getcontext ()
  78 initializes the structure
  79 pointed at by \fIucp\fP to the currently active context.
  80 .LP
  81 The function
  82 .BR setcontext ()
  83 restores the user context
  84 pointed at by \fIucp\fP.
  85 A successful call does not return.
  86 The context should have been obtained by a call of
  87 .BR getcontext (),
  88 or
  89 .BR makecontext (3),
  90 or passed as third argument to a signal
  91 handler.
  92 .LP
  93 If the context was obtained by a call of
  94 .BR getcontext (),
  95 program execution continues as if this call just returned.
  96 .LP
  97 If the context was obtained by a call of
  98 .BR makecontext (3),
  99 program execution continues by a call to the function \fIfunc\fP
 100 specified as the second argument of that call to
 101 .BR makecontext (3).
 102 When the function \fIfunc\fP returns, we continue with the
 103 \fIuc_link\fP member of the structure \fIucp\fP specified as the
 104 first argument of that call to
 105 .BR makecontext (3).
 106 When this member is NULL, the thread exits.
 107 .LP
 108 If the context was obtained by a call to a signal handler,
 109 then old standard text says that "program execution continues with the
 110 program instruction following the instruction interrupted
 111 by the signal".
 112 However, this sentence was removed in SUSv2,
 113 and the present verdict is "the result is unspecified".
 114 .SH "RETURN VALUE"
 115 When successful,
 116 .BR getcontext ()
 117 returns 0 and
 118 .BR setcontext ()
 119 does not return.
 120 On error, both return \-1 and set \fIerrno\fP
 121 appropriately.
 122 .SH ERRORS
 123 None defined.
 124 .SH "CONFORMING TO"
 125 SUSv2, POSIX.1-2001.
 126 .SH NOTES
 127 The earliest incarnation of this mechanism was the
 128 .BR setjmp (3)/ longjmp (3)
 129 mechanism.
 130 Since that does not define
 131 the handling of the signal context, the next stage was the
 132 .BR sigsetjmp (3)/ siglongjmp (3)
 133 pair.
 134 The present mechanism gives much more control.
 135 On the other hand,
 136 there is no easy way to detect whether a return from
 137 .BR getcontext ()
 138 is from the first call, or via a
 139 .BR setcontext ()
 140 call.
 141 The user has to invent her own bookkeeping device, and a register
 142 variable won't do since registers are restored.
 143 .LP
 144 When a signal occurs, the current user context is saved and
 145 a new context is created by the kernel for the signal handler.
 146 Do not leave the handler using
 147 .BR longjmp (3):
 148 it is undefined what would happen with contexts.
 149 Use
 150 .BR siglongjmp (3)
 151 or
 152 .BR setcontext ()
 153 instead.
 154 .SH "SEE ALSO"
 155 .BR sigaction (2),
 156 .BR sigaltstack (2),
 157 .BR sigprocmask (2),
 158 .BR longjmp (3),
 159 .BR makecontext (3),
 160 .BR sigsetjmp (3)