From 7f3caba522f4d24764f29d83aa2de9198bb7f01c Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Fri, 24 May 2024 06:52:22 +0200 Subject: Adding upstream version 6.8. Signed-off-by: Daniel Baumann --- man3/getcontext.3 | 201 ------------------------------------------------------ 1 file changed, 201 deletions(-) delete mode 100644 man3/getcontext.3 (limited to 'man3/getcontext.3') 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 -.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 -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 . -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) -- cgit v1.2.3