mirror of https://github.com/mkerrisk/man-pages
393 lines
11 KiB
Groff
393 lines
11 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "NM" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" nm
|
|
.SH NAME
|
|
nm \- write the name list of an object file (\fBDEVELOPMENT\fP)
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBnm\fP \fB[\fP\fB-APv\fP\fB][\fP\fB-efox\fP\fB][\fP \fB-g| -u\fP\fB][\fP\fB-t\fP
|
|
\fIformat\fP\fB]\fP \fIfile\fP\fB... \fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
This utility shall be provided on systems that support both the User
|
|
Portability Utilities option and the Software Development
|
|
Utilities option. On other systems it is optional. Certain options
|
|
are only available on XSI-conformant systems.
|
|
.LP
|
|
The \fInm\fP utility shall display symbolic information appearing
|
|
in the object file, executable file, or object-file library
|
|
named by \fIfile\fP. If no symbolic information is available for a
|
|
valid input file, the \fInm\fP utility shall report that fact,
|
|
but not consider it an error condition.
|
|
.LP
|
|
The default base used when numeric values are written is unspecified.
|
|
\ On XSI-conformant systems, it shall be decimal.
|
|
.SH OPTIONS
|
|
.LP
|
|
The \fInm\fP utility shall conform to the Base Definitions volume
|
|
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
|
|
.LP
|
|
The following options shall be supported:
|
|
.TP 7
|
|
\fB-A\fP
|
|
Write the full pathname or library name of an object on each line.
|
|
.TP 7
|
|
\fB-e\fP
|
|
Write only external (global) and static symbol information.
|
|
.TP 7
|
|
\fB-f\fP
|
|
Produce full output. Write redundant symbols ( \fB.text\fP, \fB.data\fP,
|
|
and \fB.bss\fP), normally suppressed.
|
|
.TP 7
|
|
\fB-g\fP
|
|
Write only external (global) symbol information.
|
|
.TP 7
|
|
\fB-o\fP
|
|
Write numeric values in octal (equivalent to \fB-t\ o\fP).
|
|
.TP 7
|
|
\fB-P\fP
|
|
Write information in a portable output format, as specified in the
|
|
STDOUT section.
|
|
.TP 7
|
|
\fB-t\ \fP \fIformat\fP
|
|
Write each numeric value in the specified format. The format shall
|
|
be dependent on the single character used as the
|
|
\fIformat\fP option-argument:
|
|
.TP 7
|
|
\fBd\fP
|
|
.RS
|
|
The offset is written in decimal \ (default).
|
|
.RE
|
|
.TP 7
|
|
\fBo\fP
|
|
.RS
|
|
The offset is written in octal.
|
|
.RE
|
|
.TP 7
|
|
\fBx\fP
|
|
.RS
|
|
The offset is written in hexadecimal.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
\fB-u\fP
|
|
Write only undefined symbols.
|
|
.TP 7
|
|
\fB-v\fP
|
|
Sort output by value instead of alphabetically.
|
|
.TP 7
|
|
\fB-x\fP
|
|
Write numeric values in hexadecimal (equivalent to \fB-t\ x\fP).
|
|
.sp
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operand shall be supported:
|
|
.TP 7
|
|
\fIfile\fP
|
|
A pathname of an object file, executable file, or object-file library.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
See the INPUT FILES section.
|
|
.SH INPUT FILES
|
|
.LP
|
|
The input file shall be an object file, an object-file library whose
|
|
format is the same as those produced by the \fIar\fP utility for link
|
|
editing, or an executable file. The \fInm\fP utility may accept additional
|
|
implementation-defined object library formats for the input file.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fInm\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
Provide a default value for the internationalization variables that
|
|
are unset or null. (See the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
|
|
for
|
|
the precedence of internationalization variables used to determine
|
|
the values of locale categories.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_COLLATE\fP
|
|
.sp
|
|
Determine the locale for character collation information for the symbol-name
|
|
and symbol-value collation sequences.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
Determine the locale for the interpretation of sequences of bytes
|
|
of text data as characters (for example, single-byte as
|
|
opposed to multi-byte characters in arguments).
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Determine the locale that should be used to affect the format and
|
|
contents of diagnostic messages written to standard
|
|
error.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.LP
|
|
If symbolic information is present in the input files, then for each
|
|
file or for each member of an archive, the \fInm\fP
|
|
utility shall write the following information to standard output.
|
|
By default, the format is unspecified, but the output shall be
|
|
sorted alphabetically by symbol name:
|
|
.IP " *" 3
|
|
Library or object name, if \fB-A\fP is specified
|
|
.LP
|
|
.IP " *" 3
|
|
Symbol name
|
|
.LP
|
|
.IP " *" 3
|
|
Symbol type, which shall either be one of the following single characters
|
|
or an implementation-defined type represented by a
|
|
single character:
|
|
.TP 7
|
|
\fBA\fP
|
|
.RS
|
|
Global absolute symbol.
|
|
.RE
|
|
.TP 7
|
|
\fBa\fP
|
|
.RS
|
|
Local absolute symbol.
|
|
.RE
|
|
.TP 7
|
|
\fBB\fP
|
|
.RS
|
|
Global "bss" (that is, uninitialized data space) symbol.
|
|
.RE
|
|
.TP 7
|
|
\fBb\fP
|
|
.RS
|
|
Local bss symbol.
|
|
.RE
|
|
.TP 7
|
|
\fBD\fP
|
|
.RS
|
|
Global data symbol.
|
|
.RE
|
|
.TP 7
|
|
\fBd\fP
|
|
.RS
|
|
Local data symbol.
|
|
.RE
|
|
.TP 7
|
|
\fBT\fP
|
|
.RS
|
|
Global text symbol.
|
|
.RE
|
|
.TP 7
|
|
\fBt\fP
|
|
.RS
|
|
Local text symbol.
|
|
.RE
|
|
.TP 7
|
|
\fBU\fP
|
|
.RS
|
|
Undefined symbol.
|
|
.RE
|
|
.sp
|
|
.LP
|
|
.IP " *" 3
|
|
Value of the symbol
|
|
.LP
|
|
.IP " *" 3
|
|
The size associated with the symbol, if applicable
|
|
.LP
|
|
.LP
|
|
This information may be supplemented by additional information specific
|
|
to the implementation.
|
|
.LP
|
|
If the \fB-P\fP option is specified, the previous information shall
|
|
be displayed using the following portable format. The three
|
|
versions differ depending on whether \fB-t\ d\fP, \fB-t\ o\fP, or
|
|
\fB-t\ x\fP was specified, respectively:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s%s %s %d %d\\n", <\fP\fIlibrary/object name\fP\fB>, <\fP\fIname\fP\fB>, <\fP\fItype\fP\fB>,
|
|
<\fP\fIvalue\fP\fB>, <\fP\fIsize\fP\fB>
|
|
.sp
|
|
|
|
"%s%s %s %o %o\\n", <\fP\fIlibrary/object name\fP\fB>, <\fP\fIname\fP\fB>, <\fP\fItype\fP\fB>,
|
|
<\fP\fIvalue\fP\fB>, <\fP\fIsize\fP\fB>
|
|
.sp
|
|
|
|
"%s%s %s %x %x\\n", <\fP\fIlibrary/object name\fP\fB>, <\fP\fIname\fP\fB>, <\fP\fItype\fP\fB>,
|
|
<\fP\fIvalue\fP\fB>, <\fP\fIsize\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
where <\fIlibrary/object\ name\fP> shall be formatted as follows:
|
|
.IP " *" 3
|
|
If \fB-A\fP is not specified, <\fIlibrary/object\ name\fP> shall be
|
|
an empty string.
|
|
.LP
|
|
.IP " *" 3
|
|
If \fB-A\fP is specified and the corresponding \fIfile\fP operand
|
|
does not name a library:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s: ", <\fP\fIfile\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.IP " *" 3
|
|
If \fB-A\fP is specified and the corresponding \fIfile\fP operand
|
|
names a library. In this case,
|
|
<\fIobject\ file\fP> shall name the object file in the library containing
|
|
the symbol being described:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s[%s]: ", <\fP\fIfile\fP\fB>, <\fP\fIobject file\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.LP
|
|
If \fB-A\fP is not specified, then if more than one \fIfile\fP operand
|
|
is specified or if only one \fIfile\fP operand is
|
|
specified and it names a library, \fInm\fP shall write a line identifying
|
|
the object containing the following symbols before the
|
|
lines containing those symbols, in the form:
|
|
.IP " *" 3
|
|
If the corresponding \fIfile\fP operand does not name a library:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s:\\n", <\fP\fIfile\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.IP " *" 3
|
|
If the corresponding \fIfile\fP operand names a library; in this case,
|
|
<\fIobject\ file\fP> shall be the name of the
|
|
file in the library containing the following symbols:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB"%s[%s]:\\n", <\fP\fIfile\fP\fB>, <\fP\fIobject file\fP\fB>
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.LP
|
|
If \fB-P\fP is specified, but \fB-t\fP is not, the format shall be
|
|
as if \fB-t\ x\fP had been specified.
|
|
.SH STDERR
|
|
.LP
|
|
The standard error shall be used only for diagnostic messages.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
None.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
None.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
The following exit values shall be returned:
|
|
.TP 7
|
|
\ 0
|
|
Successful completion.
|
|
.TP 7
|
|
>0
|
|
An error occurred.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
Default.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
Mechanisms for dynamic linking make this utility less meaningful when
|
|
applied to an executable file because a dynamically linked
|
|
executable may omit numerous library routines that would be found
|
|
in a statically linked executable.
|
|
.SH EXAMPLES
|
|
.LP
|
|
None.
|
|
.SH RATIONALE
|
|
.LP
|
|
Historical implementations of \fInm\fP have used different bases for
|
|
numeric output and supplied different default types of
|
|
symbols that were reported. The \fB-t\fP \fIformat\fP option, similar
|
|
to that used in \fIod\fP and \fIstrings\fP, can be used to specify
|
|
the numeric
|
|
base; \fB-g\fP and \fB-u\fP can be used to restrict the amount of
|
|
output or the types of symbols included in the output.
|
|
.LP
|
|
The compromise of using \fB-t\fP \fIformat\fP \fIversus\fP using \fB-d\fP,
|
|
\fB-o\fP, and other similar options was
|
|
necessary because of differences in the meaning of \fB-o\fP between
|
|
implementations. The \fB-o\fP option from BSD has been
|
|
provided here as \fB-A\fP to avoid confusion with the \fB-o\fP from
|
|
System V (which has been provided here as \fB-t\fP and as
|
|
\fB-o\fP on XSI-conformant systems).
|
|
.LP
|
|
The option list was significantly reduced from that provided by historical
|
|
implementations.
|
|
.LP
|
|
The \fInm\fP description is a subset of both the System V and BSD
|
|
\fInm\fP utilities with no specified default output.
|
|
.LP
|
|
It was recognized that mechanisms for dynamic linking make this utility
|
|
less meaningful when applied to an executable file
|
|
(because a dynamically linked executable file may omit numerous library
|
|
routines that would be found in a statically linked
|
|
executable file), but the value of \fInm\fP during software development
|
|
was judged to outweigh other limitations.
|
|
.LP
|
|
The default output format of \fInm\fP is not specified because of
|
|
differences in historical implementations. The \fB-P\fP
|
|
option was added to allow some type of portable output format. After
|
|
a comparison of the different formats used in SunOS, BSD,
|
|
SVR3, and SVR4, it was decided to create one that did not match the
|
|
current format of any of these four systems. The format devised
|
|
is easy to parse by humans, easy to parse in shell scripts, and does
|
|
not need to vary depending on locale (because no English
|
|
descriptions are included). All of the systems currently have the
|
|
information available to use this format.
|
|
.LP
|
|
The format given in \fInm\fP STDOUT uses spaces between the fields,
|
|
which may be any number of <blank>s required to align
|
|
the columns. The single-character types were selected to match historical
|
|
practice, and the requirement that implementation
|
|
additions also be single characters made parsing the information easier
|
|
for shell scripts.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIar\fP , \fIc99\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
|
|
Electrical and Electronics Engineers, Inc and The Open Group. In the
|
|
event of any discrepancy between this version 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 .
|