getcontext(2)                                                 getcontext(2)

NAME
     getcontext, setcontext - amend user context

SYNOPSIS
     #include <ucontext.h>

     int getcontext(ucontextt *ucp);

     int setcontext(ucontextt *ucp);

DESCRIPTION
     These functions, along with those defined in makecontext(3C), are use-
     ful for implementing user level context switching between multiple
     threads of control within a process.

     getcontext() initializes the structure pointed to by ucp to the
     current user context of the calling process. The user context is
     defined by ucontext(5) and includes the contents of the calling pro-
     cess' machine registers, signal mask and execution stack.

     setcontext() restores the user context pointed to by ucp. The call to
     setcontext() does not return; program execution resumes at the point
     specified by the context structure passed to setcontext(). The context
     structure should have been one created either by a prior call to
     getcontext() or makecontext() or passed as the third argument to a
     signal handler [see sigaction(2)]. If the context structure was one
     created with getcontext(), program execution continues as if the cor-
     responding call of getcontext() had just returned. If the context
     structure was one created with makecontext(), program execution con-
     tinues with the function specified to makecontext().

     getcontext() and setcontext() will fail if the following is true:

     EFAULT    ucp points to an invalid address.

RESULT
     On successful completion, setcontext() does not return and
     getcontext() returns 0. Otherwise, a value of -1 is returned and errno
     is set to indicate the error.

NOTES
     When a signal handler is executed, the current user context is saved
     and a new context is created by the kernel. If the process leaves the
     signal handler via longjmp(3C) the original context will not be
     restored, and future calls to getcontext() will not be reliable. Sig-
     nal handlers should use siglongjmp(3C) or setcontext() instead.









Page 1                       Reliant UNIX 5.44                Printed 11/98

getcontext(2)                                                 getcontext(2)

     If getcontext() and setcontext() are used in the same way as
     setjmp(3C) and longjmp(3C), it is important that the stack area backed
     up by getcontext() and restored by setcontext() is not used uninten-
     tionally by other functions in between these two calls. In this case,
     getcontext() and setcontext() must be called from the same higher-
     level function.

SEE ALSO
     sigaction(2), sigaltstack(2), sigprocmask(2), makecontext(3C),
     setjmp(3C), ucontext(5).












































Page 2                       Reliant UNIX 5.44                Printed 11/98