GENWiki

Premier IT Outsourcing and Support Services within the UK

User Tools

Site Tools


man:getcontext

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

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  System  V-like environment, one has the two types mcontext_t and
     ucontext_t defined in <ucontext.h> and the four functions getcontext(),
     setcontext(),  makecontext(3), and swapcontext(3) 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 following fields:
         typedef struct ucontext_t {
             struct ucontext_t *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 context was created using makecontext(3)), uc_sig-
     mask  is  the  set  of  signals  blocked  in this context (see sigproc-
     mask(2)), uc_stack is the stack  used  by  this  context  (see  sigalt-
     stack(2)),  and  uc_mcontext  is the machine-specific representation of
     the saved context, that includes the calling  thread's  machine  regis-
     ters.
     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 getcontext(), or  makecontext(3),  or  passed  as
     third argument to a signal handler.
     If  the  context was obtained by a call of getcontext(), program execu-
     tion continues as if this call just returned.
     If the context was obtained by a call of makecontext(3), program execu-
     tion  continues  by a call to the function func specified as the second
     argument of that  call  to  makecontext(3).   When  the  function  func
     returns, we continue with the uc_link member of the structure ucp spec-
     ified as the first argument of that call to makecontext(3).  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 continues with  the  program
     instruction following the instruction interrupted by the signal".  How-
     ever, 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.

ATTRIBUTES

     For  an  explanation  of  the  terms  used   in   this   section,   see
     attributes(7).
     +---------------------------+---------------+------------------+
     |Interface                  | Attribute     | Value            |
     +---------------------------+---------------+------------------+
     |getcontext(), setcontext() | Thread safety | MT-Safe race:ucp |
     +---------------------------+---------------+------------------+

CONFORMING TO

     SUSv2, POSIX.1-2001.  POSIX.1-2008 removes the specification of getcon-
     text(),  citing  portability issues, and recommending that applications
     be rewritten to use POSIX threads instead.

NOTES

     The earliest incarnation of this mechanism was the setjmp(3)/longjmp(3)
     mechanism.   Since that does not define the handling of the signal con-
     text, the next stage  was  the  sigsetjmp(3)/siglongjmp(3)  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 con-
     text is created by the kernel for the signal handler.  Do not leave the
     handler  using  longjmp(3): it is undefined what would happen with con-
     texts.  Use siglongjmp(3) or setcontext() instead.

SEE ALSO

     sigaction(2),  sigaltstack(2),  sigprocmask(2),  longjmp(3),   makecon-
     text(3), sigsetjmp(3)

COLOPHON

     This  page  is  part of release 4.16 of the Linux man-pages project.  A
     description of the project, information about reporting bugs,  and  the
     latest     version     of     this    page,    can    be    found    at
     https://www.kernel.org/doc/man-pages/.

Linux 2017-09-15 GETCONTEXT(3)

/data/webs/external/dokuwiki/data/pages/man/getcontext.txt · Last modified: 2019/05/17 09:47 by 127.0.0.1

Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki