llvm/docs/CommandGuide/llvm-nm.rst

   1 llvm-nm - list LLVM bitcode and object file's symbol table
   2 ==========================================================
   3
   4 .. program:: llvm-nm
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-nm` [*options*] [*filenames...*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 The :program:`llvm-nm` utility lists the names of symbols from LLVM bitcode
  15 files, object files, and archives. Each symbol is listed along with some simple
  16 information about its provenance. If no filename is specified, *a.out* is used
  17 as the input. If *-* is used as a filename, :program:`llvm-nm` will read a file
  18 from its standard input stream.
  19
  20 :program:`llvm-nm`'s default output format is the traditional BSD :program:`nm`
  21 output format. Each such output record consists of an (optional) 8-digit
  22 hexadecimal address, followed by a type code character, followed by a name, for
  23 each symbol. One record is printed per line; fields are separated by spaces.
  24 When the address is omitted, it is replaced by 8 spaces.
  25
  26 The supported type code characters are as follows. Where both lower and
  27 upper-case characters are listed for the same meaning, a lower-case character
  28 represents a local symbol, whilst an upper-case character represents a global
  29 (external) symbol:
  30
  31 a, A
  32
  33  Absolute symbol.
  34
  35 b, B
  36
  37  Uninitialized data (bss) object.
  38
  39 C
  40
  41  Common symbol. Multiple definitions link together into one definition.
  42
  43 d, D
  44
  45  Writable data object.
  46
  47 i, I
  48
  49  COFF: .idata symbol or symbol in a section with IMAGE_SCN_LNK_INFO set.
  50
  51 n
  52
  53  ELF: local symbol from non-alloc section.
  54
  55  COFF: debug symbol.
  56
  57 N
  58
  59  ELF: debug section symbol, or global symbol from non-alloc section.
  60
  61 s, S
  62
  63  COFF: section symbol.
  64
  65  Mach-O: absolute symbol or symbol from a section other than __TEXT_EXEC __text,
  66  __TEXT __text, __DATA __data, or __DATA __bss.
  67
  68 r, R
  69
  70  Read-only data object.
  71
  72 t, T
  73
  74  Code (text) object.
  75
  76 u
  77
  78  ELF: GNU unique symbol.
  79
  80 U
  81
  82  Named object is undefined in this file.
  83
  84 v
  85
  86  ELF: Undefined weak object. It is not a link failure if the object is not
  87  defined.
  88
  89 V
  90
  91  ELF: Defined weak object symbol. This definition will only be used if no
  92  regular definitions exist in a link. If multiple weak definitions and no
  93  regular definitions exist, one of the weak definitions will be used.
  94
  95 w
  96
  97  Undefined weak symbol other than an ELF object symbol. It is not a link failure
  98  if the symbol is not defined.
  99
 100 W
 101
 102  Defined weak symbol other than an ELF object symbol. This definition will only
 103  be used if no regular definitions exist in a link. If multiple weak definitions
 104  and no regular definitions exist, one of the weak definitions will be used.
 105
 106 \-
 107
 108  Mach-O: N_STAB symbol.
 109
 110 ?
 111
 112  Something unrecognizable.
 113
 114 Because LLVM bitcode files typically contain objects that are not considered to
 115 have addresses until they are linked into an executable image or dynamically
 116 compiled "just-in-time", :program:`llvm-nm` does not print an address for any
 117 symbol in an LLVM bitcode file, even symbols which are defined in the bitcode
 118 file.
 119
 120 OPTIONS
 121 -------
 122
 123 .. program:: llvm-nm
 124
 125 .. option:: -B
 126
 127  Use BSD output format. Alias for ``--format=bsd``.
 128
 129 .. option:: -X
 130
 131  Specify the type of XCOFF object file, ELF object file, or IR object file input
 132  from command line or from archive files that llvm-nm should examine. The
 133  mode must be one of the following:
 134
 135    32
 136          Process only 32-bit object files.
 137    64
 138          Process only 64-bit object files.
 139    32_64
 140          Process both 32-bit and 64-bit object files.
 141    any
 142          Process all the supported object files.
 143
 144   On AIX OS, the default is to process 32-bit object files only and to ignore
 145   64-bit objects. The can be changed by setting the OBJECT_MODE environment
 146   variable. For example, OBJECT_MODE=64 causes :program:`llvm-nm` to process
 147   64-bit objects and ignore 32-bit objects. The -X flag overrides the OBJECT_MODE
 148   variable.
 149
 150   On other operating systems, the default is to process all object files: the
 151   OBJECT_MODE environment variable is not supported.
 152
 153 .. option:: --debug-syms, -a
 154
 155  Show all symbols, even those usually suppressed.
 156
 157 .. option:: --defined-only, -U
 158
 159  Print only symbols defined in this file.
 160
 161 .. option:: --demangle, -C
 162
 163  Demangle symbol names.
 164
 165 .. option:: --dynamic, -D
 166
 167  Display dynamic symbols instead of normal symbols.
 168
 169 .. option:: --export-symbols
 170
 171  Print sorted symbols with their visibility (if applicable), with duplicates
 172  removed.
 173
 174 .. option:: --extern-only, -g
 175
 176  Print only symbols whose definitions are external; that is, accessible from
 177  other files.
 178
 179 .. option:: --format=<format>, -f
 180
 181  Select an output format; *format* may be *sysv*, *posix*, *darwin*, *bsd* or
 182  *just-symbols*.
 183  The default is *bsd*.
 184
 185 .. option:: --help, -h
 186
 187  Print a summary of command-line options and their meanings.
 188
 189 .. option:: -j
 190
 191  Print just the symbol names. Alias for `--format=just-symbols``.
 192
 193 .. option:: --line-numbers, -l
 194
 195  Use debugging information to print the filenames and line numbers where
 196  symbols are defined. Undefined symbols have the location of their first
 197  relocation printed instead.
 198
 199 .. option:: -m
 200
 201  Use Darwin format. Alias for ``--format=darwin``.
 202
 203 .. option:: --no-demangle
 204
 205  Don't demangle symbol names. This is the default.
 206
 207 .. option:: --no-llvm-bc
 208
 209  Disable the LLVM bitcode reader.
 210
 211 .. option:: --no-sort, -p
 212
 213  Show symbols in the order encountered.
 214
 215 .. option:: --no-weak, -W
 216
 217  Don't print weak symbols.
 218
 219 .. option:: --numeric-sort, -n, -v
 220
 221  Sort symbols by address.
 222
 223 .. option:: --portability, -P
 224
 225  Use POSIX.2 output format.  Alias for ``--format=posix``.
 226
 227 .. option:: --print-armap
 228
 229  Print the archive symbol table, in addition to the symbols.
 230
 231 .. option:: --print-file-name, -A, -o
 232
 233  Precede each symbol with the file it came from.
 234
 235 .. option:: --print-size, -S
 236
 237  Show symbol size as well as address (not applicable for Mach-O).
 238
 239 .. option:: --quiet
 240
 241  Suppress 'no symbols' diagnostic.
 242
 243 .. option:: --radix=<RADIX>, -t
 244
 245  Specify the radix of the symbol address(es). Values accepted are *d* (decimal),
 246  *x* (hexadecimal) and *o* (octal).
 247
 248 .. option:: --reverse-sort, -r
 249
 250  Sort symbols in reverse order.
 251
 252 .. option:: --size-sort
 253
 254  Sort symbols by size.
 255
 256 .. option:: --special-syms
 257
 258  Do not filter special symbols from the output.
 259
 260 .. option:: --undefined-only, -u
 261
 262  Print only undefined symbols.
 263
 264 .. option:: --version, -V
 265
 266  Display the version of the :program:`llvm-nm` executable, then exit. Does not
 267  stack with other commands.
 268
 269 .. option:: @<FILE>
 270
 271  Read command-line options from response file `<FILE>`.
 272
 273 MACH-O SPECIFIC OPTIONS
 274 -----------------------
 275
 276 .. option:: --add-dyldinfo
 277
 278  Add symbols from the dyldinfo, if they are not already in the symbol table.
 279  This is the default.
 280
 281 .. option:: --add-inlinedinfo
 282
 283  Add symbols from the inlined libraries, TBD file inputs only.
 284
 285 .. option:: --arch=<arch1[,arch2,...]>
 286
 287  Dump the symbols from the specified architecture(s).
 288
 289 .. option:: --dyldinfo-only
 290
 291  Dump only symbols from the dyldinfo.
 292
 293 .. option:: --no-dyldinfo
 294
 295  Do not add any symbols from the dyldinfo.
 296
 297 .. option:: -s <segment> <section>
 298
 299  Dump only symbols from this segment and section name.
 300
 301 .. option:: -x
 302
 303  Print symbol entry in hex.
 304
 305 XCOFF SPECIFIC OPTIONS
 306 ----------------------
 307
 308 .. option:: --no-rsrc
 309
 310   Exclude resource file symbols (``__rsrc``) from export symbol list.
 311
 312 BUGS
 313 ----
 314
 315  * :program:`llvm-nm` does not support the full set of arguments that GNU
 316    :program:`nm` does.
 317
 318 EXIT STATUS
 319 -----------
 320
 321 :program:`llvm-nm` exits with an exit code of zero.
 322
 323 SEE ALSO
 324 --------
 325
 326 :manpage:`llvm-ar(1)`, :manpage:`llvm-objdump(1)`, :manpage:`llvm-readelf(1)`,
 327 :manpage:`llvm-readobj(1)`