|
Packit |
7cfc04 |
.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(VERBATIM)
|
|
Packit |
7cfc04 |
.\" Permission is granted to make and distribute verbatim copies of this
|
|
Packit |
7cfc04 |
.\" manual provided the copyright notice and this permission notice are
|
|
Packit |
7cfc04 |
.\" preserved on all copies.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Permission is granted to copy and distribute modified versions of this
|
|
Packit |
7cfc04 |
.\" manual under the conditions for verbatim copying, provided that the
|
|
Packit |
7cfc04 |
.\" entire resulting derived work is distributed under the terms of a
|
|
Packit |
7cfc04 |
.\" permission notice identical to this one.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
Packit |
7cfc04 |
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
Packit |
7cfc04 |
.\" responsibility for errors or omissions, or for damages resulting from
|
|
Packit |
7cfc04 |
.\" the use of the information contained herein. The author(s) may not
|
|
Packit |
7cfc04 |
.\" have taken the same level of care in the production of this manual,
|
|
Packit |
7cfc04 |
.\" which is licensed free of charge, as they might when working
|
|
Packit |
7cfc04 |
.\" professionally.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
Packit |
7cfc04 |
.\" the source, must acknowledge the copyright and authors of this work.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH GETCONTEXT 3 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
getcontext, setcontext \- get or set the user context
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.B #include <ucontext.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int getcontext(ucontext_t *" ucp );
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
.BI "int setcontext(const ucontext_t *" ucp );
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
In a System V-like environment, one has the two types
|
|
Packit |
7cfc04 |
.I mcontext_t
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I ucontext_t
|
|
Packit |
7cfc04 |
defined in
|
|
Packit |
7cfc04 |
.I <ucontext.h>
|
|
Packit |
7cfc04 |
and the four functions
|
|
Packit |
7cfc04 |
.BR getcontext (),
|
|
Packit |
7cfc04 |
.BR setcontext (),
|
|
Packit |
7cfc04 |
.BR makecontext (3),
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR swapcontext (3)
|
|
Packit |
7cfc04 |
that allow user-level context switching between multiple
|
|
Packit |
7cfc04 |
threads of control within a process.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I mcontext_t
|
|
Packit |
7cfc04 |
type is machine-dependent and opaque.
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I ucontext_t
|
|
Packit |
7cfc04 |
type is a structure that has at least
|
|
Packit |
7cfc04 |
the following fields:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
typedef struct ucontext_t {
|
|
Packit |
7cfc04 |
struct ucontext_t *uc_link;
|
|
Packit |
7cfc04 |
sigset_t uc_sigmask;
|
|
Packit |
7cfc04 |
stack_t uc_stack;
|
|
Packit |
7cfc04 |
mcontext_t uc_mcontext;
|
|
Packit |
7cfc04 |
...
|
|
Packit |
7cfc04 |
} ucontext_t;
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
with
|
|
Packit |
7cfc04 |
.IR sigset_t
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I stack_t
|
|
Packit |
7cfc04 |
defined in
|
|
Packit |
7cfc04 |
.IR <signal.h> .
|
|
Packit |
7cfc04 |
Here
|
|
Packit |
7cfc04 |
.I uc_link
|
|
Packit |
7cfc04 |
points to the context that will be resumed
|
|
Packit |
7cfc04 |
when the current context terminates (in case the current context
|
|
Packit |
7cfc04 |
was created using
|
|
Packit |
7cfc04 |
.BR makecontext (3)),
|
|
Packit |
7cfc04 |
.I uc_sigmask
|
|
Packit |
7cfc04 |
is the
|
|
Packit |
7cfc04 |
set of signals blocked in this context (see
|
|
Packit |
7cfc04 |
.BR sigprocmask (2)),
|
|
Packit |
7cfc04 |
.I uc_stack
|
|
Packit |
7cfc04 |
is the stack used by this context (see
|
|
Packit |
7cfc04 |
.BR sigaltstack (2)),
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I uc_mcontext
|
|
Packit |
7cfc04 |
is the
|
|
Packit |
7cfc04 |
machine-specific representation of the saved context,
|
|
Packit |
7cfc04 |
that includes the calling thread's machine registers.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The function
|
|
Packit |
7cfc04 |
.BR getcontext ()
|
|
Packit |
7cfc04 |
initializes the structure
|
|
Packit |
7cfc04 |
pointed at by
|
|
Packit |
7cfc04 |
.I ucp
|
|
Packit |
7cfc04 |
to the currently active context.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The function
|
|
Packit |
7cfc04 |
.BR setcontext ()
|
|
Packit |
7cfc04 |
restores the user context
|
|
Packit |
7cfc04 |
pointed at by
|
|
Packit |
7cfc04 |
.IR ucp .
|
|
Packit |
7cfc04 |
A successful call does not return.
|
|
Packit |
7cfc04 |
The context should have been obtained by a call of
|
|
Packit |
7cfc04 |
.BR getcontext (),
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR makecontext (3),
|
|
Packit |
7cfc04 |
or passed as third argument to a signal
|
|
Packit |
7cfc04 |
handler.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If the context was obtained by a call of
|
|
Packit |
7cfc04 |
.BR getcontext (),
|
|
Packit |
7cfc04 |
program execution continues as if this call just returned.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If the context was obtained by a call of
|
|
Packit |
7cfc04 |
.BR makecontext (3),
|
|
Packit |
7cfc04 |
program execution continues by a call to the function
|
|
Packit |
7cfc04 |
.I func
|
|
Packit |
7cfc04 |
specified as the second argument of that call to
|
|
Packit |
7cfc04 |
.BR makecontext (3).
|
|
Packit |
7cfc04 |
When the function
|
|
Packit |
7cfc04 |
.I func
|
|
Packit |
7cfc04 |
returns, we continue with the
|
|
Packit |
7cfc04 |
.I uc_link
|
|
Packit |
7cfc04 |
member of the structure
|
|
Packit |
7cfc04 |
.I ucp
|
|
Packit |
7cfc04 |
specified as the
|
|
Packit |
7cfc04 |
first argument of that call to
|
|
Packit |
7cfc04 |
.BR makecontext (3).
|
|
Packit |
7cfc04 |
When this member is NULL, the thread exits.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If the context was obtained by a call to a signal handler,
|
|
Packit |
7cfc04 |
then old standard text says that "program execution continues with the
|
|
Packit |
7cfc04 |
program instruction following the instruction interrupted
|
|
Packit |
7cfc04 |
by the signal".
|
|
Packit |
7cfc04 |
However, this sentence was removed in SUSv2,
|
|
Packit |
7cfc04 |
and the present verdict is "the result is unspecified".
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
When successful,
|
|
Packit |
7cfc04 |
.BR getcontext ()
|
|
Packit |
7cfc04 |
returns 0 and
|
|
Packit |
7cfc04 |
.BR setcontext ()
|
|
Packit |
7cfc04 |
does not return.
|
|
Packit |
7cfc04 |
On error, both return \-1 and set
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
appropriately.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
None defined.
|
|
Packit |
7cfc04 |
.SH ATTRIBUTES
|
|
Packit |
7cfc04 |
For an explanation of the terms used in this section, see
|
|
Packit |
7cfc04 |
.BR attributes (7).
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
allbox;
|
|
Packit |
7cfc04 |
lbw26 lb lb
|
|
Packit |
7cfc04 |
l l l.
|
|
Packit |
7cfc04 |
Interface Attribute Value
|
|
Packit |
7cfc04 |
T{
|
|
Packit |
7cfc04 |
.BR getcontext (),
|
|
Packit |
7cfc04 |
.BR setcontext ()
|
|
Packit |
7cfc04 |
T} Thread safety MT-Safe race:ucp
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
SUSv2, POSIX.1-2001.
|
|
Packit |
7cfc04 |
POSIX.1-2008 removes the specification of
|
|
Packit |
7cfc04 |
.BR getcontext (),
|
|
Packit |
7cfc04 |
citing portability issues, and
|
|
Packit |
7cfc04 |
recommending that applications be rewritten to use POSIX threads instead.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
The earliest incarnation of this mechanism was the
|
|
Packit |
7cfc04 |
.BR setjmp (3)/ longjmp (3)
|
|
Packit |
7cfc04 |
mechanism.
|
|
Packit |
7cfc04 |
Since that does not define
|
|
Packit |
7cfc04 |
the handling of the signal context, the next stage was the
|
|
Packit |
7cfc04 |
.BR sigsetjmp (3)/ siglongjmp (3)
|
|
Packit |
7cfc04 |
pair.
|
|
Packit |
7cfc04 |
The present mechanism gives much more control.
|
|
Packit |
7cfc04 |
On the other hand,
|
|
Packit |
7cfc04 |
there is no easy way to detect whether a return from
|
|
Packit |
7cfc04 |
.BR getcontext ()
|
|
Packit |
7cfc04 |
is from the first call, or via a
|
|
Packit |
7cfc04 |
.BR setcontext ()
|
|
Packit |
7cfc04 |
call.
|
|
Packit |
7cfc04 |
The user has to invent her own bookkeeping device, and a register
|
|
Packit |
7cfc04 |
variable won't do since registers are restored.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
When a signal occurs, the current user context is saved and
|
|
Packit |
7cfc04 |
a new context is created by the kernel for the signal handler.
|
|
Packit |
7cfc04 |
Do not leave the handler using
|
|
Packit |
7cfc04 |
.BR longjmp (3):
|
|
Packit |
7cfc04 |
it is undefined what would happen with contexts.
|
|
Packit |
7cfc04 |
Use
|
|
Packit |
7cfc04 |
.BR siglongjmp (3)
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR setcontext ()
|
|
Packit |
7cfc04 |
instead.
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR sigaction (2),
|
|
Packit |
7cfc04 |
.BR sigaltstack (2),
|
|
Packit |
7cfc04 |
.BR sigprocmask (2),
|
|
Packit |
7cfc04 |
.BR longjmp (3),
|
|
Packit |
7cfc04 |
.BR makecontext (3),
|
|
Packit |
7cfc04 |
.BR sigsetjmp (3)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|