getcontext.2 (2010 09)

ManualsBrandsHP ManualsSoftwareHP-UX Manpages

getcontext(2) getcontext(2)

(Deprecated)

NAME

getcontext(), setcontext() - get and set current user context

SYNOPSIS

#include <ucontext.h>

int getcontext(ucontext_t *ucp);

Deprecated

int setcontext(const ucontext_t *ucp);

Deprecated

DESCRIPTION

The

getcontext() function initializes the structure pointed to by ucp to the current user context of the

calling process. The ucontext_t type that ucp points to deﬁnes the user context and includes the contents

of the calling process’ machine registers, the signal mask, and the current execution stack.

The

setcontext() function restores the user context pointed to by ucp. A successful call to

setcon-

text() does not return; program execution resumes at the point speciﬁed by the ucp argument passed to

setcontext(). The ucp argument should be created either by a prior call to

getcontext(),orby

being passed as an argument to a signal handler. If the ucp argument was created with

getcon-

text(), program execution continues as if the corresponding call of

getcontext()

had just returned.

If the ucp argument was created with

makecontext()

, program execution continues with the function

passed to

makecontext(). When that function returns, the process continues as if after a call to

setcontext() with the ucp argument that was input to makecontext()

. If the ucp argument was

passed to a signal handler, program execution continues with the program instruction following the

instruction interrupted by the signal. If the uc_link member of the

ucontext_t structure pointed to by

the ucp argument is equal to 0, then this context is the main context, and the process will exit when this

context returns. The effects of passing a ucp argument obtained from any other source are unspeciﬁed.

RETURN VALUE

On successful completion,

setcontext() does not return and getcontext() returns 0. Otherwise, a

value of −1 is returned.

WARNINGS

getcontext() and setcontext() are deprecated and should be used only by legacy applications.

Context APIs are not recommended due to possible compatibility problems from release to release,

because context APIs are very architecture-speciﬁc. The context APIs "expose" the architecture to the

application, such that the application may not be compatible with all releases.

If you must use context APIs, be aware of the following:

• Do not copy the context yourself. It is not contiguous. The context may have pointers that may point

back to the original context rather than in the copied context; hence, it will be broken.

• The size of the context will vary in length from release to release.

ERRORS

No errors are deﬁned.

APPLICATION USAGE

When a signal handler is executed, the current user context is saved and a new context is created. If the

process leaves the signal handler via

longjmp(), then it is unspeciﬁed whether the context at the time

of the corresponding setjmp() call is restored and thus whether future calls to getcontext() will

provide an accurate representation of the current context, since the context restored by longjmp() may

not contain all the information that setcontext() requires. Signal handlers should use

siglongjmp() or setcontext() instead.

Portable applications should not modify or access the uc_mcontext member of ucontext_t . A portable

application cannot assume that context includes any process-wide static data, possibly including

errno.

Users manipulating contexts should take care to handle these explicitly when required.