path: root/usr/src/man/man1/nm.1

'\" te
.\" Copyright 1989 AT&T
.\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
.\"  This notice shall appear on any product containing this material.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH NM 1 "Sep 10, 2013"
.SH NAME
nm \- print name list of an object file
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/nm\fR [\fB-ACDhlnPprRsTuVv\fR] [\fB-efox\fR] [\fB-g\fR | \fB-u\fR]
     [\fB-t\fR \fIformat\fR] \fIfile\fR...
.fi

.LP
.nf
\fB/usr/xpg4/bin/nm\fR [\fB-ACDhlnPprRsTuVv\fR] [\fB-efox\fR] [\fB-g\fR | \fB-u\fR]
     [\fB-t\fR \fIformat\fR] \fIfile\fR...
.fi

.SH DESCRIPTION
.sp
.LP
The \fBnm\fR utility displays the symbol table of each \fBELF\fR object file
that is specified by \fIfile\fR.
.sp
.LP
If no symbolic information is available for a valid input file, the \fBnm\fR
utility reports that fact, but not consider it an error condition.
.SH OPTIONS
.sp
.LP
The output of \fBnm\fR can be controlled using the following options:
.sp
.ne 2
.na
\fB\fB-A\fR\fR
.ad
.RS 13n
Writes the full path name or library name of an object on each line.
.RE

.sp
.ne 2
.na
\fB\fB-C\fR\fR
.ad
.RS 13n
Demangles C++ symbol names before printing them out.
.RE

.sp
.ne 2
.na
\fB\fB-D\fR\fR
.ad
.RS 13n
Displays the \fBSHT_DYNSYM\fR symbol information. This is the symbol table used
by \fBld.so.1\fR and is present even in stripped dynamic executables. If
\fB-D\fR is not specified, the default behavior is to display the
\fBSHT_SYMTAB\fR symbol information.
.RE

.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 13n
See NOTES below.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 13n
See NOTES below.
.RE

.sp
.ne 2
.na
\fB\fB-g\fR\fR
.ad
.RS 13n
Writes only external (global) symbol information.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.RS 13n
Does not display the output heading data.
.RE

.sp
.ne 2
.na
\fB\fB-L\fR\fR
.ad
.RS 13n
Displays the \fBSHT_SUNW_LDYNSYM\fR symbol information. This symbol table
contains local function symbols. \fBSHT_SUNW_LDYNSM\fR symbol tables are
present even in stripped dynamic executables. These symbols augment the global
symbols that are found in \fBSHT_DYNSYM\fR symbol table. If \fB-L\fR is not
specified, the default behavior is to display the \fBSHT_SYMTAB\fR symbol
information.
.RE

.sp
.ne 2
.na
\fB\fB-l\fR\fR
.ad
.RS 13n
Distinguishes between \fBWEAK\fR and \fBGLOBAL\fR symbols by appending a * to
the key letter for \fBWEAK\fR symbols.
.RE

.sp
.ne 2
.na
\fB\fB-n\fR\fR
.ad
.RS 13n
Sorts external symbols by name before they are printed.
.RE

.sp
.ne 2
.na
\fB\fB-o\fR\fR
.ad
.RS 13n
Prints the value and size of a symbol in octal instead of decimal (equivalent
to \fB-t\fR \fBo\fR).
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 13n
Produces easy to parse, terse output. Each symbol name is preceded by its value
(blanks if undefined) and one of the letters:
.sp
.ne 2
.na
\fB\fBA\fR\fR
.ad
.RS 5n
Absolute symbol.
.RE

.sp
.ne 2
.na
\fB\fBB\fR\fR
.ad
.RS 5n
bss (uninitialized data space) symbol.
.RE

.sp
.ne 2
.na
\fB\fBC\fR\fR
.ad
.RS 5n
COMMON symbol.
.RE

.sp
.ne 2
.na
\fB\fBD\fR\fR
.ad
.RS 5n
Data object symbol.
.RE

.sp
.ne 2
.na
\fB\fBF\fR\fR
.ad
.RS 5n
File symbol.
.RE

.sp
.ne 2
.na
\fB\fBN\fR\fR
.ad
.RS 5n
Symbol has no type.
.RE

.sp
.ne 2
.na
\fB\fBL\fR\fR
.ad
.RS 5n
Thread-Local storage symbol.
.RE

.sp
.ne 2
.na
\fB\fBS\fR\fR
.ad
.RS 5n
Section symbol.
.RE

.sp
.ne 2
.na
\fB\fBT\fR\fR
.ad
.RS 5n
Text symbol.
.RE

.sp
.ne 2
.na
\fB\fBU\fR\fR
.ad
.RS 5n
Undefined.
.RE

If the symbol's binding attribute is:
.sp
.ne 2
.na
\fB\fBLOCAL\fR\fR
.ad
.RS 10n
The key letter is lower case.
.RE

.sp
.ne 2
.na
\fB\fBWEAK\fR\fR
.ad
.RS 10n
The key letter is upper case. If the \fB-l\fR modifier is specified, the upper
case key letter is followed by a \fB*\fR
.RE

.sp
.ne 2
.na
\fB\fBGLOBAL\fR\fR
.ad
.RS 10n
The key letter is upper case.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.RS 13n
Writes information in a portable output format, as specified in \fBStandard
Output\fR.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 13n
Prepends the name of the object file or archive to each output line.
.RE

.sp
.ne 2
.na
\fB\fB-R\fR\fR
.ad
.RS 13n
Prints the archive name (if present), followed by the object file and symbol
name. If the \fB-r\fR option is also specified, this option is ignored.
.RE

.sp
.ne 2
.na
\fB\fB-s\fR\fR
.ad
.RS 13n
Prints section name instead of section index.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR \fIformat\fR\fR
.ad
.RS 13n
Writes each numeric value in the specified format. The format is dependent on
the single character used as the \fIformat\fR option-argument:
.sp
.ne 2
.na
\fB\fBd\fR\fR
.ad
.RS 5n
The offset is written in decimal (default).
.RE

.sp
.ne 2
.na
\fB\fBo\fR\fR
.ad
.RS 5n
The offset is written in octal.
.RE

.sp
.ne 2
.na
\fB\fBx\fR\fR
.ad
.RS 5n
The offset is written in hexadecimal.
.RE

.RE

.sp
.ne 2
.na
\fB\fB-T\fR\fR
.ad
.RS 13n
See \fBNOTES\fR.
.RE

.SS "/usr/bin/nm"
.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.RS 6n
Prints undefined symbols only.
.RE

.SS "/usr/xpg4/bin/nm"
.sp
.ne 2
.na
\fB\fB-u\fR\fR
.ad
.RS 6n
Prints long listing for each undefined symbol. See \fBOUTPUT\fR below.
.RE

.sp
.ne 2
.na
\fB\fB-v\fR\fR
.ad
.RS 6n
Sorts external symbols by value before they are printed.
.RE

.sp
.ne 2
.na
\fB\fB-V\fR\fR
.ad
.RS 6n
Prints the version of the \fBnm\fR command executing on the standard error
output.
.RE

.sp
.ne 2
.na
\fB\fB-x\fR\fR
.ad
.RS 6n
Prints the value and size of a symbol in hexadecimal instead of decimal
(equivalent to \fB-t\fR \fBx\fR).
.RE

.sp
.LP
Options can be used in any order, either singly or in combination, and can
appear anywhere in the command line. When conflicting options are specified
(such as \fB-v\fR and \fB-n\fR, or \fB-o\fR and \fB-x\fR) the first is taken
and the second ignored with a warning message to the user. (See \fB-R\fR for
exception.)
.SH OPERANDS
.sp
.LP
The following operand is supported:
.sp
.ne 2
.na
\fB\fIfile\fR\fR
.ad
.RS 8n
A path name of an object file, executable file or object-file library.
.RE

.SH OUTPUT
.sp
.LP
This section describes the \fBnm\fR utility's output options.
.SS "Standard Output"
.sp
.LP
For each symbol, the following information is printed:
.sp
.ne 2
.na
\fB\fBIndex\fR\fR
.ad
.RS 15n
The index of the symbol. (The index appears in brackets.)
.RE

.sp
.ne 2
.na
\fB\fBValue\fR\fR
.ad
.RS 15n
The value of the symbol is one of the following:
.RS +4
.TP
.ie t \(bu
.el o
A section offset for defined symbols in a relocatable file.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Alignment constraints for symbols whose section index is \fBSHN_COMMON\fR.
.RE
.RS +4
.TP
.ie t \(bu
.el o
A virtual address in executable and dynamic library files.
.RE
.RE

.sp
.ne 2
.na
\fB\fBSize\fR\fR
.ad
.RS 15n
The size in bytes of the associated object.
.RE

.sp
.ne 2
.na
\fB\fBType\fR\fR
.ad
.RS 15n
A symbol is of one of the following types:
.sp
.ne 2
.na
\fB\fBNOTYPE\fR\fR
.ad
.RS 11n
No type was specified.
.RE

.sp
.ne 2
.na
\fB\fBOBJECT\fR\fR
.ad
.RS 11n
A data object such as an array or variable.
.RE

.sp
.ne 2
.na
\fB\fBFUNC\fR\fR
.ad
.RS 11n
A function or other executable code.
.RE

.sp
.ne 2
.na
\fB\fBREGI\fR\fR
.ad
.RS 11n
A register symbol (\fBSPARC\fR only).
.RE

.sp
.ne 2
.na
\fB\fBSECTION\fR\fR
.ad
.RS 11n
A section symbol.
.RE

.sp
.ne 2
.na
\fB\fBFILE\fR\fR
.ad
.RS 11n
Name of the source file.
.RE

.sp
.ne 2
.na
\fB\fBCOMMON\fR\fR
.ad
.RS 11n
An uninitialized common block.
.RE

.sp
.ne 2
.na
\fB\fBTLS\fR\fR
.ad
.RS 11n
A variable associated with Thread-Local storage.
.RE

.RE

.sp
.ne 2
.na
\fB\fBBind\fR\fR
.ad
.RS 15n
The symbol's binding attributes.
.sp
.ne 2
.na
\fB\fBLOCAL symbols\fR\fR
.ad
.RS 18n
Have a scope limited to the object file containing their definition.
.RE

.sp
.ne 2
.na
\fB\fBGLOBAL symbols\fR\fR
.ad
.RS 18n
Are visible to all object files being combined.
.RE

.sp
.ne 2
.na
\fB\fBWEAK symbols\fR\fR
.ad
.RS 18n
Are essentially global symbols with a lower precedence than \fBGLOBAL\fR.
.RE

.RE

.sp
.ne 2
.na
\fB\fBOther\fR\fR
.ad
.RS 15n
A symbol's visibility.
.sp
The lower bits of the \fBst_other\fR member of the \fBElf32_Sym\fR structure,
and the \fBElf64_Sym\fR structure, defined in \fB<sys/elf.h>\fR, are currently
used and can be one of:
.sp
.in +2
.nf
#define STV_DEFAULT     0
#define STV_INTERNAL    1
#define STV_HIDDEN      2
#define STV_PROTECTED   3
#define STV_EXPORTED    4
#define STV_SINGLETON   5
#define STV_ELIMINATE   6
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fBShndx\fR\fR
.ad
.RS 15n
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:
.sp
.ne 2
.na
\fB\fBABS\fR\fR
.ad
.RS 10n
Indicates the symbol's value does not change through relocation.
.RE

.sp
.ne 2
.na
\fB\fBCOMMON\fR\fR
.ad
.RS 10n
Indicates an unallocated block and the value provides alignment constraints.
.RE

.sp
.ne 2
.na
\fB\fBUNDEF\fR\fR
.ad
.RS 10n
Indicates an undefined symbol.
.RE

.RE

.sp
.ne 2
.na
\fB\fBName\fR\fR
.ad
.RS 15n
The name of the symbol.
.RE

.sp
.ne 2
.na
\fB\fBObject Name\fR\fR
.ad
.RS 15n
The name of the object or library if \fB-A\fR is specified.
.RE

.sp
.LP
If the \fB-P\fR option is specified, the previous information is displayed
using the following portable format. The three versions differ depending on
whether \fB-t\fR \fBd\fR, \fB-t\fR \fBo\fR, or \fB-t\fR \fBx\fR was specified,
respectively:
.sp
.in +2
.nf
\fB"%s%s %s %d %d\n",\fR \fIlibrary/object name\fR, \fIname\fR\fB, type,\fR \fIvalue\fR, \e
     \fBsize "%s%s %s %o %o\en",\fR \fIlibrary/object name\fR, \fIname\fR, \e
     \fBtype,\fR \fIvalue\fR \fB, size "%s%s %s %x %x\en",\fR \fIlibrary/object name\fR, \fIname\fR, \e
     \fBtype,\fR \fIvalue\fR\fB, size\fR
.fi
.in -2
.sp

.sp
.LP
where \fIlibrary/object name\fR is formatted as follows:
.RS +4
.TP
.ie t \(bu
.el o
If \fB-A\fR is not specified, \fIlibrary/object name\fR is an empty string.
.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fB-A\fR is specified and the corresponding \fIfile\fR operand does not name
a library:
.sp
.in +2
.nf
\fB"%s: ", \fIfile\fR\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
.ie t \(bu
.el o
If \fB-A\fR is specified and the corresponding \fIfile\fR operand names a
library. In this case, \fIobject file\fR names the object file in the library
containing the symbol being described:
.sp
.in +2
.nf
\fB"%s[%s]: ", \fIfile\fR, \fIobject file\fR\fR
.fi
.in -2
.sp

.RE
.sp
.LP
If \fB-A\fR is not specified, then if more than one \fIfile\fR operand is
specified or if only one \fIfile\fR operand is specified and it names a
library, \fBnm\fR writes a line identifying the object containing the following
symbols before the lines containing those symbols, in the form:
.RS +4
.TP
.ie t \(bu
.el o
If the corresponding \fIfile\fR operand does not name a library:
.sp
.in +2
.nf
\fB"%s:\en", \fIfile\fR\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
.ie t \(bu
.el o
If the corresponding \fIfile\fR operand names a library; in this case,
\fIobject file\fR is the name of the file in the library containing the
following symbols:
.sp
.in +2
.nf
\fB"%s[%s]:\en", \fIfile\fR, \fIobject file\fR\fR
.fi
.in -2
.sp

.RE
.sp
.LP
If \fB-P\fR is specified, but \fB-t\fR is not, the format is as if \fB-t\fR
\fBx\fR had been specified.
.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBnm\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_COLLATE\fR, \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.SH /USR/XPG4/BIN/NM
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBar\fR(1), \fBas\fR(1), \fBdump\fR(1), \fBld\fR(1), \fBld.so.1\fR(1),
\fBar.h\fR(3HEAD), \fBa.out\fR(4), \fBattributes\fR(5), \fBenviron\fR(5),
\fBstandards\fR(5)
.SH NOTES
.sp
.LP
The following options are obsolete because of changes to the object file format
and might be deleted in a future release.
.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 6n
Prints 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 \fBcc\fR
\fB-g\fR, which can be examined using \fBdump\fR(1).
.RE

.sp
.ne 2
.na
\fB\fB-f\fR\fR
.ad
.RS 6n
Produces full output. Redundant symbols (such as \fB\&.text\fR, \fB\&.data\fR,
and so forth), which existed previously, do not exist and producing full output
is identical to the default output.
.RE

.sp
.ne 2
.na
\fB\fB-T\fR\fR
.ad
.RS 6n
By default, \fBnm\fR 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.
.RE