unw_get_proc_name_by_ip(3)

1UNW_GET_PROC_NAME_BY_IP(3)   Programming Library    UNW_GET_PROC_NAME_BY_IP(3)
2
3
4

NAME

6       unw_get_proc_name_by_ip -- get procedure name
7

SYNOPSIS

9       #include <libunwind.h>
10
11       int  unw_get_proc_name_by_ip(unw_addr_space_t  as,  unw_word_t ip, char
12       *bufp, size_t len, unw_word_t *offp, void *arg);
13

DESCRIPTION

15       The unw_get_proc_name_by_ip() routine returns the name of  a  procedure
16       just like unw_get_proc_name(), except that the name is looked up by in‐
17       struction-pointer (IP) instead of a cursor.
18
19       The routine expects the following arguments: as is the address-space in
20       which  the  instruction-pointer  should be looked up.  For a look-up in
21       the local address-space, unw_local_addr_space can be  passed  for  this
22       argument.   Argument ip is the instruction-pointer for which the proce‐
23       dure name should be looked up. The bufp argument  is  a  pointer  to  a
24       character  buffer  that is at least len bytes long. This buffer is used
25       to return the name of the procedure. The offp argument is a pointer  to
26       a  word  that  is  used  to  return  the  byte-offset  of  the instruc‐
27       tion-pointer relative to the start of the procedure.   Lastly,  arg  is
28       the  address-space  argument that should be used when accessing the ad‐
29       dress-space. It has the same purpose as the argument of the  same  name
30       for  unw_init_remote().   When accessing the local address-space (first
31       argument is unw_local_addr_space), NULL must be passed for  this  argu‐
32       ment.
33
34       Note that on some platforms there is no reliable way to distinguish be‐
35       tween procedure names and ordinary labels. Furthermore, if  symbol  in‐
36       formation has been stripped from a program, procedure names may be com‐
37       pletely unavailable or may be limited to those exported via  a  dynamic
38       symbol  table.  In such cases, unw_get_proc_name_by_ip() may return the
39       name of a label or a preceding (nearby) procedure. However, the  offset
40       returned  through  offp  is always relative to the returned name, which
41       ensures that the value (address) of the returned name plus the returned
42       offset will always be equal to the instruction-pointer ip.
43

RETURN VALUE

45       On  successful  completion, unw_get_proc_name_by_ip() returns 0. Other‐
46       wise the negative value of one of the error-codes below is returned.
47

THREAD AND SIGNAL SAFETY

49       unw_get_proc_name_by_ip() is thread-safe. If the local address-space is
50       passed  in  argument as, this routine is also safe to use from a signal
51       handler.
52

ERRORS

54       UNW_EUNSPEC
55               An unspecified error occurred.
56
57       UNW_ENOINFO
58               Libunwind was unable to determine the name of the procedure.
59
60       UNW_ENOMEM
61               The procedure name is too long to fit in the buffer provided. A
62              truncated version of the name has been returned.
63
64       In addition, unw_get_proc_name_by_ip() may return any error returned by
65       the access_mem() call-back (see unw_create_addr_space(3)).
66

AUTHOR

72       David Mosberger-Tang
73       Email: dmosberger@gmail.com
74       WWW: http://www.nongnu.org/libunwind/.
75
76
77
78Programming Library             30 August 2021      UNW_GET_PROC_NAME_BY_IP(3)