diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/nm.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/nm.1p | 413 |
1 files changed, 413 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/nm.1p b/man-pages-posix-2017/man1p/nm.1p new file mode 100644 index 0000000..d4fed31 --- /dev/null +++ b/man-pages-posix-2017/man1p/nm.1p @@ -0,0 +1,413 @@ +'\" et +.TH NM "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +nm +\(em write the name list of an object file (\fBDEVELOPMENT\fP) +.SH SYNOPSIS +.LP +.nf +nm \fB[\fR-APv\fB] [\fR-g|-u\fB] [\fR-t \fIformat\fB] \fIfile\fR... +nm \fB[\fR-APv\fB] [\fR-efox\fB] [\fR-g|-u\fB] [\fR-t \fIformat\fB]\fI file\fR... +.fi +.SH DESCRIPTION +The +.IR nm +utility shall display symbolic information appearing in the object +file, executable file, or object-file library named by +.IR file . +If no symbolic information is available for a valid input file, the +.IR nm +utility shall report that fact, but not consider it an error +condition. +.P +The default base used when numeric values are written is unspecified. +On XSI-conformant systems, it shall be decimal if the +.BR \-P +option is not specified. +.SH OPTIONS +The +.IR nm +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-A\fP" 10 +Write the full pathname or library name of an object on each line. +.IP "\fB\-e\fP" 10 +Write only external (global) and static symbol information. +.IP "\fB\-f\fP" 10 +Produce full output. Write redundant symbols (\c +.BR .text , +.BR .data , +and +.BR .bss ), +normally suppressed. +.IP "\fB\-g\fP" 10 +Write only external (global) symbol information. +.IP "\fB\-o\fP" 10 +Write numeric values in octal (equivalent to +.BR "\-t\ o" ). +.IP "\fB\-P\fP" 10 +Write information in a portable output format, as specified in the +STDOUT section. +.IP "\fB\-t\ \fIformat\fR" 10 +Write each numeric value in the specified format. The format shall be +dependent on the single character used as the +.IR format +option-argument: +.RS 10 +.IP "\fRd\fR" 6 +decimal +(default if +.BR \-P +is not specified). +.IP "\fRo\fR" 6 +octal. +.IP "\fRx\fR" 6 +hexadecimal (default if +.BR \-P +is specified). +.RE +.IP "\fB\-u\fP" 10 +Write only undefined symbols. +.IP "\fB\-v\fP" 10 +Sort output by value instead of by symbol name. +.IP "\fB\-x\fP" 10 +Write numeric values in hexadecimal (equivalent to +.BR "\-t\ x" ). +.SH OPERANDS +The following operand shall be supported: +.IP "\fIfile\fR" 10 +A pathname of an object file, executable file, or object-file library. +.SH STDIN +See the INPUT FILES section. +.SH "INPUT FILES" +The input file shall be an object file, an object-file library whose +format is the same as those produced by the +.IR ar +utility for link editing, or an executable file. The +.IR nm +utility may accept additional implementation-defined object library +formats for the input file. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR nm : +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_COLLATE\fP" 10 +.br +Determine the locale for character collation information for the +symbol-name and symbol-value collation sequences. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If symbolic information is present in the input files, then for each +file or for each member of an archive, the +.IR nm +utility shall write the following information to standard output. By +default, the format is unspecified, but the output shall be sorted by +symbol name according to the collation sequence in the current locale. +.IP " *" 4 +Library or object name, if +.BR \-A +is specified +.IP " *" 4 +Symbol name +.IP " *" 4 +Symbol type, which shall either be one of the following single +characters or an implementation-defined type represented by a single +character: +.RS 4 +.IP "\fRA\fR" 6 +Global absolute symbol. +.IP "\fRa\fR" 6 +Local absolute symbol. +.IP "\fRB\fR" 6 +Global ``bss'' (that is, uninitialized data space) symbol. +.IP "\fRb\fR" 6 +Local bss symbol. +.IP "\fRD\fR" 6 +Global data symbol. +.IP "\fRd\fR" 6 +Local data symbol. +.IP "\fRT\fR" 6 +Global text symbol. +.IP "\fRt\fR" 6 +Local text symbol. +.IP "\fRU\fR" 6 +Undefined symbol. +.RE +.IP " *" 4 +Value of the symbol +.IP " *" 4 +The size associated with the symbol, if applicable +.P +This information may be supplemented by additional information specific +to the implementation. +.P +If the +.BR \-P +option is specified, the previous information shall be displayed using +the following portable format. The three versions differ depending on +whether +.BR "\-t\ d" , +.BR "\-t\ o" , +or +.BR "\-t\ x" +was specified, respectively: +.sp +.RS 4 +.nf + +"%s%s %s %d %d\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.P +"%s%s %s %o %o\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.P +"%s%s %s %x %x\en", <\fIlibrary/object name\fR>, <\fIname\fR>, <\fItype\fR>, + <\fIvalue\fR>, <\fIsize\fR> +.fi +.P +.RE +where <\fIlibrary/object\ name\fP> shall be formatted as follows: +.IP " *" 4 +If +.BR \-A +is not specified, <\fIlibrary/object\ name\fP> shall be an empty string. +.IP " *" 4 +If +.BR \-A +is specified and the corresponding +.IR file +operand does not name a library: +.RS 4 +.sp +.RS 4 +.nf + +"%s: ", <\fIfile\fR> +.fi +.P +.RE +.RE +.IP " *" 4 +If +.BR \-A +is specified and the corresponding +.IR file +operand names a library. In this case, <\fIobject\ file\fP> shall name +the object file in the library containing the symbol being described: +.RS 4 +.sp +.RS 4 +.nf + +"%s[%s]: ", <\fIfile\fR>, <\fIobject file\fR> +.fi +.P +.RE +.RE +.P +If +.BR \-A +is not specified, then if more than one +.IR file +operand is specified or if only one +.IR file +operand is specified and it names a library, +.IR nm +shall write a line identifying the object containing the following +symbols before the lines containing those symbols, in the form: +.IP " *" 4 +If the corresponding +.IR file +operand does not name a library: +.RS 4 +.sp +.RS 4 +.nf + +"%s:\en", <\fIfile\fR> +.fi +.P +.RE +.RE +.IP " *" 4 +If the corresponding +.IR file +operand names a library; in this case, <\fIobject\ file\fP> shall be +the name of the file in the library containing the following symbols: +.RS 4 +.sp +.RS 4 +.nf + +"%s[%s]:\en", <\fIfile\fR>, <\fIobject file\fR> +.fi +.P +.RE +.RE +.P +If +.BR \-P +is specified, but +.BR \-t +is not, the format shall be as if +.BR "\-t\ x" +had been specified. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +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 +None. +.SH RATIONALE +Historical implementations of +.IR nm +have used different bases for numeric output and supplied different +default types of symbols that were reported. The +.BR \-t +.IR format +option, similar to that used in +.IR od +and +.IR strings , +can be used to specify the numeric base; +.BR \-g +and +.BR \-u +can be used to restrict the amount of output or the types of symbols +included in the output. +.P +The compromise of using +.BR \-t +.IR format +\fIversus\fP using +.BR \-d , +.BR \-o , +and other similar options was necessary because of differences in the +meaning of +.BR \-o +between implementations. The +.BR \-o +option from BSD has been provided here as +.BR \-A +to avoid confusion with the +.BR \-o +from System V (which has been provided here as +.BR \-t +and as +.BR \-o +on XSI-conformant systems). +.P +The option list was significantly reduced from that provided by +historical implementations. +.P +The +.IR nm +description is a subset of both the System V and BSD +.IR nm +utilities with no specified default output. +.P +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 +.IR nm +during software development was judged to outweigh other limitations. +.P +The default output format of +.IR nm +is not specified because of differences in historical implementations. +The +.BR \-P +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. +.P +The format given in +.IR nm +STDOUT uses +<space> +characters between the fields, which may be any number of +<blank> +characters 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" +None. +.SH "SEE ALSO" +.IR "\fIar\fR\^", +.IR "\fIc99\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |