Expose function-pointer-to-name API

The unw_get_proc_name_by_ip() function returns the name
of a procedure just like unw_get_proc_name(), except that it's
looked up by an instruction-pointer instead of a cursor.

doc/Makefile.am

@@ -8,6 +8,7 @@ man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man	\
 	unw_get_proc_info.man						\
 	unw_get_proc_info_by_ip.man					\
 	unw_get_proc_name.man						\
+	unw_get_proc_name_by_ip.man					\
 	unw_get_fpreg.man						\
 	unw_get_reg.man							\
 	unw_getcontext.man						\
@@ -38,6 +39,7 @@ EXTRA_DIST = NOTES libunwind.trans					\
 	unw_get_proc_info.tex						\
 	unw_get_proc_info_by_ip.tex					\
 	unw_get_proc_name.tex						\
+	unw_get_proc_name_by_ip.tex					\
 	unw_get_fpreg.tex						\
 	unw_get_reg.tex							\
 	unw_getcontext.tex						\

doc/unw_get_proc_name_by_ip.man

@@ -0,0 +1,139 @@
+'\" t
+.\" Manual page created with latex2man on Mon Aug 30 08:48:42 CEST 2021
+.\" NOTE: This file is generated, DO NOT EDIT.
+.de Vb
+.ft CW
+.nf
+..
+.de Ve
+.ft R
+
+.fi
+..
+.TH "UNW\\_GET\\_PROC\\_NAME\\_BY\\_IP" "3" "30 August 2021" "Programming Library " "Programming Library "
+.SH NAME
+unw_get_proc_name_by_ip
+\-\- get procedure name 
+.PP
+.SH SYNOPSIS
+
+.PP
+#include <libunwind.h>
+.br
+.PP
+int
+unw_get_proc_name_by_ip(unw_addr_space_t as,
+unw_word_t ip,
+char *bufp,
+size_t
+len,
+unw_word_t *offp,
+void *arg);
+.br
+.PP
+.SH DESCRIPTION
+
+.PP
+The unw_get_proc_name_by_ip()
+routine returns the name of 
+a procedure just like unw_get_proc_name(),
+except that the 
+name is looked up by instruction\-pointer (IP) instead of a cursor. 
+.PP
+The routine expects the following arguments: as
+is the 
+address\-space in which the instruction\-pointer should be looked up. 
+For a look\-up in the local address\-space, 
+unw_local_addr_space
+can be passed for this argument. 
+Argument ip
+is the instruction\-pointer for which the procedure 
+name should be looked up. The bufp
+argument is a pointer to 
+a character buffer that is at least len
+bytes long. This buffer 
+is used to return the name of the procedure. The offp
+argument 
+is a pointer to a word that is used to return the byte\-offset of the 
+instruction\-pointer relative to the start of the procedure. 
+Lastly, arg
+is the address\-space argument that should be used 
+when accessing the address\-space. It has the same purpose as the 
+argument of the same name for unw_init_remote().
+When 
+accessing the local address\-space (first argument is 
+unw_local_addr_space),
+NULL
+must be passed for this 
+argument. 
+.PP
+Note that on some platforms there is no reliable way to distinguish 
+between procedure names and ordinary labels. Furthermore, if symbol 
+information has been stripped from a program, procedure names may be 
+completely unavailable or may be limited to those exported via a 
+dynamic symbol table. In such cases, 
+unw_get_proc_name_by_ip()
+may return the name of a label 
+or a preceeding (nearby) procedure. However, the offset returned 
+through offp
+is always relative to the returned name, which 
+ensures that the value (address) of the returned name plus the 
+returned offset will always be equal to the instruction\-pointer 
+ip\&.
+.PP
+.SH RETURN VALUE
+
+.PP
+On successful completion, unw_get_proc_name_by_ip()
+returns 0. Otherwise the negative value of one of the error\-codes 
+below is returned. 
+.PP
+.SH THREAD AND SIGNAL SAFETY
+
+.PP
+unw_get_proc_name_by_ip()
+is thread\-safe. If the local 
+address\-space is passed in argument as,
+this routine is also 
+safe to use from a signal handler. 
+.PP
+.SH ERRORS
+
+.PP
+.TP
+UNW_EUNSPEC
+ An unspecified error occurred. 
+.TP
+UNW_ENOINFO
+ Libunwind
+was unable to determine 
+the name of the procedure. 
+.TP
+UNW_ENOMEM
+ The procedure name is too long to fit 
+in the buffer provided. A truncated version of the name has been 
+returned. 
+.PP
+In addition, unw_get_proc_name_by_ip()
+may return any error 
+returned by the access_mem()
+call\-back (see 
+unw_create_addr_space(3)).
+.PP
+.SH SEE ALSO
+
+.PP
+libunwind(3),
+unw_create_addr_space(3),
+unw_get_proc_name(3),
+unw_init_remote(3)
+.PP
+.SH AUTHOR
+
+.PP
+David Mosberger\-Tang
+.br
+Email: \fBdmosberger@gmail.com\fP
+.br
+WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
+.\" NOTE: This file is generated, DO NOT EDIT.

doc/unw_get_proc_name_by_ip.tex

@@ -0,0 +1,93 @@
+\documentclass{article}
+\usepackage[fancyhdr,pdf]{latex2man}
+
+\input{common.tex}
+
+\begin{document}
+
+\begin{Name}{3}{unw\_get\_proc\_name\_by\_ip}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_name}unw\_get\_proc\_name\_by\_ip -- get procedure name
+\end{Name}
+
+\section{Synopsis}
+
+\File{\#include $<$libunwind.h$>$}\\
+
+\Type{int} \Func{unw\_get\_proc\_name\_by\_ip}(\Type{unw\_addr\_space\_t~}\Var{as}, \Type{unw\_word\_t~}\Var{ip}, \Type{char~*}\Var{bufp}, \Type{size\_t} \Var{len}, \Type{unw\_word\_t~*}\Var{offp}, \Type{void~*}\Var{arg});\\
+
+\section{Description}
+
+The \Func{unw\_get\_proc\_name\_by\_ip}() routine returns the name of
+a procedure just like \Func{unw\_get\_proc\_name}(), except that the
+name is looked up by instruction-pointer (IP) instead of a cursor.
+
+The routine expects the following arguments: \Var{as} is the
+address-space in which the instruction-pointer should be looked up.
+For a look-up in the local address-space,
+\Var{unw\_local\_addr\_space} can be passed for this argument.
+Argument \Var{ip} is the instruction-pointer for which the procedure
+name should be looked up.  The \Var{bufp} argument is a pointer to
+a character buffer that is at least \Var{len} bytes long.  This buffer
+is used to return the name of the procedure.  The \Var{offp} argument
+is a pointer to a word that is used to return the byte-offset of the
+instruction-pointer relative to the start of the procedure.
+Lastly, \Var{arg} is the address-space argument that should be used
+when accessing the address-space.  It has the same purpose as the
+argument of the same name for \Func{unw\_init\_remote}().  When
+accessing the local address-space (first argument is
+\Var{unw\_local\_addr\_space}), \Const{NULL} must be passed for this
+argument.
+
+Note that on some platforms there is no reliable way to distinguish
+between procedure names and ordinary labels.  Furthermore, if symbol
+information has been stripped from a program, procedure names may be
+completely unavailable or may be limited to those exported via a
+dynamic symbol table.  In such cases,
+\Func{unw\_get\_proc\_name\_by\_ip}() may return the name of a label
+or a preceeding (nearby) procedure.  However, the offset returned
+through \Var{offp} is always relative to the returned name, which
+ensures that the value (address) of the returned name plus the
+returned offset will always be equal to the instruction-pointer
+\Var{ip}.
+
+\section{Return Value}
+
+On successful completion, \Func{unw\_get\_proc\_name\_by\_ip}()
+returns 0.  Otherwise the negative value of one of the error-codes
+below is returned.
+
+\section{Thread and Signal Safety}
+
+\Func{unw\_get\_proc\_name\_by\_ip}() is thread-safe.  If the local
+address-space is passed in argument \Var{as}, 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 determine
+  the name of the procedure.
+\item[\Const{UNW\_ENOMEM}] The procedure name is too long to fit
+  in the buffer provided.  A truncated version of the name has been
+  returned.
+\end{Description}
+In addition, \Func{unw\_get\_proc\_name\_by\_ip}() 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)},
+\SeeAlso{unw\_init\_remote(3)}
+
+\section{Author}
+
+\noindent
+David Mosberger-Tang\\
+Email: \Email{dmosberger@gmail.com}\\
+WWW: \URL{http://www.nongnu.org/libunwind/}.
+\LatexManEnd
+
+\end{document}

include/libunwind-common.h.in

@@ -254,6 +254,7 @@ unw_save_loc_t;
 #define unw_get_save_loc	UNW_OBJ(get_save_loc)
 #define unw_is_signal_frame	UNW_OBJ(is_signal_frame)
 #define unw_get_proc_name	UNW_OBJ(get_proc_name)
+#define unw_get_proc_name_by_ip	UNW_OBJ(get_proc_name_by_ip)
 #define unw_set_caching_policy	UNW_OBJ(set_caching_policy)
 #define unw_set_cache_size	UNW_OBJ(set_cache_size)
 #define unw_regname		UNW_ARCH_OBJ(regname)
@@ -286,6 +287,8 @@ extern int unw_set_fpreg (unw_cursor_t *, int, unw_fpreg_t);
 extern int unw_get_save_loc (unw_cursor_t *, int, unw_save_loc_t *);
 extern int unw_is_signal_frame (unw_cursor_t *);
 extern int unw_get_proc_name (unw_cursor_t *, char *, size_t, unw_word_t *);
+extern int unw_get_proc_name_by_ip (unw_addr_space_t, unw_word_t, char *,
+				    size_t, unw_word_t *, void *);
 extern const char *unw_strerror (int);
 extern int unw_backtrace (void **, int);
 

src/mi/Gget_proc_name.c

@@ -45,9 +45,10 @@ intern_string (unw_addr_space_t as, unw_accessors_t *a,
   return -UNW_ENOMEM;
 }
 
-static inline int
-get_proc_name (unw_addr_space_t as, unw_word_t ip,
-               char *buf, size_t buf_len, unw_word_t *offp, void *arg)
+int
+unw_get_proc_name_by_ip (unw_addr_space_t as, unw_word_t ip,
+                         char *buf, size_t buf_len, unw_word_t *offp,
+                         void *arg)
 {
   unw_accessors_t *a = unw_get_accessors_int (as);
   unw_proc_info_t pi;
@@ -116,8 +117,8 @@ unw_get_proc_name (unw_cursor_t *cursor, char *buf, size_t buf_len,
 
 
 #endif
-  error = get_proc_name (tdep_get_as (c), ip, buf, buf_len, offp,
-                         tdep_get_as_arg (c));
+  error = unw_get_proc_name_by_ip (tdep_get_as (c), ip, buf, buf_len, offp,
+                                   tdep_get_as_arg (c));
 #if !defined(__ia64__)
   if (c->dwarf.use_prev_instr && offp != NULL && error == 0)
     *offp += 1;

tests/check-namespace.sh.in

@@ -101,6 +101,7 @@ check_local_unw_abi () {
     match _UL${plat}_get_proc_info
     match _UL${plat}_get_proc_info_by_ip
     match _UL${plat}_get_proc_name
+    match _UL${plat}_get_proc_name_by_ip
     match _UL${plat}_get_reg
     match _UL${plat}_get_save_loc
     match _UL${plat}_init_local
@@ -222,6 +223,7 @@ check_generic_unw_abi () {
     match _U${plat}_get_proc_info
     match _U${plat}_get_proc_info_by_ip
     match _U${plat}_get_proc_name
+    match _U${plat}_get_proc_name_by_ip
     match _U${plat}_get_reg
     match _U${plat}_get_save_loc
     match _U${plat}_init_local