getcontext(2)                                                 getcontext(2)


   NAME
         getcontext, setcontext - get and set current user context

   SYNOPSIS
         #include <ucontext.h>
         int getcontext(ucontext_t *ucp);
         int setcontext(ucontext_t *ucp);

   DESCRIPTION
         These functions, along with those defined in makecontext(3C), are
         useful 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 process's
         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 corresponding
         call of getcontext had just returned.  If the context structure was
         one created with makecontext, program execution continues with the
         function specified to makecontext.

   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.
         Signal handlers should use siglongjmp(3C) or setcontext instead.

         getcontext and setcontext will fail if the following is true:

         EFAULT         ucp points to an invalid address.

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

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





   7/91                                                                 Page 1