contrib/binutils-2.17/binutils/doc/nm.1

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  29 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  30 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  31 .\" nothing in troff, for use with C<>.
  32 .tr \(*W-
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .\"
  67 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  68 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  69 .    \" fudge factors for nroff and troff
  70 .if n \{\
  71 .    ds #H 0
  72 .    ds #V .8m
  73 .    ds #F .3m
  74 .    ds #[ \f1
  75 .    ds #] \fP
  76 .\}
  77 .if t \{\
  78 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  79 .    ds #V .6m
  80 .    ds #F 0
  81 .    ds #[ \&
  82 .    ds #] \&
  83 .\}
  84 .    \" simple accents for nroff and troff
  85 .if n \{\
  86 .    ds ' \&
  87 .    ds ` \&
  88 .    ds ^ \&
  89 .    ds , \&
  90 .    ds ~ ~
  91 .    ds /
  92 .\}
  93 .if t \{\
  94 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  95 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  96 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  97 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  98 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  99 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 100 .\}
 101 .    \" troff and (daisy-wheel) nroff accents
 102 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 103 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 104 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 105 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 106 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 107 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 108 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 109 .ds ae a\h'-(\w'a'u*4/10)'e
 110 .ds Ae A\h'-(\w'A'u*4/10)'E
 111 .    \" corrections for vroff
 112 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 113 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 114 .    \" for low resolution devices (crt and lpr)
 115 .if \n(.H>23 .if \n(.V>19 \
 116 \{\
 117 .    ds : e
 118 .    ds 8 ss
 119 .    ds o a
 120 .    ds d- d\h'-1'\(ga
 121 .    ds D- D\h'-1'\(hy
 122 .    ds th \o'bp'
 123 .    ds Th \o'LP'
 124 .    ds ae ae
 125 .    ds Ae AE
 126 .\}
 127 .rm #[ #] #H #V #F C
 128 .\" ========================================================================
 129 .\"
 130 .IX Title "NM 1"
 131 .TH NM 1 "2006-06-23" "binutils-2.17" "GNU Development Tools"
 132 .SH "NAME"
 133 nm \- list symbols from object files
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 nm [\fB\-a\fR|\fB\-\-debug\-syms\fR] [\fB\-g\fR|\fB\-\-extern\-only\fR]
 137    [\fB\-B\fR] [\fB\-C\fR|\fB\-\-demangle\fR[=\fIstyle\fR]] [\fB\-D\fR|\fB\-\-dynamic\fR]
 138    [\fB\-S\fR|\fB\-\-print\-size\fR] [\fB\-s\fR|\fB\-\-print\-armap\fR]
 139    [\fB\-A\fR|\fB\-o\fR|\fB\-\-print\-file\-name\fR][\fB\-\-special\-syms\fR]
 140    [\fB\-n\fR|\fB\-v\fR|\fB\-\-numeric\-sort\fR] [\fB\-p\fR|\fB\-\-no\-sort\fR]
 141    [\fB\-r\fR|\fB\-\-reverse\-sort\fR] [\fB\-\-size\-sort\fR] [\fB\-u\fR|\fB\-\-undefined\-only\fR]
 142    [\fB\-t\fR \fIradix\fR|\fB\-\-radix=\fR\fIradix\fR] [\fB\-P\fR|\fB\-\-portability\fR]
 143    [\fB\-\-target=\fR\fIbfdname\fR] [\fB\-f\fR\fIformat\fR|\fB\-\-format=\fR\fIformat\fR]
 144    [\fB\-\-defined\-only\fR] [\fB\-l\fR|\fB\-\-line\-numbers\fR] [\fB\-\-no\-demangle\fR]
 145    [\fB\-V\fR|\fB\-\-version\fR] [\fB\-X 32_64\fR] [\fB\-\-help\fR]  [\fIobjfile\fR...]
 146 .SH "DESCRIPTION"
 147 .IX Header "DESCRIPTION"
 148 \&\s-1GNU\s0 \fBnm\fR lists the symbols from object files \fIobjfile\fR....
 149 If no object files are listed as arguments, \fBnm\fR assumes the file
 150 \&\fIa.out\fR.
 151 .PP
 152 For each symbol, \fBnm\fR shows:
 153 .IP "\(bu" 4
 154 The symbol value, in the radix selected by options (see below), or
 155 hexadecimal by default.
 156 .IP "\(bu" 4
 157 The symbol type.  At least the following types are used; others are, as
 158 well, depending on the object file format.  If lowercase, the symbol is
 159 local; if uppercase, the symbol is global (external).
 160 .RS 4
 161 .ie n .IP """A""" 4
 162 .el .IP "\f(CWA\fR" 4
 163 .IX Item "A"
 164 The symbol's value is absolute, and will not be changed by further
 165 linking.
 166 .ie n .IP """B""" 4
 167 .el .IP "\f(CWB\fR" 4
 168 .IX Item "B"
 169 The symbol is in the uninitialized data section (known as \s-1BSS\s0).
 170 .ie n .IP """C""" 4
 171 .el .IP "\f(CWC\fR" 4
 172 .IX Item "C"
 173 The symbol is common.  Common symbols are uninitialized data.  When
 174 linking, multiple common symbols may appear with the same name.  If the
 175 symbol is defined anywhere, the common symbols are treated as undefined
 176 references.
 177 .ie n .IP """D""" 4
 178 .el .IP "\f(CWD\fR" 4
 179 .IX Item "D"
 180 The symbol is in the initialized data section.
 181 .ie n .IP """G""" 4
 182 .el .IP "\f(CWG\fR" 4
 183 .IX Item "G"
 184 The symbol is in an initialized data section for small objects.  Some
 185 object file formats permit more efficient access to small data objects,
 186 such as a global int variable as opposed to a large global array.
 187 .ie n .IP """I""" 4
 188 .el .IP "\f(CWI\fR" 4
 189 .IX Item "I"
 190 The symbol is an indirect reference to another symbol.  This is a \s-1GNU\s0
 191 extension to the a.out object file format which is rarely used.
 192 .ie n .IP """N""" 4
 193 .el .IP "\f(CWN\fR" 4
 194 .IX Item "N"
 195 The symbol is a debugging symbol.
 196 .ie n .IP """R""" 4
 197 .el .IP "\f(CWR\fR" 4
 198 .IX Item "R"
 199 The symbol is in a read only data section.
 200 .ie n .IP """S""" 4
 201 .el .IP "\f(CWS\fR" 4
 202 .IX Item "S"
 203 The symbol is in an uninitialized data section for small objects.
 204 .ie n .IP """T""" 4
 205 .el .IP "\f(CWT\fR" 4
 206 .IX Item "T"
 207 The symbol is in the text (code) section.
 208 .ie n .IP """U""" 4
 209 .el .IP "\f(CWU\fR" 4
 210 .IX Item "U"
 211 The symbol is undefined.
 212 .ie n .IP """V""" 4
 213 .el .IP "\f(CWV\fR" 4
 214 .IX Item "V"
 215 The symbol is a weak object.  When a weak defined symbol is linked with
 216 a normal defined symbol, the normal defined symbol is used with no error.
 217 When a weak undefined symbol is linked and the symbol is not defined,
 218 the value of the weak symbol becomes zero with no error.
 219 .ie n .IP """W""" 4
 220 .el .IP "\f(CWW\fR" 4
 221 .IX Item "W"
 222 The symbol is a weak symbol that has not been specifically tagged as a
 223 weak object symbol.  When a weak defined symbol is linked with a normal
 224 defined symbol, the normal defined symbol is used with no error.
 225 When a weak undefined symbol is linked and the symbol is not defined,
 226 the value of the symbol is determined in a system-specific manner without
 227 error.  On some systems, uppercase indicates that a default value has been
 228 specified.
 229 .ie n .IP """\-""" 4
 230 .el .IP "\f(CW\-\fR" 4
 231 .IX Item "-"
 232 The symbol is a stabs symbol in an a.out object file.  In this case, the
 233 next values printed are the stabs other field, the stabs desc field, and
 234 the stab type.  Stabs symbols are used to hold debugging information.
 235 .ie n .IP """?""" 4
 236 .el .IP "\f(CW?\fR" 4
 237 .IX Item "?"
 238 The symbol type is unknown, or object file format specific.
 239 .RE
 240 .RS 4
 241 .RE
 242 .IP "\(bu" 4
 243 The symbol name.
 244 .SH "OPTIONS"
 245 .IX Header "OPTIONS"
 246 The long and short forms of options, shown here as alternatives, are
 247 equivalent.
 248 .IP "\fB\-A\fR" 4
 249 .IX Item "-A"
 250 .PD 0
 251 .IP "\fB\-o\fR" 4
 252 .IX Item "-o"
 253 .IP "\fB\-\-print\-file\-name\fR" 4
 254 .IX Item "--print-file-name"
 255 .PD
 256 Precede each symbol by the name of the input file (or archive member)
 257 in which it was found, rather than identifying the input file once only,
 258 before all of its symbols.
 259 .IP "\fB\-a\fR" 4
 260 .IX Item "-a"
 261 .PD 0
 262 .IP "\fB\-\-debug\-syms\fR" 4
 263 .IX Item "--debug-syms"
 264 .PD
 265 Display all symbols, even debugger-only symbols; normally these are not
 266 listed.
 267 .IP "\fB\-B\fR" 4
 268 .IX Item "-B"
 269 The same as \fB\-\-format=bsd\fR (for compatibility with the \s-1MIPS\s0 \fBnm\fR).
 270 .IP "\fB\-C\fR" 4
 271 .IX Item "-C"
 272 .PD 0
 273 .IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
 274 .IX Item "--demangle[=style]"
 275 .PD
 276 Decode (\fIdemangle\fR) low-level symbol names into user-level names.
 277 Besides removing any initial underscore prepended by the system, this
 278 makes \*(C+ function names readable. Different compilers have different
 279 mangling styles. The optional demangling style argument can be used to
 280 choose an appropriate demangling style for your compiler.
 281 .IP "\fB\-\-no\-demangle\fR" 4
 282 .IX Item "--no-demangle"
 283 Do not demangle low-level symbol names.  This is the default.
 284 .IP "\fB\-D\fR" 4
 285 .IX Item "-D"
 286 .PD 0
 287 .IP "\fB\-\-dynamic\fR" 4
 288 .IX Item "--dynamic"
 289 .PD
 290 Display the dynamic symbols rather than the normal symbols.  This is
 291 only meaningful for dynamic objects, such as certain types of shared
 292 libraries.
 293 .IP "\fB\-f\fR \fIformat\fR" 4
 294 .IX Item "-f format"
 295 .PD 0
 296 .IP "\fB\-\-format=\fR\fIformat\fR" 4
 297 .IX Item "--format=format"
 298 .PD
 299 Use the output format \fIformat\fR, which can be \f(CW\*(C`bsd\*(C'\fR,
 300 \&\f(CW\*(C`sysv\*(C'\fR, or \f(CW\*(C`posix\*(C'\fR.  The default is \f(CW\*(C`bsd\*(C'\fR.
 301 Only the first character of \fIformat\fR is significant; it can be
 302 either upper or lower case.
 303 .IP "\fB\-g\fR" 4
 304 .IX Item "-g"
 305 .PD 0
 306 .IP "\fB\-\-extern\-only\fR" 4
 307 .IX Item "--extern-only"
 308 .PD
 309 Display only external symbols.
 310 .IP "\fB\-l\fR" 4
 311 .IX Item "-l"
 312 .PD 0
 313 .IP "\fB\-\-line\-numbers\fR" 4
 314 .IX Item "--line-numbers"
 315 .PD
 316 For each symbol, use debugging information to try to find a filename and
 317 line number.  For a defined symbol, look for the line number of the
 318 address of the symbol.  For an undefined symbol, look for the line
 319 number of a relocation entry which refers to the symbol.  If line number
 320 information can be found, print it after the other symbol information.
 321 .IP "\fB\-n\fR" 4
 322 .IX Item "-n"
 323 .PD 0
 324 .IP "\fB\-v\fR" 4
 325 .IX Item "-v"
 326 .IP "\fB\-\-numeric\-sort\fR" 4
 327 .IX Item "--numeric-sort"
 328 .PD
 329 Sort symbols numerically by their addresses, rather than alphabetically
 330 by their names.
 331 .IP "\fB\-p\fR" 4
 332 .IX Item "-p"
 333 .PD 0
 334 .IP "\fB\-\-no\-sort\fR" 4
 335 .IX Item "--no-sort"
 336 .PD
 337 Do not bother to sort the symbols in any order; print them in the order
 338 encountered.
 339 .IP "\fB\-P\fR" 4
 340 .IX Item "-P"
 341 .PD 0
 342 .IP "\fB\-\-portability\fR" 4
 343 .IX Item "--portability"
 344 .PD
 345 Use the \s-1POSIX\s0.2 standard output format instead of the default format.
 346 Equivalent to \fB\-f posix\fR.
 347 .IP "\fB\-S\fR" 4
 348 .IX Item "-S"
 349 .PD 0
 350 .IP "\fB\-\-print\-size\fR" 4
 351 .IX Item "--print-size"
 352 .PD
 353 Print size, not the value, of defined symbols for the \f(CW\*(C`bsd\*(C'\fR output format.
 354 .IP "\fB\-s\fR" 4
 355 .IX Item "-s"
 356 .PD 0
 357 .IP "\fB\-\-print\-armap\fR" 4
 358 .IX Item "--print-armap"
 359 .PD
 360 When listing symbols from archive members, include the index: a mapping
 361 (stored in the archive by \fBar\fR or \fBranlib\fR) of which modules
 362 contain definitions for which names.
 363 .IP "\fB\-r\fR" 4
 364 .IX Item "-r"
 365 .PD 0
 366 .IP "\fB\-\-reverse\-sort\fR" 4
 367 .IX Item "--reverse-sort"
 368 .PD
 369 Reverse the order of the sort (whether numeric or alphabetic); let the
 370 last come first.
 371 .IP "\fB\-\-size\-sort\fR" 4
 372 .IX Item "--size-sort"
 373 Sort symbols by size.  The size is computed as the difference between
 374 the value of the symbol and the value of the symbol with the next higher
 375 value.  If the \f(CW\*(C`bsd\*(C'\fR output format is used the size of the symbol
 376 is printed, rather than the value, and \fB\-S\fR must be used in order
 377 both size and value to be printed.
 378 .IP "\fB\-\-special\-syms\fR" 4
 379 .IX Item "--special-syms"
 380 Display symbols which have a target-specific special meaning.  These
 381 symbols are usually used by the target for some special processing and
 382 are not normally helpful when included included in the normal symbol
 383 lists.  For example for \s-1ARM\s0 targets this option would skip the mapping
 384 symbols used to mark transistions between \s-1ARM\s0 code, \s-1THUMB\s0 code and
 385 data.
 386 .IP "\fB\-t\fR \fIradix\fR" 4
 387 .IX Item "-t radix"
 388 .PD 0
 389 .IP "\fB\-\-radix=\fR\fIradix\fR" 4
 390 .IX Item "--radix=radix"
 391 .PD
 392 Use \fIradix\fR as the radix for printing the symbol values.  It must be
 393 \&\fBd\fR for decimal, \fBo\fR for octal, or \fBx\fR for hexadecimal.
 394 .IP "\fB\-\-target=\fR\fIbfdname\fR" 4
 395 .IX Item "--target=bfdname"
 396 Specify an object code format other than your system's default format.
 397 .IP "\fB\-u\fR" 4
 398 .IX Item "-u"
 399 .PD 0
 400 .IP "\fB\-\-undefined\-only\fR" 4
 401 .IX Item "--undefined-only"
 402 .PD
 403 Display only undefined symbols (those external to each object file).
 404 .IP "\fB\-\-defined\-only\fR" 4
 405 .IX Item "--defined-only"
 406 Display only defined symbols for each object file.
 407 .IP "\fB\-V\fR" 4
 408 .IX Item "-V"
 409 .PD 0
 410 .IP "\fB\-\-version\fR" 4
 411 .IX Item "--version"
 412 .PD
 413 Show the version number of \fBnm\fR and exit.
 414 .IP "\fB\-X\fR" 4
 415 .IX Item "-X"
 416 This option is ignored for compatibility with the \s-1AIX\s0 version of
 417 \&\fBnm\fR.  It takes one parameter which must be the string
 418 \&\fB32_64\fR.  The default mode of \s-1AIX\s0 \fBnm\fR corresponds
 419 to \fB\-X 32\fR, which is not supported by \s-1GNU\s0 \fBnm\fR.
 420 .IP "\fB\-\-help\fR" 4
 421 .IX Item "--help"
 422 Show a summary of the options to \fBnm\fR and exit.
 423 .IP "\fB@\fR\fIfile\fR" 4
 424 .IX Item "@file"
 425 Read command-line options from \fIfile\fR.  The options read are
 426 inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
 427 does not exist, or cannot be read, then the option will be treated
 428 literally, and not removed.
 429 .Sp
 430 Options in \fIfile\fR are separated by whitespace.  A whitespace
 431 character may be included in an option by surrounding the entire
 432 option in either single or double quotes.  Any character (including a
 433 backslash) may be included by prefixing the character to be included
 434 with a backslash.  The \fIfile\fR may itself contain additional
 435 @\fIfile\fR options; any such options will be processed recursively.
 436 .SH "SEE ALSO"
 437 .IX Header "SEE ALSO"
 438 \&\fIar\fR\|(1), \fIobjdump\fR\|(1), \fIranlib\fR\|(1), and the Info entries for \fIbinutils\fR.
 439 .SH "COPYRIGHT"
 440 .IX Header "COPYRIGHT"
 441 Copyright (c) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
 442 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
 443 .PP
 444 Permission is granted to copy, distribute and/or modify this document
 445 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1
 446 or any later version published by the Free Software Foundation;
 447 with no Invariant Sections, with no Front-Cover Texts, and with no
 448 Back-Cover Texts.  A copy of the license is included in the
 449 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".