1NM(1P)                     POSIX Programmer's Manual                    NM(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

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

SYNOPSIS

16       nm [−APv] [−g|−u] [−t format] file...
17       nm [−APv] [−efox] [−g|−u] [−t format] file...
18

DESCRIPTION

20       The nm utility shall display  symbolic  information  appearing  in  the
21       object file, executable file, or object-file library named by file.  If
22       no symbolic information is available for a valid  input  file,  the  nm
23       utility shall report that fact, but not consider it an error condition.
24
25       The  default  base used when numeric values are written is unspecified.
26       On XSI-conformant systems, it shall be decimal.
27

OPTIONS

29       The nm  utility  shall  conform  to  the  Base  Definitions  volume  of
30       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
31
32       The following options shall be supported:
33
34       −A        Write  the full pathname or library name of an object on each
35                 line.
36
37       −e        Write only external (global) and static symbol information.
38
39       −f        Produce full output. Write redundant symbols  (.text,  .data,
40                 and .bss), normally suppressed.
41
42       −g        Write only external (global) symbol information.
43
44       −o        Write numeric values in octal (equivalent to −t o).
45
46       −P        Write  information  in a portable output format, as specified
47                 in the STDOUT section.
48
49       −t format Write each numeric value in the specified format. The  format
50                 shall be dependent on the single character used as the format
51                 option-argument:
52
53                 d     The offset is written in decimal (default).
54
55                 o     The offset is written in octal.
56
57                 x     The offset is written in hexadecimal.
58
59       −u        Write only undefined symbols.
60
61       −v        Sort output by value instead of by symbol name.
62
63       −x        Write numeric values in hexadecimal (equivalent to −t x).
64

OPERANDS

66       The following operand shall be supported:
67
68       file      A pathname of an object file, executable file, or object-file
69                 library.
70

STDIN

72       See the INPUT FILES section.
73

INPUT FILES

75       The  input  file  shall be an object file, an object-file library whose
76       format is the same as those produced by the ar utility for  link  edit‐
77       ing, or an executable file. The nm utility may accept additional imple‐
78       mentation-defined object library formats for the input file.
79

ENVIRONMENT VARIABLES

81       The following environment variables shall affect the execution of nm:
82
83       LANG      Provide a default value for  the  internationalization  vari‐
84                 ables  that are unset or null. (See the Base Definitions vol‐
85                 ume of POSIX.1‐2008, Section 8.2, Internationalization  Vari‐
86                 ables  for  the  precedence of internationalization variables
87                 used to determine the values of locale categories.)
88
89       LC_ALL    If set to a non-empty string value, override  the  values  of
90                 all the other internationalization variables.
91
92       LC_COLLATE
93                 Determine  the locale for character collation information for
94                 the symbol-name and symbol-value collation sequences.
95
96       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
97                 bytes of text data as characters (for example, single-byte as
98                 opposed to multi-byte characters in arguments).
99
100       LC_MESSAGES
101                 Determine the locale that should be used to affect the format
102                 and  contents  of  diagnostic  messages  written  to standard
103                 error.
104
105       NLSPATH   Determine the location of message catalogs for the processing
106                 of LC_MESSAGES.
107

ASYNCHRONOUS EVENTS

109       Default.
110

STDOUT

112       If  symbolic  information  is present in the input files, then for each
113       file or for each member of an archive, the nm utility shall  write  the
114       following  information  to  standard  output. By default, the format is
115       unspecified, but the output shall be sorted by symbol name according to
116       the collation sequence in the current locale.
117
118        *  Library or object name, if −A is specified
119
120        *  Symbol name
121
122        *  Symbol  type,  which  shall  either  be one of the following single
123           characters or an implementation-defined type represented by a  sin‐
124           gle character:
125
126           A     Global absolute symbol.
127
128           a     Local absolute symbol.
129
130           B     Global ``bss'' (that is, uninitialized data space) symbol.
131
132           b     Local bss symbol.
133
134           D     Global data symbol.
135
136           d     Local data symbol.
137
138           T     Global text symbol.
139
140           t     Local text symbol.
141
142           U     Undefined symbol.
143
144        *  Value of the symbol
145
146        *  The size associated with the symbol, if applicable
147
148       This information may be supplemented by additional information specific
149       to the implementation.
150
151       If the −P option is specified, the previous information shall  be  dis‐
152       played  using  the following portable format. The three versions differ
153       depending on whether −t d, −t o, or −t x was specified, respectively:
154
155           "%s%s %s %d %d\n", <library/object name>, <name>, <type>,
156               <value>, <size>
157
158           "%s%s %s %o %o\n", <library/object name>, <name>, <type>,
159               <value>, <size>
160
161           "%s%s %s %x %x\n", <library/object name>, <name>, <type>,
162               <value>, <size>
163
164       where <library/object name> shall be formatted as follows:
165
166        *  If −A is not specified, <library/object name>  shall  be  an  empty
167           string.
168
169        *  If −A is specified and the corresponding file operand does not name
170           a library:
171
172               "%s: ", <file>
173
174        *  If −A is specified and  the  corresponding  file  operand  names  a
175           library.  In this case, <object file> shall name the object file in
176           the library containing the symbol being described:
177
178               "%s[%s]: ", <file>, <object file>
179
180       If −A is not specified, then if more than one file operand is specified
181       or  if  only  one  file operand is specified and it names a library, nm
182       shall write a line identifying the object containing the following sym‐
183       bols before the lines containing those symbols, in the form:
184
185        *  If the corresponding file operand does not name a library:
186
187               "%s:\n", <file>
188
189        *  If  the  corresponding  file operand names a library; in this case,
190           <object file> shall be the name of the file in the library contain‐
191           ing the following symbols:
192
193               "%s[%s]:\n", <file>, <object file>
194
195       If  −P  is specified, but −t is not, the format shall be as if −t x had
196       been specified.
197

STDERR

199       The standard error shall be used only for diagnostic messages.
200

OUTPUT FILES

202       None.
203

EXTENDED DESCRIPTION

205       None.
206

EXIT STATUS

208       The following exit values shall be returned:
209
210        0    Successful completion.
211
212       >0    An error occurred.
213

CONSEQUENCES OF ERRORS

215       Default.
216
217       The following sections are informative.
218

APPLICATION USAGE

220       Mechanisms for dynamic linking make this utility less  meaningful  when
221       applied  to  an executable file because a dynamically linked executable
222       may omit numerous library routines that would be found in a  statically
223       linked executable.
224

EXAMPLES

226       None.
227

RATIONALE

229       Historical  implementations of nm have used different bases for numeric
230       output and supplied  different  default  types  of  symbols  that  were
231       reported. The −t format option, similar to that used in od and strings,
232       can be used to specify the numeric base; −g  and  −u  can  be  used  to
233       restrict  the  amount of output or the types of symbols included in the
234       output.
235
236       The compromise of using −t format versus using −d, −o, and other  simi‐
237       lar  options  was necessary because of differences in the meaning of −o
238       between implementations. The −o option from BSD has been provided  here
239       as −A to avoid confusion with the −o from System V (which has been pro‐
240       vided here as −t and as −o on XSI-conformant systems).
241
242       The option list was significantly reduced from that provided by histor‐
243       ical implementations.
244
245       The  nm  description is a subset of both the System V and BSD nm utili‐
246       ties with no specified default output.
247
248       It was recognized that mechanisms for dynamic linking make this utility
249       less  meaningful  when applied to an executable file (because a dynami‐
250       cally linked executable file may omit numerous  library  routines  that
251       would  be  found in a statically linked executable file), but the value
252       of nm during software development was judged to outweigh other  limita‐
253       tions.
254
255       The default output format of nm is not specified because of differences
256       in historical implementations.  The −P option was added to  allow  some
257       type  of  portable  output  format. After a comparison of the different
258       formats used in SunOS, BSD, SVR3, and SVR4, it was  decided  to  create
259       one that did not match the current format of any of these four systems.
260       The format devised is easy to parse by humans, easy to parse  in  shell
261       scripts, and does not need to vary depending on locale (because no Eng‐
262       lish descriptions are included).  All of the systems currently have the
263       information available to use this format.
264
265       The  format  given  in  nm  STDOUT  uses <space> characters between the
266       fields, which may be any number of <blank> characters required to align
267       the columns. The single-character types were selected to match histori‐
268       cal practice, and the requirement that implementation additions also be
269       single  characters  made  parsing  the  information  easier  for  shell
270       scripts.
271

FUTURE DIRECTIONS

273       None.
274

SEE ALSO

276       ar, c99
277
278       The Base Definitions volume of  POSIX.1‐2008,  Chapter  8,  Environment
279       Variables, Section 12.2, Utility Syntax Guidelines
280
282       Portions  of  this text are reprinted and reproduced in electronic form
283       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
284       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
285       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
286       cal  and  Electronics  Engineers,  Inc  and  The  Open Group.  (This is
287       POSIX.1-2008 with the 2013 Technical Corrigendum  1  applied.)  In  the
288       event of any discrepancy between this version and the original IEEE and
289       The Open Group Standard, the original IEEE and The Open Group  Standard
290       is  the  referee document. The original Standard can be obtained online
291       at http://www.unix.org/online.html .
292
293       Any typographical or formatting errors that appear  in  this  page  are
294       most likely to have been introduced during the conversion of the source
295       files to man page format. To report such errors,  see  https://www.ker
296       nel.org/doc/man-pages/reporting_bugs.html .
297
298
299
300IEEE/The Open Group                  2013                               NM(1P)
Impressum