| mostang.com!davidm | 9eb9f31 | 2003-04-01 07:19:34 +0000 | [diff] [blame] | 1 | '\" t |
| 2 | .\" Manual page created with latex2man on Mon Mar 31 14:18:02 PST 2003 |
| 3 | .\" NOTE: This file is generated, DO NOT EDIT. |
| 4 | .de Vb |
| 5 | .ft CW |
| 6 | .nf |
| 7 | .. |
| 8 | .de Ve |
| 9 | .ft R |
| 10 | |
| 11 | .fi |
| 12 | .. |
| 13 | .TH "UNW\\_GET\\_PROC\\_NAME" "3" "31 March 2003" "Programming Library " "Programming Library " |
| 14 | .SH NAME |
| 15 | unw_get_proc_name |
| 16 | \-\- get name of current procedure |
| 17 | .PP |
| 18 | .SH SYNOPSIS |
| 19 | |
| 20 | .PP |
| 21 | #include <libunwind.h> |
| 22 | .br |
| 23 | .PP |
| 24 | int |
| 25 | unw_get_proc_name(unw_cursor_t *cp, |
| 26 | char *bufp, |
| 27 | size_t |
| 28 | len, |
| 29 | unw_word_t *offp); |
| 30 | .br |
| 31 | .PP |
| 32 | .SH DESCRIPTION |
| 33 | |
| 34 | .PP |
| 35 | The unw_get_proc_name() |
| 36 | routine returns the name of the |
| 37 | procedure that created the stack frame identified by argument |
| 38 | cp\&. |
| 39 | The bufp |
| 40 | argument is a pointer to a character buffer |
| 41 | that is at least len |
| 42 | bytes long. This buffer is used to return |
| 43 | the name of the procedure. The offp |
| 44 | argument is a pointer to a |
| 45 | word that is used to return the byte\-offset of the instruction\-pointer |
| 46 | saved in the stack frame identified by cp, |
| 47 | relative to the start |
| 48 | of the procedure. For example, if procedure foo() |
| 49 | starts at |
| 50 | address 0x40003000, then invoking unw_get_proc_name() |
| 51 | on a |
| 52 | stack frame with an instruction\-pointer value of 0x40003080 would |
| 53 | return a value of 0x80 in the word pointed to by offp |
| 54 | (assuming |
| 55 | the procedure is at least 0x80 bytes long). |
| 56 | .PP |
| 57 | Note that on some platforms there is no reliable way to distinguish |
| 58 | between procedure names and ordinary labels. Furthermore, if symbol |
| 59 | information has been stripped from a program, procedure names may be |
| 60 | completely unavailable or may be limited to those exported via a |
| 61 | dynamic symbol table. In such cases, unw_get_proc_name() |
| 62 | may return the name of a label or a preceeding (nearby) procedure. |
| 63 | However, the offset returned through offp |
| 64 | is always relative to |
| 65 | the returned name, which ensures that the value (address) of the |
| 66 | returned name plus the returned offset will always be equal to the |
| 67 | instruction\-pointer of the stack frame identified by cp\&. |
| 68 | .PP |
| 69 | .SH RETURN VALUE |
| 70 | |
| 71 | .PP |
| 72 | On successful completion, unw_get_proc_name() |
| 73 | returns 0. |
| 74 | Otherwise the negative value of one of the error\-codes below is |
| 75 | returned. |
| 76 | .PP |
| 77 | .SH THREAD AND SIGNAL SAFETY |
| 78 | |
| 79 | .PP |
| 80 | unw_get_proc_name() |
| 81 | is thread\-safe but \fInot\fP |
| 82 | safe to |
| 83 | use from a signal handler. |
| 84 | .PP |
| 85 | .SH ERRORS |
| 86 | |
| 87 | .PP |
| 88 | .TP |
| 89 | UNW_EUNSPEC |
| 90 | An unspecified error occurred. |
| 91 | .TP |
| 92 | UNW_ENOINFO |
| 93 | Libunwind |
| 94 | was unable to determine |
| 95 | the name of the procedure. |
| 96 | .TP |
| 97 | UNW_ENOMME |
| 98 | The procedure name is too long to fit |
| 99 | in the buffer provided. A truncated version of the name has been |
| 100 | returned. |
| 101 | .PP |
| 102 | In addition, unw_get_proc_name() |
| 103 | may return any error |
| 104 | returned by the access_mem() |
| 105 | call\-back (see |
| 106 | unw_create_addr_space(3)). |
| 107 | .PP |
| 108 | .SH SEE ALSO |
| 109 | |
| 110 | .PP |
| 111 | libunwind(3), |
| 112 | unw_get_proc_info(3) |
| 113 | .PP |
| 114 | .SH AUTHOR |
| 115 | |
| 116 | .PP |
| 117 | David Mosberger\-Tang |
| 118 | .br |
| 119 | Hewlett\-Packard Labs |
| 120 | .br |
| 121 | Palo\-Alto, CA 94304 |
| 122 | .br |
| 123 | Email: \fBdavidm@hpl.hp.com\fP |
| 124 | .br |
| 125 | WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&. |
| 126 | .\" NOTE: This file is generated, DO NOT EDIT. |