1: @node Non-Local Exits, Signal Handling, Resource Usage And Limitation, Top
    2: @c %MENU% Jumping out of nested function calls
    3: @chapter Non-Local Exits
    4: @cindex non-local exits
    5: @cindex long jumps
    6: 
    7: Sometimes when your program detects an unusual situation inside a deeply
    8: nested set of function calls, you would like to be able to immediately
    9: return to an outer level of control.  This section describes how you can
   10: do such @dfn{non-local exits} using the @code{setjmp} and @code{longjmp}
   11: functions.
   12: 
   13: @menu
   14: * Intro: Non-Local Intro.        When and how to use these facilities.
   15: * Details: Non-Local Details.    Functions for non-local exits.
   16: * Non-Local Exits and Signals::  Portability issues.
   17: * System V contexts::            Complete context control a la System V.
   18: @end menu
   19: 
   20: @node Non-Local Intro, Non-Local Details,  , Non-Local Exits
   21: @section Introduction to Non-Local Exits
   22: 
   23: As an example of a situation where a non-local exit can be useful,
   24: suppose you have an interactive program that has a ``main loop'' that
   25: prompts for and executes commands.  Suppose the ``read'' command reads
   26: input from a file, doing some lexical analysis and parsing of the input
   27: while processing it.  If a low-level input error is detected, it would
   28: be useful to be able to return immediately to the ``main loop'' instead
   29: of having to make each of the lexical analysis, parsing, and processing
   30: phases all have to explicitly deal with error situations initially
   31: detected by nested calls.
   32: 
   33: (On the other hand, if each of these phases has to do a substantial
   34: amount of cleanup when it exits---such as closing files, deallocating
   35: buffers or other data structures, and the like---then it can be more
   36: appropriate to do a normal return and have each phase do its own
   37: cleanup, because a non-local exit would bypass the intervening phases and
   38: their associated cleanup code entirely.  Alternatively, you could use a
   39: non-local exit but do the cleanup explicitly either before or after
   40: returning to the ``main loop''.)
   41: 
   42: In some ways, a non-local exit is similar to using the @samp{return}
   43: statement to return from a function.  But while @samp{return} abandons
   44: only a single function call, transferring control back to the point at
   45: which it was called, a non-local exit can potentially abandon many
   46: levels of nested function calls.
   47: 
   48: You identify return points for non-local exits by calling the function
   49: @code{setjmp}.  This function saves information about the execution
   50: environment in which the call to @code{setjmp} appears in an object of
   51: type @code{jmp_buf}.  Execution of the program continues normally after
   52: the call to @code{setjmp}, but if an exit is later made to this return
   53: point by calling @code{longjmp} with the corresponding @w{@code{jmp_buf}}
   54: object, control is transferred back to the point where @code{setjmp} was
   55: called.  The return value from @code{setjmp} is used to distinguish
   56: between an ordinary return and a return made by a call to
   57: @code{longjmp}, so calls to @code{setjmp} usually appear in an @samp{if}
   58: statement.
   59: 
   60: Here is how the example program described above might be set up:
   61: 
   62: @smallexample
   63: @include setjmp.c.texi
   64: @end smallexample
   65: 
   66: The function @code{abort_to_main_loop} causes an immediate transfer of
   67: control back to the main loop of the program, no matter where it is
   68: called from.
   69: 
   70: The flow of control inside the @code{main} function may appear a little
   71: mysterious at first, but it is actually a common idiom with
   72: @code{setjmp}.  A normal call to @code{setjmp} returns zero, so the
   73: ``else'' clause of the conditional is executed.  If
   74: @code{abort_to_main_loop} is called somewhere within the execution of
   75: @code{do_command}, then it actually appears as if the @emph{same} call
   76: to @code{setjmp} in @code{main} were returning a second time with a value
   77: of @code{-1}.
   78: 
   79: @need 250
   80: So, the general pattern for using @code{setjmp} looks something like:
   81: 
   82: @smallexample
   83: if (setjmp (@var{buffer}))
   84:   /* @r{Code to clean up after premature return.} */
   85:   @dots{}
   86: else
   87:   /* @r{Code to be executed normally after setting up the return point.} */
   88:   @dots{}
   89: @end smallexample
   90: 
   91: @node Non-Local Details, Non-Local Exits and Signals, Non-Local Intro, Non-Local Exits
   92: @section Details of Non-Local Exits
   93: 
   94: Here are the details on the functions and data structures used for
   95: performing non-local exits.  These facilities are declared in
   96: @file{setjmp.h}.
   97: @pindex setjmp.h
   98: 
   99: @comment setjmp.h
  100: @comment ISO
  101: @deftp {Data Type} jmp_buf
  102: Objects of type @code{jmp_buf} hold the state information to
  103: be restored by a non-local exit.  The contents of a @code{jmp_buf}
  104: identify a specific place to return to.
  105: @end deftp
  106: 
  107: @comment setjmp.h
  108: @comment ISO
  109: @deftypefn Macro int setjmp (jmp_buf @var{state})
  110: When called normally, @code{setjmp} stores information about the
  111: execution state of the program in @var{state} and returns zero.  If
  112: @code{longjmp} is later used to perform a non-local exit to this
  113: @var{state}, @code{setjmp} returns a nonzero value.
  114: @end deftypefn
  115: 
  116: @comment setjmp.h
  117: @comment ISO
  118: @deftypefun void longjmp (jmp_buf @var{state}, int @var{value})
  119: This function restores current execution to the state saved in
  120: @var{state}, and continues execution from the call to @code{setjmp} that
  121: established that return point.  Returning from @code{setjmp} by means of
  122: @code{longjmp} returns the @var{value} argument that was passed to
  123: @code{longjmp}, rather than @code{0}.  (But if @var{value} is given as
  124: @code{0}, @code{setjmp} returns @code{1}).@refill
  125: @end deftypefun
  126: 
  127: There are a lot of obscure but important restrictions on the use of
  128: @code{setjmp} and @code{longjmp}.  Most of these restrictions are
  129: present because non-local exits require a fair amount of magic on the
  130: part of the C compiler and can interact with other parts of the language
  131: in strange ways.
  132: 
  133: The @code{setjmp} function is actually a macro without an actual
  134: function definition, so you shouldn't try to @samp{#undef} it or take
  135: its address.  In addition, calls to @code{setjmp} are safe in only the
  136: following contexts:
  137: 
  138: @itemize @bullet
  139: @item
  140: As the test expression of a selection or iteration
  141: statement (such as @samp{if}, @samp{switch}, or @samp{while}).
  142: 
  143: @item
  144: As one operand of a equality or comparison operator that appears as the
  145: test expression of a selection or iteration statement.  The other
  146: operand must be an integer constant expression.
  147: 
  148: @item
  149: As the operand of a unary @samp{!} operator, that appears as the
  150: test expression of a selection or iteration statement.
  151: 
  152: @item
  153: By itself as an expression statement.
  154: @end itemize
  155: 
  156: Return points are valid only during the dynamic extent of the function
  157: that called @code{setjmp} to establish them.  If you @code{longjmp} to
  158: a return point that was established in a function that has already
  159: returned, unpredictable and disastrous things are likely to happen.
  160: 
  161: You should use a nonzero @var{value} argument to @code{longjmp}.  While
  162: @code{longjmp} refuses to pass back a zero argument as the return value
  163: from @code{setjmp}, this is intended as a safety net against accidental
  164: misuse and is not really good programming style.
  165: 
  166: When you perform a non-local exit, accessible objects generally retain
  167: whatever values they had at the time @code{longjmp} was called.  The
  168: exception is that the values of automatic variables local to the
  169: function containing the @code{setjmp} call that have been changed since
  170: the call to @code{setjmp} are indeterminate, unless you have declared
  171: them @code{volatile}.
  172: 
  173: @node Non-Local Exits and Signals, System V contexts, Non-Local Details, Non-Local Exits
  174: @section Non-Local Exits and Signals
  175: 
  176: In BSD Unix systems, @code{setjmp} and @code{longjmp} also save and
  177: restore the set of blocked signals; see @ref{Blocking Signals}.  However,
  178: the POSIX.1 standard requires @code{setjmp} and @code{longjmp} not to
  179: change the set of blocked signals, and provides an additional pair of
  180: functions (@code{sigsetjmp} and @code{siglongjmp}) to get the BSD
  181: behavior.
  182: 
  183: The behavior of @code{setjmp} and @code{longjmp} in the GNU library is
  184: controlled by feature test macros; see @ref{Feature Test Macros}.  The
  185: default in the GNU system is the POSIX.1 behavior rather than the BSD
  186: behavior.
  187: 
  188: The facilities in this section are declared in the header file
  189: @file{setjmp.h}.
  190: @pindex setjmp.h
  191: 
  192: @comment setjmp.h
  193: @comment POSIX.1
  194: @deftp {Data Type} sigjmp_buf
  195: This is similar to @code{jmp_buf}, except that it can also store state
  196: information about the set of blocked signals.
  197: @end deftp
  198: 
  199: @comment setjmp.h
  200: @comment POSIX.1
  201: @deftypefun int sigsetjmp (sigjmp_buf @var{state}, int @var{savesigs})
  202: This is similar to @code{setjmp}.  If @var{savesigs} is nonzero, the set
  203: of blocked signals is saved in @var{state} and will be restored if a
  204: @code{siglongjmp} is later performed with this @var{state}.
  205: @end deftypefun
  206: 
  207: @comment setjmp.h
  208: @comment POSIX.1
  209: @deftypefun void siglongjmp (sigjmp_buf @var{state}, int @var{value})
  210: This is similar to @code{longjmp} except for the type of its @var{state}
  211: argument.  If the @code{sigsetjmp} call that set this @var{state} used a
  212: nonzero @var{savesigs} flag, @code{siglongjmp} also restores the set of
  213: blocked signals.
  214: @end deftypefun
  215: 
  216: @node System V contexts,, Non-Local Exits and Signals, Non-Local Exits
  217: @section Complete Context Control
  218: 
  219: The Unix standard one more set of function to control the execution path
  220: and these functions are more powerful than those discussed in this
  221: chapter so far.  These function were part of the original @w{System V}
  222: API and by this route were added to the Unix API.  Beside on branded
  223: Unix implementations these interfaces are not widely available.  Not all
  224: platforms and/or architectures the GNU C Library is available on provide
  225: this interface.  Use @file{configure} to detect the availability.
  226: 
  227: Similar to the @code{jmp_buf} and @code{sigjmp_buf} types used for the
  228: variables to contain the state of the @code{longjmp} functions the
  229: interfaces of interest here have an appropriate type as well.  Objects
  230: of this type are normally much larger since more information is
  231: contained.  The type is also used in a few more places as we will see.
  232: The types and functions described in this section are all defined and
  233: declared respectively in the @file{ucontext.h} header file.
  234: 
  235: @comment ucontext.h
  236: @comment SVID
  237: @deftp {Data Type} ucontext_t
  238: 
  239: The @code{ucontext_t} type is defined as a structure with as least the
  240: following elements:
  241: 
  242: @table @code
  243: @item ucontext_t *uc_link
  244: This is a pointer to the next context structure which is used if the
  245: context described in the current structure returns.
  246: 
  247: @item sigset_t uc_sigmask
  248: Set of signals which are blocked when this context is used.
  249: 
  250: @item stack_t uc_stack
  251: Stack used for this context.  The value need not be (and normally is
  252: not) the stack pointer.  @xref{Signal Stack}.
  253: 
  254: @item mcontext_t uc_mcontext
  255: This element contains the actual state of the process.  The
  256: @code{mcontext_t} type is also defined in this header but the definition
  257: should be treated as opaque.  Any use of knowledge of the type makes
  258: applications less portable.
  259: 
  260: @end table
  261: @end deftp
  262: 
  263: Objects of this type have to be created by the user.  The initialization
  264: and modification happens through one of the following functions:
  265: 
  266: @comment ucontext.h
  267: @comment SVID
  268: @deftypefun int getcontext (ucontext_t *@var{ucp})
  269: The @code{getcontext} function initializes the variable pointed to by
  270: @var{ucp} with the context of the calling thread.  The context contains
  271: the content of the registers, the signal mask, and the current stack.
  272: Executing the contents would start at the point where the
  273: @code{getcontext} call just returned.
  274: 
  275: The function returns @code{0} if successful.  Otherwise it returns
  276: @code{-1} and sets @var{errno} accordingly.
  277: @end deftypefun
  278: 
  279: The @code{getcontext} function is similar to @code{setjmp} but it does
  280: not provide an indication of whether the function returns for the first
  281: time or whether the initialized context was used and the execution is
  282: resumed at just that point.  If this is necessary the user has to take
  283: determine this herself.  This must be done carefully since the context
  284: contains registers which might contain register variables.  This is a
  285: good situation to define variables with @code{volatile}.
  286: 
  287: Once the context variable is initialized it can be used as is or it can
  288: be modified.  The latter is normally done to implement co-routines or
  289: similar constructs.  The @code{makecontext} function is what has to be
  290: used to do that.
  291: 
  292: @comment ucontext.h
  293: @comment SVID
  294: @deftypefun void makecontext (ucontext_t *@var{ucp}, void (*@var{func}) (void), int @var{argc}, @dots{})
  295: 
  296: The @var{ucp} parameter passed to the @code{makecontext} shall be
  297: initialized by a call to @code{getcontext}.  The context will be
  298: modified to in a way so that if the context is resumed it will start by
  299: calling the function @code{func} which gets @var{argc} integer arguments
  300: passed.  The integer arguments which are to be passed should follow the
  301: @var{argc} parameter in the call to @code{makecontext}.
  302: 
  303: Before the call to this function the @code{uc_stack} and @code{uc_link}
  304: element of the @var{ucp} structure should be initialized.  The
  305: @code{uc_stack} element describes the stack which is used for this
  306: context.  No two contexts which are used at the same time should use the
  307: same memory region for a stack.
  308: 
  309: The @code{uc_link} element of the object pointed to by @var{ucp} should
  310: be a pointer to the context to be executed when the function @var{func}
  311: returns or it should be a null pointer.  See @code{setcontext} for more
  312: information about the exact use.
  313: @end deftypefun
  314: 
  315: While allocating the memory for the stack one has to be careful.  Most
  316: modern processors keep track of whether a certain memory region is
  317: allowed to contain code which is executed or not.  Data segments and
  318: heap memory is normally not tagged to allow this.  The result is that
  319: programs would fail.  Examples for such code include the calling
  320: sequences the GNU C compiler generates for calls to nested functions.
  321: Safe ways to allocate stacks correctly include using memory on the
  322: original threads stack or explicitly allocate memory tagged for
  323: execution using (@pxref{Memory-mapped I/O}).
  324: 
  325: @strong{Compatibility note}: The current Unix standard is very imprecise
  326: about the way the stack is allocated.  All implementations seem to agree
  327: that the @code{uc_stack} element must be used but the values stored in
  328: the elements of the @code{stack_t} value are unclear.  The GNU C library
  329: and most other Unix implementations require the @code{ss_sp} value of
  330: the @code{uc_stack} element to point to the base of the memory region
  331: allocated for the stack and the size of the memory region is stored in
  332: @code{ss_size}.  There are implements out there which require
  333: @code{ss_sp} to be set to the value the stack pointer will have (which
  334: can depending on the direction the stack grows be different).  This
  335: difference makes the @code{makecontext} function hard to use and it
  336: requires detection of the platform at compile time.
  337: 
  338: @comment ucontext.h
  339: @comment SVID
  340: @deftypefun int setcontext (const ucontext_t *@var{ucp})
  341: 
  342: The @code{setcontext} function restores the context described by
  343: @var{ucp}.  The context is not modified and can be reused as often as
  344: wanted.
  345: 
  346: If the context was created by @code{getcontext} execution resumes with
  347: the registers filled with the same values and the same stack as if the
  348: @code{getcontext} call just returned.
  349: 
  350: If the context was modified with a call to @code{makecontext} execution
  351: continues with the function passed to @code{makecontext} which gets the
  352: specified parameters passed.  If this function returns execution is
  353: resumed in the context which was referenced by the @code{uc_link}
  354: element of the context structure passed to @code{makecontext} at the
  355: time of the call.  If @code{uc_link} was a null pointer the application
  356: terminates in this case.
  357: 
  358: Since the context contains information about the stack no two threads
  359: should use the same context at the same time.  The result in most cases
  360: would be disastrous.
  361: 
  362: The @code{setcontext} function does not return unless an error occurred
  363: in which case it returns @code{-1}.
  364: @end deftypefun
  365: 
  366: The @code{setcontext} function simply replaces the current context with
  367: the one described by the @var{ucp} parameter.  This is often useful but
  368: there are situations where the current context has to be preserved.
  369: 
  370: @comment ucontext.h
  371: @comment SVID
  372: @deftypefun int swapcontext (ucontext_t *restrict @var{oucp}, const ucontext_t *restrict @var{ucp})
  373: 
  374: The @code{swapcontext} function is similar to @code{setcontext} but
  375: instead of just replacing the current context the latter is first saved
  376: in the object pointed to by @var{oucp} as if this was a call to
  377: @code{getcontext}.  The saved context would resume after the call to
  378: @code{swapcontext}.
  379: 
  380: Once the current context is saved the context described in @var{ucp} is
  381: installed and execution continues as described in this context.
  382: 
  383: If @code{swapcontext} succeeds the function does not return unless the
  384: context @var{oucp} is used without prior modification by
  385: @code{makecontext}.  The return value in this case is @code{0}.  If the
  386: function fails it returns @code{-1} and set @var{errno} accordingly.
  387: @end deftypefun
  388: 
  389: @heading Example for SVID Context Handling
  390: 
  391: The easiest way to use the context handling functions is as a
  392: replacement for @code{setjmp} and @code{longjmp}.  The context contains
  393: on most platforms more information which might lead to less surprises
  394: but this also means using these functions is more expensive (beside
  395: being less portable).
  396: 
  397: @smallexample
  398: int
  399: random_search (int n, int (*fp) (int, ucontext_t *))
  400: @{
  401:   volatile int cnt = 0;
  402:   ucontext_t uc;
  403: 
  404:   /* @r{Safe current context.}  */
  405:   if (getcontext (&uc) < 0)
  406:     return -1;
  407: 
  408:   /* @r{If we have not tried @var{n} times try again.}  */
  409:   if (cnt++ < n)
  410:     /* @r{Call the function with a new random number}
  411:        @r{and the context}.  */
  412:     if (fp (rand (), &uc) != 0)
  413:       /* @r{We found what we were looking for.}  */
  414:       return 1;
  415: 
  416:   /* @r{Not found.}  */
  417:   return 0;
  418: @}
  419: @end smallexample
  420: 
  421: Using contexts in such a way enables emulating exception handling.  The
  422: search functions passed in the @var{fp} parameter could be very large,
  423: nested, and complex which would make it complicated (or at least would
  424: require a lot of code) to leave the function with an error value which
  425: has to be passed down to the caller.  By using the context it is
  426: possible to leave the search function in one step and allow restarting
  427: the search which also has the nice side effect that it can be
  428: significantly faster.
  429: 
  430: Something which is harder to implement with @code{setjmp} and
  431: @code{longjmp} is to switch temporarily to a different execution path
  432: and then resume where execution was stopped.
  433: 
  434: @smallexample
  435: @include swapcontext.c.texi
  436: @end smallexample
  437: 
  438: This an example how the context functions can be used to implement
  439: co-routines or cooperative multi-threading.  All that has to be done is
  440: to call every once in a while @code{swapcontext} to continue running a
  441: different context.  It is not allowed to do the context switching from
  442: the signal handler directly since neither @code{setcontext} nor
  443: @code{swapcontext} are functions which can be called from a signal
  444: handler.  But setting a variable in the signal handler and checking it
  445: in the body of the functions which are executed.  Since
  446: @code{swapcontext} is saving the current context it is possible to have
  447: multiple different scheduling points in the code.  Execution will always
  448: resume where it was left.