doc/unw_get_proc_info.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}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info}unw\_get\_proc\_info -- get info on current procedure
   9 \end{Name}
  10
  11 \section{Synopsis}
  12
  13 \File{\#include $<$libunwind.h$>$}\\
  14
  15 \Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_proc\_info\_t~*}\Var{pip});\\
  16
  17 \section{Description}
  18
  19 The \Func{unw\_get\_proc\_info}() routine returns auxiliary
  20 information about the procedure that created the stack frame
  21 identified by argument \Var{cp}.  The \Var{pip} argument is a pointer
  22 to a structure of type \Type{unw\_proc\_info\_t} which is used to
  23 return the information.  The \Type{unw\_proc\_info\_t} has the
  24 following members:
  25 \begin{description}
  26 \item[\Type{unw\_word\_t} \Var{start\_ip}] The address of the first
  27   instruction of the procedure.  If this address cannot be determined
  28   (e.g., due to lack of unwind information), the \Var{start\_ip}
  29   member is cleared to 0.  \\
  30 \item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first
  31   instruction \emph{beyond} the end of the procedure.  If this address
  32   cannot be determined (e.g., due to lack of unwind information),
  33   the \Var{end\_ip} member is cleared to 0.  \\
  34 \item[\Type{unw\_word\_t} \Var{lsda}] The address of the
  35   language-specific data-area (LSDA).  This area normally contains
  36   language-specific information needed during exception handling.  If
  37   the procedure has no such area, this member is cleared to 0.  \\
  38 \item[\Type{unw\_word\_t} \Var{handler}] The address of the exception
  39   handler routine.  This is sometimes called the \emph{personality}
  40   routine.  If the procedure does not define
  41   a personality routine, the \Var{handler} member is cleared to 0.  \\
  42 \item[\Type{unw\_word\_t} \Var{gp}] The global-pointer of the
  43   procedure.  On platforms that do not use a global pointer, this
  44   member may contain an undefined value.  On all other platforms, it
  45   must be set either to the correct global-pointer value of the
  46   procedure or to 0 if the proper global-pointer cannot be
  47   obtained for some reason.  \\
  48 \item[\Type{unw\_word\_t} \Var{flags}] A set of flags.  There are
  49   currently no target-independent flags.  For the IA-64 target, the
  50   flag \Const{UNW\_PI\_FLAG\_IA64\_RBS\_SWITCH} is set if the
  51   procedure may switch the register-backing store.\\
  52 \item[\Type{int} \Var{format}] The format of the unwind-info for this
  53   procedure.  If the unwind-info consists of dynamic procedure info,
  54   \Var{format} is equal to \Const{UNW\_INFO\_FORMAT\_DYNAMIC}.  If the
  55   unwind-info consists of a (target-specific) unwind table, it is
  56   equal to to \Const{UNW\_INFO\_FORMAT\_TABLE}.  All other values are
  57   reserved for future use by \Prog{libunwind}.  This member exists
  58   for use by the \Func{find\_proc\_info}() call-back (see
  59   \Func{unw\_create\_addr\_space}(3)).  The
  60   \Func{unw\_get\_proc\_info}() routine
  61   may return an undefined value in this member. \\
  62 \item[\Type{int} \Var{unwind\_info\_size}] The size of the unwind-info
  63   in bytes.  This member exists for use by the
  64   \Func{find\_proc\_info}() call-back (see
  65   \Func{unw\_create\_addr\_space}(3)).  The
  66   \Func{unw\_get\_proc\_info}() routine
  67   may return an undefined value in this member.\\
  68 \item[\Type{void~*}\Var{unwind\_info}] The pointer to the unwind-info.
  69   If no unwind info is available, this member must be set to
  70   \Const{NULL}.  This member exists for use by the
  71   \Func{find\_proc\_info}() call-back (see
  72   \Func{unw\_create\_addr\_space}(3)).  The
  73   \Func{unw\_get\_proc\_info}() routine
  74   may return an undefined value in this member.\\
  75 \end{description}
  76 Note that for the purposes of \Prog{libunwind}, the code of a
  77 procedure is assumed to occupy a single, contiguous range of
  78 addresses.  For this reason, it is alwas possible to describe the
  79 extent of a procedure with the \Var{start\_ip} and \Var{end\_ip}
  80 members.  If a single function/routine is split into multiple,
  81 discontiguous pieces, \Prog{libunwind} will treat each piece as a
  82 separate procedure.
  83
  84 \section{Return Value}
  85
  86 On successful completion, \Func{unw\_get\_proc\_info}() returns 0.
  87 Otherwise the negative value of one of the error-codes below is
  88 returned.
  89
  90 \section{Thread and Signal Safety}
  91
  92 \Func{unw\_get\_proc\_info}() is thread-safe.  If cursor \Var{cp} is
  93 in the local address-space, this routine is also safe to use from a
  94 signal handler.
  95
  96 \section{Errors}
  97
  98 \begin{Description}
  99 \item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
 100 \item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate
 101   unwind-info for the procedure.
 102 \item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has
 103   version or format that is not understood by \Prog{libunwind}.
 104 \end{Description}
 105 In addition, \Func{unw\_get\_proc\_info}() may return any error
 106 returned by the \Func{access\_mem}() call-back (see
 107 \Func{unw\_create\_addr\_space}(3)).
 108
 109 \section{See Also}
 110
 111 \SeeAlso{libunwind(3)},
 112 \SeeAlso{unw\_create\_addr\_space(3)},
 113 \SeeAlso{unw\_get\_proc\_name(3)}
 114
 115 \section{Author}
 116
 117 \noindent
 118 David Mosberger-Tang\\
 119 Email: \Email{dmosberger@gmail.com}\\
 120 WWW: \URL{http://www.nongnu.org/libunwind/}.
 121 \LatexManEnd
 122
 123 \end{document}