int f(void)
   {  /* outer function */
   int g(void)
      {  /* NOT PERMITTED */
      .....

C does, however, suffer in another way because of this design decision. It provides no easy way to transfer control out of a function except by returning to the expression that called the function. For the vast majority of function calls, that is a desirable limitation. You want the discipline of nested function calls and returns to help you understand flow of control through a program. Nevertheless, on some occasions that discipline is too restrictive. The program is sometimes easier to write, and to understand, if you can jump out of one or more function invocations at a single stroke. You want to bypass the normal function returns and transfer control to somewhere in an earlier function invocation. That's often the best way to handle a serious error.

function x: integer; {a Pascal
goto example}
   label 99;
   function y(val: integer):
integer;
      begin
      if val < 0 then
         goto 99;
      .....

A goto within the same function can often simply transfer control to the statement with the proper label. A nonlocal goto has more work to do. It must terminate execution of the active function invocation. That involves freeing any dynamically allocated storage and restoring the previous calling environment. Pascal even closes any files associated with any file variables freed this way. The function that called the function containing the goto statement is once again the active function. If the label named in the goto statement is not in the now-active function, the process repeats. Eventually, the proper function is once again active and control transfers to the statement with the proper label. The expression that invoked the function containing the goto never completes execution.

Pascal uses the nesting of functions to impose some discipline on the nonlocal goto statements you can write. The language won't let you transfer control into a function that is not active. You have no way of writing a transfer of control to an unknown function. Here is one of the ways that Pascal is arguably better than C.

The PL/I approach is rather less structured than the one used by Pascal. You can write a goto statement that names an uninitialized label variable. Or the label assigned to the variable may be out of date — it may designate the invocation of a function that has terminated. In either case, the effect can be disastrous. Unless the implementation can validate the contents of a label variable before it transfers control, it will make a wild jump. Such errors are hard to debug.

C implements nonlocal transfers of control by using library functions. The header <setjmp.h> provides the necessary machinery:

• the type jmp_buf, which you can think of as a label data-object type
• the function longjmp, which performs the nonlocal transfer of control
• the macro setjmp which stores information on the current calling context in a data object of type jmp_buf and which marks where you want control to pass on a corresponding longjmp call

longjmp and setjmp are delicate functions. They do violence to the flow of control and to the management of dynamic storage. Both of those arenas are the province of a portion of the translator that is extremely complex and hard to write. That part must generate code that is both correct and optimized for space and speed. Optimizations often involve subtle changes in flow of control or the use of dynamic storage. Yet the code generator often works in ignorance of the properties and actions of longjmp and setjmp.

• the expression that contains the setjmp macro
• the dynamic storage declared in the function that executes setjmp

One of the dangers lies in expression evaluation. A typical computer has some number of registers that it uses to hold intermediate results while evaluating an expression. Write a sufficiently complex expression, however, and you may exhaust the available registers. You then force the code generator to store intermediate results in various bits of dynamic storage.

Here is where the problem comes in. setjmp must guess how much "calling context" to store in the jmp_buf data object. It is a safe bet that certain registers must be saved. A register that can hold intermediate results across a function call is a prime candidate, since the longjmp call can be in a called function. Once the program evaluates setjmp, it needs these intermediate results to complete evaluation of the expression. If setjmp fails to save all intermediate results, a subsequent return stimulated by a longjmp call will misbehave.

The C Standard legislates the kind of expressions that can contain setjmp as a subexpression. The idea is to preclude any expressions that might store intermediate results in dynamic storage that is unknown (and unknowable) to setjmp. Thus you can write forms such as:

• switch (setjmp(buf)) .....
• if (2 < setjmp(buf)) .....
• if (!setjmp(buf)) .....
• the expression statement setjmp(buf)

n = setjmp(buf)

The second danger concerns the treatment of dynamic storage in a function that executes setjmp. Such storage comes in three flavors:

• the parameters you declare for the function
• any data objects you declare with the auto storage-class specifier,
• any data objects you declare with the register storage-class specifier

Such behavior would be an annoying anomaly if it were predictable. The problem is that it is not predictable. You have no way of knowing which parameters and auto data objects end up in registers. Even data objects you declare as register are uncertain. A translator has no obligation to store any such data objects in registers. Hence, any number of data objects declared in a function have uncertain values if the function executes setjmp and a longjmp call transfers control back to the function. This is hardly a tidy state of affairs.

X3J11 addressed the problem by adding a minor kludge to the language. Declare a dynamic data object to have a volatile type and the translator knows to be more cautious. Such a data object will never be stored in a place that is altered by longmp. This usage admittedly stretches the semantics of volatile, but it does provide a useful service.

The type declared is

jmp_buf

It is unspecified whether setjmp is a macro or an identifier declared with external linkage. If a macro definition is suppressed in order to access an actual function, or a program defines an external identifier with the name setjmp, the behavior is undefined.

#include <setjmp.h>
int setjmp(jmp_buf env);

• the entire controlling expression of a selection or iteration statement;
• one operand of a relational or equality operator with the other operand an integral constant expression, with the resulting expression being the entire controlling expression of a selection or iteration statement;
• the operand of a unary ! operator with the resulting expression being the entire controlling expression of a selection or iteration statement; or
• the entire expression of an expression statement (possibly cast to void).

#include <setjmp.h>
void longjmp(jmp_buf env, int val);

All accessible objects have values as of the time longjmp was called, except that the values of objects of automatic storage duration that are local to the function containing the invocation of the corresponding setjmp macro that do not have volatile-qualified type and have been changed between the setjmp invocation and longjmp call are indeterminate.

As it bypasses the usual function call and return mechanisms, the longjmp function shall execute correctly in contexts of interrupts, signals and any of their associated functions. However, if the longjmp function is invoked from a nested signal handler (that is, from a function invoked as a result of a signal raised during the handling of another signal), the behavior is undefined.

Footnotes:

106. These functions are useful for dealing with unusual conditions encountered in a low-level function of a program.

107. For example, by executing a return statement or because another longjmp call has caused a transfer to a setjmp invocation in a function earlier in the set of nested calls.

• Isolate each call to setjmp in a separate (small) function. That minimizes any issues about which dynamically declared data objects get rolled back on a longjmp call.
• Call setjmp from the controlling expression of a switch statement.
• Perform all the actual processing in a function (call it process) that you call from case zero of the switch statement.
• Report an error and restart process at any point by executing the call longjmp(1).
• Report an error and terminate process at any point by executing the call longjmp(2).

Here is what the top-level function might look like:

#include <setjmp.h>

static jmp_buf jmpbuf;

void top_level(void)
   { /* the top-level function */
   for (; ; )
      switch (setjmp(jmpbuf))
         {  /* switch on alternate returns */
      case 0:  /* first time */
         process();
         return;
      case 1:  /* restart */
         <report error>
         break;
      case 2:  /* terminate */
         <report error>
         return;
      default: /* unknown longjmp argument */
         <report error>
         return;
         }
}

Note in this regard that jmp_buf is an array type. If you write the argument jmpbuf, the translator alters it to a pointer to the first element of the array. That's what setjmp and longjmp expect. So even though jmpbuf appears to be passed by value, it is actually passed by reference. That's how setjmp can store the calling environment in jmpbuf.

For consistency, you should declare each parameter as jmp_buf buf and write the corresponding argument as jmpbuf. Don't declare the parameter as jmp_buf *pbuf or write the argument as &jmpbuf. The latter form is clearer but at odds with the long-standing conventions for calling setjmp and longjmp.

If you choose an alternate form for using setjmp, execute the macro in the smallest possible function you can write. If the translator does not treat setjmp specially, it has less opportunity to surprise you. If it is aware that setjmp is troublesome, it has less code to deoptimize for safety.

Additional caveats apply if you call longjmp from within a signal handler. I will discuss them next month.