# nm

## 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.
    


## NAME



           nm — write the name list of an object file (**DEVELOPMENT**)
    


## SYNOPSIS



           nm **[** -APv**] [** -g|-u**] [** -t _format_**]**_file_...
           nm **[** -APv**] [** -efox**] [** -g|-u**] [** -t _format_**]**_file_...
    


## DESCRIPTION



           The _nm_ utility shall display symbolic information appearing in the
           object file, executable file, or object-file library named by
           _file_.  If no symbolic information is available for a valid input
           file, the _nm_ utility shall report that fact, but not consider it
           an error condition.
    
           The default base used when numeric values are written is
           unspecified.  On XSI-conformant systems, it shall be decimal if
           the **-P** option is not specified.
    


## OPTIONS



           The _nm_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.
    
           The following options shall be supported:
    
           **-A** Write the full pathname or library name of an object on
                     each line.
    
           **-e** Write only external (global) and static symbol
                     information.
    
           **-f** Produce full output. Write redundant symbols (**.text** ,
                     **.data** , and **.bss**), normally suppressed.
    
           **-g** Write only external (global) symbol information.
    
           **-o** Write numeric values in octal (equivalent to **-t o**).
    
           **-P** Write information in a portable output format, as
                     specified in the STDOUT section.
    
           **-t** _format_ Write each numeric value in the specified format. The
                     format shall be dependent on the single character used
                     as the _format_ option-argument:
    
                     d     decimal (default if **-P** is not specified).
    
                     o     octal.
    
                     x     hexadecimal (default if **-P** is specified).
    
           **-u** Write only undefined symbols.
    
           **-v** Sort output by value instead of by symbol name.
    
           **-x** Write numeric values in hexadecimal (equivalent to
                     **-t x**).
    


## OPERANDS



           The following operand shall be supported:
    
           _file_      A pathname of an object file, executable file, or
                     object-file library.
    


## STDIN



           See the INPUT FILES section.
    


## INPUT FILES



           The input file shall be an object file, an object-file library
           whose format is the same as those produced by the _ar_ utility for
           link editing, or an executable file. The _nm_ utility may accept
           additional implementation-defined object library formats for the
           input file.
    


## ENVIRONMENT VARIABLES



           The following environment variables shall affect the execution of
           _nm_ :
    
           _LANG_      Provide a default value for the internationalization
                     variables that are unset or null. (See the Base
                     Definitions volume of POSIX.1‐2017, _Section 8.2_ ,
                     _Internationalization Variables_ for the precedence of
                     internationalization variables used to determine the
                     values of locale categories.)
    
           _LC_ALL_    If set to a non-empty string value, override the values
                     of all the other internationalization variables.
    
           _LC_COLLATE_
                     Determine the locale for character collation information
                     for the symbol-name and symbol-value collation
                     sequences.
    
           _LC_CTYPE_  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).
    
           _LC_MESSAGES_
                     Determine the locale that should be used to affect the
                     format and contents of diagnostic messages written to
                     standard error.
    
           _NLSPATH_   Determine the location of message catalogs for the
                     processing of _LC_MESSAGES_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           If symbolic information is present in the input files, then for
           each file or for each member of an archive, the _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.
    
            *  Library or object name, if **-A** is specified
    
            *  Symbol name
    
            *  Symbol type, which shall either be one of the following single
               characters or an implementation-defined type represented by a
               single character:
    
               A     Global absolute symbol.
    
               a     Local absolute symbol.
    
               B     Global ``bss'' (that is, uninitialized data space)
                     symbol.
    
               b     Local bss symbol.
    
               D     Global data symbol.
    
               d     Local data symbol.
    
               T     Global text symbol.
    
               t     Local text symbol.
    
               U     Undefined symbol.
    
            *  Value of the symbol
    
            *  The size associated with the symbol, if applicable
    
           This information may be supplemented by additional information
           specific to the implementation.
    
           If the **-P** option is specified, the previous information shall be
           displayed using the following portable format. The three versions
           differ depending on whether **-t d** , **-t o** , or **-t x** was specified,
           respectively:
    
               "%s%s %s %d %d\n", <_library/object name_ >, <_name_ >, <_type_ >,
                   <_value_ >, <_size_ >
    
               "%s%s %s %o %o\n", <_library/object name_ >, <_name_ >, <_type_ >,
                   <_value_ >, <_size_ >
    
               "%s%s %s %x %x\n", <_library/object name_ >, <_name_ >, <_type_ >,
                   <_value_ >, <_size_ >
    
           where <_library/object name_ > shall be formatted as follows:
    
            *  If **-A** is not specified, <_library/object name_ > shall be an
               empty string.
    
            *  If **-A** is specified and the corresponding _file_ operand does not
               name a library:
    
                   "%s: ", <_file_ >
    
            *  If **-A** is specified and the corresponding _file_ operand names a
               library. In this case, <_object file_ > shall name the object
               file in the library containing the symbol being described:
    
                   "%s[%s]: ", <_file_ >, <_object file_ >
    
           If **-A** is not specified, then if more than one _file_ operand is
           specified or if only one _file_ operand is specified and it names a
           library, _nm_ shall write a line identifying the object containing
           the following symbols before the lines containing those symbols,
           in the form:
    
            *  If the corresponding _file_ operand does not name a library:
    
                   "%s:\n", <_file_ >
    
            *  If the corresponding _file_ operand names a library; in this
               case, <_object file_ > shall be the name of the file in the
               library containing the following symbols:
    
                   "%s[%s]:\n", <_file_ >, <_object file_ >
    
           If **-P** is specified, but **-t** is not, the format shall be as if **-t x**
           had been specified.
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    Successful completion.
    
           >0    An error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## 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.
    


## EXAMPLES



           None.
    


## RATIONALE



           Historical implementations of _nm_ have used different bases for
           numeric output and supplied different default types of symbols
           that were reported. The **-t** _format_ option, similar to that used in
           _od_ and _strings_ , can be used to specify the numeric base; **-g** and **-u**
           can be used to restrict the amount of output or the types of
           symbols included in the output.
    
           The compromise of using **-t** _format versus_ using **-d** , **-o** , and other
           similar options was necessary because of differences in the
           meaning of **-o** between implementations. The **-o** option from BSD has
           been provided here as **-A** to avoid confusion with the **-o** from
           System V (which has been provided here as **-t** and as **-o** on XSI-
           conformant systems).
    
           The option list was significantly reduced from that provided by
           historical implementations.
    
           The _nm_ description is a subset of both the System V and BSD _nm_
           utilities with no specified default output.
    
           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 _nm_ during software development
           was judged to outweigh other limitations.
    
           The default output format of _nm_ is not specified because of
           differences in historical implementations.  The **-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.
    
           The format given in _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.
    


## FUTURE DIRECTIONS



           None.
    


* * *