diff options
Diffstat (limited to 'man3p/getcontext.3p')
| -rw-r--r-- | man3p/getcontext.3p | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/man3p/getcontext.3p b/man3p/getcontext.3p new file mode 100644 index 000000000..250a0d165 --- /dev/null +++ b/man3p/getcontext.3p @@ -0,0 +1,101 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "GETCONTEXT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" getcontext +.SH NAME +getcontext, setcontext \- get and set current user context +.SH SYNOPSIS +.LP +\fB#include <ucontext.h> +.br +.sp +int getcontext(ucontext_t *\fP\fIucp\fP\fB); +.br +int setcontext(const ucontext_t *\fP\fIucp\fP\fB); \fP +\fB +.br +\fP +.SH DESCRIPTION +.LP +The \fIgetcontext\fP() function shall initialize the structure pointed +to by \fIucp\fP to the current user context of the +calling thread. The \fBucontext_t\fP type that \fIucp\fP points to +defines the user context and includes the contents of the +calling thread's machine registers, the signal mask, and the current +execution stack. +.LP +The \fIsetcontext\fP() function shall restore the user context pointed +to by \fIucp\fP. A successful call to +\fIsetcontext\fP() shall not return; program execution resumes at +the point specified by the \fIucp\fP argument passed to +\fIsetcontext\fP(). The \fIucp\fP argument should be created either +by a prior call to \fIgetcontext\fP() or \fImakecontext\fP(), or by +being passed as an argument to a signal handler. If the \fIucp\fP +argument was created with \fIgetcontext\fP(), program execution continues +as if the corresponding call of \fIgetcontext\fP() had +just returned. If the \fIucp\fP argument was created with \fImakecontext\fP(), +program execution continues with the function passed to \fImakecontext\fP(). +When that +function returns, the thread shall continue as if after a call to +\fIsetcontext\fP() with the \fIucp\fP argument that was input +to \fImakecontext\fP(). If the \fIuc_link\fP member of the \fBucontext_t\fP +structure pointed to by the \fIucp\fP argument is equal to 0, then +this context is the main context, and the thread shall exit +when this context returns. The effects of passing a \fIucp\fP argument +obtained from any other source are unspecified. +.SH RETURN VALUE +.LP +Upon successful completion, \fIsetcontext\fP() shall not return and +\fIgetcontext\fP() shall return 0; otherwise, a value of +-1 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.LP +Refer to \fImakecontext\fP() . +.SH APPLICATION USAGE +.LP +When a signal handler is executed, the current user context is saved +and a new context is created. If the thread leaves the +signal handler via \fIlongjmp\fP(), then it is unspecified whether +the context at the time +of the corresponding \fIsetjmp\fP() call is restored and thus whether +future calls to +\fIgetcontext\fP() provide an accurate representation of the current +context, since the context restored by \fIlongjmp\fP() does not necessarily +contain all the information that \fIsetcontext\fP() +requires. Signal handlers should use \fIsiglongjmp\fP() or \fIsetcontext\fP() +instead. +.LP +Conforming applications should not modify or access the \fIuc_mcontext\fP +member of \fBucontext_t\fP. A conforming application +cannot assume that context includes any process-wide static data, +possibly including \fIerrno\fP. Users manipulating contexts +should take care to handle these explicitly when required. +.LP +Use of contexts to create alternate stacks is not defined by this +volume of IEEE\ Std\ 1003.1-2001. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIbsd_signal\fP() , \fImakecontext\fP() , \fIsetcontext\fP() , \fIsetjmp\fP() +, \fIsigaction\fP() , \fIsigaltstack\fP() , \fIsiglongjmp\fP() , \fIsigprocmask\fP() +, \fIsigsetjmp\fP() , the Base Definitions volume of IEEE\ Std\ 1003.1-2001, +\fI<ucontext.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |