doc/unw_reg_states_iterate.man

   1 '\" t
   2 .\" Manual page created with latex2man on Wed Aug 16 11:09:44 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\\_REG\\_STATES\\_ITERATE" "3" "16 August 2017" "Programming Library " "Programming Library "
  14 .SH NAME
  15 unw_reg_states_iterate
  16 \-\- get register state info on current procedure
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 int
  25 unw_reg_states_iterate(unw_cursor_t *cp,
  26 unw_reg_states_callbackcb,
  27 void *token);
  28 .br
  29 .PP
  30 .SH DESCRIPTION
  31
  32 .PP
  33 The unw_reg_states_iterate()
  34 routine provides
  35 information about the procedure that created the stack frame
  36 identified by argument cp\&.
  37 The cb
  38 argument is a pointer
  39 to a function of type unw_reg_states_callback
  40 which is used to
  41 return the information. The function unw_reg_states_callback
  42 has the
  43 following definition:
  44 .PP
  45 int
  46 ( *unw_reg_states_callback)(void *token,
  47 void *reg_states_data,
  48 size_t
  49 reg_states_data_size,
  50 unw_word_t
  51 start_ip,
  52 unw_word_t
  53 end_ip);
  54 .PP
  55 The callback function may be invoked several times for each call of unw_reg_states_iterate\&.
  56 Each call is associcated with a instruction address range and a set of instructions on how to update register values when returning from the procedure in that address range. For each invocation, the arguments to the callback function are:
  57 .TP
  58 void * token
  59  The token value passed to unw_reg_states_callback\&.
  60 .br
  61 .TP
  62 void * reg_states_data
  63  A pointer to data about
  64 updating register values. This data, or a copy of it, can be passed
  65 to unw_apply_reg_state\&.
  66 .br
  67 .TP
  68 int reg_states_data_size
  69  The size of the register update data.
  70 .br
  71 .TP
  72 unw_word_t start_ip
  73  The address of the first
  74 instruction of the address range.
  75 .br
  76 .TP
  77 unw_word_t end_ip
  78  The address of the first
  79 instruction \fIbeyond\fP
  80 the end of the address range.
  81 .br
  82 .PP
  83 .SH RETURN VALUE
  84
  85 .PP
  86 On successful completion, unw_reg_states_iterate()
  87 returns
  88 0. If the callback function returns a nonzero value, that indicates
  89 failure and the function returns immediately. Otherwise the negative
  90 value of one of the error\-codes below is returned.
  91 .PP
  92 .SH THREAD AND SIGNAL SAFETY
  93
  94 .PP
  95 unw_reg_states_iterate()
  96 is thread\-safe. If cursor cp
  97 is
  98 in the local address\-space, this routine is also safe to use from a
  99 signal handler.
 100 .PP
 101 .SH ERRORS
 102
 103 .PP
 104 .TP
 105 UNW_EUNSPEC
 106  An unspecified error occurred.
 107 .TP
 108 UNW_ENOINFO
 109  Libunwind
 110 was unable to locate
 111 unwind\-info for the procedure.
 112 .TP
 113 UNW_EBADVERSION
 114  The unwind\-info for the procedure has
 115 version or format that is not understood by libunwind\&.
 116 .PP
 117 In addition, unw_reg_states_iterate()
 118 may return any error
 119 returned by the access_mem()
 120 call\-back (see
 121 unw_create_addr_space(3)).
 122 .PP
 123 .SH SEE ALSO
 124
 125 .PP
 126 libunwind(3),
 127 unw_apply_reg_state(3)
 128 .PP
 129 .SH AUTHOR
 130
 131 .PP
 132 David Mosberger\-Tang
 133 .br
 134 Email: \fBdmosberger@gmail.com\fP
 135 .br
 136 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 137 .\" NOTE: This file is generated, DO NOT EDIT.