getcontext or setcontext Subroutine

Purpose

Initializes the structure pointed to by ucp to the context of the calling process.

Library

(libc.a)

Syntax

#include <ucontext.h>

int getcontext (ucontext_t *ucp);

int setcontext (const uncontext_t *ucp);

Description

The getcontext subroutine initalizes the structure pointed to by ucp to the current user context of the calling process. The ucontext_t type that ucp points to defines the user context and includes the contents of the calling process' machine registers, the signal mask, and the current execution stack.

The setcontext subroutine restores the user context pointed to by ucp. A successful call to setcontext subroutine does not return; program execution resumes at the point specified by the ucp argument passed to setcontext subroutine. The ucp argument should be created either by a prior call to getcontext subroutine, or by being passed as an argument to a signal handler. If the ucp argument was created with getcontext subroutine, program execution continues as if the corresponding call of getcontext subroutine had just returned. If the ucp argument was created with makecontext subroutine, program execution continues with the function passed to makecontext subroutine. When that function returns, the process continues as if after a call to setcontext subroutine with the ucp argument that was input to makecontext subroutine. 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 arguement is equal to 0, then this context is the main context, and the process will exit when this context returns.

Parameters

Return Values

If successful, a value of 0 is returned. If unsuccessful, a value of -1 is returned and the errno global variable is set to indicate the error.

Error Codes