diff options
Diffstat (limited to 'man1p/nm.1p')
| -rw-r--r-- | man1p/nm.1p | 392 |
1 files changed, 392 insertions, 0 deletions
diff --git a/man1p/nm.1p b/man1p/nm.1p new file mode 100644 index 000000000..20a1dbb64 --- /dev/null +++ b/man1p/nm.1p @@ -0,0 +1,392 @@ +.\" 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 . |