1NM(1P) POSIX Programmer's Manual NM(1P)
2
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
12 nm - write the name list of an object file (DEVELOPMENT)
13
15 nm [-APv][-efox][ -g| -u][-t format] file...
16
18 This utility shall be provided on systems that support both the User
19 Portability Utilities option and the Software Development Utilities
20 option. On other systems it is optional. Certain options are only
21 available on XSI-conformant systems.
22 The nm utility shall display symbolic information appearing in the
24 object file, executable file, or object-file library named by file. If
25 no symbolic information is available for a valid input file, the nm
26 utility shall report that fact, but not consider it an error condition.
27 The default base used when numeric values are written is unspecified.
29 On XSI-conformant systems, it shall be decimal.
30
32 The nm utility shall conform to the Base Definitions volume of
33 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
34 The following options shall be supported:
36 -A Write the full pathname or library name of an object on each
38 line.
39 -e Write only external (global) and static symbol information.
41 -f Produce full output. Write redundant symbols ( .text, .data, and
43 .bss), normally suppressed.
44 -g Write only external (global) symbol information.
46 -o Write numeric values in octal (equivalent to -t o).
48 -P Write information in a portable output format, as specified in
50 the STDOUT section.
51 -t format
53 Write each numeric value in the specified format. The format
54 shall be dependent on the single character used as the format
55 option-argument:
56 d
58 The offset is written in decimal (default).
59 o
61 The offset is written in octal.
62 x
64 The offset is written in hexadecimal.
65 -u Write only undefined symbols.
68 -v Sort output by value instead of alphabetically.
70 -x Write numeric values in hexadecimal (equivalent to -t x).
72
75 The following operand shall be supported:
76 file A pathname of an object file, executable file, or object-file
78 library.
79
82 See the INPUT FILES section.
83
85 The input file shall be an object file, an object-file library whose
86 format is the same as those produced by the ar utility for link edit‐
87 ing, or an executable file. The nm utility may accept additional imple‐
88 mentation-defined object library formats for the input file.
89
91 The following environment variables shall affect the execution of nm:
92 LANG Provide a default value for the internationalization variables
94 that are unset or null. (See the Base Definitions volume of
95 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
96 ables for the precedence of internationalization variables used
97 to determine the values of locale categories.)
98 LC_ALL If set to a non-empty string value, override the values of all
100 the other internationalization variables.
101 LC_COLLATE
103 Determine the locale for character collation information for the
105 symbol-name and symbol-value collation sequences.
106 LC_CTYPE
108 Determine the locale for the interpretation of sequences of
109 bytes of text data as characters (for example, single-byte as
110 opposed to multi-byte characters in arguments).
111 LC_MESSAGES
113 Determine the locale that should be used to affect the format
114 and contents of diagnostic messages written to standard error.
115 NLSPATH
117 Determine the location of message catalogs for the processing of
118 LC_MESSAGES .
119
122 Default.
123
125 If symbolic information is present in the input files, then for each
126 file or for each member of an archive, the nm utility shall write the
127 following information to standard output. By default, the format is
128 unspecified, but the output shall be sorted alphabetically by symbol
129 name:
130 * Library or object name, if -A is specified
132 * Symbol name
134 * Symbol type, which shall either be one of the following single char‐
136 acters or an implementation-defined type represented by a single
137 character:
138 A
140 Global absolute symbol.
141 a
143 Local absolute symbol.
144 B
146 Global "bss" (that is, uninitialized data space) symbol.
147 b
149 Local bss symbol.
150 D
152 Global data symbol.
153 d
155 Local data symbol.
156 T
158 Global text symbol.
159 t
161 Local text symbol.
162 U
164 Undefined symbol.
165 * Value of the symbol
168 * The size associated with the symbol, if applicable
170 This information may be supplemented by additional information specific
172 to the implementation.
173 If the -P option is specified, the previous information shall be dis‐
175 played using the following portable format. The three versions differ
176 depending on whether -t d, -t o, or -t x was specified, respectively:
177 "%s%s %s %d %d\n", <library/object name>, <name>, <type>,
180 <value>, <size>
181 "%s%s %s %o %o\n", <library/object name>, <name>, <type>,
184 <value>, <size>
185 "%s%s %s %x %x\n", <library/object name>, <name>, <type>,
188 <value>, <size>
189 where <library/object name> shall be formatted as follows:
190 * If -A is not specified, <library/object name> shall be an empty
192 string.
193 * If -A is specified and the corresponding file operand does not name
195 a library:
196 "%s: ", <file>
199 * If -A is specified and the corresponding file operand names a
201 library. In this case, <object file> shall name the object file in
202 the library containing the symbol being described:
203 "%s[%s]: ", <file>, <object file>
206 If -A is not specified, then if more than one file operand is specified
208 or if only one file operand is specified and it names a library, nm
209 shall write a line identifying the object containing the following sym‐
210 bols before the lines containing those symbols, in the form:
211 * If the corresponding file operand does not name a library:
213 "%s:\n", <file>
216 * If the corresponding file operand names a library; in this case,
218 <object file> shall be the name of the file in the library contain‐
219 ing the following symbols:
220 "%s[%s]:\n", <file>, <object file>
223 If -P is specified, but -t is not, the format shall be as if -t x had
225 been specified.
226
228 The standard error shall be used only for diagnostic messages.
229
231 None.
232
234 None.
235
237 The following exit values shall be returned:
238 0 Successful completion.
240 >0 An error occurred.
242
245 Default.
246 The following sections are informative.
248
250 Mechanisms for dynamic linking make this utility less meaningful when
251 applied to an executable file because a dynamically linked executable
252 may omit numerous library routines that would be found in a statically
253 linked executable.
254
256 None.
257
259 Historical implementations of nm have used different bases for numeric
260 output and supplied different default types of symbols that were
261 reported. The -t format option, similar to that used in od and strings,
262 can be used to specify the numeric base; -g and -u can be used to
263 restrict the amount of output or the types of symbols included in the
264 output.
265 The compromise of using -t format versus using -d, -o, and other simi‐
267 lar options was necessary because of differences in the meaning of -o
268 between implementations. The -o option from BSD has been provided here
269 as -A to avoid confusion with the -o from System V (which has been pro‐
270 vided here as -t and as -o on XSI-conformant systems).
271 The option list was significantly reduced from that provided by histor‐
273 ical implementations.
274 The nm description is a subset of both the System V and BSD nm utili‐
276 ties with no specified default output.
277 It was recognized that mechanisms for dynamic linking make this utility
279 less meaningful when applied to an executable file (because a dynami‐
280 cally linked executable file may omit numerous library routines that
281 would be found in a statically linked executable file), but the value
282 of nm during software development was judged to outweigh other limita‐
283 tions.
284 The default output format of nm is not specified because of differences
286 in historical implementations. The -P option was added to allow some
287 type of portable output format. After a comparison of the different
288 formats used in SunOS, BSD, SVR3, and SVR4, it was decided to create
289 one that did not match the current format of any of these four systems.
290 The format devised is easy to parse by humans, easy to parse in shell
291 scripts, and does not need to vary depending on locale (because no Eng‐
292 lish descriptions are included). All of the systems currently have the
293 information available to use this format.
294 The format given in nm STDOUT uses spaces between the fields, which may
296 be any number of <blank>s required to align the columns. The single-
297 character types were selected to match historical practice, and the
298 requirement that implementation additions also be single characters
299 made parsing the information easier for shell scripts.
300
302 None.
303
305 ar, c99
306
308 Portions of this text are reprinted and reproduced in electronic form
309 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
310 -- Portable Operating System Interface (POSIX), The Open Group Base
311 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
312 Electrical and Electronics Engineers, Inc and The Open Group. In the
313 event of any discrepancy between this version and the original IEEE and
314 The Open Group Standard, the original IEEE and The Open Group Standard
315 is the referee document. The original Standard can be obtained online
316 at http://www.opengroup.org/unix/online.html .
317IEEE/The Open Group 2003 NM(1P)