mirror of https://github.com/mkerrisk/man-pages
102 lines
4.1 KiB
Plaintext
102 lines
4.1 KiB
Plaintext
.\" 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 .
|