1UNW_GET_PROC_NAME(3) Programming Library UNW_GET_PROC_NAME(3)
2
6 unw_get_proc_name -- get name of current procedure
7
9 #include <libunwind.h>
10 int unw_get_proc_name(unw_cursor_t *cp, char *bufp, size_t len,
12 unw_word_t *offp);
13
15 The unw_get_proc_name() routine returns the name of the procedure that
16 created the stack frame identified by argument cp. The bufp argument
17 is a pointer to a character buffer that is at least len bytes long.
18 This buffer is used to return the name of the procedure. The offp argu‐
19 ment is a pointer to a word that is used to return the byte-offset of
20 the instruction-pointer saved in the stack frame identified by cp, rel‐
21 ative to the start of the procedure. For example, if procedure foo()
22 starts at address 0x40003000, then invoking unw_get_proc_name() on a
23 stack frame with an instruction-pointer value of 0x40003080 would
24 return a value of 0x80 in the word pointed to by offp (assuming the
25 procedure is at least 0x80 bytes long).
26 If bufp is NULL , buf_len is still verified to fit and offp is set.
28 Passing buf_len as zero to indicate no limits on the buffer length is
29 only safe if buf is NULL , otherwise the callback is entitled and
30 likely to scribble anywhere in the entire address space.
31 Note that on some platforms there is no reliable way to distinguish
33 between procedure names and ordinary labels. Furthermore, if symbol
34 information has been stripped from a program, procedure names may be
35 completely unavailable or may be limited to those exported via a
36 dynamic symbol table. In such cases, unw_get_proc_name() may return the
37 name of a label or a preceeding (nearby) procedure. However, the off‐
38 set returned through offp is always relative to the returned name,
39 which ensures that the value (address) of the returned name plus the
40 returned offset will always be equal to the instruction-pointer of the
41 stack frame identified by cp.
42
44 On successful completion, unw_get_proc_name() returns 0. Otherwise the
45 negative value of one of the error-codes below is returned.
46
48 unw_get_proc_name() is thread-safe. If cursor cp is in the local
49 address-space, this routine is also safe to use from a signal handler.
50
52 UNW_EUNSPEC
53 An unspecified error occurred.
54 UNW_ENOINFO
56 Libunwind was unable to determine the name of the procedure.
57 UNW_ENOMME
59 The procedure name is too long to fit in the buffer provided. A
60 truncated version of the name has been returned.
61 In addition, unw_get_proc_name() may return any error returned by the
63 access_mem() call-back (see unw_create_addr_space(3)).
64
66 libunwind(3), unw_get_proc_info(3)
67
69 David Mosberger-Tang
70 Hewlett-Packard Labs
71 Palo-Alto, CA 94304
72 Email: davidm@hpl.hp.com
73 WWW: http://www.hpl.hp.com/research/linux/libunwind/.
74Programming Library 05 August 2004 UNW_GET_PROC_NAME(3)