doc/unw_init_local.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:45 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "UNW\\_INIT\\_LOCAL" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 unw_init_local
  16 \-\- initialize cursor for local unwinding
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 int
  25 unw_init_local(unw_cursor_t *c,
  26 unw_context_t *ctxt);
  27 .br
  28 .PP
  29 .SH DESCRIPTION
  30
  31 .PP
  32 The unw_init_local()
  33 routine initializes the unwind cursor
  34 pointed to by c
  35 with the machine\-state in the context structure
  36 pointed to by ctxt\&.
  37 As such, the machine\-state pointed to by
  38 ctxt
  39 identifies the initial stack frame at which unwinding
  40 starts. The machine\-state must remain valid for the duration for
  41 which the cursor c
  42 is in use.
  43 .PP
  44 The unw_init_local()
  45 routine can be used only for unwinding in
  46 the address space of the current process (i.e., for local unwinding).
  47 For all other cases, unw_init_remote()
  48 must be used instead.
  49 From a behavioral point of view, the call:
  50 .PP
  51 .Vb
  52     ret = unw_init_local(&cursor, &ucontext);
  53 .Ve
  54 is equivalent to:
  55 .PP
  56 .Vb
  57     ret = unw_init_remote(&cursor, unw_local_addr_space,
  58                           &ucontext);
  59 .Ve
  60 However, unwind performance may be better when using
  61 unw_init_local().
  62 Also, unw_init_local()
  63 is
  64 available even when UNW_LOCAL_ONLY
  65 has been defined before
  66 including <libunwind.h>,
  67 whereas unw_init_remote()
  68 is not.
  69 .PP
  70 .SH RETURN VALUE
  71
  72 .PP
  73 On successful completion, unw_init_local()
  74 returns 0.
  75 Otherwise the negative value of one of the error\-codes below is
  76 returned.
  77 .PP
  78 .SH THREAD AND SIGNAL SAFETY
  79
  80 .PP
  81 unw_init_local()
  82 is thread\-safe as well as safe to use from a
  83 signal handler.
  84 .PP
  85 .SH ERRORS
  86
  87 .PP
  88 .TP
  89 UNW_EINVAL
  90  unw_init_local()
  91 was called in a
  92 version of libunwind
  93 which supports remote unwinding only
  94 (this normally happens when calling unw_init_local()
  95 for a
  96 cross\-platform version of libunwind).
  97 .TP
  98 UNW_EUNSPEC
  99  An unspecified error occurred.
 100 .TP
 101 UNW_EBADREG
 102  A register needed by unw_init_local()
 103 wasn\&'t accessible.
 104 .PP
 105 .SH SEE ALSO
 106
 107 .PP
 108 libunwind(3),
 109 unw_init_remote(3)
 110 .PP
 111 .SH AUTHOR
 112
 113 .PP
 114 David Mosberger\-Tang
 115 .br
 116 Email: \fBdmosberger@gmail.com\fP
 117 .br
 118 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 119 .\" NOTE: This file is generated, DO NOT EDIT.