unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



getcontext(2)							getcontext(2)



NAME

  getcontext, setcontext - Initiates and restores user level context switch-
  ing

SYNOPSIS

  #include <&lt;ucontext.h>&gt;


  int  getcontext(
	  ucontext_t *ucp );

  int setcontext(
	  const	ucontext_t *ucp	);

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  getcontext(),	setcontext():  XSH5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

PARAMETERS

  ucp Provides a pointer to a ucontext structure, defined in the <&lt;ucontext.h>&gt;
      header file.  The	ucontext structure contains the	signal mask, execu-
      tion stack, and machine registers. (See ucontext(5) for more informa-
      tion about the format of the ucontext structure.)

DESCRIPTION

  Using	both the getcontext() and setcontext() functions enables you to	ini-
  tiate	user level context control, switching between multiple threads of
  control within a single process.

  When you call	getcontext(), it initializes the ucp argument to the current
  user context of the calling process.

  Use the setcontext() function	to restore the state of	the user context
  pointed to by	the ucp	argument.  The setcontext() function, if successful,
  does not return; application execution continues from	the point specified
  by the ucontext structure you	pass to	the setcontext() function.

  The ucontext structure that you pass to the setcontext() function must have
  been created by a call to the	getcontext() function or the makecontext()
  function, or have been passed	as the third argument to a signal handler.
  (The third argument in a call	to the sigaction() function determines the
  action to be performed when a	signal is delivered. For more information,
  see sigaction(2).)

  When a context structure is created by the getcontext() function, execution
  of the program continues as if the corresponding call	of the getcontext()
  function had just returned.


  When a context structure is created by the makecontext() function, program
  execution continues with the function	passed to makecontext().  When that
  function returns, the	thread continues as if after a call to setcontext()
  with the context structure argument that was input to	makecontext().

  If the uc_link member	of the ucontext_t structure pointed to by the ucp
  argument is 0	(zero),	then this context is the main context, and the thread
  will exit when this context returns.	The effects of passing a ucp argument
  from any other source	are unspecified.

NOTES

  When a signal	handler	executes, the current user context is saved and	a new
  context is created by	the kernel.  If	the process leaves the signal handler
  using	the longjmp() function,	the original context cannot be restored, and
  the result of	future calls to	the getcontext() function are unpredictable.
  Use the siglongjmp() or setcontext() functions in signal handlers, instead
  of the longjmp() function.

RETURN VALUES

  The setcontext() function does not return upon success.  The getcontext()
  function returns 0 (zero) upon success.  Upon	failure, both the setcon-
  text() and getcontext() functions return a value of -1.

SEE ALSO

  Functions:  bsd_signal(2), makecontext(2), sigaction(2), sigaltstack(2),
  sigprocmask(2), setjmp(3), sigsetjmp(3)

  Files:  ucontext(5)

  Standards:  standards(5)