GETCONTEXT(T)       Linux Programmer's Manual       GETCONTEXT(T)



NAME
       getcontext, setcontext - get or set the user context

SYNOPSIS
       #include <ucontext.h>

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

DESCRIPTION
       In  a  SysV-like  environment, one has the two types mcon-
       text_t and ucontext_t defined in <ucontext.h> and the four
       functions  getcontext(),  setcontext(),  makecontext() and
       swapcontext()  that  allow  user-level  context  switching
       between multiple threads of control within a process.

       The  mcontext_t type is machine-dependent and opaque.  The
       ucontext_t type is a structure that has at least the  fol-
       lowing fields:
              typedef struct ucontext {
                   struct ucontext *uc_link;
                   sigset_t uc_sigmask;
                   stack_t uc_stack;
                   mcontext_t uc_mcontext;
                   ...
              } ucontext_t;
       with  sigset_t  and  stack_t  defined in <signal.h>.  Here
       uc_link points to the context that will  be  resumed  when
       the  current  context terminates (in case the current con-
       text was created using makecontext()), uc_sigmask  is  the
       set  of  signals  blocked  in  this  context (see sigproc-
       mask(k)), uc_stack is the stack used by this context  (see
       sigaltstack(k)),  and  uc_mcontext is the machine-specific
       representation of the saved  context,  that  includes  the
       calling thread's machine registers.

       The   function   getcontext()  initializes  the  structure
       pointed at by ucp to the currently active context.

       The  function  setcontext()  restores  the  user   context
       pointed at by ucp. A successful call does not return.  The
       context should have been obtained by  a  call  of  getcon-
       text(), or makecontext(), or passed as third argument to a
       signal handler.

       If the context was obtained by  a  call  of  getcontext(),
       program execution continues as if this call just returned.

       If the context was obtained by a  call  of  makecontext(),
       program execution continues by a call to the function func
       specified as the second argument of that call to  makecon-
       text().   When the function func returns, we continue with
       the uc_link member of the structure ucp specified  as  the
       first  argument  of that call to makecontext().  When this
       member is NULL, the thread exits.

       If the context was obtained by a call to a signal handler,
       then  old  standard text says that "program execution con-
       tinues with the program instruction following the instruc-
       tion  interrupted  by  the signal". However, this sentence
       was removed in SUSv2, and  the  present  verdict  is  "the
       result is unspecified".

RETURN VALUE
       When  successful,  getcontext() returns 0 and setcontext()
       does not return. On error, both return -1  and  set  errno
       appropriately.

ERRORS
       None defined.

NOTES
       The   earliest  incarnation  of  this  mechanism  was  the
       setjmp()/longjmp() mechanism. Since that does  not  define
       the handling of the signal context, the next stage was the
       sigsetjmp()/siglongjmp()  pair.   The  present   mechanism
       gives  much  more  control. On the other hand, there is no
       easy way to detect whether a return from  getcontext()  is
       from the first call, or via a setcontext() call.  The user
       has to invent her own bookkeeping device, and  a  register
       variable won't do since registers are restored.

       When  a  signal  occurs, the current user context is saved
       and a new context is created by the kernel for the  signal
       handler.  Do not leave the handler using longjmp() - it is
       undefined  what  would  happen  with  contexts.  Use  sig-
       longjmp() or setcontext() instead.

CONFORMING TO
       SUSv2

SEE ALSO
       sigaction(n),  sigaltstack(k), sigprocmask(k), longjmp(p),
       sigsetjmp(p), makecontext(t)




Linux 2.4                   2001-11-15              GETCONTEXT(T)