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