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