.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "GETCONTEXT" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" getcontext 
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.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 .