Quick ?s
Cheat Sheets
Man Pages
The Lynx
Software
GETCONTEXT(2)		   Linux Programmers Manual		GETCONTEXT(2)



NAME
       getcontext, setcontext - get or set the user context

SYNOPSIS
       #include 

       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  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 {
	       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 .  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  threads  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.

CONFORMING TO
       SUSv2, POSIX.1-2001.

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 wont  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 3.05 of the Linux man-pages project.  A
       description of the project, and information about reporting  bugs,  can
       be found at http://www.kernel.org/doc/man-pages/.



Linux				  2001-11-15			 GETCONTEXT(2)




Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:24 2009