summaryrefslogtreecommitdiffstats
path: root/man3/getcontext.3
diff options
context:
space:
mode:
Diffstat (limited to 'man3/getcontext.3')
-rw-r--r--man3/getcontext.3201
1 files changed, 0 insertions, 201 deletions
diff --git a/man3/getcontext.3 b/man3/getcontext.3
deleted file mode 100644
index 6515075..0000000
--- a/man3/getcontext.3
+++ /dev/null
@@ -1,201 +0,0 @@
-'\" t
-.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
-.\"
-.\" SPDX-License-Identifier: Linux-man-pages-copyleft
-.\"
-.TH getcontext 3 2023-10-31 "Linux man-pages 6.7"
-.SH NAME
-getcontext, setcontext \- get or set the user context
-.SH LIBRARY
-Standard C library
-.RI ( libc ", " \-lc )
-.SH SYNOPSIS
-.nf
-.B #include <ucontext.h>
-.P
-.BI "int getcontext(ucontext_t *" ucp );
-.BI "int setcontext(const ucontext_t *" ucp );
-.fi
-.SH DESCRIPTION
-In a System V-like environment, one has the two types
-.I mcontext_t
-and
-.I ucontext_t
-defined in
-.I <ucontext.h>
-and the four functions
-.BR getcontext (),
-.BR setcontext (),
-.BR makecontext (3),
-and
-.BR swapcontext (3)
-that allow user-level context switching between multiple
-threads of control within a process.
-.P
-The
-.I mcontext_t
-type is machine-dependent and opaque.
-The
-.I ucontext_t
-type is a structure that has at least
-the following fields:
-.P
-.in +4n
-.EX
-typedef struct ucontext_t {
- struct ucontext_t *uc_link;
- sigset_t uc_sigmask;
- stack_t uc_stack;
- mcontext_t uc_mcontext;
- ...
-} ucontext_t;
-.EE
-.in
-.P
-with
-.I sigset_t
-and
-.I stack_t
-defined in
-.IR <signal.h> .
-Here
-.I uc_link
-points to the context that will be resumed
-when the current context terminates (in case the current context
-was created using
-.BR makecontext (3)),
-.I uc_sigmask
-is the
-set of signals blocked in this context (see
-.BR sigprocmask (2)),
-.I uc_stack
-is the stack used by this context (see
-.BR sigaltstack (2)),
-and
-.I uc_mcontext
-is the
-machine-specific representation of the saved context,
-that includes the calling thread's machine registers.
-.P
-The function
-.BR getcontext ()
-initializes the structure
-pointed to by
-.I ucp
-to the currently active context.
-.P
-The function
-.BR setcontext ()
-restores the user context
-pointed to by
-.IR ucp .
-A successful call does not return.
-The context should have been obtained by a call of
-.BR getcontext (),
-or
-.BR makecontext (3),
-or received as the third argument to a signal
-handler (see the discussion of the
-.B SA_SIGINFO
-flag in
-.BR sigaction (2)).
-.P
-If the context was obtained by a call of
-.BR getcontext (),
-program execution continues as if this call just returned.
-.P
-If the context was obtained by a call of
-.BR makecontext (3),
-program execution continues by a call to the function
-.I func
-specified as the second argument of that call to
-.BR makecontext (3).
-When the function
-.I func
-returns, we continue with the
-.I uc_link
-member of the structure
-.I ucp
-specified as the
-first argument of that call to
-.BR makecontext (3).
-When this member is NULL, the thread exits.
-.P
-If the context was obtained by a call to a signal handler,
-then old standard text says that "program execution continues with the
-program instruction following the instruction interrupted
-by the signal".
-However, this sentence was removed in SUSv2,
-and the present verdict is "the result is unspecified".
-.SH RETURN VALUE
-When successful,
-.BR getcontext ()
-returns 0 and
-.BR setcontext ()
-does not return.
-On error, both return \-1 and set
-.I errno
-to indicate the error.
-.SH ERRORS
-None defined.
-.SH ATTRIBUTES
-For an explanation of the terms used in this section, see
-.BR attributes (7).
-.TS
-allbox;
-lbx lb lb
-l l l.
-Interface Attribute Value
-T{
-.na
-.nh
-.BR getcontext (),
-.BR setcontext ()
-T} Thread safety MT-Safe race:ucp
-.TE
-.SH STANDARDS
-None.
-.SH HISTORY
-SUSv2, POSIX.1-2001.
-.P
-POSIX.1-2008 removes these functions,
-citing portability issues, and
-recommending that applications be rewritten to use POSIX threads instead.
-.SH NOTES
-The earliest incarnation of this mechanism was the
-.BR setjmp (3)/\c
-.BR longjmp (3)
-mechanism.
-Since that does not define
-the handling of the signal context, the next stage was the
-.BR sigsetjmp (3)/\c
-.BR siglongjmp (3)
-pair.
-The present mechanism gives much more control.
-On the other hand,
-there is no easy way to detect whether a return from
-.BR getcontext ()
-is from the first call, or via a
-.BR setcontext ()
-call.
-The user has to invent their own bookkeeping device, and a register
-variable won't do since registers are restored.
-.P
-When a signal occurs, the current user context is saved and
-a new context is created by the kernel for the signal handler.
-Do not leave the handler using
-.BR longjmp (3):
-it is undefined what would happen with contexts.
-Use
-.BR siglongjmp (3)
-or
-.BR setcontext ()
-instead.
-.SH SEE ALSO
-.BR sigaction (2),
-.BR sigaltstack (2),
-.BR sigprocmask (2),
-.BR longjmp (3),
-.BR makecontext (3),
-.BR sigsetjmp (3),
-.BR signal (7)