1setjmp(3C) Standard C Library Functions setjmp(3C)
2
6 setjmp, sigsetjmp, longjmp, siglongjmp - non-local goto
7
9 #include <setjmp.h>
10 int setjmp(jmp_buf env);
12 int sigsetjmp(sigjmp_buf env, int savemask);
15 void longjmp(jmp_buf env, int val);
18 void siglongjmp(sigjmp_buf env, int val);
21
24 These functions are useful for dealing with errors and interrupts
25 encountered in a low-level subroutine of a program.
26 The setjmp() function saves its stack environment in env for later use
29 by longjmp().
30 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 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 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 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 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 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
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 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 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
97 Example 1 Example of setjmp() and longjmp() functions.
98 The following example uses both setjmp() and longjmp() to return the
101 flow of control to the appropriate instruction block:
102 #include <stdio.h>
105 #include <setjmp.h>
106 #include <signal.h>
107 #include <unistd.h>
108 jmp_buf env; static void signal_handler();
109 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 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 When this example is compiled and executed, and the user sends an
147 interrupt signal, the output will be:
148 longjumped from interrupt
151 Additionally, every 4 seconds the alarm will expire, signalling this
156 process, and the output will be:
157 longjumped from alarm
160
164 See attributes(5) for descriptions of the following attributes:
165 ┌─────────────────────────────┬─────────────────────────────┐
170 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
171 ├─────────────────────────────┼─────────────────────────────┤
172 │Interface Stability │Standard │
173 ├─────────────────────────────┼─────────────────────────────┤
174 │MT-Level │Unsafe │
175 └─────────────────────────────┴─────────────────────────────┘
176
178 getcontext(2), priocntl(2), sigaction(2), sigaltstack(2), sigproc‐
179 mask(2), signal(3C), attributes(5), standards(5)
180
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.
185SunOS 5.11 14 Aug 2002 setjmp(3C)