doc/unw_init_local.man

   1 '\" t
   2 .\" Manual page created with latex2man on Wed Aug 16 12:11:05 PDT 2017
   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 2017" "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 int
  29 unw_init_local2(unw_cursor_t *c,
  30 unw_context_t *ctxt,
  31 int
  32 flag);
  33 .br
  34 .PP
  35 .SH DESCRIPTION
  36
  37 .PP
  38 The unw_init_local()
  39 routine initializes the unwind cursor
  40 pointed to by c
  41 with the machine\-state in the context structure
  42 pointed to by ctxt\&.
  43 As such, the machine\-state pointed to by
  44 ctxt
  45 identifies the initial stack frame at which unwinding
  46 starts. The machine\-state is expected to be one provided by a call to
  47 unw_getcontext; as such, the instruction pointer may point to the
  48 instruction after the last instruction of a function, and libunwind
  49 will back\-up the instruction pointer before beginning a walk up the
  50 call stack. The machine\-state must remain valid for the duration for
  51 which the cursor c
  52 is in use.
  53 .PP
  54 The unw_init_local()
  55 routine can be used only for unwinding in
  56 the address space of the current process (i.e., for local unwinding).
  57 For all other cases, unw_init_remote()
  58 must be used instead.
  59 However, unwind performance may be better when using
  60 unw_init_local().
  61 Also, unw_init_local()
  62 is
  63 available even when UNW_LOCAL_ONLY
  64 has been defined before
  65 including <libunwind.h>,
  66 whereas unw_init_remote()
  67 is not.
  68 .PP
  69 If the unw_context_t is known to be a signal frame (i.e., from the
  70 third argument in a sigaction handler on linux),
  71 unw_init_local2()
  72 should be used for correct initialization
  73 on some platforms, passing the UNW_INIT_SIGNAL_FRAME flag.
  74 .PP
  75 .SH RETURN VALUE
  76
  77 .PP
  78 On successful completion, unw_init_local()
  79 returns 0.
  80 Otherwise the negative value of one of the error\-codes below is
  81 returned.
  82 .PP
  83 .SH THREAD AND SIGNAL SAFETY
  84
  85 .PP
  86 unw_init_local()
  87 is thread\-safe as well as safe to use from a
  88 signal handler.
  89 .PP
  90 .SH ERRORS
  91
  92 .PP
  93 .TP
  94 UNW_EINVAL
  95  unw_init_local()
  96 was called in a
  97 version of libunwind
  98 which supports remote unwinding only
  99 (this normally happens when calling unw_init_local()
 100 for a
 101 cross\-platform version of libunwind).
 102 .TP
 103 UNW_EUNSPEC
 104  An unspecified error occurred.
 105 .TP
 106 UNW_EBADREG
 107  A register needed by unw_init_local()
 108 wasn\&'t accessible.
 109 .PP
 110 .SH SEE ALSO
 111
 112 .PP
 113 libunwind(3),
 114 unw_init_remote(3)
 115 .PP
 116 .SH AUTHOR
 117
 118 .PP
 119 David Mosberger\-Tang
 120 .br
 121 Email: \fBdmosberger@gmail.com\fP
 122 .br
 123 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 124 .\" NOTE: This file is generated, DO NOT EDIT.