xref: /freebsd/contrib/elftoolchain/nm/nm.1 (revision 907b59d76938e654f0d040a888e8dfca3de1e222)
1.\" Copyright (c) 2007 Hyogeol Lee <hyogeollee@gmail.com>
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: nm.1 3195 2015-05-12 17:22:19Z emaste $
26.\"
27.Dd February 15, 2015
28.Os
29.Dt NM 1
30.Sh NAME
31.Nm nm
32.Nd display symbolic information in object files
33.Sh SYNOPSIS
34.Nm
35.Op Fl -debug-syms
36.Op Fl -defined-only
37.Op Fl -demangle Ns Op = Ns style
38.Op Fl -dynamic
39.Op Fl -extern-only
40.Op Fl -help
41.Op Fl -line-numbers
42.Op Fl -no-demangle
43.Op Fl -no-sort
44.Op Fl -numeric-sort
45.Op Fl -print-armap
46.Op Fl -print-file-name
47.Op Fl -print-size
48.Op Fl -radix= Ns Ar format
49.Op Fl -reverse-sort
50.Op Fl -size-sort
51.Op Fl -undefined-only
52.Op Fl -version
53.Op Fl A
54.Op Fl B
55.Op Fl C Op Ar style
56.Op Fl D
57.Op Fl P
58.Op Fl V
59.Op Fl a
60.Op Fl e
61.Op Fl g
62.Op Fl h
63.Op Fl l
64.Op Fl n
65.Op Fl o
66.Op Fl p
67.Op Fl r
68.Op Fl S
69.Op Fl s
70.Op Fl t Ar format
71.Op Fl u
72.Op Fl x
73.Ar
74.Sh DESCRIPTION
75The
76.Nm
77utility displays symbolic information in the object files,
78executables, and object library files named by its arguments.
79Lack of symbolic information in an otherwise valid input
80file, is not considered to be an error.
81If no files are specified on the command line,
82.Nm
83will attempt to read
84.Pa a.out .
85.Pp
86The
87.Nm
88utility recognizes the following options:
89.Bl -tag -width ".Fl d Ar argument"
90.It Fl -debug-syms
91Display all symbols, including debugger-only symbols.
92.It Fl -defined-only
93Display only defined symbols.
94.It Fl -demangle Ns Op = Ns Ar style
95Decode (demangle) low-level symbol names into human-readable names.
96Supported values for argument
97.Ar style
98are
99.Sq auto ,
100.Sq gnu-v2 ,
101.Sq gnu-v3
102and
103.Sq arm.
104If argument
105.Ar style
106is not specified, it is taken to be
107.Sq auto .
108.It Fl -dynamic
109Only display dynamic symbols.
110This option is only meaningful for shared libraries.
111.It Fl -extern-only
112Only display information about global (external) symbols.
113.It Fl -help
114Display a help message and exit.
115.It Fl -format Ns = Ns Ar format
116Display output in the format specified by argument
117.Ar format .
118Supported values for the format argument are
119.Sq bsd ,
120.Sq sysv ,
121and
122.Sq posix .
123The default output format is
124.Sq bsd .
125.It Fl -line-numbers
126Display the filename and line number associated a symbol using
127any debugging information present in the input file.
128For defined symbols, look up the line number associated with
129the address of the symbol.
130For undefined symbols, look up the line number associated with
131a relocation entry that refers to the symbol.
132If line number information can be determined, it is displayed after
133other symbol information.
134.It Fl -no-demangle
135Do not demangle symbol names (default).
136.It Fl -no-sort
137Do not sort symbols.
138.It Fl -numeric-sort
139Sort symbols numerically by address instead of alphabetically by name.
140.It Fl -print-armap
141For
142.Xr ar 1
143archives, include the index of the archive's members.
144.It Fl -print-file-name
145Write the full pathname or library name of an object on each line,
146before the rest of the information for a symbol.
147If this option is not specified,
148.Nm
149will only identify an input file once, before its symbols are
150listed.
151.It Fl -print-size
152Print the size of each symbol instead of its value.
153.It Fl -radix Ns = Ns Ar radix
154Print numeric values using the specified radix.
155Supported values for argument
156.Ar radix
157are
158.Sq d
159for decimal,
160.Sq o
161for octal, and
162.Sq x
163for hexadecimal.
164.It Fl -reverse-sort
165Reverse the order of the sort.
166.It Fl -size-sort
167Sort symbols by size instead of alphabetically by name.
168.It Fl -undefined-only
169Display only undefined symbols.
170.It Fl -version
171Display the version identifier for
172.Nm
173and exit.
174.It Fl A
175Equivalent to specifying option
176.Fl -print-file-name .
177.It Fl B
178Equivalent to specifying option
179.Fl -format= Ns Ar bsd .
180.It Fl C Op Ar style
181Equivalent to specifying option
182.Fl -demangle Ns Op = Ns Ar style .
183.It Fl D
184Equivalent to specifying option
185.Fl -dynamic .
186.It Fl F Ar format
187Equivalent to specifying option
188.Fl -format Ns = Ns Ar format .
189.It Fl P
190Equivalent to specifying option
191.Fl -format Ns = Ns Ar posix .
192.It Fl S
193Equivalent to specifying option
194.Fl -print-size .
195.It Fl V
196Equivalent to specifying option
197.Fl -version .
198.It Fl a
199Equivalent to specifying option
200.Fl -debug-syms .
201.It Fl e
202Only display information for global and static symbols.
203.It Fl f
204Produce full output (default).
205.It Fl g
206Equivalent to specifying option
207.Fl -extern-only .
208.It Fl h
209Equivalent to specifying option
210.Fl -help .
211.It Fl l
212Equivalent to specifying option
213.Fl -line-numbers .
214.It Fl n
215Equivalent to specifying option
216.Fl -numeric-sort .
217.It Fl o
218If POSIX output was specified using the
219.Fl F Ar posix
220or
221.Fl P
222options, this option is equivalent to specifying
223.Fl -radix Ns = Ns Sq Ar o .
224If POSIX output was not specified, this option
225acts as a synonym for the
226.Fl -print-file-name
227option.
228.It Fl p
229Equivalent to specifying option
230.Fl -no-sort .
231.It Fl v
232Equivalent to option
233.Fl n .
234.It Fl r
235Equivalent to specifying option
236.Fl -reverse-sort
237.It Fl s
238Equivalent to specifying option
239.Fl -print-armap .
240.It Fl t Ar radix
241Equivalent to specifying option
242.Fl -radix= Ns Ar radix .
243.It Fl u
244Equivalent to specifying option
245.Fl -undefined-only .
246.It Fl x
247Write numeric values in hexadecimal (equivalent to -t x).
248.El
249.Sh OUTPUT FORMAT
250.Pp
251The
252.Nm
253utility can present its information in a number of formats, numeric
254radices and sort orders.
255By default
256.Nm
257uses BSD style output, a hexadecimal radix, without output sorted
258alphabetically by name and without demangling of names.
259.Pp
260For each symbol listed,
261.Nm
262presents the following information:
263.Bl -bullet -compact
264.It
265The library or object name, if options
266.Fl A
267or
268.Fl -print-file-name
269were specified.
270.It
271The symbol name.
272.It
273The type of the symbol denoted by a single character as below:
274.Bl -tag -compact -width indent
275.It A
276A global, absolute symbol.
277.It B
278A global
279.Dq bss
280(uninitialized data) symbol.
281.It C
282A
283.Dq common
284symbol, representing uninitialized data.
285.It D
286A global symbol naming initialized data.
287.It N
288A debugger symbol.
289.It R
290A read-only data symbol.
291.It T
292A global text symbol.
293.It U
294An undefined symbol.
295.It V
296A weak object.
297.It W
298A weak reference.
299.It a
300A local absolute symbol.
301.It b
302A local
303.Dq bss
304(uninitialized data) symbol.
305.It d
306A local data symbol.
307.It t
308A local text symbol.
309.It v
310A weak object that is undefined.
311.It w
312A weak symbol that is undefined.
313.It ?
314None of the above.
315.El
316.It
317The value of the symbol.
318.It
319The size of the symbol if applicable.
320.It
321Line number information, if available and if options
322.Fl l
323or
324.Fl -line-numbers
325were specified.
326.El
327.Sh EXIT STATUS
328.Ex -std
329.Sh SEE ALSO
330.Xr ar 1 ,
331.Xr objdump 1 ,
332.Xr ranlib 1 ,
333.Xr elf 3
334.Sh AUTHORS
335The
336.Nm
337utility and this manual page were written by
338.An Hyogeol Lee Aq Mt hyogeollee@gmail.com .
339