← Back to branch summary

~ubuntu-branches/ubuntu/utopic/eglibc/utopic

« back to all changes in this revision

Viewing changes to manual/setjmp.texi

  • Committer: Package Import Robot
  • Author(s): Adam Conrad
  • Date: 2012-10-26 05:14:58 UTC
  • mfrom: (1.5.1) (4.4.22 experimental)
  • Revision ID: package-import@ubuntu.com-20121026051458-oryotr4i03ob5pab
Tags: 2.16-0ubuntu1
* Merge with unreleased 2.16 in Debian experimental, remaining changes:
  - Drop the Breaks line from libc6, which refers to a Debian transition
  - Remove the libc6 recommends on libc6-i686, which we don't build
  - Enable libc6{,-dev}-armel on armhf and libc6{-dev}-armhf on armel
  - Ship update-locale and validlocale in /usr/sbin in libc-bin
  - Don't build locales or locales-all in Ubuntu, we rely on langpacks
  - Heavily mangle the way we do service restarting on major upgrades
  - Use different MIN_KERNEL_SUPPORTED versions than Debian, due to
    buildd needs.  This should be universally bumped to 3.2.0 once all
    our buildds (including the PPA guests) are running precise kernels
  - Build i386 variants as -march=i686, build amd64 with -O3, and build
    ppc64 variants (both 64-bit and 32-bit) with -O3 -fno-tree-vectorize
  - Re-enable unsubmitted-ldconfig-cache-abi.diff and rebuild the cache
    on upgrades from previous versions that used a different constant
  - debian/patches/any/local-CVE-2012-3406.diff: switch to malloc when
    array grows too large to handle via alloca extension (CVE-2012-3406)
  - Build generic i386/i686 flavour with -mno-tls-direct-seg-refs
* Changes added/dropped with this merge while reducing our delta:
  - Stop building glibc docs from the eglibc source, and instead make
    the glibc-docs stub have a hard dependency on glibc-doc-reference
  - Remove outdated conflicts against ancient versions of ia32-libs
  - Drop the tzdata dependency from libc6, it's in required and minimal
  - Use gcc-4.7/g++-4.7 by default on all our supported architectures
  - Save our historical changelog as changelog.ubuntu in the source
  - Drop nscd's libaudit build-dep for now, as libaudit is in universe
  - Drop the unnecessary Breaks from libc6 to locales and locales-all
  - Ship xen's ld.so.conf.d snippet as /etc/ld.so.conf.d/libc6-xen.conf
* Disable hard failures on the test suite for the first upload to raring

Show diffs side-by-side

added added

removed removed

Lines of Context:
manual/setjmp.texi
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.