gen/setjmp.3

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)setjmp.3    8.1 (Berkeley) 6/4/93
  37 .\" $FreeBSD: src/lib/libc/gen/setjmp.3,v 1.9 2001/10/01 16:08:51 ru Exp $
  38 .\"
  39 .Dd June 4, 1993
  40 .Dt SETJMP 3
  41 .Os
  42 .Sh NAME
  43 .Nm _longjmp ,
  44 .Nm _setjmp ,
  45 .Nm longjmp ,
  46 .Nm longjmperror ,
  47 .Nm setjmp ,
  48 .Nm siglongjmp ,
  49 .Nm sigsetjmp
  50 .Nd non-local jumps
  51 .Sh LIBRARY
  52 .Lb libc
  53 .Sh SYNOPSIS
  54 .In setjmp.h
  55 .Ft void
  56 .Fo _longjmp
  57 .Fa "jmp_buf env"
  58 .Fa "int val"
  59 .Fc
  60 .Ft int
  61 .Fo _setjmp
  62 .Fa "jmp_buf env"
  63 .Fc
  64 .Ft void
  65 .Fo longjmp
  66 .Fa "jmp_buf env"
  67 .Fa "int val"
  68 .Fc
  69 .Ft void
  70 .Fo longjmperror
  71 .Fa void
  72 .Fc
  73 .Ft int
  74 .Fo setjmp
  75 .Fa "jmp_buf env"
  76 .Fc
  77 .Ft void
  78 .Fo siglongjmp
  79 .Fa "sigjmp_buf env"
  80 .Fa "int val"
  81 .Fc
  82 .Ft int
  83 .Fo sigsetjmp
  84 .Fa "sigjmp_buf env"
  85 .Fa "int savemask"
  86 .Fc
  87 .Sh DESCRIPTION
  88 The
  89 .Fn sigsetjmp ,
  90 .Fn setjmp ,
  91 and
  92 .Fn _setjmp
  93 functions save their calling environment in
  94 .Fa env .
  95 Each of these functions returns 0.
  96 .Pp
  97 The corresponding
  98 .Fn longjmp
  99 functions restore the environment saved by their most recent respective
 100 invocations
 101 of the
 102 .Fn setjmp
 103 function.
 104 They then return, so that program execution continues
 105 as if the corresponding invocation of the
 106 .Fn setjmp
 107 call had just returned the value specified by
 108 .Fa val ,
 109 instead of 0.
 110 .Pp
 111 Pairs of calls may be intermixed
 112 (i.e., both
 113 .Fn sigsetjmp
 114 and
 115 .Fn siglongjmp
 116 and
 117 .Fn setjmp
 118 and
 119 .Fn longjmp
 120 combinations may be used in the same program); however, individual
 121 calls may not (e.g. the
 122 .Fa env
 123 argument to
 124 .Fn setjmp
 125 may not be passed to
 126 .Fn siglongjmp ) .
 127 .Pp
 128 The
 129 .Fn longjmp
 130 routines may not be called after the routine which called the
 131 .Fn setjmp
 132 routines returns.
 133 .Pp
 134 All accessible objects have values as of the time
 135 .Fn longjmp
 136 routine was called, except that the values of objects of automatic storage
 137 invocation duration that do not have the
 138 .Em volatile
 139 type and have been changed between the
 140 .Fn setjmp
 141 invocation and
 142 .Fn longjmp
 143 call are indeterminate.
 144 .Pp
 145 The
 146 .Fn setjmp Ns / Ns Fn longjmp
 147 pairs save and restore the signal mask while
 148 .Fn _setjmp Ns / Ns Fn _longjmp
 149 pairs save and restore only the register set and the stack.
 150 (See
 151 .Fn sigprocmask 2 . )
 152 .Pp
 153 The
 154 .Fn sigsetjmp Ns / Ns Fn siglongjmp
 155 function
 156 pairs save and restore the signal mask if the argument
 157 .Fa savemask
 158 is non-zero; otherwise, only the register set and the stack are saved.
 159 .Sh ERRORS
 160 If the contents of the
 161 .Fa env
 162 are corrupted, or correspond to an environment that has already returned,
 163 the
 164 .Fn longjmp
 165 routine calls the routine
 166 .Fn longjmperror 3 .
 167 If
 168 .Fn longjmperror
 169 returns, the program is aborted (see
 170 .Xr abort 3 ) .
 171 The default version of
 172 .Fn longjmperror
 173 prints the message
 174 .Dq Li longjmp botch
 175 to standard error and returns.
 176 User programs wishing to exit more gracefully should write their own
 177 versions of
 178 .Fn longjmperror .
 179 .Sh SEE ALSO
 180 .Xr sigaction 2 ,
 181 .Xr sigaltstack 2 ,
 182 .Xr signal 3
 183 .Sh STANDARDS
 184 The
 185 .Fn setjmp
 186 and
 187 .Fn longjmp
 188 functions conform to
 189 .St -isoC .
 190 The
 191 .Fn sigsetjmp
 192 and
 193 .Fn siglongjmp
 194 functions conform to
 195 .St -p1003.1-88 .