diff options
Diffstat (limited to 'man3/makecontext.3')
| -rw-r--r-- | man3/makecontext.3 | 236 |
1 files changed, 0 insertions, 236 deletions
diff --git a/man3/makecontext.3 b/man3/makecontext.3 deleted file mode 100644 index 5fc342f..0000000 --- a/man3/makecontext.3 +++ /dev/null @@ -1,236 +0,0 @@ -'\" t -.\" Copyright (C) 2001 Andries Brouwer (aeb@cwi.nl) -.\" and Copyright (C) 2006 Michael Kerrisk <mtk.manpages@gmail.com> -.\" -.\" SPDX-License-Identifier: Linux-man-pages-copyleft -.\" -.\" 2006-08-02, mtk, Added example program -.\" -.TH makecontext 3 2023-10-31 "Linux man-pages 6.7" -.SH NAME -makecontext, swapcontext \- manipulate user context -.SH LIBRARY -Standard C library -.RI ( libc ", " \-lc ) -.SH SYNOPSIS -.nf -.B #include <ucontext.h> -.P -.BI "void makecontext(ucontext_t *" ucp ", void (*" func ")(), int " argc \ -", ...);" -.BI "int swapcontext(ucontext_t *restrict " oucp , -.BI " const ucontext_t *restrict " ucp ); -.fi -.SH DESCRIPTION -In a System V-like environment, one has the type -.I ucontext_t -(defined in -.I <ucontext.h> -and described in -.BR getcontext (3)) -and the four functions -.BR getcontext (3), -.BR setcontext (3), -.BR makecontext (), -and -.BR swapcontext () -that allow user-level context switching -between multiple threads of control within a process. -.P -The -.BR makecontext () -function modifies the context pointed to -by \fIucp\fP (which was obtained from a call to -.BR getcontext (3)). -Before invoking -.BR makecontext (), -the caller must allocate a new stack -for this context and assign its address to \fIucp\->uc_stack\fP, -and define a successor context and -assign its address to \fIucp\->uc_link\fP. -.P -When this context is later activated (using -.BR setcontext (3) -or -.BR swapcontext ()) -the function \fIfunc\fP is called, -and passed the series of integer -.RI ( int ) -arguments that follow -.IR argc ; -the caller must specify the number of these arguments in -.IR argc . -When this function returns, the successor context is activated. -If the successor context pointer is NULL, the thread exits. -.P -The -.BR swapcontext () -function saves the current context in -the structure pointed to by \fIoucp\fP, and then activates the -context pointed to by \fIucp\fP. -.SH RETURN VALUE -When successful, -.BR swapcontext () -does not return. -(But we may return later, in case \fIoucp\fP is -activated, in which case it looks like -.BR swapcontext () -returns 0.) -On error, -.BR swapcontext () -returns \-1 and sets -.I errno -to indicate the error. -.SH ERRORS -.TP -.B ENOMEM -Insufficient stack space left. -.SH ATTRIBUTES -For an explanation of the terms used in this section, see -.BR attributes (7). -.TS -allbox; -lb lb lbx -l l l. -Interface Attribute Value -T{ -.na -.nh -.BR makecontext () -T} Thread safety T{ -.na -.nh -MT-Safe race:ucp -T} -T{ -.na -.nh -.BR swapcontext () -T} Thread safety T{ -.na -.nh -MT-Safe race:oucp race:ucp -T} -.TE -.SH STANDARDS -None. -.SH HISTORY -glibc 2.1. -SUSv2, POSIX.1-2001. -Removed in POSIX.1-2008, -citing portability issues, and -recommending that applications be rewritten to use POSIX threads instead. -.SH NOTES -The interpretation of \fIucp\->uc_stack\fP is just as in -.BR sigaltstack (2), -namely, this struct contains the start and length of a memory area -to be used as the stack, regardless of the direction of growth of -the stack. -Thus, it is not necessary for the user program to -worry about this direction. -.P -On architectures where -.I int -and pointer types are the same size -(e.g., x86-32, where both types are 32 bits), -you may be able to get away with passing pointers as arguments to -.BR makecontext () -following -.IR argc . -However, doing this is not guaranteed to be portable, -is undefined according to the standards, -and won't work on architectures where pointers are larger than -.IR int s. -Nevertheless, starting with glibc 2.8, glibc makes some changes to -.BR makecontext (), -to permit this on some 64-bit architectures (e.g., x86-64). -.SH EXAMPLES -The example program below demonstrates the use of -.BR getcontext (3), -.BR makecontext (), -and -.BR swapcontext (). -Running the program produces the following output: -.P -.in +4n -.EX -.RB "$" " ./a.out" -main: swapcontext(&uctx_main, &uctx_func2) -func2: started -func2: swapcontext(&uctx_func2, &uctx_func1) -func1: started -func1: swapcontext(&uctx_func1, &uctx_func2) -func2: returning -func1: returning -main: exiting -.EE -.in -.SS Program source -\& -.\" SRC BEGIN (makecontext.c) -.EX -#include <stdio.h> -#include <stdlib.h> -#include <ucontext.h> -\& -static ucontext_t uctx_main, uctx_func1, uctx_func2; -\& -#define handle_error(msg) \e - do { perror(msg); exit(EXIT_FAILURE); } while (0) -\& -static void -func1(void) -{ - printf("%s: started\en", __func__); - printf("%s: swapcontext(&uctx_func1, &uctx_func2)\en", __func__); - if (swapcontext(&uctx_func1, &uctx_func2) == \-1) - handle_error("swapcontext"); - printf("%s: returning\en", __func__); -} -\& -static void -func2(void) -{ - printf("%s: started\en", __func__); - printf("%s: swapcontext(&uctx_func2, &uctx_func1)\en", __func__); - if (swapcontext(&uctx_func2, &uctx_func1) == \-1) - handle_error("swapcontext"); - printf("%s: returning\en", __func__); -} -\& -int -main(int argc, char *argv[]) -{ - char func1_stack[16384]; - char func2_stack[16384]; -\& - if (getcontext(&uctx_func1) == \-1) - handle_error("getcontext"); - uctx_func1.uc_stack.ss_sp = func1_stack; - uctx_func1.uc_stack.ss_size = sizeof(func1_stack); - uctx_func1.uc_link = &uctx_main; - makecontext(&uctx_func1, func1, 0); -\& - if (getcontext(&uctx_func2) == \-1) - handle_error("getcontext"); - uctx_func2.uc_stack.ss_sp = func2_stack; - uctx_func2.uc_stack.ss_size = sizeof(func2_stack); - /* Successor context is f1(), unless argc > 1 */ - uctx_func2.uc_link = (argc > 1) ? NULL : &uctx_func1; - makecontext(&uctx_func2, func2, 0); -\& - printf("%s: swapcontext(&uctx_main, &uctx_func2)\en", __func__); - if (swapcontext(&uctx_main, &uctx_func2) == \-1) - handle_error("swapcontext"); -\& - printf("%s: exiting\en", __func__); - exit(EXIT_SUCCESS); -} -.EE -.\" SRC END -.SH SEE ALSO -.BR sigaction (2), -.BR sigaltstack (2), -.BR sigprocmask (2), -.BR getcontext (3), -.BR sigsetjmp (3) |