xenial (3) unw_get_proc_info_by_ip.3.gz

Provided by: libunwind-dev_1.1-4.1_amd64 bug

NAME
       unw_get_proc_info_by_ip -- get procedure info by IP


SYNOPSIS
       #include <libunwind.h>

       int unw_get_proc_info_by_ip(unw_addr_space_t as, unw_word_t ip, unw_proc_info_t *pip, void *arg);


DESCRIPTION
       The unw_get_proc_info_by_ip() routine returns the same kind of auxiliary information about a procedure as
       unw_get_proc_info(), except that the info is looked up by instruction-pointer (IP) instead of  a  cursor.
       This  is  more flexible because it is possible to look up the info for an arbitrary procedure, even if it
       is not part of the current call-chain. However, since it is more flexible, it also tends  to  run  slower
       (and often much slower) than unw_get_proc_info().

       The  routine  expects  the  followins 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 info should be looked up
       and pip is a pointer to a structure of type unw_proc_info_t which is used to return  the  info.   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.

       Note  that  for  the  purposes  of  libunwind,  the  code  of  a procedure is assumed to occupy a single,
       contiguous range of addresses. For this reason, it  is  alwas  possible  to  describe  the  extent  of  a
       procedure  with  the  start_ip  and  end_ip members. If a single function/routine is split into multiple,
       discontiguous pieces, libunwind will treat each piece as a separate procedure.


RETURN VALUE
       On successful completion, unw_get_proc_info_by_ip() returns 0. Otherwise the negative value of one of the
       error-codes below is returned.


THREAD AND SIGNAL SAFETY
       unw_get_proc_info()  is thread-safe. If the local address-space is passed in argument as, this routine is
       also safe to use from a signal handler.


ERRORS
       UNW_EUNSPEC
               An unspecified error occurred.

       UNW_ENOINFO
               Libunwind was unable to locate unwind-info for the procedure.

       UNW_EBADVERSION
               The unwind-info for the procedure has version or format that is not understood by libunwind.

       In addition, unw_get_proc_info() may return  any  error  returned  by  the  access_mem()  call-back  (see
       unw_create_addr_space(3)).


SEE ALSO
       libunwind(3), unw_create_addr_space(3), unw_get_proc_name(3), unw_get_proc_info(3), unw_init_remote(3)


AUTHOR
       David Mosberger-Tang
       Email: dmosberger@gmail.com
       WWW: http://www.nongnu.org/libunwind/.