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