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 thread.  The user context
             is defined by ucontext(5) and includes the contents of the
             calling thread'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.

          Return Values
             On success, setcontext does not return and getcontext returns
             0.  On failure, setcontext and getcontext return -1 and set
             errno to identify the error.

       REFERENCES
             makecontext(3C), setjmp(3C), sigaction(2), sigaltstack(2),
             sigprocmask(2), ucontext(5)

       NOTICES
             When a signal handler is executed, the current user context is
             saved and a new context is created by the kernel.  If the
             thread leaves the signal handler via longjmp [see setjmp(3C)]
             the original context will not be restored, and future calls to


                           Copyright 1994 Novell, Inc.               Page 1

      getcontext(2)                                          getcontext(2)


            getcontext will not be reliable.  Signal handlers should use
            siglongjmp [see setjmp(3C)] or setcontext instead.

         Considerations for Threads Programming
            setcontext affects the calling thread only; siblings are not
            affected.

         Considerations for Lightweight Processes
            The Threads Library has a wrapper function for setcontext that
            will set the thread's signal mask as well.  The system call
            itself only modifies the underlying LWP.





































                          Copyright 1994 Novell, Inc.               Page 2