diff options
Diffstat (limited to 'man/man3/getcontext.3')
| -rw-r--r-- | man/man3/getcontext.3 | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/man/man3/getcontext.3 b/man/man3/getcontext.3 new file mode 100644 index 0000000..879cfe8 --- /dev/null +++ b/man/man3/getcontext.3 @@ -0,0 +1,201 @@ +'\" t +.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH getcontext 3 2024-05-02 "Linux man-pages (unreleased)" +.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) |