.\" @(#)nm.1 1.29 95/10/09 SMI; from SVr4
.\" Copyright 1989 AT&T
.\" Copyright (c) 1995, Sun Microsystems, Inc.
.\" All Rights Reserved
.\" Portions Copyright (c) 1992, X/Open Company Limited
.\" All Rights Reserved
.TH nm 1 "11 Apr 1995"
.SH NAME
nm \- print name list of an object file
.SH SYNOPSIS
.B /usr/ccs/bin/nm
[
.B \-AChlnPprRsTuVv
] [
.B \-efox
] [
.B \-g
|
.B \-u
]
.if n .ti +5n
[
.BI \-t \0format
]
.IR file .\|.\|.\|
.LP
.B /usr/xpg4/bin/nm
[
.B \-AChlnPprRsTuVv
] [
.B \-efox
] [
.B \-g
|
.B \-u
]
.if n .ti +5n
[
.BI \-t \0format
]
.IR file .\|.\|.\|
.SH AVAILABILITY
.SS /usr/ccs/bin/nm
SUNWbtool
.SS /usr/xpg4/bin/nm
SUNWxcu4
.SH DESCRIPTION
.IX "nm command" "" "\fLnm\fP \(em print name list of an object file"
.IX "programming tools" "print name list of an object file" "" "print name list of an object file \(em \fLnm\fP"
The
.B nm
command
displays the symbol table of each
.SM ELF
object file that is specified by
.IR file .
.LP
If no symbolic
information is available for a valid input file, the
.B nm
utility will report that fact, but not consider it an error condition.
.SH OPTIONS
.LP
The output of
.B nm
may be controlled using the following options:
.LP
.TP 10
.B \-A
Write the full path name or library name of an object on each line.
.TP
.B \-C
Demangle C++ symbol names before printing them out.
.TP
.B \-e
See
.B NOTES
below.
.TP
.B \-f
See
.B NOTES
below.
.TP
.B \-g
Write only external (global) symbol information.
.TP
.B \-h
Do not display the output heading data.
.TP
.B \-l
Distinguish between
.SB WEAK
and
.SB GLOBAL
symbols by appending a * to the key letter for
.BR \s-1WEAK\s0 " symbols."
.TP
.B \-n
Sort external symbols by name before they are printed.
.TP
.B \-o
Print the value and size of a symbol in octal instead of decimal.
(equivalent to
.BR "\-t o" ).
.TP
.B \-p
Produce easy to parse, terse output.
Each symbol name is preceded by its value (blanks if undefined) and one of
the letters:
.LP
.PD 0
.RS 10
.TP
.B A
absolute symbol
.TP
.B B
bss (uninitialized data space) symbol
.TP
.B D
data object symbol
.TP
.B F
file symbol.
.TP
.B N
symbol has no type
.TP
.B S
section symbol
.TP
.B T
text symbol
.TP
.B U
undefined
.RE
.PD
.br
.ne 4
.IP "" 10
If the symbol's binding attribute is:
.LP
.RS 10
.TP 10
.SB LOCAL
the key letter is lower case
.TP
.SB WEAK
the key letter is upper case; if the
.B \-l
modifier is specified, the upper case key letter is followed by a
.BR *
.TP
.SB GLOBAL
the key letter is upper case.
.RE
.PD
.TP 10
.B \-P
Write information in a portable output format, as specified in
.BR "Standard Output" .
.TP
.B \-r
Prepend the name of the object file or archive to each output line.
.TP
.B \-R
Print the archive name (if present), followed by the object file
and symbol name.  If the
.B \-r
option is also specified, this option is ignored.
.TP
.B \-s
Print section name instead of section index.
.TP
.BI \-t \0format
Write each numeric value in the specified format.
The format is dependent on the single
character used as the
.I format
option-argument:
.LP
.PD 0
.RS 10
.TP
.B d
The offset is written in decimal (default).
.TP
.B o
The offset is written in octal.
.TP
.B x
The offset is written in hexadecimal.
.RE
.PD
.TP 10
.B \-T
See
.B NOTES
below.
.sp 1n
.PD 0
.SS /usr/ccs/bin/nm
.TP 10
.B \-u
Print undefined symbols only.
.SS /usr/xpg4/bin/nm
.TP 10
.B \-u
Print long listing for each undefined symbol. See 
.B OUTPUT
below.
.PD
.TP
.B \-v
Sort external symbols by value before they are printed.
.TP
.B \-V
Print the version of the
.B nm
command executing on the standard error output.
.TP
.B \-x
Print the value and size of a symbol in hexadecimal instead of decimal
(equivalent to
.BR "\-t x" ).
.LP
Options may be used in any order, either singly or in combination,
and may appear anywhere in the command line.
When conflicting options are specified (such as
.BR \-v " and " \-n "; and "
.BR \-o " and " \-x )
the first is taken and the second ignored
with a warning message to the user. (See
.B \-R
for exception.)
.SH OPERANDS
The following operand is supported:
.TP 10
.I file
A path name of an object file, executable file or object-file library.
.SH OUTPUT
.SS Standard Output
.LP
For each symbol, the following information will be printed:
.LP
.TP 10
.B Index
The index of the symbol.  (The index appears in brackets.)
.TP
.B Value
The value of the symbol is one of the following:
.LP
.PD 0
.RS 10
.TP 2
\(bu
a section offset for defined symbols in a relocatable file
.TP
\(bu
alignment constraints for symbols whose section index is
.SB SHN_COMMON
.TP
\(bu
a virtual address in executable and dynamic library files.
.RE
.PD
.TP 10
.B Size
The size in bytes of the associated object.
.TP
.B Type
A symbol is of one of the following types:
.LP
.PD 0
.RS 10
.TP 20
.SB NOTYPE
no type was specified
.TP
.SB OBJECT
a data object such as an array or variable
.TP
.SB FUNC
a function or other executable code
.TP
.SB SECTION
a section symbol
.TP
.SB FILE
name of the source file.
.RE
.PD
.TP 10
.B Bind
The symbol's binding attributes.
.LP
.PD 0
.RS 10
.TP 20
.SB LOCAL \s0\f1symbols
have a scope limited to the
object file containing their definition
.TP
.SB GLOBAL \s0\f1symbols
are visible to all object files being combined
.TP
.SB WEAK \s0\f1symbols
are essentially global symbols with
a lower precedence than
.BR \s-1GLOBAL\s0 .
.RE
.PD
.TP 10
.B Other
A field reserved for future use, currently containing
.BR 0 .
.TP
.B Shndx
Except for three special values, this is the section header table index
in relation to which the symbol is defined.
The following special values exist:
.LP
.PD 0
.RS 10
.TP 20
.SB ABS
indicates the symbol's value will not change through relocation
.TP
.SB COMMON
indicates an unallocated block and the value provides alignment
constraints
.TP
.SB UNDEF
indicates an undefined symbol.
.RE
.PD
.TP 10
.B Name
The name of the symbol
.TP
.B Object Name
The name of the object or library if
.B \-A
is specified.
.LP 
If the
.B \-P
option is specified, the previous information is displayed using
the following portable format.
The three versions differ depending on whether
.BR "\-t d" ,
.B "\-t o"
or
.B "\-t x"
was specified, respectively:
.LP
.RS
\f3"%s%s %s %d %d\en",\f1
.RI < "library/object name" >,
.IB name ,
.IB type ,
.IB value ,
.IB size
.sp 1n
\f3"%s%s %s %o %o\en",\f1
.RI < "library/object name" >,
.IB name ,
.IB type ,
.IB value ,
.IB size
.sp 1n
\f3"%s%s %s %x %x\en",\f1
.RI < "library/object name" >,
.IB name ,
.IB type ,
.IB value ,
.I size
.sp 1n
.RE
where
.RI < "library/object name" >
is formatted as follows:
.LP
.RS
.TP 2
\(bu
If
.B \-A
is not specified,
.RI < "library/object name" >
is an empty string.
.TP
\(bu
If
.B \-A
is specified and the corresponding
.I file
operand does not name a library:
.LP
.RS +5
\f3"%s: ",\f1
.I file
.RE
.TP 2
\(bu
If
.B \-A
is specified and the corresponding
.I file
operand names a library.
In this case,
.RI < "object file" >
names the object file
in the library containing the symbol being described:
.if n .LP
.RS +5
\f3"%s[%s]: ",\f1
.IB file ,
.RI < "object file" >
.RE
.RE
.LP 
If
.B \-A
is not specified, then if more than one
.I file
operand is
specified or if only one
.I file
operand is specified and it names
a library,
.B nm
will write a line identifying the object containing the following
symbols before the lines containing those
symbols, in the form:
.LP
.RS
.TP 2
\(bu
If the corresponding
.I file
operand does not name a library:
.LP
.RS +5
\f3"%s:\en",\f1
.I file
.RE
.TP 2
\(bu
If the corresponding
.I file
operand names a library; in this case,
.RI  < "object file" >
is the name of the file in the library containing the following symbols:
.LP
.RS +5
.fi
\f3"%s[%s]:\en",\f1
.IB file ,
.RI < "object file" >
.RE
.RE
.LP 
If
.B \-P
is specified, but
.B \-t
is not, the format is as if
.B "\-t x"
had been specified.
.SH ENVIRONMENT
See
.BR environ (5)
for descriptions of the following environment variables that affect the
execution of
.BR nm :
.BR \s-1LC_COLLATE\s0\f1 ,
.BR \s-1LC_CTYPE\s0\f1 ,
.BR \s-1LC_MESSAGES\s0\f1 ,
and
.BR \s-1NLSPATH\s0\f1 .
.SH "EXIT STATUS"
The following exit values are returned:
.PD 0
.TP 10
.B 0
Successful completion.
.TP
.B >0
An error occurred.
.PD
.SH "SEE ALSO"
.BR ar (1),
.BR as (1),
.BR dump (1),
.BR ld (1),
.BR a.out (4),
.BR ar (4),
.BR environ (5)
.SH NOTES
.LP
The following options are obsolete because of
changes to the object file format and will be
deleted in a future release.
.LP
.TP 10
.B \-e
Print only external and static symbols.
The symbol table now contains only static
and external symbols.
Automatic symbols no longer appear in the symbol table.
They do appear in the debugging information
produced by
.BR "cc \-g" ,
which may be examined using
.BR dump (1).
.TP
.B \-f
Produce full output.
Redundant symbols (such as .text, .data, and so forth). which
existed previously do not exist and producing full
output will be identical to the default output.
.TP
.B \-T
By default,
.B nm
prints the entire name of the symbols listed.
Since symbol names have been moved to the last column,
the problem of overflow is removed and it is no longer necessary to truncate
the symbol name.
