diff options
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/unw_get_proc_name_by_ip.man | 139 | ||||
| -rw-r--r-- | doc/unw_get_proc_name_by_ip.tex | 93 | ||||
| -rw-r--r-- | include/libunwind-common.h.in | 3 | ||||
| -rw-r--r-- | src/mi/Gget_proc_name.c | 11 | ||||
| -rw-r--r-- | tests/check-namespace.sh.in | 2 |
6 files changed, 245 insertions, 5 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am index bfe46691..f79d8c54 100644 --- a/doc/Makefile.am +++ b/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 \ diff --git a/doc/unw_get_proc_name_by_ip.man b/doc/unw_get_proc_name_by_ip.man new file mode 100644 index 00000000..26c533ce --- /dev/null +++ b/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. diff --git a/doc/unw_get_proc_name_by_ip.tex b/doc/unw_get_proc_name_by_ip.tex new file mode 100644 index 00000000..4f46690f --- /dev/null +++ b/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} diff --git a/include/libunwind-common.h.in b/include/libunwind-common.h.in index c2e51782..6791211e 100644 --- a/include/libunwind-common.h.in +++ b/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); diff --git a/src/mi/Gget_proc_name.c b/src/mi/Gget_proc_name.c index 0b77fa59..15fbbc8f 100644 --- a/src/mi/Gget_proc_name.c +++ b/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; diff --git a/tests/check-namespace.sh.in b/tests/check-namespace.sh.in index f99fb59f..b4f2ec15 100644 --- a/tests/check-namespace.sh.in +++ b/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 |