lib/libc/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.5.2.5 2003/03/15 15:11:05 trhodes Exp $
  38 .\" $DragonFly: src/lib/libc/gen/setjmp.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
  39 .\"
  40 .Dd June 4, 1993
  41 .Dt SETJMP 3
  42 .Os
  43 .Sh NAME
  44 .Nm sigsetjmp ,
  45 .Nm siglongjmp ,
  46 .Nm setjmp ,
  47 .Nm longjmp ,
  48 .Nm _setjmp ,
  49 .Nm _longjmp ,
  50 .Nm longjmperror
  51 .Nd non-local jumps
  52 .Sh LIBRARY
  53 .Lb libc
  54 .Sh SYNOPSIS
  55 .In setjmp.h
  56 .Ft int
  57 .Fn sigsetjmp "sigjmp_buf env" "int savemask"
  58 .Ft void
  59 .Fn siglongjmp "sigjmp_buf env" "int val"
  60 .Ft int
  61 .Fn setjmp "jmp_buf env"
  62 .Ft void
  63 .Fn longjmp "jmp_buf env" "int val"
  64 .Ft int
  65 .Fn _setjmp "jmp_buf env"
  66 .Ft void
  67 .Fn _longjmp "jmp_buf env" "int val"
  68 .Ft void
  69 .Fn longjmperror void
  70 .Sh DESCRIPTION
  71 The
  72 .Fn sigsetjmp ,
  73 .Fn setjmp ,
  74 and
  75 .Fn _setjmp
  76 functions save their calling environment in
  77 .Fa env .
  78 Each of these functions returns 0.
  79 .Pp
  80 The corresponding
  81 .Fn longjmp
  82 functions restore the environment saved by their most recent respective
  83 invocations
  84 of the
  85 .Fn setjmp
  86 function.
  87 They then return so that program execution continues as if the corresponding
  88 invocation of the
  89 .Fn setjmp
  90 call had just returned  the value specified by
  91 .Fa val ,
  92 instead of 0.
  93 .Pp
  94 Pairs of calls may be intermixed, i.e. both
  95 .Fn sigsetjmp
  96 and
  97 .Fn siglongjmp
  98 and
  99 .Fn setjmp
 100 and
 101 .Fn longjmp
 102 combinations may be used in the same program, however, individual
 103 calls may not, e.g. the
 104 .Fa env
 105 argument to
 106 .Fn setjmp
 107 may not be passed to
 108 .Fn siglongjmp .
 109 .Pp
 110 The
 111 .Fn longjmp
 112 routines may not be called after the routine which called the
 113 .Fn setjmp
 114 routines returns.
 115 .Pp
 116 All accessible objects have values as of the time
 117 .Fn longjmp
 118 routine was called, except that the values of objects of automatic storage
 119 invocation duration that do not have the
 120 .Vt volatile
 121 type and have been changed between the
 122 .Fn setjmp
 123 invocation and
 124 .Fn longjmp
 125 call are indeterminate.
 126 .Pp
 127 The
 128 .Fn setjmp Ns / Ns Fn longjmp
 129 pairs save and restore the signal mask while
 130 .Fn _setjmp Ns / Ns Fn _longjmp
 131 pairs save and restore only the register set and the stack.
 132 (See
 133 .Fn sigprocmask 2 . )
 134 .Pp
 135 The
 136 .Fn sigsetjmp Ns / Ns Fn siglongjmp
 137 function
 138 pairs save and restore the signal mask if the argument
 139 .Fa savemask
 140 is non-zero, otherwise only the register set and the stack are saved.
 141 .Sh ERRORS
 142 If the contents of the
 143 .Fa env
 144 are corrupted, or correspond to an environment that has already returned,
 145 the
 146 .Fn longjmp
 147 routine calls the routine
 148 .Fn longjmperror 3 .
 149 If
 150 .Fn longjmperror
 151 returns the program is aborted (see
 152 .Xr abort 3 ) .
 153 The default version of
 154 .Fn longjmperror
 155 prints the message
 156 .Dq Li longjmp botch
 157 to standard error and returns.
 158 User programs wishing to exit more gracefully should write their own
 159 versions of
 160 .Fn longjmperror .
 161 .Sh SEE ALSO
 162 .Xr sigaction 2 ,
 163 .Xr sigaltstack 2 ,
 164 .Xr signal 3
 165 .Sh STANDARDS
 166 The
 167 .Fn setjmp
 168 and
 169 .Fn longjmp
 170 functions conform to
 171 .St -isoC .
 172 The
 173 .Fn sigsetjmp
 174 and
 175 .Fn siglongjmp
 176 functions conform to
 177 .St -p1003.1-88 .