Import binutils-2.20
[dragonfly.git] / contrib / binutils-2.20 / binutils / doc / binutils.texi
1 \input texinfo       @c                    -*- Texinfo -*-
2 @setfilename binutils.info
3 @settitle @sc{gnu} Binary Utilities
4 @finalout
5 @synindex ky cp
6
7 @c man begin INCLUDE
8 @include bfdver.texi
9 @c man end
10
11 @copying
12 @c man begin COPYRIGHT
13 Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
14 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
15
16 Permission is granted to copy, distribute and/or modify this document
17 under the terms of the GNU Free Documentation License, Version 1.3
18 or any later version published by the Free Software Foundation;
19 with no Invariant Sections, with no Front-Cover Texts, and with no
20 Back-Cover Texts.  A copy of the license is included in the
21 section entitled ``GNU Free Documentation License''.
22
23 @c man end
24 @end copying
25
26 @dircategory Software development
27 @direntry
28 * Binutils: (binutils).         The GNU binary utilities.
29 @end direntry
30
31 @dircategory Individual utilities
32 @direntry
33 * addr2line: (binutils)addr2line. Convert addresses to file and line.
34 * ar: (binutils)ar.               Create, modify, and extract from archives.
35 * c++filt: (binutils)c++filt.     Filter to demangle encoded C++ symbols.
36 * cxxfilt: (binutils)c++filt.     MS-DOS name for c++filt.
37 * dlltool: (binutils)dlltool.     Create files needed to build and use DLLs.
38 * nlmconv: (binutils)nlmconv.     Converts object code into an NLM.
39 * nm: (binutils)nm.               List symbols from object files.
40 * objcopy: (binutils)objcopy.     Copy and translate object files.
41 * objdump: (binutils)objdump.     Display information from object files.
42 * ranlib: (binutils)ranlib.       Generate index to archive contents.
43 * readelf: (binutils)readelf.     Display the contents of ELF format files.
44 * size: (binutils)size.           List section sizes and total size.
45 * strings: (binutils)strings.     List printable strings from files.
46 * strip: (binutils)strip.         Discard symbols.
47 * windmc: (binutils)windmc.       Generator for Windows message resources.
48 * windres: (binutils)windres.     Manipulate Windows resources.
49 @end direntry
50
51 @titlepage
52 @title The @sc{gnu} Binary Utilities
53 @ifset VERSION_PACKAGE
54 @subtitle @value{VERSION_PACKAGE}
55 @end ifset
56 @subtitle Version @value{VERSION}
57 @sp 1
58 @subtitle @value{UPDATED}
59 @author Roland H. Pesch
60 @author Jeffrey M. Osier
61 @author Cygnus Support
62 @page
63
64 @tex
65 {\parskip=0pt \hfill Cygnus Support\par \hfill
66 Texinfo \texinfoversion\par }
67 @end tex
68
69 @vskip 0pt plus 1filll
70 @insertcopying
71 @end titlepage
72 @contents
73
74 @node Top
75 @top Introduction
76
77 @cindex version
78 This brief manual contains documentation for the @sc{gnu} binary
79 utilities
80 @ifset VERSION_PACKAGE
81 @value{VERSION_PACKAGE}
82 @end ifset
83 version @value{VERSION}:
84
85 @iftex
86 @table @code
87 @item ar
88 Create, modify, and extract from archives
89
90 @item nm
91 List symbols from object files
92
93 @item objcopy
94 Copy and translate object files
95
96 @item objdump
97 Display information from object files
98
99 @item ranlib
100 Generate index to archive contents
101
102 @item readelf
103 Display the contents of ELF format files.
104
105 @item size
106 List file section sizes and total size
107
108 @item strings
109 List printable strings from files
110
111 @item strip
112 Discard symbols
113
114 @item c++filt
115 Demangle encoded C++ symbols (on MS-DOS, this program is named
116 @code{cxxfilt})
117
118 @item addr2line
119 Convert addresses into file names and line numbers
120
121 @item nlmconv
122 Convert object code into a Netware Loadable Module
123
124 @item windres
125 Manipulate Windows resources
126
127 @item windmc
128 Genertor for Windows message resources
129
130 @item dlltool
131 Create the files needed to build and use Dynamic Link Libraries
132 @end table
133 @end iftex
134
135 This document is distributed under the terms of the GNU Free
136 Documentation License version 1.3.  A copy of the license is included
137 in the section entitled ``GNU Free Documentation License''.
138
139 @menu
140 * ar::                          Create, modify, and extract from archives
141 * nm::                          List symbols from object files
142 * objcopy::                     Copy and translate object files
143 * objdump::                     Display information from object files
144 * ranlib::                      Generate index to archive contents
145 * readelf::                     Display the contents of ELF format files
146 * size::                        List section sizes and total size
147 * strings::                     List printable strings from files
148 * strip::                       Discard symbols
149 * c++filt::                     Filter to demangle encoded C++ symbols
150 * cxxfilt: c++filt.             MS-DOS name for c++filt
151 * addr2line::                   Convert addresses to file and line
152 * nlmconv::                     Converts object code into an NLM
153 * windres::                     Manipulate Windows resources
154 * windmc::                      Generator for Windows message resources
155 * dlltool::                     Create files needed to build and use DLLs
156 * Common Options::              Command-line options for all utilities
157 * Selecting the Target System:: How these utilities determine the target
158 * Reporting Bugs::              Reporting Bugs
159 * GNU Free Documentation License::  GNU Free Documentation License
160 * Binutils Index::              Binutils Index
161 @end menu
162
163 @node ar
164 @chapter ar
165
166 @kindex ar
167 @cindex archives
168 @cindex collections of files
169
170 @c man title ar create, modify, and extract from archives
171
172 @smallexample
173 ar [@option{--plugin} @var{name}] [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
174 ar -M [ <mri-script ]
175 @end smallexample
176
177 @c man begin DESCRIPTION ar
178
179 The @sc{gnu} @command{ar} program creates, modifies, and extracts from
180 archives.  An @dfn{archive} is a single file holding a collection of
181 other files in a structure that makes it possible to retrieve
182 the original individual files (called @dfn{members} of the archive).
183
184 The original files' contents, mode (permissions), timestamp, owner, and
185 group are preserved in the archive, and can be restored on
186 extraction.
187
188 @cindex name length
189 @sc{gnu} @command{ar} can maintain archives whose members have names of any
190 length; however, depending on how @command{ar} is configured on your
191 system, a limit on member-name length may be imposed for compatibility
192 with archive formats maintained with other tools.  If it exists, the
193 limit is often 15 characters (typical of formats related to a.out) or 16
194 characters (typical of formats related to coff).
195
196 @cindex libraries
197 @command{ar} is considered a binary utility because archives of this sort
198 are most often used as @dfn{libraries} holding commonly needed
199 subroutines.
200
201 @cindex symbol index
202 @command{ar} creates an index to the symbols defined in relocatable
203 object modules in the archive when you specify the modifier @samp{s}.
204 Once created, this index is updated in the archive whenever @command{ar}
205 makes a change to its contents (save for the @samp{q} update operation).
206 An archive with such an index speeds up linking to the library, and
207 allows routines in the library to call each other without regard to
208 their placement in the archive.
209
210 You may use @samp{nm -s} or @samp{nm --print-armap} to list this index
211 table.  If an archive lacks the table, another form of @command{ar} called
212 @command{ranlib} can be used to add just the table.
213
214 @cindex thin archives
215 @sc{gnu} @command{ar} can optionally create a @emph{thin} archive,
216 which contains a symbol index and references to the original copies
217 of the member files of the archives.  Such an archive is useful
218 for building libraries for use within a local build, where the
219 relocatable objects are expected to remain available, and copying the
220 contents of each object would only waste time and space.  Thin archives
221 are also @emph{flattened}, so that adding one or more archives to a
222 thin archive will add the elements of the nested archive individually.
223 The paths to the elements of the archive are stored relative to the
224 archive itself.
225
226 @cindex compatibility, @command{ar}
227 @cindex @command{ar} compatibility
228 @sc{gnu} @command{ar} is designed to be compatible with two different
229 facilities.  You can control its activity using command-line options,
230 like the different varieties of @command{ar} on Unix systems; or, if you
231 specify the single command-line option @option{-M}, you can control it
232 with a script supplied via standard input, like the MRI ``librarian''
233 program.
234
235 @c man end
236
237 @menu
238 * ar cmdline::                  Controlling @command{ar} on the command line
239 * ar scripts::                  Controlling @command{ar} with a script
240 @end menu
241
242 @page
243 @node ar cmdline
244 @section Controlling @command{ar} on the Command Line
245
246 @smallexample
247 @c man begin SYNOPSIS ar
248 ar [@option{--plugin} @var{name}] [@option{-X32_64}] [@option{-}]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
249 @c man end
250 @end smallexample
251
252 @cindex Unix compatibility, @command{ar}
253 When you use @command{ar} in the Unix style, @command{ar} insists on at least two
254 arguments to execute: one keyletter specifying the @emph{operation}
255 (optionally accompanied by other keyletters specifying
256 @emph{modifiers}), and the archive name to act on.
257
258 Most operations can also accept further @var{member} arguments,
259 specifying particular files to operate on.
260
261 @c man begin OPTIONS ar
262
263 @sc{gnu} @command{ar} allows you to mix the operation code @var{p} and modifier
264 flags @var{mod} in any order, within the first command-line argument.
265
266 If you wish, you may begin the first command-line argument with a
267 dash.
268
269 @cindex operations on archive
270 The @var{p} keyletter specifies what operation to execute; it may be
271 any of the following, but you must specify only one of them:
272
273 @table @samp
274 @item d
275 @cindex deleting from archive
276 @emph{Delete} modules from the archive.  Specify the names of modules to
277 be deleted as @var{member}@dots{}; the archive is untouched if you
278 specify no files to delete.
279
280 If you specify the @samp{v} modifier, @command{ar} lists each module
281 as it is deleted.
282
283 @item m
284 @cindex moving in archive
285 Use this operation to @emph{move} members in an archive.
286
287 The ordering of members in an archive can make a difference in how
288 programs are linked using the library, if a symbol is defined in more
289 than one member.
290
291 If no modifiers are used with @code{m}, any members you name in the
292 @var{member} arguments are moved to the @emph{end} of the archive;
293 you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a
294 specified place instead.
295
296 @item p
297 @cindex printing from archive
298 @emph{Print} the specified members of the archive, to the standard
299 output file.  If the @samp{v} modifier is specified, show the member
300 name before copying its contents to standard output.
301
302 If you specify no @var{member} arguments, all the files in the archive are
303 printed.
304
305 @item q
306 @cindex quick append to archive
307 @emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of
308 @var{archive}, without checking for replacement.
309
310 The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this
311 operation; new members are always placed at the end of the archive.
312
313 The modifier @samp{v} makes @command{ar} list each file as it is appended.
314
315 Since the point of this operation is speed, the archive's symbol table
316 index is not updated, even if it already existed; you can use @samp{ar s} or
317 @command{ranlib} explicitly to update the symbol table index.
318
319 However, too many different systems assume quick append rebuilds the
320 index, so @sc{gnu} @command{ar} implements @samp{q} as a synonym for @samp{r}.
321
322 @item r
323 @cindex replacement in archive
324 Insert the files @var{member}@dots{} into @var{archive} (with
325 @emph{replacement}). This operation differs from @samp{q} in that any
326 previously existing members are deleted if their names match those being
327 added.
328
329 If one of the files named in @var{member}@dots{} does not exist, @command{ar}
330 displays an error message, and leaves undisturbed any existing members
331 of the archive matching that name.
332
333 By default, new members are added at the end of the file; but you may
334 use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request
335 placement relative to some existing member.
336
337 The modifier @samp{v} used with this operation elicits a line of
338 output for each file inserted, along with one of the letters @samp{a} or
339 @samp{r} to indicate whether the file was appended (no old member
340 deleted) or replaced.
341
342 @item t
343 @cindex contents of archive
344 Display a @emph{table} listing the contents of @var{archive}, or those
345 of the files listed in @var{member}@dots{} that are present in the
346 archive.  Normally only the member name is shown; if you also want to
347 see the modes (permissions), timestamp, owner, group, and size, you can
348 request that by also specifying the @samp{v} modifier.
349
350 If you do not specify a @var{member}, all files in the archive
351 are listed.
352
353 @cindex repeated names in archive
354 @cindex name duplication in archive
355 If there is more than one file with the same name (say, @samp{fie}) in
356 an archive (say @samp{b.a}), @samp{ar t b.a fie} lists only the
357 first instance; to see them all, you must ask for a complete
358 listing---in our example, @samp{ar t b.a}.
359 @c WRS only; per Gumby, this is implementation-dependent, and in a more
360 @c recent case in fact works the other way.
361
362 @item x
363 @cindex extract from archive
364 @emph{Extract} members (named @var{member}) from the archive.  You can
365 use the @samp{v} modifier with this operation, to request that
366 @command{ar} list each name as it extracts it.
367
368 If you do not specify a @var{member}, all files in the archive
369 are extracted.
370
371 Files cannot be extracted from a thin archive.
372
373 @end table
374
375 A number of modifiers (@var{mod}) may immediately follow the @var{p}
376 keyletter, to specify variations on an operation's behavior:
377
378 @table @samp
379 @item a
380 @cindex relative placement in archive
381 Add new files @emph{after} an existing member of the
382 archive.  If you use the modifier @samp{a}, the name of an existing archive
383 member must be present as the @var{relpos} argument, before the
384 @var{archive} specification.
385
386 @item b
387 Add new files @emph{before} an existing member of the
388 archive.  If you use the modifier @samp{b}, the name of an existing archive
389 member must be present as the @var{relpos} argument, before the
390 @var{archive} specification.  (same as @samp{i}).
391
392 @item c
393 @cindex creating archives
394 @emph{Create} the archive.  The specified @var{archive} is always
395 created if it did not exist, when you request an update.  But a warning is
396 issued unless you specify in advance that you expect to create it, by
397 using this modifier.
398
399 @item D
400 @cindex deterministic archives
401 Operate in @emph{deterministic} mode.  When adding files and the archive
402 index use zero for UIDs, GIDs, timestamps, and use consistent file modes
403 for all files.  When this option is used, if @command{ar} is used with
404 identical options and identical input files, multiple runs will create
405 identical output files regardless of the input files' owners, groups,
406 file modes, or modification times.
407
408 @item f
409 Truncate names in the archive.  @sc{gnu} @command{ar} will normally permit file
410 names of any length.  This will cause it to create archives which are
411 not compatible with the native @command{ar} program on some systems.  If
412 this is a concern, the @samp{f} modifier may be used to truncate file
413 names when putting them in the archive.
414
415 @item i
416 Insert new files @emph{before} an existing member of the
417 archive.  If you use the modifier @samp{i}, the name of an existing archive
418 member must be present as the @var{relpos} argument, before the
419 @var{archive} specification.  (same as @samp{b}).
420
421 @item l
422 This modifier is accepted but not used.
423 @c whaffor ar l modifier??? presumably compat; with
424 @c what???---doc@@cygnus.com, 25jan91
425
426 @item N
427 Uses the @var{count} parameter.  This is used if there are multiple
428 entries in the archive with the same name.  Extract or delete instance
429 @var{count} of the given name from the archive.
430
431 @item o
432 @cindex dates in archive
433 Preserve the @emph{original} dates of members when extracting them.  If
434 you do not specify this modifier, files extracted from the archive
435 are stamped with the time of extraction.
436
437 @item P
438 Use the full path name when matching names in the archive.  @sc{gnu}
439 @command{ar} can not create an archive with a full path name (such archives
440 are not POSIX complaint), but other archive creators can.  This option
441 will cause @sc{gnu} @command{ar} to match file names using a complete path
442 name, which can be convenient when extracting a single file from an
443 archive created by another tool.
444
445 @item s
446 @cindex writing archive index
447 Write an object-file index into the archive, or update an existing one,
448 even if no other change is made to the archive.  You may use this modifier
449 flag either with any operation, or alone.  Running @samp{ar s} on an
450 archive is equivalent to running @samp{ranlib} on it.
451
452 @item S
453 @cindex not writing archive index
454 Do not generate an archive symbol table.  This can speed up building a
455 large library in several steps.  The resulting archive can not be used
456 with the linker.  In order to build a symbol table, you must omit the
457 @samp{S} modifier on the last execution of @samp{ar}, or you must run
458 @samp{ranlib} on the archive.
459
460 @item T
461 @cindex creating thin archive
462 Make the specified @var{archive} a @emph{thin} archive.  If it already
463 exists and is a regular archive, the existing members must be present
464 in the same directory as @var{archive}.
465
466 @item u
467 @cindex updating an archive
468 Normally, @samp{ar r}@dots{} inserts all files
469 listed into the archive.  If you would like to insert @emph{only} those
470 of the files you list that are newer than existing members of the same
471 names, use this modifier.  The @samp{u} modifier is allowed only for the
472 operation @samp{r} (replace).  In particular, the combination @samp{qu} is
473 not allowed, since checking the timestamps would lose any speed
474 advantage from the operation @samp{q}.
475
476 @item v
477 This modifier requests the @emph{verbose} version of an operation.  Many
478 operations display additional information, such as filenames processed,
479 when the modifier @samp{v} is appended.
480
481 @item V
482 This modifier shows the version number of @command{ar}.
483 @end table
484
485 @command{ar} ignores an initial option spelt @samp{-X32_64}, for
486 compatibility with AIX.  The behaviour produced by this option is the
487 default for @sc{gnu} @command{ar}.  @command{ar} does not support any of the other
488 @samp{-X} options; in particular, it does not support @option{-X32}
489 which is the default for AIX @command{ar}.
490
491 The optional command line switch @option{--plugin} @var{name} causes
492 @command{ar} to load the plugin called @var{name} which adds support
493 for more file formats.  This option is only available if the toolchain
494 has been built with plugin support enabled.
495
496 @c man end
497
498 @ignore
499 @c man begin SEEALSO ar
500 nm(1), ranlib(1), and the Info entries for @file{binutils}.
501 @c man end
502 @end ignore
503
504 @node ar scripts
505 @section Controlling @command{ar} with a Script
506
507 @smallexample
508 ar -M [ <@var{script} ]
509 @end smallexample
510
511 @cindex MRI compatibility, @command{ar}
512 @cindex scripts, @command{ar}
513 If you use the single command-line option @samp{-M} with @command{ar}, you
514 can control its operation with a rudimentary command language.  This
515 form of @command{ar} operates interactively if standard input is coming
516 directly from a terminal.  During interactive use, @command{ar} prompts for
517 input (the prompt is @samp{AR >}), and continues executing even after
518 errors.  If you redirect standard input to a script file, no prompts are
519 issued, and @command{ar} abandons execution (with a nonzero exit code)
520 on any error.
521
522 The @command{ar} command language is @emph{not} designed to be equivalent
523 to the command-line options; in fact, it provides somewhat less control
524 over archives.  The only purpose of the command language is to ease the
525 transition to @sc{gnu} @command{ar} for developers who already have scripts
526 written for the MRI ``librarian'' program.
527
528 The syntax for the @command{ar} command language is straightforward:
529 @itemize @bullet
530 @item
531 commands are recognized in upper or lower case; for example, @code{LIST}
532 is the same as @code{list}.  In the following descriptions, commands are
533 shown in upper case for clarity.
534
535 @item
536 a single command may appear on each line; it is the first word on the
537 line.
538
539 @item
540 empty lines are allowed, and have no effect.
541
542 @item
543 comments are allowed; text after either of the characters @samp{*}
544 or @samp{;} is ignored.
545
546 @item
547 Whenever you use a list of names as part of the argument to an @command{ar}
548 command, you can separate the individual names with either commas or
549 blanks.  Commas are shown in the explanations below, for clarity.
550
551 @item
552 @samp{+} is used as a line continuation character; if @samp{+} appears
553 at the end of a line, the text on the following line is considered part
554 of the current command.
555 @end itemize
556
557 Here are the commands you can use in @command{ar} scripts, or when using
558 @command{ar} interactively.  Three of them have special significance:
559
560 @code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is
561 a temporary file required for most of the other commands.
562
563 @code{SAVE} commits the changes so far specified by the script.  Prior
564 to @code{SAVE}, commands affect only the temporary copy of the current
565 archive.
566
567 @table @code
568 @item ADDLIB @var{archive}
569 @itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module})
570 Add all the contents of @var{archive} (or, if specified, each named
571 @var{module} from @var{archive}) to the current archive.
572
573 Requires prior use of @code{OPEN} or @code{CREATE}.
574
575 @item ADDMOD @var{member}, @var{member}, @dots{} @var{member}
576 @c FIXME! w/Replacement??  If so, like "ar r @var{archive} @var{names}"
577 @c        else like "ar q..."
578 Add each named @var{member} as a module in the current archive.
579
580 Requires prior use of @code{OPEN} or @code{CREATE}.
581
582 @item CLEAR
583 Discard the contents of the current archive, canceling the effect of
584 any operations since the last @code{SAVE}.  May be executed (with no
585 effect) even if  no current archive is specified.
586
587 @item CREATE @var{archive}
588 Creates an archive, and makes it the current archive (required for many
589 other commands).  The new archive is created with a temporary name; it
590 is not actually saved as @var{archive} until you use @code{SAVE}.
591 You can overwrite existing archives; similarly, the contents of any
592 existing file named @var{archive} will not be destroyed until @code{SAVE}.
593
594 @item DELETE @var{module}, @var{module}, @dots{} @var{module}
595 Delete each listed @var{module} from the current archive; equivalent to
596 @samp{ar -d @var{archive} @var{module} @dots{} @var{module}}.
597
598 Requires prior use of @code{OPEN} or @code{CREATE}.
599
600 @item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module})
601 @itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile}
602 List each named @var{module} present in @var{archive}.  The separate
603 command @code{VERBOSE} specifies the form of the output: when verbose
604 output is off, output is like that of @samp{ar -t @var{archive}
605 @var{module}@dots{}}.  When verbose output is on, the listing is like
606 @samp{ar -tv @var{archive} @var{module}@dots{}}.
607
608 Output normally goes to the standard output stream; however, if you
609 specify @var{outputfile} as a final argument, @command{ar} directs the
610 output to that file.
611
612 @item END
613 Exit from @command{ar}, with a @code{0} exit code to indicate successful
614 completion.  This command does not save the output file; if you have
615 changed the current archive since the last @code{SAVE} command, those
616 changes are lost.
617
618 @item EXTRACT @var{module}, @var{module}, @dots{} @var{module}
619 Extract each named @var{module} from the current archive, writing them
620 into the current directory as separate files.  Equivalent to @samp{ar -x
621 @var{archive} @var{module}@dots{}}.
622
623 Requires prior use of @code{OPEN} or @code{CREATE}.
624
625 @ignore
626 @c FIXME Tokens but no commands???
627 @item FULLDIR
628
629 @item HELP
630 @end ignore
631
632 @item LIST
633 Display full contents of the current archive, in ``verbose'' style
634 regardless of the state of @code{VERBOSE}.  The effect is like @samp{ar
635 tv @var{archive}}.  (This single command is a @sc{gnu} @command{ar}
636 enhancement, rather than present for MRI compatibility.)
637
638 Requires prior use of @code{OPEN} or @code{CREATE}.
639
640 @item OPEN @var{archive}
641 Opens an existing archive for use as the current archive (required for
642 many other commands).  Any changes as the result of subsequent commands
643 will not actually affect @var{archive} until you next use @code{SAVE}.
644
645 @item REPLACE @var{module}, @var{module}, @dots{} @var{module}
646 In the current archive, replace each existing @var{module} (named in
647 the @code{REPLACE} arguments) from files in the current working directory.
648 To execute this command without errors, both the file, and the module in
649 the current archive, must exist.
650
651 Requires prior use of @code{OPEN} or @code{CREATE}.
652
653 @item VERBOSE
654 Toggle an internal flag governing the output from @code{DIRECTORY}.
655 When the flag is on, @code{DIRECTORY} output matches output from
656 @samp{ar -tv }@dots{}.
657
658 @item SAVE
659 Commit your changes to the current archive, and actually save it as a
660 file with the name specified in the last @code{CREATE} or @code{OPEN}
661 command.
662
663 Requires prior use of @code{OPEN} or @code{CREATE}.
664
665 @end table
666
667 @iftex
668 @node ld
669 @chapter ld
670 @cindex linker
671 @kindex ld
672 The @sc{gnu} linker @command{ld} is now described in a separate manual.
673 @xref{Top,, Overview,, Using LD: the @sc{gnu} linker}.
674 @end iftex
675
676 @node nm
677 @chapter nm
678 @cindex symbols
679 @kindex nm
680
681 @c man title nm list symbols from object files
682
683 @smallexample
684 @c man begin SYNOPSIS nm
685 nm [@option{-a}|@option{--debug-syms}]
686    [@option{-g}|@option{--extern-only}][@option{--plugin} @var{name}]
687    [@option{-B}] [@option{-C}|@option{--demangle}[=@var{style}]] [@option{-D}|@option{--dynamic}]
688    [@option{-S}|@option{--print-size}] [@option{-s}|@option{--print-armap}]
689    [@option{-A}|@option{-o}|@option{--print-file-name}][@option{--special-syms}]
690    [@option{-n}|@option{-v}|@option{--numeric-sort}] [@option{-p}|@option{--no-sort}]
691    [@option{-r}|@option{--reverse-sort}] [@option{--size-sort}] [@option{-u}|@option{--undefined-only}]
692    [@option{-t} @var{radix}|@option{--radix=}@var{radix}] [@option{-P}|@option{--portability}]
693    [@option{--target=}@var{bfdname}] [@option{-f}@var{format}|@option{--format=}@var{format}]
694    [@option{--defined-only}] [@option{-l}|@option{--line-numbers}] [@option{--no-demangle}]
695    [@option{-V}|@option{--version}] [@option{-X 32_64}] [@option{--help}]  [@var{objfile}@dots{}]
696 @c man end
697 @end smallexample
698
699 @c man begin DESCRIPTION nm
700 @sc{gnu} @command{nm} lists the symbols from object files @var{objfile}@dots{}.
701 If no object files are listed as arguments, @command{nm} assumes the file
702 @file{a.out}.
703
704 For each symbol, @command{nm} shows:
705
706 @itemize @bullet
707 @item
708 The symbol value, in the radix selected by options (see below), or
709 hexadecimal by default.
710
711 @item
712 The symbol type.  At least the following types are used; others are, as
713 well, depending on the object file format.  If lowercase, the symbol is
714 local; if uppercase, the symbol is global (external).
715
716 @c Some more detail on exactly what these symbol types are used for
717 @c would be nice.
718 @table @code
719 @item A
720 The symbol's value is absolute, and will not be changed by further
721 linking.
722
723 @item B
724 @itemx b
725 The symbol is in the uninitialized data section (known as BSS).
726
727 @item C
728 The symbol is common.  Common symbols are uninitialized data.  When
729 linking, multiple common symbols may appear with the same name.  If the
730 symbol is defined anywhere, the common symbols are treated as undefined
731 references.
732 @ifclear man
733 For more details on common symbols, see the discussion of
734 --warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}.
735 @end ifclear
736
737 @item D
738 @itemx d
739 The symbol is in the initialized data section.
740
741 @item G
742 @itemx g
743 The symbol is in an initialized data section for small objects.  Some
744 object file formats permit more efficient access to small data objects,
745 such as a global int variable as opposed to a large global array.
746
747 @item i
748 For PE format files this indicates that the symbol is in a section
749 specific to the implementation of DLLs.  For ELF format files this
750 indicates that the symbol is an indirect function.  This is a GNU
751 extension to the standard set of ELF symbol types.  It indicates a
752 symbol which if referenced by a relocation does not evaluate to its
753 address, but instead must be invoked at runtime.  The runtime
754 execution will then return the value to be used in the relocation.
755
756 @item N
757 The symbol is a debugging symbol.
758
759 @item p
760 The symbols is in a stack unwind section.
761
762 @item R
763 @itemx r
764 The symbol is in a read only data section.
765
766 @item S
767 @itemx s
768 The symbol is in an uninitialized data section for small objects.
769
770 @item T
771 @itemx t
772 The symbol is in the text (code) section.
773
774 @item U
775 The symbol is undefined.
776
777 @item u
778 The symbol is a unique global symbol.  This is a GNU extension to the
779 standard set of ELF symbol bindings.  For such a symbol the dynamic linker
780 will make sure that in the entire process there is just one symbol with
781 this name and type in use.
782
783 @item V
784 @itemx v
785 The symbol is a weak object.  When a weak defined symbol is linked with
786 a normal defined symbol, the normal defined symbol is used with no error.
787 When a weak undefined symbol is linked and the symbol is not defined,
788 the value of the weak symbol becomes zero with no error.  On some
789 systems, uppercase indicates that a default value has been specified.
790
791 @item W
792 @itemx w
793 The symbol is a weak symbol that has not been specifically tagged as a
794 weak object symbol.  When a weak defined symbol is linked with a normal
795 defined symbol, the normal defined symbol is used with no error.
796 When a weak undefined symbol is linked and the symbol is not defined,
797 the value of the symbol is determined in a system-specific manner without
798 error.  On some systems, uppercase indicates that a default value has been
799 specified.
800
801 @item -
802 The symbol is a stabs symbol in an a.out object file.  In this case, the
803 next values printed are the stabs other field, the stabs desc field, and
804 the stab type.  Stabs symbols are used to hold debugging information.
805 @ifclear man
806 For more information, see @ref{Top,Stabs,Stabs Overview,stabs.info, The
807 ``stabs'' debug format}.
808 @end ifclear
809
810 @item ?
811 The symbol type is unknown, or object file format specific.
812 @end table
813
814 @item
815 The symbol name.
816 @end itemize
817
818 @c man end
819
820 @c man begin OPTIONS nm
821 The long and short forms of options, shown here as alternatives, are
822 equivalent.
823
824 @table @env
825 @item -A
826 @itemx -o
827 @itemx --print-file-name
828 @cindex input file name
829 @cindex file name
830 @cindex source file name
831 Precede each symbol by the name of the input file (or archive member)
832 in which it was found, rather than identifying the input file once only,
833 before all of its symbols.
834
835 @item -a
836 @itemx --debug-syms
837 @cindex debugging symbols
838 Display all symbols, even debugger-only symbols; normally these are not
839 listed.
840
841 @item -B
842 @cindex @command{nm} format
843 @cindex @command{nm} compatibility
844 The same as @option{--format=bsd} (for compatibility with the MIPS @command{nm}).
845
846 @item -C
847 @itemx --demangle[=@var{style}]
848 @cindex demangling in nm
849 Decode (@dfn{demangle}) low-level symbol names into user-level names.
850 Besides removing any initial underscore prepended by the system, this
851 makes C++ function names readable. Different compilers have different
852 mangling styles. The optional demangling style argument can be used to
853 choose an appropriate demangling style for your compiler. @xref{c++filt},
854 for more information on demangling.
855
856 @item --no-demangle
857 Do not demangle low-level symbol names.  This is the default.
858
859 @item -D
860 @itemx --dynamic
861 @cindex dynamic symbols
862 Display the dynamic symbols rather than the normal symbols.  This is
863 only meaningful for dynamic objects, such as certain types of shared
864 libraries.
865
866 @item -f @var{format}
867 @itemx --format=@var{format}
868 @cindex @command{nm} format
869 @cindex @command{nm} compatibility
870 Use the output format @var{format}, which can be @code{bsd},
871 @code{sysv}, or @code{posix}.  The default is @code{bsd}.
872 Only the first character of @var{format} is significant; it can be
873 either upper or lower case.
874
875 @item -g
876 @itemx --extern-only
877 @cindex external symbols
878 Display only external symbols.
879
880 @item --plugin @var{name}
881 @cindex load plugin
882 Load the plugin called @var{name} to add support for extra target
883 types.  This option is only available if the toolchain has been built
884 with plugin support enabled.
885
886 @item -l
887 @itemx --line-numbers
888 @cindex symbol line numbers
889 For each symbol, use debugging information to try to find a filename and
890 line number.  For a defined symbol, look for the line number of the
891 address of the symbol.  For an undefined symbol, look for the line
892 number of a relocation entry which refers to the symbol.  If line number
893 information can be found, print it after the other symbol information.
894
895 @item -n
896 @itemx -v
897 @itemx --numeric-sort
898 Sort symbols numerically by their addresses, rather than alphabetically
899 by their names.
900
901 @item -p
902 @itemx --no-sort
903 @cindex sorting symbols
904 Do not bother to sort the symbols in any order; print them in the order
905 encountered.
906
907 @item -P
908 @itemx --portability
909 Use the POSIX.2 standard output format instead of the default format.
910 Equivalent to @samp{-f posix}.
911
912 @item -S
913 @itemx --print-size
914 Print both value and size of defined symbols for the @code{bsd} output style.
915 This option has no effect for object formats that do not record symbol
916 sizes, unless @samp{--size-sort} is also used in which case a
917 calculated size is displayed.
918
919 @item -s
920 @itemx --print-armap
921 @cindex symbol index, listing
922 When listing symbols from archive members, include the index: a mapping
923 (stored in the archive by @command{ar} or @command{ranlib}) of which modules
924 contain definitions for which names.
925
926 @item -r
927 @itemx --reverse-sort
928 Reverse the order of the sort (whether numeric or alphabetic); let the
929 last come first.
930
931 @item --size-sort
932 Sort symbols by size.  The size is computed as the difference between
933 the value of the symbol and the value of the symbol with the next higher
934 value.  If the @code{bsd} output format is used the size of the symbol
935 is printed, rather than the value, and @samp{-S} must be used in order
936 both size and value to be printed.
937
938 @item --special-syms
939 Display symbols which have a target-specific special meaning.  These
940 symbols are usually used by the target for some special processing and
941 are not normally helpful when included included in the normal symbol
942 lists.  For example for ARM targets this option would skip the mapping
943 symbols used to mark transitions between ARM code, THUMB code and
944 data.
945
946 @item -t @var{radix}
947 @itemx --radix=@var{radix}
948 Use @var{radix} as the radix for printing the symbol values.  It must be
949 @samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal.
950
951 @item --target=@var{bfdname}
952 @cindex object code format
953 Specify an object code format other than your system's default format.
954 @xref{Target Selection}, for more information.
955
956 @item -u
957 @itemx --undefined-only
958 @cindex external symbols
959 @cindex undefined symbols
960 Display only undefined symbols (those external to each object file).
961
962 @item --defined-only
963 @cindex external symbols
964 @cindex undefined symbols
965 Display only defined symbols for each object file.
966
967 @item -V
968 @itemx --version
969 Show the version number of @command{nm} and exit.
970
971 @item -X
972 This option is ignored for compatibility with the AIX version of
973 @command{nm}.  It takes one parameter which must be the string
974 @option{32_64}.  The default mode of AIX @command{nm} corresponds
975 to @option{-X 32}, which is not supported by @sc{gnu} @command{nm}.
976
977 @item --help
978 Show a summary of the options to @command{nm} and exit.
979 @end table
980
981 @c man end
982
983 @ignore
984 @c man begin SEEALSO nm
985 ar(1), objdump(1), ranlib(1), and the Info entries for @file{binutils}.
986 @c man end
987 @end ignore
988
989 @node objcopy
990 @chapter objcopy
991
992 @c man title objcopy copy and translate object files
993
994 @smallexample
995 @c man begin SYNOPSIS objcopy
996 objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}]
997         [@option{-I} @var{bfdname}|@option{--input-target=}@var{bfdname}]
998         [@option{-O} @var{bfdname}|@option{--output-target=}@var{bfdname}]
999         [@option{-B} @var{bfdarch}|@option{--binary-architecture=}@var{bfdarch}]
1000         [@option{-S}|@option{--strip-all}]
1001         [@option{-g}|@option{--strip-debug}]
1002         [@option{-K} @var{symbolname}|@option{--keep-symbol=}@var{symbolname}]
1003         [@option{-N} @var{symbolname}|@option{--strip-symbol=}@var{symbolname}]
1004         [@option{--strip-unneeded-symbol=}@var{symbolname}]
1005         [@option{-G} @var{symbolname}|@option{--keep-global-symbol=}@var{symbolname}]
1006         [@option{--localize-hidden}]
1007         [@option{-L} @var{symbolname}|@option{--localize-symbol=}@var{symbolname}]
1008         [@option{--globalize-symbol=}@var{symbolname}]
1009         [@option{-W} @var{symbolname}|@option{--weaken-symbol=}@var{symbolname}]
1010         [@option{-w}|@option{--wildcard}]
1011         [@option{-x}|@option{--discard-all}]
1012         [@option{-X}|@option{--discard-locals}]
1013         [@option{-b} @var{byte}|@option{--byte=}@var{byte}]
1014         [@option{-i} @var{interleave}|@option{--interleave=}@var{interleave}]
1015         [@option{-j} @var{sectionname}|@option{--only-section=}@var{sectionname}]
1016         [@option{-R} @var{sectionname}|@option{--remove-section=}@var{sectionname}]
1017         [@option{-p}|@option{--preserve-dates}]
1018         [@option{--debugging}]
1019         [@option{--gap-fill=}@var{val}]
1020         [@option{--pad-to=}@var{address}]
1021         [@option{--set-start=}@var{val}]
1022         [@option{--adjust-start=}@var{incr}]
1023         [@option{--change-addresses=}@var{incr}]
1024         [@option{--change-section-address} @var{section}@{=,+,-@}@var{val}]
1025         [@option{--change-section-lma} @var{section}@{=,+,-@}@var{val}]
1026         [@option{--change-section-vma} @var{section}@{=,+,-@}@var{val}]
1027         [@option{--change-warnings}] [@option{--no-change-warnings}]
1028         [@option{--set-section-flags} @var{section}=@var{flags}]
1029         [@option{--add-section} @var{sectionname}=@var{filename}]
1030         [@option{--rename-section} @var{oldname}=@var{newname}[,@var{flags}]]
1031         [@option{--long-section-names} @{enable,disable,keep@}]
1032         [@option{--change-leading-char}] [@option{--remove-leading-char}]
1033         [@option{--reverse-bytes=}@var{num}]
1034         [@option{--srec-len=}@var{ival}] [@option{--srec-forceS3}]
1035         [@option{--redefine-sym} @var{old}=@var{new}]
1036         [@option{--redefine-syms=}@var{filename}]
1037         [@option{--weaken}]
1038         [@option{--keep-symbols=}@var{filename}]
1039         [@option{--strip-symbols=}@var{filename}]
1040         [@option{--strip-unneeded-symbols=}@var{filename}]
1041         [@option{--keep-global-symbols=}@var{filename}]
1042         [@option{--localize-symbols=}@var{filename}]
1043         [@option{--globalize-symbols=}@var{filename}]
1044         [@option{--weaken-symbols=}@var{filename}]
1045         [@option{--alt-machine-code=}@var{index}]
1046         [@option{--prefix-symbols=}@var{string}]
1047         [@option{--prefix-sections=}@var{string}]
1048         [@option{--prefix-alloc-sections=}@var{string}]
1049         [@option{--add-gnu-debuglink=}@var{path-to-file}]
1050         [@option{--keep-file-symbols}]
1051         [@option{--only-keep-debug}]
1052         [@option{--extract-symbol}]
1053         [@option{--writable-text}]
1054         [@option{--readonly-text}]
1055         [@option{--pure}]
1056         [@option{--impure}]
1057         [@option{--file-alignment=}@var{num}]
1058         [@option{--heap=}@var{size}]
1059         [@option{--image-base=}@var{address}]
1060         [@option{--section-alignment=}@var{num}]
1061         [@option{--stack=}@var{size}]
1062         [@option{--subsystem=}@var{which}:@var{major}.@var{minor}]
1063         [@option{-v}|@option{--verbose}]
1064         [@option{-V}|@option{--version}]
1065         [@option{--help}] [@option{--info}]
1066         @var{infile} [@var{outfile}]
1067 @c man end
1068 @end smallexample
1069
1070 @c man begin DESCRIPTION objcopy
1071 The @sc{gnu} @command{objcopy} utility copies the contents of an object
1072 file to another.  @command{objcopy} uses the @sc{gnu} @sc{bfd} Library to
1073 read and write the object files.  It can write the destination object
1074 file in a format different from that of the source object file.  The
1075 exact behavior of @command{objcopy} is controlled by command-line options.
1076 Note that @command{objcopy} should be able to copy a fully linked file
1077 between any two formats. However, copying a relocatable object file
1078 between any two formats may not work as expected.
1079
1080 @command{objcopy} creates temporary files to do its translations and
1081 deletes them afterward.  @command{objcopy} uses @sc{bfd} to do all its
1082 translation work; it has access to all the formats described in @sc{bfd}
1083 and thus is able to recognize most formats without being told
1084 explicitly.  @xref{BFD,,BFD,ld.info,Using LD}.
1085
1086 @command{objcopy} can be used to generate S-records by using an output
1087 target of @samp{srec} (e.g., use @samp{-O srec}).
1088
1089 @command{objcopy} can be used to generate a raw binary file by using an
1090 output target of @samp{binary} (e.g., use @option{-O binary}).  When
1091 @command{objcopy} generates a raw binary file, it will essentially produce
1092 a memory dump of the contents of the input object file.  All symbols and
1093 relocation information will be discarded.  The memory dump will start at
1094 the load address of the lowest section copied into the output file.
1095
1096 When generating an S-record or a raw binary file, it may be helpful to
1097 use @option{-S} to remove sections containing debugging information.  In
1098 some cases @option{-R} will be useful to remove sections which contain
1099 information that is not needed by the binary file.
1100
1101 Note---@command{objcopy} is not able to change the endianness of its input
1102 files.  If the input format has an endianness (some formats do not),
1103 @command{objcopy} can only copy the inputs into file formats that have the
1104 same endianness or which have no endianness (e.g., @samp{srec}).
1105 (However, see the @option{--reverse-bytes} option.)
1106
1107 @c man end
1108
1109 @c man begin OPTIONS objcopy
1110
1111 @table @env
1112 @item @var{infile}
1113 @itemx @var{outfile}
1114 The input and output files, respectively.
1115 If you do not specify @var{outfile}, @command{objcopy} creates a
1116 temporary file and destructively renames the result with
1117 the name of @var{infile}.
1118
1119 @item -I @var{bfdname}
1120 @itemx --input-target=@var{bfdname}
1121 Consider the source file's object format to be @var{bfdname}, rather than
1122 attempting to deduce it.  @xref{Target Selection}, for more information.
1123
1124 @item -O @var{bfdname}
1125 @itemx --output-target=@var{bfdname}
1126 Write the output file using the object format @var{bfdname}.
1127 @xref{Target Selection}, for more information.
1128
1129 @item -F @var{bfdname}
1130 @itemx --target=@var{bfdname}
1131 Use @var{bfdname} as the object format for both the input and the output
1132 file; i.e., simply transfer data from source to destination with no
1133 translation.  @xref{Target Selection}, for more information.
1134
1135 @item -B @var{bfdarch}
1136 @itemx --binary-architecture=@var{bfdarch}
1137 Useful when transforming a raw binary input file into an object file.
1138 In this case the output architecture can be set to @var{bfdarch}. This
1139 option will be ignored if the input file has a known @var{bfdarch}. You
1140 can access this binary data inside a program by referencing the special
1141 symbols that are created by the conversion process.  These symbols are
1142 called _binary_@var{objfile}_start, _binary_@var{objfile}_end and
1143 _binary_@var{objfile}_size.  e.g. you can transform a picture file into
1144 an object file and then access it in your code using these symbols.
1145
1146 @item -j @var{sectionname}
1147 @itemx --only-section=@var{sectionname}
1148 Copy only the named section from the input file to the output file.
1149 This option may be given more than once.  Note that using this option
1150 inappropriately may make the output file unusable.
1151
1152 @item -R @var{sectionname}
1153 @itemx --remove-section=@var{sectionname}
1154 Remove any section named @var{sectionname} from the output file.  This
1155 option may be given more than once.  Note that using this option
1156 inappropriately may make the output file unusable.
1157
1158 @item -S
1159 @itemx --strip-all
1160 Do not copy relocation and symbol information from the source file.
1161
1162 @item -g
1163 @itemx --strip-debug
1164 Do not copy debugging symbols or sections from the source file.
1165
1166 @item --strip-unneeded
1167 Strip all symbols that are not needed for relocation processing.
1168
1169 @item -K @var{symbolname}
1170 @itemx --keep-symbol=@var{symbolname}
1171 When stripping symbols, keep symbol @var{symbolname} even if it would
1172 normally be stripped.  This option may be given more than once.
1173
1174 @item -N @var{symbolname}
1175 @itemx --strip-symbol=@var{symbolname}
1176 Do not copy symbol @var{symbolname} from the source file.  This option
1177 may be given more than once.
1178
1179 @item --strip-unneeded-symbol=@var{symbolname}
1180 Do not copy symbol @var{symbolname} from the source file unless it is needed
1181 by a relocation.  This option may be given more than once.
1182
1183 @item -G @var{symbolname}
1184 @itemx --keep-global-symbol=@var{symbolname}
1185 Keep only symbol @var{symbolname} global.  Make all other symbols local
1186 to the file, so that they are not visible externally.  This option may
1187 be given more than once.
1188
1189 @item --localize-hidden
1190 In an ELF object, mark all symbols that have hidden or internal visibility
1191 as local.  This option applies on top of symbol-specific localization options
1192 such as @option{-L}.
1193
1194 @item -L @var{symbolname}
1195 @itemx --localize-symbol=@var{symbolname}
1196 Make symbol @var{symbolname} local to the file, so that it is not
1197 visible externally.  This option may be given more than once.
1198
1199 @item -W @var{symbolname}
1200 @itemx --weaken-symbol=@var{symbolname}
1201 Make symbol @var{symbolname} weak. This option may be given more than once.
1202
1203 @item --globalize-symbol=@var{symbolname}
1204 Give symbol @var{symbolname} global scoping so that it is visible
1205 outside of the file in which it is defined.  This option may be given
1206 more than once.
1207
1208 @item -w
1209 @itemx --wildcard
1210 Permit regular expressions in @var{symbolname}s used in other command
1211 line options.  The question mark (?), asterisk (*), backslash (\) and
1212 square brackets ([]) operators can be used anywhere in the symbol
1213 name.  If the first character of the symbol name is the exclamation
1214 point (!) then the sense of the switch is reversed for that symbol.
1215 For example:
1216
1217 @smallexample
1218   -w -W !foo -W fo*
1219 @end smallexample
1220
1221 would cause objcopy to weaken all symbols that start with ``fo''
1222 except for the symbol ``foo''.
1223
1224 @item -x
1225 @itemx --discard-all
1226 Do not copy non-global symbols from the source file.
1227 @c FIXME any reason to prefer "non-global" to "local" here?
1228
1229 @item -X
1230 @itemx --discard-locals
1231 Do not copy compiler-generated local symbols.
1232 (These usually start with @samp{L} or @samp{.}.)
1233
1234 @item -b @var{byte}
1235 @itemx --byte=@var{byte}
1236 Keep only every @var{byte}th byte of the input file (header data is not
1237 affected).  @var{byte} can be in the range from 0 to @var{interleave}-1,
1238 where @var{interleave} is given by the @option{-i} or @option{--interleave}
1239 option, or the default of 4.  This option is useful for creating files
1240 to program @sc{rom}.  It is typically used with an @code{srec} output
1241 target.
1242
1243 @item -i @var{interleave}
1244 @itemx --interleave=@var{interleave}
1245 Only copy one out of every @var{interleave} bytes.  Select which byte to
1246 copy with the @option{-b} or @option{--byte} option.  The default is 4.
1247 @command{objcopy} ignores this option if you do not specify either @option{-b} or
1248 @option{--byte}.
1249
1250 @item -p
1251 @itemx --preserve-dates
1252 Set the access and modification dates of the output file to be the same
1253 as those of the input file.
1254
1255 @item --debugging
1256 Convert debugging information, if possible.  This is not the default
1257 because only certain debugging formats are supported, and the
1258 conversion process can be time consuming.
1259
1260 @item --gap-fill @var{val}
1261 Fill gaps between sections with @var{val}.  This operation applies to
1262 the @emph{load address} (LMA) of the sections.  It is done by increasing
1263 the size of the section with the lower address, and filling in the extra
1264 space created with @var{val}.
1265
1266 @item --pad-to @var{address}
1267 Pad the output file up to the load address @var{address}.  This is
1268 done by increasing the size of the last section.  The extra space is
1269 filled in with the value specified by @option{--gap-fill} (default zero).
1270
1271 @item --set-start @var{val}
1272 Set the start address of the new file to @var{val}.  Not all object file
1273 formats support setting the start address.
1274
1275 @item --change-start @var{incr}
1276 @itemx --adjust-start @var{incr}
1277 @cindex changing start address
1278 Change the start address by adding @var{incr}.  Not all object file
1279 formats support setting the start address.
1280
1281 @item --change-addresses @var{incr}
1282 @itemx --adjust-vma @var{incr}
1283 @cindex changing object addresses
1284 Change the VMA and LMA addresses of all sections, as well as the start
1285 address, by adding @var{incr}.  Some object file formats do not permit
1286 section addresses to be changed arbitrarily.  Note that this does not
1287 relocate the sections; if the program expects sections to be loaded at a
1288 certain address, and this option is used to change the sections such
1289 that they are loaded at a different address, the program may fail.
1290
1291 @item --change-section-address @var{section}@{=,+,-@}@var{val}
1292 @itemx --adjust-section-vma @var{section}@{=,+,-@}@var{val}
1293 @cindex changing section address
1294 Set or change both the VMA address and the LMA address of the named
1295 @var{section}.  If @samp{=} is used, the section address is set to
1296 @var{val}.  Otherwise, @var{val} is added to or subtracted from the
1297 section address.  See the comments under @option{--change-addresses},
1298 above. If @var{section} does not exist in the input file, a warning will
1299 be issued, unless @option{--no-change-warnings} is used.
1300
1301 @item --change-section-lma @var{section}@{=,+,-@}@var{val}
1302 @cindex changing section LMA
1303 Set or change the LMA address of the named @var{section}.  The LMA
1304 address is the address where the section will be loaded into memory at
1305 program load time.  Normally this is the same as the VMA address, which
1306 is the address of the section at program run time, but on some systems,
1307 especially those where a program is held in ROM, the two can be
1308 different.  If @samp{=} is used, the section address is set to
1309 @var{val}.  Otherwise, @var{val} is added to or subtracted from the
1310 section address.  See the comments under @option{--change-addresses},
1311 above.  If @var{section} does not exist in the input file, a warning
1312 will be issued, unless @option{--no-change-warnings} is used.
1313
1314 @item --change-section-vma @var{section}@{=,+,-@}@var{val}
1315 @cindex changing section VMA
1316 Set or change the VMA address of the named @var{section}.  The VMA
1317 address is the address where the section will be located once the
1318 program has started executing.  Normally this is the same as the LMA
1319 address, which is the address where the section will be loaded into
1320 memory, but on some systems, especially those where a program is held in
1321 ROM, the two can be different.  If @samp{=} is used, the section address
1322 is set to @var{val}.  Otherwise, @var{val} is added to or subtracted
1323 from the section address.  See the comments under
1324 @option{--change-addresses}, above.  If @var{section} does not exist in
1325 the input file, a warning will be issued, unless
1326 @option{--no-change-warnings} is used.
1327
1328 @item --change-warnings
1329 @itemx --adjust-warnings
1330 If @option{--change-section-address} or @option{--change-section-lma} or
1331 @option{--change-section-vma} is used, and the named section does not
1332 exist, issue a warning.  This is the default.
1333
1334 @item --no-change-warnings
1335 @itemx --no-adjust-warnings
1336 Do not issue a warning if @option{--change-section-address} or
1337 @option{--adjust-section-lma} or @option{--adjust-section-vma} is used, even
1338 if the named section does not exist.
1339
1340 @item --set-section-flags @var{section}=@var{flags}
1341 Set the flags for the named section.  The @var{flags} argument is a
1342 comma separated string of flag names.  The recognized names are
1343 @samp{alloc}, @samp{contents}, @samp{load}, @samp{noload},
1344 @samp{readonly}, @samp{code}, @samp{data}, @samp{rom}, @samp{share}, and
1345 @samp{debug}.  You can set the @samp{contents} flag for a section which
1346 does not have contents, but it is not meaningful to clear the
1347 @samp{contents} flag of a section which does have contents--just remove
1348 the section instead.  Not all flags are meaningful for all object file
1349 formats.
1350
1351 @item --add-section @var{sectionname}=@var{filename}
1352 Add a new section named @var{sectionname} while copying the file.  The
1353 contents of the new section are taken from the file @var{filename}.  The
1354 size of the section will be the size of the file.  This option only
1355 works on file formats which can support sections with arbitrary names.
1356
1357 @item --rename-section @var{oldname}=@var{newname}[,@var{flags}]
1358 Rename a section from @var{oldname} to @var{newname}, optionally
1359 changing the section's flags to @var{flags} in the process.  This has
1360 the advantage over usng a linker script to perform the rename in that
1361 the output stays as an object file and does not become a linked
1362 executable.
1363
1364 This option is particularly helpful when the input format is binary,
1365 since this will always create a section called .data.  If for example,
1366 you wanted instead to create a section called .rodata containing binary
1367 data you could use the following command line to achieve it:
1368
1369 @smallexample
1370   objcopy -I binary -O <output_format> -B <architecture> \
1371    --rename-section .data=.rodata,alloc,load,readonly,data,contents \
1372    <input_binary_file> <output_object_file>
1373 @end smallexample
1374
1375 @item --long-section-names @{enable,disable,keep@}
1376 Controls the handling of long section names when processing @code{COFF}
1377 and @code{PE-COFF} object formats.  The default behaviour, @samp{keep},
1378 is to preserve long section names if any are present in the input file.
1379 The @samp{enable} and @samp{disable} options forcibly enable or disable
1380 the use of long section names in the output object; when @samp{disable}
1381 is in effect, any long section names in the input object will be truncated.
1382 The @samp{enable} option will only emit long section names if any are
1383 present in the inputs; this is mostly the same as @samp{keep}, but it
1384 is left undefined whether the @samp{enable} option might force the 
1385 creation of an empty string table in the output file.
1386
1387 @item --change-leading-char
1388 Some object file formats use special characters at the start of
1389 symbols.  The most common such character is underscore, which compilers
1390 often add before every symbol.  This option tells @command{objcopy} to
1391 change the leading character of every symbol when it converts between
1392 object file formats.  If the object file formats use the same leading
1393 character, this option has no effect.  Otherwise, it will add a
1394 character, or remove a character, or change a character, as
1395 appropriate.
1396
1397 @item --remove-leading-char
1398 If the first character of a global symbol is a special symbol leading
1399 character used by the object file format, remove the character.  The
1400 most common symbol leading character is underscore.  This option will
1401 remove a leading underscore from all global symbols.  This can be useful
1402 if you want to link together objects of different file formats with
1403 different conventions for symbol names.  This is different from
1404 @option{--change-leading-char} because it always changes the symbol name
1405 when appropriate, regardless of the object file format of the output
1406 file.
1407
1408 @item --reverse-bytes=@var{num}
1409 Reverse the bytes in a section with output contents.  A section length must
1410 be evenly divisible by the value given in order for the swap to be able to
1411 take place. Reversing takes place before the interleaving is performed.
1412
1413 This option is used typically in generating ROM images for problematic
1414 target systems.  For example, on some target boards, the 32-bit words
1415 fetched from 8-bit ROMs are re-assembled in little-endian byte order
1416 regardless of the CPU byte order.  Depending on the programming model, the
1417 endianness of the ROM may need to be modified.
1418
1419 Consider a simple file with a section containing the following eight
1420 bytes:  @code{12345678}.
1421
1422 Using @samp{--reverse-bytes=2} for the above example, the bytes in the
1423 output file would be ordered @code{21436587}.
1424
1425 Using @samp{--reverse-bytes=4} for the above example, the bytes in the
1426 output file would be ordered @code{43218765}.
1427
1428 By using @samp{--reverse-bytes=2} for the above example, followed by
1429 @samp{--reverse-bytes=4} on the output file, the bytes in the second
1430 output file would be ordered @code{34127856}.
1431
1432 @item --srec-len=@var{ival}
1433 Meaningful only for srec output.  Set the maximum length of the Srecords
1434 being produced to @var{ival}.  This length covers both address, data and
1435 crc fields.
1436
1437 @item --srec-forceS3
1438 Meaningful only for srec output.  Avoid generation of S1/S2 records,
1439 creating S3-only record format.
1440
1441 @item --redefine-sym @var{old}=@var{new}
1442 Change the name of a symbol @var{old}, to @var{new}.  This can be useful
1443 when one is trying link two things together for which you have no
1444 source, and there are name collisions.
1445
1446 @item --redefine-syms=@var{filename}
1447 Apply @option{--redefine-sym} to each symbol pair "@var{old} @var{new}"
1448 listed in the file @var{filename}.  @var{filename} is simply a flat file,
1449 with one symbol pair per line.  Line comments may be introduced by the hash
1450 character.  This option may be given more than once.
1451
1452 @item --weaken
1453 Change all global symbols in the file to be weak.  This can be useful
1454 when building an object which will be linked against other objects using
1455 the @option{-R} option to the linker.  This option is only effective when
1456 using an object file format which supports weak symbols.
1457
1458 @item --keep-symbols=@var{filename}
1459 Apply @option{--keep-symbol} option to each symbol listed in the file
1460 @var{filename}.  @var{filename} is simply a flat file, with one symbol
1461 name per line.  Line comments may be introduced by the hash character.
1462 This option may be given more than once.
1463
1464 @item --strip-symbols=@var{filename}
1465 Apply @option{--strip-symbol} option to each symbol listed in the file
1466 @var{filename}.  @var{filename} is simply a flat file, with one symbol
1467 name per line.  Line comments may be introduced by the hash character.
1468 This option may be given more than once.
1469
1470 @item --strip-unneeded-symbols=@var{filename}
1471 Apply @option{--strip-unneeded-symbol} option to each symbol listed in
1472 the file @var{filename}.  @var{filename} is simply a flat file, with one
1473 symbol name per line.  Line comments may be introduced by the hash
1474 character.  This option may be given more than once.
1475
1476 @item --keep-global-symbols=@var{filename}
1477 Apply @option{--keep-global-symbol} option to each symbol listed in the
1478 file @var{filename}.  @var{filename} is simply a flat file, with one
1479 symbol name per line.  Line comments may be introduced by the hash
1480 character.  This option may be given more than once.
1481
1482 @item --localize-symbols=@var{filename}
1483 Apply @option{--localize-symbol} option to each symbol listed in the file
1484 @var{filename}.  @var{filename} is simply a flat file, with one symbol
1485 name per line.  Line comments may be introduced by the hash character.
1486 This option may be given more than once.
1487
1488 @item --globalize-symbols=@var{filename}
1489 Apply @option{--globalize-symbol} option to each symbol listed in the file
1490 @var{filename}.  @var{filename} is simply a flat file, with one symbol
1491 name per line.  Line comments may be introduced by the hash character.
1492 This option may be given more than once.
1493
1494 @item --weaken-symbols=@var{filename}
1495 Apply @option{--weaken-symbol} option to each symbol listed in the file
1496 @var{filename}.  @var{filename} is simply a flat file, with one symbol
1497 name per line.  Line comments may be introduced by the hash character.
1498 This option may be given more than once.
1499
1500 @item --alt-machine-code=@var{index}
1501 If the output architecture has alternate machine codes, use the
1502 @var{index}th code instead of the default one.  This is useful in case
1503 a machine is assigned an official code and the tool-chain adopts the
1504 new code, but other applications still depend on the original code
1505 being used.  For ELF based architectures if the @var{index}
1506 alternative does not exist then the value is treated as an absolute
1507 number to be stored in the e_machine field of the ELF header.
1508
1509 @item --writable-text
1510 Mark the output text as writable.  This option isn't meaningful for all
1511 object file formats.
1512
1513 @item --readonly-text
1514 Make the output text write protected.  This option isn't meaningful for all
1515 object file formats.
1516
1517 @item --pure
1518 Mark the output file as demand paged.  This option isn't meaningful for all
1519 object file formats.
1520
1521 @item --impure
1522 Mark the output file as impure.  This option isn't meaningful for all
1523 object file formats.
1524
1525 @item --prefix-symbols=@var{string}
1526 Prefix all symbols in the output file with @var{string}.
1527
1528 @item --prefix-sections=@var{string}
1529 Prefix all section names in the output file with @var{string}.
1530
1531 @item --prefix-alloc-sections=@var{string}
1532 Prefix all the names of all allocated sections in the output file with
1533 @var{string}.
1534
1535 @item --add-gnu-debuglink=@var{path-to-file}
1536 Creates a .gnu_debuglink section which contains a reference to @var{path-to-file}
1537 and adds it to the output file.
1538
1539 @item --keep-file-symbols
1540 When stripping a file, perhaps with @option{--strip-debug} or
1541 @option{--strip-unneeded}, retain any symbols specifying source file names,
1542 which would otherwise get stripped.
1543
1544 @item --only-keep-debug
1545 Strip a file, removing contents of any sections that would not be
1546 stripped by @option{--strip-debug} and leaving the debugging sections
1547 intact.  In ELF files, this preserves all note sections in the output.
1548
1549 The intention is that this option will be used in conjunction with
1550 @option{--add-gnu-debuglink} to create a two part executable.  One a
1551 stripped binary which will occupy less space in RAM and in a
1552 distribution and the second a debugging information file which is only
1553 needed if debugging abilities are required.  The suggested procedure
1554 to create these files is as follows:
1555
1556 @enumerate
1557 @item Link the executable as normal.  Assuming that is is called
1558 @code{foo} then...
1559 @item Run @code{objcopy --only-keep-debug foo foo.dbg} to
1560 create a file containing the debugging info.
1561 @item Run @code{objcopy --strip-debug foo} to create a
1562 stripped executable.
1563 @item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo}
1564 to add a link to the debugging info into the stripped executable.
1565 @end enumerate
1566
1567 Note---the choice of @code{.dbg} as an extension for the debug info
1568 file is arbitrary.  Also the @code{--only-keep-debug} step is
1569 optional.  You could instead do this:
1570
1571 @enumerate
1572 @item Link the executable as normal.
1573 @item Copy @code{foo} to  @code{foo.full}
1574 @item Run @code{objcopy --strip-debug foo}
1575 @item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
1576 @end enumerate
1577
1578 i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the
1579 full executable.  It does not have to be a file created by the
1580 @option{--only-keep-debug} switch.
1581
1582 Note---this switch is only intended for use on fully linked files.  It
1583 does not make sense to use it on object files where the debugging
1584 information may be incomplete.  Besides the gnu_debuglink feature
1585 currently only supports the presence of one filename containing
1586 debugging information, not multiple filenames on a one-per-object-file
1587 basis.
1588
1589 @item --file-alignment @var{num}
1590 Specify the file alignment.  Sections in the file will always begin at
1591 file offsets which are multiples of this number.  This defaults to
1592 512.
1593 [This option is specific to PE targets.]
1594
1595 @item --heap @var{reserve}
1596 @itemx --heap @var{reserve},@var{commit}
1597 Specify the number of bytes of memory to reserve (and optionally commit)
1598 to be used as heap for this program.
1599 [This option is specific to PE targets.]
1600
1601 @item --image-base @var{value}
1602 Use @var{value} as the base address of your program or dll.  This is
1603 the lowest memory location that will be used when your program or dll
1604 is loaded.  To reduce the need to relocate and improve performance of
1605 your dlls, each should have a unique base address and not overlap any
1606 other dlls.  The default is 0x400000 for executables, and 0x10000000
1607 for dlls.
1608 [This option is specific to PE targets.]
1609
1610 @item --section-alignment @var{num}
1611 Sets the section alignment.  Sections in memory will always begin at
1612 addresses which are a multiple of this number.  Defaults to 0x1000.
1613 [This option is specific to PE targets.]
1614
1615 @item --stack @var{reserve}
1616 @itemx --stack @var{reserve},@var{commit}
1617 Specify the number of bytes of memory to reserve (and optionally commit)
1618 to be used as stack for this program.
1619 [This option is specific to PE targets.]
1620
1621 @item --subsystem @var{which}
1622 @itemx --subsystem @var{which}:@var{major}
1623 @itemx --subsystem @var{which}:@var{major}.@var{minor}
1624 Specifies the subsystem under which your program will execute.  The
1625 legal values for @var{which} are @code{native}, @code{windows},
1626 @code{console}, @code{posix}, @code{efi-app}, @code{efi-bsd},
1627 @code{efi-rtd}, @code{sal-rtd}, and @code{xbox}.  You may optionally set
1628 the subsystem version also.  Numeric values are also accepted for
1629 @var{which}.
1630 [This option is specific to PE targets.]
1631
1632 @item --extract-symbol
1633 Keep the file's section flags and symbols but remove all section data.
1634 Specifically, the option:
1635
1636 @itemize
1637 @item removes the contents of all sections;
1638 @item sets the size of every section to zero; and
1639 @item sets the file's start address to zero.
1640 @end itemize
1641
1642 This option is used to build a @file{.sym} file for a VxWorks kernel.
1643 It can also be a useful way of reducing the size of a @option{--just-symbols}
1644 linker input file.
1645
1646 @item -V
1647 @itemx --version
1648 Show the version number of @command{objcopy}.
1649
1650 @item -v
1651 @itemx --verbose
1652 Verbose output: list all object files modified.  In the case of
1653 archives, @samp{objcopy -V} lists all members of the archive.
1654
1655 @item --help
1656 Show a summary of the options to @command{objcopy}.
1657
1658 @item --info
1659 Display a list showing all architectures and object formats available.
1660 @end table
1661
1662 @c man end
1663
1664 @ignore
1665 @c man begin SEEALSO objcopy
1666 ld(1), objdump(1), and the Info entries for @file{binutils}.
1667 @c man end
1668 @end ignore
1669
1670 @node objdump
1671 @chapter objdump
1672
1673 @cindex object file information
1674 @kindex objdump
1675
1676 @c man title objdump display information from object files.
1677
1678 @smallexample
1679 @c man begin SYNOPSIS objdump
1680 objdump [@option{-a}|@option{--archive-headers}]
1681         [@option{-b} @var{bfdname}|@option{--target=@var{bfdname}}]
1682         [@option{-C}|@option{--demangle}[=@var{style}] ]
1683         [@option{-d}|@option{--disassemble}]
1684         [@option{-D}|@option{--disassemble-all}]
1685         [@option{-z}|@option{--disassemble-zeroes}]
1686         [@option{-EB}|@option{-EL}|@option{--endian=}@{big | little @}]
1687         [@option{-f}|@option{--file-headers}]
1688         [@option{-F}|@option{--file-offsets}]
1689         [@option{--file-start-context}]
1690         [@option{-g}|@option{--debugging}]
1691         [@option{-e}|@option{--debugging-tags}]
1692         [@option{-h}|@option{--section-headers}|@option{--headers}]
1693         [@option{-i}|@option{--info}]
1694         [@option{-j} @var{section}|@option{--section=}@var{section}]
1695         [@option{-l}|@option{--line-numbers}]
1696         [@option{-S}|@option{--source}]
1697         [@option{-m} @var{machine}|@option{--architecture=}@var{machine}]
1698         [@option{-M} @var{options}|@option{--disassembler-options=}@var{options}]
1699         [@option{-p}|@option{--private-headers}]
1700         [@option{-r}|@option{--reloc}]
1701         [@option{-R}|@option{--dynamic-reloc}]
1702         [@option{-s}|@option{--full-contents}]
1703         [@option{-W[lLiaprmfFsoR]}|
1704          @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]]
1705         [@option{-G}|@option{--stabs}]
1706         [@option{-t}|@option{--syms}]
1707         [@option{-T}|@option{--dynamic-syms}]
1708         [@option{-x}|@option{--all-headers}]
1709         [@option{-w}|@option{--wide}]
1710         [@option{--start-address=}@var{address}]
1711         [@option{--stop-address=}@var{address}]
1712         [@option{--prefix-addresses}]
1713         [@option{--[no-]show-raw-insn}]
1714         [@option{--adjust-vma=}@var{offset}]
1715         [@option{--special-syms}]
1716         [@option{--prefix=}@var{prefix}]
1717         [@option{--prefix-strip=}@var{level}]
1718         [@option{--insn-width=}@var{width}]
1719         [@option{-V}|@option{--version}]
1720         [@option{-H}|@option{--help}]
1721         @var{objfile}@dots{}
1722 @c man end
1723 @end smallexample
1724
1725 @c man begin DESCRIPTION objdump
1726
1727 @command{objdump} displays information about one or more object files.
1728 The options control what particular information to display.  This
1729 information is mostly useful to programmers who are working on the
1730 compilation tools, as opposed to programmers who just want their
1731 program to compile and work.
1732
1733 @var{objfile}@dots{} are the object files to be examined.  When you
1734 specify archives, @command{objdump} shows information on each of the member
1735 object files.
1736
1737 @c man end
1738
1739 @c man begin OPTIONS objdump
1740
1741 The long and short forms of options, shown here as alternatives, are
1742 equivalent.  At least one option from the list
1743 @option{-a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x} must be given.
1744
1745 @table @env
1746 @item -a
1747 @itemx --archive-header
1748 @cindex archive headers
1749 If any of the @var{objfile} files are archives, display the archive
1750 header information (in a format similar to @samp{ls -l}).  Besides the
1751 information you could list with @samp{ar tv}, @samp{objdump -a} shows
1752 the object file format of each archive member.
1753
1754 @item --adjust-vma=@var{offset}
1755 @cindex section addresses in objdump
1756 @cindex VMA in objdump
1757 When dumping information, first add @var{offset} to all the section
1758 addresses.  This is useful if the section addresses do not correspond to
1759 the symbol table, which can happen when putting sections at particular
1760 addresses when using a format which can not represent section addresses,
1761 such as a.out.
1762
1763 @item -b @var{bfdname}
1764 @itemx --target=@var{bfdname}
1765 @cindex object code format
1766 Specify that the object-code format for the object files is
1767 @var{bfdname}.  This option may not be necessary; @var{objdump} can
1768 automatically recognize many formats.
1769
1770 For example,
1771 @example
1772 objdump -b oasys -m vax -h fu.o
1773 @end example
1774 @noindent
1775 displays summary information from the section headers (@option{-h}) of
1776 @file{fu.o}, which is explicitly identified (@option{-m}) as a VAX object
1777 file in the format produced by Oasys compilers.  You can list the
1778 formats available with the @option{-i} option.
1779 @xref{Target Selection}, for more information.
1780
1781 @item -C
1782 @itemx --demangle[=@var{style}]
1783 @cindex demangling in objdump
1784 Decode (@dfn{demangle}) low-level symbol names into user-level names.
1785 Besides removing any initial underscore prepended by the system, this
1786 makes C++ function names readable.  Different compilers have different
1787 mangling styles. The optional demangling style argument can be used to
1788 choose an appropriate demangling style for your compiler. @xref{c++filt},
1789 for more information on demangling.
1790
1791 @item -g
1792 @itemx --debugging
1793 Display debugging information.  This attempts to parse STABS and IEEE
1794 debugging format information stored in the file and print it out using
1795 a C like syntax.  If neither of these formats are found this option
1796 falls back on the @option{-W} option to print any DWARF information in
1797 the file.
1798
1799 @item -e
1800 @itemx --debugging-tags
1801 Like @option{-g}, but the information is generated in a format compatible
1802 with ctags tool.
1803
1804 @item -d
1805 @itemx --disassemble
1806 @cindex disassembling object code
1807 @cindex machine instructions
1808 Display the assembler mnemonics for the machine instructions from
1809 @var{objfile}.  This option only disassembles those sections which are
1810 expected to contain instructions.
1811
1812 @item -D
1813 @itemx --disassemble-all
1814 Like @option{-d}, but disassemble the contents of all sections, not just
1815 those expected to contain instructions.
1816
1817 If the target is an ARM architecture this switch also has the effect
1818 of forcing the disassembler to decode pieces of data found in code
1819 sections as if they were instructions.
1820
1821 @item --prefix-addresses
1822 When disassembling, print the complete address on each line.  This is
1823 the older disassembly format.
1824
1825 @item -EB
1826 @itemx -EL
1827 @itemx --endian=@{big|little@}
1828 @cindex endianness
1829 @cindex disassembly endianness
1830 Specify the endianness of the object files.  This only affects
1831 disassembly.  This can be useful when disassembling a file format which
1832 does not describe endianness information, such as S-records.
1833
1834 @item -f
1835 @itemx --file-headers
1836 @cindex object file header
1837 Display summary information from the overall header of
1838 each of the @var{objfile} files.
1839
1840 @item -F
1841 @itemx --file-offsets
1842 @cindex object file offsets
1843 When disassembling sections, whenever a symbol is displayed, also
1844 display the file offset of the region of data that is about to be
1845 dumped.  If zeroes are being skipped, then when disassembly resumes,
1846 tell the user how many zeroes were skipped and the file offset of the
1847 location from where the disassembly resumes.  When dumping sections,
1848 display the file offset of the location from where the dump starts.
1849
1850 @item --file-start-context
1851 @cindex source code context
1852 Specify that when displaying interlisted source code/disassembly
1853 (assumes @option{-S}) from a file that has not yet been displayed, extend the
1854 context to the start of the file.
1855
1856 @item -h
1857 @itemx --section-headers
1858 @itemx --headers
1859 @cindex section headers
1860 Display summary information from the section headers of the
1861 object file.
1862
1863 File segments may be relocated to nonstandard addresses, for example by
1864 using the @option{-Ttext}, @option{-Tdata}, or @option{-Tbss} options to
1865 @command{ld}.  However, some object file formats, such as a.out, do not
1866 store the starting address of the file segments.  In those situations,
1867 although @command{ld} relocates the sections correctly, using @samp{objdump
1868 -h} to list the file section headers cannot show the correct addresses.
1869 Instead, it shows the usual addresses, which are implicit for the
1870 target.
1871
1872 @item -H
1873 @itemx --help
1874 Print a summary of the options to @command{objdump} and exit.
1875
1876 @item -i
1877 @itemx --info
1878 @cindex architectures available
1879 @cindex object formats available
1880 Display a list showing all architectures and object formats available
1881 for specification with @option{-b} or @option{-m}.
1882
1883 @item -j @var{name}
1884 @itemx --section=@var{name}
1885 @cindex section information
1886 Display information only for section @var{name}.
1887
1888 @item -l
1889 @itemx --line-numbers
1890 @cindex source filenames for object files
1891 Label the display (using debugging information) with the filename and
1892 source line numbers corresponding to the object code or relocs shown.
1893 Only useful with @option{-d}, @option{-D}, or @option{-r}.
1894
1895 @item -m @var{machine}
1896 @itemx --architecture=@var{machine}
1897 @cindex architecture
1898 @cindex disassembly architecture
1899 Specify the architecture to use when disassembling object files.  This
1900 can be useful when disassembling object files which do not describe
1901 architecture information, such as S-records.  You can list the available
1902 architectures with the @option{-i} option.
1903
1904 If the target is an ARM architecture then this switch has an
1905 additional effect.  It restricts the disassembly to only those
1906 instructions supported by the architecture specified by @var{machine}.
1907 If it is necessary to use this switch because the input file does not
1908 contain any architecture information, but it is also desired to
1909 disassemble all the instructions use @option{-marm}.
1910
1911 @item -M @var{options}
1912 @itemx --disassembler-options=@var{options}
1913 Pass target specific information to the disassembler.  Only supported on
1914 some targets.  If it is necessary to specify more than one
1915 disassembler option then multiple @option{-M} options can be used or
1916 can be placed together into a comma separated list.
1917
1918 If the target is an ARM architecture then this switch can be used to
1919 select which register name set is used during disassembler.  Specifying
1920 @option{-M reg-names-std} (the default) will select the register names as
1921 used in ARM's instruction set documentation, but with register 13 called
1922 'sp', register 14 called 'lr' and register 15 called 'pc'.  Specifying
1923 @option{-M reg-names-apcs} will select the name set used by the ARM
1924 Procedure Call Standard, whilst specifying @option{-M reg-names-raw} will
1925 just use @samp{r} followed by the register number.
1926
1927 There are also two variants on the APCS register naming scheme enabled
1928 by @option{-M reg-names-atpcs} and @option{-M reg-names-special-atpcs} which
1929 use the ARM/Thumb Procedure Call Standard naming conventions.  (Either
1930 with the normal register names or the special register names).
1931
1932 This option can also be used for ARM architectures to force the
1933 disassembler to interpret all instructions as Thumb instructions by
1934 using the switch @option{--disassembler-options=force-thumb}.  This can be
1935 useful when attempting to disassemble thumb code produced by other
1936 compilers.
1937
1938 For the x86, some of the options duplicate functions of the @option{-m}
1939 switch, but allow finer grained control.  Multiple selections from the
1940 following may be specified as a comma separated string.
1941 @option{x86-64}, @option{i386} and @option{i8086} select disassembly for
1942 the given architecture.  @option{intel} and @option{att} select between
1943 intel syntax mode and AT&T syntax mode.
1944 @option{intel-mnemonic} and @option{att-mnemonic} select between
1945 intel mnemonic mode and AT&T mnemonic mode. @option{intel-mnemonic}
1946 implies @option{intel} and @option{att-mnemonic} implies @option{att}.
1947 @option{addr64}, @option{addr32},
1948 @option{addr16}, @option{data32} and @option{data16} specify the default
1949 address size and operand size.  These four options will be overridden if
1950 @option{x86-64}, @option{i386} or @option{i8086} appear later in the
1951 option string.  Lastly, @option{suffix}, when in AT&T mode,
1952 instructs the disassembler to print a mnemonic suffix even when the
1953 suffix could be inferred by the operands.
1954
1955 For PowerPC, @option{booke} controls the disassembly of BookE
1956 instructions.  @option{32} and @option{64} select PowerPC and
1957 PowerPC64 disassembly, respectively.  @option{e300} selects
1958 disassembly for the e300 family.  @option{440} selects disassembly for
1959 the PowerPC 440.  @option{ppcps} selects disassembly for the paired
1960 single instructions of the PPC750CL.
1961
1962 For MIPS, this option controls the printing of instruction mnemonic
1963 names and register names in disassembled instructions.  Multiple
1964 selections from the following may be specified as a comma separated
1965 string, and invalid options are ignored:
1966
1967 @table @code
1968 @item no-aliases
1969 Print the 'raw' instruction mnemonic instead of some pseudo
1970 instruction mnemonic.  I.e., print 'daddu' or 'or' instead of 'move',
1971 'sll' instead of 'nop', etc.
1972
1973 @item gpr-names=@var{ABI}
1974 Print GPR (general-purpose register) names as appropriate
1975 for the specified ABI.  By default, GPR names are selected according to
1976 the ABI of the binary being disassembled.
1977
1978 @item fpr-names=@var{ABI}
1979 Print FPR (floating-point register) names as
1980 appropriate for the specified ABI.  By default, FPR numbers are printed
1981 rather than names.
1982
1983 @item cp0-names=@var{ARCH}
1984 Print CP0 (system control coprocessor; coprocessor 0) register names
1985 as appropriate for the CPU or architecture specified by
1986 @var{ARCH}.  By default, CP0 register names are selected according to
1987 the architecture and CPU of the binary being disassembled.
1988
1989 @item hwr-names=@var{ARCH}
1990 Print HWR (hardware register, used by the @code{rdhwr} instruction) names
1991 as appropriate for the CPU or architecture specified by
1992 @var{ARCH}.  By default, HWR names are selected according to
1993 the architecture and CPU of the binary being disassembled.
1994
1995 @item reg-names=@var{ABI}
1996 Print GPR and FPR names as appropriate for the selected ABI.
1997
1998 @item reg-names=@var{ARCH}
1999 Print CPU-specific register names (CP0 register and HWR names)
2000 as appropriate for the selected CPU or architecture.
2001 @end table
2002
2003 For any of the options listed above, @var{ABI} or
2004 @var{ARCH} may be specified as @samp{numeric} to have numbers printed
2005 rather than names, for the selected types of registers.
2006 You can list the available values of @var{ABI} and @var{ARCH} using
2007 the @option{--help} option.
2008
2009 For VAX, you can specify function entry addresses with @option{-M
2010 entry:0xf00ba}.  You can use this multiple times to properly
2011 disassemble VAX binary files that don't contain symbol tables (like
2012 ROM dumps).  In these cases, the function entry mask would otherwise
2013 be decoded as VAX instructions, which would probably lead the rest
2014 of the function being wrongly disassembled.
2015
2016 @item -p
2017 @itemx --private-headers
2018 Print information that is specific to the object file format.  The exact
2019 information printed depends upon the object file format.  For some
2020 object file formats, no additional information is printed.
2021
2022 @item -r
2023 @itemx --reloc
2024 @cindex relocation entries, in object file
2025 Print the relocation entries of the file.  If used with @option{-d} or
2026 @option{-D}, the relocations are printed interspersed with the
2027 disassembly.
2028
2029 @item -R
2030 @itemx --dynamic-reloc
2031 @cindex dynamic relocation entries, in object file
2032 Print the dynamic relocation entries of the file.  This is only
2033 meaningful for dynamic objects, such as certain types of shared
2034 libraries.  As for @option{-r}, if used with @option{-d} or
2035 @option{-D}, the relocations are printed interspersed with the
2036 disassembly.
2037
2038 @item -s
2039 @itemx --full-contents
2040 @cindex sections, full contents
2041 @cindex object file sections
2042 Display the full contents of any sections requested.  By default all
2043 non-empty sections are displayed.
2044
2045 @item -S
2046 @itemx --source
2047 @cindex source disassembly
2048 @cindex disassembly, with source
2049 Display source code intermixed with disassembly, if possible.  Implies
2050 @option{-d}.
2051
2052 @item --prefix=@var{prefix}
2053 @cindex Add prefix to absolute paths
2054 Specify @var{prefix} to add to the absolute paths when used with
2055 @option{-S}. 
2056
2057 @item --prefix-strip=@var{level}
2058 @cindex Strip absolute paths
2059 Indicate how many initial directory names to strip off the hardwired
2060 absolute paths. It has no effect without @option{--prefix=}@var{prefix}.
2061
2062 @item --show-raw-insn
2063 When disassembling instructions, print the instruction in hex as well as
2064 in symbolic form.  This is the default except when
2065 @option{--prefix-addresses} is used.
2066
2067 @item --no-show-raw-insn
2068 When disassembling instructions, do not print the instruction bytes.
2069 This is the default when @option{--prefix-addresses} is used.
2070
2071 @item --insn-width=@var{width}
2072 @cindex Instruction width 
2073 Display @var{width} bytes on a single line when disassembling
2074 instructions.
2075
2076 @item -W[lLiaprmfFsoR]
2077 @itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]
2078 @cindex DWARF
2079 @cindex debug symbols
2080 Displays the contents of the debug sections in the file, if any are
2081 present.  If one of the optional letters or words follows the switch
2082 then only data found in those specific sections will be dumped.
2083
2084 @item -G
2085 @itemx --stabs
2086 @cindex stab
2087 @cindex .stab
2088 @cindex debug symbols
2089 @cindex ELF object file format
2090 Display the full contents of any sections requested.  Display the
2091 contents of the .stab and .stab.index and .stab.excl sections from an
2092 ELF file.  This is only useful on systems (such as Solaris 2.0) in which
2093 @code{.stab} debugging symbol-table entries are carried in an ELF
2094 section.  In most other file formats, debugging symbol-table entries are
2095 interleaved with linkage symbols, and are visible in the @option{--syms}
2096 output.
2097 @ifclear man
2098 For more information on stabs symbols, see @ref{Top,Stabs,Stabs
2099 Overview,stabs.info, The ``stabs'' debug format}.
2100 @end ifclear
2101
2102 @item --start-address=@var{address}
2103 @cindex start-address
2104 Start displaying data at the specified address.  This affects the output
2105 of the @option{-d}, @option{-r} and @option{-s} options.
2106
2107 @item --stop-address=@var{address}
2108 @cindex stop-address
2109 Stop displaying data at the specified address.  This affects the output
2110 of the @option{-d}, @option{-r} and @option{-s} options.
2111
2112 @item -t
2113 @itemx --syms
2114 @cindex symbol table entries, printing
2115 Print the symbol table entries of the file.
2116 This is similar to the information provided by the @samp{nm} program,
2117 although the display format is different.  The format of the output
2118 depends upon the format of the file being dumped, but there are two main
2119 types.  One looks like this:
2120
2121 @smallexample
2122 [  4](sec  3)(fl 0x00)(ty   0)(scl   3) (nx 1) 0x00000000 .bss
2123 [  6](sec  1)(fl 0x00)(ty   0)(scl   2) (nx 0) 0x00000000 fred
2124 @end smallexample
2125
2126 where the number inside the square brackets is the number of the entry
2127 in the symbol table, the @var{sec} number is the section number, the
2128 @var{fl} value are the symbol's flag bits, the @var{ty} number is the
2129 symbol's type, the @var{scl} number is the symbol's storage class and
2130 the @var{nx} value is the number of auxilary entries associated with
2131 the symbol.  The last two fields are the symbol's value and its name.
2132
2133 The other common output format, usually seen with ELF based files,
2134 looks like this:
2135
2136 @smallexample
2137 00000000 l    d  .bss   00000000 .bss
2138 00000000 g       .text  00000000 fred
2139 @end smallexample
2140
2141 Here the first number is the symbol's value (sometimes refered to as
2142 its address).  The next field is actually a set of characters and
2143 spaces indicating the flag bits that are set on the symbol.  These
2144 characters are described below.  Next is the section with which the
2145 symbol is associated or @emph{*ABS*} if the section is absolute (ie
2146 not connected with any section), or @emph{*UND*} if the section is
2147 referenced in the file being dumped, but not defined there.
2148
2149 After the section name comes another field, a number, which for common
2150 symbols is the alignment and for other symbol is the size.  Finally
2151 the symbol's name is displayed.
2152
2153 The flag characters are divided into 7 groups as follows:
2154 @table @code
2155 @item l
2156 @itemx g
2157 @itemx u
2158 @itemx !
2159 The symbol is a local (l), global (g), unique global (u), neither
2160 global nor local (a space) or both global and local (!).  A
2161 symbol can be neither local or global for a variety of reasons, e.g.,
2162 because it is used for debugging, but it is probably an indication of
2163 a bug if it is ever both local and global.  Unique global symbols are
2164 a GNU extension to the standard set of ELF symbol bindings.  For such
2165 a symbol the dynamic linker will make sure that in the entire process
2166 there is just one symbol with this name and type in use.
2167
2168 @item w
2169 The symbol is weak (w) or strong (a space).
2170
2171 @item C
2172 The symbol denotes a constructor (C) or an ordinary symbol (a space).
2173
2174 @item W
2175 The symbol is a warning (W) or a normal symbol (a space).  A warning
2176 symbol's name is a message to be displayed if the symbol following the
2177 warning symbol is ever referenced.
2178
2179 @item I
2180 @item i
2181 The symbol is an indirect reference to another symbol (I), a function
2182 to be evaluated during reloc processing (i) or a normal symbol (a
2183 space).
2184
2185 @item d
2186 @itemx D
2187 The symbol is a debugging symbol (d) or a dynamic symbol (D) or a
2188 normal symbol (a space).
2189
2190 @item F
2191 @item f
2192 @item O
2193 The symbol is the name of a function (F) or a file (f) or an object
2194 (O) or just a normal symbol (a space).
2195 @end table
2196
2197 @item -T
2198 @itemx --dynamic-syms
2199 @cindex dynamic symbol table entries, printing
2200 Print the dynamic symbol table entries of the file.  This is only
2201 meaningful for dynamic objects, such as certain types of shared
2202 libraries.  This is similar to the information provided by the @samp{nm}
2203 program when given the @option{-D} (@option{--dynamic}) option.
2204
2205 @item --special-syms
2206 When displaying symbols include those which the target considers to be
2207 special in some way and which would not normally be of interest to the
2208 user.
2209
2210 @item -V
2211 @itemx --version
2212 Print the version number of @command{objdump} and exit.
2213
2214 @item -x
2215 @itemx --all-headers
2216 @cindex all header information, object file
2217 @cindex header information, all
2218 Display all available header information, including the symbol table and
2219 relocation entries.  Using @option{-x} is equivalent to specifying all of
2220 @option{-a -f -h -p -r -t}.
2221
2222 @item -w
2223 @itemx --wide
2224 @cindex wide output, printing
2225 Format some lines for output devices that have more than 80 columns.
2226 Also do not truncate symbol names when they are displayed.
2227
2228 @item -z
2229 @itemx --disassemble-zeroes
2230 Normally the disassembly output will skip blocks of zeroes.  This
2231 option directs the disassembler to disassemble those blocks, just like
2232 any other data.
2233 @end table
2234
2235 @c man end
2236
2237 @ignore
2238 @c man begin SEEALSO objdump
2239 nm(1), readelf(1), and the Info entries for @file{binutils}.
2240 @c man end
2241 @end ignore
2242
2243 @node ranlib
2244 @chapter ranlib
2245
2246 @kindex ranlib
2247 @cindex archive contents
2248 @cindex symbol index
2249
2250 @c man title ranlib generate index to archive.
2251
2252 @smallexample
2253 @c man begin SYNOPSIS ranlib
2254 ranlib [@option{-vVt}] @var{archive}
2255 @c man end
2256 @end smallexample
2257
2258 @c man begin DESCRIPTION ranlib
2259
2260 @command{ranlib} generates an index to the contents of an archive and
2261 stores it in the archive.  The index lists each symbol defined by a
2262 member of an archive that is a relocatable object file.
2263
2264 You may use @samp{nm -s} or @samp{nm --print-armap} to list this index.
2265
2266 An archive with such an index speeds up linking to the library and
2267 allows routines in the library to call each other without regard to
2268 their placement in the archive.
2269
2270 The @sc{gnu} @command{ranlib} program is another form of @sc{gnu} @command{ar}; running
2271 @command{ranlib} is completely equivalent to executing @samp{ar -s}.
2272 @xref{ar}.
2273
2274 @c man end
2275
2276 @c man begin OPTIONS ranlib
2277
2278 @table @env
2279 @item -v
2280 @itemx -V
2281 @itemx --version
2282 Show the version number of @command{ranlib}.
2283
2284 @item -t
2285 Update the timestamp of the symbol map of an archive.
2286 @end table
2287
2288 @c man end
2289
2290 @ignore
2291 @c man begin SEEALSO ranlib
2292 ar(1), nm(1), and the Info entries for @file{binutils}.
2293 @c man end
2294 @end ignore
2295
2296 @node size
2297 @chapter size
2298
2299 @kindex size
2300 @cindex section sizes
2301
2302 @c man title size list section sizes and total size.
2303
2304 @smallexample
2305 @c man begin SYNOPSIS size
2306 size [@option{-A}|@option{-B}|@option{--format=}@var{compatibility}]
2307      [@option{--help}]
2308      [@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}]
2309      [@option{--common}]
2310      [@option{-t}|@option{--totals}]
2311      [@option{--target=}@var{bfdname}] [@option{-V}|@option{--version}]
2312      [@var{objfile}@dots{}]
2313 @c man end
2314 @end smallexample
2315
2316 @c man begin DESCRIPTION size
2317
2318 The @sc{gnu} @command{size} utility lists the section sizes---and the total
2319 size---for each of the object or archive files @var{objfile} in its
2320 argument list.  By default, one line of output is generated for each
2321 object file or each module in an archive.
2322
2323 @var{objfile}@dots{} are the object files to be examined.
2324 If none are specified, the file @code{a.out} will be used.
2325
2326 @c man end
2327
2328 @c man begin OPTIONS size
2329
2330 The command line options have the following meanings:
2331
2332 @table @env
2333 @item -A
2334 @itemx -B
2335 @itemx --format=@var{compatibility}
2336 @cindex @command{size} display format
2337 Using one of these options, you can choose whether the output from @sc{gnu}
2338 @command{size} resembles output from System V @command{size} (using @option{-A},
2339 or @option{--format=sysv}), or Berkeley @command{size} (using @option{-B}, or
2340 @option{--format=berkeley}).  The default is the one-line format similar to
2341 Berkeley's.
2342 @c Bonus for doc-source readers: you can also say --format=strange (or
2343 @c anything else that starts with 's') for sysv, and --format=boring (or
2344 @c anything else that starts with 'b') for Berkeley.
2345
2346 Here is an example of the Berkeley (default) format of output from
2347 @command{size}:
2348 @smallexample
2349 $ size --format=Berkeley ranlib size
2350 text    data    bss     dec     hex     filename
2351 294880  81920   11592   388392  5ed28   ranlib
2352 294880  81920   11888   388688  5ee50   size
2353 @end smallexample
2354
2355 @noindent
2356 This is the same data, but displayed closer to System V conventions:
2357
2358 @smallexample
2359 $ size --format=SysV ranlib size
2360 ranlib  :
2361 section         size         addr
2362 .text         294880         8192
2363 .data          81920       303104
2364 .bss           11592       385024
2365 Total         388392
2366
2367
2368 size  :
2369 section         size         addr
2370 .text         294880         8192
2371 .data          81920       303104
2372 .bss           11888       385024
2373 Total         388688
2374 @end smallexample
2375
2376 @item --help
2377 Show a summary of acceptable arguments and options.
2378
2379 @item -d
2380 @itemx -o
2381 @itemx -x
2382 @itemx --radix=@var{number}
2383 @cindex @command{size} number format
2384 @cindex radix for section sizes
2385 Using one of these options, you can control whether the size of each
2386 section is given in decimal (@option{-d}, or @option{--radix=10}); octal
2387 (@option{-o}, or @option{--radix=8}); or hexadecimal (@option{-x}, or
2388 @option{--radix=16}).  In @option{--radix=@var{number}}, only the three
2389 values (8, 10, 16) are supported.  The total size is always given in two
2390 radices; decimal and hexadecimal for @option{-d} or @option{-x} output, or
2391 octal and hexadecimal if you're using @option{-o}.
2392
2393 @item --common
2394 Print total size of common symbols in each file.  When using Berkeley
2395 format these are included in the bss size.
2396
2397 @item -t
2398 @itemx --totals
2399 Show totals of all objects listed (Berkeley format listing mode only).
2400
2401 @item --target=@var{bfdname}
2402 @cindex object code format
2403 Specify that the object-code format for @var{objfile} is
2404 @var{bfdname}.  This option may not be necessary; @command{size} can
2405 automatically recognize many formats.
2406 @xref{Target Selection}, for more information.
2407
2408 @item -V
2409 @itemx --version
2410 Display the version number of @command{size}.
2411 @end table
2412
2413 @c man end
2414
2415 @ignore
2416 @c man begin SEEALSO size
2417 ar(1), objdump(1), readelf(1), and the Info entries for @file{binutils}.
2418 @c man end
2419 @end ignore
2420
2421 @node strings
2422 @chapter strings
2423 @kindex strings
2424 @cindex listings strings
2425 @cindex printing strings
2426 @cindex strings, printing
2427
2428 @c man title strings print the strings of printable characters in files.
2429
2430 @smallexample
2431 @c man begin SYNOPSIS strings
2432 strings [@option{-afovV}] [@option{-}@var{min-len}]
2433         [@option{-n} @var{min-len}] [@option{--bytes=}@var{min-len}]
2434         [@option{-t} @var{radix}] [@option{--radix=}@var{radix}]
2435         [@option{-e} @var{encoding}] [@option{--encoding=}@var{encoding}]
2436         [@option{-}] [@option{--all}] [@option{--print-file-name}]
2437         [@option{-T} @var{bfdname}] [@option{--target=}@var{bfdname}]
2438         [@option{--help}] [@option{--version}] @var{file}@dots{}
2439 @c man end
2440 @end smallexample
2441
2442 @c man begin DESCRIPTION strings
2443
2444 For each @var{file} given, @sc{gnu} @command{strings} prints the printable
2445 character sequences that are at least 4 characters long (or the number
2446 given with the options below) and are followed by an unprintable
2447 character.  By default, it only prints the strings from the initialized
2448 and loaded sections of object files; for other types of files, it prints
2449 the strings from the whole file.
2450
2451 @command{strings} is mainly useful for determining the contents of non-text
2452 files.
2453
2454 @c man end
2455
2456 @c man begin OPTIONS strings
2457
2458 @table @env
2459 @item -a
2460 @itemx --all
2461 @itemx -
2462 Do not scan only the initialized and loaded sections of object files;
2463 scan the whole files.
2464
2465 @item -f
2466 @itemx --print-file-name
2467 Print the name of the file before each string.
2468
2469 @item --help
2470 Print a summary of the program usage on the standard output and exit.
2471
2472 @item -@var{min-len}
2473 @itemx -n @var{min-len}
2474 @itemx --bytes=@var{min-len}
2475 Print sequences of characters that are at least @var{min-len} characters
2476 long, instead of the default 4.
2477
2478 @item -o
2479 Like @samp{-t o}.  Some other versions of @command{strings} have @option{-o}
2480 act like @samp{-t d} instead.  Since we can not be compatible with both
2481 ways, we simply chose one.
2482
2483 @item -t @var{radix}
2484 @itemx --radix=@var{radix}
2485 Print the offset within the file before each string.  The single
2486 character argument specifies the radix of the offset---@samp{o} for
2487 octal, @samp{x} for hexadecimal, or @samp{d} for decimal.
2488
2489 @item -e @var{encoding}
2490 @itemx --encoding=@var{encoding}
2491 Select the character encoding of the strings that are to be found.
2492 Possible values for @var{encoding} are: @samp{s} = single-7-bit-byte
2493 characters (ASCII, ISO 8859, etc., default), @samp{S} =
2494 single-8-bit-byte characters, @samp{b} = 16-bit bigendian, @samp{l} =
2495 16-bit littleendian, @samp{B} = 32-bit bigendian, @samp{L} = 32-bit
2496 littleendian.  Useful for finding wide character strings. (@samp{l}
2497 and @samp{b} apply to, for example, Unicode UTF-16/UCS-2 encodings).
2498
2499 @item -T @var{bfdname}
2500 @itemx --target=@var{bfdname}
2501 @cindex object code format
2502 Specify an object code format other than your system's default format.
2503 @xref{Target Selection}, for more information.
2504
2505 @item -v
2506 @itemx -V
2507 @itemx --version
2508 Print the program version number on the standard output and exit.
2509 @end table
2510
2511 @c man end
2512
2513 @ignore
2514 @c man begin SEEALSO strings
2515 ar(1), nm(1), objdump(1), ranlib(1), readelf(1)
2516 and the Info entries for @file{binutils}.
2517 @c man end
2518 @end ignore
2519
2520 @node strip
2521 @chapter strip
2522
2523 @kindex strip
2524 @cindex removing symbols
2525 @cindex discarding symbols
2526 @cindex symbols, discarding
2527
2528 @c man title strip Discard symbols from object files.
2529
2530 @smallexample
2531 @c man begin SYNOPSIS strip
2532 strip [@option{-F} @var{bfdname} |@option{--target=}@var{bfdname}]
2533       [@option{-I} @var{bfdname} |@option{--input-target=}@var{bfdname}]
2534       [@option{-O} @var{bfdname} |@option{--output-target=}@var{bfdname}]
2535       [@option{-s}|@option{--strip-all}]
2536       [@option{-S}|@option{-g}|@option{-d}|@option{--strip-debug}]
2537       [@option{-K} @var{symbolname} |@option{--keep-symbol=}@var{symbolname}]
2538       [@option{-N} @var{symbolname} |@option{--strip-symbol=}@var{symbolname}]
2539       [@option{-w}|@option{--wildcard}]
2540       [@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}]
2541       [@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}]
2542       [@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}]
2543       [@option{--keep-file-symbols}]
2544       [@option{--only-keep-debug}]
2545       [@option{-v} |@option{--verbose}] [@option{-V}|@option{--version}]
2546       [@option{--help}] [@option{--info}]
2547       @var{objfile}@dots{}
2548 @c man end
2549 @end smallexample
2550
2551 @c man begin DESCRIPTION strip
2552
2553 @sc{gnu} @command{strip} discards all symbols from object files
2554 @var{objfile}.  The list of object files may include archives.
2555 At least one object file must be given.
2556
2557 @command{strip} modifies the files named in its argument,
2558 rather than writing modified copies under different names.
2559
2560 @c man end
2561
2562 @c man begin OPTIONS strip
2563
2564 @table @env
2565 @item -F @var{bfdname}
2566 @itemx --target=@var{bfdname}
2567 Treat the original @var{objfile} as a file with the object
2568 code format @var{bfdname}, and rewrite it in the same format.
2569 @xref{Target Selection}, for more information.
2570
2571 @item --help
2572 Show a summary of the options to @command{strip} and exit.
2573
2574 @item --info
2575 Display a list showing all architectures and object formats available.
2576
2577 @item -I @var{bfdname}
2578 @itemx --input-target=@var{bfdname}
2579 Treat the original @var{objfile} as a file with the object
2580 code format @var{bfdname}.
2581 @xref{Target Selection}, for more information.
2582
2583 @item -O @var{bfdname}
2584 @itemx --output-target=@var{bfdname}
2585 Replace @var{objfile} with a file in the output format @var{bfdname}.
2586 @xref{Target Selection}, for more information.
2587
2588 @item -R @var{sectionname}
2589 @itemx --remove-section=@var{sectionname}
2590 Remove any section named @var{sectionname} from the output file.  This
2591 option may be given more than once.  Note that using this option
2592 inappropriately may make the output file unusable.
2593
2594 @item -s
2595 @itemx --strip-all
2596 Remove all symbols.
2597
2598 @item -g
2599 @itemx -S
2600 @itemx -d
2601 @itemx --strip-debug
2602 Remove debugging symbols only.
2603
2604 @item --strip-unneeded
2605 Remove all symbols that are not needed for relocation processing.
2606
2607 @item -K @var{symbolname}
2608 @itemx --keep-symbol=@var{symbolname}
2609 When stripping symbols, keep symbol @var{symbolname} even if it would
2610 normally be stripped.  This option may be given more than once.
2611
2612 @item -N @var{symbolname}
2613 @itemx --strip-symbol=@var{symbolname}
2614 Remove symbol @var{symbolname} from the source file. This option may be
2615 given more than once, and may be combined with strip options other than
2616 @option{-K}.
2617
2618 @item -o @var{file}
2619 Put the stripped output in @var{file}, rather than replacing the
2620 existing file.  When this argument is used, only one @var{objfile}
2621 argument may be specified.
2622
2623 @item -p
2624 @itemx --preserve-dates
2625 Preserve the access and modification dates of the file.
2626
2627 @item -w
2628 @itemx --wildcard
2629 Permit regular expressions in @var{symbolname}s used in other command
2630 line options.  The question mark (?), asterisk (*), backslash (\) and
2631 square brackets ([]) operators can be used anywhere in the symbol
2632 name.  If the first character of the symbol name is the exclamation
2633 point (!) then the sense of the switch is reversed for that symbol.
2634 For example:
2635
2636 @smallexample
2637   -w -K !foo -K fo*
2638 @end smallexample
2639
2640 would cause strip to only keep symbols that start with the letters
2641 ``fo'', but to discard the symbol ``foo''.
2642
2643 @item -x
2644 @itemx --discard-all
2645 Remove non-global symbols.
2646
2647 @item -X
2648 @itemx --discard-locals
2649 Remove compiler-generated local symbols.
2650 (These usually start with @samp{L} or @samp{.}.)
2651
2652 @item --keep-file-symbols
2653 When stripping a file, perhaps with @option{--strip-debug} or
2654 @option{--strip-unneeded}, retain any symbols specifying source file names,
2655 which would otherwise get stripped.
2656
2657 @item --only-keep-debug
2658 Strip a file, removing contents of any sections that would not be
2659 stripped by @option{--strip-debug} and leaving the debugging sections
2660 intact.  In ELF files, this preserves all note sections in the output.
2661
2662 The intention is that this option will be used in conjunction with
2663 @option{--add-gnu-debuglink} to create a two part executable.  One a
2664 stripped binary which will occupy less space in RAM and in a
2665 distribution and the second a debugging information file which is only
2666 needed if debugging abilities are required.  The suggested procedure
2667 to create these files is as follows:
2668
2669 @enumerate
2670 @item Link the executable as normal.  Assuming that is is called
2671 @code{foo} then...
2672 @item Run @code{objcopy --only-keep-debug foo foo.dbg} to
2673 create a file containing the debugging info.
2674 @item Run @code{objcopy --strip-debug foo} to create a
2675 stripped executable.
2676 @item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo}
2677 to add a link to the debugging info into the stripped executable.
2678 @end enumerate
2679
2680 Note---the choice of @code{.dbg} as an extension for the debug info
2681 file is arbitrary.  Also the @code{--only-keep-debug} step is
2682 optional.  You could instead do this:
2683
2684 @enumerate
2685 @item Link the executable as normal.
2686 @item Copy @code{foo} to @code{foo.full}
2687 @item Run @code{strip --strip-debug foo}
2688 @item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
2689 @end enumerate
2690
2691 i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the
2692 full executable.  It does not have to be a file created by the
2693 @option{--only-keep-debug} switch.
2694
2695 Note---this switch is only intended for use on fully linked files.  It
2696 does not make sense to use it on object files where the debugging
2697 information may be incomplete.  Besides the gnu_debuglink feature
2698 currently only supports the presence of one filename containing
2699 debugging information, not multiple filenames on a one-per-object-file
2700 basis.
2701
2702 @item -V
2703 @itemx --version
2704 Show the version number for @command{strip}.
2705
2706 @item -v
2707 @itemx --verbose
2708 Verbose output: list all object files modified.  In the case of
2709 archives, @samp{strip -v} lists all members of the archive.
2710 @end table
2711
2712 @c man end
2713
2714 @ignore
2715 @c man begin SEEALSO strip
2716 the Info entries for @file{binutils}.
2717 @c man end
2718 @end ignore
2719
2720 @node c++filt, addr2line, strip, Top
2721 @chapter c++filt
2722
2723 @kindex c++filt
2724 @cindex demangling C++ symbols
2725
2726 @c man title cxxfilt Demangle C++ and Java symbols.
2727
2728 @smallexample
2729 @c man begin SYNOPSIS cxxfilt
2730 c++filt [@option{-_}|@option{--strip-underscores}]
2731         [@option{-n}|@option{--no-strip-underscores}]
2732         [@option{-p}|@option{--no-params}]
2733         [@option{-t}|@option{--types}]
2734         [@option{-i}|@option{--no-verbose}]
2735         [@option{-s} @var{format}|@option{--format=}@var{format}]
2736         [@option{--help}]  [@option{--version}]  [@var{symbol}@dots{}]
2737 @c man end
2738 @end smallexample
2739
2740 @c man begin DESCRIPTION cxxfilt
2741
2742 @kindex cxxfilt
2743 The C++ and Java languages provide function overloading, which means
2744 that you can write many functions with the same name, providing that
2745 each function takes parameters of different types.  In order to be
2746 able to distinguish these similarly named functions C++ and Java
2747 encode them into a low-level assembler name which uniquely identifies
2748 each different version.  This process is known as @dfn{mangling}. The
2749 @command{c++filt}
2750 @footnote{MS-DOS does not allow @kbd{+} characters in file names, so on
2751 MS-DOS this program is named @command{CXXFILT}.}
2752 program does the inverse mapping: it decodes (@dfn{demangles}) low-level
2753 names into user-level names so that they can be read.
2754
2755 Every alphanumeric word (consisting of letters, digits, underscores,
2756 dollars, or periods) seen in the input is a potential mangled name.
2757 If the name decodes into a C++ name, the C++ name replaces the
2758 low-level name in the output, otherwise the original word is output.
2759 In this way you can pass an entire assembler source file, containing
2760 mangled names, through @command{c++filt} and see the same source file
2761 containing demangled names.
2762
2763 You can also use @command{c++filt} to decipher individual symbols by
2764 passing them on the command line:
2765
2766 @example
2767 c++filt @var{symbol}
2768 @end example
2769
2770 If no @var{symbol} arguments are given, @command{c++filt} reads symbol
2771 names from the standard input instead.  All the results are printed on
2772 the standard output.  The difference between reading names from the
2773 command line versus reading names from the standard input is that
2774 command line arguments are expected to be just mangled names and no
2775 checking is performed to separate them from surrounding text.  Thus
2776 for example:
2777
2778 @smallexample
2779 c++filt -n _Z1fv
2780 @end smallexample
2781
2782 will work and demangle the name to ``f()'' whereas:
2783
2784 @smallexample
2785 c++filt -n _Z1fv,
2786 @end smallexample
2787
2788 will not work.  (Note the extra comma at the end of the mangled
2789 name which makes it invalid).  This command however will work:
2790
2791 @smallexample
2792 echo _Z1fv, | c++filt -n
2793 @end smallexample
2794
2795 and will display ``f(),'', i.e., the demangled name followed by a
2796 trailing comma.  This behaviour is because when the names are read
2797 from the standard input it is expected that they might be part of an
2798 assembler source file where there might be extra, extraneous
2799 characters trailing after a mangled name.  For example:
2800
2801 @smallexample
2802     .type   _Z1fv, @@function
2803 @end smallexample
2804
2805 @c man end
2806
2807 @c man begin OPTIONS cxxfilt
2808
2809 @table @env
2810 @item -_
2811 @itemx --strip-underscores
2812 On some systems, both the C and C++ compilers put an underscore in front
2813 of every name.  For example, the C name @code{foo} gets the low-level
2814 name @code{_foo}.  This option removes the initial underscore.  Whether
2815 @command{c++filt} removes the underscore by default is target dependent.
2816
2817 @item -n
2818 @itemx --no-strip-underscores
2819 Do not remove the initial underscore.
2820
2821 @item -p
2822 @itemx --no-params
2823 When demangling the name of a function, do not display the types of
2824 the function's parameters.
2825
2826 @item -t
2827 @itemx --types
2828 Attempt to demangle types as well as function names.  This is disabled
2829 by default since mangled types are normally only used internally in
2830 the compiler, and they can be confused with non-mangled names.  For example,
2831 a function called ``a'' treated as a mangled type name would be
2832 demangled to ``signed char''.
2833
2834 @item -i
2835 @itemx --no-verbose
2836 Do not include implementation details (if any) in the demangled
2837 output.
2838
2839 @item -s @var{format}
2840 @itemx --format=@var{format}
2841 @command{c++filt} can decode various methods of mangling, used by
2842 different compilers.  The argument to this option selects which
2843 method it uses:
2844
2845 @table @code
2846 @item auto
2847 Automatic selection based on executable (the default method)
2848 @item gnu
2849 the one used by the @sc{gnu} C++ compiler (g++)
2850 @item lucid
2851 the one used by the Lucid compiler (lcc)
2852 @item arm
2853 the one specified by the C++ Annotated Reference Manual
2854 @item hp
2855 the one used by the HP compiler (aCC)
2856 @item edg
2857 the one used by the EDG compiler
2858 @item gnu-v3
2859 the one used by the @sc{gnu} C++ compiler (g++) with the V3 ABI.
2860 @item java
2861 the one used by the @sc{gnu} Java compiler (gcj)
2862 @item gnat
2863 the one used by the @sc{gnu} Ada compiler (GNAT).
2864 @end table
2865
2866 @item --help
2867 Print a summary of the options to @command{c++filt} and exit.
2868
2869 @item --version
2870 Print the version number of @command{c++filt} and exit.
2871 @end table
2872
2873 @c man end
2874
2875 @ignore
2876 @c man begin SEEALSO cxxfilt
2877 the Info entries for @file{binutils}.
2878 @c man end
2879 @end ignore
2880
2881 @quotation
2882 @emph{Warning:} @command{c++filt} is a new utility, and the details of its
2883 user interface are subject to change in future releases.  In particular,
2884 a command-line option may be required in the future to decode a name
2885 passed as an argument on the command line; in other words,
2886
2887 @example
2888 c++filt @var{symbol}
2889 @end example
2890
2891 @noindent
2892 may in a future release become
2893
2894 @example
2895 c++filt @var{option} @var{symbol}
2896 @end example
2897 @end quotation
2898
2899 @node addr2line
2900 @chapter addr2line
2901
2902 @kindex addr2line
2903 @cindex address to file name and line number
2904
2905 @c man title addr2line convert addresses into file names and line numbers.
2906
2907 @smallexample
2908 @c man begin SYNOPSIS addr2line
2909 addr2line [@option{-b} @var{bfdname}|@option{--target=}@var{bfdname}]
2910           [@option{-C}|@option{--demangle}[=@var{style}]]
2911           [@option{-e} @var{filename}|@option{--exe=}@var{filename}]
2912           [@option{-f}|@option{--functions}] [@option{-s}|@option{--basename}]
2913           [@option{-i}|@option{--inlines}]
2914           [@option{-j}|@option{--section=}@var{name}]
2915           [@option{-H}|@option{--help}] [@option{-V}|@option{--version}]
2916           [addr addr @dots{}]
2917 @c man end
2918 @end smallexample
2919
2920 @c man begin DESCRIPTION addr2line
2921
2922 @command{addr2line} translates addresses into file names and line numbers.
2923 Given an address in an executable or an offset in a section of a relocatable
2924 object, it uses the debugging information to figure out which file name and
2925 line number are associated with it.
2926
2927 The executable or relocatable object to use is specified with the @option{-e}
2928 option.  The default is the file @file{a.out}.  The section in the relocatable
2929 object to use is specified with the @option{-j} option.
2930
2931 @command{addr2line} has two modes of operation.
2932
2933 In the first, hexadecimal addresses are specified on the command line,
2934 and @command{addr2line} displays the file name and line number for each
2935 address.
2936
2937 In the second, @command{addr2line} reads hexadecimal addresses from
2938 standard input, and prints the file name and line number for each
2939 address on standard output.  In this mode, @command{addr2line} may be used
2940 in a pipe to convert dynamically chosen addresses.
2941
2942 The format of the output is @samp{FILENAME:LINENO}.  The file name and
2943 line number for each address is printed on a separate line.  If the
2944 @command{-f} option is used, then each @samp{FILENAME:LINENO} line is
2945 preceded by a @samp{FUNCTIONNAME} line which is the name of the function
2946 containing the address.
2947
2948 If the file name or function name can not be determined,
2949 @command{addr2line} will print two question marks in their place.  If the
2950 line number can not be determined, @command{addr2line} will print 0.
2951
2952 @c man end
2953
2954 @c man begin OPTIONS addr2line
2955
2956 The long and short forms of options, shown here as alternatives, are
2957 equivalent.
2958
2959 @table @env
2960 @item -b @var{bfdname}
2961 @itemx --target=@var{bfdname}
2962 @cindex object code format
2963 Specify that the object-code format for the object files is
2964 @var{bfdname}.
2965
2966 @item -C
2967 @itemx --demangle[=@var{style}]
2968 @cindex demangling in objdump
2969 Decode (@dfn{demangle}) low-level symbol names into user-level names.
2970 Besides removing any initial underscore prepended by the system, this
2971 makes C++ function names readable.  Different compilers have different
2972 mangling styles. The optional demangling style argument can be used to
2973 choose an appropriate demangling style for your compiler. @xref{c++filt},
2974 for more information on demangling.
2975
2976 @item -e @var{filename}
2977 @itemx --exe=@var{filename}
2978 Specify the name of the executable for which addresses should be
2979 translated.  The default file is @file{a.out}.
2980
2981 @item -f
2982 @itemx --functions
2983 Display function names as well as file and line number information.
2984
2985 @item -s
2986 @itemx --basenames
2987 Display only the base of each file name.
2988
2989 @item -i
2990 @itemx --inlines
2991 If the address belongs to a function that was inlined, the source
2992 information for all enclosing scopes back to the first non-inlined
2993 function will also be printed.  For example, if @code{main} inlines
2994 @code{callee1} which inlines @code{callee2}, and address is from
2995 @code{callee2}, the source information for @code{callee1} and @code{main}
2996 will also be printed.
2997
2998 @item -j
2999 @itemx --section
3000 Read offsets relative to the specified section instead of absolute addresses.
3001 @end table
3002
3003 @c man end
3004
3005 @ignore
3006 @c man begin SEEALSO addr2line
3007 Info entries for @file{binutils}.
3008 @c man end
3009 @end ignore
3010
3011 @node nlmconv
3012 @chapter nlmconv
3013
3014 @command{nlmconv} converts a relocatable object file into a NetWare
3015 Loadable Module.
3016
3017 @ignore
3018 @command{nlmconv} currently works with @samp{i386} object
3019 files in @code{coff}, @sc{elf}, or @code{a.out} format, and @sc{SPARC}
3020 object files in @sc{elf}, or @code{a.out} format@footnote{
3021 @command{nlmconv} should work with any @samp{i386} or @sc{sparc} object
3022 format in the Binary File Descriptor library.  It has only been tested
3023 with the above formats.}.
3024 @end ignore
3025
3026 @quotation
3027 @emph{Warning:} @command{nlmconv} is not always built as part of the binary
3028 utilities, since it is only useful for NLM targets.
3029 @end quotation
3030
3031 @c man title nlmconv converts object code into an NLM.
3032
3033 @smallexample
3034 @c man begin SYNOPSIS nlmconv
3035 nlmconv [@option{-I} @var{bfdname}|@option{--input-target=}@var{bfdname}]
3036         [@option{-O} @var{bfdname}|@option{--output-target=}@var{bfdname}]
3037         [@option{-T} @var{headerfile}|@option{--header-file=}@var{headerfile}]
3038         [@option{-d}|@option{--debug}] [@option{-l} @var{linker}|@option{--linker=}@var{linker}]
3039         [@option{-h}|@option{--help}] [@option{-V}|@option{--version}]
3040         @var{infile} @var{outfile}
3041 @c man end
3042 @end smallexample
3043
3044 @c man begin DESCRIPTION nlmconv
3045
3046 @command{nlmconv} converts the relocatable @samp{i386} object file
3047 @var{infile} into the NetWare Loadable Module @var{outfile}, optionally
3048 reading @var{headerfile} for NLM header information.  For instructions
3049 on writing the NLM command file language used in header files, see the
3050 @samp{linkers} section, @samp{NLMLINK} in particular, of the @cite{NLM
3051 Development and Tools Overview}, which is part of the NLM Software
3052 Developer's Kit (``NLM SDK''), available from Novell, Inc.
3053 @command{nlmconv} uses the @sc{gnu} Binary File Descriptor library to read
3054 @var{infile};
3055 @ifclear man
3056 see @ref{BFD,,BFD,ld.info,Using LD}, for more information.
3057 @end ifclear
3058
3059 @command{nlmconv} can perform a link step.  In other words, you can list
3060 more than one object file for input if you list them in the definitions
3061 file (rather than simply specifying one input file on the command line).
3062 In this case, @command{nlmconv} calls the linker for you.
3063
3064 @c man end
3065
3066 @c man begin OPTIONS nlmconv
3067
3068 @table @env
3069 @item -I @var{bfdname}
3070 @itemx --input-target=@var{bfdname}
3071 Object format of the input file.  @command{nlmconv} can usually determine
3072 the format of a given file (so no default is necessary).
3073 @xref{Target Selection}, for more information.
3074
3075 @item -O @var{bfdname}
3076 @itemx --output-target=@var{bfdname}
3077 Object format of the output file.  @command{nlmconv} infers the output
3078 format based on the input format, e.g. for a @samp{i386} input file the
3079 output format is @samp{nlm32-i386}.
3080 @xref{Target Selection}, for more information.
3081
3082 @item -T @var{headerfile}
3083 @itemx --header-file=@var{headerfile}
3084 Reads @var{headerfile} for NLM header information.  For instructions on
3085 writing the NLM command file language used in header files, see@ see the
3086 @samp{linkers} section, of the @cite{NLM Development and Tools
3087 Overview}, which is part of the NLM Software Developer's Kit, available
3088 from Novell, Inc.
3089
3090 @item -d
3091 @itemx --debug
3092 Displays (on standard error) the linker command line used by @command{nlmconv}.
3093
3094 @item -l @var{linker}
3095 @itemx --linker=@var{linker}
3096 Use @var{linker} for any linking.  @var{linker} can be an absolute or a
3097 relative pathname.
3098
3099 @item -h
3100 @itemx --help
3101 Prints a usage summary.
3102
3103 @item -V
3104 @itemx --version
3105 Prints the version number for @command{nlmconv}.
3106 @end table
3107
3108 @c man end
3109
3110 @ignore
3111 @c man begin SEEALSO nlmconv
3112 the Info entries for @file{binutils}.
3113 @c man end
3114 @end ignore
3115
3116 @node windmc
3117 @chapter windmc
3118
3119 @command{windmc} may be used to generator Windows message resources.
3120
3121 @quotation
3122 @emph{Warning:} @command{windmc} is not always built as part of the binary
3123 utilities, since it is only useful for Windows targets.
3124 @end quotation
3125
3126 @c man title windmc generates Windows message resources.
3127
3128 @smallexample
3129 @c man begin SYNOPSIS windres
3130 windmc [options] input-file
3131 @c man end
3132 @end smallexample
3133
3134 @c man begin DESCRIPTION windmc
3135
3136 @command{windmc} reads message definitions from an input file (.mc) and
3137 translate them into a set of output files.  The output files may be of
3138 four kinds:
3139
3140 @table @code
3141 @item h
3142 A C header file containing the message definitions.
3143
3144 @item rc
3145 A resource file compilable by the @command{windres} tool.
3146
3147 @item bin
3148 One or more binary files containing the resource data for a specific
3149 message language.
3150
3151 @item dbg
3152 A C include file that maps message id's to their symbolic name.
3153 @end table
3154
3155 The exact description of these different formats is available in
3156 documentation from Microsoft.
3157
3158 When @command{windmc} converts from the @code{mc} format to the @code{bin}
3159 format, @code{rc}, @code{h}, and optional @code{dbg} it is acting like the
3160 Windows Message Compiler.
3161
3162 @c man end
3163
3164 @c man begin OPTIONS windmc
3165
3166 @table @env
3167 @item -a
3168 @itemx --ascii_in
3169 Specifies that the input file specified is ANSI. This is the default
3170 behaviour.
3171
3172 @item -A
3173 @itemx --ascii_out
3174 Specifies that messages in the output @code{bin} files should be in ANSI
3175 format.
3176
3177 @item -b
3178 @itemx --binprefix
3179 Specifies that @code{bin} filenames should have to be prefixed by the
3180 basename of the source file.
3181
3182 @item -c
3183 @itemx --customflag
3184 Sets the customer bit in all message id's.
3185
3186 @item -C @var{codepage}
3187 @itemx --codepage_in @var{codepage}
3188 Sets the default codepage to be used to convert input file to UTF16. The
3189 default is ocdepage 1252.
3190
3191 @item -d
3192 @itemx --decimal_values
3193 Outputs the constants in the header file in decimal. Default is using
3194 hexadecimal output.
3195
3196 @item -e @var{ext}
3197 @itemx --extension @var{ext}
3198 The extension for the header file. The default is .h extension.
3199
3200 @item -F @var{target}
3201 @itemx --target @var{target}
3202 Specify the BFD format to use for a bin file as output.  This
3203 is a BFD target name; you can use the @option{--help} option to see a list
3204 of supported targets.  Normally @command{windmc} will use the default
3205 format, which is the first one listed by the @option{--help} option.
3206 @ifclear man
3207 @ref{Target Selection}.
3208 @end ifclear
3209
3210 @item -h @var{path}
3211 @itemx --headerdir @var{path}
3212 The target directory of the generated header file. The default is the
3213 current directory.
3214
3215 @item -H
3216 @itemx --help
3217 Displays a list of command line options and then exits.
3218
3219 @item -m @var{characters}
3220 @itemx --maxlength @var{characters}
3221 Instructs @command{windmc} to generate a warning if the length
3222 of any message exceeds the number specified.
3223
3224 @item -n
3225 @itemx --nullterminate
3226 Terminate message text in @code{bin} files by zero. By default they are
3227 terminated by CR/LF.
3228
3229 @item -o
3230 @itemx --hresult_use
3231 Not yet implemented. Instructs @code{windmc} to generate an OLE2 header
3232 file, using HRESULT definitions. Status codes are used if the flag is not
3233 specified.
3234
3235 @item -O @var{codepage}
3236 @itemx --codepage_out @var{codepage}
3237 Sets the default codepage to be used to output text files. The default
3238 is ocdepage 1252.
3239
3240 @item -r @var{path}
3241 @itemx --rcdir @var{path}
3242 The target directory for the generated @code{rc} script and the generated
3243 @code{bin} files that the resource compiler script includes. The default
3244 is the current directory.
3245
3246 @item -u
3247 @itemx --unicode_in
3248 Specifies that the input file is UTF16.
3249
3250 @item -U
3251 @itemx --unicode_out
3252 Specifies that messages in the output @code{bin} file should be in UTF16
3253 format. This is the default behaviour.
3254
3255 @item -v
3256 @item --verbose
3257 Enable verbose mode.
3258
3259 @item -V
3260 @item --version
3261 Prints the version number for @command{windmc}.
3262
3263 @item -x @var{path}
3264 @itemx --xdgb @var{path}
3265 The path of the @code{dbg} C include file that maps message id's to the
3266 symbolic name. No such file is generated without specifying the switch.
3267 @end table
3268
3269 @c man end
3270
3271 @ignore
3272 @c man begin SEEALSO windmc
3273 the Info entries for @file{binutils}.
3274 @c man end
3275 @end ignore
3276
3277 @node windres
3278 @chapter windres
3279
3280 @command{windres} may be used to manipulate Windows resources.
3281
3282 @quotation
3283 @emph{Warning:} @command{windres} is not always built as part of the binary
3284 utilities, since it is only useful for Windows targets.
3285 @end quotation
3286
3287 @c man title windres manipulate Windows resources.
3288
3289 @smallexample
3290 @c man begin SYNOPSIS windres
3291 windres [options] [input-file] [output-file]
3292 @c man end
3293 @end smallexample
3294
3295 @c man begin DESCRIPTION windres
3296
3297 @command{windres} reads resources from an input file and copies them into
3298 an output file.  Either file may be in one of three formats:
3299
3300 @table @code
3301 @item rc
3302 A text format read by the Resource Compiler.
3303
3304 @item res
3305 A binary format generated by the Resource Compiler.
3306
3307 @item coff
3308 A COFF object or executable.
3309 @end table
3310
3311 The exact description of these different formats is available in
3312 documentation from Microsoft.
3313
3314 When @command{windres} converts from the @code{rc} format to the @code{res}
3315 format, it is acting like the Windows Resource Compiler.  When
3316 @command{windres} converts from the @code{res} format to the @code{coff}
3317 format, it is acting like the Windows @code{CVTRES} program.
3318
3319 When @command{windres} generates an @code{rc} file, the output is similar
3320 but not identical to the format expected for the input.  When an input
3321 @code{rc} file refers to an external filename, an output @code{rc} file
3322 will instead include the file contents.
3323
3324 If the input or output format is not specified, @command{windres} will
3325 guess based on the file name, or, for the input file, the file contents.
3326 A file with an extension of @file{.rc} will be treated as an @code{rc}
3327 file, a file with an extension of @file{.res} will be treated as a
3328 @code{res} file, and a file with an extension of @file{.o} or
3329 @file{.exe} will be treated as a @code{coff} file.
3330
3331 If no output file is specified, @command{windres} will print the resources
3332 in @code{rc} format to standard output.
3333
3334 The normal use is for you to write an @code{rc} file, use @command{windres}
3335 to convert it to a COFF object file, and then link the COFF file into
3336 your application.  This will make the resources described in the
3337 @code{rc} file available to Windows.
3338
3339 @c man end
3340
3341 @c man begin OPTIONS windres
3342
3343 @table @env
3344 @item -i @var{filename}
3345 @itemx --input @var{filename}
3346 The name of the input file.  If this option is not used, then
3347 @command{windres} will use the first non-option argument as the input file
3348 name.  If there are no non-option arguments, then @command{windres} will
3349 read from standard input.  @command{windres} can not read a COFF file from
3350 standard input.
3351
3352 @item -o @var{filename}
3353 @itemx --output @var{filename}
3354 The name of the output file.  If this option is not used, then
3355 @command{windres} will use the first non-option argument, after any used
3356 for the input file name, as the output file name.  If there is no
3357 non-option argument, then @command{windres} will write to standard output.
3358 @command{windres} can not write a COFF file to standard output.  Note,
3359 for compatibility with @command{rc} the option @option{-fo} is also
3360 accepted, but its use is not recommended.
3361
3362 @item -J @var{format}
3363 @itemx --input-format @var{format}
3364 The input format to read.  @var{format} may be @samp{res}, @samp{rc}, or
3365 @samp{coff}.  If no input format is specified, @command{windres} will
3366 guess, as described above.
3367
3368 @item -O @var{format}
3369 @itemx --output-format @var{format}
3370 The output format to generate.  @var{format} may be @samp{res},
3371 @samp{rc}, or @samp{coff}.  If no output format is specified,
3372 @command{windres} will guess, as described above.
3373
3374 @item -F @var{target}
3375 @itemx --target @var{target}
3376 Specify the BFD format to use for a COFF file as input or output.  This
3377 is a BFD target name; you can use the @option{--help} option to see a list
3378 of supported targets.  Normally @command{windres} will use the default
3379 format, which is the first one listed by the @option{--help} option.
3380 @ifclear man
3381 @ref{Target Selection}.
3382 @end ifclear
3383
3384 @item --preprocessor @var{program}
3385 When @command{windres} reads an @code{rc} file, it runs it through the C
3386 preprocessor first.  This option may be used to specify the preprocessor
3387 to use, including any leading arguments.  The default preprocessor
3388 argument is @code{gcc -E -xc-header -DRC_INVOKED}.
3389
3390 @item -I @var{directory}
3391 @itemx --include-dir @var{directory}
3392 Specify an include directory to use when reading an @code{rc} file.
3393 @command{windres} will pass this to the preprocessor as an @option{-I}
3394 option.  @command{windres} will also search this directory when looking for
3395 files named in the @code{rc} file.  If the argument passed to this command
3396 matches any of the supported @var{formats} (as described in the @option{-J}
3397 option), it will issue a deprecation warning, and behave just like the
3398 @option{-J} option.  New programs should not use this behaviour.  If a
3399 directory happens to match a @var{format}, simple prefix it with @samp{./}
3400 to disable the backward compatibility.
3401
3402 @item -D @var{target}
3403 @itemx --define @var{sym}[=@var{val}]
3404 Specify a @option{-D} option to pass to the preprocessor when reading an
3405 @code{rc} file.
3406
3407 @item -U @var{target}
3408 @itemx --undefine @var{sym}
3409 Specify a @option{-U} option to pass to the preprocessor when reading an
3410 @code{rc} file.
3411
3412 @item -r
3413 Ignored for compatibility with rc.
3414
3415 @item -v
3416 Enable verbose mode.  This tells you what the preprocessor is if you
3417 didn't specify one.
3418
3419 @item -c @var{val}
3420 @item --codepage @var{val}
3421 Specify the default codepage to use when reading an @code{rc} file.
3422 @var{val} should be a hexadecimal prefixed by @samp{0x} or decimal
3423 codepage code. The valid range is from zero up to 0xffff, but the
3424 validity of the codepage is host and configuration dependent.
3425
3426 @item -l @var{val}
3427 @item --language @var{val}
3428 Specify the default language to use when reading an @code{rc} file.
3429 @var{val} should be a hexadecimal language code.  The low eight bits are
3430 the language, and the high eight bits are the sublanguage.
3431
3432 @item --use-temp-file
3433 Use a temporary file to instead of using popen to read the output of
3434 the preprocessor. Use this option if the popen implementation is buggy
3435 on the host (eg., certain non-English language versions of Windows 95 and
3436 Windows 98 are known to have buggy popen where the output will instead
3437 go the console).
3438
3439 @item --no-use-temp-file
3440 Use popen, not a temporary file, to read the output of the preprocessor.
3441 This is the default behaviour.
3442
3443 @item -h
3444 @item --help
3445 Prints a usage summary.
3446
3447 @item -V
3448 @item --version
3449 Prints the version number for @command{windres}.
3450
3451 @item --yydebug
3452 If @command{windres} is compiled with @code{YYDEBUG} defined as @code{1},
3453 this will turn on parser debugging.
3454 @end table
3455
3456 @c man end
3457
3458 @ignore
3459 @c man begin SEEALSO windres
3460 the Info entries for @file{binutils}.
3461 @c man end
3462 @end ignore
3463
3464 @node dlltool
3465 @chapter dlltool
3466 @cindex DLL
3467 @kindex dlltool
3468
3469 @command{dlltool} is used to create the files needed to create dynamic
3470 link libraries (DLLs) on systems which understand PE format image
3471 files such as Windows.  A DLL contains an export table which contains
3472 information that the runtime loader needs to resolve references from a
3473 referencing program.
3474
3475 The export table is generated by this program by reading in a
3476 @file{.def} file or scanning the @file{.a} and @file{.o} files which
3477 will be in the DLL.  A @file{.o} file can contain information in
3478 special @samp{.drectve} sections with export information.
3479
3480 @quotation
3481 @emph{Note:} @command{dlltool} is not always built as part of the
3482 binary utilities, since it is only useful for those targets which
3483 support DLLs.
3484 @end quotation
3485
3486 @c man title dlltool Create files needed to build and use DLLs.
3487
3488 @smallexample
3489 @c man begin SYNOPSIS dlltool
3490 dlltool [@option{-d}|@option{--input-def} @var{def-file-name}]
3491         [@option{-b}|@option{--base-file} @var{base-file-name}]
3492         [@option{-e}|@option{--output-exp} @var{exports-file-name}]
3493         [@option{-z}|@option{--output-def} @var{def-file-name}]
3494         [@option{-l}|@option{--output-lib} @var{library-file-name}]
3495         [@option{-y}|@option{--output-delaylib} @var{library-file-name}]
3496         [@option{--export-all-symbols}] [@option{--no-export-all-symbols}]
3497         [@option{--exclude-symbols} @var{list}]
3498         [@option{--no-default-excludes}]
3499         [@option{-S}|@option{--as} @var{path-to-assembler}] [@option{-f}|@option{--as-flags} @var{options}]
3500         [@option{-D}|@option{--dllname} @var{name}] [@option{-m}|@option{--machine} @var{machine}]
3501         [@option{-a}|@option{--add-indirect}]
3502         [@option{-U}|@option{--add-underscore}] [@option{--add-stdcall-underscore}]
3503         [@option{-k}|@option{--kill-at}] [@option{-A}|@option{--add-stdcall-alias}]
3504         [@option{-p}|@option{--ext-prefix-alias} @var{prefix}]
3505         [@option{-x}|@option{--no-idata4}] [@option{-c}|@option{--no-idata5}]
3506         [@option{--use-nul-prefixed-import-tables}]
3507         [@option{-I}|@option{--identify} @var{library-file-name}] [@option{--identify-strict}]
3508         [@option{-i}|@option{--interwork}]
3509         [@option{-n}|@option{--nodelete}] [@option{-t}|@option{--temp-prefix} @var{prefix}]
3510         [@option{-v}|@option{--verbose}]
3511         [@option{-h}|@option{--help}] [@option{-V}|@option{--version}]
3512         [object-file @dots{}]
3513 @c man end
3514 @end smallexample
3515
3516 @c man begin DESCRIPTION dlltool
3517
3518 @command{dlltool} reads its inputs, which can come from the @option{-d} and
3519 @option{-b} options as well as object files specified on the command
3520 line.  It then processes these inputs and if the @option{-e} option has
3521 been specified it creates a exports file.  If the @option{-l} option
3522 has been specified it creates a library file and if the @option{-z} option
3523 has been specified it creates a def file.  Any or all of the @option{-e},
3524 @option{-l} and @option{-z} options can be present in one invocation of
3525 dlltool.
3526
3527 When creating a DLL, along with the source for the DLL, it is necessary
3528 to have three other files.  @command{dlltool} can help with the creation of
3529 these files.
3530
3531 The first file is a @file{.def} file which specifies which functions are
3532 exported from the DLL, which functions the DLL imports, and so on.  This
3533 is a text file and can be created by hand, or @command{dlltool} can be used
3534 to create it using the @option{-z} option.  In this case @command{dlltool}
3535 will scan the object files specified on its command line looking for
3536 those functions which have been specially marked as being exported and
3537 put entries for them in the @file{.def} file it creates.
3538
3539 In order to mark a function as being exported from a DLL, it needs to
3540 have an @option{-export:<name_of_function>} entry in the @samp{.drectve}
3541 section of the object file.  This can be done in C by using the
3542 asm() operator:
3543
3544 @smallexample
3545   asm (".section .drectve");
3546   asm (".ascii \"-export:my_func\"");
3547
3548   int my_func (void) @{ @dots{} @}
3549 @end smallexample
3550
3551 The second file needed for DLL creation is an exports file.  This file
3552 is linked with the object files that make up the body of the DLL and it
3553 handles the interface between the DLL and the outside world.  This is a
3554 binary file and it can be created by giving the @option{-e} option to
3555 @command{dlltool} when it is creating or reading in a @file{.def} file.
3556
3557 The third file needed for DLL creation is the library file that programs
3558 will link with in order to access the functions in the DLL (an `import
3559 library').  This file can be created by giving the @option{-l} option to
3560 dlltool when it is creating or reading in a @file{.def} file.
3561
3562 If the @option{-y} option is specified, dlltool generates a delay-import
3563 library that can be used instead of the normal import library to allow
3564 a program to link to the dll only as soon as an imported function is
3565 called for the first time. The resulting executable will need to be
3566 linked to the static delayimp library containing __delayLoadHelper2(),
3567 which in turn will import LoadLibraryA and GetProcAddress from kernel32.
3568
3569 @command{dlltool} builds the library file by hand, but it builds the
3570 exports file by creating temporary files containing assembler statements
3571 and then assembling these.  The @option{-S} command line option can be
3572 used to specify the path to the assembler that dlltool will use,
3573 and the @option{-f} option can be used to pass specific flags to that
3574 assembler.  The @option{-n} can be used to prevent dlltool from deleting
3575 these temporary assembler files when it is done, and if @option{-n} is
3576 specified twice then this will prevent dlltool from deleting the
3577 temporary object files it used to build the library.
3578
3579 Here is an example of creating a DLL from a source file @samp{dll.c} and
3580 also creating a program (from an object file called @samp{program.o})
3581 that uses that DLL:
3582
3583 @smallexample
3584   gcc -c dll.c
3585   dlltool -e exports.o -l dll.lib dll.o
3586   gcc dll.o exports.o -o dll.dll
3587   gcc program.o dll.lib -o program
3588 @end smallexample
3589
3590
3591 @command{dlltool} may also be used to query an existing import library
3592 to determine the name of the DLL to which it is associated.  See the 
3593 description of the @option{-I} or @option{--identify} option.
3594  
3595 @c man end
3596
3597 @c man begin OPTIONS dlltool
3598
3599 The command line options have the following meanings:
3600
3601 @table @env
3602
3603 @item -d @var{filename}
3604 @itemx --input-def @var{filename}
3605 @cindex input .def file
3606 Specifies the name of a @file{.def} file to be read in and processed.
3607
3608 @item -b @var{filename}
3609 @itemx --base-file @var{filename}
3610 @cindex base files
3611 Specifies the name of a base file to be read in and processed.  The
3612 contents of this file will be added to the relocation section in the
3613 exports file generated by dlltool.
3614
3615 @item -e @var{filename}
3616 @itemx --output-exp @var{filename}
3617 Specifies the name of the export file to be created by dlltool.
3618
3619 @item -z @var{filename}
3620 @itemx --output-def @var{filename}
3621 Specifies the name of the @file{.def} file to be created by dlltool.
3622
3623 @item -l @var{filename}
3624 @itemx --output-lib @var{filename}
3625 Specifies the name of the library file to be created by dlltool.
3626
3627 @item -y @var{filename}
3628 @itemx --output-delaylib @var{filename}
3629 Specifies the name of the delay-import library file to be created by dlltool.
3630
3631 @item --export-all-symbols
3632 Treat all global and weak defined symbols found in the input object
3633 files as symbols to be exported.  There is a small list of symbols which
3634 are not exported by default; see the @option{--no-default-excludes}
3635 option.  You may add to the list of symbols to not export by using the
3636 @option{--exclude-symbols} option.
3637
3638 @item --no-export-all-symbols
3639 Only export symbols explicitly listed in an input @file{.def} file or in
3640 @samp{.drectve} sections in the input object files.  This is the default
3641 behaviour.  The @samp{.drectve} sections are created by @samp{dllexport}
3642 attributes in the source code.
3643
3644 @item --exclude-symbols @var{list}
3645 Do not export the symbols in @var{list}.  This is a list of symbol names
3646 separated by comma or colon characters.  The symbol names should not
3647 contain a leading underscore.  This is only meaningful when
3648 @option{--export-all-symbols} is used.
3649
3650 @item --no-default-excludes
3651 When @option{--export-all-symbols} is used, it will by default avoid
3652 exporting certain special symbols.  The current list of symbols to avoid
3653 exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0},
3654 @samp{impure_ptr}.  You may use the @option{--no-default-excludes} option
3655 to go ahead and export these special symbols.  This is only meaningful
3656 when @option{--export-all-symbols} is used.
3657
3658 @item -S @var{path}
3659 @itemx --as @var{path}
3660 Specifies the path, including the filename, of the assembler to be used
3661 to create the exports file.
3662
3663 @item -f @var{options}
3664 @itemx --as-flags @var{options}
3665 Specifies any specific command line options to be passed to the
3666 assembler when building the exports file.  This option will work even if
3667 the @option{-S} option is not used.  This option only takes one argument,
3668 and if it occurs more than once on the command line, then later
3669 occurrences will override earlier occurrences.  So if it is necessary to
3670 pass multiple options to the assembler they should be enclosed in
3671 double quotes.
3672
3673 @item -D @var{name}
3674 @itemx --dll-name @var{name}
3675 Specifies the name to be stored in the @file{.def} file as the name of
3676 the DLL when the @option{-e} option is used.  If this option is not
3677 present, then the filename given to the @option{-e} option will be
3678 used as the name of the DLL.
3679
3680 @item -m @var{machine}
3681 @itemx -machine @var{machine}
3682 Specifies the type of machine for which the library file should be
3683 built.  @command{dlltool} has a built in default type, depending upon how
3684 it was created, but this option can be used to override that.  This is
3685 normally only useful when creating DLLs for an ARM processor, when the
3686 contents of the DLL are actually encode using Thumb instructions.
3687
3688 @item -a
3689 @itemx --add-indirect
3690 Specifies that when @command{dlltool} is creating the exports file it
3691 should add a section which allows the exported functions to be
3692 referenced without using the import library.  Whatever the hell that
3693 means!
3694
3695 @item -U
3696 @itemx --add-underscore
3697 Specifies that when @command{dlltool} is creating the exports file it
3698 should prepend an underscore to the names of @emph{all} exported symbols.
3699
3700 @item --add-stdcall-underscore
3701 Specifies that when @command{dlltool} is creating the exports file it
3702 should prepend an underscore to the names of exported @emph{stdcall}
3703 functions. Variable names and non-stdcall function names are not modified.
3704 This option is useful when creating GNU-compatible import libs for third
3705 party DLLs that were built with MS-Windows tools.
3706
3707 @item -k
3708 @itemx --kill-at
3709 Specifies that when @command{dlltool} is creating the exports file it
3710 should not append the string @samp{@@ <number>}.  These numbers are
3711 called ordinal numbers and they represent another way of accessing the
3712 function in a DLL, other than by name.
3713
3714 @item -A
3715 @itemx --add-stdcall-alias
3716 Specifies that when @command{dlltool} is creating the exports file it
3717 should add aliases for stdcall symbols without @samp{@@ <number>}
3718 in addition to the symbols with @samp{@@ <number>}.
3719
3720 @item -p
3721 @itemx --ext-prefix-alias @var{prefix}
3722 Causes @command{dlltool} to create external aliases for all DLL
3723 imports with the specified prefix.  The aliases are created for both
3724 external and import symbols with no leading underscore.
3725
3726 @item -x
3727 @itemx --no-idata4
3728 Specifies that when @command{dlltool} is creating the exports and library
3729 files it should omit the @code{.idata4} section.  This is for compatibility
3730 with certain operating systems.
3731
3732 @item --use-nul-prefixed-import-tables
3733 Specifies that when @command{dlltool} is creating the exports and library
3734 files it should prefix the @code{.idata4} and @code{.idata5} by zero an
3735 element. This emulates old gnu import library generation of
3736 @code{dlltool}. By default this option is turned off.
3737
3738 @item -c
3739 @itemx --no-idata5
3740 Specifies that when @command{dlltool} is creating the exports and library
3741 files it should omit the @code{.idata5} section.  This is for compatibility
3742 with certain operating systems.
3743
3744 @item -I @var{filename}
3745 @itemx --identify @var{filename}
3746 Specifies that @command{dlltool} should inspect the import library
3747 indicated by @var{filename} and report, on @code{stdout}, the name(s)
3748 of the associated DLL(s).  This can be performed in addition to any
3749 other operations indicated by the other options and arguments.
3750 @command{dlltool} fails if the import library does not exist or is not
3751 actually an import library. See also @option{--identify-strict}.
3752
3753 @item --identify-strict
3754 Modifies the behavior of the @option{--identify} option, such
3755 that an error is reported if @var{filename} is associated with
3756 more than one DLL.
3757
3758 @item -i
3759 @itemx --interwork
3760 Specifies that @command{dlltool} should mark the objects in the library
3761 file and exports file that it produces as supporting interworking
3762 between ARM and Thumb code.
3763
3764 @item -n
3765 @itemx --nodelete
3766 Makes @command{dlltool} preserve the temporary assembler files it used to
3767 create the exports file.  If this option is repeated then dlltool will
3768 also preserve the temporary object files it uses to create the library
3769 file.
3770
3771 @item -t @var{prefix}
3772 @itemx --temp-prefix @var{prefix}
3773 Makes @command{dlltool} use @var{prefix} when constructing the names of
3774 temporary assembler and object files.  By default, the temp file prefix
3775 is generated from the pid.
3776
3777 @item -v
3778 @itemx --verbose
3779 Make dlltool describe what it is doing.
3780
3781 @item -h
3782 @itemx --help
3783 Displays a list of command line options and then exits.
3784
3785 @item -V
3786 @itemx --version
3787 Displays dlltool's version number and then exits.
3788
3789 @end table
3790
3791 @c man end
3792
3793 @menu
3794 * def file format::             The format of the dlltool @file{.def} file
3795 @end menu
3796
3797 @node def file format
3798 @section The format of the @command{dlltool} @file{.def} file
3799
3800 A @file{.def} file contains any number of the following commands:
3801
3802 @table @asis
3803
3804 @item @code{NAME} @var{name} @code{[ ,} @var{base} @code{]}
3805 The result is going to be named @var{name}@code{.exe}.
3806
3807 @item @code{LIBRARY} @var{name} @code{[ ,} @var{base} @code{]}
3808 The result is going to be named @var{name}@code{.dll}.
3809
3810 @item @code{EXPORTS ( ( (} @var{name1} @code{[ = } @var{name2} @code{] ) | ( } @var{name1} @code{=} @var{module-name} @code{.} @var{external-name} @code{) )}
3811 @item @code{[} @var{integer} @code{] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *}
3812 Declares @var{name1} as an exported symbol from the DLL, with optional
3813 ordinal number @var{integer}, or declares @var{name1} as an alias
3814 (forward) of the function @var{external-name} in the DLL
3815 @var{module-name}.
3816
3817 @item @code{IMPORTS ( (} @var{internal-name} @code{=} @var{module-name} @code{.} @var{integer} @code{) | [} @var{internal-name} @code{= ]} @var{module-name} @code{.} @var{external-name} @code{) ) *}
3818 Declares that @var{external-name} or the exported function whose
3819 ordinal number is @var{integer} is to be imported from the file
3820 @var{module-name}.  If @var{internal-name} is specified then this is
3821 the name that the imported function will be referred to in the body of
3822 the DLL.
3823
3824 @item @code{DESCRIPTION} @var{string}
3825 Puts @var{string} into the output @file{.exp} file in the
3826 @code{.rdata} section.
3827
3828 @item @code{STACKSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
3829 @item @code{HEAPSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
3830 Generates @code{--stack} or @code{--heap}
3831 @var{number-reserve},@var{number-commit} in the output @code{.drectve}
3832 section.  The linker will see this and act upon it.
3833
3834 @item @code{CODE} @var{attr} @code{+}
3835 @item @code{DATA} @var{attr} @code{+}
3836 @item @code{SECTIONS (} @var{section-name} @var{attr}@code{ + ) *}
3837 Generates @code{--attr} @var{section-name} @var{attr} in the output
3838 @code{.drectve} section, where @var{attr} is one of @code{READ},
3839 @code{WRITE}, @code{EXECUTE} or @code{SHARED}.  The linker will see
3840 this and act upon it.
3841
3842 @end table
3843
3844 @ignore
3845 @c man begin SEEALSO dlltool
3846 The Info pages for @file{binutils}.
3847 @c man end
3848 @end ignore
3849
3850 @node readelf
3851 @chapter readelf
3852
3853 @cindex ELF file information
3854 @kindex readelf
3855
3856 @c man title readelf Displays information about ELF files.
3857
3858 @smallexample
3859 @c man begin SYNOPSIS readelf
3860 readelf [@option{-a}|@option{--all}]
3861         [@option{-h}|@option{--file-header}]
3862         [@option{-l}|@option{--program-headers}|@option{--segments}]
3863         [@option{-S}|@option{--section-headers}|@option{--sections}]
3864         [@option{-g}|@option{--section-groups}]
3865         [@option{-t}|@option{--section-details}]
3866         [@option{-e}|@option{--headers}]
3867         [@option{-s}|@option{--syms}|@option{--symbols}]
3868         [@option{-n}|@option{--notes}]
3869         [@option{-r}|@option{--relocs}]
3870         [@option{-u}|@option{--unwind}]
3871         [@option{-d}|@option{--dynamic}]
3872         [@option{-V}|@option{--version-info}]
3873         [@option{-A}|@option{--arch-specific}]
3874         [@option{-D}|@option{--use-dynamic}]
3875         [@option{-x} <number or name>|@option{--hex-dump=}<number or name>]
3876         [@option{-p} <number or name>|@option{--string-dump=}<number or name>]
3877         [@option{-R} <number or name>|@option{--relocated-dump=}<number or name>]
3878         [@option{-c}|@option{--archive-index}]
3879         [@option{-w[lLiaprmfFsoR]}|
3880          @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]]
3881         [@option{-I}|@option{-histogram}]
3882         [@option{-v}|@option{--version}]
3883         [@option{-W}|@option{--wide}]
3884         [@option{-H}|@option{--help}]
3885         @var{elffile}@dots{}
3886 @c man end
3887 @end smallexample
3888
3889 @c man begin DESCRIPTION readelf
3890
3891 @command{readelf} displays information about one or more ELF format object
3892 files.  The options control what particular information to display.
3893
3894 @var{elffile}@dots{} are the object files to be examined.  32-bit and
3895 64-bit ELF files are supported, as are archives containing ELF files.
3896
3897 This program performs a similar function to @command{objdump} but it
3898 goes into more detail and it exists independently of the @sc{bfd}
3899 library, so if there is a bug in @sc{bfd} then readelf will not be
3900 affected.
3901
3902 @c man end
3903
3904 @c man begin OPTIONS readelf
3905
3906 The long and short forms of options, shown here as alternatives, are
3907 equivalent.  At least one option besides @samp{-v} or @samp{-H} must be
3908 given.
3909
3910 @table @env
3911 @item -a
3912 @itemx --all
3913 Equivalent to specifying @option{--file-header},
3914 @option{--program-headers}, @option{--sections}, @option{--symbols},
3915 @option{--relocs}, @option{--dynamic}, @option{--notes} and
3916 @option{--version-info}.
3917
3918 @item -h
3919 @itemx --file-header
3920 @cindex ELF file header information
3921 Displays the information contained in the ELF header at the start of the
3922 file.
3923
3924 @item -l
3925 @itemx --program-headers
3926 @itemx --segments
3927 @cindex ELF program header information
3928 @cindex ELF segment information
3929 Displays the information contained in the file's segment headers, if it
3930 has any.
3931
3932 @item -S
3933 @itemx --sections
3934 @itemx --section-headers
3935 @cindex ELF section information
3936 Displays the information contained in the file's section headers, if it
3937 has any.
3938
3939 @item -g
3940 @itemx --section-groups
3941 @cindex ELF section group information
3942 Displays the information contained in the file's section groups, if it
3943 has any.
3944
3945 @item -t
3946 @itemx --section-details
3947 @cindex ELF section information
3948 Displays the detailed section information. Implies @option{-S}.
3949
3950 @item -s
3951 @itemx --symbols
3952 @itemx --syms
3953 @cindex ELF symbol table information
3954 Displays the entries in symbol table section of the file, if it has one.
3955
3956 @item -e
3957 @itemx --headers
3958 Display all the headers in the file.  Equivalent to @option{-h -l -S}.
3959
3960 @item -n
3961 @itemx --notes
3962 @cindex ELF notes
3963 Displays the contents of the NOTE segments and/or sections, if any.
3964
3965 @item -r
3966 @itemx --relocs
3967 @cindex ELF reloc information
3968 Displays the contents of the file's relocation section, if it has one.
3969
3970 @item -u
3971 @itemx --unwind
3972 @cindex unwind information
3973 Displays the contents of the file's unwind section, if it has one.  Only
3974 the unwind sections for IA64 ELF files are currently supported.
3975
3976 @item -d
3977 @itemx --dynamic
3978 @cindex ELF dynamic section information
3979 Displays the contents of the file's dynamic section, if it has one.
3980
3981 @item -V
3982 @itemx --version-info
3983 @cindex ELF version sections informations
3984 Displays the contents of the version sections in the file, it they
3985 exist.
3986
3987 @item -A
3988 @itemx --arch-specific
3989 Displays architecture-specific information in the file, if there
3990 is any.
3991
3992 @item -D
3993 @itemx --use-dynamic
3994 When displaying symbols, this option makes @command{readelf} use the
3995 symbol table in the file's dynamic section, rather than the one in the
3996 symbols section.
3997
3998 @item -x <number or name>
3999 @itemx --hex-dump=<number or name>
4000 Displays the contents of the indicated section as a hexadecimal bytes.
4001 A number identifies a particular section by index in the section table;
4002 any other string identifies all sections with that name in the object file.
4003
4004 @item -R <number or name>
4005 @itemx --relocated-dump=<number or name>
4006 Displays the contents of the indicated section as a hexadecimal
4007 bytes.  A number identifies a particular section by index in the
4008 section table; any other string identifies all sections with that name
4009 in the object file.  The contents of the section will be relocated
4010 before they are displayed.
4011
4012 @item -p <number or name>
4013 @itemx --string-dump=<number or name>
4014 Displays the contents of the indicated section as printable strings.
4015 A number identifies a particular section by index in the section table;
4016 any other string identifies all sections with that name in the object file.
4017
4018 @item -c
4019 @itemx --archive-index
4020 @cindex Archive file symbol index information
4021 Displays the file symbol index infomation contained in the header part
4022 of binary archives.  Performs the same function as the @option{t}
4023 command to @command{ar}, but without using the BFD library.  @xref{ar}.
4024
4025 @item -w[lLiaprmfFsoR]
4026 @itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]
4027 Displays the contents of the debug sections in the file, if any are
4028 present.  If one of the optional letters or words follows the switch
4029 then only data found in those specific sections will be dumped.
4030
4031 Note: the @option{=decodedline} option will display the interpreted
4032 contents of a .debug_line section whereas the @option{=rawline} option
4033 dumps the contents in a raw format.
4034
4035 @item -I
4036 @itemx --histogram
4037 Display a histogram of bucket list lengths when displaying the contents
4038 of the symbol tables.
4039
4040 @item -v
4041 @itemx --version
4042 Display the version number of readelf.
4043
4044 @item -W
4045 @itemx --wide
4046 Don't break output lines to fit into 80 columns. By default
4047 @command{readelf} breaks section header and segment listing lines for
4048 64-bit ELF files, so that they fit into 80 columns. This option causes
4049 @command{readelf} to print each section header resp. each segment one a
4050 single line, which is far more readable on terminals wider than 80 columns.
4051
4052 @item -H
4053 @itemx --help
4054 Display the command line options understood by @command{readelf}.
4055
4056 @end table
4057
4058 @c man end
4059
4060 @ignore
4061 @c man begin SEEALSO readelf
4062 objdump(1), and the Info entries for @file{binutils}.
4063 @c man end
4064 @end ignore
4065
4066 @node Common Options
4067 @chapter Common Options
4068
4069 The following command-line options are supported by all of the
4070 programs described in this manual.
4071
4072 @c man begin OPTIONS
4073 @table @env
4074 @include at-file.texi
4075 @c man end
4076
4077 @item --help
4078 Display the command-line options supported by the program.
4079
4080 @item --version
4081 Display the version number of the program.
4082
4083 @c man begin OPTIONS
4084 @end table
4085 @c man end
4086
4087 @node Selecting the Target System
4088 @chapter Selecting the Target System
4089
4090 You can specify two aspects of the target system to the @sc{gnu}
4091 binary file utilities, each in several ways:
4092
4093 @itemize @bullet
4094 @item
4095 the target
4096
4097 @item
4098 the architecture
4099 @end itemize
4100
4101 In the following summaries, the lists of ways to specify values are in
4102 order of decreasing precedence.  The ways listed first override those
4103 listed later.
4104
4105 The commands to list valid values only list the values for which the
4106 programs you are running were configured.  If they were configured with
4107 @option{--enable-targets=all}, the commands list most of the available
4108 values, but a few are left out; not all targets can be configured in at
4109 once because some of them can only be configured @dfn{native} (on hosts
4110 with the same type as the target system).
4111
4112 @menu
4113 * Target Selection::
4114 * Architecture Selection::
4115 @end menu
4116
4117 @node Target Selection
4118 @section Target Selection
4119
4120 A @dfn{target} is an object file format.  A given target may be
4121 supported for multiple architectures (@pxref{Architecture Selection}).
4122 A target selection may also have variations for different operating
4123 systems or architectures.
4124
4125 The command to list valid target values is @samp{objdump -i}
4126 (the first column of output contains the relevant information).
4127
4128 Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips},
4129 @samp{a.out-sunos-big}.
4130
4131 You can also specify a target using a configuration triplet.  This is
4132 the same sort of name that is passed to @file{configure} to specify a
4133 target.  When you use a configuration triplet as an argument, it must be
4134 fully canonicalized.  You can see the canonical version of a triplet by
4135 running the shell script @file{config.sub} which is included with the
4136 sources.
4137
4138 Some sample configuration triplets are: @samp{m68k-hp-bsd},
4139 @samp{mips-dec-ultrix}, @samp