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