doc/unw_get_proc_info_by_ip.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\\_GET\\_PROC\\_INFO\\_BY\\_IP" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 unw_get_proc_info_by_ip
  16 \-\- get procedure info by IP
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 int
  25 unw_get_proc_info_by_ip(unw_addr_space_t as,
  26 unw_word_t ip,
  27 unw_proc_info_t *pip,
  28 void *arg);
  29 .br
  30 .PP
  31 .SH DESCRIPTION
  32
  33 .PP
  34 The unw_get_proc_info_by_ip()
  35 routine returns the same
  36 kind of auxiliary information about a procedure as
  37 unw_get_proc_info(),
  38 except that the info is looked up by
  39 instruction\-pointer (IP) instead of a cursor. This is more flexible
  40 because it is possible to look up the info for an arbitrary procedure,
  41 even if it is not part of the current call\-chain. However, since it
  42 is more flexible, it also tends to run slower (and often much slower)
  43 than unw_get_proc_info().
  44 .PP
  45 The routine expects the followins arguments: as
  46 is the
  47 address\-space in which the instruction\-pointer should be looked up.
  48 For a look\-up in the local address\-space,
  49 unw_local_addr_space
  50 can be passed for this argument.
  51 Argument ip
  52 is the instruction\-pointer for which the procedure
  53 info should be looked up and pip
  54 is a pointer to a structure of
  55 type unw_proc_info_t
  56 which is used to return the info.
  57 Lastly, arg
  58 is the address\-space argument that should be used
  59 when accessing the address\-space. It has the same purpose as the
  60 argument of the same name for unw_init_remote().
  61 When
  62 accessing the local address\-space (first argument is
  63 unw_local_addr_space),
  64 NULL
  65 must be passed for this
  66 argument.
  67 .PP
  68 Note that for the purposes of libunwind,
  69 the code of a
  70 procedure is assumed to occupy a single, contiguous range of
  71 addresses. For this reason, it is alwas possible to describe the
  72 extent of a procedure with the start_ip
  73 and end_ip
  74 members. If a single function/routine is split into multiple,
  75 discontiguous pieces, libunwind
  76 will treat each piece as a
  77 separate procedure.
  78 .PP
  79 .SH RETURN VALUE
  80
  81 .PP
  82 On successful completion, unw_get_proc_info_by_ip()
  83 returns 0. Otherwise the negative value of one of the error\-codes
  84 below is returned.
  85 .PP
  86 .SH THREAD AND SIGNAL SAFETY
  87
  88 .PP
  89 unw_get_proc_info()
  90 is thread\-safe. If the local
  91 address\-space is passed in argument as,
  92 this routine is also
  93 safe to use from a signal handler.
  94 .PP
  95 .SH ERRORS
  96
  97 .PP
  98 .TP
  99 UNW_EUNSPEC
 100  An unspecified error occurred.
 101 .TP
 102 UNW_ENOINFO
 103  Libunwind
 104 was unable to locate
 105 unwind\-info for the procedure.
 106 .TP
 107 UNW_EBADVERSION
 108  The unwind\-info for the procedure has
 109 version or format that is not understood by libunwind\&.
 110 .PP
 111 In addition, unw_get_proc_info()
 112 may return any error
 113 returned by the access_mem()
 114 call\-back (see
 115 unw_create_addr_space(3)).
 116 .PP
 117 .SH SEE ALSO
 118
 119 .PP
 120 libunwind(3),
 121 unw_create_addr_space(3),
 122 unw_get_proc_name(3),
 123 unw_get_proc_info(3),
 124 unw_init_remote(3)
 125 .PP
 126 .SH AUTHOR
 127
 128 .PP
 129 David Mosberger\-Tang
 130 .br
 131 Email: \fBdmosberger@gmail.com\fP
 132 .br
 133 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 134 .\" NOTE: This file is generated, DO NOT EDIT.