NAME

getcontext, setcontext − provides user level context switching

SYNOPSIS

#include  <ucontext.h>

int  getcontext (
         ucontext_t ∗ucp );
 
int  setcontext (
         ucontext_t ∗ucp );

PARAMETERS

ucpProvides a pointer to a ucontext structure. 

DESCRIPTION

Using both the getcontext and setcontext functions enables you to initiate user level control switching multiple threads of control within a single process. 

To initialize the structure pointed to by the ucp parameter to the current user context of the calling process, you must use the getcontext function.  The format of the user context is defined by ucontext(5) file format.  The ucontext file format contains the signal mask, execution stack, and machine registers. 

To restore the state of the user context pointed to by the ucp parameter, you must use the setcontext function.  Requesting the setcontext function does not return any value and program execution continues from the point specified by the context structure passed to the setcontext function.  The context structure must be created by a call to the getcontext function, or it must be passed as the third argument to a signal handler as described by the sigaction function.  When a context structure is created by the getcontext structure, execution of the program continues as if the corresponding call of the getcontext function had just returned. 

RETURN VALUES

The setcontext function does not return upon success.  For the getcontext function, zero (0) is returned upon success.  Upon failure, a value of -1 is returned and errno is set to indicate the error. 

RESTRICTIONS

On a signal handler’s execution, the current user context is saved and a new context is created by the kernel.  If the process leaves the signal handler using the longjmp routine, the original context cannot be restored, and future calls to the getcontext function are not predictable.  Signal handlers should use the siglongjmp or setcontext function. 

RELATED INFORMATION

Functions: sigaction(2), sigaltstack(2), sigprocmask(2). 

Files: ucontext(5).