1 .\"  Copyright 1989 AT&T  Copyright (c) 2001, Sun Microsystems, Inc.  All Rights Reserved  Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   3 .\" http://www.opengroup.org/bookstore/.
   4 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions 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.
   5 .\"  This notice shall appear on any product containing this material.
   6 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   7 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   8 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   9 .Dd "Jul 20, 2014"
  10 .Dt GETCONTEXT 2
  11 .Os
  12 .Sh NAME
  13 .Nm getcontext, setcontext
  14 .Nd get and set current user context
  15 .Sh SYNOPSIS
  16 .In ucontext.h
  17 .Ft int
  18 .Fn getcontext "ucontext_t *ucp"
  19 .Ft int
  20 .Fn setcontext "const ucontext_t *ucp"
  21 .Sh DESCRIPTION
  22 The
  23 .Fn getcontext
  24 function initializes the structure pointed to by
  25 .Fa ucp
  26 to the current user context of the calling process.  The
  27 .Fa ucontext_t
  28 type that
  29 .Fa ucp
  30 points to defines the user context and
  31 includes the contents of the calling process' machine registers, the signal
  32 mask, and the current execution stack.
  33 .Lp
  34 The
  35 .Fn setcontext
  36 function restores the user context pointed to by
  37 .Fa ucp .
  38 A successful call to
  39 .Fn setcontext
  40 does not return; program
  41 execution resumes at the point specified by the
  42 .Fa ucp
  43 argument passed to
  44 .Fn setcontext .
  45 The
  46 .Fa ucp
  47 argument should be created either by a prior
  48 call to
  49 .Fn getcontext ,
  50 or by being passed as an argument to a signal
  51 handler.
  52 .Lp
  53 If the
  54 .Fa ucp
  55 argument was created with
  56 .Fn getcontext ,
  57 program execution continues as if the corresponding call of
  58 .Fn getcontext
  59 had just returned.
  60 .Lp
  61 If the
  62 .Fa ucp
  63 argument was created with
  64 .Xr makecontext 3C ,
  65 program execution continues with the function passed to
  66 .Xr makecontext 3C .
  67 When that function returns, the process continues as if after a call to
  68 .Fn setcontext
  69 with the
  70 .Fa ucp
  71 argument that was input to
  72 .Xr makecontext 3C .
  73 .Lp
  74 If the
  75 .Fa ucp
  76 argument was passed to a signal
  77 handler, program execution continues with the program instruction following the
  78 instruction interrupted by the signal.
  79 .Lp
  80 If the
  81 .Fa uc_link
  82 member of the
  83 .Ft ucontext_t
  84 structure pointed to by the
  85 .Fa ucp
  86 argument is equal to 0,
  87 then this context is the main context, and the process will exit when this
  88 context returns.  The effects of passing a
  89 .Fa ucp
  90 argument obtained from any other source are unspecified.
  91 .Sh RETURN VALUES
  92 On successful completion,
  93 .Fn setcontext
  94 does not return and
  95 .Fn getcontext()
  96 returns 0. Otherwise, -1 is returned.
  97 .Sh ERRORS
  98 No errors are defined.
  99 .Sh USAGE
 100 When a signal handler is executed, the current user context is saved and a new
 101 context is created.  If the thread leaves the signal handler via
 102 .Xr longjmp 3C ,
 103 then it is unspecified whether the context at the time of
 104 the corresponding
 105 .Xr setjmp 3C
 106 call is restored and thus whether future
 107 calls to
 108 .Fn getcontext
 109 will provide an accurate representation of the
 110 current context, since the context restored by
 111 .Xr longjmp 3C
 112 may not contain all the information that
 113 .Fn setcontext
 114 requires.  Signal handlers
 115 should use
 116 .Xr siglongjmp 3C
 117 instead.
 118 .Lp
 119 Portable applications should not modify or access the
 120 .Fa uc_mcontext
 121 member
 122 of
 123 .Ft ucontext_t .
 124 A portable application cannot assume that context
 125 includes any process-wide static data, possibly including
 126 .Va errno .
 127 Users manipulating contexts should take care to handle these explicitly when
 128 required.
 129 .Lp
 130 Portable applications should make use of the
 131 .Xr pthreads 5
 132 routines for co-processing instead of these routines.
 133 .Sh INTERFACE STABILITY
 134 .Sy Obsolete Standard .
 135 .Sh SEE ALSO
 136 .Xr sigaction 2 ,
 137 .Xr sigaltstack 2 ,
 138 .Xr sigprocmask 2 ,
 139 .Xr bsd_signal 3C ,
 140 .Xr makecontext 3C ,
 141 .Xr setjmp 3C ,
 142 .Xr sigsetjmp 3C ,
 143 .Xr ucontext.h 3HEAD ,
 144 .Xr pthreads 5 ,
 145 .Xr standards 5
 146 .Sh STANDARDS
 147 These routines were introduced in
 148 .St -xpg4.2
 149 and subsequently removed in
 150 .St -p1003.1-2008 .