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. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)setjmp.3    8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD: src/lib/libc/gen/setjmp.3,v 1.5.2.5 2003/03/15 15:11:05 trhodes Exp $
  34 .\" $DragonFly: src/lib/libc/gen/setjmp.3,v 1.2 2003/06/17 04:26:42 dillon Exp $
  35 .\"
  36 .Dd June 4, 1993
  37 .Dt SETJMP 3
  38 .Os
  39 .Sh NAME
  40 .Nm sigsetjmp ,
  41 .Nm siglongjmp ,
  42 .Nm setjmp ,
  43 .Nm longjmp ,
  44 .Nm _setjmp ,
  45 .Nm _longjmp ,
  46 .Nm longjmperror
  47 .Nd non-local jumps
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In setjmp.h
  52 .Ft int
  53 .Fn sigsetjmp "sigjmp_buf env" "int savemask"
  54 .Ft void
  55 .Fn siglongjmp "sigjmp_buf env" "int val"
  56 .Ft int
  57 .Fn setjmp "jmp_buf env"
  58 .Ft void
  59 .Fn longjmp "jmp_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 void
  65 .Fn longjmperror void
  66 .Sh DESCRIPTION
  67 The
  68 .Fn sigsetjmp ,
  69 .Fn setjmp ,
  70 and
  71 .Fn _setjmp
  72 functions save their calling environment in
  73 .Fa env .
  74 Each of these functions returns 0.
  75 .Pp
  76 The corresponding
  77 .Fn longjmp
  78 functions restore the environment saved by their most recent respective
  79 invocations
  80 of the
  81 .Fn setjmp
  82 function.
  83 They then return so that program execution continues as if the corresponding
  84 invocation of the
  85 .Fn setjmp
  86 call had just returned  the value specified by
  87 .Fa val ,
  88 instead of 0.
  89 .Pp
  90 Pairs of calls may be intermixed, i.e. both
  91 .Fn sigsetjmp
  92 and
  93 .Fn siglongjmp
  94 and
  95 .Fn setjmp
  96 and
  97 .Fn longjmp
  98 combinations may be used in the same program, however, individual
  99 calls may not, e.g. the
 100 .Fa env
 101 argument to
 102 .Fn setjmp
 103 may not be passed to
 104 .Fn siglongjmp .
 105 .Pp
 106 The
 107 .Fn longjmp
 108 routines may not be called after the routine which called the
 109 .Fn setjmp
 110 routines returns.
 111 .Pp
 112 All accessible objects have values as of the time
 113 .Fn longjmp
 114 routine was called, except that the values of objects of automatic storage
 115 invocation duration that do not have the
 116 .Vt volatile
 117 type and have been changed between the
 118 .Fn setjmp
 119 invocation and
 120 .Fn longjmp
 121 call are indeterminate.
 122 .Pp
 123 The
 124 .Fn setjmp Ns / Ns Fn longjmp
 125 pairs save and restore the signal mask while
 126 .Fn _setjmp Ns / Ns Fn _longjmp
 127 pairs save and restore only the register set and the stack.
 128 (See
 129 .Fn sigprocmask 2 . )
 130 .Pp
 131 The
 132 .Fn sigsetjmp Ns / Ns Fn siglongjmp
 133 function
 134 pairs save and restore the signal mask if the argument
 135 .Fa savemask
 136 is non-zero, otherwise only the register set and the stack are saved.
 137 .Sh ERRORS
 138 If the contents of the
 139 .Fa env
 140 are corrupted, or correspond to an environment that has already returned,
 141 the
 142 .Fn longjmp
 143 routine calls the routine
 144 .Fn longjmperror 3 .
 145 If
 146 .Fn longjmperror
 147 returns the program is aborted (see
 148 .Xr abort 3 ) .
 149 The default version of
 150 .Fn longjmperror
 151 prints the message
 152 .Dq Li longjmp botch
 153 to standard error and returns.
 154 User programs wishing to exit more gracefully should write their own
 155 versions of
 156 .Fn longjmperror .
 157 .Sh SEE ALSO
 158 .Xr sigaction 2 ,
 159 .Xr sigaltstack 2 ,
 160 .Xr signal 3
 161 .Sh STANDARDS
 162 The
 163 .Fn setjmp
 164 and
 165 .Fn longjmp
 166 functions conform to
 167 .St -isoC .
 168 The
 169 .Fn sigsetjmp
 170 and
 171 .Fn siglongjmp
 172 functions conform to
 173 .St -p1003.1-88 .