Commit | Line | Data |
---|---|---|
765a273f | 1 | \input texinfo @c -*- Texinfo -*- |
c72af735 RP |
2 | @setfilename binutils.info |
3 | ||
9abcc3b8 RP |
4 | @ifinfo |
5 | @format | |
6 | START-INFO-DIR-ENTRY | |
7 | ||
c72af735 RP |
8 | * Binutils: (binutils). |
9 | The GNU binary utilities "ar", "ld", "objdump", "nm", | |
10 | "size", "strip", and "ranlib". | |
9abcc3b8 RP |
11 | |
12 | END-INFO-DIR-ENTRY | |
13 | @end format | |
14 | @end ifinfo | |
c72af735 RP |
15 | |
16 | @synindex ky cp | |
17 | @c | |
18 | @c This file documents the GNU binary utilities "ar", "ld", "objdump", "nm", | |
19 | @c "size", "strip", and "ranlib". | |
20 | @c | |
21 | @c Copyright (C) 1991 Free Software Foundation, Inc. | |
22 | @c | |
23 | @c This text may be freely distributed under the terms of the GNU | |
24 | @c General Public License. | |
25 | @c | |
26 | @c $Id$ | |
27e94bd5 | 27 | |
c72af735 RP |
28 | @setchapternewpage odd |
29 | @settitle GNU Binary Utilities | |
30 | @titlepage | |
27e94bd5 RP |
31 | @finalout |
32 | @c @smallbook | |
33 | @c @cropmarks | |
c72af735 | 34 | @title The GNU Binary Utilities |
da52f26b | 35 | @subtitle Version 1.97 |
c72af735 RP |
36 | @sp 1 |
37 | @subtitle October 1991 | |
38 | @author Roland H. Pesch | |
39 | @author Cygnus Support | |
40 | @page | |
41 | ||
42 | @tex | |
43 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
44 | \xdef\manvers{\$Revision$} % For use in headers, footers too | |
45 | {\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par \hfill | |
46 | \TeX{}info \texinfoversion\par } | |
47 | @end tex | |
48 | ||
49 | @vskip 0pt plus 1filll | |
50 | Copyright @copyright{} 1991 Free Software Foundation, Inc. | |
51 | ||
52 | Permission is granted to make and distribute verbatim copies of | |
53 | this manual provided the copyright notice and this permission notice | |
54 | are preserved on all copies. | |
55 | ||
56 | Permission is granted to copy and distribute modified versions of this | |
57 | manual under the conditions for verbatim copying, provided also that | |
58 | the entire resulting derived work is distributed under the terms of a | |
59 | permission notice identical to this one. | |
60 | ||
61 | Permission is granted to copy and distribute translations of this manual | |
62 | into another language, under the above conditions for modified versions. | |
63 | @end titlepage | |
64 | ||
65 | @node Top, ar, (dir), (dir) | |
66 | @chapter Introduction | |
67 | ||
68 | @cindex version | |
69 | This brief manual contains preliminary documentation for the GNU binary | |
da52f26b | 70 | utilities (collectively version 1.97): |
c72af735 RP |
71 | @table @code |
72 | @item ar | |
73 | Create, modify, and extract from archives | |
74 | ||
75 | @item nm | |
76 | List symbols from object files | |
77 | ||
78 | @item objdump | |
79 | Display information from object files | |
80 | ||
81 | @item ranlib | |
82 | Generate index to archive contents | |
83 | ||
84 | @item size | |
85 | List section sizes and total size | |
86 | ||
87 | @item strip | |
88 | Discard symbols | |
89 | @end table | |
90 | ||
91 | @ifinfo | |
92 | Copyright @copyright{} 1991 Free Software Foundation, Inc. | |
93 | ||
94 | Permission is granted to make and distribute verbatim copies of | |
95 | this manual provided the copyright notice and this permission notice | |
96 | are preserved on all copies. | |
97 | ||
98 | @ignore | |
99 | Permission is granted to process this file through TeX and print the | |
100 | results, provided the printed document carries a copying permission | |
101 | notice identical to this one except for the removal of this paragraph | |
102 | (this paragraph not being relevant to the printed manual). | |
103 | ||
104 | @end ignore | |
105 | ||
106 | Permission is granted to copy and distribute modified versions of this | |
107 | manual under the conditions for verbatim copying, provided also that | |
108 | the entire resulting derived work is distributed under the terms of a | |
109 | permission notice identical to this one. | |
110 | ||
111 | Permission is granted to copy and distribute translations of this manual | |
112 | into another language, under the above conditions for modified versions. | |
113 | @end ifinfo | |
114 | ||
115 | @menu | |
765a273f RP |
116 | * ar:: ar |
117 | * ld:: ld | |
118 | * nm:: nm | |
119 | * objdump:: objdump | |
120 | * ranlib:: ranlib | |
121 | * size:: size | |
122 | * strip:: strip | |
123 | * Index:: Index | |
124 | ||
125 | --- The Detailed Node Listing --- | |
126 | ||
127 | ar | |
128 | ||
129 | * ar-cmdline:: Controlling @code{ar} on the command line | |
130 | * ar-scripts:: Controlling @code{ar} with a script | |
c72af735 RP |
131 | @end menu |
132 | ||
133 | @node ar, ld, Top, Top | |
134 | @chapter ar | |
135 | ||
136 | @kindex ar | |
137 | @cindex archives | |
138 | @cindex collections of files | |
139 | @smallexample | |
140 | ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{files}@dots{} | |
765a273f | 141 | ar -M [ <mri-script ] |
c72af735 RP |
142 | @end smallexample |
143 | ||
144 | The GNU @code{ar} program creates, modifies, and extracts from | |
145 | archives. An @dfn{archive} is a single file holding a collection of | |
146 | other files in a structure that makes it possible to retrieve | |
147 | the original individual files (called @dfn{members} of the archive). | |
148 | ||
149 | The original files' contents, mode (permissions), timestamp, owner, and | |
150 | group are preserved in the archive, and may be reconstituted on | |
151 | extraction. | |
152 | ||
153 | @cindex name length | |
154 | GNU @code{ar} can maintain archives whose members have names of any | |
155 | length; however, depending on how @code{ar} is configured on your | |
156 | system, a limit on member-name length may be imposed (for compatibility | |
157 | with archive formats maintained with other tools). If it exists, the | |
158 | limit is often 15 characters (typical of formats related to a.out) or 16 | |
159 | characters (typical of formats related to coff). | |
160 | ||
161 | @cindex libraries | |
162 | @code{ar} is considered a binary utility because archives of this sort | |
163 | are most often used as @dfn{libraries} holding commonly needed | |
164 | subroutines. | |
165 | ||
166 | @cindex symbol index | |
167 | @code{ar} will create an index to the symbols defined in relocatable | |
168 | object modules in the archive when you specify the modifier @samp{s}. | |
169 | Once created, this index is updated in the archive whenever @code{ar} | |
170 | makes a change to its contents (save for the @samp{q} update operation). | |
171 | An archive with such an index speeds up linking to the library, and | |
172 | allows routines in the library to call each other without regard to | |
173 | their placement in the archive. | |
174 | ||
175 | You may use @samp{nm -s} or @samp{nm +print-armap} to list this index | |
176 | table. If an archive lacks the table, another form of @code{ar} called | |
177 | @code{ranlib} can be used to add just the table. | |
178 | ||
765a273f RP |
179 | @cindex compatibility, @code{ar} |
180 | @cindex @code{ar} compatibility | |
181 | GNU @code{ar} is designed to be compatible with two different | |
182 | facilities. You can control its activity using command-line options, | |
183 | like the different varieties of @code{ar} on Unix systems; or, if you | |
184 | specify the single command-line option @samp{-M}, you can control it | |
185 | with a script supplied via standard input, like the MRI ``librarian'' | |
186 | program. | |
187 | ||
188 | @menu | |
189 | * ar-cmdline:: Controlling @code{ar} on the command line | |
190 | * ar-scripts:: Controlling @code{ar} with a script | |
191 | @end menu | |
192 | ||
193 | @page | |
194 | @node ar-cmdline, ar-scripts, ar, ar | |
195 | @section Controlling @code{ar} on the command line | |
196 | ||
197 | @smallexample | |
198 | ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{files}@dots{} | |
199 | @end smallexample | |
200 | ||
201 | @cindex Unix compatibility, @code{ar} | |
202 | When you use @code{ar} in the Unix style, @code{ar} insists on at least two | |
203 | arguments to execute: one keyletter specifying the @emph{operation} | |
204 | (optionally accompanied by other keyletters specifying | |
205 | @emph{modifiers}), and the archive name to act on. | |
c72af735 RP |
206 | |
207 | Most operations can also accept further @var{files} arguments, | |
208 | specifying particular files to operate on. | |
209 | ||
210 | GNU @code{ar} allows you to mix the operation code @var{p} and modifier | |
211 | flags @var{mod} in any order, within the first command-line argument. | |
212 | ||
213 | If you wish, you may begin the first command-line argument with a | |
214 | dash. | |
215 | ||
216 | @cindex operations on archive | |
217 | The @var{p} keyletter specifies what operation to execute; it may be | |
218 | any of the following, but you must specify only one of them: | |
219 | ||
220 | @table @code | |
221 | @item d | |
222 | @cindex deleting from archive | |
223 | @emph{Delete} modules from the archive. Specify the names of modules to | |
224 | be deleted as @var{files}; the archive is untouched if you | |
225 | specify no files to delete. | |
226 | ||
227 | If you specify the @samp{v} modifier, @code{ar} will list each module | |
228 | as it is deleted. | |
229 | ||
230 | @item m | |
231 | @cindex moving in archive | |
232 | Use this operation to @emph{move} members in an archive. | |
233 | ||
234 | The ordering of members in an archive can make a difference in how | |
235 | programs are linked using the library, if a symbol is defined in more | |
236 | than one member. | |
237 | ||
238 | If no modifiers are used with @code{m}, any members you name in the | |
239 | @var{files} arguments are moved to the @emph{end} of the archive; | |
240 | you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a | |
241 | specified place instead. | |
242 | ||
243 | @item p | |
244 | @cindex printing from archive | |
245 | @emph{Print} the specified members of the archive, to the standard | |
246 | output file. If the @samp{v} modifier is specified, show the member | |
247 | name before copying its contents to standard output. | |
248 | ||
249 | If you specify no @var{files}, all the files in the archive are printed. | |
250 | ||
251 | @item q | |
252 | @cindex quick append to archive | |
253 | @emph{Quick append}; add @var{files} to the end of @var{archive}, | |
254 | without checking for replacement. | |
255 | ||
256 | The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this | |
257 | operation; new members are always placed at the end of the archive. | |
258 | ||
259 | The modifier @samp{v} makes @code{ar} list each file as it is appended. | |
260 | ||
261 | Since the point of this operation is speed, the archive's symbol table | |
262 | index is not updated, even if it already existed; you can use @samp{ar s} or | |
263 | @code{ranlib} explicitly to update the symbol table index. | |
264 | ||
265 | @item r | |
266 | @cindex replacement in archive | |
267 | Insert @var{files} into @var{archive} (with @emph{replacement}). This | |
268 | operation differs from @samp{q} in that any previously existing members | |
269 | are deleted if their names match those being added. | |
270 | ||
271 | If one of the files named in @var{files} doesn't exist, @code{ar} | |
272 | displays an error message, and leaves undisturbed any existing members | |
273 | of the archive matching that name. | |
274 | ||
275 | By default, new members are added at the end of the file; but you may | |
276 | use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request | |
277 | placement relative to some existing member. | |
278 | ||
279 | The modifier @samp{v} used with this operation elicits a line of | |
280 | output for each file inserted, along with one of the letters @samp{a} or | |
281 | @samp{r} to indicate whether the file was appended (no old member | |
282 | deleted) or replaced. | |
283 | ||
284 | @item t | |
285 | @cindex contents of archive | |
286 | Display a @emph{table} listing the contents of @var{archive}, or those | |
287 | of the files listed in @var{files} that are present in the | |
288 | archive. Normally only the member name is shown; if you also want to | |
289 | see the modes (permissions), timestamp, owner, group, and size, you can | |
290 | request that by also specifying the @samp{v} modifier. | |
291 | ||
292 | If you do not specify any @var{files}, all files in the archive | |
293 | are listed. | |
294 | ||
295 | @cindex repeated names in archive | |
296 | @cindex name duplication in archive | |
297 | If there is more than one file with the same name (say, @samp{fie}) in | |
298 | an archive (say @samp{b.a}), @samp{ar t b.a fie} will list only the | |
299 | first instance; to see them all, you must ask for a complete | |
300 | listing---in our example, @samp{ar t b.a}. | |
301 | @c WRS only; per Gumby, this is implementation-dependent, and in a more | |
302 | @c recent case in fact works the other way. | |
303 | ||
304 | @item x | |
305 | @cindex extract from archive | |
306 | @emph{Extract} members (named @var{files}) from the archive. You can | |
307 | use the @samp{v} modifier with this operation, to request that | |
308 | @code{ar} list each name as it extracts it. | |
309 | ||
310 | If you do not specify any @var{files}, all files in the archive | |
311 | are extracted. | |
312 | ||
313 | @end table | |
314 | ||
315 | A number of modifiers (@var{mod}) may immediately follow the @var{p} | |
316 | keyletter, to specify variations on an operation's behavior: | |
317 | ||
318 | @table @code | |
319 | @item a | |
320 | @cindex relative placement in archive | |
321 | Add new files @emph{after} an existing member of the | |
322 | archive. If you use the modifier @code{a}, the name of an existing archive | |
323 | member must be present as the @var{membername} argument, before the | |
324 | @var{archive} specification. | |
325 | ||
326 | @item b | |
327 | Add new files @emph{before} an existing member of the | |
328 | archive. If you use the modifier @code{b}, the name of an existing archive | |
329 | member must be present as the @var{membername} argument, before the | |
330 | @var{archive} specification. (same as @samp{i}). | |
331 | ||
332 | @item c | |
333 | @cindex creating archives | |
334 | @emph{Create} the archive. The specified @var{archive} is always | |
335 | created if it didn't exist, when you request an update. But a warning is | |
336 | issued unless you specify in advance that you expect to create it, by | |
337 | using this modifier. | |
338 | ||
339 | @item i | |
340 | Insert new files @emph{before} an existing member of the | |
341 | archive. If you use the modifier @code{i}, the name of an existing archive | |
342 | member must be present as the @var{membername} argument, before the | |
343 | @var{archive} specification. (same as @samp{b}). | |
344 | ||
345 | @item l | |
346 | This modifier is accepted but not used. | |
347 | @c whaffor ar l modifier??? presumably compat; with | |
348 | @c what???---pesch@@cygnus.com, 25jan91 | |
349 | ||
350 | @item o | |
351 | @cindex dates in archive | |
352 | Preserve the @emph{original} dates of members when extracting them. If | |
353 | you do not specify this modifier, files extracted from the archive | |
354 | will be stamped with the time of extraction. | |
355 | ||
356 | @item s | |
357 | @cindex writing archive index | |
358 | Write an object-file index into the archive, or update an existing one, | |
359 | even if no other change is made to the archive. You may use this modifier | |
360 | flag either with any operation, or alone. Running @samp{ar s} on an | |
361 | archive is equivalent to running @samp{ranlib} on it. | |
362 | ||
363 | @item u | |
364 | @cindex updating an archive | |
365 | Normally, @code{ar r}@dots{} inserts all files | |
366 | listed into the archive. If you would like to insert @emph{only} those | |
367 | of the files you list that are newer than existing members of the same | |
368 | names, use this modifier. The @samp{u} modifier is allowed only for the | |
369 | operation @samp{r} (replace). In particular, the combination @samp{qu} is | |
370 | not allowed, since checking the timestamps would lose any speed | |
371 | advantage from the operation @samp{q}. | |
372 | ||
373 | @item v | |
374 | This modifier requests the @emph{verbose} version of an operation. Many | |
375 | operations display additional information, such as filenames processed, | |
376 | when the modifier @samp{v} is appended. | |
765a273f RP |
377 | @end table |
378 | ||
379 | @node ar-scripts, , ar-cmdline, ar | |
380 | @section Controlling @code{ar} with a script | |
381 | ||
382 | @smallexample | |
383 | ar -M [ <@var{script} ] | |
384 | @end smallexample | |
385 | ||
386 | @cindex MRI compatibility, @code{ar} | |
387 | @cindex scripts, @code{ar} | |
388 | If you use the single command-line option @samp{-M} with @code{ar}, you | |
389 | can control its operation with a rudimentary command language. This | |
390 | form of @code{ar} will operate interactively if standard input is coming | |
391 | directly from a terminal. During interactive use, @code{ar} prompts for | |
392 | input (the prompt is @samp{AR >}), and continues executing even after | |
393 | errors. If you redirect standard input to a script file, no prompts are | |
394 | issued, and @code{ar} will abandon execution (with a nonzero exit code) | |
395 | on any error. | |
396 | ||
397 | The @code{ar} command language is @emph{not} designed to be equivalent | |
398 | to the command-line options; in fact, it provides somewhat less control | |
399 | over archives. The only purpose of the command language is to ease the | |
400 | transition to GNU @code{ar} for developers who already have scripts | |
401 | written for the MRI ``librarian'' program. | |
402 | ||
403 | The syntax for the @code{ar} command language is straightforward: | |
404 | @itemize @bullet | |
405 | @item | |
406 | commands are recognized in upper or lower case; for example, @code{LIST} | |
407 | is the same as @code{list}. In the following descriptions, commands are | |
408 | shown in upper case for clarity. | |
409 | ||
410 | @item | |
411 | a single command may appear on each line; it is the first word on the | |
412 | line. | |
413 | ||
414 | @item | |
415 | empty lines are allowed, and have no effect. | |
416 | ||
417 | @item | |
418 | comments are allowed; text after either of the characters @samp{*} | |
419 | or @samp{;} is ignored. | |
420 | ||
421 | @item | |
422 | Whenever you use a list of names as part of the argument to an @code{ar} | |
423 | command, you can separate the individual names with either commas or | |
424 | blanks. Commas are shown in the explanations below, for clarity. | |
425 | ||
426 | @item | |
427 | @samp{+} is used as a line continuation character; if @samp{+} appears | |
428 | at the end of a line, the text on the following line is considered part | |
429 | of the current command. | |
430 | @end itemize | |
431 | ||
432 | Here are the commands you can use in @code{ar} scripts, or when using | |
433 | @code{ar} interactively. Three of them have special significance: | |
434 | ||
435 | @code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is | |
436 | a temporary file required for most of the other commands. | |
437 | ||
438 | @code{SAVE} commits the changes so far specified by the script. Prior | |
439 | to @code{SAVE}, commands affect only the temporary copy of the current | |
440 | archive. | |
441 | ||
442 | @table @code | |
443 | @item ADDLIB @var{archive} | |
444 | @itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module}) | |
445 | Add all the contents of @var{archive} (or, if specified, each named | |
446 | @var{module} from @var{archive}) to the current archive. | |
447 | ||
448 | Requires prior use of @code{OPEN} or @code{CREATE}. | |
449 | ||
450 | @item ADDMOD @var{file}, @var{file}, @dots{} @var{file} | |
451 | @c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}" | |
452 | @c else like "ar q..." | |
453 | Add each named @var{file} as a module in the current archive. | |
454 | ||
455 | Requires prior use of @code{OPEN} or @code{CREATE}. | |
456 | ||
457 | @item CLEAR | |
458 | Discard the contents of the current archive, cancelling the effect of | |
459 | any operations since the last @code{SAVE}. May be executed (with no | |
460 | effect) even if no current archive is specified. | |
461 | ||
462 | @item CREATE @var{archive} | |
463 | Creates an archive, and makes it the current archive (required for many | |
464 | other commands). The new archive is created with a temporary name; it | |
465 | is not actually saved as @var{archive} until you use @code{SAVE}. | |
466 | You can overwrite existing archives; similarly, the contents of any | |
467 | existing file named @var{archive} will not be destroyed until @code{SAVE}. | |
468 | ||
469 | @item DELETE @var{module}, @var{module}, @dots{} @var{module} | |
470 | Delete each listed @var{module} from the current archive; equivalent to | |
471 | @samp{ar -d @var{archive} @var{module} @dots{} @var{module}}. | |
472 | ||
473 | Requires prior use of @code{OPEN} or @code{CREATE}. | |
474 | ||
475 | @item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) | |
476 | @itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile} | |
477 | List each named @var{module} present in @var{archive}. The separate | |
478 | command @code{VERBOSE} specifies the form of the output: when verbose | |
479 | output is off, output is like that of @samp{ar -t @var{archive} | |
480 | @var{module}@dots{}}. When verbose output is on, the listing is like | |
481 | @samp{ar -tv @var{archive} @var{module}@dots{}}. | |
482 | ||
483 | Output normally goes to the standard output stream; however, if you | |
484 | specify @var{outputfile} as a final argument, @code{ar} directs the | |
485 | output to that file. | |
486 | ||
487 | @item END | |
488 | Exit from @code{ar}, with a @code{0} exit code to indicate successful | |
489 | completion. This command does not save the output file; if you have | |
490 | changed the current archive since the last @code{SAVE} command, those | |
491 | changes are lost. | |
492 | ||
493 | @item EXTRACT @var{module}, @var{module}, @dots{} @var{module} | |
494 | Extract each named @var{module} from the current archive, writing them | |
495 | into the current directory as separate files. Equivalent to @samp{ar -x | |
496 | @var{archive} @var{module}@dots{}}. | |
497 | ||
498 | Requires prior use of @code{OPEN} or @code{CREATE}. | |
499 | ||
500 | @ignore | |
501 | @c FIXME Tokens but no commands??? | |
502 | @item FULLDIR | |
503 | ||
504 | @item HELP | |
505 | @end ignore | |
506 | ||
507 | @item LIST | |
508 | Display full contents of the current archive, in ``verbose'' style | |
509 | regardless of the state of @code{VERBOSE}. The effect is like @samp{ar | |
510 | tv @var{archive}}). (This single command is a GNU @code{ld} | |
511 | enhancement, rather than present for MRI compatibility.) | |
512 | ||
513 | Requires prior use of @code{OPEN} or @code{CREATE}. | |
514 | ||
515 | @item OPEN @var{archive} | |
516 | Opens an existing archive for use as the current archive (required for | |
517 | many other commands). Any changes as the result of subsequent commands | |
518 | will not actually affect @var{archive} until you next use @code{SAVE}. | |
519 | ||
520 | @item REPLACE @var{module}, @var{module}, @dots{} @var{module} | |
521 | In the current archive, replace each existing @var{module} (named in | |
522 | the @code{REPLACE} arguments) from files in the current working directory. | |
523 | To execute this command without errors, both the file, and the module in | |
524 | the current archive, must exist. | |
525 | ||
526 | Requires prior use of @code{OPEN} or @code{CREATE}. | |
527 | ||
528 | @item VERBOSE | |
529 | Toggle an internal flag governing the output from @code{DIRECTORY}. | |
530 | When the flag is on, @code{DIRECTORY} output matches output from | |
531 | @samp{ar -tv @dots{}}. | |
532 | ||
533 | @item SAVE | |
534 | Commit your changes to the current archive, and actually save it as a | |
535 | file with the name specified in the last @code{CREATE} or @code{OPEN} | |
536 | command. | |
537 | ||
538 | Requires prior use of @code{OPEN} or @code{CREATE}. | |
c72af735 RP |
539 | |
540 | @end table | |
541 | ||
765a273f | 542 | |
c72af735 RP |
543 | @node ld, nm, ar, Top |
544 | @chapter ld | |
545 | @cindex linker | |
546 | @kindex ld | |
547 | The GNU linker @code{ld} is now described in a separate manual. | |
27e94bd5 | 548 | @xref{Top,, Overview,, Using LD: the GNU linker}. |
c72af735 RP |
549 | |
550 | @node nm, objdump, ld, Top | |
551 | @chapter nm | |
552 | @cindex symbols | |
553 | @kindex nm | |
554 | ||
555 | @smallexample | |
556 | nm [ -a | +debug-syms ] [ -g | +extern-only ] | |
557 | [ -s | +print-armap ] [ -o | +print-file-name ] | |
558 | [ -n | +numeric-sort ] [ -p | +no-sort ] | |
559 | [ -r | +reverse-sort ] [ -u | +undefined-only ] | |
560 | [ +target @var{bfdname} ] | |
561 | [ @var{objfiles}@dots{} ] | |
562 | @end smallexample | |
563 | ||
564 | GNU @code{nm} will list the symbols from object files @var{objfiles}. | |
565 | ||
566 | The long and short forms of options, shown here as alternatives, are | |
567 | equivalent. | |
568 | ||
569 | @table @code | |
570 | @item @var{objfiles}@dots{} | |
571 | @kindex a.out | |
572 | Object files whose symbols are to be listed. If no object files are | |
573 | listed as arguments, @code{nm} assumes @samp{a.out}. | |
574 | ||
575 | @item -a | |
576 | @itemx +debug-syms | |
577 | @cindex debugging symbols | |
578 | Display debugger-only symbols; normally these are not listed. | |
579 | ||
580 | @item -g | |
581 | @itemx +extern-only | |
582 | @cindex external symbols | |
583 | Display only external symbols. | |
584 | ||
585 | @item -p | |
586 | @itemx +no-sort | |
587 | @cindex sorting symbols | |
588 | Don't bother to sort the symbols in any order; just print them in the | |
589 | order encountered. | |
590 | ||
591 | @item -n | |
592 | @itemx +numeric-sort | |
593 | Sort symbols numerically by their addresses, not alphabetically by their | |
594 | names. | |
595 | ||
596 | @item -s | |
597 | @itemx +print-armap | |
598 | @cindex symbol index, listing | |
599 | When listing symbols from archive members, include the index: a mapping | |
600 | (stored in the archive by @code{ar} or @code{ranlib}) of what modules | |
601 | contain definitions for what names. | |
602 | ||
603 | @item -o | |
604 | @itemx +print-file-name | |
605 | @cindex input file name | |
606 | @cindex file name | |
607 | @cindex source file name | |
608 | Precede each symbol by the name of the input file where it was found, | |
609 | rather than identifying the input file once only before all of its | |
610 | symbols. | |
611 | ||
612 | @item -r | |
613 | @itemx +reverse-sort | |
614 | Reverse the sense of the sort (whether numeric or alphabetic); let the | |
615 | last come first. | |
616 | ||
617 | @item +target @var{bfdname} | |
618 | @c @item +target | |
619 | @cindex object code format | |
620 | Specify an object code format other than your system's default format. | |
621 | @xref{objdump}, for information on listing available formats. | |
622 | @c FIXME what *does* +target/no arg do? | |
623 | ||
624 | @item -u | |
625 | @itemx +undefined-only | |
626 | @cindex external symbols | |
627 | @cindex undefined symbols | |
628 | Display only undefined symbols (those external to each object file). | |
629 | ||
630 | @end table | |
631 | ||
632 | @node objdump, ranlib, nm, Top | |
633 | @chapter objdump | |
634 | ||
635 | @cindex object file information | |
636 | @kindex objdump | |
637 | ||
638 | @smallexample | |
639 | objdump [ -a ] [ -b @var{bfdname} ] [ -d ] [ -f ] | |
640 | [ -h | +header ] [ -i ] [ -j @var{section} ] [ -l ] | |
641 | [ -m @var{machine} ] [ -r | +reloc ] [ -s ] | |
642 | [ -t | +syms ] [ -x ] | |
643 | @var{objfiles}@dots{} | |
644 | @end smallexample | |
645 | ||
646 | @code{objdump} displays information about one or more object files. | |
647 | The options control what particular information to display. This | |
648 | information is mostly useful to programmers who are working on the | |
649 | compilation tools, as opposed to programmers who just want their | |
650 | program to compile and work. | |
651 | ||
652 | The long and short forms of options, shown here as alternatives, are | |
653 | equivalent. | |
654 | ||
655 | @table @code | |
656 | @item @var{objfiles}@dots{} | |
657 | The object files to be examined. When you specify archives, | |
658 | @code{objdump} shows information on each of the member object files. | |
659 | ||
660 | @item -a | |
661 | @c print_arelt_descr | |
662 | @cindex archive headers | |
663 | If any files from @var{objfiles} are archives, display the archive | |
664 | header information (in a format similar to @samp{ls -l}). Besides the | |
665 | information you could list with @samp{ar tv}, @samp{objdump -a} shows | |
666 | the object file format of each archive member. | |
667 | ||
668 | @c suggest longname +target or +format or +bfd | |
669 | @item -b @var{bfdname} | |
670 | @cindex object code format | |
671 | You can specify a particular object-code format for your object files as | |
672 | @var{bfdname}. This may not be necessary; @var{objdump} can | |
673 | automatically recognize many formats. For example, | |
674 | @example | |
675 | objdump -b oasys -m vax -h fu.o | |
676 | @end example | |
677 | @noindent | |
678 | Displays summary information from the section headers (@samp{-h}) of | |
679 | @file{fu.o}, which is explicitly identified (@samp{-m}) as a Vax object | |
680 | file in the format produced by Oasys compilers. You can list the | |
681 | formats available with the @samp{-i} option. | |
682 | ||
683 | @item -d | |
684 | @cindex disassembling object code | |
685 | @cindex machine instructions | |
686 | Disassemble. Display the assembler mnemonics for the machine | |
687 | instructions from @var{objfiles}. | |
688 | ||
689 | @item -f | |
690 | @cindex object file header | |
691 | File header. Display summary information from the overall header of | |
692 | each file in @var{objfiles}. | |
693 | ||
694 | @item -h | |
695 | @itemx +header | |
696 | @cindex section headers | |
697 | Header. Display summary information from the section headers of the | |
698 | object file. | |
699 | ||
700 | @item -i | |
701 | @cindex architectures available | |
702 | @cindex object formats available | |
703 | Display a list showing all architectures and object formats available | |
704 | for specification with @code{-b} or @code{-m}. | |
705 | ||
706 | @c suggest longname +section | |
707 | @item -j @var{name} | |
708 | @cindex section information | |
709 | Display information only for section @var{name} | |
710 | ||
711 | @c suggest longname +label or +linespec | |
712 | @item -l | |
713 | @cindex source filenames for object files | |
714 | Label the display (using debugging information) with the source filename | |
715 | and line numbers corresponding to the object code shown. | |
716 | ||
717 | @c suggest longname +architecture | |
718 | @item -m @var{machine} | |
719 | @cindex architecture | |
720 | Specify the object files @var{objfiles} are for architecture | |
721 | @var{machine}. You can list available architectures using the @samp{-i} | |
722 | option. | |
723 | ||
724 | @item -r | |
725 | @itemx +reloc | |
726 | @cindex relocation entries, in object file | |
727 | Relocation. Print the relocation entries of the file. | |
728 | ||
729 | @item -s | |
730 | @cindex sections, full contents | |
731 | @cindex object file sections | |
732 | Display the full contents of any sections requested. | |
733 | ||
734 | @item -t | |
735 | @itemx +syms | |
736 | @cindex symbol table entries, printing | |
737 | Symbol Table. Print the symbol table entries of the file. | |
738 | This is similar to the information provided by the @samp{nm} program. | |
739 | ||
740 | @item -x | |
741 | @cindex all header information, object file | |
742 | @cindex header information, all | |
743 | Display all available header information, including the symbol table and | |
744 | relocation entries. Using @samp{-x} is equivalent to specifying all of | |
745 | @samp{-a -f -h -r -t}. | |
746 | ||
747 | @end table | |
748 | ||
749 | @node ranlib, size, objdump, Top | |
750 | @chapter ranlib | |
751 | ||
752 | @kindex ranlib | |
753 | @cindex archive contents | |
754 | @cindex symbol index | |
755 | ||
756 | @smallexample | |
757 | ranlib @var{archive} | |
758 | @end smallexample | |
759 | ||
760 | @code{ranlib} generates an index to the contents of an archive, and | |
761 | stores it in the archive. The index lists each symbol defined by a | |
762 | member of an archive that is a relocatable object file. | |
763 | ||
764 | You may use @samp{nm -s} or @samp{nm +print-armap} to list this index. | |
765 | ||
766 | An archive with such an index speeds up linking to the library, and | |
767 | allows routines in the library to call each other without regard to | |
768 | their placement in the archive. | |
769 | ||
770 | The GNU @code{ranlib} program is another form of GNU @code{ar}; running | |
771 | @code{ranlib} is completely equivalent to executing @samp{ar -s}. | |
772 | @xref{ar}. | |
773 | ||
774 | @node size, strip, ranlib, Top | |
775 | @chapter size | |
776 | ||
777 | @kindex size | |
778 | @cindex section sizes | |
779 | ||
780 | @smallexample | |
781 | size [ -A | -B | +format @var{compatibility} ] | |
782 | [ +help ] [ -d | -o | -x | +radix @var{number} ] | |
783 | [ +target @var{bfdname} ] [ -V | +version ] | |
784 | @var{objfiles}@dots{} | |
785 | @end smallexample | |
786 | ||
787 | The GNU @code{size} utility lists the section sizes---and the total | |
788 | size---for each of the object files @var{objfiles} in its argument list. | |
789 | By default, one line of output is generated for each object file or each | |
790 | module in an archive. | |
791 | ||
792 | The command line options have the following meanings: | |
793 | @table @code | |
794 | @item @var{objfiles}@dots{} | |
795 | The object files to be examined. | |
796 | ||
797 | @item -A | |
798 | @itemx -B | |
799 | @itemx +format @var{compatibility} | |
800 | @cindex size display format | |
801 | Using one of these options, you can choose whether the output from GNU | |
802 | @code{size} resembles output from System V @code{size} (using @samp{-A}, | |
803 | or @samp{+format sysv}), or Berkeley @code{size} (using @samp{-B}, or | |
804 | @samp{+format berkeley}). The default is the one-line format similar to | |
805 | Berkeley's. | |
806 | @c Bonus for doc-source readers: you can also say +format=strange (or | |
807 | @c anything else that starts with 's') for sysv, and +format=boring (or | |
808 | @c anything else that starts with 'b') for Berkeley. | |
809 | ||
810 | Here is an example of the Berkeley (default) format of output from | |
811 | @code{size}: | |
812 | @smallexample | |
813 | eg$ size +format Berkeley ranlib size | |
814 | text data bss dec hex filename | |
815 | 294880 81920 11592 388392 5ed28 ranlib | |
816 | 294880 81920 11888 388688 5ee50 size | |
817 | @end smallexample | |
818 | ||
819 | @noindent | |
820 | This is the same data, but displayed closer to System V conventions: | |
821 | ||
822 | @smallexample | |
823 | eg$ size +format SysV ranlib size | |
824 | ranlib : | |
825 | section size addr | |
826 | .text 294880 8192 | |
827 | .data 81920 303104 | |
828 | .bss 11592 385024 | |
829 | Total 388392 | |
830 | ||
831 | ||
832 | size : | |
833 | section size addr | |
834 | .text 294880 8192 | |
835 | .data 81920 303104 | |
836 | .bss 11888 385024 | |
837 | Total 388688 | |
838 | @end smallexample | |
839 | ||
840 | @item +help | |
841 | Show a summary of acceptable arguments and options. | |
842 | ||
843 | @item -d | |
844 | @itemx -o | |
845 | @itemx -x | |
846 | @itemx +radix @var{number} | |
847 | @cindex size number format | |
848 | @cindex radix for section sizes | |
849 | Using one of these options, you can control whether the size of each | |
850 | section is given in decimal (@samp{-d}, or @samp{+radix 10}); octal | |
851 | (@samp{-o}, or @samp{+radix 8}); or hexadecimal (@samp{-x}, or | |
852 | @samp{+radix 16}). In @samp{+radix @var{number}}, only the three | |
853 | values (8, 10, 16) are supported. The total size is always given in two | |
854 | radices; decimal and hexadecimal for @samp{-d} or @samp{-x} output, or | |
855 | octal and hexadecimal if you're using @samp{-o}. | |
856 | ||
857 | @item +target @var{bfdname} | |
858 | @cindex object code format | |
859 | You can specify a particular object-code format for @var{objfiles} as | |
860 | @var{bfdname}. This may not be necessary; @var{size} can | |
861 | automatically recognize many formats. @xref{objdump}, for information | |
862 | on listing available formats. | |
863 | ||
864 | @item -V | |
865 | @itemx +version | |
866 | Display version number information on @code{size} itself. | |
867 | ||
868 | @end table | |
869 | ||
870 | @node strip, Index, size, Top | |
871 | @chapter strip | |
872 | ||
873 | @kindex strip | |
874 | @cindex removing symbols | |
875 | @cindex discarding symbols | |
876 | ||
877 | @smallexample | |
878 | strip [ -s | +strip-all ] [ -g | -S | +strip-debug ] | |
879 | [ -x | +discard-all ] [ -X | +discard-locals ] | |
880 | [ -T @var{bfdname} ] | |
881 | @var{objfiles}@dots{} | |
882 | @end smallexample | |
883 | ||
884 | GNU @code{strip} will discard all symbols from object files | |
885 | @var{objfiles}, if no options are specified; or only certain symbols, | |
886 | depending on its command-line options. | |
887 | ||
888 | @code{strip} will not execute unless at least one object file is listed. | |
889 | ||
890 | @quotation | |
891 | @emph{WARNING:} @code{strip} modifies the files named in its argument, | |
892 | rather than writing modified copies under different names. | |
893 | @end quotation | |
894 | ||
895 | The long and short forms of options, shown here as alternatives, are | |
896 | equivalent. | |
897 | ||
898 | @table @code | |
899 | @item -s | |
900 | @itemx +strip-all | |
901 | @cindex all symbols, discarding | |
902 | This is the default case: strip all symbol entries from @var{objfiles}. | |
903 | ||
904 | @item -g | |
905 | @itemx -S | |
906 | @itemx +strip-debug | |
907 | @cindex debugging symbols, discarding | |
908 | Discard only debugging symbol information from @var{objfiles}. | |
909 | ||
910 | @item -x | |
911 | @itemx +discard-all | |
912 | @cindex local symbols, discarding | |
913 | Discard all symbols local to each file in @var{objfiles}. | |
914 | @emph{WARNING:} Note that @code{+discard-all} discards only @emph{local} | |
915 | symbols, in spite of its name. | |
916 | ||
917 | @item -X | |
918 | @itemx +discard-locals | |
919 | Discard local symbols starting with @samp{L} from each file in | |
920 | @var{objfiles}. (Some compilers produce internally-used symbols that | |
921 | begin with @samp{L}.) | |
922 | ||
923 | @item -T @var{bfdname} | |
924 | @cindex object code format | |
925 | You can specify a particular object-code format @var{bfdname} for | |
926 | @var{objfiles}. This may not be necessary; @var{strip} can automatically | |
927 | recognize many formats. @xref{objdump}, for information on listing | |
928 | available formats. | |
929 | @end table | |
930 | ||
765a273f | 931 | @node Index, , strip, Top |
c72af735 RP |
932 | @unnumbered Index |
933 | ||
934 | @printindex cp | |
935 | ||
936 | @contents | |
937 | @bye |