getcontext, setcontext - display or modify user context

Syntax	#include <ucontext.h> int getcontext(ucontext_t *ucp); int setcontext(const ucontext_t *ucp);
Description	In conjunction with the functions defined in makecontext(), these functions serve to implement the change of context at user level between several control flows of a process. getcontext() initializes the structure pointed to by ucp as the current user context of the calling process. The ucontext_t structure pointed to by ucp defines the user context and contains the contents of the machine register, the signal mask and the stack of the calling process. setcontext() restores the user context pointed to by ucp. A successful setcontext() call does not return; the program execution continues at the position pointed to by the context structure of setcontext(). The context structure should be generated by a preceding getcontext() call or have been supplied by the system as the third argument to a signal handling routine (see sigaction()). If the context structure was generated with getcontext(), the program execution is resumed as if the corresponding call of getcontext() had returned. If the context structure was generated with makecontext(), the program execution is resumed with the function specified by makecontext(). If this function returns, the process is continued, like after a setcontext() call, with the ucp argument that was also the argument for makecontext(). If the ucp argument is passed to a signal handling routine, the program execution is continued with the next instruction after the one interrupted by the signal. If the uc_link component from the ucontext_t structure pointed to by ucp has the value 0, this is a basic process and the process terminates when this context is terminated. The use of a ucp argument that was generated differently from the description above leads to unpredictable results. If threads are used, then the function affects the process or a thread in the following manner: getcontext() gets the current user context of the calling thread. setcontext() sets the current user context of the calling thread.
Return val.	getcontext():
	0 -1	if successful. if an error occurs.
	setcontext(): does not return if successful.
	-1	if an error occurs.
Notes	If a signal handling routine is executed, the user context is stored and a new context generated. If the process leaves the signal handling routine via longjmp(), the original context will not be restored and subsequent getcontext() calls are no longer reliable. Signal handling routines should therefore use siglongjmp() or setcontext(). Portable applications should neither access nor modify the uc_mcontext component of the ucontext_t structure. A portable application cannot assume that getcontext() stores static data of the process in ucp, not even errno. Care must be taken when manipulating contexts.
See also	bsd_signal(), makecontext(), setjmp(), sigaction(), sigaltstack(), sigprocmask(), sigsetjmp() , ucontext.h .