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\_name}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_name}unw\_get\_proc\_name -- get name of current procedure 9\end{Name} 10 11\section{Synopsis} 12 13\File{\#include $<$libunwind.h$>$}\\ 14 15\Type{int} \Func{unw\_get\_proc\_name}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{char~*}\Var{bufp}, \Type{size\_t} \Var{len}, \Type{unw\_word\_t~*}\Var{offp});\\ 16 17\section{Description} 18 19The \Func{unw\_get\_proc\_name}() routine returns the name of the 20procedure that created the stack frame identified by argument 21\Var{cp}. The \Var{bufp} argument is a pointer to a character buffer 22that is at least \Var{len} bytes long. This buffer is used to return 23the name of the procedure. The \Var{offp} argument is a pointer to a 24word that is used to return the byte-offset of the instruction-pointer 25saved in the stack frame identified by \Var{cp}, relative to the start 26of the procedure. For example, if procedure \Func{foo}() starts at 27address 0x40003000, then invoking \Func{unw\_get\_proc\_name}() on a 28stack frame with an instruction-pointer value of 0x40003080 would 29return a value of 0x80 in the word pointed to by \Var{offp} (assuming 30the procedure is at least 0x80 bytes long). 31 32Note that on some platforms there is no reliable way to distinguish 33between procedure names and ordinary labels. Furthermore, if symbol 34information has been stripped from a program, procedure names may be 35completely unavailable or may be limited to those exported via a 36dynamic symbol table. In such cases, \Func{unw\_get\_proc\_name}() 37may return the name of a label or a preceeding (nearby) procedure. 38However, the offset returned through \Var{offp} is always relative to 39the returned name, which ensures that the value (address) of the 40returned name plus the returned offset will always be equal to the 41instruction-pointer of the stack frame identified by \Var{cp}. 42 43\section{Return Value} 44 45On successful completion, \Func{unw\_get\_proc\_name}() returns 0. 46Otherwise the negative value of one of the error-codes below is 47returned. 48 49\section{Thread and Signal Safety} 50 51\Func{unw\_get\_proc\_name}() is thread-safe. If cursor \Var{cp} is 52in the local address-space, this routine is also safe to use from a 53signal handler. 54 55\section{Errors} 56 57\begin{Description} 58\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred. 59\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to determine 60 the name of the procedure. 61\item[\Const{UNW\_ENOMEM}] The procedure name is too long to fit 62 in the buffer provided. A truncated version of the name has been 63 returned. 64\end{Description} 65In addition, \Func{unw\_get\_proc\_name}() may return any error 66returned by the \Func{access\_mem}() call-back (see 67\Func{unw\_create\_addr\_space}(3)). 68 69\section{See Also} 70 71\SeeAlso{libunwind(3)}, 72\SeeAlso{unw\_get\_proc\_info(3)} 73 74\section{Author} 75 76\noindent 77David Mosberger-Tang\\ 78Email: \Email{dmosberger@gmail.com}\\ 79WWW: \URL{http://www.nongnu.org/libunwind/}. 80\LatexManEnd 81 82\end{document} 83