contrib/elftoolchain/addr2line/addr2line.1

   1 .\" Copyright (c) 2009,2010 Joseph Koshy <jkoshy@users.sourceforge.net>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer
   9 .\"    in this position and unchanged.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS ``AS IS'' AND ANY EXPRESS OR
  15 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
  16 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
  17 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
  18 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  19 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  20 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  21 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  22 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
  23 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  24 .\"
  25 .\" $Id: addr2line.1 3642 2018-10-14 14:24:28Z jkoshy $
  26 .\"
  27 .Dd November 30, 2015
  28 .Dt ADDR2LINE 1
  29 .Os
  30 .Sh NAME
  31 .Nm addr2line
  32 .Nd translate program addresses to source file names and line numbers
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl a | Fl -addresses
  36 .Op Fl b Ar target | Fl -target Ns = Ns Ar target
  37 .Op Fl e Ar pathname | Fl -exe Ns = Ns Ar pathname
  38 .Op Fl f | Fl -functions
  39 .Op Fl i | Fl -inlines
  40 .Op Fl j Ar sectionname | Fl -section Ns = Ns Ar sectionname
  41 .Op Fl p | Fl -pretty-print
  42 .Op Fl s | Fl -basename
  43 .Op Fl C | Fl -demangle
  44 .Op Fl H | Fl -help
  45 .Op Fl V | Fl -version
  46 .Op Ar hexaddress Ns ...
  47 .Sh DESCRIPTION
  48 The
  49 .Nm
  50 utility translates program addresses specified by the command line
  51 arguments
  52 .Ar hexaddress
  53 to their corresponding source file names and line numbers.
  54 If no arguments are given to
  55 .Nm ,
  56 it will read these addresses from standard input.
  57 .Pp
  58 Program addresses specified by arguments
  59 .Ar hexaddress
  60 are encoded using the conventions accepted by
  61 .Xr strtoull 3 .
  62 .Pp
  63 By default,
  64 .Nm
  65 will use the executable
  66 .Dq Pa a.out .
  67 The
  68 .Fl e
  69 option may be used to specified a different ELF object.
  70 .Pp
  71 The
  72 .Nm
  73 utility recognizes the following options:
  74 .Bl -tag -width indent
  75 .It Fl a | Fl -addresses
  76 Display the address prior to the line number information.
  77 .It Fl b Ar target | Fl -target Ns = Ns Ar target
  78 This option is recognized by
  79 .Nm
  80 but is ignored.
  81 It is supported for compatibility with GNU binutils.
  82 .It Fl e Ar pathname | Fl -exe Ns = Ns Ar pathname
  83 Use the ELF object specified by argument
  84 .Ar pathname
  85 to translate addresses.
  86 If this option is not specified,
  87 .Nm
  88 will use the file
  89 .Dq Pa a.out .
  90 .It Fl f | Fl -functions
  91 Display function names in addition to file and line number information.
  92 .It Fl i | Fl -inlines
  93 If the address specified belongs to an inlined function, also display the line
  94 number information for its caller, recursively until the first non-inlined
  95 caller.
  96 .It Fl j Ar sectionname | Fl -section Ns = Ns Ar sectionname
  97 The values specified by arguments
  98 .Ar hexaddress
  99 are to be treated as offsets into the section named
 100 .Ar sectionname .
 101 .It Fl p | -pretty-print
 102 Display the line number information on one line, in human readable manner.
 103 .It Fl s | -basename
 104 Display only the base name for each file name.
 105 .It Fl C | Fl -demangle
 106 Demangle C++ names.
 107 .It Fl H | Fl -help
 108 Print a help message.
 109 .It Fl V | Fl -version
 110 Print a version identifier and exit.
 111 .El
 112 .Sh OUTPUT FORMAT
 113 If the
 114 .Fl f
 115 option was not specified,
 116 .Nm
 117 will print the file name and line number for each address specified
 118 on a separate line.
 119 .Pp
 120 If the
 121 .Fl f
 122 option was specified,
 123 .Nm
 124 will print a line containing the name of the function corresponding
 125 to program address
 126 .Ar hexaddress ,
 127 followed by a line with the file name and line number.
 128 .Pp
 129 If the
 130 .Fl p
 131 option was specified,
 132 .Nm
 133 will print line number information and function name on one line in
 134 human readable manner. If the
 135 .Fl i
 136 option was also specified,
 137 .Nm
 138 will print the caller function information prefixed with
 139 .Dq (inlined by) .
 140 .Pp
 141 The
 142 .Nm
 143 utility prints the file name and line number using the format
 144 .Dq FILENAME:LINENUMBER .
 145 .Pp
 146 If a file or function name could not be determined,
 147 .Nm
 148 will print a question mark in their place.
 149 If the line number could not be determined,
 150 .Nm
 151 will print a zero in its place.
 152 .Sh EXAMPLES
 153 To map address 080483c4 in the default executable
 154 .Pa a.out
 155 to a source file name and line number use:
 156 .D1 "% addr2line 080483c4"
 157 .Pp
 158 To map address 080483c4 in executable
 159 .Pa helloworld ,
 160 use:
 161 .D1 "% addr2line -e helloworld 080483c4"
 162 .Pp
 163 To have
 164 .Nm
 165 act as a filter reading addresses from its standard input use:
 166 .D1 "% addr2line"
 167 .Pp
 168 To print the function name corresponding to an address in addition to
 169 its source file and line number use:
 170 .D1 "% addr2line -f 080483c4"
 171 .Sh EXIT STATUS
 172 .Ex -std
 173 .Sh SEE ALSO
 174 .Xr nm 1 ,
 175 .Xr elfdump 1 ,
 176 .Xr elfcopy 1 ,
 177 .Xr strtoull 3
 178 .Sh AUTHORS
 179 The
 180 .Nm
 181 utility was written by
 182 .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .