blob: 72621f1a6510f7c30f56d1910c2fa10c7f3fa01d [file] [log] [blame]
 \documentclass{article} \usepackage[fancyhdr,pdf]{latex2man} \input{common.tex} \begin{document} \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 \end{Name} \section{Synopsis} \File{\#include $<$libunwind.h$>$}\\ \Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_proc\_info\_t~*}\Var{pip});\\ \section{Description} The \Func{unw\_get\_proc\_info}() routine returns auxiliary information about the procedure that created the stack frame identified by argument \Var{cp}. The \Var{pip} argument is a pointer to a structure of type \Type{unw\_proc\_info\_t} which is used to return the information. The \Type{unw\_proc\_info\_t} has the following members: \begin{description} \item[\Type{unw\_word\_t} \Var{start\_ip}] The address of the first instruction of the procedure. If this address cannot be determined (e.g., due to lack of unwind information), the \Var{start\_ip} member is cleared to 0. \\ \item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first instruction \emph{beyond} the end of the procedure. If this address cannot be determined (e.g., due to lack of unwind information), the \Var{end\_ip} member is cleared to 0. \\ \item[\Type{unw\_word\_t} \Var{lsda}] The address of the language-specific data-area (LSDA). This area normally contains language-specific information needed during exception handling. If the procedure has no such area, this member is cleared to 0. \\ \item[\Type{unw\_word\_t} \Var{handler}] The address of the exception handler routine. This is sometimes called the \emph{personality} routine. If the procedure does not define a personality routine, the \Var{handler} member is cleared to 0. \\ \item[\Type{unw\_word\_t} \Var{gp}] The global-pointer of the procedure. On platforms that do not use a global pointer, this member may contain an undefined value. On all other platforms, it must be set either to the correct global-pointer value of the procedure or to 0 if the proper global-pointer cannot be obtained for some reason. \\ \item[\Type{unw\_word\_t} \Var{flags}] A set of flags. There are currently no target-independent flags. For the IA-64 target, the flag \Const{UNW\_PI\_FLAG\_IA64\_RBS\_SWITCH} is set if the procedure may switch the register-backing store.\\ \item[\Type{int} \Var{format}] The format of the unwind-info for this procedure. If the unwind-info consists of dynamic procedure info, \Var{format} is equal to \Const{UNW\_INFO\_FORMAT\_DYNAMIC}. If the unwind-info consists of a (target-specific) unwind table, it is equal to to \Const{UNW\_INFO\_FORMAT\_TABLE}. All other values are reserved for future use by \Prog{libunwind}. This member exists for use by the \Func{find\_proc\_info}() call-back (see \Func{unw\_create\_addr\_space}(3)). The \Func{unw\_get\_proc\_info}() routine may return an undefined value in this member. \\ \item[\Type{int} \Var{unwind\_info\_size}] The size of the unwind-info in bytes. This member exists for use by the \Func{find\_proc\_info}() call-back (see \Func{unw\_create\_addr\_space}(3)). The \Func{unw\_get\_proc\_info}() routine may return an undefined value in this member.\\ \item[\Type{void~*}\Var{unwind\_info}] The pointer to the unwind-info. If no unwind info is available, this member must be set to \Const{NULL}. This member exists for use by the \Func{find\_proc\_info}() call-back (see \Func{unw\_create\_addr\_space}(3)). The \Func{unw\_get\_proc\_info}() routine may return an undefined value in this member.\\ \end{description} Note that for the purposes of \Prog{libunwind}, the code of a procedure is assumed to occupy a single, contiguous range of addresses. For this reason, it is alwas possible to describe the extent of a procedure with the \Var{start\_ip} and \Var{end\_ip} members. If a single function/routine is split into multiple, discontiguous pieces, \Prog{libunwind} will treat each piece as a separate procedure. \section{Return Value} On successful completion, \Func{unw\_get\_proc\_info}() returns 0. Otherwise the negative value of one of the error-codes below is returned. \section{Thread and Signal Safety} \Func{unw\_get\_proc\_info}() is thread-safe. If cursor \Var{cp} is in the local address-space, this routine is also safe to use from a signal handler. \section{Errors} \begin{Description} \item[\Const{UNW\_EUNSPEC}] An unspecified error occurred. \item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate unwind-info for the procedure. \item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has version or format that is not understood by \Prog{libunwind}. \end{Description} In addition, \Func{unw\_get\_proc\_info}() may return any error returned by the \Func{access\_mem}() call-back (see \Func{unw\_create\_addr\_space}(3)). \section{See Also} \SeeAlso{libunwind(3)}, \SeeAlso{unw\_create\_addr\_space(3)}, \SeeAlso{unw\_get\_proc\_name(3)} \section{Author} \noindent David Mosberger-Tang\\ Email: \Email{dmosberger@gmail.com}\\ WWW: \URL{http://www.nongnu.org/libunwind/}. \LatexManEnd \end{document}