doc/unw_get_proc_name.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:45 MDT 2007
   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" "16 August 2007" "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. If cursor cp
  82 is
  83 in the local address\-space, this routine is also safe to use from a
  84 signal handler.
  85 .PP
  86 .SH ERRORS
  87
  88 .PP
  89 .TP
  90 UNW_EUNSPEC
  91  An unspecified error occurred.
  92 .TP
  93 UNW_ENOINFO
  94  Libunwind
  95 was unable to determine
  96 the name of the procedure.
  97 .TP
  98 UNW_ENOMEM
  99  The procedure name is too long to fit
 100 in the buffer provided. A truncated version of the name has been
 101 returned.
 102 .PP
 103 In addition, unw_get_proc_name()
 104 may return any error
 105 returned by the access_mem()
 106 call\-back (see
 107 unw_create_addr_space(3)).
 108 .PP
 109 .SH SEE ALSO
 110
 111 .PP
 112 libunwind(3),
 113 unw_get_proc_info(3)
 114 .PP
 115 .SH AUTHOR
 116
 117 .PP
 118 David Mosberger\-Tang
 119 .br
 120 Email: \fBdmosberger@gmail.com\fP
 121 .br
 122 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 123 .\" NOTE: This file is generated, DO NOT EDIT.