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 3195 2015-05-12 17:22:19Z emaste $
  26 .\"
  27 .Dd July 25, 2010
  28 .Os
  29 .Dt ADDR2LINE 1
  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 b Ar target | Fl -target Ns = Ns Ar target
  36 .Op Fl e Ar pathname | Fl -exe Ns = Ns Ar pathname
  37 .Op Fl f | Fl -functions
  38 .Op Fl j Ar sectionname | Fl -section Ns = Ns Ar sectionname
  39 .Op Fl s | Fl -basename
  40 .Op Fl C | Fl -demangle
  41 .Op Fl H | Fl -help
  42 .Op Fl V | Fl -version
  43 .Op Ar hexaddress Ns ...
  44 .Sh DESCRIPTION
  45 The
  46 .Nm
  47 utility translates program addresses specified by the command line
  48 arguments
  49 .Ar hexaddress
  50 to their corresponding source file names and line numbers.
  51 If no arguments are given to
  52 .Nm ,
  53 it will read these addresses from standard input.
  54 .Pp
  55 Program addresses specified by arguments
  56 .Ar hexaddress
  57 are encoded using the conventions accepted by
  58 .Xr strtoull 3 .
  59 .Pp
  60 By default,
  61 .Nm
  62 will use the executable
  63 .Dq Pa a.out .
  64 The
  65 .Fl e
  66 option may be used to specified a different ELF object.
  67 .Pp
  68 The
  69 .Nm
  70 utility recognizes the following options:
  71 .Bl -tag -width indent
  72 .It Fl b Ar target | Fl -target Ns = Ns Ar target
  73 This option is recognized by
  74 .Nm
  75 but is ignored.
  76 It is supported for compatibility with GNU binutils.
  77 .It Fl e Ar pathname | Fl -exe Ns = Ns Ar pathname
  78 Use the ELF object specified by argument
  79 .Ar pathname
  80 to translate addresses.
  81 If this option is not specified,
  82 .Nm
  83 will use the file
  84 .Dq Pa a.out .
  85 .It Fl f | Fl -functions
  86 Display function names in addition to file and line number information.
  87 .It Fl j Ar sectionname | Fl -section Ns = Ns Ar sectionname
  88 The values specified by arguments
  89 .Ar hexaddress
  90 are to be treated as offsets into the section named
  91 .Ar sectionname .
  92 .It Fl s | -basename
  93 Display only the base name for each file name.
  94 .It Fl C | Fl -demangle
  95 Demangle C++ names.
  96 .It Fl H | Fl -help
  97 Print a help message.
  98 .It Fl V | Fl -version
  99 Print a version identifier and exit.
 100 .El
 101 .Sh OUTPUT FORMAT
 102 If the
 103 .Fl f
 104 option was not specified,
 105 .Nm
 106 will print the file name and line number for each address specified
 107 on a separate line.
 108 .Pp
 109 If the
 110 .Fl f
 111 option was specified,
 112 .Nm
 113 will print a line containing the name of the function corresponding
 114 to program address
 115 .Ar hexaddress ,
 116 followed by a line with the file name and line number.
 117 .Pp
 118 The
 119 .Nm
 120 utility prints the file name and line number using the format
 121 .Dq FILENAME:LINENUMBER .
 122 .Pp
 123 If a file or function name could not be determined,
 124 .Nm
 125 will print a question mark in their place.
 126 If the line number could not be determined,
 127 .Nm
 128 will print a zero in its place.
 129 .Sh EXAMPLES
 130 To map address 080483c4 in the default executable
 131 .Pa a.out
 132 to a source file name and line number use:
 133 .D1 "% addr2line 080483c4"
 134 .Pp
 135 To map address 080483c4 in executable
 136 .Pa helloworld ,
 137 use:
 138 .D1 "% addr2line -e helloworld 080483c4"
 139 .Pp
 140 To have
 141 .Nm
 142 act as a filter reading addresses from its standard input use:
 143 .D1 "% addr2line"
 144 .Pp
 145 To print the function name corresponding to an address in addition to
 146 its source file and line number use:
 147 .D1 "% addr2line -f 080483c4"
 148 .Sh EXIT STATUS
 149 .Ex -std
 150 .Sh SEE ALSO
 151 .Xr nm 1 ,
 152 .Xr elfdump 1 ,
 153 .Xr elfcopy 1 ,
 154 .Xr strtoull 3
 155 .Sh AUTHORS
 156 The
 157 .Nm
 158 utility was written by
 159 .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .