lib/libc/sys/getcontext.2

   1 .\"     $NetBSD: getcontext.2,v 1.7 2010/04/29 06:07:35 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Klaus Klein.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd April 28, 2010
  31 .Dt GETCONTEXT 2
  32 .Os
  33 .Sh NAME
  34 .Nm getcontext ,
  35 .Nm setcontext
  36 .Nd get and set current user context
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In ucontext.h
  41 .Ft int
  42 .Fn getcontext "ucontext_t *ucp"
  43 .Ft int
  44 .Fn setcontext "const ucontext_t *ucp"
  45 .Sh DESCRIPTION
  46 The
  47 .Fn getcontext
  48 function initializes the object pointed to by
  49 .Fa ucp
  50 to the current user context of the calling thread.
  51 The user context defines a thread's execution environment and includes
  52 the contents of its machine registers,
  53 its signal mask,
  54 and its current execution stack.
  55 .Pp
  56 The
  57 .Fn setcontext
  58 function restores the user context defined in the object pointed to by
  59 .Fa ucp
  60 as most recently initialized by a previous call to either
  61 .Fn getcontext
  62 or
  63 .Xr makecontext 3 .
  64 .\" TODO: signal handler
  65 If successful, execution of the program resumes as defined in the
  66 .Fa ucp
  67 argument, and
  68 .Fn setcontext
  69 will not return.
  70 If
  71 .Fa ucp
  72 was initialized by the
  73 .Fn getcontext
  74 function, program execution continues as if the corresponding invocation of
  75 .Fn getcontext
  76 had just returned (successfully).
  77 If
  78 .Fa ucp
  79 was initialized by the
  80 .Xr makecontext 3
  81 function, program execution continues with the function (and function
  82 arguments) passed to
  83 .Xr makecontext 3 .
  84 .Sh RETURN VALUES
  85 On successful completion,
  86 .Fn getcontext
  87 returns 0 and
  88 .Fn setcontext
  89 does not return.
  90 Otherwise a value of \-1 is returned and
  91 .Va errno
  92 is set to indicate the error.
  93 .Sh ERRORS
  94 The
  95 .Fn getcontext
  96 and
  97 .Fn setcontext
  98 functions will fail if:
  99 .Bl -tag -width Er
 100 .It Bq Er EFAULT
 101 The
 102 .Fa ucp
 103 argument points to an invalid address.
 104 .El
 105 .Pp
 106 The
 107 .Fn setcontext
 108 function will fail if:
 109 .Bl -tag -width Er
 110 .It Bq Er EINVAL
 111 The contents of the datum pointed to by
 112 .Fa ucp
 113 are invalid.
 114 .El
 115 .Sh SEE ALSO
 116 .Xr sigprocmask 2 ,
 117 .Xr longjmp 3 ,
 118 .Xr makecontext 3 ,
 119 .Xr setjmp 3 ,
 120 .Xr swapcontext 3
 121 .Sh STANDARDS
 122 The
 123 .Fn getcontext
 124 and
 125 .Fn setcontext
 126 functions conform to
 127 .St -xsh5
 128 and
 129 .St -p1003.1-2001 .
 130 The
 131 .Va errno
 132 indications are an extension to the standard.
 133 .Pp
 134 The
 135 .St -p1003.1-2004
 136 revision marked the functions
 137 .Fn getcontext
 138 and
 139 .Fn setcontext
 140 as obsolete, citing portability issues and recommending the use of
 141 .Tn POSIX
 142 threads instead.
 143 The
 144 .St -p1003.1-2008
 145 revision removed the functions from the specification.
 146 .Sh HISTORY
 147 The
 148 .Fn getcontext
 149 and
 150 .Fn setcontext
 151 functions first appeared in
 152 .At V.4 .