1 \input texinfo @c -*- Texinfo -*-
2 @setfilename binutils.info
3 @settitle @sc{gnu} Binary Utilities
12 @c man begin COPYRIGHT
13 Copyright @copyright{} 1991-2021 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this document
16 under the terms of the GNU Free Documentation License, Version 1.3
17 or any later version published by the Free Software Foundation;
18 with no Invariant Sections, with no Front-Cover Texts, and with no
19 Back-Cover Texts. A copy of the license is included in the
20 section entitled ``GNU Free Documentation License''.
25 @dircategory Software development
27 * Binutils: (binutils). The GNU binary utilities.
30 @dircategory Individual utilities
32 * addr2line: (binutils)addr2line. Convert addresses to file and line.
33 * ar: (binutils)ar. Create, modify, and extract from archives.
34 * c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols.
35 * cxxfilt: (binutils)c++filt. MS-DOS name for c++filt.
36 * dlltool: (binutils)dlltool. Create files needed to build and use DLLs.
37 * nm: (binutils)nm. List symbols from object files.
38 * objcopy: (binutils)objcopy. Copy and translate object files.
39 * objdump: (binutils)objdump. Display information from object files.
40 * ranlib: (binutils)ranlib. Generate index to archive contents.
41 * readelf: (binutils)readelf. Display the contents of ELF format files.
42 * size: (binutils)size. List section sizes and total size.
43 * strings: (binutils)strings. List printable strings from files.
44 * strip: (binutils)strip. Discard symbols.
45 * elfedit: (binutils)elfedit. Update ELF header and property of ELF files.
46 * windmc: (binutils)windmc. Generator for Windows message resources.
47 * windres: (binutils)windres. Manipulate Windows resources.
51 @title The @sc{gnu} Binary Utilities
52 @ifset VERSION_PACKAGE
53 @subtitle @value{VERSION_PACKAGE}
55 @subtitle Version @value{VERSION}
57 @subtitle @value{UPDATED}
58 @author Roland H. Pesch
59 @author Jeffrey M. Osier
60 @author Cygnus Support
64 {\parskip=0pt \hfill Cygnus Support\par \hfill
65 Texinfo \texinfoversion\par }
68 @vskip 0pt plus 1filll
77 This brief manual contains documentation for the @sc{gnu} binary
79 @ifset VERSION_PACKAGE
80 @value{VERSION_PACKAGE}
82 version @value{VERSION}:
87 Create, modify, and extract from archives
90 List symbols from object files
93 Copy and translate object files
96 Display information from object files
99 Generate index to archive contents
102 Display the contents of ELF format files.
105 List file section sizes and total size
108 List printable strings from files
114 Update the ELF header and program property of ELF files.
117 Demangle encoded C++ symbols (on MS-DOS, this program is named
121 Convert addresses into file names and line numbers
124 Manipulate Windows resources
127 Generator for Windows message resources
130 Create the files needed to build and use Dynamic Link Libraries
134 This document is distributed under the terms of the GNU Free
135 Documentation License version 1.3. A copy of the license is included
136 in the section entitled ``GNU Free Documentation License''.
139 * ar:: Create, modify, and extract from archives
140 * nm:: List symbols from object files
141 * objcopy:: Copy and translate object files
142 * objdump:: Display information from object files
143 * ranlib:: Generate index to archive contents
144 * size:: List section sizes and total size
145 * strings:: List printable strings from files
146 * strip:: Discard symbols
147 * c++filt:: Filter to demangle encoded C++ symbols
148 * cxxfilt: c++filt. MS-DOS name for c++filt
149 * addr2line:: Convert addresses to file and line
150 * windmc:: Generator for Windows message resources
151 * windres:: Manipulate Windows resources
152 * dlltool:: Create files needed to build and use DLLs
153 * readelf:: Display the contents of ELF format files
154 * elfedit:: Update ELF header and property of ELF files
155 * Common Options:: Command-line options for all utilities
156 * Selecting the Target System:: How these utilities determine the target
157 * debuginfod:: Using binutils with debuginfod
158 * Reporting Bugs:: Reporting Bugs
159 * GNU Free Documentation License:: GNU Free Documentation License
160 * Binutils Index:: Binutils Index
168 @cindex collections of files
170 @c man title ar create, modify, and extract from archives
173 ar [-]@var{p}[@var{mod}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@option{--output} @var{dirname}] [@option{--record-libdeps} @var{libdeps}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}]
174 ar -M [ <mri-script ]
177 @c man begin DESCRIPTION ar
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).
184 The original files' contents, mode (permissions), timestamp, owner, and
185 group are preserved in the archive, and can be restored on
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).
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. Since libraries often will depend on other libraries,
200 @command{ar} can also record the dependencies of a library when the
201 @option{--record-libdeps} option is specified.
204 @command{ar} creates an index to the symbols defined in relocatable
205 object modules in the archive when you specify the modifier @samp{s}.
206 Once created, this index is updated in the archive whenever @command{ar}
207 makes a change to its contents (save for the @samp{q} update operation).
208 An archive with such an index speeds up linking to the library, and
209 allows routines in the library to call each other without regard to
210 their placement in the archive.
212 You may use @samp{nm -s} or @samp{nm --print-armap} to list this index
213 table. If an archive lacks the table, another form of @command{ar} called
214 @command{ranlib} can be used to add just the table.
216 @cindex thin archives
217 @sc{gnu} @command{ar} can optionally create a @emph{thin} archive,
218 which contains a symbol index and references to the original copies
219 of the member files of the archive. This is useful for building
220 libraries for use within a local build tree, where the relocatable
221 objects are expected to remain available, and copying the contents of
222 each object would only waste time and space.
224 An archive can either be @emph{thin} or it can be normal. It cannot
225 be both at the same time. Once an archive is created its format
226 cannot be changed without first deleting it and then creating a new
227 archive in its place.
229 Thin archives are also @emph{flattened}, so that adding one thin
230 archive to another thin archive does not nest it, as would happen with
231 a normal archive. Instead the elements of the first archive are added
232 individually to the second archive.
234 The paths to the elements of the archive are stored relative to the
237 @cindex compatibility, @command{ar}
238 @cindex @command{ar} compatibility
239 @sc{gnu} @command{ar} is designed to be compatible with two different
240 facilities. You can control its activity using command-line options,
241 like the different varieties of @command{ar} on Unix systems; or, if you
242 specify the single command-line option @option{-M}, you can control it
243 with a script supplied via standard input, like the MRI ``librarian''
249 * ar cmdline:: Controlling @command{ar} on the command line
250 * ar scripts:: Controlling @command{ar} with a script
255 @section Controlling @command{ar} on the Command Line
258 @c man begin SYNOPSIS ar
259 ar [@option{-X32_64}] [@option{-}]@var{p}[@var{mod}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@option{--output} @var{dirname}] [@option{--record-libdeps} @var{libdeps}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}]
263 @cindex Unix compatibility, @command{ar}
264 When you use @command{ar} in the Unix style, @command{ar} insists on at least two
265 arguments to execute: one keyletter specifying the @emph{operation}
266 (optionally accompanied by other keyletters specifying
267 @emph{modifiers}), and the archive name to act on.
269 Most operations can also accept further @var{member} arguments,
270 specifying particular files to operate on.
272 @c man begin OPTIONS ar
274 @sc{gnu} @command{ar} allows you to mix the operation code @var{p} and modifier
275 flags @var{mod} in any order, within the first command-line argument.
277 If you wish, you may begin the first command-line argument with a
280 @cindex operations on archive
281 The @var{p} keyletter specifies what operation to execute; it may be
282 any of the following, but you must specify only one of them:
286 @cindex deleting from archive
287 @emph{Delete} modules from the archive. Specify the names of modules to
288 be deleted as @var{member}@dots{}; the archive is untouched if you
289 specify no files to delete.
291 If you specify the @samp{v} modifier, @command{ar} lists each module
295 @cindex moving in archive
296 Use this operation to @emph{move} members in an archive.
298 The ordering of members in an archive can make a difference in how
299 programs are linked using the library, if a symbol is defined in more
302 If no modifiers are used with @code{m}, any members you name in the
303 @var{member} arguments are moved to the @emph{end} of the archive;
304 you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a
305 specified place instead.
308 @cindex printing from archive
309 @emph{Print} the specified members of the archive, to the standard
310 output file. If the @samp{v} modifier is specified, show the member
311 name before copying its contents to standard output.
313 If you specify no @var{member} arguments, all the files in the archive are
317 @cindex quick append to archive
318 @emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of
319 @var{archive}, without checking for replacement.
321 The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this
322 operation; new members are always placed at the end of the archive.
324 The modifier @samp{v} makes @command{ar} list each file as it is appended.
326 Since the point of this operation is speed, implementations of
327 @command{ar} have the option of not updating the archive's symbol
328 table if one exists. Too many different systems however assume that
329 symbol tables are always up-to-date, so @sc{gnu} @command{ar} will
330 rebuild the table even with a quick append.
332 Note - @sc{gnu} @command{ar} treats the command @samp{qs} as a
333 synonym for @samp{r} - replacing already existing files in the
334 archive and appending new ones at the end.
337 @cindex replacement in archive
338 Insert the files @var{member}@dots{} into @var{archive} (with
339 @emph{replacement}). This operation differs from @samp{q} in that any
340 previously existing members are deleted if their names match those being
343 If one of the files named in @var{member}@dots{} does not exist, @command{ar}
344 displays an error message, and leaves undisturbed any existing members
345 of the archive matching that name.
347 By default, new members are added at the end of the file; but you may
348 use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request
349 placement relative to some existing member.
351 The modifier @samp{v} used with this operation elicits a line of
352 output for each file inserted, along with one of the letters @samp{a} or
353 @samp{r} to indicate whether the file was appended (no old member
354 deleted) or replaced.
358 Add an index to the archive, or update it if it already exists. Note
359 this command is an exception to the rule that there can only be one
360 command letter, as it is possible to use it as either a command or a
361 modifier. In either case it does the same thing.
364 @cindex contents of archive
365 Display a @emph{table} listing the contents of @var{archive}, or those
366 of the files listed in @var{member}@dots{} that are present in the
367 archive. Normally only the member name is shown, but if the modifier
368 @samp{O} is specified, then the corresponding offset of the member is also
369 displayed. Finally, in order to see the modes (permissions), timestamp,
370 owner, group, and size the @samp{v} modifier should be included.
372 If you do not specify a @var{member}, all files in the archive
375 @cindex repeated names in archive
376 @cindex name duplication in archive
377 If there is more than one file with the same name (say, @samp{fie}) in
378 an archive (say @samp{b.a}), @samp{ar t b.a fie} lists only the
379 first instance; to see them all, you must ask for a complete
380 listing---in our example, @samp{ar t b.a}.
381 @c WRS only; per Gumby, this is implementation-dependent, and in a more
382 @c recent case in fact works the other way.
385 @cindex extract from archive
386 @emph{Extract} members (named @var{member}) from the archive. You can
387 use the @samp{v} modifier with this operation, to request that
388 @command{ar} list each name as it extracts it.
390 If you do not specify a @var{member}, all files in the archive
393 Files cannot be extracted from a thin archive, and there are
394 restrictions on extracting from archives created with @option{P}: The
395 paths must not be absolute, may not contain @code{..}, and any
396 subdirectories in the paths must exist. If it is desired to avoid
397 these restrictions then used the @option{--output} option to specify
401 A number of modifiers (@var{mod}) may immediately follow the @var{p}
402 keyletter, to specify variations on an operation's behavior:
406 @cindex relative placement in archive
407 Add new files @emph{after} an existing member of the
408 archive. If you use the modifier @samp{a}, the name of an existing archive
409 member must be present as the @var{relpos} argument, before the
410 @var{archive} specification.
413 Add new files @emph{before} an existing member of the
414 archive. If you use the modifier @samp{b}, the name of an existing archive
415 member must be present as the @var{relpos} argument, before the
416 @var{archive} specification. (same as @samp{i}).
419 @cindex creating archives
420 @emph{Create} the archive. The specified @var{archive} is always
421 created if it did not exist, when you request an update. But a warning is
422 issued unless you specify in advance that you expect to create it, by
426 @cindex deterministic archives
427 @kindex --enable-deterministic-archives
428 Operate in @emph{deterministic} mode. When adding files and the archive
429 index use zero for UIDs, GIDs, timestamps, and use consistent file modes
430 for all files. When this option is used, if @command{ar} is used with
431 identical options and identical input files, multiple runs will create
432 identical output files regardless of the input files' owners, groups,
433 file modes, or modification times.
435 If @file{binutils} was configured with
436 @option{--enable-deterministic-archives}, then this mode is on by default.
437 It can be disabled with the @samp{U} modifier, below.
440 Truncate names in the archive. @sc{gnu} @command{ar} will normally permit file
441 names of any length. This will cause it to create archives which are
442 not compatible with the native @command{ar} program on some systems. If
443 this is a concern, the @samp{f} modifier may be used to truncate file
444 names when putting them in the archive.
447 Insert new files @emph{before} an existing member of the
448 archive. If you use the modifier @samp{i}, the name of an existing archive
449 member must be present as the @var{relpos} argument, before the
450 @var{archive} specification. (same as @samp{b}).
453 @c This modifier was accepted but not used.
454 @c whaffor ar l modifier??? presumably compat; with
455 @c what???---doc@@cygnus.com, 25jan91
456 Specify dependencies of this library. The dependencies must immediately
457 follow this option character, must use the same syntax as the linker
458 command line, and must be specified within a single argument. I.e., if
459 multiple items are needed, they must be quoted to form a single command
460 line argument. For example @samp{L "-L/usr/local/lib -lmydep1 -lmydep2"}
463 Uses the @var{count} parameter. This is used if there are multiple
464 entries in the archive with the same name. Extract or delete instance
465 @var{count} of the given name from the archive.
468 @cindex dates in archive
469 Preserve the @emph{original} dates of members when extracting them. If
470 you do not specify this modifier, files extracted from the archive
471 are stamped with the time of extraction.
474 @cindex offsets of files
475 Display member offsets inside the archive. Use together with the @samp{t}
479 Use the full path name when matching or storing names in the archive.
480 Archives created with full path names are not POSIX compliant, and
481 thus may not work with tools other than up to date @sc{gnu} tools.
482 Modifying such archives with @sc{gnu} @command{ar} without using
483 @option{P} will remove the full path names unless the archive is a
484 thin archive. Note that @option{P} may be useful when adding files to
485 a thin archive since @option{r} without @option{P} ignores the path
486 when choosing which element to replace. Thus
488 ar rcST archive.a subdir/file1 subdir/file2 file1
490 will result in the first @code{subdir/file1} being replaced with
491 @code{file1} from the current directory. Adding @option{P} will
492 prevent this replacement.
495 @cindex writing archive index
496 Write an object-file index into the archive, or update an existing one,
497 even if no other change is made to the archive. You may use this modifier
498 flag either with any operation, or alone. Running @samp{ar s} on an
499 archive is equivalent to running @samp{ranlib} on it.
502 @cindex not writing archive index
503 Do not generate an archive symbol table. This can speed up building a
504 large library in several steps. The resulting archive can not be used
505 with the linker. In order to build a symbol table, you must omit the
506 @samp{S} modifier on the last execution of @samp{ar}, or you must run
507 @samp{ranlib} on the archive.
510 @cindex creating thin archive
511 Make the specified @var{archive} a @emph{thin} archive. If it already
512 exists and is a regular archive, the existing members must be present
513 in the same directory as @var{archive}.
516 @cindex updating an archive
517 Normally, @samp{ar r}@dots{} inserts all files
518 listed into the archive. If you would like to insert @emph{only} those
519 of the files you list that are newer than existing members of the same
520 names, use this modifier. The @samp{u} modifier is allowed only for the
521 operation @samp{r} (replace). In particular, the combination @samp{qu} is
522 not allowed, since checking the timestamps would lose any speed
523 advantage from the operation @samp{q}.
526 @cindex deterministic archives
527 @kindex --enable-deterministic-archives
528 Do @emph{not} operate in @emph{deterministic} mode. This is the inverse
529 of the @samp{D} modifier, above: added files and the archive index will
530 get their actual UID, GID, timestamp, and file mode values.
532 This is the default unless @file{binutils} was configured with
533 @option{--enable-deterministic-archives}.
536 This modifier requests the @emph{verbose} version of an operation. Many
537 operations display additional information, such as filenames processed,
538 when the modifier @samp{v} is appended.
541 This modifier shows the version number of @command{ar}.
544 The @command{ar} program also supports some command-line options which
545 are neither modifiers nor actions, but which do change its behaviour
550 Displays the list of command-line options supported by @command{ar}
554 Displays the version information of @command{ar} and then exits.
557 @command{ar} ignores an initial option spelled @samp{-X32_64}, for
558 compatibility with AIX. The behaviour produced by this option is the
559 default for @sc{gnu} @command{ar}. @command{ar} does not support any
560 of the other @samp{-X} options; in particular, it does not support
561 @option{-X32} which is the default for AIX @command{ar}.
563 @item --plugin @var{name}
565 The optional command-line switch @option{--plugin @var{name}} causes
566 @command{ar} to load the plugin called @var{name} which adds support
567 for more file formats, including object files with link-time
568 optimization information.
570 This option is only available if the toolchain has been built with
571 plugin support enabled.
573 If @option{--plugin} is not provided, but plugin support has been
574 enabled then @command{ar} iterates over the files in
575 @file{$@{libdir@}/bfd-plugins} in alphabetic order and the first
576 plugin that claims the object in question is used.
578 Please note that this plugin search directory is @emph{not} the one
579 used by @command{ld}'s @option{-plugin} option. In order to make
580 @command{ar} use the linker plugin it must be copied into the
581 @file{$@{libdir@}/bfd-plugins} directory. For GCC based compilations
582 the linker plugin is called @file{liblto_plugin.so.0.0.0}. For Clang
583 based compilations it is called @file{LLVMgold.so}. The GCC plugin
584 is always backwards compatible with earlier versions, so it is
585 sufficient to just copy the newest one.
587 @item --target @var{target}
588 The optional command-line switch @option{--target @var{bfdname}}
589 specifies that the archive members are in an object code format
590 different from your system's default format. See
591 @xref{Target Selection}, for more information.
593 @item --output @var{dirname}
594 The @option{--output} option can be used to specify a path to a
595 directory into which archive members should be extracted. If this
596 option is not specified then the current directory will be used.
598 Note - although the presence of this option does imply a @option{x}
599 extraction operation that option must still be included on the command
602 @item --record-libdeps @var{libdeps}
603 The @option{--record-libdeps} option is identical to the @option{l} modifier,
604 just handled in long form.
610 @c man begin SEEALSO ar
611 nm(1), ranlib(1), and the Info entries for @file{binutils}.
616 @section Controlling @command{ar} with a Script
619 ar -M [ <@var{script} ]
622 @cindex MRI compatibility, @command{ar}
623 @cindex scripts, @command{ar}
624 If you use the single command-line option @samp{-M} with @command{ar}, you
625 can control its operation with a rudimentary command language. This
626 form of @command{ar} operates interactively if standard input is coming
627 directly from a terminal. During interactive use, @command{ar} prompts for
628 input (the prompt is @samp{AR >}), and continues executing even after
629 errors. If you redirect standard input to a script file, no prompts are
630 issued, and @command{ar} abandons execution (with a nonzero exit code)
633 The @command{ar} command language is @emph{not} designed to be equivalent
634 to the command-line options; in fact, it provides somewhat less control
635 over archives. The only purpose of the command language is to ease the
636 transition to @sc{gnu} @command{ar} for developers who already have scripts
637 written for the MRI ``librarian'' program.
639 The syntax for the @command{ar} command language is straightforward:
642 commands are recognized in upper or lower case; for example, @code{LIST}
643 is the same as @code{list}. In the following descriptions, commands are
644 shown in upper case for clarity.
647 a single command may appear on each line; it is the first word on the
651 empty lines are allowed, and have no effect.
654 comments are allowed; text after either of the characters @samp{*}
655 or @samp{;} is ignored.
658 Whenever you use a list of names as part of the argument to an @command{ar}
659 command, you can separate the individual names with either commas or
660 blanks. Commas are shown in the explanations below, for clarity.
663 @samp{+} is used as a line continuation character; if @samp{+} appears
664 at the end of a line, the text on the following line is considered part
665 of the current command.
668 Here are the commands you can use in @command{ar} scripts, or when using
669 @command{ar} interactively. Three of them have special significance:
671 @code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is
672 a temporary file required for most of the other commands.
674 @code{SAVE} commits the changes so far specified by the script. Prior
675 to @code{SAVE}, commands affect only the temporary copy of the current
679 @item ADDLIB @var{archive}
680 @itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module})
681 Add all the contents of @var{archive} (or, if specified, each named
682 @var{module} from @var{archive}) to the current archive.
684 Requires prior use of @code{OPEN} or @code{CREATE}.
686 @item ADDMOD @var{member}, @var{member}, @dots{} @var{member}
687 @c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}"
688 @c else like "ar q..."
689 Add each named @var{member} as a module in the current archive.
691 Requires prior use of @code{OPEN} or @code{CREATE}.
694 Discard the contents of the current archive, canceling the effect of
695 any operations since the last @code{SAVE}. May be executed (with no
696 effect) even if no current archive is specified.
698 @item CREATE @var{archive}
699 Creates an archive, and makes it the current archive (required for many
700 other commands). The new archive is created with a temporary name; it
701 is not actually saved as @var{archive} until you use @code{SAVE}.
702 You can overwrite existing archives; similarly, the contents of any
703 existing file named @var{archive} will not be destroyed until @code{SAVE}.
705 @item DELETE @var{module}, @var{module}, @dots{} @var{module}
706 Delete each listed @var{module} from the current archive; equivalent to
707 @samp{ar -d @var{archive} @var{module} @dots{} @var{module}}.
709 Requires prior use of @code{OPEN} or @code{CREATE}.
711 @item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module})
712 @itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile}
713 List each named @var{module} present in @var{archive}. The separate
714 command @code{VERBOSE} specifies the form of the output: when verbose
715 output is off, output is like that of @samp{ar -t @var{archive}
716 @var{module}@dots{}}. When verbose output is on, the listing is like
717 @samp{ar -tv @var{archive} @var{module}@dots{}}.
719 Output normally goes to the standard output stream; however, if you
720 specify @var{outputfile} as a final argument, @command{ar} directs the
724 Exit from @command{ar}, with a @code{0} exit code to indicate successful
725 completion. This command does not save the output file; if you have
726 changed the current archive since the last @code{SAVE} command, those
729 @item EXTRACT @var{module}, @var{module}, @dots{} @var{module}
730 Extract each named @var{module} from the current archive, writing them
731 into the current directory as separate files. Equivalent to @samp{ar -x
732 @var{archive} @var{module}@dots{}}.
734 Requires prior use of @code{OPEN} or @code{CREATE}.
737 @c FIXME Tokens but no commands???
744 Display full contents of the current archive, in ``verbose'' style
745 regardless of the state of @code{VERBOSE}. The effect is like @samp{ar
746 tv @var{archive}}. (This single command is a @sc{gnu} @command{ar}
747 enhancement, rather than present for MRI compatibility.)
749 Requires prior use of @code{OPEN} or @code{CREATE}.
751 @item OPEN @var{archive}
752 Opens an existing archive for use as the current archive (required for
753 many other commands). Any changes as the result of subsequent commands
754 will not actually affect @var{archive} until you next use @code{SAVE}.
756 @item REPLACE @var{module}, @var{module}, @dots{} @var{module}
757 In the current archive, replace each existing @var{module} (named in
758 the @code{REPLACE} arguments) from files in the current working directory.
759 To execute this command without errors, both the file, and the module in
760 the current archive, must exist.
762 Requires prior use of @code{OPEN} or @code{CREATE}.
765 Toggle an internal flag governing the output from @code{DIRECTORY}.
766 When the flag is on, @code{DIRECTORY} output matches output from
767 @samp{ar -tv }@dots{}.
770 Commit your changes to the current archive, and actually save it as a
771 file with the name specified in the last @code{CREATE} or @code{OPEN}
774 Requires prior use of @code{OPEN} or @code{CREATE}.
783 The @sc{gnu} linker @command{ld} is now described in a separate manual.
784 @xref{Top,, Overview,, Using LD: the @sc{gnu} linker}.
792 @c man title nm list symbols from object files
795 @c man begin SYNOPSIS nm
796 nm [@option{-A}|@option{-o}|@option{--print-file-name}]
797 [@option{-a}|@option{--debug-syms}]
798 [@option{-B}|@option{--format=bsd}]
799 [@option{-C}|@option{--demangle}[=@var{style}]]
800 [@option{-D}|@option{--dynamic}]
801 [@option{-f}@var{format}|@option{--format=}@var{format}]
802 [@option{-g}|@option{--extern-only}]
803 [@option{-h}|@option{--help}]
804 [@option{--ifunc-chars=@var{CHARS}}]
805 [@option{-j}|@option{--format=just-symbols}]
806 [@option{-l}|@option{--line-numbers}] [@option{--inlines}]
807 [@option{-n}|@option{-v}|@option{--numeric-sort}]
808 [@option{-P}|@option{--portability}]
809 [@option{-p}|@option{--no-sort}]
810 [@option{-r}|@option{--reverse-sort}]
811 [@option{-S}|@option{--print-size}]
812 [@option{-s}|@option{--print-armap}]
813 [@option{-t} @var{radix}|@option{--radix=}@var{radix}]
814 [@option{-u}|@option{--undefined-only}]
815 [@option{-V}|@option{--version}]
817 [@option{--defined-only}]
818 [@option{--no-demangle}]
819 [@option{--no-recurse-limit}|@option{--recurse-limit}]]
820 [@option{--plugin} @var{name}]
821 [@option{--size-sort}]
822 [@option{--special-syms}]
823 [@option{--synthetic}]
824 [@option{--target=}@var{bfdname}]
825 [@option{--with-symbol-versions}]
826 [@option{--without-symbol-versions}]
827 [@var{objfile}@dots{}]
831 @c man begin DESCRIPTION nm
832 @sc{gnu} @command{nm} lists the symbols from object files @var{objfile}@dots{}.
833 If no object files are listed as arguments, @command{nm} assumes the file
836 For each symbol, @command{nm} shows:
840 The symbol value, in the radix selected by options (see below), or
841 hexadecimal by default.
844 The symbol type. At least the following types are used; others are, as
845 well, depending on the object file format. If lowercase, the symbol is
846 usually local; if uppercase, the symbol is global (external). There
847 are however a few lowercase symbols that are shown for special global
848 symbols (@code{u}, @code{v} and @code{w}).
850 @c Some more detail on exactly what these symbol types are used for
854 The symbol's value is absolute, and will not be changed by further
859 The symbol is in the BSS data section. This section typically
860 contains zero-initialized or uninitialized data, although the exact
861 behavior is system dependent.
865 The symbol is common. Common symbols are uninitialized data. When
866 linking, multiple common symbols may appear with the same name. If the
867 symbol is defined anywhere, the common symbols are treated as undefined
870 For more details on common symbols, see the discussion of
871 --warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}.
873 The lower case @var{c} character is used when the symbol is in a
874 special section for small commons.
878 The symbol is in the initialized data section.
882 The symbol is in an initialized data section for small objects. Some
883 object file formats permit more efficient access to small data objects,
884 such as a global int variable as opposed to a large global array.
887 For PE format files this indicates that the symbol is in a section
888 specific to the implementation of DLLs.
890 For ELF format files this indicates that the symbol is an indirect
891 function. This is a GNU extension to the standard set of ELF symbol
892 types. It indicates a symbol which if referenced by a relocation does
893 not evaluate to its address, but instead must be invoked at runtime.
894 The runtime execution will then return the value to be used in the
897 Note - the actual symbols display for GNU indirect symbols is
898 controlled by the @option{--ifunc-chars} command line option. If this
899 option has been provided then the first character in the string will
900 be used for global indirect function symbols. If the string contains
901 a second character then that will be used for local indirect function
905 The symbol is an indirect reference to another symbol.
908 The symbol is a debugging symbol.
911 The symbol is in the read-only data section.
914 The symbol is in a stack unwind section.
918 The symbol is in a read only data section.
922 The symbol is in an uninitialized or zero-initialized data section
927 The symbol is in the text (code) section.
930 The symbol is undefined.
933 The symbol is a unique global symbol. This is a GNU extension to the
934 standard set of ELF symbol bindings. For such a symbol the dynamic linker
935 will make sure that in the entire process there is just one symbol with
936 this name and type in use.
940 The symbol is a weak object. When a weak defined symbol is linked with
941 a normal defined symbol, the normal defined symbol is used with no error.
942 When a weak undefined symbol is linked and the symbol is not defined,
943 the value of the weak symbol becomes zero with no error. On some
944 systems, uppercase indicates that a default value has been specified.
948 The symbol is a weak symbol that has not been specifically tagged as a
949 weak object symbol. When a weak defined symbol is linked with a normal
950 defined symbol, the normal defined symbol is used with no error.
951 When a weak undefined symbol is linked and the symbol is not defined,
952 the value of the symbol is determined in a system-specific manner without
953 error. On some systems, uppercase indicates that a default value has been
957 The symbol is a stabs symbol in an a.out object file. In this case, the
958 next values printed are the stabs other field, the stabs desc field, and
959 the stab type. Stabs symbols are used to hold debugging information.
962 The symbol type is unknown, or object file format specific.
966 The symbol name. If a symbol has version information associated with it,
967 then the version information is displayed as well. If the versioned
968 symbol is undefined or hidden from linker, the version string is displayed
969 as a suffix to the symbol name, preceded by an @@ character. For example
970 @samp{foo@@VER_1}. If the version is the default version to be used when
971 resolving unversioned references to the symbol, then it is displayed as a
972 suffix preceded by two @@ characters. For example @samp{foo@@@@VER_2}.
977 @c man begin OPTIONS nm
978 The long and short forms of options, shown here as alternatives, are
984 @itemx --print-file-name
985 @cindex input file name
987 @cindex source file name
988 Precede each symbol by the name of the input file (or archive member)
989 in which it was found, rather than identifying the input file once only,
990 before all of its symbols.
994 @cindex debugging symbols
995 Display all symbols, even debugger-only symbols; normally these are not
999 @cindex @command{nm} format
1000 @cindex @command{nm} compatibility
1001 The same as @option{--format=bsd} (for compatibility with the MIPS @command{nm}).
1004 @itemx --demangle[=@var{style}]
1005 @cindex demangling in nm
1006 Decode (@dfn{demangle}) low-level symbol names into user-level names.
1007 Besides removing any initial underscore prepended by the system, this
1008 makes C++ function names readable. Different compilers have different
1009 mangling styles. The optional demangling style argument can be used to
1010 choose an appropriate demangling style for your compiler. @xref{c++filt},
1011 for more information on demangling.
1014 Do not demangle low-level symbol names. This is the default.
1016 @item --recurse-limit
1017 @itemx --no-recurse-limit
1018 @itemx --recursion-limit
1019 @itemx --no-recursion-limit
1020 Enables or disables a limit on the amount of recursion performed
1021 whilst demangling strings. Since the name mangling formats allow for
1022 an infinite level of recursion it is possible to create strings whose
1023 decoding will exhaust the amount of stack space available on the host
1024 machine, triggering a memory fault. The limit tries to prevent this
1025 from happening by restricting recursion to 2048 levels of nesting.
1027 The default is for this limit to be enabled, but disabling it may be
1028 necessary in order to demangle truly complicated names. Note however
1029 that if the recursion limit is disabled then stack exhaustion is
1030 possible and any bug reports about such an event will be rejected.
1034 @cindex dynamic symbols
1035 Display the dynamic symbols rather than the normal symbols. This is
1036 only meaningful for dynamic objects, such as certain types of shared
1039 @item -f @var{format}
1040 @itemx --format=@var{format}
1041 @cindex @command{nm} format
1042 @cindex @command{nm} compatibility
1043 Use the output format @var{format}, which can be @code{bsd},
1044 @code{sysv}, @code{posix} or @code{just-symbols}. The default is @code{bsd}.
1045 Only the first character of @var{format} is significant; it can be
1046 either upper or lower case.
1049 @itemx --extern-only
1050 @cindex external symbols
1051 Display only external symbols.
1055 Show a summary of the options to @command{nm} and exit.
1057 @item --ifunc-chars=@var{CHARS}
1058 When display GNU indirect function symbols @command{nm} will default
1059 to using the @code{i} character for both local indirect functions and
1060 global indirect functions. The @option{--ifunc-chars} option allows
1061 the user to specify a string containing one or two characters. The
1062 first character will be used for global indirect function symbols and
1063 the second character, if present, will be used for local indirect
1067 The same as @option{--format=just-symbols}.
1070 @itemx --line-numbers
1071 @cindex symbol line numbers
1072 For each symbol, use debugging information to try to find a filename and
1073 line number. For a defined symbol, look for the line number of the
1074 address of the symbol. For an undefined symbol, look for the line
1075 number of a relocation entry which refers to the symbol. If line number
1076 information can be found, print it after the other symbol information.
1079 @cindex objdump inlines
1080 When option @option{-l} is active, if the address belongs to a
1081 function that was inlined, then this option causes the source
1082 information for all enclosing scopes back to the first non-inlined
1083 function to be printed as well. For example, if @code{main} inlines
1084 @code{callee1} which inlines @code{callee2}, and address is from
1085 @code{callee2}, the source information for @code{callee1} and @code{main}
1086 will also be printed.
1090 @itemx --numeric-sort
1091 Sort symbols numerically by their addresses, rather than alphabetically
1096 @cindex sorting symbols
1097 Do not bother to sort the symbols in any order; print them in the order
1101 @itemx --portability
1102 Use the POSIX.2 standard output format instead of the default format.
1103 Equivalent to @samp{-f posix}.
1106 @itemx --reverse-sort
1107 Reverse the order of the sort (whether numeric or alphabetic); let the
1112 Print both value and size of defined symbols for the @code{bsd} output style.
1113 This option has no effect for object formats that do not record symbol
1114 sizes, unless @samp{--size-sort} is also used in which case a
1115 calculated size is displayed.
1118 @itemx --print-armap
1119 @cindex symbol index, listing
1120 When listing symbols from archive members, include the index: a mapping
1121 (stored in the archive by @command{ar} or @command{ranlib}) of which modules
1122 contain definitions for which names.
1124 @item -t @var{radix}
1125 @itemx --radix=@var{radix}
1126 Use @var{radix} as the radix for printing the symbol values. It must be
1127 @samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal.
1130 @itemx --undefined-only
1131 @cindex external symbols
1132 @cindex undefined symbols
1133 Display only undefined symbols (those external to each object file).
1137 Show the version number of @command{nm} and exit.
1140 This option is ignored for compatibility with the AIX version of
1141 @command{nm}. It takes one parameter which must be the string
1142 @option{32_64}. The default mode of AIX @command{nm} corresponds
1143 to @option{-X 32}, which is not supported by @sc{gnu} @command{nm}.
1145 @item --defined-only
1146 @cindex external symbols
1147 @cindex undefined symbols
1148 Display only defined symbols for each object file.
1150 @item --plugin @var{name}
1152 Load the plugin called @var{name} to add support for extra target
1153 types. This option is only available if the toolchain has been built
1154 with plugin support enabled.
1156 If @option{--plugin} is not provided, but plugin support has been
1157 enabled then @command{nm} iterates over the files in
1158 @file{$@{libdir@}/bfd-plugins} in alphabetic order and the first
1159 plugin that claims the object in question is used.
1161 Please note that this plugin search directory is @emph{not} the one
1162 used by @command{ld}'s @option{-plugin} option. In order to make
1163 @command{nm} use the linker plugin it must be copied into the
1164 @file{$@{libdir@}/bfd-plugins} directory. For GCC based compilations
1165 the linker plugin is called @file{liblto_plugin.so.0.0.0}. For Clang
1166 based compilations it is called @file{LLVMgold.so}. The GCC plugin
1167 is always backwards compatible with earlier versions, so it is
1168 sufficient to just copy the newest one.
1171 Sort symbols by size. For ELF objects symbol sizes are read from the
1172 ELF, for other object types the symbol sizes are computed as the
1173 difference between the value of the symbol and the value of the symbol
1174 with the next higher value. If the @code{bsd} output format is used
1175 the size of the symbol is printed, rather than the value, and
1176 @samp{-S} must be used in order both size and value to be printed.
1178 @item --special-syms
1179 Display symbols which have a target-specific special meaning. These
1180 symbols are usually used by the target for some special processing and
1181 are not normally helpful when included in the normal symbol lists.
1182 For example for ARM targets this option would skip the mapping symbols
1183 used to mark transitions between ARM code, THUMB code and data.
1186 Include synthetic symbols in the output. These are special symbols
1187 created by the linker for various purposes. They are not shown by
1188 default since they are not part of the binary's original source code.
1190 @item --with-symbol-versions
1191 @item --without-symbol-versions
1192 Enables or disables the display of symbol version information. The
1193 version string is displayed as a suffix to the symbol name, preceded
1194 by an @@ character. For example @samp{foo@@VER_1}. If the version is
1195 the default version to be used when resolving unversioned references
1196 to the symbol then it is displayed as a suffix preceded by two @@
1197 characters. For example @samp{foo@@@@VER_2}. By default, symbol
1198 version information is displayed.
1200 @item --target=@var{bfdname}
1201 @cindex object code format
1202 Specify an object code format other than your system's default format.
1203 @xref{Target Selection}, for more information.
1210 @c man begin SEEALSO nm
1211 ar(1), objdump(1), ranlib(1), and the Info entries for @file{binutils}.
1218 @c man title objcopy copy and translate object files
1221 @c man begin SYNOPSIS objcopy
1222 objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}]
1223 [@option{-I} @var{bfdname}|@option{--input-target=}@var{bfdname}]
1224 [@option{-O} @var{bfdname}|@option{--output-target=}@var{bfdname}]
1225 [@option{-B} @var{bfdarch}|@option{--binary-architecture=}@var{bfdarch}]
1226 [@option{-S}|@option{--strip-all}]
1227 [@option{-g}|@option{--strip-debug}]
1228 [@option{--strip-unneeded}]
1229 [@option{-K} @var{symbolname}|@option{--keep-symbol=}@var{symbolname}]
1230 [@option{--keep-file-symbols}]
1231 [@option{--keep-section-symbols}]
1232 [@option{-N} @var{symbolname}|@option{--strip-symbol=}@var{symbolname}]
1233 [@option{--strip-unneeded-symbol=}@var{symbolname}]
1234 [@option{-G} @var{symbolname}|@option{--keep-global-symbol=}@var{symbolname}]
1235 [@option{--localize-hidden}]
1236 [@option{-L} @var{symbolname}|@option{--localize-symbol=}@var{symbolname}]
1237 [@option{--globalize-symbol=}@var{symbolname}]
1238 [@option{--globalize-symbols=}@var{filename}]
1239 [@option{-W} @var{symbolname}|@option{--weaken-symbol=}@var{symbolname}]
1240 [@option{-w}|@option{--wildcard}]
1241 [@option{-x}|@option{--discard-all}]
1242 [@option{-X}|@option{--discard-locals}]
1243 [@option{-b} @var{byte}|@option{--byte=}@var{byte}]
1244 [@option{-i} [@var{breadth}]|@option{--interleave}[=@var{breadth}]]
1245 [@option{--interleave-width=}@var{width}]
1246 [@option{-j} @var{sectionpattern}|@option{--only-section=}@var{sectionpattern}]
1247 [@option{-R} @var{sectionpattern}|@option{--remove-section=}@var{sectionpattern}]
1248 [@option{--keep-section=}@var{sectionpattern}]
1249 [@option{--remove-relocations=}@var{sectionpattern}]
1250 [@option{-p}|@option{--preserve-dates}]
1251 [@option{-D}|@option{--enable-deterministic-archives}]
1252 [@option{-U}|@option{--disable-deterministic-archives}]
1253 [@option{--debugging}]
1254 [@option{--gap-fill=}@var{val}]
1255 [@option{--pad-to=}@var{address}]
1256 [@option{--set-start=}@var{val}]
1257 [@option{--adjust-start=}@var{incr}]
1258 [@option{--change-addresses=}@var{incr}]
1259 [@option{--change-section-address} @var{sectionpattern}@{=,+,-@}@var{val}]
1260 [@option{--change-section-lma} @var{sectionpattern}@{=,+,-@}@var{val}]
1261 [@option{--change-section-vma} @var{sectionpattern}@{=,+,-@}@var{val}]
1262 [@option{--change-warnings}] [@option{--no-change-warnings}]
1263 [@option{--set-section-flags} @var{sectionpattern}=@var{flags}]
1264 [@option{--set-section-alignment} @var{sectionpattern}=@var{align}]
1265 [@option{--add-section} @var{sectionname}=@var{filename}]
1266 [@option{--dump-section} @var{sectionname}=@var{filename}]
1267 [@option{--update-section} @var{sectionname}=@var{filename}]
1268 [@option{--rename-section} @var{oldname}=@var{newname}[,@var{flags}]]
1269 [@option{--long-section-names} @{enable,disable,keep@}]
1270 [@option{--change-leading-char}] [@option{--remove-leading-char}]
1271 [@option{--reverse-bytes=}@var{num}]
1272 [@option{--srec-len=}@var{ival}] [@option{--srec-forceS3}]
1273 [@option{--redefine-sym} @var{old}=@var{new}]
1274 [@option{--redefine-syms=}@var{filename}]
1276 [@option{--keep-symbols=}@var{filename}]
1277 [@option{--strip-symbols=}@var{filename}]
1278 [@option{--strip-unneeded-symbols=}@var{filename}]
1279 [@option{--keep-global-symbols=}@var{filename}]
1280 [@option{--localize-symbols=}@var{filename}]
1281 [@option{--weaken-symbols=}@var{filename}]
1282 [@option{--add-symbol} @var{name}=[@var{section}:]@var{value}[,@var{flags}]]
1283 [@option{--alt-machine-code=}@var{index}]
1284 [@option{--prefix-symbols=}@var{string}]
1285 [@option{--prefix-sections=}@var{string}]
1286 [@option{--prefix-alloc-sections=}@var{string}]
1287 [@option{--add-gnu-debuglink=}@var{path-to-file}]
1288 [@option{--only-keep-debug}]
1289 [@option{--strip-dwo}]
1290 [@option{--extract-dwo}]
1291 [@option{--extract-symbol}]
1292 [@option{--writable-text}]
1293 [@option{--readonly-text}]
1296 [@option{--file-alignment=}@var{num}]
1297 [@option{--heap=}@var{size}]
1298 [@option{--image-base=}@var{address}]
1299 [@option{--section-alignment=}@var{num}]
1300 [@option{--stack=}@var{size}]
1301 [@option{--subsystem=}@var{which}:@var{major}.@var{minor}]
1302 [@option{--compress-debug-sections}]
1303 [@option{--decompress-debug-sections}]
1304 [@option{--elf-stt-common=@var{val}}]
1305 [@option{--merge-notes}]
1306 [@option{--no-merge-notes}]
1307 [@option{--verilog-data-width=@var{val}}]
1308 [@option{-v}|@option{--verbose}]
1309 [@option{-V}|@option{--version}]
1310 [@option{--help}] [@option{--info}]
1311 @var{infile} [@var{outfile}]
1315 @c man begin DESCRIPTION objcopy
1316 The @sc{gnu} @command{objcopy} utility copies the contents of an object
1317 file to another. @command{objcopy} uses the @sc{gnu} @sc{bfd} Library to
1318 read and write the object files. It can write the destination object
1319 file in a format different from that of the source object file. The
1320 exact behavior of @command{objcopy} is controlled by command-line options.
1321 Note that @command{objcopy} should be able to copy a fully linked file
1322 between any two formats. However, copying a relocatable object file
1323 between any two formats may not work as expected.
1325 @command{objcopy} creates temporary files to do its translations and
1326 deletes them afterward. @command{objcopy} uses @sc{bfd} to do all its
1327 translation work; it has access to all the formats described in @sc{bfd}
1328 and thus is able to recognize most formats without being told
1329 explicitly. @xref{BFD,,BFD,ld.info,Using LD}.
1331 @command{objcopy} can be used to generate S-records by using an output
1332 target of @samp{srec} (e.g., use @samp{-O srec}).
1334 @command{objcopy} can be used to generate a raw binary file by using an
1335 output target of @samp{binary} (e.g., use @option{-O binary}). When
1336 @command{objcopy} generates a raw binary file, it will essentially produce
1337 a memory dump of the contents of the input object file. All symbols and
1338 relocation information will be discarded. The memory dump will start at
1339 the load address of the lowest section copied into the output file.
1341 When generating an S-record or a raw binary file, it may be helpful to
1342 use @option{-S} to remove sections containing debugging information. In
1343 some cases @option{-R} will be useful to remove sections which contain
1344 information that is not needed by the binary file.
1346 Note---@command{objcopy} is not able to change the endianness of its input
1347 files. If the input format has an endianness (some formats do not),
1348 @command{objcopy} can only copy the inputs into file formats that have the
1349 same endianness or which have no endianness (e.g., @samp{srec}).
1350 (However, see the @option{--reverse-bytes} option.)
1354 @c man begin OPTIONS objcopy
1358 @itemx @var{outfile}
1359 The input and output files, respectively.
1360 If you do not specify @var{outfile}, @command{objcopy} creates a
1361 temporary file and destructively renames the result with
1362 the name of @var{infile}.
1364 @item -I @var{bfdname}
1365 @itemx --input-target=@var{bfdname}
1366 Consider the source file's object format to be @var{bfdname}, rather than
1367 attempting to deduce it. @xref{Target Selection}, for more information.
1369 @item -O @var{bfdname}
1370 @itemx --output-target=@var{bfdname}
1371 Write the output file using the object format @var{bfdname}.
1372 @xref{Target Selection}, for more information.
1374 @item -F @var{bfdname}
1375 @itemx --target=@var{bfdname}
1376 Use @var{bfdname} as the object format for both the input and the output
1377 file; i.e., simply transfer data from source to destination with no
1378 translation. @xref{Target Selection}, for more information.
1380 @item -B @var{bfdarch}
1381 @itemx --binary-architecture=@var{bfdarch}
1382 Useful when transforming a architecture-less input file into an object file.
1383 In this case the output architecture can be set to @var{bfdarch}. This
1384 option will be ignored if the input file has a known @var{bfdarch}. You
1385 can access this binary data inside a program by referencing the special
1386 symbols that are created by the conversion process. These symbols are
1387 called _binary_@var{objfile}_start, _binary_@var{objfile}_end and
1388 _binary_@var{objfile}_size. e.g. you can transform a picture file into
1389 an object file and then access it in your code using these symbols.
1391 @item -j @var{sectionpattern}
1392 @itemx --only-section=@var{sectionpattern}
1393 Copy only the indicated sections from the input file to the output file.
1394 This option may be given more than once. Note that using this option
1395 inappropriately may make the output file unusable. Wildcard
1396 characters are accepted in @var{sectionpattern}.
1398 If the first character of @var{sectionpattern} is the exclamation
1399 point (!) then matching sections will not be copied, even if earlier
1400 use of @option{--only-section} on the same command line would
1401 otherwise copy it. For example:
1404 --only-section=.text.* --only-section=!.text.foo
1407 will copy all sectinos matching '.text.*' but not the section
1410 @item -R @var{sectionpattern}
1411 @itemx --remove-section=@var{sectionpattern}
1412 Remove any section matching @var{sectionpattern} from the output file.
1413 This option may be given more than once. Note that using this option
1414 inappropriately may make the output file unusable. Wildcard
1415 characters are accepted in @var{sectionpattern}. Using both the
1416 @option{-j} and @option{-R} options together results in undefined
1419 If the first character of @var{sectionpattern} is the exclamation
1420 point (!) then matching sections will not be removed even if an
1421 earlier use of @option{--remove-section} on the same command line
1422 would otherwise remove it. For example:
1425 --remove-section=.text.* --remove-section=!.text.foo
1428 will remove all sections matching the pattern '.text.*', but will not
1429 remove the section '.text.foo'.
1431 @item --keep-section=@var{sectionpattern}
1432 When removing sections from the output file, keep sections that match
1433 @var{sectionpattern}.
1435 @item --remove-relocations=@var{sectionpattern}
1436 Remove non-dynamic relocations from the output file for any section
1437 matching @var{sectionpattern}. This option may be given more than
1438 once. Note that using this option inappropriately may make the output
1439 file unusable, and attempting to remove a dynamic relocation section
1440 such as @samp{.rela.plt} from an executable or shared library with
1441 @option{--remove-relocations=.plt} will not work. Wildcard characters
1442 are accepted in @var{sectionpattern}.
1446 --remove-relocations=.text.*
1449 will remove the relocations for all sections matching the pattern
1452 If the first character of @var{sectionpattern} is the exclamation
1453 point (!) then matching sections will not have their relocation
1454 removed even if an earlier use of @option{--remove-relocations} on the
1455 same command line would otherwise cause the relocations to be removed.
1459 --remove-relocations=.text.* --remove-relocations=!.text.foo
1462 will remove all relocations for sections matching the pattern
1463 '.text.*', but will not remove relocations for the section
1468 Do not copy relocation and symbol information from the source file.
1469 Also deletes debug sections.
1472 @itemx --strip-debug
1473 Do not copy debugging symbols or sections from the source file.
1475 @item --strip-unneeded
1476 Remove all symbols that are not needed for relocation processing in
1477 addition to debugging symbols and sections stripped by
1478 @option{--strip-debug}.
1480 @item -K @var{symbolname}
1481 @itemx --keep-symbol=@var{symbolname}
1482 When stripping symbols, keep symbol @var{symbolname} even if it would
1483 normally be stripped. This option may be given more than once.
1485 @item -N @var{symbolname}
1486 @itemx --strip-symbol=@var{symbolname}
1487 Do not copy symbol @var{symbolname} from the source file. This option
1488 may be given more than once.
1490 @item --strip-unneeded-symbol=@var{symbolname}
1491 Do not copy symbol @var{symbolname} from the source file unless it is needed
1492 by a relocation. This option may be given more than once.
1494 @item -G @var{symbolname}
1495 @itemx --keep-global-symbol=@var{symbolname}
1496 Keep only symbol @var{symbolname} global. Make all other symbols local
1497 to the file, so that they are not visible externally. This option may
1498 be given more than once. Note: this option cannot be used in
1499 conjunction with the @option{--globalize-symbol} or
1500 @option{--globalize-symbols} options.
1502 @item --localize-hidden
1503 In an ELF object, mark all symbols that have hidden or internal visibility
1504 as local. This option applies on top of symbol-specific localization options
1505 such as @option{-L}.
1507 @item -L @var{symbolname}
1508 @itemx --localize-symbol=@var{symbolname}
1509 Convert a global or weak symbol called @var{symbolname} into a local
1510 symbol, so that it is not visible externally. This option may be
1511 given more than once. Note - unique symbols are not converted.
1513 @item -W @var{symbolname}
1514 @itemx --weaken-symbol=@var{symbolname}
1515 Make symbol @var{symbolname} weak. This option may be given more than once.
1517 @item --globalize-symbol=@var{symbolname}
1518 Give symbol @var{symbolname} global scoping so that it is visible
1519 outside of the file in which it is defined. This option may be given
1520 more than once. Note: this option cannot be used in conjunction with
1521 the @option{-G} or @option{--keep-global-symbol} options.
1525 Permit regular expressions in @var{symbolname}s used in other command
1526 line options. The question mark (?), asterisk (*), backslash (\) and
1527 square brackets ([]) operators can be used anywhere in the symbol
1528 name. If the first character of the symbol name is the exclamation
1529 point (!) then the sense of the switch is reversed for that symbol.
1536 would cause objcopy to weaken all symbols that start with ``fo''
1537 except for the symbol ``foo''.
1540 @itemx --discard-all
1541 Do not copy non-global symbols from the source file.
1542 @c FIXME any reason to prefer "non-global" to "local" here?
1545 @itemx --discard-locals
1546 Do not copy compiler-generated local symbols.
1547 (These usually start with @samp{L} or @samp{.}.)
1550 @itemx --byte=@var{byte}
1551 If interleaving has been enabled via the @option{--interleave} option
1552 then start the range of bytes to keep at the @var{byte}th byte.
1553 @var{byte} can be in the range from 0 to @var{breadth}-1, where
1554 @var{breadth} is the value given by the @option{--interleave} option.
1556 @item -i [@var{breadth}]
1557 @itemx --interleave[=@var{breadth}]
1558 Only copy a range out of every @var{breadth} bytes. (Header data is
1559 not affected). Select which byte in the range begins the copy with
1560 the @option{--byte} option. Select the width of the range with the
1561 @option{--interleave-width} option.
1563 This option is useful for creating files to program @sc{rom}. It is
1564 typically used with an @code{srec} output target. Note that
1565 @command{objcopy} will complain if you do not specify the
1566 @option{--byte} option as well.
1568 The default interleave breadth is 4, so with @option{--byte} set to 0,
1569 @command{objcopy} would copy the first byte out of every four bytes
1570 from the input to the output.
1572 @item --interleave-width=@var{width}
1573 When used with the @option{--interleave} option, copy @var{width}
1574 bytes at a time. The start of the range of bytes to be copied is set
1575 by the @option{--byte} option, and the extent of the range is set with
1576 the @option{--interleave} option.
1578 The default value for this option is 1. The value of @var{width} plus
1579 the @var{byte} value set by the @option{--byte} option must not exceed
1580 the interleave breadth set by the @option{--interleave} option.
1582 This option can be used to create images for two 16-bit flashes interleaved
1583 in a 32-bit bus by passing @option{-b 0 -i 4 --interleave-width=2}
1584 and @option{-b 2 -i 4 --interleave-width=2} to two @command{objcopy}
1585 commands. If the input was '12345678' then the outputs would be
1586 '1256' and '3478' respectively.
1589 @itemx --preserve-dates
1590 Set the access and modification dates of the output file to be the same
1591 as those of the input file.
1594 @itemx --enable-deterministic-archives
1595 @cindex deterministic archives
1596 @kindex --enable-deterministic-archives
1597 Operate in @emph{deterministic} mode. When copying archive members
1598 and writing the archive index, use zero for UIDs, GIDs, timestamps,
1599 and use consistent file modes for all files.
1601 If @file{binutils} was configured with
1602 @option{--enable-deterministic-archives}, then this mode is on by default.
1603 It can be disabled with the @samp{-U} option, below.
1606 @itemx --disable-deterministic-archives
1607 @cindex deterministic archives
1608 @kindex --enable-deterministic-archives
1609 Do @emph{not} operate in @emph{deterministic} mode. This is the
1610 inverse of the @option{-D} option, above: when copying archive members
1611 and writing the archive index, use their actual UID, GID, timestamp,
1612 and file mode values.
1614 This is the default unless @file{binutils} was configured with
1615 @option{--enable-deterministic-archives}.
1618 Convert debugging information, if possible. This is not the default
1619 because only certain debugging formats are supported, and the
1620 conversion process can be time consuming.
1622 @item --gap-fill @var{val}
1623 Fill gaps between sections with @var{val}. This operation applies to
1624 the @emph{load address} (LMA) of the sections. It is done by increasing
1625 the size of the section with the lower address, and filling in the extra
1626 space created with @var{val}.
1628 @item --pad-to @var{address}
1629 Pad the output file up to the load address @var{address}. This is
1630 done by increasing the size of the last section. The extra space is
1631 filled in with the value specified by @option{--gap-fill} (default zero).
1633 @item --set-start @var{val}
1634 Set the start address (also known as the entry address) of the new
1635 file to @var{val}. Not all object file formats support setting the
1638 @item --change-start @var{incr}
1639 @itemx --adjust-start @var{incr}
1640 @cindex changing start address
1641 Change the start address (also known as the entry address) by adding
1642 @var{incr}. Not all object file formats support setting the start
1645 @item --change-addresses @var{incr}
1646 @itemx --adjust-vma @var{incr}
1647 @cindex changing object addresses
1648 Change the VMA and LMA addresses of all sections, as well as the start
1649 address, by adding @var{incr}. Some object file formats do not permit
1650 section addresses to be changed arbitrarily. Note that this does not
1651 relocate the sections; if the program expects sections to be loaded at a
1652 certain address, and this option is used to change the sections such
1653 that they are loaded at a different address, the program may fail.
1655 @item --change-section-address @var{sectionpattern}@{=,+,-@}@var{val}
1656 @itemx --adjust-section-vma @var{sectionpattern}@{=,+,-@}@var{val}
1657 @cindex changing section address
1658 Set or change both the VMA address and the LMA address of any section
1659 matching @var{sectionpattern}. If @samp{=} is used, the section
1660 address is set to @var{val}. Otherwise, @var{val} is added to or
1661 subtracted from the section address. See the comments under
1662 @option{--change-addresses}, above. If @var{sectionpattern} does not
1663 match any sections in the input file, a warning will be issued, unless
1664 @option{--no-change-warnings} is used.
1666 @item --change-section-lma @var{sectionpattern}@{=,+,-@}@var{val}
1667 @cindex changing section LMA
1668 Set or change the LMA address of any sections matching
1669 @var{sectionpattern}. The LMA address is the address where the
1670 section will be loaded into memory at program load time. Normally
1671 this is the same as the VMA address, which is the address of the
1672 section at program run time, but on some systems, especially those
1673 where a program is held in ROM, the two can be different. If @samp{=}
1674 is used, the section address is set to @var{val}. Otherwise,
1675 @var{val} is added to or subtracted from the section address. See the
1676 comments under @option{--change-addresses}, above. If
1677 @var{sectionpattern} does not match any sections in the input file, a
1678 warning will be issued, unless @option{--no-change-warnings} is used.
1680 @item --change-section-vma @var{sectionpattern}@{=,+,-@}@var{val}
1681 @cindex changing section VMA
1682 Set or change the VMA address of any section matching
1683 @var{sectionpattern}. The VMA address is the address where the
1684 section will be located once the program has started executing.
1685 Normally this is the same as the LMA address, which is the address
1686 where the section will be loaded into memory, but on some systems,
1687 especially those where a program is held in ROM, the two can be
1688 different. If @samp{=} is used, the section address is set to
1689 @var{val}. Otherwise, @var{val} is added to or subtracted from the
1690 section address. See the comments under @option{--change-addresses},
1691 above. If @var{sectionpattern} does not match any sections in the
1692 input file, a warning will be issued, unless
1693 @option{--no-change-warnings} is used.
1695 @item --change-warnings
1696 @itemx --adjust-warnings
1697 If @option{--change-section-address} or @option{--change-section-lma} or
1698 @option{--change-section-vma} is used, and the section pattern does not
1699 match any sections, issue a warning. This is the default.
1701 @item --no-change-warnings
1702 @itemx --no-adjust-warnings
1703 Do not issue a warning if @option{--change-section-address} or
1704 @option{--adjust-section-lma} or @option{--adjust-section-vma} is used, even
1705 if the section pattern does not match any sections.
1707 @item --set-section-flags @var{sectionpattern}=@var{flags}
1708 Set the flags for any sections matching @var{sectionpattern}. The
1709 @var{flags} argument is a comma separated string of flag names. The
1710 recognized names are @samp{alloc}, @samp{contents}, @samp{load},
1711 @samp{noload}, @samp{readonly}, @samp{code}, @samp{data}, @samp{rom},
1712 @samp{exclude}, @samp{share}, and @samp{debug}. You can set the
1713 @samp{contents} flag for a section which does not have contents, but it
1714 is not meaningful to clear the @samp{contents} flag of a section which
1715 does have contents--just remove the section instead. Not all flags are
1716 meaningful for all object file formats. In particular the
1717 @samp{share} flag is only meaningful for COFF format files and not for
1720 @item --set-section-alignment @var{sectionpattern}=@var{align}
1721 Set the alignment for any sections matching @var{sectionpattern}.
1722 @var{align} specifies the alignment in bytes and must be a power of
1723 two, i.e. 1, 2, 4, 8@dots{}.
1725 @item --add-section @var{sectionname}=@var{filename}
1726 Add a new section named @var{sectionname} while copying the file. The
1727 contents of the new section are taken from the file @var{filename}. The
1728 size of the section will be the size of the file. This option only
1729 works on file formats which can support sections with arbitrary names.
1730 Note - it may be necessary to use the @option{--set-section-flags}
1731 option to set the attributes of the newly created section.
1733 @item --dump-section @var{sectionname}=@var{filename}
1734 Place the contents of section named @var{sectionname} into the file
1735 @var{filename}, overwriting any contents that may have been there
1736 previously. This option is the inverse of @option{--add-section}.
1737 This option is similar to the @option{--only-section} option except
1738 that it does not create a formatted file, it just dumps the contents
1739 as raw binary data, without applying any relocations. The option can
1740 be specified more than once.
1742 @item --update-section @var{sectionname}=@var{filename}
1743 Replace the existing contents of a section named @var{sectionname}
1744 with the contents of file @var{filename}. The size of the section
1745 will be adjusted to the size of the file. The section flags for
1746 @var{sectionname} will be unchanged. For ELF format files the section
1747 to segment mapping will also remain unchanged, something which is not
1748 possible using @option{--remove-section} followed by
1749 @option{--add-section}. The option can be specified more than once.
1751 Note - it is possible to use @option{--rename-section} and
1752 @option{--update-section} to both update and rename a section from one
1753 command line. In this case, pass the original section name to
1754 @option{--update-section}, and the original and new section names to
1755 @option{--rename-section}.
1757 @item --add-symbol @var{name}=[@var{section}:]@var{value}[,@var{flags}]
1758 Add a new symbol named @var{name} while copying the file. This option may be
1759 specified multiple times. If the @var{section} is given, the symbol will be
1760 associated with and relative to that section, otherwise it will be an ABS
1761 symbol. Specifying an undefined section will result in a fatal error. There
1762 is no check for the value, it will be taken as specified. Symbol flags can
1763 be specified and not all flags will be meaningful for all object file
1764 formats. By default, the symbol will be global. The special flag
1765 'before=@var{othersym}' will insert the new symbol in front of the specified
1766 @var{othersym}, otherwise the symbol(s) will be added at the end of the
1767 symbol table in the order they appear.
1769 @item --rename-section @var{oldname}=@var{newname}[,@var{flags}]
1770 Rename a section from @var{oldname} to @var{newname}, optionally
1771 changing the section's flags to @var{flags} in the process. This has
1772 the advantage over using a linker script to perform the rename in that
1773 the output stays as an object file and does not become a linked
1774 executable. This option accepts the same set of flags as the
1775 @option{--sect-section-flags} option.
1777 This option is particularly helpful when the input format is binary,
1778 since this will always create a section called .data. If for example,
1779 you wanted instead to create a section called .rodata containing binary
1780 data you could use the following command line to achieve it:
1783 objcopy -I binary -O <output_format> -B <architecture> \
1784 --rename-section .data=.rodata,alloc,load,readonly,data,contents \
1785 <input_binary_file> <output_object_file>
1788 @item --long-section-names @{enable,disable,keep@}
1789 Controls the handling of long section names when processing @code{COFF}
1790 and @code{PE-COFF} object formats. The default behaviour, @samp{keep},
1791 is to preserve long section names if any are present in the input file.
1792 The @samp{enable} and @samp{disable} options forcibly enable or disable
1793 the use of long section names in the output object; when @samp{disable}
1794 is in effect, any long section names in the input object will be truncated.
1795 The @samp{enable} option will only emit long section names if any are
1796 present in the inputs; this is mostly the same as @samp{keep}, but it
1797 is left undefined whether the @samp{enable} option might force the
1798 creation of an empty string table in the output file.
1800 @item --change-leading-char
1801 Some object file formats use special characters at the start of
1802 symbols. The most common such character is underscore, which compilers
1803 often add before every symbol. This option tells @command{objcopy} to
1804 change the leading character of every symbol when it converts between
1805 object file formats. If the object file formats use the same leading
1806 character, this option has no effect. Otherwise, it will add a
1807 character, or remove a character, or change a character, as
1810 @item --remove-leading-char
1811 If the first character of a global symbol is a special symbol leading
1812 character used by the object file format, remove the character. The
1813 most common symbol leading character is underscore. This option will
1814 remove a leading underscore from all global symbols. This can be useful
1815 if you want to link together objects of different file formats with
1816 different conventions for symbol names. This is different from
1817 @option{--change-leading-char} because it always changes the symbol name
1818 when appropriate, regardless of the object file format of the output
1821 @item --reverse-bytes=@var{num}
1822 Reverse the bytes in a section with output contents. A section length must
1823 be evenly divisible by the value given in order for the swap to be able to
1824 take place. Reversing takes place before the interleaving is performed.
1826 This option is used typically in generating ROM images for problematic
1827 target systems. For example, on some target boards, the 32-bit words
1828 fetched from 8-bit ROMs are re-assembled in little-endian byte order
1829 regardless of the CPU byte order. Depending on the programming model, the
1830 endianness of the ROM may need to be modified.
1832 Consider a simple file with a section containing the following eight
1833 bytes: @code{12345678}.
1835 Using @samp{--reverse-bytes=2} for the above example, the bytes in the
1836 output file would be ordered @code{21436587}.
1838 Using @samp{--reverse-bytes=4} for the above example, the bytes in the
1839 output file would be ordered @code{43218765}.
1841 By using @samp{--reverse-bytes=2} for the above example, followed by
1842 @samp{--reverse-bytes=4} on the output file, the bytes in the second
1843 output file would be ordered @code{34127856}.
1845 @item --srec-len=@var{ival}
1846 Meaningful only for srec output. Set the maximum length of the Srecords
1847 being produced to @var{ival}. This length covers both address, data and
1850 @item --srec-forceS3
1851 Meaningful only for srec output. Avoid generation of S1/S2 records,
1852 creating S3-only record format.
1854 @item --redefine-sym @var{old}=@var{new}
1855 Change the name of a symbol @var{old}, to @var{new}. This can be useful
1856 when one is trying link two things together for which you have no
1857 source, and there are name collisions.
1859 @item --redefine-syms=@var{filename}
1860 Apply @option{--redefine-sym} to each symbol pair "@var{old} @var{new}"
1861 listed in the file @var{filename}. @var{filename} is simply a flat file,
1862 with one symbol pair per line. Line comments may be introduced by the hash
1863 character. This option may be given more than once.
1866 Change all global symbols in the file to be weak. This can be useful
1867 when building an object which will be linked against other objects using
1868 the @option{-R} option to the linker. This option is only effective when
1869 using an object file format which supports weak symbols.
1871 @item --keep-symbols=@var{filename}
1872 Apply @option{--keep-symbol} option to each symbol listed in the file
1873 @var{filename}. @var{filename} is simply a flat file, with one symbol
1874 name per line. Line comments may be introduced by the hash character.
1875 This option may be given more than once.
1877 @item --strip-symbols=@var{filename}
1878 Apply @option{--strip-symbol} option to each symbol listed in the file
1879 @var{filename}. @var{filename} is simply a flat file, with one symbol
1880 name per line. Line comments may be introduced by the hash character.
1881 This option may be given more than once.
1883 @item --strip-unneeded-symbols=@var{filename}
1884 Apply @option{--strip-unneeded-symbol} option to each symbol listed in
1885 the file @var{filename}. @var{filename} is simply a flat file, with one
1886 symbol name per line. Line comments may be introduced by the hash
1887 character. This option may be given more than once.
1889 @item --keep-global-symbols=@var{filename}
1890 Apply @option{--keep-global-symbol} option to each symbol listed in the
1891 file @var{filename}. @var{filename} is simply a flat file, with one
1892 symbol name per line. Line comments may be introduced by the hash
1893 character. This option may be given more than once.
1895 @item --localize-symbols=@var{filename}
1896 Apply @option{--localize-symbol} option to each symbol listed in the file
1897 @var{filename}. @var{filename} is simply a flat file, with one symbol
1898 name per line. Line comments may be introduced by the hash character.
1899 This option may be given more than once.
1901 @item --globalize-symbols=@var{filename}
1902 Apply @option{--globalize-symbol} option to each symbol listed in the file
1903 @var{filename}. @var{filename} is simply a flat file, with one symbol
1904 name per line. Line comments may be introduced by the hash character.
1905 This option may be given more than once. Note: this option cannot be
1906 used in conjunction with the @option{-G} or @option{--keep-global-symbol}
1909 @item --weaken-symbols=@var{filename}
1910 Apply @option{--weaken-symbol} option to each symbol listed in the file
1911 @var{filename}. @var{filename} is simply a flat file, with one symbol
1912 name per line. Line comments may be introduced by the hash character.
1913 This option may be given more than once.
1915 @item --alt-machine-code=@var{index}
1916 If the output architecture has alternate machine codes, use the
1917 @var{index}th code instead of the default one. This is useful in case
1918 a machine is assigned an official code and the tool-chain adopts the
1919 new code, but other applications still depend on the original code
1920 being used. For ELF based architectures if the @var{index}
1921 alternative does not exist then the value is treated as an absolute
1922 number to be stored in the e_machine field of the ELF header.
1924 @item --writable-text
1925 Mark the output text as writable. This option isn't meaningful for all
1926 object file formats.
1928 @item --readonly-text
1929 Make the output text write protected. This option isn't meaningful for all
1930 object file formats.
1933 Mark the output file as demand paged. This option isn't meaningful for all
1934 object file formats.
1937 Mark the output file as impure. This option isn't meaningful for all
1938 object file formats.
1940 @item --prefix-symbols=@var{string}
1941 Prefix all symbols in the output file with @var{string}.
1943 @item --prefix-sections=@var{string}
1944 Prefix all section names in the output file with @var{string}.
1946 @item --prefix-alloc-sections=@var{string}
1947 Prefix all the names of all allocated sections in the output file with
1950 @item --add-gnu-debuglink=@var{path-to-file}
1951 Creates a .gnu_debuglink section which contains a reference to
1952 @var{path-to-file} and adds it to the output file. Note: the file at
1953 @var{path-to-file} must exist. Part of the process of adding the
1954 .gnu_debuglink section involves embedding a checksum of the contents
1955 of the debug info file into the section.
1957 If the debug info file is built in one location but it is going to be
1958 installed at a later time into a different location then do not use
1959 the path to the installed location. The @option{--add-gnu-debuglink}
1960 option will fail because the installed file does not exist yet.
1961 Instead put the debug info file in the current directory and use the
1962 @option{--add-gnu-debuglink} option without any directory components,
1966 objcopy --add-gnu-debuglink=foo.debug
1969 At debug time the debugger will attempt to look for the separate debug
1970 info file in a set of known locations. The exact set of these
1971 locations varies depending upon the distribution being used, but it
1976 @item * The same directory as the executable.
1978 @item * A sub-directory of the directory containing the executable
1981 @item * A global debug directory such as /usr/lib/debug.
1984 As long as the debug info file has been installed into one of these
1985 locations before the debugger is run everything should work
1988 @item --keep-section-symbils
1989 When stripping a file, perhaps with @option{--strip-debug} or
1990 @option{--strip-unneeded}, retain any symbols specifying section names,
1991 which would otherwise get stripped.
1993 @item --keep-file-symbols
1994 When stripping a file, perhaps with @option{--strip-debug} or
1995 @option{--strip-unneeded}, retain any symbols specifying source file names,
1996 which would otherwise get stripped.
1998 @item --only-keep-debug
1999 Strip a file, removing contents of any sections that would not be
2000 stripped by @option{--strip-debug} and leaving the debugging sections
2001 intact. In ELF files, this preserves all note sections in the output.
2003 Note - the section headers of the stripped sections are preserved,
2004 including their sizes, but the contents of the section are discarded.
2005 The section headers are preserved so that other tools can match up the
2006 debuginfo file with the real executable, even if that executable has
2007 been relocated to a different address space.
2009 The intention is that this option will be used in conjunction with
2010 @option{--add-gnu-debuglink} to create a two part executable. One a
2011 stripped binary which will occupy less space in RAM and in a
2012 distribution and the second a debugging information file which is only
2013 needed if debugging abilities are required. The suggested procedure
2014 to create these files is as follows:
2017 @item Link the executable as normal. Assuming that it is called
2019 @item Run @code{objcopy --only-keep-debug foo foo.dbg} to
2020 create a file containing the debugging info.
2021 @item Run @code{objcopy --strip-debug foo} to create a
2022 stripped executable.
2023 @item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo}
2024 to add a link to the debugging info into the stripped executable.
2027 Note---the choice of @code{.dbg} as an extension for the debug info
2028 file is arbitrary. Also the @code{--only-keep-debug} step is
2029 optional. You could instead do this:
2032 @item Link the executable as normal.
2033 @item Copy @code{foo} to @code{foo.full}
2034 @item Run @code{objcopy --strip-debug foo}
2035 @item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
2038 i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the
2039 full executable. It does not have to be a file created by the
2040 @option{--only-keep-debug} switch.
2042 Note---this switch is only intended for use on fully linked files. It
2043 does not make sense to use it on object files where the debugging
2044 information may be incomplete. Besides the gnu_debuglink feature
2045 currently only supports the presence of one filename containing
2046 debugging information, not multiple filenames on a one-per-object-file
2050 Remove the contents of all DWARF .dwo sections, leaving the
2051 remaining debugging sections and all symbols intact.
2052 This option is intended for use by the compiler as part of
2053 the @option{-gsplit-dwarf} option, which splits debug information
2054 between the .o file and a separate .dwo file. The compiler
2055 generates all debug information in the same file, then uses
2056 the @option{--extract-dwo} option to copy the .dwo sections to
2057 the .dwo file, then the @option{--strip-dwo} option to remove
2058 those sections from the original .o file.
2061 Extract the contents of all DWARF .dwo sections. See the
2062 @option{--strip-dwo} option for more information.
2064 @item --file-alignment @var{num}
2065 Specify the file alignment. Sections in the file will always begin at
2066 file offsets which are multiples of this number. This defaults to
2068 [This option is specific to PE targets.]
2070 @item --heap @var{reserve}
2071 @itemx --heap @var{reserve},@var{commit}
2072 Specify the number of bytes of memory to reserve (and optionally commit)
2073 to be used as heap for this program.
2074 [This option is specific to PE targets.]
2076 @item --image-base @var{value}
2077 Use @var{value} as the base address of your program or dll. This is
2078 the lowest memory location that will be used when your program or dll
2079 is loaded. To reduce the need to relocate and improve performance of
2080 your dlls, each should have a unique base address and not overlap any
2081 other dlls. The default is 0x400000 for executables, and 0x10000000
2083 [This option is specific to PE targets.]
2085 @item --section-alignment @var{num}
2086 Sets the section alignment field in the PE header. Sections in memory
2087 will always begin at addresses which are a multiple of this number.
2089 [This option is specific to PE targets.]
2091 @item --stack @var{reserve}
2092 @itemx --stack @var{reserve},@var{commit}
2093 Specify the number of bytes of memory to reserve (and optionally commit)
2094 to be used as stack for this program.
2095 [This option is specific to PE targets.]
2097 @item --subsystem @var{which}
2098 @itemx --subsystem @var{which}:@var{major}
2099 @itemx --subsystem @var{which}:@var{major}.@var{minor}
2100 Specifies the subsystem under which your program will execute. The
2101 legal values for @var{which} are @code{native}, @code{windows},
2102 @code{console}, @code{posix}, @code{efi-app}, @code{efi-bsd},
2103 @code{efi-rtd}, @code{sal-rtd}, and @code{xbox}. You may optionally set
2104 the subsystem version also. Numeric values are also accepted for
2106 [This option is specific to PE targets.]
2108 @item --extract-symbol
2109 Keep the file's section flags and symbols but remove all section data.
2110 Specifically, the option:
2113 @item removes the contents of all sections;
2114 @item sets the size of every section to zero; and
2115 @item sets the file's start address to zero.
2118 This option is used to build a @file{.sym} file for a VxWorks kernel.
2119 It can also be a useful way of reducing the size of a @option{--just-symbols}
2122 @item --compress-debug-sections
2123 Compress DWARF debug sections using zlib with SHF_COMPRESSED from the
2124 ELF ABI. Note - if compression would actually make a section
2125 @emph{larger}, then it is not compressed.
2127 @item --compress-debug-sections=none
2128 @itemx --compress-debug-sections=zlib
2129 @itemx --compress-debug-sections=zlib-gnu
2130 @itemx --compress-debug-sections=zlib-gabi
2131 For ELF files, these options control how DWARF debug sections are
2132 compressed. @option{--compress-debug-sections=none} is equivalent
2133 to @option{--decompress-debug-sections}.
2134 @option{--compress-debug-sections=zlib} and
2135 @option{--compress-debug-sections=zlib-gabi} are equivalent to
2136 @option{--compress-debug-sections}.
2137 @option{--compress-debug-sections=zlib-gnu} compresses DWARF debug
2138 sections using zlib. The debug sections are renamed to begin with
2139 @samp{.zdebug} instead of @samp{.debug}. Note - if compression would
2140 actually make a section @emph{larger}, then it is not compressed nor
2143 @item --decompress-debug-sections
2144 Decompress DWARF debug sections using zlib. The original section
2145 names of the compressed sections are restored.
2147 @item --elf-stt-common=yes
2148 @itemx --elf-stt-common=no
2149 For ELF files, these options control whether common symbols should be
2150 converted to the @code{STT_COMMON} or @code{STT_OBJECT} type.
2151 @option{--elf-stt-common=yes} converts common symbol type to
2152 @code{STT_COMMON}. @option{--elf-stt-common=no} converts common symbol
2153 type to @code{STT_OBJECT}.
2156 @itemx --no-merge-notes
2157 For ELF files, attempt (or do not attempt) to reduce the size of any
2158 SHT_NOTE type sections by removing duplicate notes.
2162 Show the version number of @command{objcopy}.
2164 @item --verilog-data-width=@var{bytes}
2165 For Verilog output, this options controls the number of bytes
2166 converted for each output data element. The input target controls the
2167 endianness of the conversion.
2171 Verbose output: list all object files modified. In the case of
2172 archives, @samp{objcopy -V} lists all members of the archive.
2175 Show a summary of the options to @command{objcopy}.
2178 Display a list showing all architectures and object formats available.
2184 @c man begin SEEALSO objcopy
2185 ld(1), objdump(1), and the Info entries for @file{binutils}.
2192 @cindex object file information
2195 @c man title objdump display information from object files
2198 @c man begin SYNOPSIS objdump
2199 objdump [@option{-a}|@option{--archive-headers}]
2200 [@option{-b} @var{bfdname}|@option{--target=@var{bfdname}}]
2201 [@option{-C}|@option{--demangle}[=@var{style}] ]
2202 [@option{-d}|@option{--disassemble}[=@var{symbol}]]
2203 [@option{-D}|@option{--disassemble-all}]
2204 [@option{-z}|@option{--disassemble-zeroes}]
2205 [@option{-EB}|@option{-EL}|@option{--endian=}@{big | little @}]
2206 [@option{-f}|@option{--file-headers}]
2207 [@option{-F}|@option{--file-offsets}]
2208 [@option{--file-start-context}]
2209 [@option{-g}|@option{--debugging}]
2210 [@option{-e}|@option{--debugging-tags}]
2211 [@option{-h}|@option{--section-headers}|@option{--headers}]
2212 [@option{-i}|@option{--info}]
2213 [@option{-j} @var{section}|@option{--section=}@var{section}]
2214 [@option{-l}|@option{--line-numbers}]
2215 [@option{-S}|@option{--source}]
2216 [@option{--source-comment}[=@var{text}]]
2217 [@option{-m} @var{machine}|@option{--architecture=}@var{machine}]
2218 [@option{-M} @var{options}|@option{--disassembler-options=}@var{options}]
2219 [@option{-p}|@option{--private-headers}]
2220 [@option{-P} @var{options}|@option{--private=}@var{options}]
2221 [@option{-r}|@option{--reloc}]
2222 [@option{-R}|@option{--dynamic-reloc}]
2223 [@option{-s}|@option{--full-contents}]
2224 [@option{-W[lLiaprmfFsoORtUuTgAck]}|
2225 @option{--dwarf}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links]]
2226 [@option{-WK}|@option{--dwarf=follow-links}]
2227 [@option{-WN}|@option{--dwarf=no-follow-links}]
2228 [@option{-L}|@option{--process-links}]
2229 [@option{--ctf=}@var{section}]
2230 [@option{-G}|@option{--stabs}]
2231 [@option{-t}|@option{--syms}]
2232 [@option{-T}|@option{--dynamic-syms}]
2233 [@option{-x}|@option{--all-headers}]
2234 [@option{-w}|@option{--wide}]
2235 [@option{--start-address=}@var{address}]
2236 [@option{--stop-address=}@var{address}]
2237 [@option{--no-addresses}]
2238 [@option{--prefix-addresses}]
2239 [@option{--[no-]show-raw-insn}]
2240 [@option{--adjust-vma=}@var{offset}]
2241 [@option{--dwarf-depth=@var{n}}]
2242 [@option{--dwarf-start=@var{n}}]
2243 [@option{--ctf-parent=}@var{section}]
2244 [@option{--no-recurse-limit}|@option{--recurse-limit}]
2245 [@option{--special-syms}]
2246 [@option{--prefix=}@var{prefix}]
2247 [@option{--prefix-strip=}@var{level}]
2248 [@option{--insn-width=}@var{width}]
2249 [@option{--visualize-jumps[=color|=extended-color|=off]}
2250 [@option{-V}|@option{--version}]
2251 [@option{-H}|@option{--help}]
2252 @var{objfile}@dots{}
2256 @c man begin DESCRIPTION objdump
2258 @command{objdump} displays information about one or more object files.
2259 The options control what particular information to display. This
2260 information is mostly useful to programmers who are working on the
2261 compilation tools, as opposed to programmers who just want their
2262 program to compile and work.
2264 @var{objfile}@dots{} are the object files to be examined. When you
2265 specify archives, @command{objdump} shows information on each of the member
2270 @c man begin OPTIONS objdump
2272 The long and short forms of options, shown here as alternatives, are
2273 equivalent. At least one option from the list
2274 @option{-a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-P,-r,-R,-s,-S,-t,-T,-V,-x} must be given.
2278 @itemx --archive-header
2279 @cindex archive headers
2280 If any of the @var{objfile} files are archives, display the archive
2281 header information (in a format similar to @samp{ls -l}). Besides the
2282 information you could list with @samp{ar tv}, @samp{objdump -a} shows
2283 the object file format of each archive member.
2285 @item --adjust-vma=@var{offset}
2286 @cindex section addresses in objdump
2287 @cindex VMA in objdump
2288 When dumping information, first add @var{offset} to all the section
2289 addresses. This is useful if the section addresses do not correspond to
2290 the symbol table, which can happen when putting sections at particular
2291 addresses when using a format which can not represent section addresses,
2294 @item -b @var{bfdname}
2295 @itemx --target=@var{bfdname}
2296 @cindex object code format
2297 Specify that the object-code format for the object files is
2298 @var{bfdname}. This option may not be necessary; @var{objdump} can
2299 automatically recognize many formats.
2303 objdump -b oasys -m vax -h fu.o
2306 displays summary information from the section headers (@option{-h}) of
2307 @file{fu.o}, which is explicitly identified (@option{-m}) as a VAX object
2308 file in the format produced by Oasys compilers. You can list the
2309 formats available with the @option{-i} option.
2310 @xref{Target Selection}, for more information.
2313 @itemx --demangle[=@var{style}]
2314 @cindex demangling in objdump
2315 Decode (@dfn{demangle}) low-level symbol names into user-level names.
2316 Besides removing any initial underscore prepended by the system, this
2317 makes C++ function names readable. Different compilers have different
2318 mangling styles. The optional demangling style argument can be used to
2319 choose an appropriate demangling style for your compiler. @xref{c++filt},
2320 for more information on demangling.
2322 @item --recurse-limit
2323 @itemx --no-recurse-limit
2324 @itemx --recursion-limit
2325 @itemx --no-recursion-limit
2326 Enables or disables a limit on the amount of recursion performed
2327 whilst demangling strings. Since the name mangling formats allow for
2328 an infinite level of recursion it is possible to create strings whose
2329 decoding will exhaust the amount of stack space available on the host
2330 machine, triggering a memory fault. The limit tries to prevent this
2331 from happening by restricting recursion to 2048 levels of nesting.
2333 The default is for this limit to be enabled, but disabling it may be
2334 necessary in order to demangle truly complicated names. Note however
2335 that if the recursion limit is disabled then stack exhaustion is
2336 possible and any bug reports about such an event will be rejected.
2340 Display debugging information. This attempts to parse STABS
2341 debugging format information stored in the file and print it out using
2342 a C like syntax. If no STABS debugging was found this option
2343 falls back on the @option{-W} option to print any DWARF information in
2347 @itemx --debugging-tags
2348 Like @option{-g}, but the information is generated in a format compatible
2352 @itemx --disassemble
2353 @itemx --disassemble=@var{symbol}
2354 @cindex disassembling object code
2355 @cindex machine instructions
2356 Display the assembler mnemonics for the machine instructions from the
2357 input file. This option only disassembles those sections which are
2358 expected to contain instructions. If the optional @var{symbol}
2359 argument is given, then display the assembler mnemonics starting at
2360 @var{symbol}. If @var{symbol} is a function name then disassembly
2361 will stop at the end of the function, otherwise it will stop when the
2362 next symbol is encountered. If there are no matches for @var{symbol}
2363 then nothing will be displayed.
2365 Note if the @option{--dwarf=follow-links} option is enabled
2366 then any symbol tables in linked debug info files will be read in and
2367 used when disassembling.
2370 @itemx --disassemble-all
2371 Like @option{-d}, but disassemble the contents of all sections, not just
2372 those expected to contain instructions.
2374 This option also has a subtle effect on the disassembly of
2375 instructions in code sections. When option @option{-d} is in effect
2376 objdump will assume that any symbols present in a code section occur
2377 on the boundary between instructions and it will refuse to disassemble
2378 across such a boundary. When option @option{-D} is in effect however
2379 this assumption is supressed. This means that it is possible for the
2380 output of @option{-d} and @option{-D} to differ if, for example, data
2381 is stored in code sections.
2383 If the target is an ARM architecture this switch also has the effect
2384 of forcing the disassembler to decode pieces of data found in code
2385 sections as if they were instructions.
2387 Note if the @option{--dwarf=follow-links} option is enabled
2388 then any symbol tables in linked debug info files will be read in and
2389 used when disassembling.
2391 @item --no-addresses
2392 When disassembling, don't print addresses on each line or for symbols
2393 and relocation offsets. In combination with @option{--no-show-raw-insn}
2394 this may be useful for comparing compiler output.
2396 @item --prefix-addresses
2397 When disassembling, print the complete address on each line. This is
2398 the older disassembly format.
2402 @itemx --endian=@{big|little@}
2404 @cindex disassembly endianness
2405 Specify the endianness of the object files. This only affects
2406 disassembly. This can be useful when disassembling a file format which
2407 does not describe endianness information, such as S-records.
2410 @itemx --file-headers
2411 @cindex object file header
2412 Display summary information from the overall header of
2413 each of the @var{objfile} files.
2416 @itemx --file-offsets
2417 @cindex object file offsets
2418 When disassembling sections, whenever a symbol is displayed, also
2419 display the file offset of the region of data that is about to be
2420 dumped. If zeroes are being skipped, then when disassembly resumes,
2421 tell the user how many zeroes were skipped and the file offset of the
2422 location from where the disassembly resumes. When dumping sections,
2423 display the file offset of the location from where the dump starts.
2425 @item --file-start-context
2426 @cindex source code context
2427 Specify that when displaying interlisted source code/disassembly
2428 (assumes @option{-S}) from a file that has not yet been displayed, extend the
2429 context to the start of the file.
2432 @itemx --section-headers
2434 @cindex section headers
2435 Display summary information from the section headers of the
2438 File segments may be relocated to nonstandard addresses, for example by
2439 using the @option{-Ttext}, @option{-Tdata}, or @option{-Tbss} options to
2440 @command{ld}. However, some object file formats, such as a.out, do not
2441 store the starting address of the file segments. In those situations,
2442 although @command{ld} relocates the sections correctly, using @samp{objdump
2443 -h} to list the file section headers cannot show the correct addresses.
2444 Instead, it shows the usual addresses, which are implicit for the
2447 Note, in some cases it is possible for a section to have both the
2448 READONLY and the NOREAD attributes set. In such cases the NOREAD
2449 attribute takes precedence, but @command{objdump} will report both
2450 since the exact setting of the flag bits might be important.
2454 Print a summary of the options to @command{objdump} and exit.
2458 @cindex architectures available
2459 @cindex object formats available
2460 Display a list showing all architectures and object formats available
2461 for specification with @option{-b} or @option{-m}.
2464 @itemx --section=@var{name}
2465 @cindex section information
2466 Display information only for section @var{name}.
2469 @itemx --process-links
2470 Display the contents of non-debug sections found in separate debuginfo
2471 files that are linked to the main file. This option automatically
2472 implies the @option{-WK} option, and only sections requested by other
2473 command line options will be displayed.
2476 @itemx --line-numbers
2477 @cindex source filenames for object files
2478 Label the display (using debugging information) with the filename and
2479 source line numbers corresponding to the object code or relocs shown.
2480 Only useful with @option{-d}, @option{-D}, or @option{-r}.
2482 @item -m @var{machine}
2483 @itemx --architecture=@var{machine}
2484 @cindex architecture
2485 @cindex disassembly architecture
2486 Specify the architecture to use when disassembling object files. This
2487 can be useful when disassembling object files which do not describe
2488 architecture information, such as S-records. You can list the available
2489 architectures with the @option{-i} option.
2491 If the target is an ARM architecture then this switch has an
2492 additional effect. It restricts the disassembly to only those
2493 instructions supported by the architecture specified by @var{machine}.
2494 If it is necessary to use this switch because the input file does not
2495 contain any architecture information, but it is also desired to
2496 disassemble all the instructions use @option{-marm}.
2498 @item -M @var{options}
2499 @itemx --disassembler-options=@var{options}
2500 Pass target specific information to the disassembler. Only supported on
2501 some targets. If it is necessary to specify more than one
2502 disassembler option then multiple @option{-M} options can be used or
2503 can be placed together into a comma separated list.
2505 For ARC, @option{dsp} controls the printing of DSP instructions,
2506 @option{spfp} selects the printing of FPX single precision FP
2507 instructions, @option{dpfp} selects the printing of FPX double
2508 precision FP instructions, @option{quarkse_em} selects the printing of
2509 special QuarkSE-EM instructions, @option{fpuda} selects the printing
2510 of double precision assist instructions, @option{fpus} selects the
2511 printing of FPU single precision FP instructions, while @option{fpud}
2512 selects the printing of FPU double precision FP instructions.
2513 Additionally, one can choose to have all the immediates printed in
2514 hexadecimal using @option{hex}. By default, the short immediates are
2515 printed using the decimal representation, while the long immediate
2516 values are printed as hexadecimal.
2518 @option{cpu=...} allows one to enforce a particular ISA when disassembling
2519 instructions, overriding the @option{-m} value or whatever is in the ELF file.
2520 This might be useful to select ARC EM or HS ISA, because architecture is same
2521 for those and disassembler relies on private ELF header data to decide if code
2522 is for EM or HS. This option might be specified multiple times - only the
2523 latest value will be used. Valid values are same as for the assembler
2524 @option{-mcpu=...} option.
2526 If the target is an ARM architecture then this switch can be used to
2527 select which register name set is used during disassembler. Specifying
2528 @option{-M reg-names-std} (the default) will select the register names as
2529 used in ARM's instruction set documentation, but with register 13 called
2530 'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying
2531 @option{-M reg-names-apcs} will select the name set used by the ARM
2532 Procedure Call Standard, whilst specifying @option{-M reg-names-raw} will
2533 just use @samp{r} followed by the register number.
2535 There are also two variants on the APCS register naming scheme enabled
2536 by @option{-M reg-names-atpcs} and @option{-M reg-names-special-atpcs} which
2537 use the ARM/Thumb Procedure Call Standard naming conventions. (Either
2538 with the normal register names or the special register names).
2540 This option can also be used for ARM architectures to force the
2541 disassembler to interpret all instructions as Thumb instructions by
2542 using the switch @option{--disassembler-options=force-thumb}. This can be
2543 useful when attempting to disassemble thumb code produced by other
2546 For AArch64 targets this switch can be used to set whether instructions are
2547 disassembled as the most general instruction using the @option{-M no-aliases}
2548 option or whether instruction notes should be generated as comments in the
2549 disasssembly using @option{-M notes}.
2551 For the x86, some of the options duplicate functions of the @option{-m}
2552 switch, but allow finer grained control.
2557 Select disassembly for the given architecture.
2561 Select between intel syntax mode and AT&T syntax mode.
2565 Select between AMD64 ISA and Intel64 ISA.
2567 @item intel-mnemonic
2569 Select between intel mnemonic mode and AT&T mnemonic mode.
2570 Note: @code{intel-mnemonic} implies @code{intel} and
2571 @code{att-mnemonic} implies @code{att}.
2578 Specify the default address size and operand size. These five options
2579 will be overridden if @code{x86-64}, @code{i386} or @code{i8086}
2580 appear later in the option string.
2583 When in AT&T mode and also for a limited set of instructions when in Intel
2584 mode, instructs the disassembler to print a mnemonic suffix even when the
2585 suffix could be inferred by the operands or, for certain instructions, the
2586 execution mode's defaults.
2589 For PowerPC, the @option{-M} argument @option{raw} selects
2590 disasssembly of hardware insns rather than aliases. For example, you
2591 will see @code{rlwinm} rather than @code{clrlwi}, and @code{addi}
2592 rather than @code{li}. All of the @option{-m} arguments for
2593 @command{gas} that select a CPU are supported. These are:
2594 @option{403}, @option{405}, @option{440}, @option{464}, @option{476},
2595 @option{601}, @option{603}, @option{604}, @option{620}, @option{7400},
2596 @option{7410}, @option{7450}, @option{7455}, @option{750cl},
2597 @option{821}, @option{850}, @option{860}, @option{a2}, @option{booke},
2598 @option{booke32}, @option{cell}, @option{com}, @option{e200z4},
2599 @option{e300}, @option{e500}, @option{e500mc}, @option{e500mc64},
2600 @option{e500x2}, @option{e5500}, @option{e6500}, @option{efs},
2601 @option{power4}, @option{power5}, @option{power6}, @option{power7},
2602 @option{power8}, @option{power9}, @option{power10}, @option{ppc},
2603 @option{ppc32}, @option{ppc64}, @option{ppc64bridge}, @option{ppcps},
2604 @option{pwr}, @option{pwr2}, @option{pwr4}, @option{pwr5}, @option{pwr5x},
2605 @option{pwr6}, @option{pwr7}, @option{pwr8}, @option{pwr9}, @option{pwr10},
2606 @option{pwrx}, @option{titan}, and @option{vle}.
2607 @option{32} and @option{64} modify the default or a prior CPU
2608 selection, disabling and enabling 64-bit insns respectively. In
2609 addition, @option{altivec}, @option{any}, @option{htm}, @option{vsx},
2610 and @option{spe} add capabilities to a previous @emph{or later} CPU
2611 selection. @option{any} will disassemble any opcode known to
2612 binutils, but in cases where an opcode has two different meanings or
2613 different arguments, you may not see the disassembly you expect.
2614 If you disassemble without giving a CPU selection, a default will be
2615 chosen from information gleaned by BFD from the object files headers,
2616 but the result again may not be as you expect.
2618 For MIPS, this option controls the printing of instruction mnemonic
2619 names and register names in disassembled instructions. Multiple
2620 selections from the following may be specified as a comma separated
2621 string, and invalid options are ignored:
2625 Print the 'raw' instruction mnemonic instead of some pseudo
2626 instruction mnemonic. I.e., print 'daddu' or 'or' instead of 'move',
2627 'sll' instead of 'nop', etc.
2630 Disassemble MSA instructions.
2633 Disassemble the virtualization ASE instructions.
2636 Disassemble the eXtended Physical Address (XPA) ASE instructions.
2638 @item gpr-names=@var{ABI}
2639 Print GPR (general-purpose register) names as appropriate
2640 for the specified ABI. By default, GPR names are selected according to
2641 the ABI of the binary being disassembled.
2643 @item fpr-names=@var{ABI}
2644 Print FPR (floating-point register) names as
2645 appropriate for the specified ABI. By default, FPR numbers are printed
2648 @item cp0-names=@var{ARCH}
2649 Print CP0 (system control coprocessor; coprocessor 0) register names
2650 as appropriate for the CPU or architecture specified by
2651 @var{ARCH}. By default, CP0 register names are selected according to
2652 the architecture and CPU of the binary being disassembled.
2654 @item hwr-names=@var{ARCH}
2655 Print HWR (hardware register, used by the @code{rdhwr} instruction) names
2656 as appropriate for the CPU or architecture specified by
2657 @var{ARCH}. By default, HWR names are selected according to
2658 the architecture and CPU of the binary being disassembled.
2660 @item reg-names=@var{ABI}
2661 Print GPR and FPR names as appropriate for the selected ABI.
2663 @item reg-names=@var{ARCH}
2664 Print CPU-specific register names (CP0 register and HWR names)
2665 as appropriate for the selected CPU or architecture.
2668 For any of the options listed above, @var{ABI} or
2669 @var{ARCH} may be specified as @samp{numeric} to have numbers printed
2670 rather than names, for the selected types of registers.
2671 You can list the available values of @var{ABI} and @var{ARCH} using
2672 the @option{--help} option.
2674 For VAX, you can specify function entry addresses with @option{-M
2675 entry:0xf00ba}. You can use this multiple times to properly
2676 disassemble VAX binary files that don't contain symbol tables (like
2677 ROM dumps). In these cases, the function entry mask would otherwise
2678 be decoded as VAX instructions, which would probably lead the rest
2679 of the function being wrongly disassembled.
2682 @itemx --private-headers
2683 Print information that is specific to the object file format. The exact
2684 information printed depends upon the object file format. For some
2685 object file formats, no additional information is printed.
2687 @item -P @var{options}
2688 @itemx --private=@var{options}
2689 Print information that is specific to the object file format. The
2690 argument @var{options} is a comma separated list that depends on the
2691 format (the lists of options is displayed with the help).
2693 For XCOFF, the available options are:
2709 Not all object formats support this option. In particular the ELF
2710 format does not use it.
2714 @cindex relocation entries, in object file
2715 Print the relocation entries of the file. If used with @option{-d} or
2716 @option{-D}, the relocations are printed interspersed with the
2720 @itemx --dynamic-reloc
2721 @cindex dynamic relocation entries, in object file
2722 Print the dynamic relocation entries of the file. This is only
2723 meaningful for dynamic objects, such as certain types of shared
2724 libraries. As for @option{-r}, if used with @option{-d} or
2725 @option{-D}, the relocations are printed interspersed with the
2729 @itemx --full-contents
2730 @cindex sections, full contents
2731 @cindex object file sections
2732 Display the full contents of any sections requested. By default all
2733 non-empty sections are displayed.
2737 @cindex source disassembly
2738 @cindex disassembly, with source
2739 Display source code intermixed with disassembly, if possible. Implies
2742 @item --source-comment[=@var{txt}]
2743 @cindex source disassembly
2744 @cindex disassembly, with source
2745 Like the @option{-S} option, but all source code lines are displayed
2746 with a prefix of @var{txt}. Typically @var{txt} will be a comment
2747 string which can be used to distinguish the assembler code from the
2748 source code. If @var{txt} is not provided then a default string of
2749 @var{``# ``} (hash followed by a space), will be used.
2751 @item --prefix=@var{prefix}
2752 @cindex Add prefix to absolute paths
2753 Specify @var{prefix} to add to the absolute paths when used with
2756 @item --prefix-strip=@var{level}
2757 @cindex Strip absolute paths
2758 Indicate how many initial directory names to strip off the hardwired
2759 absolute paths. It has no effect without @option{--prefix=}@var{prefix}.
2761 @item --show-raw-insn
2762 When disassembling instructions, print the instruction in hex as well as
2763 in symbolic form. This is the default except when
2764 @option{--prefix-addresses} is used.
2766 @item --no-show-raw-insn
2767 When disassembling instructions, do not print the instruction bytes.
2768 This is the default when @option{--prefix-addresses} is used.
2770 @item --insn-width=@var{width}
2771 @cindex Instruction width
2772 Display @var{width} bytes on a single line when disassembling
2775 @item --visualize-jumps[=color|=extended-color|=off]
2776 Visualize jumps that stay inside a function by drawing ASCII art between
2777 the start and target addresses. The optional @option{=color} argument
2778 adds color to the output using simple terminal colors. Alternatively
2779 the @option{=extended-color} argument will add color using 8bit
2780 colors, but these might not work on all terminals.
2782 If it is necessary to disable the @option{visualize-jumps} option
2783 after it has previously been enabled then use
2784 @option{visualize-jumps=off}.
2786 @item -W[lLiaprmfFsoORtUuTgAckK]
2787 @itemx --dwarf[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]
2788 @include debug.options.texi
2791 Enable additional checks for consistency of Dwarf information.
2793 @include ctf.options.texi
2799 @cindex debug symbols
2800 @cindex ELF object file format
2801 Display the full contents of any sections requested. Display the
2802 contents of the .stab and .stab.index and .stab.excl sections from an
2803 ELF file. This is only useful on systems (such as Solaris 2.0) in which
2804 @code{.stab} debugging symbol-table entries are carried in an ELF
2805 section. In most other file formats, debugging symbol-table entries are
2806 interleaved with linkage symbols, and are visible in the @option{--syms}
2809 @item --start-address=@var{address}
2810 @cindex start-address
2811 Start displaying data at the specified address. This affects the output
2812 of the @option{-d}, @option{-r} and @option{-s} options.
2814 @item --stop-address=@var{address}
2815 @cindex stop-address
2816 Stop displaying data at the specified address. This affects the output
2817 of the @option{-d}, @option{-r} and @option{-s} options.
2821 @cindex symbol table entries, printing
2822 Print the symbol table entries of the file.
2823 This is similar to the information provided by the @samp{nm} program,
2824 although the display format is different. The format of the output
2825 depends upon the format of the file being dumped, but there are two main
2826 types. One looks like this:
2829 [ 4](sec 3)(fl 0x00)(ty 0)(scl 3) (nx 1) 0x00000000 .bss
2830 [ 6](sec 1)(fl 0x00)(ty 0)(scl 2) (nx 0) 0x00000000 fred
2833 where the number inside the square brackets is the number of the entry
2834 in the symbol table, the @var{sec} number is the section number, the
2835 @var{fl} value are the symbol's flag bits, the @var{ty} number is the
2836 symbol's type, the @var{scl} number is the symbol's storage class and
2837 the @var{nx} value is the number of auxiliary entries associated with
2838 the symbol. The last two fields are the symbol's value and its name.
2840 The other common output format, usually seen with ELF based files,
2844 00000000 l d .bss 00000000 .bss
2845 00000000 g .text 00000000 fred
2848 Here the first number is the symbol's value (sometimes referred to as
2849 its address). The next field is actually a set of characters and
2850 spaces indicating the flag bits that are set on the symbol. These
2851 characters are described below. Next is the section with which the
2852 symbol is associated or @emph{*ABS*} if the section is absolute (ie
2853 not connected with any section), or @emph{*UND*} if the section is
2854 referenced in the file being dumped, but not defined there.
2856 After the section name comes another field, a number, which for common
2857 symbols is the alignment and for other symbol is the size. Finally
2858 the symbol's name is displayed.
2860 The flag characters are divided into 7 groups as follows:
2866 The symbol is a local (l), global (g), unique global (u), neither
2867 global nor local (a space) or both global and local (!). A
2868 symbol can be neither local or global for a variety of reasons, e.g.,
2869 because it is used for debugging, but it is probably an indication of
2870 a bug if it is ever both local and global. Unique global symbols are
2871 a GNU extension to the standard set of ELF symbol bindings. For such
2872 a symbol the dynamic linker will make sure that in the entire process
2873 there is just one symbol with this name and type in use.
2876 The symbol is weak (w) or strong (a space).
2879 The symbol denotes a constructor (C) or an ordinary symbol (a space).
2882 The symbol is a warning (W) or a normal symbol (a space). A warning
2883 symbol's name is a message to be displayed if the symbol following the
2884 warning symbol is ever referenced.
2888 The symbol is an indirect reference to another symbol (I), a function
2889 to be evaluated during reloc processing (i) or a normal symbol (a
2894 The symbol is a debugging symbol (d) or a dynamic symbol (D) or a
2895 normal symbol (a space).
2900 The symbol is the name of a function (F) or a file (f) or an object
2901 (O) or just a normal symbol (a space).
2905 @itemx --dynamic-syms
2906 @cindex dynamic symbol table entries, printing
2907 Print the dynamic symbol table entries of the file. This is only
2908 meaningful for dynamic objects, such as certain types of shared
2909 libraries. This is similar to the information provided by the @samp{nm}
2910 program when given the @option{-D} (@option{--dynamic}) option.
2912 The output format is similar to that produced by the @option{--syms}
2913 option, except that an extra field is inserted before the symbol's
2914 name, giving the version information associated with the symbol.
2915 If the version is the default version to be used when resolving
2916 unversioned references to the symbol then it's displayed as is,
2917 otherwise it's put into parentheses.
2919 @item --special-syms
2920 When displaying symbols include those which the target considers to be
2921 special in some way and which would not normally be of interest to the
2926 Print the version number of @command{objdump} and exit.
2929 @itemx --all-headers
2930 @cindex all header information, object file
2931 @cindex header information, all
2932 Display all available header information, including the symbol table and
2933 relocation entries. Using @option{-x} is equivalent to specifying all of
2934 @option{-a -f -h -p -r -t}.
2938 @cindex wide output, printing
2939 Format some lines for output devices that have more than 80 columns.
2940 Also do not truncate symbol names when they are displayed.
2943 @itemx --disassemble-zeroes
2944 Normally the disassembly output will skip blocks of zeroes. This
2945 option directs the disassembler to disassemble those blocks, just like
2952 @c man begin SEEALSO objdump
2953 nm(1), readelf(1), and the Info entries for @file{binutils}.
2961 @cindex archive contents
2962 @cindex symbol index
2964 @c man title ranlib generate an index to an archive
2967 @c man begin SYNOPSIS ranlib
2968 ranlib [@option{--plugin} @var{name}] [@option{-DhHvVt}] @var{archive}
2972 @c man begin DESCRIPTION ranlib
2974 @command{ranlib} generates an index to the contents of an archive and
2975 stores it in the archive. The index lists each symbol defined by a
2976 member of an archive that is a relocatable object file.
2978 You may use @samp{nm -s} or @samp{nm --print-armap} to list this index.
2980 An archive with such an index speeds up linking to the library and
2981 allows routines in the library to call each other without regard to
2982 their placement in the archive.
2984 The @sc{gnu} @command{ranlib} program is another form of @sc{gnu} @command{ar}; running
2985 @command{ranlib} is completely equivalent to executing @samp{ar -s}.
2990 @c man begin OPTIONS ranlib
2996 Show usage information for @command{ranlib}.
3001 Show the version number of @command{ranlib}.
3004 @cindex deterministic archives
3005 @kindex --enable-deterministic-archives
3006 Operate in @emph{deterministic} mode. The symbol map archive member's
3007 header will show zero for the UID, GID, and timestamp. When this
3008 option is used, multiple runs will produce identical output files.
3010 If @file{binutils} was configured with
3011 @option{--enable-deterministic-archives}, then this mode is on by
3012 default. It can be disabled with the @samp{-U} option, described
3016 Update the timestamp of the symbol map of an archive.
3019 @cindex deterministic archives
3020 @kindex --enable-deterministic-archives
3021 Do @emph{not} operate in @emph{deterministic} mode. This is the
3022 inverse of the @samp{-D} option, above: the archive index will get
3023 actual UID, GID, timestamp, and file mode values.
3025 If @file{binutils} was configured @emph{without}
3026 @option{--enable-deterministic-archives}, then this mode is on by
3034 @c man begin SEEALSO ranlib
3035 ar(1), nm(1), and the Info entries for @file{binutils}.
3043 @cindex section sizes
3045 @c man title size list section sizes and total size of binary files
3048 @c man begin SYNOPSIS size
3049 size [@option{-A}|@option{-B}|@option{-G}|@option{--format=}@var{compatibility}]
3051 [@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}]
3053 [@option{-t}|@option{--totals}]
3054 [@option{--target=}@var{bfdname}] [@option{-V}|@option{--version}]
3055 [@var{objfile}@dots{}]
3059 @c man begin DESCRIPTION size
3061 The @sc{gnu} @command{size} utility lists the section sizes and the total
3062 size for each of the binary files @var{objfile} on its argument list.
3063 By default, one line of output is generated for each file or each
3064 module if the file is an archive.
3066 @var{objfile}@dots{} are the files to be examined. If none are
3067 specified, the file @code{a.out} will be used instead.
3071 @c man begin OPTIONS size
3073 The command-line options have the following meanings:
3079 @itemx --format=@var{compatibility}
3080 @cindex @command{size} display format
3081 Using one of these options, you can choose whether the output from @sc{gnu}
3082 @command{size} resembles output from System V @command{size} (using @option{-A},
3083 or @option{--format=sysv}), or Berkeley @command{size} (using @option{-B}, or
3084 @option{--format=berkeley}). The default is the one-line format similar to
3085 Berkeley's. Alternatively, you can choose the GNU format output
3086 (using @option{-G}, or @option{--format=gnu}), this is similar to
3087 Berkeley's output format, but sizes are counted differently.
3088 @c Bonus for doc-source readers: you can also say --format=strange (or
3089 @c anything else that starts with 's') for sysv, and --format=boring (or
3090 @c anything else that starts with 'b') for Berkeley.
3092 Here is an example of the Berkeley (default) format of output from
3095 $ size --format=Berkeley ranlib size
3096 text data bss dec hex filename
3097 294880 81920 11592 388392 5ed28 ranlib
3098 294880 81920 11888 388688 5ee50 size
3101 The Berkeley style output counts read only data in the @code{text}
3102 column, not in the @code{data} column, the @code{dec} and @code{hex}
3103 columns both display the sum of the @code{text}, @code{data}, and
3104 @code{bss} columns in decimal and hexadecimal respectively.
3106 The GNU format counts read only data in the @code{data} column, not
3107 the @code{text} column, and only displays the sum of the @code{text},
3108 @code{data}, and @code{bss} columns once, in the @code{total} column.
3109 The @option{--radix} option can be used to change the number base for
3110 all columns. Here is the same data displayed with GNU conventions:
3113 $ size --format=GNU ranlib size
3114 text data bss total filename
3115 279880 96920 11592 388392 ranlib
3116 279880 96920 11888 388688 size
3120 This is the same data, but displayed closer to System V conventions:
3123 $ size --format=SysV ranlib size
3141 Show a summary of acceptable arguments and options.
3146 @itemx --radix=@var{number}
3147 @cindex @command{size} number format
3148 @cindex radix for section sizes
3149 Using one of these options, you can control whether the size of each
3150 section is given in decimal (@option{-d}, or @option{--radix=10}); octal
3151 (@option{-o}, or @option{--radix=8}); or hexadecimal (@option{-x}, or
3152 @option{--radix=16}). In @option{--radix=@var{number}}, only the three
3153 values (8, 10, 16) are supported. The total size is always given in two
3154 radices; decimal and hexadecimal for @option{-d} or @option{-x} output, or
3155 octal and hexadecimal if you're using @option{-o}.
3158 Print total size of common symbols in each file. When using Berkeley
3159 or GNU format these are included in the bss size.
3163 Show totals of all objects listed (Berkeley or GNU format mode only).
3165 @item --target=@var{bfdname}
3166 @cindex object code format
3167 Specify that the object-code format for @var{objfile} is
3168 @var{bfdname}. This option may not be necessary; @command{size} can
3169 automatically recognize many formats.
3170 @xref{Target Selection}, for more information.
3174 Display the version number of @command{size}.
3180 @c man begin SEEALSO size
3181 ar(1), objdump(1), readelf(1), and the Info entries for @file{binutils}.
3188 @cindex listings strings
3189 @cindex printing strings
3190 @cindex strings, printing
3192 @c man title strings print the sequences of printable characters in files
3195 @c man begin SYNOPSIS strings
3196 strings [@option{-afovV}] [@option{-}@var{min-len}]
3197 [@option{-n} @var{min-len}] [@option{--bytes=}@var{min-len}]
3198 [@option{-t} @var{radix}] [@option{--radix=}@var{radix}]
3199 [@option{-e} @var{encoding}] [@option{--encoding=}@var{encoding}]
3200 [@option{-}] [@option{--all}] [@option{--print-file-name}]
3201 [@option{-T} @var{bfdname}] [@option{--target=}@var{bfdname}]
3202 [@option{-w}] [@option{--include-all-whitespace}]
3203 [@option{-s}] [@option{--output-separator}@var{sep_string}]
3204 [@option{--help}] [@option{--version}] @var{file}@dots{}
3208 @c man begin DESCRIPTION strings
3210 For each @var{file} given, @sc{gnu} @command{strings} prints the
3211 printable character sequences that are at least 4 characters long (or
3212 the number given with the options below) and are followed by an
3213 unprintable character.
3215 Depending upon how the strings program was configured it will default
3216 to either displaying all the printable sequences that it can find in
3217 each file, or only those sequences that are in loadable, initialized
3218 data sections. If the file type is unrecognizable, or if strings is
3219 reading from stdin then it will always display all of the printable
3220 sequences that it can find.
3222 For backwards compatibility any file that occurs after a command-line
3223 option of just @option{-} will also be scanned in full, regardless of
3224 the presence of any @option{-d} option.
3226 @command{strings} is mainly useful for determining the contents of
3231 @c man begin OPTIONS strings
3237 Scan the whole file, regardless of what sections it contains or
3238 whether those sections are loaded or initialized. Normally this is
3239 the default behaviour, but strings can be configured so that the
3240 @option{-d} is the default instead.
3242 The @option{-} option is position dependent and forces strings to
3243 perform full scans of any file that is mentioned after the @option{-}
3244 on the command line, even if the @option{-d} option has been
3249 Only print strings from initialized, loaded data sections in the
3250 file. This may reduce the amount of garbage in the output, but it
3251 also exposes the strings program to any security flaws that may be
3252 present in the BFD library used to scan and load sections. Strings
3253 can be configured so that this option is the default behaviour. In
3254 such cases the @option{-a} option can be used to avoid using the BFD
3255 library and instead just print all of the strings found in the file.
3258 @itemx --print-file-name
3259 Print the name of the file before each string.
3262 Print a summary of the program usage on the standard output and exit.
3264 @item -@var{min-len}
3265 @itemx -n @var{min-len}
3266 @itemx --bytes=@var{min-len}
3267 Print sequences of characters that are at least @var{min-len} characters
3268 long, instead of the default 4.
3271 Like @samp{-t o}. Some other versions of @command{strings} have @option{-o}
3272 act like @samp{-t d} instead. Since we can not be compatible with both
3273 ways, we simply chose one.
3275 @item -t @var{radix}
3276 @itemx --radix=@var{radix}
3277 Print the offset within the file before each string. The single
3278 character argument specifies the radix of the offset---@samp{o} for
3279 octal, @samp{x} for hexadecimal, or @samp{d} for decimal.
3281 @item -e @var{encoding}
3282 @itemx --encoding=@var{encoding}
3283 Select the character encoding of the strings that are to be found.
3284 Possible values for @var{encoding} are: @samp{s} = single-7-bit-byte
3285 characters (ASCII, ISO 8859, etc., default), @samp{S} =
3286 single-8-bit-byte characters, @samp{b} = 16-bit bigendian, @samp{l} =
3287 16-bit littleendian, @samp{B} = 32-bit bigendian, @samp{L} = 32-bit
3288 littleendian. Useful for finding wide character strings. (@samp{l}
3289 and @samp{b} apply to, for example, Unicode UTF-16/UCS-2 encodings).
3291 @item -T @var{bfdname}
3292 @itemx --target=@var{bfdname}
3293 @cindex object code format
3294 Specify an object code format other than your system's default format.
3295 @xref{Target Selection}, for more information.
3300 Print the program version number on the standard output and exit.
3303 @itemx --include-all-whitespace
3304 By default tab and space characters are included in the strings that
3305 are displayed, but other whitespace characters, such a newlines and
3306 carriage returns, are not. The @option{-w} option changes this so
3307 that all whitespace characters are considered to be part of a string.
3310 @itemx --output-separator
3311 By default, output strings are delimited by a new-line. This option
3312 allows you to supply any string to be used as the output record
3313 separator. Useful with --include-all-whitespace where strings
3314 may contain new-lines internally.
3320 @c man begin SEEALSO strings
3321 ar(1), nm(1), objdump(1), ranlib(1), readelf(1)
3322 and the Info entries for @file{binutils}.
3330 @cindex removing symbols
3331 @cindex discarding symbols
3332 @cindex symbols, discarding
3334 @c man title strip discard symbols and other data from object files
3337 @c man begin SYNOPSIS strip
3338 strip [@option{-F} @var{bfdname} |@option{--target=}@var{bfdname}]
3339 [@option{-I} @var{bfdname} |@option{--input-target=}@var{bfdname}]
3340 [@option{-O} @var{bfdname} |@option{--output-target=}@var{bfdname}]
3341 [@option{-s}|@option{--strip-all}]
3342 [@option{-S}|@option{-g}|@option{-d}|@option{--strip-debug}]
3343 [@option{--strip-dwo}]
3344 [@option{-K} @var{symbolname}|@option{--keep-symbol=}@var{symbolname}]
3345 [@option{-M}|@option{--merge-notes}][@option{--no-merge-notes}]
3346 [@option{-N} @var{symbolname} |@option{--strip-symbol=}@var{symbolname}]
3347 [@option{-w}|@option{--wildcard}]
3348 [@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}]
3349 [@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}]
3350 [@option{--keep-section=}@var{sectionpattern}]
3351 [@option{--remove-relocations=}@var{sectionpattern}]
3352 [@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}]
3353 [@option{-D}|@option{--enable-deterministic-archives}]
3354 [@option{-U}|@option{--disable-deterministic-archives}]
3355 [@option{--keep-section-symbols}]
3356 [@option{--keep-file-symbols}]
3357 [@option{--only-keep-debug}]
3358 [@option{-v} |@option{--verbose}] [@option{-V}|@option{--version}]
3359 [@option{--help}] [@option{--info}]
3360 @var{objfile}@dots{}
3364 @c man begin DESCRIPTION strip
3366 @sc{gnu} @command{strip} discards all symbols from object files
3367 @var{objfile}. The list of object files may include archives.
3368 At least one object file must be given.
3370 @command{strip} modifies the files named in its argument,
3371 rather than writing modified copies under different names.
3375 @c man begin OPTIONS strip
3378 @item -F @var{bfdname}
3379 @itemx --target=@var{bfdname}
3380 Treat the original @var{objfile} as a file with the object
3381 code format @var{bfdname}, and rewrite it in the same format.
3382 @xref{Target Selection}, for more information.
3385 Show a summary of the options to @command{strip} and exit.
3388 Display a list showing all architectures and object formats available.
3390 @item -I @var{bfdname}
3391 @itemx --input-target=@var{bfdname}
3392 Treat the original @var{objfile} as a file with the object
3393 code format @var{bfdname}.
3394 @xref{Target Selection}, for more information.
3396 @item -O @var{bfdname}
3397 @itemx --output-target=@var{bfdname}
3398 Replace @var{objfile} with a file in the output format @var{bfdname}.
3399 @xref{Target Selection}, for more information.
3401 @item -R @var{sectionname}
3402 @itemx --remove-section=@var{sectionname}
3403 Remove any section named @var{sectionname} from the output file, in
3404 addition to whatever sections would otherwise be removed. This
3405 option may be given more than once. Note that using this option
3406 inappropriately may make the output file unusable. The wildcard
3407 character @samp{*} may be given at the end of @var{sectionname}. If
3408 so, then any section starting with @var{sectionname} will be removed.
3410 If the first character of @var{sectionpattern} is the exclamation
3411 point (!) then matching sections will not be removed even if an
3412 earlier use of @option{--remove-section} on the same command line
3413 would otherwise remove it. For example:
3416 --remove-section=.text.* --remove-section=!.text.foo
3419 will remove all sections matching the pattern '.text.*', but will not
3420 remove the section '.text.foo'.
3422 @item --keep-section=@var{sectionpattern}
3423 When removing sections from the output file, keep sections that match
3424 @var{sectionpattern}.
3426 @item --remove-relocations=@var{sectionpattern}
3427 Remove relocations from the output file for any section matching
3428 @var{sectionpattern}. This option may be given more than once. Note
3429 that using this option inappropriately may make the output file
3430 unusable. Wildcard characters are accepted in @var{sectionpattern}.
3434 --remove-relocations=.text.*
3437 will remove the relocations for all sections matching the patter
3440 If the first character of @var{sectionpattern} is the exclamation
3441 point (!) then matching sections will not have their relocation
3442 removed even if an earlier use of @option{--remove-relocations} on the
3443 same command line would otherwise cause the relocations to be removed.
3447 --remove-relocations=.text.* --remove-relocations=!.text.foo
3450 will remove all relocations for sections matching the pattern
3451 '.text.*', but will not remove relocations for the section
3461 @itemx --strip-debug
3462 Remove debugging symbols only.
3465 Remove the contents of all DWARF .dwo sections, leaving the
3466 remaining debugging sections and all symbols intact.
3467 See the description of this option in the @command{objcopy} section
3468 for more information.
3470 @item --strip-unneeded
3471 Remove all symbols that are not needed for relocation processing in
3472 addition to debugging symbols and sections stripped by
3473 @option{--strip-debug}.
3475 @item -K @var{symbolname}
3476 @itemx --keep-symbol=@var{symbolname}
3477 When stripping symbols, keep symbol @var{symbolname} even if it would
3478 normally be stripped. This option may be given more than once.
3481 @itemx --merge-notes
3482 @itemx --no-merge-notes
3483 For ELF files, attempt (or do not attempt) to reduce the size of any
3484 SHT_NOTE type sections by removing duplicate notes. The default is to
3485 attempt this reduction unless stripping debug or DWO information.
3487 @item -N @var{symbolname}
3488 @itemx --strip-symbol=@var{symbolname}
3489 Remove symbol @var{symbolname} from the source file. This option may be
3490 given more than once, and may be combined with strip options other than
3494 Put the stripped output in @var{file}, rather than replacing the
3495 existing file. When this argument is used, only one @var{objfile}
3496 argument may be specified.
3499 @itemx --preserve-dates
3500 Preserve the access and modification dates of the file.
3503 @itemx --enable-deterministic-archives
3504 @cindex deterministic archives
3505 @kindex --enable-deterministic-archives
3506 Operate in @emph{deterministic} mode. When copying archive members
3507 and writing the archive index, use zero for UIDs, GIDs, timestamps,
3508 and use consistent file modes for all files.
3510 If @file{binutils} was configured with
3511 @option{--enable-deterministic-archives}, then this mode is on by default.
3512 It can be disabled with the @samp{-U} option, below.
3515 @itemx --disable-deterministic-archives
3516 @cindex deterministic archives
3517 @kindex --enable-deterministic-archives
3518 Do @emph{not} operate in @emph{deterministic} mode. This is the
3519 inverse of the @option{-D} option, above: when copying archive members
3520 and writing the archive index, use their actual UID, GID, timestamp,
3521 and file mode values.
3523 This is the default unless @file{binutils} was configured with
3524 @option{--enable-deterministic-archives}.
3528 Permit regular expressions in @var{symbolname}s used in other command
3529 line options. The question mark (?), asterisk (*), backslash (\) and
3530 square brackets ([]) operators can be used anywhere in the symbol
3531 name. If the first character of the symbol name is the exclamation
3532 point (!) then the sense of the switch is reversed for that symbol.
3539 would cause strip to only keep symbols that start with the letters
3540 ``fo'', but to discard the symbol ``foo''.
3543 @itemx --discard-all
3544 Remove non-global symbols.
3547 @itemx --discard-locals
3548 Remove compiler-generated local symbols.
3549 (These usually start with @samp{L} or @samp{.}.)
3551 @item --keep-section-symbols
3552 When stripping a file, perhaps with @option{--strip-debug} or
3553 @option{--strip-unneeded}, retain any symbols specifying section names,
3554 which would otherwise get stripped.
3556 @item --keep-file-symbols
3557 When stripping a file, perhaps with @option{--strip-debug} or
3558 @option{--strip-unneeded}, retain any symbols specifying source file names,
3559 which would otherwise get stripped.
3561 @item --only-keep-debug
3562 Strip a file, emptying the contents of any sections that would not be
3563 stripped by @option{--strip-debug} and leaving the debugging sections
3564 intact. In ELF files, this preserves all the note sections in the
3567 Note - the section headers of the stripped sections are preserved,
3568 including their sizes, but the contents of the section are discarded.
3569 The section headers are preserved so that other tools can match up the
3570 debuginfo file with the real executable, even if that executable has
3571 been relocated to a different address space.
3573 The intention is that this option will be used in conjunction with
3574 @option{--add-gnu-debuglink} to create a two part executable. One a
3575 stripped binary which will occupy less space in RAM and in a
3576 distribution and the second a debugging information file which is only
3577 needed if debugging abilities are required. The suggested procedure
3578 to create these files is as follows:
3581 @item Link the executable as normal. Assuming that it is called
3583 @item Run @code{objcopy --only-keep-debug foo foo.dbg} to
3584 create a file containing the debugging info.
3585 @item Run @code{objcopy --strip-debug foo} to create a
3586 stripped executable.
3587 @item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo}
3588 to add a link to the debugging info into the stripped executable.
3591 Note---the choice of @code{.dbg} as an extension for the debug info
3592 file is arbitrary. Also the @code{--only-keep-debug} step is
3593 optional. You could instead do this:
3596 @item Link the executable as normal.
3597 @item Copy @code{foo} to @code{foo.full}
3598 @item Run @code{strip --strip-debug foo}
3599 @item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
3602 i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the
3603 full executable. It does not have to be a file created by the
3604 @option{--only-keep-debug} switch.
3606 Note---this switch is only intended for use on fully linked files. It
3607 does not make sense to use it on object files where the debugging
3608 information may be incomplete. Besides the gnu_debuglink feature
3609 currently only supports the presence of one filename containing
3610 debugging information, not multiple filenames on a one-per-object-file
3615 Show the version number for @command{strip}.
3619 Verbose output: list all object files modified. In the case of
3620 archives, @samp{strip -v} lists all members of the archive.
3626 @c man begin SEEALSO strip
3627 the Info entries for @file{binutils}.
3631 @node c++filt, addr2line, strip, Top
3635 @cindex demangling C++ symbols
3637 @c man title cxxfilt demangle C++ and Java symbols
3640 @c man begin SYNOPSIS cxxfilt
3641 c++filt [@option{-_}|@option{--strip-underscore}]
3642 [@option{-n}|@option{--no-strip-underscore}]
3643 [@option{-p}|@option{--no-params}]
3644 [@option{-t}|@option{--types}]
3645 [@option{-i}|@option{--no-verbose}]
3646 [@option{-r}|@option{--no-recurse-limit}]
3647 [@option{-R}|@option{--recurse-limit}]
3648 [@option{-s} @var{format}|@option{--format=}@var{format}]
3649 [@option{--help}] [@option{--version}] [@var{symbol}@dots{}]
3653 @c man begin DESCRIPTION cxxfilt
3656 The C++ and Java languages provide function overloading, which means
3657 that you can write many functions with the same name, providing that
3658 each function takes parameters of different types. In order to be
3659 able to distinguish these similarly named functions C++ and Java
3660 encode them into a low-level assembler name which uniquely identifies
3661 each different version. This process is known as @dfn{mangling}. The
3663 @footnote{MS-DOS does not allow @kbd{+} characters in file names, so on
3664 MS-DOS this program is named @command{CXXFILT}.}
3665 program does the inverse mapping: it decodes (@dfn{demangles}) low-level
3666 names into user-level names so that they can be read.
3668 Every alphanumeric word (consisting of letters, digits, underscores,
3669 dollars, or periods) seen in the input is a potential mangled name.
3670 If the name decodes into a C++ name, the C++ name replaces the
3671 low-level name in the output, otherwise the original word is output.
3672 In this way you can pass an entire assembler source file, containing
3673 mangled names, through @command{c++filt} and see the same source file
3674 containing demangled names.
3676 You can also use @command{c++filt} to decipher individual symbols by
3677 passing them on the command line:
3680 c++filt @var{symbol}
3683 If no @var{symbol} arguments are given, @command{c++filt} reads symbol
3684 names from the standard input instead. All the results are printed on
3685 the standard output. The difference between reading names from the
3686 command line versus reading names from the standard input is that
3687 command-line arguments are expected to be just mangled names and no
3688 checking is performed to separate them from surrounding text. Thus
3695 will work and demangle the name to ``f()'' whereas:
3701 will not work. (Note the extra comma at the end of the mangled
3702 name which makes it invalid). This command however will work:
3705 echo _Z1fv, | c++filt -n
3708 and will display ``f(),'', i.e., the demangled name followed by a
3709 trailing comma. This behaviour is because when the names are read
3710 from the standard input it is expected that they might be part of an
3711 assembler source file where there might be extra, extraneous
3712 characters trailing after a mangled name. For example:
3715 .type _Z1fv, @@function
3720 @c man begin OPTIONS cxxfilt
3724 @itemx --strip-underscore
3725 On some systems, both the C and C++ compilers put an underscore in front
3726 of every name. For example, the C name @code{foo} gets the low-level
3727 name @code{_foo}. This option removes the initial underscore. Whether
3728 @command{c++filt} removes the underscore by default is target dependent.
3731 @itemx --no-strip-underscore
3732 Do not remove the initial underscore.
3736 When demangling the name of a function, do not display the types of
3737 the function's parameters.
3741 Attempt to demangle types as well as function names. This is disabled
3742 by default since mangled types are normally only used internally in
3743 the compiler, and they can be confused with non-mangled names. For example,
3744 a function called ``a'' treated as a mangled type name would be
3745 demangled to ``signed char''.
3749 Do not include implementation details (if any) in the demangled
3754 @itemx --recurse-limit
3755 @itemx --no-recurse-limit
3756 @itemx --recursion-limit
3757 @itemx --no-recursion-limit
3758 Enables or disables a limit on the amount of recursion performed
3759 whilst demangling strings. Since the name mangling formats allow for
3760 an infinite level of recursion it is possible to create strings whose
3761 decoding will exhaust the amount of stack space available on the host
3762 machine, triggering a memory fault. The limit tries to prevent this
3763 from happening by restricting recursion to 2048 levels of nesting.
3765 The default is for this limit to be enabled, but disabling it may be
3766 necessary in order to demangle truly complicated names. Note however
3767 that if the recursion limit is disabled then stack exhaustion is
3768 possible and any bug reports about such an event will be rejected.
3770 The @option{-r} option is a synonym for the
3771 @option{--no-recurse-limit} option. The @option{-R} option is a
3772 synonym for the @option{--recurse-limit} option.
3774 @item -s @var{format}
3775 @itemx --format=@var{format}
3776 @command{c++filt} can decode various methods of mangling, used by
3777 different compilers. The argument to this option selects which
3782 Automatic selection based on executable (the default method)
3784 the one used by the @sc{gnu} C++ compiler (g++)
3786 the one used by the Lucid compiler (lcc)
3788 the one specified by the C++ Annotated Reference Manual
3790 the one used by the HP compiler (aCC)
3792 the one used by the EDG compiler
3794 the one used by the @sc{gnu} C++ compiler (g++) with the V3 ABI.
3796 the one used by the @sc{gnu} Java compiler (gcj)
3798 the one used by the @sc{gnu} Ada compiler (GNAT).
3802 Print a summary of the options to @command{c++filt} and exit.
3805 Print the version number of @command{c++filt} and exit.
3811 @c man begin SEEALSO cxxfilt
3812 the Info entries for @file{binutils}.
3817 @emph{Warning:} @command{c++filt} is a new utility, and the details of its
3818 user interface are subject to change in future releases. In particular,
3819 a command-line option may be required in the future to decode a name
3820 passed as an argument on the command line; in other words,
3823 c++filt @var{symbol}
3827 may in a future release become
3830 c++filt @var{option} @var{symbol}
3838 @cindex address to file name and line number
3840 @c man title addr2line convert addresses into file names and line numbers
3843 @c man begin SYNOPSIS addr2line
3844 addr2line [@option{-a}|@option{--addresses}]
3845 [@option{-b} @var{bfdname}|@option{--target=}@var{bfdname}]
3846 [@option{-C}|@option{--demangle}[=@var{style}]]
3847 [@option{-r}|@option{--no-recurse-limit}]
3848 [@option{-R}|@option{--recurse-limit}]
3849 [@option{-e} @var{filename}|@option{--exe=}@var{filename}]
3850 [@option{-f}|@option{--functions}] [@option{-s}|@option{--basename}]
3851 [@option{-i}|@option{--inlines}]
3852 [@option{-p}|@option{--pretty-print}]
3853 [@option{-j}|@option{--section=}@var{name}]
3854 [@option{-H}|@option{--help}] [@option{-V}|@option{--version}]
3859 @c man begin DESCRIPTION addr2line
3861 @command{addr2line} translates addresses into file names and line numbers.
3862 Given an address in an executable or an offset in a section of a relocatable
3863 object, it uses the debugging information to figure out which file name and
3864 line number are associated with it.
3866 The executable or relocatable object to use is specified with the @option{-e}
3867 option. The default is the file @file{a.out}. The section in the relocatable
3868 object to use is specified with the @option{-j} option.
3870 @command{addr2line} has two modes of operation.
3872 In the first, hexadecimal addresses are specified on the command line,
3873 and @command{addr2line} displays the file name and line number for each
3876 In the second, @command{addr2line} reads hexadecimal addresses from
3877 standard input, and prints the file name and line number for each
3878 address on standard output. In this mode, @command{addr2line} may be used
3879 in a pipe to convert dynamically chosen addresses.
3881 The format of the output is @samp{FILENAME:LINENO}. By default
3882 each input address generates one line of output.
3884 Two options can generate additional lines before each
3885 @samp{FILENAME:LINENO} line (in that order).
3887 If the @option{-a} option is used then a line with the input address
3890 If the @option{-f} option is used, then a line with the
3891 @samp{FUNCTIONNAME} is displayed. This is the name of the function
3892 containing the address.
3894 One option can generate additional lines after the
3895 @samp{FILENAME:LINENO} line.
3897 If the @option{-i} option is used and the code at the given address is
3898 present there because of inlining by the compiler then additional
3899 lines are displayed afterwards. One or two extra lines (if the
3900 @option{-f} option is used) are displayed for each inlined function.
3902 Alternatively if the @option{-p} option is used then each input
3903 address generates a single, long, output line containing the address,
3904 the function name, the file name and the line number. If the
3905 @option{-i} option has also been used then any inlined functions will
3906 be displayed in the same manner, but on separate lines, and prefixed
3907 by the text @samp{(inlined by)}.
3909 If the file name or function name can not be determined,
3910 @command{addr2line} will print two question marks in their place. If the
3911 line number can not be determined, @command{addr2line} will print 0.
3915 @c man begin OPTIONS addr2line
3917 The long and short forms of options, shown here as alternatives, are
3923 Display the address before the function name, file and line number
3924 information. The address is printed with a @samp{0x} prefix to easily
3927 @item -b @var{bfdname}
3928 @itemx --target=@var{bfdname}
3929 @cindex object code format
3930 Specify that the object-code format for the object files is
3934 @itemx --demangle[=@var{style}]
3935 @cindex demangling in objdump
3936 Decode (@dfn{demangle}) low-level symbol names into user-level names.
3937 Besides removing any initial underscore prepended by the system, this
3938 makes C++ function names readable. Different compilers have different
3939 mangling styles. The optional demangling style argument can be used to
3940 choose an appropriate demangling style for your compiler. @xref{c++filt},
3941 for more information on demangling.
3943 @item -e @var{filename}
3944 @itemx --exe=@var{filename}
3945 Specify the name of the executable for which addresses should be
3946 translated. The default file is @file{a.out}.
3950 Display function names as well as file and line number information.
3954 Display only the base of each file name.
3958 If the address belongs to a function that was inlined, the source
3959 information for all enclosing scopes back to the first non-inlined
3960 function will also be printed. For example, if @code{main} inlines
3961 @code{callee1} which inlines @code{callee2}, and address is from
3962 @code{callee2}, the source information for @code{callee1} and @code{main}
3963 will also be printed.
3967 Read offsets relative to the specified section instead of absolute addresses.
3970 @itemx --pretty-print
3971 Make the output more human friendly: each location are printed on one line.
3972 If option @option{-i} is specified, lines for all enclosing scopes are
3973 prefixed with @samp{(inlined by)}.
3977 @itemx --recurse-limit
3978 @itemx --no-recurse-limit
3979 @itemx --recursion-limit
3980 @itemx --no-recursion-limit
3981 Enables or disables a limit on the amount of recursion performed
3982 whilst demangling strings. Since the name mangling formats allow for
3983 an infinite level of recursion it is possible to create strings whose
3984 decoding will exhaust the amount of stack space available on the host
3985 machine, triggering a memory fault. The limit tries to prevent this
3986 from happening by restricting recursion to 2048 levels of nesting.
3988 The default is for this limit to be enabled, but disabling it may be
3989 necessary in order to demangle truly complicated names. Note however
3990 that if the recursion limit is disabled then stack exhaustion is
3991 possible and any bug reports about such an event will be rejected.
3993 The @option{-r} option is a synonym for the
3994 @option{--no-recurse-limit} option. The @option{-R} option is a
3995 synonym for the @option{--recurse-limit} option.
3997 Note this option is only effective if the @option{-C} or
3998 @option{--demangle} option has been enabled.
4005 @c man begin SEEALSO addr2line
4006 Info entries for @file{binutils}.
4013 @command{windmc} may be used to generator Windows message resources.
4016 @emph{Warning:} @command{windmc} is not always built as part of the binary
4017 utilities, since it is only useful for Windows targets.
4020 @c man title windmc generates Windows message resources
4023 @c man begin SYNOPSIS windmc
4024 windmc [options] input-file
4028 @c man begin DESCRIPTION windmc
4030 @command{windmc} reads message definitions from an input file (.mc) and
4031 translate them into a set of output files. The output files may be of
4036 A C header file containing the message definitions.
4039 A resource file compilable by the @command{windres} tool.
4042 One or more binary files containing the resource data for a specific
4046 A C include file that maps message id's to their symbolic name.
4049 The exact description of these different formats is available in
4050 documentation from Microsoft.
4052 When @command{windmc} converts from the @code{mc} format to the @code{bin}
4053 format, @code{rc}, @code{h}, and optional @code{dbg} it is acting like the
4054 Windows Message Compiler.
4058 @c man begin OPTIONS windmc
4063 Specifies that the input file specified is ASCII. This is the default
4068 Specifies that messages in the output @code{bin} files should be in ASCII
4073 Specifies that @code{bin} filenames should have to be prefixed by the
4074 basename of the source file.
4078 Sets the customer bit in all message id's.
4080 @item -C @var{codepage}
4081 @itemx --codepage_in @var{codepage}
4082 Sets the default codepage to be used to convert input file to UTF16. The
4083 default is ocdepage 1252.
4086 @itemx --decimal_values
4087 Outputs the constants in the header file in decimal. Default is using
4091 @itemx --extension @var{ext}
4092 The extension for the header file. The default is .h extension.
4094 @item -F @var{target}
4095 @itemx --target @var{target}
4096 Specify the BFD format to use for a bin file as output. This
4097 is a BFD target name; you can use the @option{--help} option to see a list
4098 of supported targets. Normally @command{windmc} will use the default
4099 format, which is the first one listed by the @option{--help} option.
4101 @ref{Target Selection}.
4105 @itemx --headerdir @var{path}
4106 The target directory of the generated header file. The default is the
4111 Displays a list of command-line options and then exits.
4113 @item -m @var{characters}
4114 @itemx --maxlength @var{characters}
4115 Instructs @command{windmc} to generate a warning if the length
4116 of any message exceeds the number specified.
4119 @itemx --nullterminate
4120 Terminate message text in @code{bin} files by zero. By default they are
4121 terminated by CR/LF.
4124 @itemx --hresult_use
4125 Not yet implemented. Instructs @code{windmc} to generate an OLE2 header
4126 file, using HRESULT definitions. Status codes are used if the flag is not
4129 @item -O @var{codepage}
4130 @itemx --codepage_out @var{codepage}
4131 Sets the default codepage to be used to output text files. The default
4135 @itemx --rcdir @var{path}
4136 The target directory for the generated @code{rc} script and the generated
4137 @code{bin} files that the resource compiler script includes. The default
4138 is the current directory.
4142 Specifies that the input file is UTF16.
4145 @itemx --unicode_out
4146 Specifies that messages in the output @code{bin} file should be in UTF16
4147 format. This is the default behaviour.
4151 Enable verbose mode.
4155 Prints the version number for @command{windmc}.
4158 @itemx --xdgb @var{path}
4159 The path of the @code{dbg} C include file that maps message id's to the
4160 symbolic name. No such file is generated without specifying the switch.
4166 @c man begin SEEALSO windmc
4167 the Info entries for @file{binutils}.
4174 @command{windres} may be used to manipulate Windows resources.
4177 @emph{Warning:} @command{windres} is not always built as part of the binary
4178 utilities, since it is only useful for Windows targets.
4181 @c man title windres manipulate Windows resources
4184 @c man begin SYNOPSIS windres
4185 windres [options] [input-file] [output-file]
4189 @c man begin DESCRIPTION windres
4191 @command{windres} reads resources from an input file and copies them into
4192 an output file. Either file may be in one of three formats:
4196 A text format read by the Resource Compiler.
4199 A binary format generated by the Resource Compiler.
4202 A COFF object or executable.
4205 The exact description of these different formats is available in
4206 documentation from Microsoft.
4208 When @command{windres} converts from the @code{rc} format to the @code{res}
4209 format, it is acting like the Windows Resource Compiler. When
4210 @command{windres} converts from the @code{res} format to the @code{coff}
4211 format, it is acting like the Windows @code{CVTRES} program.
4213 When @command{windres} generates an @code{rc} file, the output is similar
4214 but not identical to the format expected for the input. When an input
4215 @code{rc} file refers to an external filename, an output @code{rc} file
4216 will instead include the file contents.
4218 If the input or output format is not specified, @command{windres} will
4219 guess based on the file name, or, for the input file, the file contents.
4220 A file with an extension of @file{.rc} will be treated as an @code{rc}
4221 file, a file with an extension of @file{.res} will be treated as a
4222 @code{res} file, and a file with an extension of @file{.o} or
4223 @file{.exe} will be treated as a @code{coff} file.
4225 If no output file is specified, @command{windres} will print the resources
4226 in @code{rc} format to standard output.
4228 The normal use is for you to write an @code{rc} file, use @command{windres}
4229 to convert it to a COFF object file, and then link the COFF file into
4230 your application. This will make the resources described in the
4231 @code{rc} file available to Windows.
4235 @c man begin OPTIONS windres
4238 @item -i @var{filename}
4239 @itemx --input @var{filename}
4240 The name of the input file. If this option is not used, then
4241 @command{windres} will use the first non-option argument as the input file
4242 name. If there are no non-option arguments, then @command{windres} will
4243 read from standard input. @command{windres} can not read a COFF file from
4246 @item -o @var{filename}
4247 @itemx --output @var{filename}
4248 The name of the output file. If this option is not used, then
4249 @command{windres} will use the first non-option argument, after any used
4250 for the input file name, as the output file name. If there is no
4251 non-option argument, then @command{windres} will write to standard output.
4252 @command{windres} can not write a COFF file to standard output. Note,
4253 for compatibility with @command{rc} the option @option{-fo} is also
4254 accepted, but its use is not recommended.
4256 @item -J @var{format}
4257 @itemx --input-format @var{format}
4258 The input format to read. @var{format} may be @samp{res}, @samp{rc}, or
4259 @samp{coff}. If no input format is specified, @command{windres} will
4260 guess, as described above.
4262 @item -O @var{format}
4263 @itemx --output-format @var{format}
4264 The output format to generate. @var{format} may be @samp{res},
4265 @samp{rc}, or @samp{coff}. If no output format is specified,
4266 @command{windres} will guess, as described above.
4268 @item -F @var{target}
4269 @itemx --target @var{target}
4270 Specify the BFD format to use for a COFF file as input or output. This
4271 is a BFD target name; you can use the @option{--help} option to see a list
4272 of supported targets. Normally @command{windres} will use the default
4273 format, which is the first one listed by the @option{--help} option.
4275 @ref{Target Selection}.
4278 @item --preprocessor @var{program}
4279 When @command{windres} reads an @code{rc} file, it runs it through the C
4280 preprocessor first. This option may be used to specify the preprocessor
4281 to use, including any leading arguments. The default preprocessor
4282 argument is @code{gcc -E -xc-header -DRC_INVOKED}.
4284 @item --preprocessor-arg @var{option}
4285 When @command{windres} reads an @code{rc} file, it runs it through
4286 the C preprocessor first. This option may be used to specify additional
4287 text to be passed to preprocessor on its command line.
4288 This option can be used multiple times to add multiple options to the
4289 preprocessor command line.
4291 @item -I @var{directory}
4292 @itemx --include-dir @var{directory}
4293 Specify an include directory to use when reading an @code{rc} file.
4294 @command{windres} will pass this to the preprocessor as an @option{-I}
4295 option. @command{windres} will also search this directory when looking for
4296 files named in the @code{rc} file. If the argument passed to this command
4297 matches any of the supported @var{formats} (as described in the @option{-J}
4298 option), it will issue a deprecation warning, and behave just like the
4299 @option{-J} option. New programs should not use this behaviour. If a
4300 directory happens to match a @var{format}, simple prefix it with @samp{./}
4301 to disable the backward compatibility.
4303 @item -D @var{target}
4304 @itemx --define @var{sym}[=@var{val}]
4305 Specify a @option{-D} option to pass to the preprocessor when reading an
4308 @item -U @var{target}
4309 @itemx --undefine @var{sym}
4310 Specify a @option{-U} option to pass to the preprocessor when reading an
4314 Ignored for compatibility with rc.
4317 Enable verbose mode. This tells you what the preprocessor is if you
4321 @item --codepage @var{val}
4322 Specify the default codepage to use when reading an @code{rc} file.
4323 @var{val} should be a hexadecimal prefixed by @samp{0x} or decimal
4324 codepage code. The valid range is from zero up to 0xffff, but the
4325 validity of the codepage is host and configuration dependent.
4328 @item --language @var{val}
4329 Specify the default language to use when reading an @code{rc} file.
4330 @var{val} should be a hexadecimal language code. The low eight bits are
4331 the language, and the high eight bits are the sublanguage.
4333 @item --use-temp-file
4334 Use a temporary file to instead of using popen to read the output of
4335 the preprocessor. Use this option if the popen implementation is buggy
4336 on the host (eg., certain non-English language versions of Windows 95 and
4337 Windows 98 are known to have buggy popen where the output will instead
4340 @item --no-use-temp-file
4341 Use popen, not a temporary file, to read the output of the preprocessor.
4342 This is the default behaviour.
4346 Prints a usage summary.
4350 Prints the version number for @command{windres}.
4353 If @command{windres} is compiled with @code{YYDEBUG} defined as @code{1},
4354 this will turn on parser debugging.
4360 @c man begin SEEALSO windres
4361 the Info entries for @file{binutils}.
4370 @command{dlltool} is used to create the files needed to create dynamic
4371 link libraries (DLLs) on systems which understand PE format image
4372 files such as Windows. A DLL contains an export table which contains
4373 information that the runtime loader needs to resolve references from a
4374 referencing program.
4376 The export table is generated by this program by reading in a
4377 @file{.def} file or scanning the @file{.a} and @file{.o} files which
4378 will be in the DLL. A @file{.o} file can contain information in
4379 special @samp{.drectve} sections with export information.
4382 @emph{Note:} @command{dlltool} is not always built as part of the
4383 binary utilities, since it is only useful for those targets which
4387 @c man title dlltool create files needed to build and use DLLs
4390 @c man begin SYNOPSIS dlltool
4391 dlltool [@option{-d}|@option{--input-def} @var{def-file-name}]
4392 [@option{-b}|@option{--base-file} @var{base-file-name}]
4393 [@option{-e}|@option{--output-exp} @var{exports-file-name}]
4394 [@option{-z}|@option{--output-def} @var{def-file-name}]
4395 [@option{-l}|@option{--output-lib} @var{library-file-name}]
4396 [@option{-y}|@option{--output-delaylib} @var{library-file-name}]
4397 [@option{--export-all-symbols}] [@option{--no-export-all-symbols}]
4398 [@option{--exclude-symbols} @var{list}]
4399 [@option{--no-default-excludes}]
4400 [@option{-S}|@option{--as} @var{path-to-assembler}] [@option{-f}|@option{--as-flags} @var{options}]
4401 [@option{-D}|@option{--dllname} @var{name}] [@option{-m}|@option{--machine} @var{machine}]
4402 [@option{-a}|@option{--add-indirect}]
4403 [@option{-U}|@option{--add-underscore}] [@option{--add-stdcall-underscore}]
4404 [@option{-k}|@option{--kill-at}] [@option{-A}|@option{--add-stdcall-alias}]
4405 [@option{-p}|@option{--ext-prefix-alias} @var{prefix}]
4406 [@option{-x}|@option{--no-idata4}] [@option{-c}|@option{--no-idata5}]
4407 [@option{--use-nul-prefixed-import-tables}]
4408 [@option{-I}|@option{--identify} @var{library-file-name}] [@option{--identify-strict}]
4409 [@option{-i}|@option{--interwork}]
4410 [@option{-n}|@option{--nodelete}] [@option{-t}|@option{--temp-prefix} @var{prefix}]
4411 [@option{-v}|@option{--verbose}]
4412 [@option{-h}|@option{--help}] [@option{-V}|@option{--version}]
4413 [@option{--no-leading-underscore}] [@option{--leading-underscore}]
4414 [object-file @dots{}]
4418 @c man begin DESCRIPTION dlltool
4420 @command{dlltool} reads its inputs, which can come from the @option{-d} and
4421 @option{-b} options as well as object files specified on the command
4422 line. It then processes these inputs and if the @option{-e} option has
4423 been specified it creates a exports file. If the @option{-l} option
4424 has been specified it creates a library file and if the @option{-z} option
4425 has been specified it creates a def file. Any or all of the @option{-e},
4426 @option{-l} and @option{-z} options can be present in one invocation of
4429 When creating a DLL, along with the source for the DLL, it is necessary
4430 to have three other files. @command{dlltool} can help with the creation of
4433 The first file is a @file{.def} file which specifies which functions are
4434 exported from the DLL, which functions the DLL imports, and so on. This
4435 is a text file and can be created by hand, or @command{dlltool} can be used
4436 to create it using the @option{-z} option. In this case @command{dlltool}
4437 will scan the object files specified on its command line looking for
4438 those functions which have been specially marked as being exported and
4439 put entries for them in the @file{.def} file it creates.
4441 In order to mark a function as being exported from a DLL, it needs to
4442 have an @option{-export:<name_of_function>} entry in the @samp{.drectve}
4443 section of the object file. This can be done in C by using the
4447 asm (".section .drectve");
4448 asm (".ascii \"-export:my_func\"");
4450 int my_func (void) @{ @dots{} @}
4453 The second file needed for DLL creation is an exports file. This file
4454 is linked with the object files that make up the body of the DLL and it
4455 handles the interface between the DLL and the outside world. This is a
4456 binary file and it can be created by giving the @option{-e} option to
4457 @command{dlltool} when it is creating or reading in a @file{.def} file.
4459 The third file needed for DLL creation is the library file that programs
4460 will link with in order to access the functions in the DLL (an `import
4461 library'). This file can be created by giving the @option{-l} option to
4462 dlltool when it is creating or reading in a @file{.def} file.
4464 If the @option{-y} option is specified, dlltool generates a delay-import
4465 library that can be used instead of the normal import library to allow
4466 a program to link to the dll only as soon as an imported function is
4467 called for the first time. The resulting executable will need to be
4468 linked to the static delayimp library containing __delayLoadHelper2(),
4469 which in turn will import LoadLibraryA and GetProcAddress from kernel32.
4471 @command{dlltool} builds the library file by hand, but it builds the
4472 exports file by creating temporary files containing assembler statements
4473 and then assembling these. The @option{-S} command-line option can be
4474 used to specify the path to the assembler that dlltool will use,
4475 and the @option{-f} option can be used to pass specific flags to that
4476 assembler. The @option{-n} can be used to prevent dlltool from deleting
4477 these temporary assembler files when it is done, and if @option{-n} is
4478 specified twice then this will prevent dlltool from deleting the
4479 temporary object files it used to build the library.
4481 Here is an example of creating a DLL from a source file @samp{dll.c} and
4482 also creating a program (from an object file called @samp{program.o})
4487 dlltool -e exports.o -l dll.lib dll.o
4488 gcc dll.o exports.o -o dll.dll
4489 gcc program.o dll.lib -o program
4493 @command{dlltool} may also be used to query an existing import library
4494 to determine the name of the DLL to which it is associated. See the
4495 description of the @option{-I} or @option{--identify} option.
4499 @c man begin OPTIONS dlltool
4501 The command-line options have the following meanings:
4505 @item -d @var{filename}
4506 @itemx --input-def @var{filename}
4507 @cindex input .def file
4508 Specifies the name of a @file{.def} file to be read in and processed.
4510 @item -b @var{filename}
4511 @itemx --base-file @var{filename}
4513 Specifies the name of a base file to be read in and processed. The
4514 contents of this file will be added to the relocation section in the
4515 exports file generated by dlltool.
4517 @item -e @var{filename}
4518 @itemx --output-exp @var{filename}
4519 Specifies the name of the export file to be created by dlltool.
4521 @item -z @var{filename}
4522 @itemx --output-def @var{filename}
4523 Specifies the name of the @file{.def} file to be created by dlltool.
4525 @item -l @var{filename}
4526 @itemx --output-lib @var{filename}
4527 Specifies the name of the library file to be created by dlltool.
4529 @item -y @var{filename}
4530 @itemx --output-delaylib @var{filename}
4531 Specifies the name of the delay-import library file to be created by dlltool.
4533 @item --export-all-symbols
4534 Treat all global and weak defined symbols found in the input object
4535 files as symbols to be exported. There is a small list of symbols which
4536 are not exported by default; see the @option{--no-default-excludes}
4537 option. You may add to the list of symbols to not export by using the
4538 @option{--exclude-symbols} option.
4540 @item --no-export-all-symbols
4541 Only export symbols explicitly listed in an input @file{.def} file or in
4542 @samp{.drectve} sections in the input object files. This is the default
4543 behaviour. The @samp{.drectve} sections are created by @samp{dllexport}
4544 attributes in the source code.
4546 @item --exclude-symbols @var{list}
4547 Do not export the symbols in @var{list}. This is a list of symbol names
4548 separated by comma or colon characters. The symbol names should not
4549 contain a leading underscore. This is only meaningful when
4550 @option{--export-all-symbols} is used.
4552 @item --no-default-excludes
4553 When @option{--export-all-symbols} is used, it will by default avoid
4554 exporting certain special symbols. The current list of symbols to avoid
4555 exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0},
4556 @samp{impure_ptr}. You may use the @option{--no-default-excludes} option
4557 to go ahead and export these special symbols. This is only meaningful
4558 when @option{--export-all-symbols} is used.
4561 @itemx --as @var{path}
4562 Specifies the path, including the filename, of the assembler to be used
4563 to create the exports file.
4565 @item -f @var{options}
4566 @itemx --as-flags @var{options}
4567 Specifies any specific command-line options to be passed to the
4568 assembler when building the exports file. This option will work even if
4569 the @option{-S} option is not used. This option only takes one argument,
4570 and if it occurs more than once on the command line, then later
4571 occurrences will override earlier occurrences. So if it is necessary to
4572 pass multiple options to the assembler they should be enclosed in
4576 @itemx --dll-name @var{name}
4577 Specifies the name to be stored in the @file{.def} file as the name of
4578 the DLL when the @option{-e} option is used. If this option is not
4579 present, then the filename given to the @option{-e} option will be
4580 used as the name of the DLL.
4582 @item -m @var{machine}
4583 @itemx -machine @var{machine}
4584 Specifies the type of machine for which the library file should be
4585 built. @command{dlltool} has a built in default type, depending upon how
4586 it was created, but this option can be used to override that. This is
4587 normally only useful when creating DLLs for an ARM processor, when the
4588 contents of the DLL are actually encode using Thumb instructions.
4591 @itemx --add-indirect
4592 Specifies that when @command{dlltool} is creating the exports file it
4593 should add a section which allows the exported functions to be
4594 referenced without using the import library. Whatever the hell that
4598 @itemx --add-underscore
4599 Specifies that when @command{dlltool} is creating the exports file it
4600 should prepend an underscore to the names of @emph{all} exported symbols.
4602 @item --no-leading-underscore
4603 @item --leading-underscore
4604 Specifies whether standard symbol should be forced to be prefixed, or
4607 @item --add-stdcall-underscore
4608 Specifies that when @command{dlltool} is creating the exports file it
4609 should prepend an underscore to the names of exported @emph{stdcall}
4610 functions. Variable names and non-stdcall function names are not modified.
4611 This option is useful when creating GNU-compatible import libs for third
4612 party DLLs that were built with MS-Windows tools.
4616 Specifies that @samp{@@<number>} suffixes should be omitted from the names
4617 of stdcall functions that will be imported from the DLL. This is
4618 useful when creating an import library for a DLL which exports stdcall
4619 functions but without the usual @samp{@@<number>} symbol name suffix.
4621 This does not change the naming of symbols provided by the import library
4622 to programs linked against it, but only the entries in the import table
4623 (ie the .idata section).
4626 @itemx --add-stdcall-alias
4627 Specifies that when @command{dlltool} is creating the exports file it
4628 should add aliases for stdcall symbols without @samp{@@ <number>}
4629 in addition to the symbols with @samp{@@ <number>}.
4632 @itemx --ext-prefix-alias @var{prefix}
4633 Causes @command{dlltool} to create external aliases for all DLL
4634 imports with the specified prefix. The aliases are created for both
4635 external and import symbols with no leading underscore.
4639 Specifies that when @command{dlltool} is creating the exports and library
4640 files it should omit the @code{.idata4} section. This is for compatibility
4641 with certain operating systems.
4643 @item --use-nul-prefixed-import-tables
4644 Specifies that when @command{dlltool} is creating the exports and library
4645 files it should prefix the @code{.idata4} and @code{.idata5} by zero an
4646 element. This emulates old gnu import library generation of
4647 @code{dlltool}. By default this option is turned off.
4651 Specifies that when @command{dlltool} is creating the exports and library
4652 files it should omit the @code{.idata5} section. This is for compatibility
4653 with certain operating systems.
4655 @item -I @var{filename}
4656 @itemx --identify @var{filename}
4657 Specifies that @command{dlltool} should inspect the import library
4658 indicated by @var{filename} and report, on @code{stdout}, the name(s)
4659 of the associated DLL(s). This can be performed in addition to any
4660 other operations indicated by the other options and arguments.
4661 @command{dlltool} fails if the import library does not exist or is not
4662 actually an import library. See also @option{--identify-strict}.
4664 @item --identify-strict
4665 Modifies the behavior of the @option{--identify} option, such
4666 that an error is reported if @var{filename} is associated with
4671 Specifies that @command{dlltool} should mark the objects in the library
4672 file and exports file that it produces as supporting interworking
4673 between ARM and Thumb code.
4677 Makes @command{dlltool} preserve the temporary assembler files it used to
4678 create the exports file. If this option is repeated then dlltool will
4679 also preserve the temporary object files it uses to create the library
4682 @item -t @var{prefix}
4683 @itemx --temp-prefix @var{prefix}
4684 Makes @command{dlltool} use @var{prefix} when constructing the names of
4685 temporary assembler and object files. By default, the temp file prefix
4686 is generated from the pid.
4690 Make dlltool describe what it is doing.
4694 Displays a list of command-line options and then exits.
4698 Displays dlltool's version number and then exits.
4705 * def file format:: The format of the dlltool @file{.def} file
4708 @node def file format
4709 @section The format of the @command{dlltool} @file{.def} file
4711 A @file{.def} file contains any number of the following commands:
4715 @item @code{NAME} @var{name} @code{[ ,} @var{base} @code{]}
4716 The result is going to be named @var{name}@code{.exe}.
4718 @item @code{LIBRARY} @var{name} @code{[ ,} @var{base} @code{]}
4719 The result is going to be named @var{name}@code{.dll}.
4720 Note: If you want to use LIBRARY as name then you need to quote. Otherwise
4721 this will fail due a necessary hack for libtool (see PR binutils/13710 for more
4724 @item @code{EXPORTS ( ( (} @var{name1} @code{[ = } @var{name2} @code{] ) | ( } @var{name1} @code{=} @var{module-name} @code{.} @var{external-name} @code{) ) [ == } @var{its_name} @code{]}
4725 @item @code{[} @var{integer} @code{] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *}
4726 Declares @var{name1} as an exported symbol from the DLL, with optional
4727 ordinal number @var{integer}, or declares @var{name1} as an alias
4728 (forward) of the function @var{external-name} in the DLL.
4729 If @var{its_name} is specified, this name is used as string in export table.
4731 Note: The @code{EXPORTS} has to be the last command in .def file, as keywords
4732 are treated - beside @code{LIBRARY} - as simple name-identifiers.
4733 If you want to use LIBRARY as name then you need to quote it.
4735 @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{) [ == ) @var{its_name} @code{]} *}
4736 Declares that @var{external-name} or the exported function whose
4737 ordinal number is @var{integer} is to be imported from the file
4738 @var{module-name}. If @var{internal-name} is specified then this is
4739 the name that the imported function will be referred to in the body of
4741 If @var{its_name} is specified, this name is used as string in import table.
4742 Note: The @code{IMPORTS} has to be the last command in .def file, as keywords
4743 are treated - beside @code{LIBRARY} - as simple name-identifiers.
4744 If you want to use LIBRARY as name then you need to quote it.
4746 @item @code{DESCRIPTION} @var{string}
4747 Puts @var{string} into the output @file{.exp} file in the
4748 @code{.rdata} section.
4750 @item @code{STACKSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
4751 @item @code{HEAPSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]}
4752 Generates @code{--stack} or @code{--heap}
4753 @var{number-reserve},@var{number-commit} in the output @code{.drectve}
4754 section. The linker will see this and act upon it.
4756 @item @code{CODE} @var{attr} @code{+}
4757 @item @code{DATA} @var{attr} @code{+}
4758 @item @code{SECTIONS (} @var{section-name} @var{attr}@code{ + ) *}
4759 Generates @code{--attr} @var{section-name} @var{attr} in the output
4760 @code{.drectve} section, where @var{attr} is one of @code{READ},
4761 @code{WRITE}, @code{EXECUTE} or @code{SHARED}. The linker will see
4762 this and act upon it.
4767 @c man begin SEEALSO dlltool
4768 The Info pages for @file{binutils}.
4775 @cindex ELF file information
4778 @c man title readelf display information about ELF files
4781 @c man begin SYNOPSIS readelf
4782 readelf [@option{-a}|@option{--all}]
4783 [@option{-h}|@option{--file-header}]
4784 [@option{-l}|@option{--program-headers}|@option{--segments}]
4785 [@option{-S}|@option{--section-headers}|@option{--sections}]
4786 [@option{-g}|@option{--section-groups}]
4787 [@option{-t}|@option{--section-details}]
4788 [@option{-e}|@option{--headers}]
4789 [@option{-s}|@option{--syms}|@option{--symbols}]
4790 [@option{--dyn-syms}|@option{--lto-syms}]
4791 [@option{--demangle@var{=style}}|@option{--no-demangle}]
4793 [@option{--recurse-limit}|@option{--no-recurse-limit}]
4794 [@option{-n}|@option{--notes}]
4795 [@option{-r}|@option{--relocs}]
4796 [@option{-u}|@option{--unwind}]
4797 [@option{-d}|@option{--dynamic}]
4798 [@option{-V}|@option{--version-info}]
4799 [@option{-A}|@option{--arch-specific}]
4800 [@option{-D}|@option{--use-dynamic}]
4801 [@option{-L}|@option{--lint}|@option{--enable-checks}]
4802 [@option{-x} <number or name>|@option{--hex-dump=}<number or name>]
4803 [@option{-p} <number or name>|@option{--string-dump=}<number or name>]
4804 [@option{-R} <number or name>|@option{--relocated-dump=}<number or name>]
4805 [@option{-z}|@option{--decompress}]
4806 [@option{-c}|@option{--archive-index}]
4807 [@option{-w[lLiaprmfFsoORtUuTgAck]}|
4808 @option{--debug-dump}[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links]]
4809 [@option{-wK}|@option{--debug-dump=follow-links}]
4810 [@option{-wN}|@option{--debug-dump=no-follow-links}]
4811 [@option{-P}|@option{--process-links}]
4812 [@option{--dwarf-depth=@var{n}}]
4813 [@option{--dwarf-start=@var{n}}]
4814 [@option{--ctf=}@var{section}]
4815 [@option{--ctf-parent=}@var{section}]
4816 [@option{--ctf-symbols=}@var{section}]
4817 [@option{--ctf-strings=}@var{section}]
4818 [@option{-I}|@option{--histogram}]
4819 [@option{-v}|@option{--version}]
4820 [@option{-W}|@option{--wide}]
4821 [@option{-T}|@option{--silent-truncation}]
4822 [@option{-H}|@option{--help}]
4823 @var{elffile}@dots{}
4827 @c man begin DESCRIPTION readelf
4829 @command{readelf} displays information about one or more ELF format object
4830 files. The options control what particular information to display.
4832 @var{elffile}@dots{} are the object files to be examined. 32-bit and
4833 64-bit ELF files are supported, as are archives containing ELF files.
4835 This program performs a similar function to @command{objdump} but it
4836 goes into more detail and it exists independently of the @sc{bfd}
4837 library, so if there is a bug in @sc{bfd} then readelf will not be
4842 @c man begin OPTIONS readelf
4844 The long and short forms of options, shown here as alternatives, are
4845 equivalent. At least one option besides @samp{-v} or @samp{-H} must be
4851 Equivalent to specifying @option{--file-header},
4852 @option{--program-headers}, @option{--sections}, @option{--symbols},
4853 @option{--relocs}, @option{--dynamic}, @option{--notes},
4854 @option{--version-info}, @option{--arch-specific}, @option{--unwind},
4855 @option{--section-groups} and @option{--histogram}.
4857 Note - this option does not enable @option{--use-dynamic} itself, so
4858 if that option is not present on the command line then dynamic symbols
4859 and dynamic relocs will not be displayed.
4862 @itemx --file-header
4863 @cindex ELF file header information
4864 Displays the information contained in the ELF header at the start of the
4868 @itemx --program-headers
4870 @cindex ELF program header information
4871 @cindex ELF segment information
4872 Displays the information contained in the file's segment headers, if it
4877 Suppress "no symbols" diagnostic.
4881 @itemx --section-headers
4882 @cindex ELF section information
4883 Displays the information contained in the file's section headers, if it
4887 @itemx --section-groups
4888 @cindex ELF section group information
4889 Displays the information contained in the file's section groups, if it
4893 @itemx --section-details
4894 @cindex ELF section information
4895 Displays the detailed section information. Implies @option{-S}.
4900 @cindex ELF symbol table information
4901 Displays the entries in symbol table section of the file, if it has one.
4902 If a symbol has version information associated with it then this is
4903 displayed as well. The version string is displayed as a suffix to the
4904 symbol name, preceded by an @@ character. For example
4905 @samp{foo@@VER_1}. If the version is the default version to be used
4906 when resolving unversioned references to the symbol then it is
4907 displayed as a suffix preceded by two @@ characters. For example
4908 @samp{foo@@@@VER_2}.
4911 @cindex ELF dynamic symbol table information
4912 Displays the entries in dynamic symbol table section of the file, if it
4913 has one. The output format is the same as the format used by the
4914 @option{--syms} option.
4917 @cindex LTO symbol table
4918 Displays the contents of any LTO symbol tables in the file.
4921 @itemx --demangle[=@var{style}]
4922 @cindex demangling in nm
4923 Decode (@dfn{demangle}) low-level symbol names into user-level names.
4924 This makes C++ function names readable. Different compilers have
4925 different mangling styles. The optional demangling style argument can
4926 be used to choose an appropriate demangling style for your
4927 compiler. @xref{c++filt}, for more information on demangling.
4930 Do not demangle low-level symbol names. This is the default.
4932 @item --recurse-limit
4933 @itemx --no-recurse-limit
4934 @itemx --recursion-limit
4935 @itemx --no-recursion-limit
4936 Enables or disables a limit on the amount of recursion performed
4937 whilst demangling strings. Since the name mangling formats allow for
4938 an infinite level of recursion it is possible to create strings whose
4939 decoding will exhaust the amount of stack space available on the host
4940 machine, triggering a memory fault. The limit tries to prevent this
4941 from happening by restricting recursion to 2048 levels of nesting.
4943 The default is for this limit to be enabled, but disabling it may be
4944 necessary in order to demangle truly complicated names. Note however
4945 that if the recursion limit is disabled then stack exhaustion is
4946 possible and any bug reports about such an event will be rejected.
4950 Display all the headers in the file. Equivalent to @option{-h -l -S}.
4955 Displays the contents of the NOTE segments and/or sections, if any.
4959 @cindex ELF reloc information
4960 Displays the contents of the file's relocation section, if it has one.
4964 @cindex unwind information
4965 Displays the contents of the file's unwind section, if it has one. Only
4966 the unwind sections for IA64 ELF files, as well as ARM unwind tables
4967 (@code{.ARM.exidx} / @code{.ARM.extab}) are currently supported. If
4968 support is not yet implemented for your architecture you could try
4969 dumping the contents of the @var{.eh_frames} section using the
4970 @option{--debug-dump=frames} or @option{--debug-dump=frames-interp}
4975 @cindex ELF dynamic section information
4976 Displays the contents of the file's dynamic section, if it has one.
4979 @itemx --version-info
4980 @cindex ELF version sections information
4981 Displays the contents of the version sections in the file, it they
4985 @itemx --arch-specific
4986 Displays architecture-specific information in the file, if there
4990 @itemx --use-dynamic
4991 When displaying symbols, this option makes @command{readelf} use the
4992 symbol hash tables in the file's dynamic section, rather than the
4993 symbol table sections.
4995 When displaying relocations, this option makes @command{readelf}
4996 display the dynamic relocations rather than the static relocations.
5000 @itemx --enable-checks
5001 Displays warning messages about possible problems with the file(s)
5002 being examined. If used on its own then all of the contents of the
5003 file(s) will be examined. If used with one of the dumping options
5004 then the warning messages will only be produced for the things being
5007 @item -x <number or name>
5008 @itemx --hex-dump=<number or name>
5009 Displays the contents of the indicated section as a hexadecimal bytes.
5010 A number identifies a particular section by index in the section table;
5011 any other string identifies all sections with that name in the object file.
5013 @item -R <number or name>
5014 @itemx --relocated-dump=<number or name>
5015 Displays the contents of the indicated section as a hexadecimal
5016 bytes. A number identifies a particular section by index in the
5017 section table; any other string identifies all sections with that name
5018 in the object file. The contents of the section will be relocated
5019 before they are displayed.
5021 @item -p <number or name>
5022 @itemx --string-dump=<number or name>
5023 Displays the contents of the indicated section as printable strings.
5024 A number identifies a particular section by index in the section table;
5025 any other string identifies all sections with that name in the object file.
5029 Requests that the section(s) being dumped by @option{x}, @option{R} or
5030 @option{p} options are decompressed before being displayed. If the
5031 section(s) are not compressed then they are displayed as is.
5034 @itemx --archive-index
5035 @cindex Archive file symbol index information
5036 Displays the file symbol index information contained in the header part
5037 of binary archives. Performs the same function as the @option{t}
5038 command to @command{ar}, but without using the BFD library. @xref{ar}.
5040 @item -w[lLiaprmfFsOoRtUuTgAckK]
5041 @itemx --debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=str-offsets,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]
5042 @include debug.options.texi
5045 @itemx --process-links
5046 Display the contents of non-debug sections found in separate debuginfo
5047 files that are linked to the main file. This option automatically
5048 implies the @option{-wK} option, and only sections requested by other
5049 command line options will be displayed.
5051 @include ctf.options.texi
5052 @item --ctf-symbols=@var{section}
5053 @item --ctf-strings=@var{section}
5054 Specify the name of another section from which the CTF file can inherit
5055 strings and symbols. By default, the @code{.symtab} and its linked
5056 string table are used.
5058 If either of @option{--ctf-symbols} or @option{--ctf-strings} is specified, the
5059 other must be specified as well.
5063 Display a histogram of bucket list lengths when displaying the contents
5064 of the symbol tables.
5068 Display the version number of readelf.
5072 Don't break output lines to fit into 80 columns. By default
5073 @command{readelf} breaks section header and segment listing lines for
5074 64-bit ELF files, so that they fit into 80 columns. This option causes
5075 @command{readelf} to print each section header resp. each segment one a
5076 single line, which is far more readable on terminals wider than 80 columns.
5079 @itemx --silent-truncation
5080 Normally when readelf is displaying a symbol name, and it has to
5081 truncate the name to fit into an 80 column display, it will add a
5082 suffix of @code{[...]} to the name. This command line option
5083 disables this behaviour, allowing 5 more characters of the name to be
5084 displayed and restoring the old behaviour of readelf (prior to release
5089 Display the command-line options understood by @command{readelf}.
5096 @c man begin SEEALSO readelf
5097 objdump(1), and the Info entries for @file{binutils}.
5104 @cindex Update ELF header
5107 @c man title elfedit update ELF header and program property of ELF files
5110 @c man begin SYNOPSIS elfedit
5111 elfedit [@option{--input-mach=}@var{machine}]
5112 [@option{--input-type=}@var{type}]
5113 [@option{--input-osabi=}@var{osabi}]
5114 @option{--output-mach=}@var{machine}
5115 @option{--output-type=}@var{type}
5116 @option{--output-osabi=}@var{osabi}
5117 @option{--enable-x86-feature=}@var{feature}
5118 @option{--disable-x86-feature=}@var{feature}
5119 [@option{-v}|@option{--version}]
5120 [@option{-h}|@option{--help}]
5121 @var{elffile}@dots{}
5125 @c man begin DESCRIPTION elfedit
5127 @command{elfedit} updates the ELF header and program property of ELF
5128 files which have the matching ELF machine and file types. The options
5129 control how and which fields in the ELF header and program property
5132 @var{elffile}@dots{} are the ELF files to be updated. 32-bit and
5133 64-bit ELF files are supported, as are archives containing ELF files.
5136 @c man begin OPTIONS elfedit
5138 The long and short forms of options, shown here as alternatives, are
5139 equivalent. At least one of the @option{--output-mach},
5140 @option{--output-type}, @option{--output-osabi},
5141 @option{--enable-x86-feature} and @option{--disable-x86-feature}
5142 options must be given.
5146 @item --input-mach=@var{machine}
5147 Set the matching input ELF machine type to @var{machine}. If
5148 @option{--input-mach} isn't specified, it will match any ELF
5151 The supported ELF machine types are, @var{i386}, @var{IAMCU}, @var{L1OM},
5152 @var{K1OM} and @var{x86-64}.
5154 @item --output-mach=@var{machine}
5155 Change the ELF machine type in the ELF header to @var{machine}. The
5156 supported ELF machine types are the same as @option{--input-mach}.
5158 @item --input-type=@var{type}
5159 Set the matching input ELF file type to @var{type}. If
5160 @option{--input-type} isn't specified, it will match any ELF file types.
5162 The supported ELF file types are, @var{rel}, @var{exec} and @var{dyn}.
5164 @item --output-type=@var{type}
5165 Change the ELF file type in the ELF header to @var{type}. The
5166 supported ELF types are the same as @option{--input-type}.
5168 @item --input-osabi=@var{osabi}
5169 Set the matching input ELF file OSABI to @var{osabi}. If
5170 @option{--input-osabi} isn't specified, it will match any ELF OSABIs.
5172 The supported ELF OSABIs are, @var{none}, @var{HPUX}, @var{NetBSD},
5173 @var{GNU}, @var{Linux} (alias for @var{GNU}),
5174 @var{Solaris}, @var{AIX}, @var{Irix},
5175 @var{FreeBSD}, @var{TRU64}, @var{Modesto}, @var{OpenBSD}, @var{OpenVMS},
5176 @var{NSK}, @var{AROS} and @var{FenixOS}.
5178 @item --output-osabi=@var{osabi}
5179 Change the ELF OSABI in the ELF header to @var{osabi}. The
5180 supported ELF OSABI are the same as @option{--input-osabi}.
5182 @item --enable-x86-feature=@var{feature}
5183 Set the @var{feature} bit in program property in @var{exec} or @var{dyn}
5184 ELF files with machine types of @var{i386} or @var{x86-64}. The
5185 supported features are, @var{ibt}, @var{shstk}, @var{lam_u48} and
5188 @item --disable-x86-feature=@var{feature}
5189 Clear the @var{feature} bit in program property in @var{exec} or
5190 @var{dyn} ELF files with machine types of @var{i386} or @var{x86-64}.
5191 The supported features are the same as @option{--enable-x86-feature}.
5193 Note: @option{--enable-x86-feature} and @option{--disable-x86-feature}
5194 are available only on hosts with @samp{mmap} support.
5198 Display the version number of @command{elfedit}.
5202 Display the command-line options understood by @command{elfedit}.
5209 @c man begin SEEALSO elfedit
5210 readelf(1), and the Info entries for @file{binutils}.
5214 @node Common Options
5215 @chapter Common Options
5217 The following command-line options are supported by all of the
5218 programs described in this manual.
5220 @c man begin OPTIONS
5222 @include at-file.texi
5226 Display the command-line options supported by the program.
5229 Display the version number of the program.
5231 @c man begin OPTIONS
5235 @node Selecting the Target System
5236 @chapter Selecting the Target System
5238 You can specify two aspects of the target system to the @sc{gnu}
5239 binary file utilities, each in several ways:
5249 In the following summaries, the lists of ways to specify values are in
5250 order of decreasing precedence. The ways listed first override those
5253 The commands to list valid values only list the values for which the
5254 programs you are running were configured. If they were configured with
5255 @option{--enable-targets=all}, the commands list most of the available
5256 values, but a few are left out; not all targets can be configured in at
5257 once because some of them can only be configured @dfn{native} (on hosts
5258 with the same type as the target system).
5261 * Target Selection::
5262 * Architecture Selection::
5265 @node Target Selection
5266 @section Target Selection
5268 A @dfn{target} is an object file format. A given target may be
5269 supported for multiple architectures (@pxref{Architecture Selection}).
5270 A target selection may also have variations for different operating
5271 systems or architectures.
5273 The command to list valid target values is @samp{objdump -i}
5274 (the first column of output contains the relevant information).
5276 Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips},
5277 @samp{a.out-sunos-big}.
5279 You can also specify a target using a configuration triplet. This is
5280 the same sort of name that is passed to @file{configure} to specify a
5281 target. When you use a configuration triplet as an argument, it must be
5282 fully canonicalized. You can see the canonical version of a triplet by
5283 running the shell script @file{config.sub} which is included with the
5286 Some sample configuration triplets are: @samp{m68k-hp-bsd},
5287 @samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}.
5289 @subheading @command{objdump} Target
5295 command-line option: @option{-b} or @option{--target}
5298 environment variable @code{GNUTARGET}
5301 deduced from the input file
5304 @subheading @command{objcopy} and @command{strip} Input Target
5310 command-line options: @option{-I} or @option{--input-target}, or @option{-F} or @option{--target}
5313 environment variable @code{GNUTARGET}
5316 deduced from the input file
5319 @subheading @command{objcopy} and @command{strip} Output Target
5325 command-line options: @option{-O} or @option{--output-target}, or @option{-F} or @option{--target}
5328 the input target (see ``@command{objcopy} and @command{strip} Input Target'' above)
5331 environment variable @code{GNUTARGET}
5334 deduced from the input file
5337 @subheading @command{nm}, @command{size}, and @command{strings} Target
5343 command-line option: @option{--target}
5346 environment variable @code{GNUTARGET}
5349 deduced from the input file
5352 @node Architecture Selection
5353 @section Architecture Selection
5355 An @dfn{architecture} is a type of @sc{cpu} on which an object file is
5356 to run. Its name may contain a colon, separating the name of the
5357 processor family from the name of the particular @sc{cpu}.
5359 The command to list valid architecture values is @samp{objdump -i} (the
5360 second column contains the relevant information).
5362 Sample values: @samp{m68k:68020}, @samp{mips:3000}, @samp{sparc}.
5364 @subheading @command{objdump} Architecture
5370 command-line option: @option{-m} or @option{--architecture}
5373 deduced from the input file
5376 @subheading @command{objcopy}, @command{nm}, @command{size}, @command{strings} Architecture
5382 deduced from the input file
5387 @cindex separate debug files
5389 debuginfod is a web service that indexes ELF/DWARF debugging resources
5390 by build-id and serves them over HTTP.
5392 Binutils can be built with the debuginfod client library
5393 @code{libdebuginfod} using the @option{--with-debuginfod} configure option.
5394 This option is enabled by default if @code{libdebuginfod} is installed
5395 and found at configure time. This allows @command{objdump} and
5396 @command{readelf} to automatically query debuginfod servers for
5397 separate debug files when the files are otherwise not found.
5399 debuginfod is packaged with elfutils, starting with version 0.178.
5400 You can get the latest version from `https://sourceware.org/elfutils/'.
5402 @node Reporting Bugs
5403 @chapter Reporting Bugs
5405 @cindex reporting bugs
5407 Your bug reports play an essential role in making the binary utilities
5410 Reporting a bug may help you by bringing a solution to your problem, or
5411 it may not. But in any case the principal function of a bug report is
5412 to help the entire community by making the next version of the binary
5413 utilities work better. Bug reports are your contribution to their
5416 In order for a bug report to serve its purpose, you must include the
5417 information that enables us to fix the bug.
5420 * Bug Criteria:: Have you found a bug?
5421 * Bug Reporting:: How to report bugs
5425 @section Have You Found a Bug?
5426 @cindex bug criteria
5428 If you are not sure whether you have found a bug, here are some guidelines:
5431 @cindex fatal signal
5434 If a binary utility gets a fatal signal, for any input whatever, that is
5435 a bug. Reliable utilities never crash.
5437 @cindex error on valid input
5439 If a binary utility produces an error message for valid input, that is a
5443 If you are an experienced user of binary utilities, your suggestions for
5444 improvement are welcome in any case.
5448 @section How to Report Bugs
5450 @cindex bugs, reporting
5452 A number of companies and individuals offer support for @sc{gnu}
5453 products. If you obtained the binary utilities from a support
5454 organization, we recommend you contact that organization first.
5456 You can find contact information for many support companies and
5457 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
5461 In any event, we also recommend that you send bug reports for the binary
5462 utilities to @value{BUGURL}.
5465 The fundamental principle of reporting bugs usefully is this:
5466 @strong{report all the facts}. If you are not sure whether to state a
5467 fact or leave it out, state it!
5469 Often people omit facts because they think they know what causes the
5470 problem and assume that some details do not matter. Thus, you might
5471 assume that the name of a file you use in an example does not matter.
5472 Well, probably it does not, but one cannot be sure. Perhaps the bug is
5473 a stray memory reference which happens to fetch from the location where
5474 that pathname is stored in memory; perhaps, if the pathname were
5475 different, the contents of that location would fool the utility into
5476 doing the right thing despite the bug. Play it safe and give a
5477 specific, complete example. That is the easiest thing for you to do,
5478 and the most helpful.
5480 Keep in mind that the purpose of a bug report is to enable us to fix the bug if
5481 it is new to us. Therefore, always write your bug reports on the assumption
5482 that the bug has not been reported previously.
5484 Sometimes people give a few sketchy facts and ask, ``Does this ring a
5485 bell?'' This cannot help us fix a bug, so it is basically useless. We
5486 respond by asking for enough details to enable us to investigate.
5487 You might as well expedite matters by sending them to begin with.
5489 To enable us to fix the bug, you should include all these things:
5493 The version of the utility. Each utility announces it if you start it
5494 with the @option{--version} argument.
5496 Without this, we will not know whether there is any point in looking for
5497 the bug in the current version of the binary utilities.
5500 Any patches you may have applied to the source, including any patches
5501 made to the @code{BFD} library.
5504 The type of machine you are using, and the operating system name and
5508 What compiler (and its version) was used to compile the utilities---e.g.
5512 The command arguments you gave the utility to observe the bug. To
5513 guarantee you will not omit something important, list them all. A copy
5514 of the Makefile (or the output from make) is sufficient.
5516 If we were to try to guess the arguments, we would probably guess wrong
5517 and then we might not encounter the bug.
5520 A complete input file, or set of input files, that will reproduce the
5521 bug. If the utility is reading an object file or files, then it is
5522 generally most helpful to send the actual object files.
5524 If the source files were produced exclusively using @sc{gnu} programs
5525 (e.g., @command{gcc}, @command{gas}, and/or the @sc{gnu} @command{ld}), then it
5526 may be OK to send the source files rather than the object files. In
5527 this case, be sure to say exactly what version of @command{gcc}, or
5528 whatever, was used to produce the object files. Also say how
5529 @command{gcc}, or whatever, was configured.
5532 A description of what behavior you observe that you believe is
5533 incorrect. For example, ``It gets a fatal signal.''
5535 Of course, if the bug is that the utility gets a fatal signal, then we
5536 will certainly notice it. But if the bug is incorrect output, we might
5537 not notice unless it is glaringly wrong. You might as well not give us
5538 a chance to make a mistake.
5540 Even if the problem you experience is a fatal signal, you should still
5541 say so explicitly. Suppose something strange is going on, such as your
5542 copy of the utility is out of sync, or you have encountered a bug in
5543 the C library on your system. (This has happened!) Your copy might
5544 crash and ours would not. If you told us to expect a crash, then when
5545 ours fails to crash, we would know that the bug was not happening for
5546 us. If you had not told us to expect a crash, then we would not be able
5547 to draw any conclusion from our observations.
5550 If you wish to suggest changes to the source, send us context diffs, as
5551 generated by @command{diff} with the @option{-u}, @option{-c}, or @option{-p}
5552 option. Always send diffs from the old file to the new file. If you
5553 wish to discuss something in the @command{ld} source, refer to it by
5554 context, not by line number.
5556 The line numbers in our development sources will not match those in your
5557 sources. Your line numbers would convey no useful information to us.
5560 Here are some things that are not necessary:
5564 A description of the envelope of the bug.
5566 Often people who encounter a bug spend a lot of time investigating
5567 which changes to the input file will make the bug go away and which
5568 changes will not affect it.
5570 This is often time consuming and not very useful, because the way we
5571 will find the bug is by running a single example under the debugger
5572 with breakpoints, not by pure deduction from a series of examples.
5573 We recommend that you save your time for something else.
5575 Of course, if you can find a simpler example to report @emph{instead}
5576 of the original one, that is a convenience for us. Errors in the
5577 output will be easier to spot, running under the debugger will take
5578 less time, and so on.
5580 However, simplification is not vital; if you do not want to do this,
5581 report the bug anyway and send us the entire test case you used.
5584 A patch for the bug.
5586 A patch for the bug does help us if it is a good one. But do not omit
5587 the necessary information, such as the test case, on the assumption that
5588 a patch is all we need. We might see problems with your patch and decide
5589 to fix the problem another way, or we might not understand it at all.
5591 Sometimes with programs as complicated as the binary utilities it is
5592 very hard to construct an example that will make the program follow a
5593 certain path through the code. If you do not send us the example, we
5594 will not be able to construct one, so we will not be able to verify that
5597 And if we cannot understand what bug you are trying to fix, or why your
5598 patch should be an improvement, we will not install it. A test case will
5599 help us to understand.
5602 A guess about what the bug is or what it depends on.
5604 Such guesses are usually wrong. Even we cannot guess right about such
5605 things without first using the debugger to find the facts.
5608 @node GNU Free Documentation License
5609 @appendix GNU Free Documentation License
5613 @node Binutils Index
5614 @unnumbered Binutils Index