1setjmp(3C)               Standard C Library Functions               setjmp(3C)
2
3
4

NAME

6       setjmp, sigsetjmp, longjmp, siglongjmp - non-local goto
7

SYNOPSIS

9       #include <setjmp.h>
10
11       int setjmp(jmp_buf env);
12
13
14       int sigsetjmp(sigjmp_buf env, int savemask);
15
16
17       void longjmp(jmp_buf env, int val);
18
19
20       void siglongjmp(sigjmp_buf env, int val);
21
22

DESCRIPTION

24       These  functions  are  useful  for  dealing with errors  and interrupts
25       encountered in a low-level subroutine of a program.
26
27
28       The setjmp() function saves its stack environment in env for later  use
29       by longjmp().
30
31
32       The  sigsetjmp()  function  saves  the  calling process's registers and
33       stack environment (see sigaltstack(2)) in  env for later  use  by  sig‐
34       longjmp().  If  savemask is non-zero, the calling process's signal mask
35       (see sigprocmask(2)) and scheduling parameters  (see  priocntl(2))  are
36       also saved.
37
38
39       The  longjmp() function restores the environment saved by the last call
40       of setjmp() with the corresponding env argument. After  longjmp()  com‐
41       pletes,  program  execution  continues  as if the corresponding call to
42       setjmp() had just returned the value val. The caller of  setjmp()  must
43       not  have returned in the interim.  The longjmp() function cannot cause
44       setjmp() to return the value 0.  If longjmp() is invoked with a  second
45       argument of 0, setjmp() will return 1. At the time of the second return
46       from setjmp(), all external and static variables have values as of  the
47       time longjmp() is called (see EXAMPLES).
48
49
50       The  siglongjmp()  function  restores the environment saved by the last
51       call of sigsetjmp() with the corresponding  env  argument.  After  sig‐
52       longjmp()  completes, program execution continues as if the correspond‐
53       ing call to sigsetjmp() had just  returned  the  value  val.  The  sig‐
54       longjmp()  function cannot cause sigsetjmp() to return the value 0.  If
55       siglongjmp() is invoked with a second argument of 0,  sigsetjmp()  will
56       return 1. At the time of the second return from sigsetjmp(), all exter‐
57       nal and static variables have values as of the  time  siglongjmp()  was
58       called.
59
60
61       If  a  signal-catching  function  interrupts  sleep(3C)  and calls sig‐
62       longjmp() to restore an environment saved prior to  the  sleep()  call,
63       the  action associated with SIGALRM and time it is scheduled to be gen‐
64       erated are unspecified. It is also unspecified whether the SIGALRM sig‐
65       nal is blocked, unless the process's signal mask is restored as part of
66       the environment.
67
68
69       The  siglongjmp() function restores the saved signal mask if  and  only
70       if the  env argument was initialized by a call to the sigsetjmp() func‐
71       tion with a non-zero  savemask argument.
72
73
74       The values of register and automatic variables are undefined.  Register
75       or automatic variables whose value must be relied upon must be declared
76       as volatile.
77

RETURN VALUES

79       If the return is from a direct  invocation,  setjmp()  and  sigsetjmp()
80       return 0. If the return is from a call to longjmp(), setjmp() returns a
81       non-zero  value.  If  the  return  is  from  a  call  to  siglongjmp(),
82       sigsetjmp() returns a non-zero value.
83
84
85       After  longjmp()  is  completed,  program execution continues as if the
86       corresponding invocation of setjmp() had just returned the value speci‐
87       fied  by val. The longjmp() function cannot cause setjmp() to return 0;
88       if val is 0, setjmp() returns 1.
89
90
91       After siglongjmp() is completed, program execution continues as if  the
92       corresponding  invocation  of  sigsetjmp()  had just returned the value
93       specified by val. The siglongjmp() function cannot cause sigsetjmp() to
94       return 0; if val is 0, sigsetjmp() returns 1.
95

EXAMPLES

97       Example 1 Example of setjmp() and longjmp() functions.
98
99
100       The  following  example  uses both setjmp() and longjmp() to return the
101       flow of control to the appropriate instruction block:
102
103
104         #include <stdio.h>
105         #include <setjmp.h>
106         #include <signal.h>
107         #include <unistd.h>
108         jmp_buf env; static void signal_handler();
109
110         main()  {
111                 int returned_from_longjump, processing = 1;
112                 unsigned int time_interval = 4;
113                 if ((returned_from_longjump = setjmp(env)) != 0)
114                     switch (returned_from_longjump)     {
115                       case SIGINT:
116                         printf("longjumped from interrupt %d\n",SIGINT);
117                         break;
118                       case SIGALRM:
119                         printf("longjumped from alarm %d\n",SIGALRM);
120                         break;
121                     }
122                 (void) signal(SIGINT, signal_handler);
123                 (void) signal(SIGALRM, signal_handler);
124                 alarm(time_interval);
125                 while (processing)        {
126                   printf(" waiting for you to INTERRUPT (cntrl-C) ...\n");
127                   sleep(1);
128                 }       /* end while forever loop */
129         }
130
131         static void signal_handler(sig)
132         int sig; {
133                 switch (sig)     {
134                   case SIGINT:   ...    /* process for interrupt */
135                                  longjmp(env,sig);
136                                         /* break never reached */
137                   case SIGALRM:  ...    /* process for alarm */
138                                  longjmp(env,sig);
139                                        /* break never reached */
140                   default:       exit(sig);
141                 }
142         }
143
144
145
146       When this example is compiled and  executed,  and  the  user  sends  an
147       interrupt signal, the output will be:
148
149
150         longjumped from interrupt
151
152
153
154
155       Additionally,  every  4  seconds the alarm will expire, signalling this
156       process, and the output will be:
157
158
159         longjumped from alarm
160
161
162

ATTRIBUTES

164       See attributes(5) for descriptions of the following attributes:
165
166
167
168
169       ┌─────────────────────────────┬─────────────────────────────┐
170       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
171       ├─────────────────────────────┼─────────────────────────────┤
172       │Interface Stability          │Standard                     │
173       ├─────────────────────────────┼─────────────────────────────┤
174       │MT-Level                     │Unsafe                       │
175       └─────────────────────────────┴─────────────────────────────┘
176

SEE ALSO

178       getcontext(2),  priocntl(2),  sigaction(2),  sigaltstack(2),   sigproc‐
179       mask(2), signal(3C), attributes(5), standards(5)
180

WARNINGS

182       If  longjmp()  or  siglongjmp()  are  called  even though env was never
183       primed by a call to setjmp() or sigsetjmp(), or when the last such call
184       was in a function that has since returned, the results are undefined.
185
186
187
188SunOS 5.11                        14 Aug 2002                       setjmp(3C)
Impressum