doc/unw_get_proc_info_by_ip.tex

   1 \documentclass{article}
   2 \usepackage[fancyhdr,pdf]{latex2man}
   3
   4 \input{common.tex}
   5
   6 \begin{document}
   7
   8 \begin{Name}{3}{unw\_get\_proc\_info\_by\_ip}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info\_by\_ip}unw\_get\_proc\_info\_by\_ip -- get procedure info by IP
   9 \end{Name}
  10
  11 \section{Synopsis}
  12
  13 \File{\#include $<$libunwind.h$>$}\\
  14
  15 \Type{int} \Func{unw\_get\_proc\_info\_by\_ip}(\Type{unw\_addr\_space\_t~}\Var{as}, \Type{unw\_word\_t~}\Var{ip}, \Type{unw\_proc\_info\_t~*}\Var{pip}, \Type{void~*}\Var{arg});\\
  16
  17 \section{Description}
  18
  19 The \Func{unw\_get\_proc\_info\_by\_ip}() routine returns the same
  20 kind of auxiliary information about a procedure as
  21 \Func{unw\_get\_proc\_info}(), except that the info is looked up by
  22 instruction-pointer (IP) instead of a cursor.  This is more flexible
  23 because it is possible to look up the info for an arbitrary procedure,
  24 even if it is not part of the current call-chain.  However, since it
  25 is more flexible, it also tends to run slower (and often much slower)
  26 than \Func{unw\_get\_proc\_info}().
  27
  28 The routine expects the followins arguments: \Var{as} is the
  29 address-space in which the instruction-pointer should be looked up.
  30 For a look-up in the local address-space,
  31 \Var{unw\_local\_addr\_space} can be passed for this argument.
  32 Argument \Var{ip} is the instruction-pointer for which the procedure
  33 info should be looked up and \Var{pip} is a pointer to a structure of
  34 type \Type{unw\_proc\_info\_t} which is used to return the info.
  35 Lastly, \Var{arg} is the address-space argument that should be used
  36 when accessing the address-space.  It has the same purpose as the
  37 argument of the same name for \Func{unw\_init\_remote}().  When
  38 accessing the local address-space (first argument is
  39 \Var{unw\_local\_addr\_space}), \Const{NULL} must be passed for this
  40 argument.
  41
  42 Note that for the purposes of \Prog{libunwind}, the code of a
  43 procedure is assumed to occupy a single, contiguous range of
  44 addresses.  For this reason, it is alwas possible to describe the
  45 extent of a procedure with the \Var{start\_ip} and \Var{end\_ip}
  46 members.  If a single function/routine is split into multiple,
  47 discontiguous pieces, \Prog{libunwind} will treat each piece as a
  48 separate procedure.
  49
  50 \section{Return Value}
  51
  52 On successful completion, \Func{unw\_get\_proc\_info\_by\_ip}()
  53 returns 0.  Otherwise the negative value of one of the error-codes
  54 below is returned.
  55
  56 \section{Thread and Signal Safety}
  57
  58 \Func{unw\_get\_proc\_info}() is thread-safe.  If the local
  59 address-space is passed in argument \Var{as}, this routine is also
  60 safe to use from a signal handler.
  61
  62 \section{Errors}
  63
  64 \begin{Description}
  65 \item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
  66 \item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate
  67   unwind-info for the procedure.
  68 \item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has
  69   version or format that is not understood by \Prog{libunwind}.
  70 \end{Description}
  71 In addition, \Func{unw\_get\_proc\_info}() may return any error
  72 returned by the \Func{access\_mem}() call-back (see
  73 \Func{unw\_create\_addr\_space}(3)).
  74
  75 \section{See Also}
  76
  77 \SeeAlso{libunwind(3)},
  78 \SeeAlso{unw\_create\_addr\_space(3)},
  79 \SeeAlso{unw\_get\_proc\_name(3)},
  80 \SeeAlso{unw\_get\_proc\_info(3)},
  81 \SeeAlso{unw\_init\_remote(3)}
  82
  83 \section{Author}
  84
  85 \noindent
  86 David Mosberger-Tang\\
  87 Email: \Email{dmosberger@gmail.com}\\
  88 WWW: \URL{http://www.nongnu.org/libunwind/}.
  89 \LatexManEnd
  90
  91 \end{document}