Commit | Line | Data |
---|---|---|
de5fd53b RP |
1 | \input texinfo |
2 | @setfilename binutils.info | |
3 | @synindex ky cp | |
4 | @c | |
5 | @c This file documents the GNU binary utilities "ar", "ld", "objdump", "nm", | |
6 | @c "size", "strip", and "ranlib". | |
7 | @c | |
8 | @c Copyright (C) 1991 Free Software Foundation, Inc. | |
9 | @c | |
10 | @c This text may be freely distributed under the terms of the GNU | |
11 | @c General Public License. | |
12 | @c | |
13 | @c $Id$ | |
14 | @tex | |
15 | @finalout | |
16 | @c @smallbook | |
17 | @end tex | |
18 | @c @cropmarks | |
19 | @setchapternewpage odd | |
20 | @settitle GNU Binary Utilities | |
21 | @titlepage | |
22 | @title{The GNU Binary Utilities} | |
23 | @sp 1 | |
24 | @subtitle January 1991 | |
25 | @author{Roland H. Pesch} | |
26 | @author{Cygnus Support} | |
27 | @page | |
28 | ||
29 | @tex | |
30 | \def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ | |
31 | \xdef\manvers{\$Revision$} % For use in headers, footers too | |
32 | {\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par \hfill | |
33 | \TeX{}info \texinfoversion\par } | |
34 | @end tex | |
35 | ||
36 | @vskip 0pt plus 1filll | |
37 | Copyright @copyright{} 1991 Free Software Foundation, Inc. | |
38 | ||
39 | Permission is granted to make and distribute verbatim copies of | |
40 | this manual provided the copyright notice and this permission notice | |
41 | are preserved on all copies. | |
42 | ||
43 | Permission is granted to copy and distribute modified versions of this | |
44 | manual under the conditions for verbatim copying, provided also that | |
45 | the entire resulting derived work is distributed under the terms of a | |
46 | permission notice identical to this one. | |
47 | ||
48 | Permission is granted to copy and distribute translations of this manual | |
49 | into another language, under the above conditions for modified versions. | |
50 | @end titlepage | |
51 | ||
52 | @ifinfo | |
53 | @node Top, ar, (dir), (dir) | |
54 | This file documents the GNU binary utilities @samp{ar}, @samp{ld}, | |
55 | @samp{objdump}, @samp{nm}, @samp{size}, @samp{strip}, and | |
56 | @samp{ranlib}.@refill | |
57 | ||
58 | Copyright @copyright{} 1991 Free Software Foundation, Inc. | |
59 | ||
60 | Permission is granted to make and distribute verbatim copies of | |
61 | this manual provided the copyright notice and this permission notice | |
62 | are preserved on all copies. | |
63 | ||
64 | @ignore | |
65 | Permission is granted to process this file through TeX and print the | |
66 | results, provided the printed document carries a copying permission | |
67 | notice identical to this one except for the removal of this paragraph | |
68 | (this paragraph not being relevant to the printed manual). | |
69 | ||
70 | @end ignore | |
71 | ||
72 | Permission is granted to copy and distribute modified versions of this | |
73 | manual under the conditions for verbatim copying, provided also that | |
74 | the entire resulting derived work is distributed under the terms of a | |
75 | permission notice identical to this one. | |
76 | ||
77 | Permission is granted to copy and distribute translations of this manual | |
78 | into another language, under the above conditions for modified versions. | |
79 | @end ifinfo | |
80 | ||
81 | @menu | |
82 | * ar:: ar | |
83 | * ld:: ld | |
84 | * nm:: nm | |
85 | * objdump:: objdump | |
86 | * ranlib:: ranlib | |
87 | * size:: size | |
88 | * strip:: strip | |
89 | ||
90 | @end menu | |
91 | ||
92 | @node ar, ld, Top, Top | |
93 | @chapter ar | |
94 | ||
95 | @smallexample | |
96 | ar [-]@var{Op}@var{Mod} [ @var{membername} ] @var{archive} @var{files}@dots{} | |
97 | @end smallexample | |
98 | ||
99 | The GNU @code{ar} program creates, modifies, and extracts | |
100 | archives. An @dfn{archive} is a single file holding a collection of | |
101 | other files in a structure that makes it possible to retrieve | |
102 | the original individual files (called @dfn{members} of the archive). | |
103 | ||
104 | The original files' contents, mode (permissions), timestamp, owner, and | |
105 | group are preserved in the archive, and may be reconstituted on | |
106 | extraction. | |
107 | ||
108 | Only the first fifteen characters of a file name are kept in archives. | |
109 | @c Note: with next (BFD) version, this will depend on obj format. | |
110 | ||
111 | @code{ar} is considered a binary utility because archives of this sort | |
112 | are most often used as @dfn{libraries} holding commonly needed | |
113 | subroutines. | |
114 | ||
115 | @code{ar} will create an index to the symbols defined in relocatable | |
116 | object modules in the archive when you specify the option @samp{s}. | |
117 | Once created, this index is updated in the archive whenever @code{ar} | |
118 | makes a change to its contents. An archive with such an index speeds up | |
119 | linking to the library, and allows routines in the library to call each | |
120 | other without regard to their placement in the archive. | |
121 | @c This auto-update may happen-always only for WRS version; Gumby says, for | |
122 | @c instance, that it doesn't happen with 'q' updates elsewhere. | |
123 | ||
124 | You may use @samp{nm -s} or @samp{nm +print-symdefs} to list this index | |
125 | table. If an archive lacks the table, another form of @code{ar} called | |
126 | @code{ranlib} can be used to add just the table. | |
127 | ||
128 | @code{ar} insists on at least two arguments to execute: one | |
129 | keyletter specifying the @emph{operation} (optionally accompanied by other | |
130 | keyletters specifying @emph{modifiers}), and the archive name to act on. | |
131 | ||
132 | Most operations can also accept further @var{files} arguments, | |
133 | specifying particular files to operate on. | |
134 | ||
135 | GNU @code{ar} allows you to mix the operation code and modifier flags in | |
136 | any order, within the first command-line argument. | |
137 | ||
138 | If you wish, you may precede the first command-line argument with a | |
139 | dash. | |
140 | ||
141 | The @var{Op} keyletter specifies what operation to execute; it may be | |
142 | any of the following, but you must specify only one of them: | |
143 | ||
144 | @table @code | |
145 | @item d | |
146 | @emph{Delete} modules from the archive. Specify the names of modules to | |
147 | be deleted as @var{files}; the archive is untouched if you | |
148 | specify no files to delete. | |
149 | ||
150 | If you wish to delete an archive's index, you can use this option to do | |
151 | it; the internal name of the index (which you will need to specify in | |
152 | @var{files} to delete it) is @samp{__.SYMDEF}. | |
153 | ||
154 | If you specify the @samp{v} option flag, @code{ar} will list each module | |
155 | as it is deleted. | |
156 | ||
157 | @item m | |
158 | Use this operation to @emph{move} members in an archive. | |
159 | ||
160 | The ordering of members in an archive can make a difference in how | |
161 | programs are linked using the library, if a symbol is defined in more | |
162 | than one member. | |
163 | ||
164 | If no option flags are used with @code{m}, any members you name in the | |
165 | @var{files} arguments are moved to the @emph{end} of the archive; | |
166 | you can use the @samp{a}, @samp{b}, or @samp{i} options to move them to a | |
167 | specified place instead. | |
168 | ||
169 | @item p | |
170 | @emph{Print} the specified members of the archive, to the standard | |
171 | output file. If the @samp{v} option flag is specified, show the member | |
172 | name before copying its contents to standard output. | |
173 | ||
174 | If you specify no @var{files}, all the files in the archive are printed, | |
175 | save for the index (if any), which is listed only if you ask for it by | |
176 | name: @samp{__.SYMDEF}. | |
177 | ||
178 | @item q | |
179 | @emph{Quick append}; add @var{files} to the end of @var{archive}, | |
180 | without checking for replacement. | |
181 | ||
182 | The options @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this | |
183 | operation; new members are always placed at the end of the archive. | |
184 | ||
185 | The option @samp{v} makes @code{ar} list each file as it is appended. | |
186 | ||
187 | @c per Gumby, versions other than WRS of this will *not* auto-update | |
188 | @c SYMDEF index on 'q' updates. | |
189 | ||
190 | @item r | |
191 | Insert @var{files} into @var{archive} (with @emph{replacement}). This | |
192 | operation differs from @samp{q} in that any previously existing members | |
193 | are deleted if their names match those being added. | |
194 | ||
195 | If one of the files named in @var{files} doesn't exist, @code{ar} | |
196 | displays an error message, and leaves undisturbed any existing members | |
197 | of the archive matching that name. | |
198 | ||
199 | By default, new members are added at the end of the file; but you may | |
200 | use one of the options @samp{a}, @samp{b}, or @samp{i} to request | |
201 | placement relative to some existing member. | |
202 | ||
203 | The option flag @samp{v} used with this operation elicits a line of | |
204 | output for each file inserted, along with one of the letters @samp{a} or | |
205 | @samp{r} to indicate whether the file was appended (no old member | |
206 | deleted) or replaced. | |
207 | ||
208 | @item t | |
209 | Display a @emph{table} listing the contents of @var{archive}, or those | |
210 | of the files listed in @var{files} that are present in the | |
211 | archive. Normally only the member name is shown; if you also want to | |
212 | see the modes (permissions), timestamp, owner, group, and size, you can | |
213 | request that by also specifying the @samp{v} option flag. | |
214 | ||
215 | If you do not specify any @var{files}, all files in the archive | |
216 | are listed; but the index to symbols from relocatable modules, called | |
217 | @samp{__.SYMDEF}, is not listed unless you explicitly request it by | |
218 | name. | |
219 | ||
220 | If there is more than one file with the same name (say, @samp{fie}) in | |
221 | an archive (say @samp{b.a}), @samp{ar t b.a fie} will list only the | |
222 | first instance; to see them all, you must ask for a complete | |
223 | listing---in our example, @samp{ar t b.a}. | |
224 | @c WRS only; per Gumby, this is implementation-dependent, and in a more | |
225 | @c recent case in fact works the other way. | |
226 | ||
227 | @item x | |
228 | @emph{Extract} a member from the archive. The @samp{v} option flag | |
229 | requests that @code{ar} list each name as it extracts it. | |
230 | ||
231 | If you do not specify any @var{files}, all files in the archive | |
232 | are extracted; but the index to symbols from relocatable modules, called | |
233 | @samp{__.SYMDEF}, is not extracted unless you explicitly request it by | |
234 | name. | |
235 | ||
236 | @end table | |
237 | ||
238 | A number of modifiers may immediately follow the @var{Op} keyletter, to | |
239 | specify variations on an operation's behavior: | |
240 | ||
241 | @table @code | |
242 | @item a | |
243 | Add new files @emph{after} an existing member of the | |
244 | archive. If you use the modifier @code{a}, the name of an existing archive | |
245 | member must be present as the @var{membername} argument, before the | |
246 | @var{archive} specification. | |
247 | ||
248 | @item b | |
249 | Add new files @emph{before} an existing member of the | |
250 | archive. If you use the modifier @code{b}, the name of an existing archive | |
251 | member must be present as the @var{membername} argument, before the | |
252 | @var{archive} specification. (same as @samp{i}). | |
253 | ||
254 | @item c | |
255 | @emph{Create} the archive. The specified @var{archive} is always | |
256 | created if it didn't exist, when you request an update. But a warning is | |
257 | issued unless you specify in advance that you expect to create it, by | |
258 | using this option flag. | |
259 | ||
260 | @item i | |
261 | Insert new files @emph{before} an existing member of the | |
262 | archive. If you use the modifier @code{i}, the name of an existing archive | |
263 | member must be present as the @var{membername} argument, before the | |
264 | @var{archive} specification. (same as @samp{b}). | |
265 | ||
266 | @item l | |
267 | This option flag is recognized but not used; it is permitted for | |
268 | compatibility with other forms of @code{ar}. | |
269 | @c ???---pesch@@cygnus.com, 25jan91 | |
270 | ||
271 | @item o | |
272 | Preserve the @emph{original} dates of members when extracting them. If | |
273 | you do not specify this option flag, files extracted from the archive | |
274 | will be stamped with the time of extraction. | |
275 | ||
276 | @item s | |
277 | Write an object-file index into the archive, or update an existing one, | |
278 | even if no other change is made to the archive. You may use this option | |
279 | flag either with any operation, or alone. Running @samp{ar s} on an | |
280 | archive is equivalent to running @samp{ranlib} on it. | |
281 | ||
282 | @item u | |
283 | Normally, @code{ar r}@dots{} or @code{ar q}@dots{} insert all files | |
284 | listed into the archive. If you would like to insert @emph{only} those | |
285 | of the files you list that are newer than existing members of the same | |
286 | names, use this option. The option-flag combination @samp{qu} is | |
287 | equivalent to @samp{ru}; checking the timestamps loses any speed | |
288 | advantage, so @code{ar} treats both commands as replace operations with | |
289 | the @samp{u} option appended. | |
290 | ||
291 | @c u actually turns *anything* into a replace. I claim this is a bug; | |
292 | @c 'du' and 'tu' for example should either be rejected or equivalent to | |
293 | @c plain 'd' and 't'. ---pesch@@cygnus.com, 25jan91 | |
294 | ||
295 | @item v | |
296 | This option requests the @emph{verbose} version of an operations. Many | |
297 | operations display additional information, such as filenames processed, | |
298 | when the option @samp{v} is appended. | |
299 | ||
300 | @end table | |
301 | ||
302 | @node ld, nm, ar, Top | |
303 | @chapter ld | |
304 | The GNU linker @code{ld} is now described in a separate manual. | |
305 | @xref{Top, , Overview, , GLD: the GNU linker}. | |
306 | ||
307 | @node nm, objdump, ld, Top | |
308 | @chapter nm | |
309 | ||
310 | @smallexample | |
311 | nm [ -a | +debug-syms ] [ -g | +extern-only ] | |
312 | [ -n | +numeric-sort ] [ -o | +print-file-name ] | |
313 | [ -p | +no-sort ] [ -r | +reverse-sort ] | |
314 | [ -s | +print-symdefs ] [ -u | +undefined-only ] | |
315 | [ @var{objfiles}@dots{} ] | |
316 | @end smallexample | |
317 | ||
318 | GNU @code{nm} will list the symbols from object files @var{objfiles}. | |
319 | Any command-line options must precede all object files; no option takes | |
320 | an argument. | |
321 | ||
322 | The long and short forms of options, shown here as alternatives, are | |
323 | equivalent. | |
324 | ||
325 | @table @code | |
326 | @item @var{objfiles}@dots{} | |
327 | Object files whose symbols are to be listed. If no object files are | |
328 | listed as arguments, @code{nm} assumes @samp{a.out}. | |
329 | ||
330 | @item -a | +debug-syms | |
331 | Display debugger-only symbols; normally these are not listed. | |
332 | ||
333 | @item -g | +extern-only | |
334 | Display only external symbols. | |
335 | ||
336 | @item -n | +numeric-sort | |
337 | Sort symbols numerically by their addresses, not alphabetically by their | |
338 | names. | |
339 | ||
340 | @item -o | +print-file-name | |
341 | Precede each symbol by the name of the input file where it was found, | |
342 | rather than identifying the input file once only before all of its | |
343 | symbols. | |
344 | ||
345 | @item -p | +no-sort | |
346 | Don't bother to sort the symbols in any order; just print them in the | |
347 | order encountered. | |
348 | ||
349 | @item -r | +reverse-sort | |
350 | Reverse the sense of the sort (whether numeric or alphabetic); let the | |
351 | last come first. | |
352 | ||
353 | @item -s | +print-symdefs | |
354 | When listing symbols from archives, list the index: a mapping (stored in | |
355 | the archive by @code{ar} or @code{ranlib} of what modules contain | |
356 | definitions for what names. | |
357 | ||
358 | @item -u | +undefined-only | |
359 | Display only undefined symbols (those external to each object file). | |
360 | ||
361 | @end table | |
362 | ||
363 | @node objdump, ranlib, nm, Top | |
364 | @chapter objdump | |
365 | ||
366 | @smallexample | |
367 | objdump [ -h | +header ] [ -n | +nstuff ] [ -r | +reloc ] | |
368 | [ -t | +syms ] @var{objfiles}@dots{} | |
369 | @end smallexample | |
370 | ||
371 | @code{objdump} displays information about one or more object files. | |
372 | The options control what particular information to display. This | |
373 | information is mostly useful to programmers who are working on the | |
374 | compilation tools, as opposed to programmers who just want their | |
375 | program to compile and work. | |
376 | ||
377 | The long and short forms of options, shown here as alternatives, are | |
378 | equivalent. | |
379 | ||
380 | @table @code | |
381 | @item @var{objfiles}@dots{} | |
382 | The object files to be examined. | |
383 | ||
384 | @item -h | +header | |
385 | Header. Print summary information from the header of the object file. | |
386 | ||
387 | @item -n | +nstuff | |
388 | @samp{N_} symbols. Print the values of various macros from @file{a.out.h} | |
389 | as applied to the object file; e.g. @code{N_TXTOFF}. | |
390 | ||
391 | @item -r | +reloc | |
392 | Relocation. Print the relocation entries of the file. | |
393 | ||
394 | @item -t | +syms | |
395 | Symbol Table. Print the symbol table entries of the file. | |
396 | This is similar to the information provided by the @samp{nm} program. | |
397 | ||
398 | @end table | |
399 | ||
400 | @node ranlib, size, objdump, Top | |
401 | @chapter ranlib | |
402 | ||
403 | @smallexample | |
404 | ranlib [ -t | +touch ] [ -v | +verbose ] @var{archive} | |
405 | @end smallexample | |
406 | ||
407 | @code{ranlib} generates the an index to the contents of an archive, and | |
408 | stores it in the archive. The index lists each symbol defined by a | |
409 | member of an archive that is a relocatable object file. | |
410 | ||
411 | You may use @code{nm -s} or @code{nm +print-symdefs} to list this table. | |
412 | The index is internally stored in the archive under the name | |
413 | @samp{__.SYMDEF}. | |
414 | ||
415 | An archive with such an index speeds up linking to the library, and | |
416 | allows routines in the library to call each other without regard to | |
417 | their placement in the archive. | |
418 | ||
419 | The GNU @code{ranlib} program is another form of GNU @code{ar}. | |
420 | ||
421 | @code{ranlib}'s options make it report on what it's doing and fake an | |
422 | update of a particular archive's index. | |
423 | ||
424 | Any command-line options must precede the archive name. | |
425 | ||
426 | The long and short forms of options, shown here as alternatives, are | |
427 | equivalent. | |
428 | ||
429 | @table @code | |
430 | ||
431 | @item -t | +touch | |
432 | You can use the ``touch'' option to fake an update of the index | |
433 | table in archives; @code{ranlib} will first set the current date for the | |
434 | index object module in the archive (to make it appear to have changed). | |
435 | ||
436 | @item -v | +verbose | |
437 | Use this option if you'd like informational messages about what | |
438 | @code{ranlib} is up to, while it loops through the specified archives. | |
439 | ||
440 | @end table | |
441 | ||
442 | @node size, strip, ranlib, Top | |
443 | @chapter size | |
444 | ||
445 | @smallexample | |
446 | size @var{objfiles}@dots{} | |
447 | @end smallexample | |
448 | ||
449 | The GNU @code{size} utility lists the segment (@code{text}, @code{data}, | |
450 | @code{bss} sizes ---and the total size--- for the object files | |
451 | @var{objfiles} in its argument list. For archives, one line of output | |
452 | is generated for each module. | |
453 | ||
454 | @code{size} has no command-line options. | |
455 | ||
456 | If more than one object module is listed, @code{size} labels each line | |
457 | of output with the module's name: | |
458 | @smallexample | |
459 | % size a.out libX11.a | |
460 | text data bss dec hex | |
461 | 49152 49152 0 98304 18000 a.out | |
462 | 1256 16 0 1272 4f8 libX11.a(Context.o) | |
463 | 176 0 0 176 b0 libX11.a(Depths.o) | |
464 | 1360 56 0 1416 588 libX11.a(ParseCmd.o) | |
465 | 904 24 4096 5024 13a0 libX11.a(Quarks.o) | |
466 | 216 0 0 216 d8 libX11.a(XAllCells.o) | |
467 | . | |
468 | . | |
469 | . | |
470 | ||
471 | @end smallexample | |
472 | [sample output truncated] | |
473 | ||
474 | @node strip, , size, Top | |
475 | @chapter strip | |
476 | ||
477 | @smallexample | |
478 | strip [ -s | +strip-all ] [ -S | +strip-debug ] | |
479 | [ -x | +discard-all ] [ -X | +discard-locals ] | |
480 | @var{objfiles}@dots{} | |
481 | @end smallexample | |
482 | ||
483 | GNU @code{strip} will discard all symbols from object files | |
484 | @var{objfiles}, if no options are specified; or only certain symbols, | |
485 | depending on its command-line options. | |
486 | ||
487 | @code{strip} will not execute unless at least one object file is listed. | |
488 | ||
489 | @emph{WARNING:} @code{strip} modifies the files named in its argument, | |
490 | rather than writing modified copies under different names. | |
491 | ||
492 | The long and short forms of options, shown here as alternatives, are | |
493 | equivalent. | |
494 | ||
495 | @table @code | |
496 | @item -s | +strip-all | |
497 | This is the default case: strip all symbol entries from @var{objfiles}. | |
498 | ||
499 | @item -S | +strip-debug | |
500 | Discard only debugging symbol information from @var{objfiles}. | |
501 | ||
502 | @item -x | +discard-all | |
503 | Discard all symbols local to each file in @var{objfiles}. | |
504 | @emph{WARNING:} Note that @code{+discard-all} discards only @emph{local} | |
505 | symbols, in spite of its name. | |
506 | ||
507 | @item -X | +discard-locals | |
508 | Discard local symbols starting with @samp{L} from each file in | |
509 | @var{objfiles}. (Some compilers produce internally-used symbols that | |
510 | begin with @samp{L}.) | |
511 | @end table | |
512 | ||
513 | ||
514 | @contents | |
515 | @bye | |
516 | ||
517 |