setcontext

SYNOPSIS
       #include <ucontext.h>

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


DESCRIPTION
       The  getcontext() function shall initialize the structure pointed to by
       ucp to the current user context of the calling thread.  The  ucontext_t
       type  that ucp points to defines the user context and includes the con-
       tents of the calling thread's machine registers, the signal  mask,  and
       the current execution stack.

       The  setcontext() function shall restore the user context pointed to by
       ucp. A successful call to setcontext() shall not return; program execu-
       tion  resumes at the point specified by the ucp argument passed to set-
       context(). The ucp argument should be created either by a prior call to
       getcontext()  or  makecontext(), or by being passed as an argument to a
       signal handler. If the ucp argument was created with getcontext(), pro-
       gram  execution  continues as if the corresponding call of getcontext()
       had just returned. If the ucp argument was created with  makecontext(),
       program  execution continues with the function passed to makecontext().
       When that function returns, the thread shall continue  as  if  after  a
       call  to  setcontext() with the ucp argument that was input to makecon-
       text(). If the uc_link member of the ucontext_t structure pointed to by
       the  ucp argument is equal to 0, then this context is the main context,
       and the thread shall exit when this context  returns.  The  effects  of
       passing a ucp argument obtained from any other source are unspecified.

RETURN VALUE
       Upon  successful  completion, setcontext() shall not return and getcon-
       text() shall return 0; otherwise, a value of -1 shall be returned.

ERRORS
       No errors are defined.

       The following sections are informative.

EXAMPLES
       Refer to makecontext() .

APPLICATION USAGE
       When a signal handler is executed, the current user  context  is  saved
       and  a  new context is created. If the thread leaves the signal handler
       via longjmp(), then it is unspecified whether the context at  the  time
       of  the corresponding setjmp() call is restored and thus whether future
       calls to getcontext() provide an accurate representation of the current
       context,  since  the context restored by longjmp() does not necessarily
       contain all the information that setcontext() requires. Signal handlers
       should use siglongjmp() or setcontext() instead.

       Conforming  applications  should  not  modify or access the uc_mcontext
       None.

SEE ALSO
       bsd_signal() , makecontext() , setcontext() , setjmp() , sigaction()  ,
       sigaltstack()  ,  siglongjmp() , sigprocmask() , sigsetjmp() , the Base
       Definitions volume of IEEE Std 1003.1-2001, <ucontext.h>

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
       Specifications  Issue  6,  Copyright  (C) 2001-2003 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open  Group.  In  the
       event of any discrepancy between this version and the original IEEE and
       The Open Group Standard, the original IEEE and The Open Group  Standard
       is  the  referee document. The original Standard can be obtained online
       at http://www.opengroup.org/unix/online.html .



IEEE/The Open Group                  2003                        GETCONTEXT(P)