1 files changed, 202 insertions, 0 deletions
diff --git a/upstream/opensuse-tumbleweed/man3/getcontext.3 b/upstream/opensuse-tumbleweed/man3/getcontext.3
new file mode 100644
index 00000000..4cd604c6
--- /dev/null
+++ b/upstream/opensuse-tumbleweed/man3/getcontext.3
@@ -0,0 +1,202 @@
+'\" t
+.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl)
+.\"
+.\" SPDX-License-Identifier: Linux-man-pages-copyleft
+.\"
+.TH getcontext 3 2023-07-20 "Linux man-pages 6.05.01"
+.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>
+.PP
+.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.
+.PP
+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:
+.PP
+.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
+.PP
+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.
+.PP
+The function
+.BR getcontext ()
+initializes the structure
+pointed to by
+.I ucp
+to the currently active context.
+.PP
+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)).
+.PP
+If the context was obtained by a call of
+.BR getcontext (),
+program execution continues as if this call just returned.
+.PP
+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.
+.PP
+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
+.sp 1
+.SH STANDARDS
+None.
+.SH HISTORY
+SUSv2, POSIX.1-2001.
+.PP
+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.
+.PP
+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)