setcontext(2)

NAME

     getcontext, setcontext - get and set current user context

SYNOPSIS

     #include <ucontext.h>

     int getcontext(ucontext_t *ucp);

     int setcontext(const ucontext_t *ucp);

DESCRIPTION

     The getcontext() function initializes the structure  pointed
     to  by  ucp  to the current user context of the calling pro-
     cess.  The ucontext_t type that ucp points  to  defines  the
     user  context  and includes the contents of the calling pro-
     cess' machine registers, the signal mask,  and  the  current
     execution stack.

     The setcontext() function restores the user context  pointed
     to  by  ucp.   A  successful  call  to setcontext() does not
     return; program execution resumes at the point specified  by
     the  ucp  argument  passed to setcontext(). The ucp argument
     should be created either by a prior call to getcontext(), or
     by  being  passed as an argument to a signal handler. If the
     ucp argument was created with getcontext(),  program  execu-
     tion  continues as if the corresponding call of getcontext()
     had just returned.  If the ucp  argument  was  created  with
     makecontext(3C),  program execution continues with the func-
     tion passed to makecontext(3C). When that function  returns,
     the  process  continues  as  if after a call to setcontext()
     with the ucp argument that was input to makecontext(3C).  If
     the  ucp  argument  was  passed to a signal handler, program
     execution continues with the program  instruction  following
     the  instruction  interrupted by the signal.  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 con-
     text, and the process will exit when this  context  returns.
     The  effects  of  passing  a  ucp argument obtained from any
     other source are unspecified.

RETURN VALUES

     On successful completion, setcontext() does not  return  and
     getcontext() returns 0. Otherwise, -1 is returned.

ERRORS

     No errors are defined.

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(3UCB), then it is unspecified
     whether  the  context  at  the  time  of  the  corresponding
     setjmp(3UCB) call is restored and thus whether future  calls
     to  getcontext()  will provide an accurate representation of
     the  current  context,  since  the   context   restored   by
     longjmp(3UCB)  may  not  contain  all  the  information that
     setcontext()   requires.    Signal   handlers   should   use
     siglongjmp(3C) instead.

     Portable  applications  should  not  modify  or  access  the
     uc_mcontext  member  of  ucontext_t.  A portable application
     cannot assume that context includes any process-wide  static
     data,  possibly including errno. Users manipulating contexts
     should take care to handle these explicitly when required.

SEE ALSO

     sigaction(2),        sigaltstack(2),         sigprocmask(2),
     bsd_signal(3C),        makecontext(3C),        setjmp(3UCB),
     sigsetjmp(3C), ucontext(3HEAD)