setcontext(2) [hpux man page]

getcontext(2)							System Calls Manual						     getcontext(2)

NAME

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

SYNOPSIS

       Deprecated

       Deprecated

DESCRIPTION

       The  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 defines the user context and includes the contents of the calling process' machine registers, the signal mask,  and  the  current
       execution stack.

       The  function  restores	the  user context pointed to by ucp.  A successful call to does not return; program execution resumes at the point
       specified by the ucp argument passed to The ucp argument should be created either by a prior call to or by being passed as an argument to a
       signal handler.	If the ucp argument was created with program execution continues as if the corresponding call of had just returned. If the
       ucp argument was created with program execution continues with the function passed to When that function returns, the process continues	as
       if  after a call to with the ucp argument that was input to 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 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 unspecified.

RETURN VALUE

       On successful completion, does not return and returns 0. Otherwise, a value of -1 is returned.

WARNINGS

       and 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  architec-
       ture-specific.	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:

       o  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.

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

ERRORS

       No errors are defined.

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 then it is unspecified whether the context at the time of the corresponding call is restored and thus whether future calls to will pro-
       vide  an  accurate representation of the  current context, since the context restored by may not contain all the information that requires.
       Signal handlers should use or 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 Users manipulating contexts should take care to handle these explicitly when
       required.

SEE ALSO

       makecontext(2), sigaction(2), sigaltstack(2), sigprocmask(2), setjmp(3C), sigsetjmp(3C), <ucontext.h>.

								    Deprecated							     getcontext(2)

getcontext(2)							System Calls Manual						     getcontext(2)

NAME

       getcontext, setcontext - Initiates and restores user level context switching

SYNOPSIS

       #include <ucontext.h>

       int  getcontext(
	       ucontext_t *ucp ); int setcontext(
	       const ucontext_t *ucp );

STANDARDS

       Interfaces documented on this reference page conform to industry standards as follows:

       getcontext(), setcontext():  XSH5.0

       Refer to the standards(5) reference page for more information about industry standards and associated tags.

PARAMETERS

       Provides a pointer to a ucontext structure, defined in the <ucontext.h> header file.  The ucontext structure contains the signal mask, exe-
       cution stack, and machine registers. (See ucontext(5) for more information about the format of the ucontext structure.)

DESCRIPTION

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

       When you call getcontext(), it initializes the ucp argument to the current user context of the calling process.

       Use  the setcontext() function to restore the state of the user context pointed to by the ucp argument.	The setcontext() function, if suc-
       cessful, does not return; application execution continues from the point specified by the ucontext structure you pass to  the  setcontext()
       function.

       The  ucontext  structure  that  you  pass to the setcontext() function must have been created by a call to the getcontext() function or the
       makecontext() function, or have been passed as the third argument to a signal handler.  (The third argument in a call  to  the  sigaction()
       function determines the action to be performed when a signal is delivered. For more information, see sigaction(2).)

       When  a	context  structure is created by the getcontext() function, execution of the program continues as if the corresponding call of the
       getcontext() function had just returned.

       When a context structure is created by the makecontext() function, program execution continues with the function passed	to  makecontext().
       When  that  function returns, the thread continues as if after a call to setcontext() with the context structure argument that was input to
       makecontext().

       If the uc_link member of the ucontext_t structure pointed to by the ucp argument is 0 (zero), then this context is the  main  context,  and
       the thread will exit when this context returns.	The effects of passing a ucp argument from any other source are unspecified.

NOTES

       When  a	signal	handler executes, 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() function, the original context cannot be restored, and the result of future calls  to  the  getcontext()
       function are unpredictable.  Use the siglongjmp() or setcontext() functions in signal handlers, instead of the longjmp() function.

RETURN VALUES

       The  setcontext()  function does not return upon success.  The getcontext() function returns 0 (zero) upon success.  Upon failure, both the
       setcontext() and getcontext() functions return a value of -1.

SEE ALSO

       Functions:  bsd_signal(2), makecontext(2), sigaction(2), sigaltstack(2), sigprocmask(2), setjmp(3), sigsetjmp(3)

       Files:  ucontext(5)

       Standards:  standards(5)

																     getcontext(2)