unw_get_proc_info_by_ip(3)

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

NAME

6       unw_get_proc_info_by_ip -- get procedure info by IP
7

SYNOPSIS

9       #include <libunwind.h>
10
11       int   unw_get_proc_info_by_ip(unw_addr_space_t   as,   unw_word_t   ip,
12       unw_proc_info_t *pip, void *arg);
13

DESCRIPTION

15       The unw_get_proc_info_by_ip() routine returns the same kind  of  auxil‐
16       iary  information about a procedure as unw_get_proc_info(), except that
17       the info is looked up by instruction-pointer (IP) instead of a  cursor.
18       This is more flexible because it is possible to look up the info for an
19       arbitrary procedure, even if it is not part of the current  call-chain.
20       However,  since  it  is more flexible, it also tends to run slower (and
21       often much slower) than unw_get_proc_info().
22
23       The routine expects the followins arguments: as is the address-space in
24       which  the  instruction-pointer  should be looked up.  For a look-up in
25       the local address-space, unw_local_addr_space can be  passed  for  this
26       argument.   Argument ip is the instruction-pointer for which the proce‐
27       dure info should be looked up and pip is a pointer to  a  structure  of
28       type  unw_proc_info_t which is used to return the info.  Lastly, arg is
29       the address-space argument that  should  be  used  when  accessing  the
30       address-space. It has the same purpose as the argument of the same name
31       for unw_init_remote().  When accessing the local  address-space  (first
32       argument  is  unw_local_addr_space), NULL must be passed for this argu‐
33       ment.
34
35       Note that for the purposes of libunwind, the code  of  a  procedure  is
36       assumed  to  occupy  a  single, contiguous range of addresses. For this
37       reason, it is alwas possible to describe the extent of a procedure with
38       the  start_ip and end_ip members. If a single function/routine is split
39       into multiple, discontiguous pieces, libunwind will treat each piece as
40       a separate procedure.
41

RETURN VALUE

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

THREAD AND SIGNAL SAFETY

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

ERRORS

52       UNW_EUNSPEC
53               An unspecified error occurred.
54
55       UNW_ENOINFO
56               Libunwind was unable to locate unwind-info for the procedure.
57
58       UNW_EBADVERSION
59               The unwind-info for the procedure has version or format that is
60              not understood by libunwind.
61
62       In  addition,  unw_get_proc_info() may return any error returned by the
63       access_mem() call-back (see unw_create_addr_space(3)).
64

AUTHOR

70       David Mosberger-Tang
71       Email: dmosberger@gmail.com
72       WWW: http://www.nongnu.org/libunwind/.
73
74
75
76Programming Library             16 August 2007      UNW_GET_PROC_INFO_BY_IP(3)