1193323Sed\input texinfo @c -*- Texinfo -*- 2193323Sed@setfilename binutils.info 3353358Sdim@settitle @sc{gnu} Binary Utilities 4353358Sdim@finalout 5353358Sdim@synindex ky cp 6193323Sed 7193323Sed@c man begin INCLUDE 8193323Sed@include bfdver.texi 9193323Sed@c man end 10193323Sed 11193323Sed@copying 12193323Sed@c man begin COPYRIGHT 13193323SedCopyright @copyright{} 1991-2020 Free Software Foundation, Inc. 14249423Sdim 15249423SdimPermission is granted to copy, distribute and/or modify this document 16193323Sedunder the terms of the GNU Free Documentation License, Version 1.3 17218893Sdimor any later version published by the Free Software Foundation; 18199481Srdivackywith no Invariant Sections, with no Front-Cover Texts, and with no 19193323SedBack-Cover Texts. A copy of the license is included in the 20193323Sedsection entitled ``GNU Free Documentation License''. 21193323Sed 22193323Sed@c man end 23193323Sed@end copying 24193323Sed 25193323Sed@dircategory Software development 26193323Sed@direntry 27193323Sed* Binutils: (binutils). The GNU binary utilities. 28193323Sed@end direntry 29341825Sdim 30193323Sed@dircategory Individual utilities 31193323Sed@direntry 32193323Sed* addr2line: (binutils)addr2line. Convert addresses to file and line. 33193323Sed* ar: (binutils)ar. Create, modify, and extract from archives. 34341825Sdim* c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols. 35193323Sed* cxxfilt: (binutils)c++filt. MS-DOS name for c++filt. 36193323Sed* dlltool: (binutils)dlltool. Create files needed to build and use DLLs. 37341825Sdim* nm: (binutils)nm. List symbols from object files. 38193323Sed* objcopy: (binutils)objcopy. Copy and translate object files. 39193323Sed* objdump: (binutils)objdump. Display information from object files. 40193323Sed* ranlib: (binutils)ranlib. Generate index to archive contents. 41193323Sed* readelf: (binutils)readelf. Display the contents of ELF format files. 42193323Sed* size: (binutils)size. List section sizes and total size. 43193323Sed* strings: (binutils)strings. List printable strings from files. 44193323Sed* strip: (binutils)strip. Discard symbols. 45193323Sed* elfedit: (binutils)elfedit. Update ELF header and property of ELF files. 46193323Sed* windmc: (binutils)windmc. Generator for Windows message resources. 47341825Sdim* windres: (binutils)windres. Manipulate Windows resources. 48341825Sdim@end direntry 49193323Sed 50193323Sed@titlepage 51193323Sed@title The @sc{gnu} Binary Utilities 52193323Sed@ifset VERSION_PACKAGE 53193323Sed@subtitle @value{VERSION_PACKAGE} 54193323Sed@end ifset 55249423Sdim@subtitle Version @value{VERSION} 56@sp 1 57@subtitle @value{UPDATED} 58@author Roland H. Pesch 59@author Jeffrey M. Osier 60@author Cygnus Support 61@page 62 63@tex 64{\parskip=0pt \hfill Cygnus Support\par \hfill 65Texinfo \texinfoversion\par } 66@end tex 67 68@vskip 0pt plus 1filll 69@insertcopying 70@end titlepage 71@contents 72 73@node Top 74@top Introduction 75 76@cindex version 77This brief manual contains documentation for the @sc{gnu} binary 78utilities 79@ifset VERSION_PACKAGE 80@value{VERSION_PACKAGE} 81@end ifset 82version @value{VERSION}: 83 84@iftex 85@table @code 86@item ar 87Create, modify, and extract from archives 88 89@item nm 90List symbols from object files 91 92@item objcopy 93Copy and translate object files 94 95@item objdump 96Display information from object files 97 98@item ranlib 99Generate index to archive contents 100 101@item readelf 102Display the contents of ELF format files. 103 104@item size 105List file section sizes and total size 106 107@item strings 108List printable strings from files 109 110@item strip 111Discard symbols 112 113@item elfedit 114Update the ELF header and program property of ELF files. 115 116@item c++filt 117Demangle encoded C++ symbols (on MS-DOS, this program is named 118@code{cxxfilt}) 119 120@item addr2line 121Convert addresses into file names and line numbers 122 123@item windres 124Manipulate Windows resources 125 126@item windmc 127Generator for Windows message resources 128 129@item dlltool 130Create the files needed to build and use Dynamic Link Libraries 131@end table 132@end iftex 133 134This document is distributed under the terms of the GNU Free 135Documentation License version 1.3. A copy of the license is included 136in the section entitled ``GNU Free Documentation License''. 137 138@menu 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 161@end menu 162 163@node ar 164@chapter ar 165 166@kindex ar 167@cindex archives 168@cindex collections of files 169 170@c man title ar create, modify, and extract from archives 171 172@smallexample 173ar [-]@var{p}[@var{mod}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@option{--output} @var{dirname}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}] 174ar -M [ <mri-script ] 175@end smallexample 176 177@c man begin DESCRIPTION ar 178 179The @sc{gnu} @command{ar} program creates, modifies, and extracts from 180archives. An @dfn{archive} is a single file holding a collection of 181other files in a structure that makes it possible to retrieve 182the original individual files (called @dfn{members} of the archive). 183 184The original files' contents, mode (permissions), timestamp, owner, and 185group are preserved in the archive, and can be restored on 186extraction. 187 188@cindex name length 189@sc{gnu} @command{ar} can maintain archives whose members have names of any 190length; however, depending on how @command{ar} is configured on your 191system, a limit on member-name length may be imposed for compatibility 192with archive formats maintained with other tools. If it exists, the 193limit is often 15 characters (typical of formats related to a.out) or 16 194characters (typical of formats related to coff). 195 196@cindex libraries 197@command{ar} is considered a binary utility because archives of this sort 198are most often used as @dfn{libraries} holding commonly needed 199subroutines. 200 201@cindex symbol index 202@command{ar} creates an index to the symbols defined in relocatable 203object modules in the archive when you specify the modifier @samp{s}. 204Once created, this index is updated in the archive whenever @command{ar} 205makes a change to its contents (save for the @samp{q} update operation). 206An archive with such an index speeds up linking to the library, and 207allows routines in the library to call each other without regard to 208their placement in the archive. 209 210You may use @samp{nm -s} or @samp{nm --print-armap} to list this index 211table. If an archive lacks the table, another form of @command{ar} called 212@command{ranlib} can be used to add just the table. 213 214@cindex thin archives 215@sc{gnu} @command{ar} can optionally create a @emph{thin} archive, 216which contains a symbol index and references to the original copies 217of the member files of the archive. This is useful for building 218libraries for use within a local build tree, where the relocatable 219objects are expected to remain available, and copying the contents of 220each object would only waste time and space. 221 222An archive can either be @emph{thin} or it can be normal. It cannot 223be both at the same time. Once an archive is created its format 224cannot be changed without first deleting it and then creating a new 225archive in its place. 226 227Thin archives are also @emph{flattened}, so that adding one thin 228archive to another thin archive does not nest it, as would happen with 229a normal archive. Instead the elements of the first archive are added 230individually to the second archive. 231 232The paths to the elements of the archive are stored relative to the 233archive itself. 234 235@cindex compatibility, @command{ar} 236@cindex @command{ar} compatibility 237@sc{gnu} @command{ar} is designed to be compatible with two different 238facilities. You can control its activity using command-line options, 239like the different varieties of @command{ar} on Unix systems; or, if you 240specify the single command-line option @option{-M}, you can control it 241with a script supplied via standard input, like the MRI ``librarian'' 242program. 243 244@c man end 245 246@menu 247* ar cmdline:: Controlling @command{ar} on the command line 248* ar scripts:: Controlling @command{ar} with a script 249@end menu 250 251@page 252@node ar cmdline 253@section Controlling @command{ar} on the Command Line 254 255@smallexample 256@c man begin SYNOPSIS ar 257ar [@option{-X32_64}] [@option{-}]@var{p}[@var{mod}] [@option{--plugin} @var{name}] [@option{--target} @var{bfdname}] [@option{--output} @var{dirname}] [@var{relpos}] [@var{count}] @var{archive} [@var{member}@dots{}] 258@c man end 259@end smallexample 260 261@cindex Unix compatibility, @command{ar} 262When you use @command{ar} in the Unix style, @command{ar} insists on at least two 263arguments to execute: one keyletter specifying the @emph{operation} 264(optionally accompanied by other keyletters specifying 265@emph{modifiers}), and the archive name to act on. 266 267Most operations can also accept further @var{member} arguments, 268specifying particular files to operate on. 269 270@c man begin OPTIONS ar 271 272@sc{gnu} @command{ar} allows you to mix the operation code @var{p} and modifier 273flags @var{mod} in any order, within the first command-line argument. 274 275If you wish, you may begin the first command-line argument with a 276dash. 277 278@cindex operations on archive 279The @var{p} keyletter specifies what operation to execute; it may be 280any of the following, but you must specify only one of them: 281 282@table @samp 283@item d 284@cindex deleting from archive 285@emph{Delete} modules from the archive. Specify the names of modules to 286be deleted as @var{member}@dots{}; the archive is untouched if you 287specify no files to delete. 288 289If you specify the @samp{v} modifier, @command{ar} lists each module 290as it is deleted. 291 292@item m 293@cindex moving in archive 294Use this operation to @emph{move} members in an archive. 295 296The ordering of members in an archive can make a difference in how 297programs are linked using the library, if a symbol is defined in more 298than one member. 299 300If no modifiers are used with @code{m}, any members you name in the 301@var{member} arguments are moved to the @emph{end} of the archive; 302you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a 303specified place instead. 304 305@item p 306@cindex printing from archive 307@emph{Print} the specified members of the archive, to the standard 308output file. If the @samp{v} modifier is specified, show the member 309name before copying its contents to standard output. 310 311If you specify no @var{member} arguments, all the files in the archive are 312printed. 313 314@item q 315@cindex quick append to archive 316@emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of 317@var{archive}, without checking for replacement. 318 319The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this 320operation; new members are always placed at the end of the archive. 321 322The modifier @samp{v} makes @command{ar} list each file as it is appended. 323 324Since the point of this operation is speed, implementations of 325@command{ar} have the option of not updating the archive's symbol 326table if one exists. Too many different systems however assume that 327symbol tables are always up-to-date, so @sc{gnu} @command{ar} will 328rebuild the table even with a quick append. 329 330Note - @sc{gnu} @command{ar} treats the command @samp{qs} as a 331synonym for @samp{r} - replacing already existing files in the 332archive and appending new ones at the end. 333 334@item r 335@cindex replacement in archive 336Insert the files @var{member}@dots{} into @var{archive} (with 337@emph{replacement}). This operation differs from @samp{q} in that any 338previously existing members are deleted if their names match those being 339added. 340 341If one of the files named in @var{member}@dots{} does not exist, @command{ar} 342displays an error message, and leaves undisturbed any existing members 343of the archive matching that name. 344 345By default, new members are added at the end of the file; but you may 346use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request 347placement relative to some existing member. 348 349The modifier @samp{v} used with this operation elicits a line of 350output for each file inserted, along with one of the letters @samp{a} or 351@samp{r} to indicate whether the file was appended (no old member 352deleted) or replaced. 353 354@item s 355@cindex ranlib 356Add an index to the archive, or update it if it already exists. Note 357this command is an exception to the rule that there can only be one 358command letter, as it is possible to use it as either a command or a 359modifier. In either case it does the same thing. 360 361@item t 362@cindex contents of archive 363Display a @emph{table} listing the contents of @var{archive}, or those 364of the files listed in @var{member}@dots{} that are present in the 365archive. Normally only the member name is shown, but if the modifier 366@samp{O} is specified, then the corresponding offset of the member is also 367displayed. Finally, in order to see the modes (permissions), timestamp, 368owner, group, and size the @samp{v} modifier should be included. 369 370If you do not specify a @var{member}, all files in the archive 371are listed. 372 373@cindex repeated names in archive 374@cindex name duplication in archive 375If there is more than one file with the same name (say, @samp{fie}) in 376an archive (say @samp{b.a}), @samp{ar t b.a fie} lists only the 377first instance; to see them all, you must ask for a complete 378listing---in our example, @samp{ar t b.a}. 379@c WRS only; per Gumby, this is implementation-dependent, and in a more 380@c recent case in fact works the other way. 381 382@item x 383@cindex extract from archive 384@emph{Extract} members (named @var{member}) from the archive. You can 385use the @samp{v} modifier with this operation, to request that 386@command{ar} list each name as it extracts it. 387 388If you do not specify a @var{member}, all files in the archive 389are extracted. 390 391Files cannot be extracted from a thin archive, and there are 392restrictions on extracting from archives created with @option{P}: The 393paths must not be absolute, may not contain @code{..}, and any 394subdirectories in the paths must exist. If it is desired to avoid 395these restrictions then used the @option{--output} option to specify 396an output directory. 397@end table 398 399A number of modifiers (@var{mod}) may immediately follow the @var{p} 400keyletter, to specify variations on an operation's behavior: 401 402@table @samp 403@item a 404@cindex relative placement in archive 405Add new files @emph{after} an existing member of the 406archive. If you use the modifier @samp{a}, the name of an existing archive 407member must be present as the @var{relpos} argument, before the 408@var{archive} specification. 409 410@item b 411Add new files @emph{before} an existing member of the 412archive. If you use the modifier @samp{b}, the name of an existing archive 413member must be present as the @var{relpos} argument, before the 414@var{archive} specification. (same as @samp{i}). 415 416@item c 417@cindex creating archives 418@emph{Create} the archive. The specified @var{archive} is always 419created if it did not exist, when you request an update. But a warning is 420issued unless you specify in advance that you expect to create it, by 421using this modifier. 422 423@item D 424@cindex deterministic archives 425@kindex --enable-deterministic-archives 426Operate in @emph{deterministic} mode. When adding files and the archive 427index use zero for UIDs, GIDs, timestamps, and use consistent file modes 428for all files. When this option is used, if @command{ar} is used with 429identical options and identical input files, multiple runs will create 430identical output files regardless of the input files' owners, groups, 431file modes, or modification times. 432 433If @file{binutils} was configured with 434@option{--enable-deterministic-archives}, then this mode is on by default. 435It can be disabled with the @samp{U} modifier, below. 436 437@item f 438Truncate names in the archive. @sc{gnu} @command{ar} will normally permit file 439names of any length. This will cause it to create archives which are 440not compatible with the native @command{ar} program on some systems. If 441this is a concern, the @samp{f} modifier may be used to truncate file 442names when putting them in the archive. 443 444@item i 445Insert new files @emph{before} an existing member of the 446archive. If you use the modifier @samp{i}, the name of an existing archive 447member must be present as the @var{relpos} argument, before the 448@var{archive} specification. (same as @samp{b}). 449 450@item l 451This modifier is accepted but not used. 452@c whaffor ar l modifier??? presumably compat; with 453@c what???---doc@@cygnus.com, 25jan91 454 455@item N 456Uses the @var{count} parameter. This is used if there are multiple 457entries in the archive with the same name. Extract or delete instance 458@var{count} of the given name from the archive. 459 460@item o 461@cindex dates in archive 462Preserve the @emph{original} dates of members when extracting them. If 463you do not specify this modifier, files extracted from the archive 464are stamped with the time of extraction. 465 466@item O 467@cindex offsets of files 468Display member offsets inside the archive. Use together with the @samp{t} 469option. 470 471@item P 472Use the full path name when matching or storing names in the archive. 473Archives created with full path names are not POSIX compliant, and 474thus may not work with tools other than up to date @sc{gnu} tools. 475Modifying such archives with @sc{gnu} @command{ar} without using 476@option{P} will remove the full path names unless the archive is a 477thin archive. Note that @option{P} may be useful when adding files to 478a thin archive since @option{r} without @option{P} ignores the path 479when choosing which element to replace. Thus 480@smallexample 481ar rcST archive.a subdir/file1 subdir/file2 file1 482@end smallexample 483will result in the first @code{subdir/file1} being replaced with 484@code{file1} from the current directory. Adding @option{P} will 485prevent this replacement. 486 487@item s 488@cindex writing archive index 489Write an object-file index into the archive, or update an existing one, 490even if no other change is made to the archive. You may use this modifier 491flag either with any operation, or alone. Running @samp{ar s} on an 492archive is equivalent to running @samp{ranlib} on it. 493 494@item S 495@cindex not writing archive index 496Do not generate an archive symbol table. This can speed up building a 497large library in several steps. The resulting archive can not be used 498with the linker. In order to build a symbol table, you must omit the 499@samp{S} modifier on the last execution of @samp{ar}, or you must run 500@samp{ranlib} on the archive. 501 502@item T 503@cindex creating thin archive 504Make the specified @var{archive} a @emph{thin} archive. If it already 505exists and is a regular archive, the existing members must be present 506in the same directory as @var{archive}. 507 508@item u 509@cindex updating an archive 510Normally, @samp{ar r}@dots{} inserts all files 511listed into the archive. If you would like to insert @emph{only} those 512of the files you list that are newer than existing members of the same 513names, use this modifier. The @samp{u} modifier is allowed only for the 514operation @samp{r} (replace). In particular, the combination @samp{qu} is 515not allowed, since checking the timestamps would lose any speed 516advantage from the operation @samp{q}. 517 518@item U 519@cindex deterministic archives 520@kindex --enable-deterministic-archives 521Do @emph{not} operate in @emph{deterministic} mode. This is the inverse 522of the @samp{D} modifier, above: added files and the archive index will 523get their actual UID, GID, timestamp, and file mode values. 524 525This is the default unless @file{binutils} was configured with 526@option{--enable-deterministic-archives}. 527 528@item v 529This modifier requests the @emph{verbose} version of an operation. Many 530operations display additional information, such as filenames processed, 531when the modifier @samp{v} is appended. 532 533@item V 534This modifier shows the version number of @command{ar}. 535@end table 536 537The @command{ar} program also supports some command-line options which 538are neither modifiers nor actions, but which do change its behaviour 539in specific ways: 540 541@table @samp 542@item --help 543Displays the list of command-line options supported by @command{ar} 544and then exits. 545 546@item --version 547Displays the version information of @command{ar} and then exits. 548 549@item -X32_64 550@command{ar} ignores an initial option spelled @samp{-X32_64}, for 551compatibility with AIX. The behaviour produced by this option is the 552default for @sc{gnu} @command{ar}. @command{ar} does not support any 553of the other @samp{-X} options; in particular, it does not support 554@option{-X32} which is the default for AIX @command{ar}. 555 556@item --plugin @var{name} 557@cindex plugins 558The optional command-line switch @option{--plugin @var{name}} causes 559@command{ar} to load the plugin called @var{name} which adds support 560for more file formats, including object files with link-time 561optimization information. 562 563This option is only available if the toolchain has been built with 564plugin support enabled. 565 566If @option{--plugin} is not provided, but plugin support has been 567enabled then @command{ar} iterates over the files in 568@file{$@{libdir@}/bfd-plugins} in alphabetic order and the first 569plugin that claims the object in question is used. 570 571Please note that this plugin search directory is @emph{not} the one 572used by @command{ld}'s @option{-plugin} option. In order to make 573@command{ar} use the linker plugin it must be copied into the 574@file{$@{libdir@}/bfd-plugins} directory. For GCC based compilations 575the linker plugin is called @file{liblto_plugin.so.0.0.0}. For Clang 576based compilations it is called @file{LLVMgold.so}. The GCC plugin 577is always backwards compatible with earlier versions, so it is 578sufficient to just copy the newest one. 579 580@item --target @var{target} 581The optional command-line switch @option{--target @var{bfdname}} 582specifies that the archive members are in an object code format 583different from your system's default format. See 584@xref{Target Selection}, for more information. 585 586@item --output @var{dirname} 587The @option{--output} option can be used to specify a path to a 588directory into which archive members should be extracted. If this 589option is not specified then the current directory will be used. 590 591Note - although the presence of this option does imply a @option{x} 592extraction operation that option must still be included on the command 593line. 594 595@end table 596@c man end 597 598@ignore 599@c man begin SEEALSO ar 600nm(1), ranlib(1), and the Info entries for @file{binutils}. 601@c man end 602@end ignore 603 604@node ar scripts 605@section Controlling @command{ar} with a Script 606 607@smallexample 608ar -M [ <@var{script} ] 609@end smallexample 610 611@cindex MRI compatibility, @command{ar} 612@cindex scripts, @command{ar} 613If you use the single command-line option @samp{-M} with @command{ar}, you 614can control its operation with a rudimentary command language. This 615form of @command{ar} operates interactively if standard input is coming 616directly from a terminal. During interactive use, @command{ar} prompts for 617input (the prompt is @samp{AR >}), and continues executing even after 618errors. If you redirect standard input to a script file, no prompts are 619issued, and @command{ar} abandons execution (with a nonzero exit code) 620on any error. 621 622The @command{ar} command language is @emph{not} designed to be equivalent 623to the command-line options; in fact, it provides somewhat less control 624over archives. The only purpose of the command language is to ease the 625transition to @sc{gnu} @command{ar} for developers who already have scripts 626written for the MRI ``librarian'' program. 627 628The syntax for the @command{ar} command language is straightforward: 629@itemize @bullet 630@item 631commands are recognized in upper or lower case; for example, @code{LIST} 632is the same as @code{list}. In the following descriptions, commands are 633shown in upper case for clarity. 634 635@item 636a single command may appear on each line; it is the first word on the 637line. 638 639@item 640empty lines are allowed, and have no effect. 641 642@item 643comments are allowed; text after either of the characters @samp{*} 644or @samp{;} is ignored. 645 646@item 647Whenever you use a list of names as part of the argument to an @command{ar} 648command, you can separate the individual names with either commas or 649blanks. Commas are shown in the explanations below, for clarity. 650 651@item 652@samp{+} is used as a line continuation character; if @samp{+} appears 653at the end of a line, the text on the following line is considered part 654of the current command. 655@end itemize 656 657Here are the commands you can use in @command{ar} scripts, or when using 658@command{ar} interactively. Three of them have special significance: 659 660@code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is 661a temporary file required for most of the other commands. 662 663@code{SAVE} commits the changes so far specified by the script. Prior 664to @code{SAVE}, commands affect only the temporary copy of the current 665archive. 666 667@table @code 668@item ADDLIB @var{archive} 669@itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module}) 670Add all the contents of @var{archive} (or, if specified, each named 671@var{module} from @var{archive}) to the current archive. 672 673Requires prior use of @code{OPEN} or @code{CREATE}. 674 675@item ADDMOD @var{member}, @var{member}, @dots{} @var{member} 676@c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}" 677@c else like "ar q..." 678Add each named @var{member} as a module in the current archive. 679 680Requires prior use of @code{OPEN} or @code{CREATE}. 681 682@item CLEAR 683Discard the contents of the current archive, canceling the effect of 684any operations since the last @code{SAVE}. May be executed (with no 685effect) even if no current archive is specified. 686 687@item CREATE @var{archive} 688Creates an archive, and makes it the current archive (required for many 689other commands). The new archive is created with a temporary name; it 690is not actually saved as @var{archive} until you use @code{SAVE}. 691You can overwrite existing archives; similarly, the contents of any 692existing file named @var{archive} will not be destroyed until @code{SAVE}. 693 694@item DELETE @var{module}, @var{module}, @dots{} @var{module} 695Delete each listed @var{module} from the current archive; equivalent to 696@samp{ar -d @var{archive} @var{module} @dots{} @var{module}}. 697 698Requires prior use of @code{OPEN} or @code{CREATE}. 699 700@item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) 701@itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile} 702List each named @var{module} present in @var{archive}. The separate 703command @code{VERBOSE} specifies the form of the output: when verbose 704output is off, output is like that of @samp{ar -t @var{archive} 705@var{module}@dots{}}. When verbose output is on, the listing is like 706@samp{ar -tv @var{archive} @var{module}@dots{}}. 707 708Output normally goes to the standard output stream; however, if you 709specify @var{outputfile} as a final argument, @command{ar} directs the 710output to that file. 711 712@item END 713Exit from @command{ar}, with a @code{0} exit code to indicate successful 714completion. This command does not save the output file; if you have 715changed the current archive since the last @code{SAVE} command, those 716changes are lost. 717 718@item EXTRACT @var{module}, @var{module}, @dots{} @var{module} 719Extract each named @var{module} from the current archive, writing them 720into the current directory as separate files. Equivalent to @samp{ar -x 721@var{archive} @var{module}@dots{}}. 722 723Requires prior use of @code{OPEN} or @code{CREATE}. 724 725@ignore 726@c FIXME Tokens but no commands??? 727@item FULLDIR 728 729@item HELP 730@end ignore 731 732@item LIST 733Display full contents of the current archive, in ``verbose'' style 734regardless of the state of @code{VERBOSE}. The effect is like @samp{ar 735tv @var{archive}}. (This single command is a @sc{gnu} @command{ar} 736enhancement, rather than present for MRI compatibility.) 737 738Requires prior use of @code{OPEN} or @code{CREATE}. 739 740@item OPEN @var{archive} 741Opens an existing archive for use as the current archive (required for 742many other commands). Any changes as the result of subsequent commands 743will not actually affect @var{archive} until you next use @code{SAVE}. 744 745@item REPLACE @var{module}, @var{module}, @dots{} @var{module} 746In the current archive, replace each existing @var{module} (named in 747the @code{REPLACE} arguments) from files in the current working directory. 748To execute this command without errors, both the file, and the module in 749the current archive, must exist. 750 751Requires prior use of @code{OPEN} or @code{CREATE}. 752 753@item VERBOSE 754Toggle an internal flag governing the output from @code{DIRECTORY}. 755When the flag is on, @code{DIRECTORY} output matches output from 756@samp{ar -tv }@dots{}. 757 758@item SAVE 759Commit your changes to the current archive, and actually save it as a 760file with the name specified in the last @code{CREATE} or @code{OPEN} 761command. 762 763Requires prior use of @code{OPEN} or @code{CREATE}. 764 765@end table 766 767@iftex 768@node ld 769@chapter ld 770@cindex linker 771@kindex ld 772The @sc{gnu} linker @command{ld} is now described in a separate manual. 773@xref{Top,, Overview,, Using LD: the @sc{gnu} linker}. 774@end iftex 775 776@node nm 777@chapter nm 778@cindex symbols 779@kindex nm 780 781@c man title nm list symbols from object files 782 783@smallexample 784@c man begin SYNOPSIS nm 785nm [@option{-A}|@option{-o}|@option{--print-file-name}] [@option{-a}|@option{--debug-syms}] 786 [@option{-B}|@option{--format=bsd}] [@option{-C}|@option{--demangle}[=@var{style}]] 787 [@option{-D}|@option{--dynamic}] [@option{-f}@var{format}|@option{--format=}@var{format}] 788 [@option{-g}|@option{--extern-only}] [@option{-h}|@option{--help}] 789 [@option{-l}|@option{--line-numbers}] [@option{--inlines}] 790 [@option{-n}|@option{-v}|@option{--numeric-sort}] 791 [@option{-P}|@option{--portability}] [@option{-p}|@option{--no-sort}] 792 [@option{-r}|@option{--reverse-sort}] [@option{-S}|@option{--print-size}] 793 [@option{-s}|@option{--print-armap}] [@option{-t} @var{radix}|@option{--radix=}@var{radix}] 794 [@option{-u}|@option{--undefined-only}] [@option{-V}|@option{--version}] 795 [@option{-X 32_64}] [@option{--defined-only}] [@option{--no-demangle}] 796 [@option{--plugin} @var{name}] 797 [@option{--no-recurse-limit}|@option{--recurse-limit}]] 798 [@option{--size-sort}] [@option{--special-syms}] 799 [@option{--synthetic}] [@option{--target=}@var{bfdname}] 800 [@var{objfile}@dots{}] 801@c man end 802@end smallexample 803 804@c man begin DESCRIPTION nm 805@sc{gnu} @command{nm} lists the symbols from object files @var{objfile}@dots{}. 806If no object files are listed as arguments, @command{nm} assumes the file 807@file{a.out}. 808 809For each symbol, @command{nm} shows: 810 811@itemize @bullet 812@item 813The symbol value, in the radix selected by options (see below), or 814hexadecimal by default. 815 816@item 817The symbol type. At least the following types are used; others are, as 818well, depending on the object file format. If lowercase, the symbol is 819usually local; if uppercase, the symbol is global (external). There 820are however a few lowercase symbols that are shown for special global 821symbols (@code{u}, @code{v} and @code{w}). 822 823@c Some more detail on exactly what these symbol types are used for 824@c would be nice. 825@table @code 826@item A 827The symbol's value is absolute, and will not be changed by further 828linking. 829 830@item B 831@itemx b 832The symbol is in the BSS data section. This section typically 833contains zero-initialized or uninitialized data, although the exact 834behavior is system dependent. 835 836@item C 837The symbol is common. Common symbols are uninitialized data. When 838linking, multiple common symbols may appear with the same name. If the 839symbol is defined anywhere, the common symbols are treated as undefined 840references. 841@ifclear man 842For more details on common symbols, see the discussion of 843--warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}. 844@end ifclear 845 846@item D 847@itemx d 848The symbol is in the initialized data section. 849 850@item G 851@itemx g 852The symbol is in an initialized data section for small objects. Some 853object file formats permit more efficient access to small data objects, 854such as a global int variable as opposed to a large global array. 855 856@item i 857For PE format files this indicates that the symbol is in a section 858specific to the implementation of DLLs. For ELF format files this 859indicates that the symbol is an indirect function. This is a GNU 860extension to the standard set of ELF symbol types. It indicates a 861symbol which if referenced by a relocation does not evaluate to its 862address, but instead must be invoked at runtime. The runtime 863execution will then return the value to be used in the relocation. 864 865@item I 866The symbol is an indirect reference to another symbol. 867 868@item N 869The symbol is a debugging symbol. 870 871@item n 872The symbol is in the read-only data section. 873 874@item p 875The symbol is in a stack unwind section. 876 877@item R 878@itemx r 879The symbol is in a read only data section. 880 881@item S 882@itemx s 883The symbol is in an uninitialized or zero-initialized data section 884for small objects. 885 886@item T 887@itemx t 888The symbol is in the text (code) section. 889 890@item U 891The symbol is undefined. 892 893@item u 894The symbol is a unique global symbol. This is a GNU extension to the 895standard set of ELF symbol bindings. For such a symbol the dynamic linker 896will make sure that in the entire process there is just one symbol with 897this name and type in use. 898 899@item V 900@itemx v 901The symbol is a weak object. When a weak defined symbol is linked with 902a normal defined symbol, the normal defined symbol is used with no error. 903When a weak undefined symbol is linked and the symbol is not defined, 904the value of the weak symbol becomes zero with no error. On some 905systems, uppercase indicates that a default value has been specified. 906 907@item W 908@itemx w 909The symbol is a weak symbol that has not been specifically tagged as a 910weak object symbol. When a weak defined symbol is linked with a normal 911defined symbol, the normal defined symbol is used with no error. 912When a weak undefined symbol is linked and the symbol is not defined, 913the value of the symbol is determined in a system-specific manner without 914error. On some systems, uppercase indicates that a default value has been 915specified. 916 917@item - 918The symbol is a stabs symbol in an a.out object file. In this case, the 919next values printed are the stabs other field, the stabs desc field, and 920the stab type. Stabs symbols are used to hold debugging information. 921 922@item ? 923The symbol type is unknown, or object file format specific. 924@end table 925 926@item 927The symbol name. If a symbol has version information associated with it, 928then the version information is displayed as well. If the versioned 929symbol is undefined or hidden from linker, the version string is displayed 930as a suffix to the symbol name, preceded by an @@ character. For example 931@samp{foo@@VER_1}. If the version is the default version to be used when 932resolving unversioned references to the symbol, then it is displayed as a 933suffix preceded by two @@ characters. For example @samp{foo@@@@VER_2}. 934@end itemize 935 936@c man end 937 938@c man begin OPTIONS nm 939The long and short forms of options, shown here as alternatives, are 940equivalent. 941 942@table @env 943@item -A 944@itemx -o 945@itemx --print-file-name 946@cindex input file name 947@cindex file name 948@cindex source file name 949Precede each symbol by the name of the input file (or archive member) 950in which it was found, rather than identifying the input file once only, 951before all of its symbols. 952 953@item -a 954@itemx --debug-syms 955@cindex debugging symbols 956Display all symbols, even debugger-only symbols; normally these are not 957listed. 958 959@item -B 960@cindex @command{nm} format 961@cindex @command{nm} compatibility 962The same as @option{--format=bsd} (for compatibility with the MIPS @command{nm}). 963 964@item -C 965@itemx --demangle[=@var{style}] 966@cindex demangling in nm 967Decode (@dfn{demangle}) low-level symbol names into user-level names. 968Besides removing any initial underscore prepended by the system, this 969makes C++ function names readable. Different compilers have different 970mangling styles. The optional demangling style argument can be used to 971choose an appropriate demangling style for your compiler. @xref{c++filt}, 972for more information on demangling. 973 974@item --no-demangle 975Do not demangle low-level symbol names. This is the default. 976 977@item --recurse-limit 978@itemx --no-recurse-limit 979@itemx --recursion-limit 980@itemx --no-recursion-limit 981Enables or disables a limit on the amount of recursion performed 982whilst demangling strings. Since the name mangling formats allow for 983an inifinite level of recursion it is possible to create strings whose 984decoding will exhaust the amount of stack space available on the host 985machine, triggering a memory fault. The limit tries to prevent this 986from happening by restricting recursion to 2048 levels of nesting. 987 988The default is for this limit to be enabled, but disabling it may be 989necessary in order to demangle truly complicated names. Note however 990that if the recursion limit is disabled then stack exhaustion is 991possible and any bug reports about such an event will be rejected. 992 993@item -D 994@itemx --dynamic 995@cindex dynamic symbols 996Display the dynamic symbols rather than the normal symbols. This is 997only meaningful for dynamic objects, such as certain types of shared 998libraries. 999 1000@item -f @var{format} 1001@itemx --format=@var{format} 1002@cindex @command{nm} format 1003@cindex @command{nm} compatibility 1004Use the output format @var{format}, which can be @code{bsd}, 1005@code{sysv}, or @code{posix}. The default is @code{bsd}. 1006Only the first character of @var{format} is significant; it can be 1007either upper or lower case. 1008 1009@item -g 1010@itemx --extern-only 1011@cindex external symbols 1012Display only external symbols. 1013 1014@item -h 1015@itemx --help 1016Show a summary of the options to @command{nm} and exit. 1017 1018@item -l 1019@itemx --line-numbers 1020@cindex symbol line numbers 1021For each symbol, use debugging information to try to find a filename and 1022line number. For a defined symbol, look for the line number of the 1023address of the symbol. For an undefined symbol, look for the line 1024number of a relocation entry which refers to the symbol. If line number 1025information can be found, print it after the other symbol information. 1026 1027@item --inlines 1028@cindex objdump inlines 1029When option @option{-l} is active, if the address belongs to a 1030function that was inlined, then this option causes the source 1031information for all enclosing scopes back to the first non-inlined 1032function to be printed as well. For example, if @code{main} inlines 1033@code{callee1} which inlines @code{callee2}, and address is from 1034@code{callee2}, the source information for @code{callee1} and @code{main} 1035will also be printed. 1036 1037@item -n 1038@itemx -v 1039@itemx --numeric-sort 1040Sort symbols numerically by their addresses, rather than alphabetically 1041by their names. 1042 1043@item -p 1044@itemx --no-sort 1045@cindex sorting symbols 1046Do not bother to sort the symbols in any order; print them in the order 1047encountered. 1048 1049@item -P 1050@itemx --portability 1051Use the POSIX.2 standard output format instead of the default format. 1052Equivalent to @samp{-f posix}. 1053 1054@item -r 1055@itemx --reverse-sort 1056Reverse the order of the sort (whether numeric or alphabetic); let the 1057last come first. 1058 1059@item -S 1060@itemx --print-size 1061Print both value and size of defined symbols for the @code{bsd} output style. 1062This option has no effect for object formats that do not record symbol 1063sizes, unless @samp{--size-sort} is also used in which case a 1064calculated size is displayed. 1065 1066@item -s 1067@itemx --print-armap 1068@cindex symbol index, listing 1069When listing symbols from archive members, include the index: a mapping 1070(stored in the archive by @command{ar} or @command{ranlib}) of which modules 1071contain definitions for which names. 1072 1073@item -t @var{radix} 1074@itemx --radix=@var{radix} 1075Use @var{radix} as the radix for printing the symbol values. It must be 1076@samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal. 1077 1078@item -u 1079@itemx --undefined-only 1080@cindex external symbols 1081@cindex undefined symbols 1082Display only undefined symbols (those external to each object file). 1083 1084@item -V 1085@itemx --version 1086Show the version number of @command{nm} and exit. 1087 1088@item -X 1089This option is ignored for compatibility with the AIX version of 1090@command{nm}. It takes one parameter which must be the string 1091@option{32_64}. The default mode of AIX @command{nm} corresponds 1092to @option{-X 32}, which is not supported by @sc{gnu} @command{nm}. 1093 1094@item --defined-only 1095@cindex external symbols 1096@cindex undefined symbols 1097Display only defined symbols for each object file. 1098 1099@item --plugin @var{name} 1100@cindex plugins 1101Load the plugin called @var{name} to add support for extra target 1102types. This option is only available if the toolchain has been built 1103with plugin support enabled. 1104 1105If @option{--plugin} is not provided, but plugin support has been 1106enabled then @command{nm} iterates over the files in 1107@file{$@{libdir@}/bfd-plugins} in alphabetic order and the first 1108plugin that claims the object in question is used. 1109 1110Please note that this plugin search directory is @emph{not} the one 1111used by @command{ld}'s @option{-plugin} option. In order to make 1112@command{nm} use the linker plugin it must be copied into the 1113@file{$@{libdir@}/bfd-plugins} directory. For GCC based compilations 1114the linker plugin is called @file{liblto_plugin.so.0.0.0}. For Clang 1115based compilations it is called @file{LLVMgold.so}. The GCC plugin 1116is always backwards compatible with earlier versions, so it is 1117sufficient to just copy the newest one. 1118 1119@item --size-sort 1120Sort symbols by size. For ELF objects symbol sizes are read from the 1121ELF, for other object types the symbol sizes are computed as the 1122difference between the value of the symbol and the value of the symbol 1123with the next higher value. If the @code{bsd} output format is used 1124the size of the symbol is printed, rather than the value, and 1125@samp{-S} must be used in order both size and value to be printed. 1126 1127@item --special-syms 1128Display symbols which have a target-specific special meaning. These 1129symbols are usually used by the target for some special processing and 1130are not normally helpful when included in the normal symbol lists. 1131For example for ARM targets this option would skip the mapping symbols 1132used to mark transitions between ARM code, THUMB code and data. 1133 1134@item --synthetic 1135Include synthetic symbols in the output. These are special symbols 1136created by the linker for various purposes. They are not shown by 1137default since they are not part of the binary's original source code. 1138 1139@item --target=@var{bfdname} 1140@cindex object code format 1141Specify an object code format other than your system's default format. 1142@xref{Target Selection}, for more information. 1143 1144@end table 1145 1146@c man end 1147 1148@ignore 1149@c man begin SEEALSO nm 1150ar(1), objdump(1), ranlib(1), and the Info entries for @file{binutils}. 1151@c man end 1152@end ignore 1153 1154@node objcopy 1155@chapter objcopy 1156 1157@c man title objcopy copy and translate object files 1158 1159@smallexample 1160@c man begin SYNOPSIS objcopy 1161objcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}] 1162 [@option{-I} @var{bfdname}|@option{--input-target=}@var{bfdname}] 1163 [@option{-O} @var{bfdname}|@option{--output-target=}@var{bfdname}] 1164 [@option{-B} @var{bfdarch}|@option{--binary-architecture=}@var{bfdarch}] 1165 [@option{-S}|@option{--strip-all}] 1166 [@option{-g}|@option{--strip-debug}] 1167 [@option{--strip-unneeded}] 1168 [@option{-K} @var{symbolname}|@option{--keep-symbol=}@var{symbolname}] 1169 [@option{-N} @var{symbolname}|@option{--strip-symbol=}@var{symbolname}] 1170 [@option{--strip-unneeded-symbol=}@var{symbolname}] 1171 [@option{-G} @var{symbolname}|@option{--keep-global-symbol=}@var{symbolname}] 1172 [@option{--localize-hidden}] 1173 [@option{-L} @var{symbolname}|@option{--localize-symbol=}@var{symbolname}] 1174 [@option{--globalize-symbol=}@var{symbolname}] 1175 [@option{--globalize-symbols=}@var{filename}] 1176 [@option{-W} @var{symbolname}|@option{--weaken-symbol=}@var{symbolname}] 1177 [@option{-w}|@option{--wildcard}] 1178 [@option{-x}|@option{--discard-all}] 1179 [@option{-X}|@option{--discard-locals}] 1180 [@option{-b} @var{byte}|@option{--byte=}@var{byte}] 1181 [@option{-i} [@var{breadth}]|@option{--interleave}[=@var{breadth}]] 1182 [@option{--interleave-width=}@var{width}] 1183 [@option{-j} @var{sectionpattern}|@option{--only-section=}@var{sectionpattern}] 1184 [@option{-R} @var{sectionpattern}|@option{--remove-section=}@var{sectionpattern}] 1185 [@option{--keep-section=}@var{sectionpattern}] 1186 [@option{--remove-relocations=}@var{sectionpattern}] 1187 [@option{-p}|@option{--preserve-dates}] 1188 [@option{-D}|@option{--enable-deterministic-archives}] 1189 [@option{-U}|@option{--disable-deterministic-archives}] 1190 [@option{--debugging}] 1191 [@option{--gap-fill=}@var{val}] 1192 [@option{--pad-to=}@var{address}] 1193 [@option{--set-start=}@var{val}] 1194 [@option{--adjust-start=}@var{incr}] 1195 [@option{--change-addresses=}@var{incr}] 1196 [@option{--change-section-address} @var{sectionpattern}@{=,+,-@}@var{val}] 1197 [@option{--change-section-lma} @var{sectionpattern}@{=,+,-@}@var{val}] 1198 [@option{--change-section-vma} @var{sectionpattern}@{=,+,-@}@var{val}] 1199 [@option{--change-warnings}] [@option{--no-change-warnings}] 1200 [@option{--set-section-flags} @var{sectionpattern}=@var{flags}] 1201 [@option{--set-section-alignment} @var{sectionpattern}=@var{align}] 1202 [@option{--add-section} @var{sectionname}=@var{filename}] 1203 [@option{--dump-section} @var{sectionname}=@var{filename}] 1204 [@option{--update-section} @var{sectionname}=@var{filename}] 1205 [@option{--rename-section} @var{oldname}=@var{newname}[,@var{flags}]] 1206 [@option{--long-section-names} @{enable,disable,keep@}] 1207 [@option{--change-leading-char}] [@option{--remove-leading-char}] 1208 [@option{--reverse-bytes=}@var{num}] 1209 [@option{--srec-len=}@var{ival}] [@option{--srec-forceS3}] 1210 [@option{--redefine-sym} @var{old}=@var{new}] 1211 [@option{--redefine-syms=}@var{filename}] 1212 [@option{--weaken}] 1213 [@option{--keep-symbols=}@var{filename}] 1214 [@option{--strip-symbols=}@var{filename}] 1215 [@option{--strip-unneeded-symbols=}@var{filename}] 1216 [@option{--keep-global-symbols=}@var{filename}] 1217 [@option{--localize-symbols=}@var{filename}] 1218 [@option{--weaken-symbols=}@var{filename}] 1219 [@option{--add-symbol} @var{name}=[@var{section}:]@var{value}[,@var{flags}]] 1220 [@option{--alt-machine-code=}@var{index}] 1221 [@option{--prefix-symbols=}@var{string}] 1222 [@option{--prefix-sections=}@var{string}] 1223 [@option{--prefix-alloc-sections=}@var{string}] 1224 [@option{--add-gnu-debuglink=}@var{path-to-file}] 1225 [@option{--keep-file-symbols}] 1226 [@option{--only-keep-debug}] 1227 [@option{--strip-dwo}] 1228 [@option{--extract-dwo}] 1229 [@option{--extract-symbol}] 1230 [@option{--writable-text}] 1231 [@option{--readonly-text}] 1232 [@option{--pure}] 1233 [@option{--impure}] 1234 [@option{--file-alignment=}@var{num}] 1235 [@option{--heap=}@var{size}] 1236 [@option{--image-base=}@var{address}] 1237 [@option{--section-alignment=}@var{num}] 1238 [@option{--stack=}@var{size}] 1239 [@option{--subsystem=}@var{which}:@var{major}.@var{minor}] 1240 [@option{--compress-debug-sections}] 1241 [@option{--decompress-debug-sections}] 1242 [@option{--elf-stt-common=@var{val}}] 1243 [@option{--merge-notes}] 1244 [@option{--no-merge-notes}] 1245 [@option{--verilog-data-width=@var{val}}] 1246 [@option{-v}|@option{--verbose}] 1247 [@option{-V}|@option{--version}] 1248 [@option{--help}] [@option{--info}] 1249 @var{infile} [@var{outfile}] 1250@c man end 1251@end smallexample 1252 1253@c man begin DESCRIPTION objcopy 1254The @sc{gnu} @command{objcopy} utility copies the contents of an object 1255file to another. @command{objcopy} uses the @sc{gnu} @sc{bfd} Library to 1256read and write the object files. It can write the destination object 1257file in a format different from that of the source object file. The 1258exact behavior of @command{objcopy} is controlled by command-line options. 1259Note that @command{objcopy} should be able to copy a fully linked file 1260between any two formats. However, copying a relocatable object file 1261between any two formats may not work as expected. 1262 1263@command{objcopy} creates temporary files to do its translations and 1264deletes them afterward. @command{objcopy} uses @sc{bfd} to do all its 1265translation work; it has access to all the formats described in @sc{bfd} 1266and thus is able to recognize most formats without being told 1267explicitly. @xref{BFD,,BFD,ld.info,Using LD}. 1268 1269@command{objcopy} can be used to generate S-records by using an output 1270target of @samp{srec} (e.g., use @samp{-O srec}). 1271 1272@command{objcopy} can be used to generate a raw binary file by using an 1273output target of @samp{binary} (e.g., use @option{-O binary}). When 1274@command{objcopy} generates a raw binary file, it will essentially produce 1275a memory dump of the contents of the input object file. All symbols and 1276relocation information will be discarded. The memory dump will start at 1277the load address of the lowest section copied into the output file. 1278 1279When generating an S-record or a raw binary file, it may be helpful to 1280use @option{-S} to remove sections containing debugging information. In 1281some cases @option{-R} will be useful to remove sections which contain 1282information that is not needed by the binary file. 1283 1284Note---@command{objcopy} is not able to change the endianness of its input 1285files. If the input format has an endianness (some formats do not), 1286@command{objcopy} can only copy the inputs into file formats that have the 1287same endianness or which have no endianness (e.g., @samp{srec}). 1288(However, see the @option{--reverse-bytes} option.) 1289 1290@c man end 1291 1292@c man begin OPTIONS objcopy 1293 1294@table @env 1295@item @var{infile} 1296@itemx @var{outfile} 1297The input and output files, respectively. 1298If you do not specify @var{outfile}, @command{objcopy} creates a 1299temporary file and destructively renames the result with 1300the name of @var{infile}. 1301 1302@item -I @var{bfdname} 1303@itemx --input-target=@var{bfdname} 1304Consider the source file's object format to be @var{bfdname}, rather than 1305attempting to deduce it. @xref{Target Selection}, for more information. 1306 1307@item -O @var{bfdname} 1308@itemx --output-target=@var{bfdname} 1309Write the output file using the object format @var{bfdname}. 1310@xref{Target Selection}, for more information. 1311 1312@item -F @var{bfdname} 1313@itemx --target=@var{bfdname} 1314Use @var{bfdname} as the object format for both the input and the output 1315file; i.e., simply transfer data from source to destination with no 1316translation. @xref{Target Selection}, for more information. 1317 1318@item -B @var{bfdarch} 1319@itemx --binary-architecture=@var{bfdarch} 1320Useful when transforming a architecture-less input file into an object file. 1321In this case the output architecture can be set to @var{bfdarch}. This 1322option will be ignored if the input file has a known @var{bfdarch}. You 1323can access this binary data inside a program by referencing the special 1324symbols that are created by the conversion process. These symbols are 1325called _binary_@var{objfile}_start, _binary_@var{objfile}_end and 1326_binary_@var{objfile}_size. e.g. you can transform a picture file into 1327an object file and then access it in your code using these symbols. 1328 1329@item -j @var{sectionpattern} 1330@itemx --only-section=@var{sectionpattern} 1331Copy only the indicated sections from the input file to the output file. 1332This option may be given more than once. Note that using this option 1333inappropriately may make the output file unusable. Wildcard 1334characters are accepted in @var{sectionpattern}. 1335 1336If the first character of @var{sectionpattern} is the exclamation 1337point (!) then matching sections will not be copied, even if earlier 1338use of @option{--only-section} on the same command line would 1339otherwise copy it. For example: 1340 1341@smallexample 1342 --only-section=.text.* --only-section=!.text.foo 1343@end smallexample 1344 1345will copy all sectinos maching '.text.*' but not the section 1346'.text.foo'. 1347 1348@item -R @var{sectionpattern} 1349@itemx --remove-section=@var{sectionpattern} 1350Remove any section matching @var{sectionpattern} from the output file. 1351This option may be given more than once. Note that using this option 1352inappropriately may make the output file unusable. Wildcard 1353characters are accepted in @var{sectionpattern}. Using both the 1354@option{-j} and @option{-R} options together results in undefined 1355behaviour. 1356 1357If the first character of @var{sectionpattern} is the exclamation 1358point (!) then matching sections will not be removed even if an 1359earlier use of @option{--remove-section} on the same command line 1360would otherwise remove it. For example: 1361 1362@smallexample 1363 --remove-section=.text.* --remove-section=!.text.foo 1364@end smallexample 1365 1366will remove all sections matching the pattern '.text.*', but will not 1367remove the section '.text.foo'. 1368 1369@item --keep-section=@var{sectionpattern} 1370When removing sections from the output file, keep sections that match 1371@var{sectionpattern}. 1372 1373@item --remove-relocations=@var{sectionpattern} 1374Remove non-dynamic relocations from the output file for any section 1375matching @var{sectionpattern}. This option may be given more than 1376once. Note that using this option inappropriately may make the output 1377file unusable, and attempting to remove a dynamic relocation section 1378such as @samp{.rela.plt} from an executable or shared library with 1379@option{--remove-relocations=.plt} will not work. Wildcard characters 1380are accepted in @var{sectionpattern}. 1381For example: 1382 1383@smallexample 1384 --remove-relocations=.text.* 1385@end smallexample 1386 1387will remove the relocations for all sections matching the pattern 1388'.text.*'. 1389 1390If the first character of @var{sectionpattern} is the exclamation 1391point (!) then matching sections will not have their relocation 1392removed even if an earlier use of @option{--remove-relocations} on the 1393same command line would otherwise cause the relocations to be removed. 1394For example: 1395 1396@smallexample 1397 --remove-relocations=.text.* --remove-relocations=!.text.foo 1398@end smallexample 1399 1400will remove all relocations for sections matching the pattern 1401'.text.*', but will not remove relocations for the section 1402'.text.foo'. 1403 1404@item -S 1405@itemx --strip-all 1406Do not copy relocation and symbol information from the source file. 1407 1408@item -g 1409@itemx --strip-debug 1410Do not copy debugging symbols or sections from the source file. 1411 1412@item --strip-unneeded 1413Strip all symbols that are not needed for relocation processing. 1414 1415@item -K @var{symbolname} 1416@itemx --keep-symbol=@var{symbolname} 1417When stripping symbols, keep symbol @var{symbolname} even if it would 1418normally be stripped. This option may be given more than once. 1419 1420@item -N @var{symbolname} 1421@itemx --strip-symbol=@var{symbolname} 1422Do not copy symbol @var{symbolname} from the source file. This option 1423may be given more than once. 1424 1425@item --strip-unneeded-symbol=@var{symbolname} 1426Do not copy symbol @var{symbolname} from the source file unless it is needed 1427by a relocation. This option may be given more than once. 1428 1429@item -G @var{symbolname} 1430@itemx --keep-global-symbol=@var{symbolname} 1431Keep only symbol @var{symbolname} global. Make all other symbols local 1432to the file, so that they are not visible externally. This option may 1433be given more than once. Note: this option cannot be used in 1434conjunction with the @option{--globalize-symbol} or 1435@option{--globalize-symbols} options. 1436 1437@item --localize-hidden 1438In an ELF object, mark all symbols that have hidden or internal visibility 1439as local. This option applies on top of symbol-specific localization options 1440such as @option{-L}. 1441 1442@item -L @var{symbolname} 1443@itemx --localize-symbol=@var{symbolname} 1444Convert a global or weak symbol called @var{symbolname} into a local 1445symbol, so that it is not visible externally. This option may be 1446given more than once. Note - unique symbols are not converted. 1447 1448@item -W @var{symbolname} 1449@itemx --weaken-symbol=@var{symbolname} 1450Make symbol @var{symbolname} weak. This option may be given more than once. 1451 1452@item --globalize-symbol=@var{symbolname} 1453Give symbol @var{symbolname} global scoping so that it is visible 1454outside of the file in which it is defined. This option may be given 1455more than once. Note: this option cannot be used in conjunction with 1456the @option{-G} or @option{--keep-global-symbol} options. 1457 1458@item -w 1459@itemx --wildcard 1460Permit regular expressions in @var{symbolname}s used in other command 1461line options. The question mark (?), asterisk (*), backslash (\) and 1462square brackets ([]) operators can be used anywhere in the symbol 1463name. If the first character of the symbol name is the exclamation 1464point (!) then the sense of the switch is reversed for that symbol. 1465For example: 1466 1467@smallexample 1468 -w -W !foo -W fo* 1469@end smallexample 1470 1471would cause objcopy to weaken all symbols that start with ``fo'' 1472except for the symbol ``foo''. 1473 1474@item -x 1475@itemx --discard-all 1476Do not copy non-global symbols from the source file. 1477@c FIXME any reason to prefer "non-global" to "local" here? 1478 1479@item -X 1480@itemx --discard-locals 1481Do not copy compiler-generated local symbols. 1482(These usually start with @samp{L} or @samp{.}.) 1483 1484@item -b @var{byte} 1485@itemx --byte=@var{byte} 1486If interleaving has been enabled via the @option{--interleave} option 1487then start the range of bytes to keep at the @var{byte}th byte. 1488@var{byte} can be in the range from 0 to @var{breadth}-1, where 1489@var{breadth} is the value given by the @option{--interleave} option. 1490 1491@item -i [@var{breadth}] 1492@itemx --interleave[=@var{breadth}] 1493Only copy a range out of every @var{breadth} bytes. (Header data is 1494not affected). Select which byte in the range begins the copy with 1495the @option{--byte} option. Select the width of the range with the 1496@option{--interleave-width} option. 1497 1498This option is useful for creating files to program @sc{rom}. It is 1499typically used with an @code{srec} output target. Note that 1500@command{objcopy} will complain if you do not specify the 1501@option{--byte} option as well. 1502 1503The default interleave breadth is 4, so with @option{--byte} set to 0, 1504@command{objcopy} would copy the first byte out of every four bytes 1505from the input to the output. 1506 1507@item --interleave-width=@var{width} 1508When used with the @option{--interleave} option, copy @var{width} 1509bytes at a time. The start of the range of bytes to be copied is set 1510by the @option{--byte} option, and the extent of the range is set with 1511the @option{--interleave} option. 1512 1513The default value for this option is 1. The value of @var{width} plus 1514the @var{byte} value set by the @option{--byte} option must not exceed 1515the interleave breadth set by the @option{--interleave} option. 1516 1517This option can be used to create images for two 16-bit flashes interleaved 1518in a 32-bit bus by passing @option{-b 0 -i 4 --interleave-width=2} 1519and @option{-b 2 -i 4 --interleave-width=2} to two @command{objcopy} 1520commands. If the input was '12345678' then the outputs would be 1521'1256' and '3478' respectively. 1522 1523@item -p 1524@itemx --preserve-dates 1525Set the access and modification dates of the output file to be the same 1526as those of the input file. 1527 1528@item -D 1529@itemx --enable-deterministic-archives 1530@cindex deterministic archives 1531@kindex --enable-deterministic-archives 1532Operate in @emph{deterministic} mode. When copying archive members 1533and writing the archive index, use zero for UIDs, GIDs, timestamps, 1534and use consistent file modes for all files. 1535 1536If @file{binutils} was configured with 1537@option{--enable-deterministic-archives}, then this mode is on by default. 1538It can be disabled with the @samp{-U} option, below. 1539 1540@item -U 1541@itemx --disable-deterministic-archives 1542@cindex deterministic archives 1543@kindex --enable-deterministic-archives 1544Do @emph{not} operate in @emph{deterministic} mode. This is the 1545inverse of the @option{-D} option, above: when copying archive members 1546and writing the archive index, use their actual UID, GID, timestamp, 1547and file mode values. 1548 1549This is the default unless @file{binutils} was configured with 1550@option{--enable-deterministic-archives}. 1551 1552@item --debugging 1553Convert debugging information, if possible. This is not the default 1554because only certain debugging formats are supported, and the 1555conversion process can be time consuming. 1556 1557@item --gap-fill @var{val} 1558Fill gaps between sections with @var{val}. This operation applies to 1559the @emph{load address} (LMA) of the sections. It is done by increasing 1560the size of the section with the lower address, and filling in the extra 1561space created with @var{val}. 1562 1563@item --pad-to @var{address} 1564Pad the output file up to the load address @var{address}. This is 1565done by increasing the size of the last section. The extra space is 1566filled in with the value specified by @option{--gap-fill} (default zero). 1567 1568@item --set-start @var{val} 1569Set the start address (also known as the entry address) of the new 1570file to @var{val}. Not all object file formats support setting the 1571start address. 1572 1573@item --change-start @var{incr} 1574@itemx --adjust-start @var{incr} 1575@cindex changing start address 1576Change the start address (also known as the entry address) by adding 1577@var{incr}. Not all object file formats support setting the start 1578address. 1579 1580@item --change-addresses @var{incr} 1581@itemx --adjust-vma @var{incr} 1582@cindex changing object addresses 1583Change the VMA and LMA addresses of all sections, as well as the start 1584address, by adding @var{incr}. Some object file formats do not permit 1585section addresses to be changed arbitrarily. Note that this does not 1586relocate the sections; if the program expects sections to be loaded at a 1587certain address, and this option is used to change the sections such 1588that they are loaded at a different address, the program may fail. 1589 1590@item --change-section-address @var{sectionpattern}@{=,+,-@}@var{val} 1591@itemx --adjust-section-vma @var{sectionpattern}@{=,+,-@}@var{val} 1592@cindex changing section address 1593Set or change both the VMA address and the LMA address of any section 1594matching @var{sectionpattern}. If @samp{=} is used, the section 1595address is set to @var{val}. Otherwise, @var{val} is added to or 1596subtracted from the section address. See the comments under 1597@option{--change-addresses}, above. If @var{sectionpattern} does not 1598match any sections in the input file, a warning will be issued, unless 1599@option{--no-change-warnings} is used. 1600 1601@item --change-section-lma @var{sectionpattern}@{=,+,-@}@var{val} 1602@cindex changing section LMA 1603Set or change the LMA address of any sections matching 1604@var{sectionpattern}. The LMA address is the address where the 1605section will be loaded into memory at program load time. Normally 1606this is the same as the VMA address, which is the address of the 1607section at program run time, but on some systems, especially those 1608where a program is held in ROM, the two can be different. If @samp{=} 1609is used, the section address is set to @var{val}. Otherwise, 1610@var{val} is added to or subtracted from the section address. See the 1611comments under @option{--change-addresses}, above. If 1612@var{sectionpattern} does not match any sections in the input file, a 1613warning will be issued, unless @option{--no-change-warnings} is used. 1614 1615@item --change-section-vma @var{sectionpattern}@{=,+,-@}@var{val} 1616@cindex changing section VMA 1617Set or change the VMA address of any section matching 1618@var{sectionpattern}. The VMA address is the address where the 1619section will be located once the program has started executing. 1620Normally this is the same as the LMA address, which is the address 1621where the section will be loaded into memory, but on some systems, 1622especially those where a program is held in ROM, the two can be 1623different. If @samp{=} is used, the section address is set to 1624@var{val}. Otherwise, @var{val} is added to or subtracted from the 1625section address. See the comments under @option{--change-addresses}, 1626above. If @var{sectionpattern} does not match any sections in the 1627input file, a warning will be issued, unless 1628@option{--no-change-warnings} is used. 1629 1630@item --change-warnings 1631@itemx --adjust-warnings 1632If @option{--change-section-address} or @option{--change-section-lma} or 1633@option{--change-section-vma} is used, and the section pattern does not 1634match any sections, issue a warning. This is the default. 1635 1636@item --no-change-warnings 1637@itemx --no-adjust-warnings 1638Do not issue a warning if @option{--change-section-address} or 1639@option{--adjust-section-lma} or @option{--adjust-section-vma} is used, even 1640if the section pattern does not match any sections. 1641 1642@item --set-section-flags @var{sectionpattern}=@var{flags} 1643Set the flags for any sections matching @var{sectionpattern}. The 1644@var{flags} argument is a comma separated string of flag names. The 1645recognized names are @samp{alloc}, @samp{contents}, @samp{load}, 1646@samp{noload}, @samp{readonly}, @samp{code}, @samp{data}, @samp{rom}, 1647@samp{exclude}, @samp{share}, and @samp{debug}. You can set the 1648@samp{contents} flag for a section which does not have contents, but it 1649is not meaningful to clear the @samp{contents} flag of a section which 1650does have contents--just remove the section instead. Not all flags are 1651meaningful for all object file formats. In particular the 1652@samp{share} flag is only meaningful for COFF format files and not for 1653ELF format files. 1654 1655@item --set-section-alignment @var{sectionpattern}=@var{align} 1656Set the alignment for any sections matching @var{sectionpattern}. 1657@var{align} specifies the alignment in bytes and must be a power of 1658two, i.e. 1, 2, 4, 8@dots{}. 1659 1660@item --add-section @var{sectionname}=@var{filename} 1661Add a new section named @var{sectionname} while copying the file. The 1662contents of the new section are taken from the file @var{filename}. The 1663size of the section will be the size of the file. This option only 1664works on file formats which can support sections with arbitrary names. 1665Note - it may be necessary to use the @option{--set-section-flags} 1666option to set the attributes of the newly created section. 1667 1668@item --dump-section @var{sectionname}=@var{filename} 1669Place the contents of section named @var{sectionname} into the file 1670@var{filename}, overwriting any contents that may have been there 1671previously. This option is the inverse of @option{--add-section}. 1672This option is similar to the @option{--only-section} option except 1673that it does not create a formatted file, it just dumps the contents 1674as raw binary data, without applying any relocations. The option can 1675be specified more than once. 1676 1677@item --update-section @var{sectionname}=@var{filename} 1678Replace the existing contents of a section named @var{sectionname} 1679with the contents of file @var{filename}. The size of the section 1680will be adjusted to the size of the file. The section flags for 1681@var{sectionname} will be unchanged. For ELF format files the section 1682to segment mapping will also remain unchanged, something which is not 1683possible using @option{--remove-section} followed by 1684@option{--add-section}. The option can be specified more than once. 1685 1686Note - it is possible to use @option{--rename-section} and 1687@option{--update-section} to both update and rename a section from one 1688command line. In this case, pass the original section name to 1689@option{--update-section}, and the original and new section names to 1690@option{--rename-section}. 1691 1692@item --add-symbol @var{name}=[@var{section}:]@var{value}[,@var{flags}] 1693Add a new symbol named @var{name} while copying the file. This option may be 1694specified multiple times. If the @var{section} is given, the symbol will be 1695associated with and relative to that section, otherwise it will be an ABS 1696symbol. Specifying an undefined section will result in a fatal error. There 1697is no check for the value, it will be taken as specified. Symbol flags can 1698be specified and not all flags will be meaningful for all object file 1699formats. By default, the symbol will be global. The special flag 1700'before=@var{othersym}' will insert the new symbol in front of the specified 1701@var{othersym}, otherwise the symbol(s) will be added at the end of the 1702symbol table in the order they appear. 1703 1704@item --rename-section @var{oldname}=@var{newname}[,@var{flags}] 1705Rename a section from @var{oldname} to @var{newname}, optionally 1706changing the section's flags to @var{flags} in the process. This has 1707the advantage over using a linker script to perform the rename in that 1708the output stays as an object file and does not become a linked 1709executable. This option accepts the same set of flags as the 1710@option{--sect-section-flags} option. 1711 1712This option is particularly helpful when the input format is binary, 1713since this will always create a section called .data. If for example, 1714you wanted instead to create a section called .rodata containing binary 1715data you could use the following command line to achieve it: 1716 1717@smallexample 1718 objcopy -I binary -O <output_format> -B <architecture> \ 1719 --rename-section .data=.rodata,alloc,load,readonly,data,contents \ 1720 <input_binary_file> <output_object_file> 1721@end smallexample 1722 1723@item --long-section-names @{enable,disable,keep@} 1724Controls the handling of long section names when processing @code{COFF} 1725and @code{PE-COFF} object formats. The default behaviour, @samp{keep}, 1726is to preserve long section names if any are present in the input file. 1727The @samp{enable} and @samp{disable} options forcibly enable or disable 1728the use of long section names in the output object; when @samp{disable} 1729is in effect, any long section names in the input object will be truncated. 1730The @samp{enable} option will only emit long section names if any are 1731present in the inputs; this is mostly the same as @samp{keep}, but it 1732is left undefined whether the @samp{enable} option might force the 1733creation of an empty string table in the output file. 1734 1735@item --change-leading-char 1736Some object file formats use special characters at the start of 1737symbols. The most common such character is underscore, which compilers 1738often add before every symbol. This option tells @command{objcopy} to 1739change the leading character of every symbol when it converts between 1740object file formats. If the object file formats use the same leading 1741character, this option has no effect. Otherwise, it will add a 1742character, or remove a character, or change a character, as 1743appropriate. 1744 1745@item --remove-leading-char 1746If the first character of a global symbol is a special symbol leading 1747character used by the object file format, remove the character. The 1748most common symbol leading character is underscore. This option will 1749remove a leading underscore from all global symbols. This can be useful 1750if you want to link together objects of different file formats with 1751different conventions for symbol names. This is different from 1752@option{--change-leading-char} because it always changes the symbol name 1753when appropriate, regardless of the object file format of the output 1754file. 1755 1756@item --reverse-bytes=@var{num} 1757Reverse the bytes in a section with output contents. A section length must 1758be evenly divisible by the value given in order for the swap to be able to 1759take place. Reversing takes place before the interleaving is performed. 1760 1761This option is used typically in generating ROM images for problematic 1762target systems. For example, on some target boards, the 32-bit words 1763fetched from 8-bit ROMs are re-assembled in little-endian byte order 1764regardless of the CPU byte order. Depending on the programming model, the 1765endianness of the ROM may need to be modified. 1766 1767Consider a simple file with a section containing the following eight 1768bytes: @code{12345678}. 1769 1770Using @samp{--reverse-bytes=2} for the above example, the bytes in the 1771output file would be ordered @code{21436587}. 1772 1773Using @samp{--reverse-bytes=4} for the above example, the bytes in the 1774output file would be ordered @code{43218765}. 1775 1776By using @samp{--reverse-bytes=2} for the above example, followed by 1777@samp{--reverse-bytes=4} on the output file, the bytes in the second 1778output file would be ordered @code{34127856}. 1779 1780@item --srec-len=@var{ival} 1781Meaningful only for srec output. Set the maximum length of the Srecords 1782being produced to @var{ival}. This length covers both address, data and 1783crc fields. 1784 1785@item --srec-forceS3 1786Meaningful only for srec output. Avoid generation of S1/S2 records, 1787creating S3-only record format. 1788 1789@item --redefine-sym @var{old}=@var{new} 1790Change the name of a symbol @var{old}, to @var{new}. This can be useful 1791when one is trying link two things together for which you have no 1792source, and there are name collisions. 1793 1794@item --redefine-syms=@var{filename} 1795Apply @option{--redefine-sym} to each symbol pair "@var{old} @var{new}" 1796listed in the file @var{filename}. @var{filename} is simply a flat file, 1797with one symbol pair per line. Line comments may be introduced by the hash 1798character. This option may be given more than once. 1799 1800@item --weaken 1801Change all global symbols in the file to be weak. This can be useful 1802when building an object which will be linked against other objects using 1803the @option{-R} option to the linker. This option is only effective when 1804using an object file format which supports weak symbols. 1805 1806@item --keep-symbols=@var{filename} 1807Apply @option{--keep-symbol} option to each symbol listed in the file 1808@var{filename}. @var{filename} is simply a flat file, with one symbol 1809name per line. Line comments may be introduced by the hash character. 1810This option may be given more than once. 1811 1812@item --strip-symbols=@var{filename} 1813Apply @option{--strip-symbol} option to each symbol listed in the file 1814@var{filename}. @var{filename} is simply a flat file, with one symbol 1815name per line. Line comments may be introduced by the hash character. 1816This option may be given more than once. 1817 1818@item --strip-unneeded-symbols=@var{filename} 1819Apply @option{--strip-unneeded-symbol} option to each symbol listed in 1820the file @var{filename}. @var{filename} is simply a flat file, with one 1821symbol name per line. Line comments may be introduced by the hash 1822character. This option may be given more than once. 1823 1824@item --keep-global-symbols=@var{filename} 1825Apply @option{--keep-global-symbol} option to each symbol listed in the 1826file @var{filename}. @var{filename} is simply a flat file, with one 1827symbol name per line. Line comments may be introduced by the hash 1828character. This option may be given more than once. 1829 1830@item --localize-symbols=@var{filename} 1831Apply @option{--localize-symbol} option to each symbol listed in the file 1832@var{filename}. @var{filename} is simply a flat file, with one symbol 1833name per line. Line comments may be introduced by the hash character. 1834This option may be given more than once. 1835 1836@item --globalize-symbols=@var{filename} 1837Apply @option{--globalize-symbol} option to each symbol listed in the file 1838@var{filename}. @var{filename} is simply a flat file, with one symbol 1839name per line. Line comments may be introduced by the hash character. 1840This option may be given more than once. Note: this option cannot be 1841used in conjunction with the @option{-G} or @option{--keep-global-symbol} 1842options. 1843 1844@item --weaken-symbols=@var{filename} 1845Apply @option{--weaken-symbol} option to each symbol listed in the file 1846@var{filename}. @var{filename} is simply a flat file, with one symbol 1847name per line. Line comments may be introduced by the hash character. 1848This option may be given more than once. 1849 1850@item --alt-machine-code=@var{index} 1851If the output architecture has alternate machine codes, use the 1852@var{index}th code instead of the default one. This is useful in case 1853a machine is assigned an official code and the tool-chain adopts the 1854new code, but other applications still depend on the original code 1855being used. For ELF based architectures if the @var{index} 1856alternative does not exist then the value is treated as an absolute 1857number to be stored in the e_machine field of the ELF header. 1858 1859@item --writable-text 1860Mark the output text as writable. This option isn't meaningful for all 1861object file formats. 1862 1863@item --readonly-text 1864Make the output text write protected. This option isn't meaningful for all 1865object file formats. 1866 1867@item --pure 1868Mark the output file as demand paged. This option isn't meaningful for all 1869object file formats. 1870 1871@item --impure 1872Mark the output file as impure. This option isn't meaningful for all 1873object file formats. 1874 1875@item --prefix-symbols=@var{string} 1876Prefix all symbols in the output file with @var{string}. 1877 1878@item --prefix-sections=@var{string} 1879Prefix all section names in the output file with @var{string}. 1880 1881@item --prefix-alloc-sections=@var{string} 1882Prefix all the names of all allocated sections in the output file with 1883@var{string}. 1884 1885@item --add-gnu-debuglink=@var{path-to-file} 1886Creates a .gnu_debuglink section which contains a reference to 1887@var{path-to-file} and adds it to the output file. Note: the file at 1888@var{path-to-file} must exist. Part of the process of adding the 1889.gnu_debuglink section involves embedding a checksum of the contents 1890of the debug info file into the section. 1891 1892If the debug info file is built in one location but it is going to be 1893installed at a later time into a different location then do not use 1894the path to the installed location. The @option{--add-gnu-debuglink} 1895option will fail because the installed file does not exist yet. 1896Instead put the debug info file in the current directory and use the 1897@option{--add-gnu-debuglink} option without any directory components, 1898like this: 1899 1900@smallexample 1901 objcopy --add-gnu-debuglink=foo.debug 1902@end smallexample 1903 1904At debug time the debugger will attempt to look for the separate debug 1905info file in a set of known locations. The exact set of these 1906locations varies depending upon the distribution being used, but it 1907typically includes: 1908 1909@table @code 1910 1911@item * The same directory as the executable. 1912 1913@item * A sub-directory of the directory containing the executable 1914called .debug 1915 1916@item * A global debug directory such as /usr/lib/debug. 1917@end table 1918 1919As long as the debug info file has been installed into one of these 1920locations before the debugger is run everything should work 1921correctly. 1922 1923@item --keep-file-symbols 1924When stripping a file, perhaps with @option{--strip-debug} or 1925@option{--strip-unneeded}, retain any symbols specifying source file names, 1926which would otherwise get stripped. 1927 1928@item --only-keep-debug 1929Strip a file, removing contents of any sections that would not be 1930stripped by @option{--strip-debug} and leaving the debugging sections 1931intact. In ELF files, this preserves all note sections in the output. 1932 1933Note - the section headers of the stripped sections are preserved, 1934including their sizes, but the contents of the section are discarded. 1935The section headers are preserved so that other tools can match up the 1936debuginfo file with the real executable, even if that executable has 1937been relocated to a different address space. 1938 1939The intention is that this option will be used in conjunction with 1940@option{--add-gnu-debuglink} to create a two part executable. One a 1941stripped binary which will occupy less space in RAM and in a 1942distribution and the second a debugging information file which is only 1943needed if debugging abilities are required. The suggested procedure 1944to create these files is as follows: 1945 1946@enumerate 1947@item Link the executable as normal. Assuming that it is called 1948@code{foo} then... 1949@item Run @code{objcopy --only-keep-debug foo foo.dbg} to 1950create a file containing the debugging info. 1951@item Run @code{objcopy --strip-debug foo} to create a 1952stripped executable. 1953@item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo} 1954to add a link to the debugging info into the stripped executable. 1955@end enumerate 1956 1957Note---the choice of @code{.dbg} as an extension for the debug info 1958file is arbitrary. Also the @code{--only-keep-debug} step is 1959optional. You could instead do this: 1960 1961@enumerate 1962@item Link the executable as normal. 1963@item Copy @code{foo} to @code{foo.full} 1964@item Run @code{objcopy --strip-debug foo} 1965@item Run @code{objcopy --add-gnu-debuglink=foo.full foo} 1966@end enumerate 1967 1968i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the 1969full executable. It does not have to be a file created by the 1970@option{--only-keep-debug} switch. 1971 1972Note---this switch is only intended for use on fully linked files. It 1973does not make sense to use it on object files where the debugging 1974information may be incomplete. Besides the gnu_debuglink feature 1975currently only supports the presence of one filename containing 1976debugging information, not multiple filenames on a one-per-object-file 1977basis. 1978 1979@item --strip-dwo 1980Remove the contents of all DWARF .dwo sections, leaving the 1981remaining debugging sections and all symbols intact. 1982This option is intended for use by the compiler as part of 1983the @option{-gsplit-dwarf} option, which splits debug information 1984between the .o file and a separate .dwo file. The compiler 1985generates all debug information in the same file, then uses 1986the @option{--extract-dwo} option to copy the .dwo sections to 1987the .dwo file, then the @option{--strip-dwo} option to remove 1988those sections from the original .o file. 1989 1990@item --extract-dwo 1991Extract the contents of all DWARF .dwo sections. See the 1992@option{--strip-dwo} option for more information. 1993 1994@item --file-alignment @var{num} 1995Specify the file alignment. Sections in the file will always begin at 1996file offsets which are multiples of this number. This defaults to 1997512. 1998[This option is specific to PE targets.] 1999 2000@item --heap @var{reserve} 2001@itemx --heap @var{reserve},@var{commit} 2002Specify the number of bytes of memory to reserve (and optionally commit) 2003to be used as heap for this program. 2004[This option is specific to PE targets.] 2005 2006@item --image-base @var{value} 2007Use @var{value} as the base address of your program or dll. This is 2008the lowest memory location that will be used when your program or dll 2009is loaded. To reduce the need to relocate and improve performance of 2010your dlls, each should have a unique base address and not overlap any 2011other dlls. The default is 0x400000 for executables, and 0x10000000 2012for dlls. 2013[This option is specific to PE targets.] 2014 2015@item --section-alignment @var{num} 2016Sets the section alignment field in the PE header. Sections in memory 2017will always begin at addresses which are a multiple of this number. 2018Defaults to 0x1000. 2019[This option is specific to PE targets.] 2020 2021@item --stack @var{reserve} 2022@itemx --stack @var{reserve},@var{commit} 2023Specify the number of bytes of memory to reserve (and optionally commit) 2024to be used as stack for this program. 2025[This option is specific to PE targets.] 2026 2027@item --subsystem @var{which} 2028@itemx --subsystem @var{which}:@var{major} 2029@itemx --subsystem @var{which}:@var{major}.@var{minor} 2030Specifies the subsystem under which your program will execute. The 2031legal values for @var{which} are @code{native}, @code{windows}, 2032@code{console}, @code{posix}, @code{efi-app}, @code{efi-bsd}, 2033@code{efi-rtd}, @code{sal-rtd}, and @code{xbox}. You may optionally set 2034the subsystem version also. Numeric values are also accepted for 2035@var{which}. 2036[This option is specific to PE targets.] 2037 2038@item --extract-symbol 2039Keep the file's section flags and symbols but remove all section data. 2040Specifically, the option: 2041 2042@itemize 2043@item removes the contents of all sections; 2044@item sets the size of every section to zero; and 2045@item sets the file's start address to zero. 2046@end itemize 2047 2048This option is used to build a @file{.sym} file for a VxWorks kernel. 2049It can also be a useful way of reducing the size of a @option{--just-symbols} 2050linker input file. 2051 2052@item --compress-debug-sections 2053Compress DWARF debug sections using zlib with SHF_COMPRESSED from the 2054ELF ABI. Note - if compression would actually make a section 2055@emph{larger}, then it is not compressed. 2056 2057@item --compress-debug-sections=none 2058@itemx --compress-debug-sections=zlib 2059@itemx --compress-debug-sections=zlib-gnu 2060@itemx --compress-debug-sections=zlib-gabi 2061For ELF files, these options control how DWARF debug sections are 2062compressed. @option{--compress-debug-sections=none} is equivalent 2063to @option{--decompress-debug-sections}. 2064@option{--compress-debug-sections=zlib} and 2065@option{--compress-debug-sections=zlib-gabi} are equivalent to 2066@option{--compress-debug-sections}. 2067@option{--compress-debug-sections=zlib-gnu} compresses DWARF debug 2068sections using zlib. The debug sections are renamed to begin with 2069@samp{.zdebug} instead of @samp{.debug}. Note - if compression would 2070actually make a section @emph{larger}, then it is not compressed nor 2071renamed. 2072 2073@item --decompress-debug-sections 2074Decompress DWARF debug sections using zlib. The original section 2075names of the compressed sections are restored. 2076 2077@item --elf-stt-common=yes 2078@itemx --elf-stt-common=no 2079For ELF files, these options control whether common symbols should be 2080converted to the @code{STT_COMMON} or @code{STT_OBJECT} type. 2081@option{--elf-stt-common=yes} converts common symbol type to 2082@code{STT_COMMON}. @option{--elf-stt-common=no} converts common symbol 2083type to @code{STT_OBJECT}. 2084 2085@item --merge-notes 2086@itemx --no-merge-notes 2087For ELF files, attempt (or do not attempt) to reduce the size of any 2088SHT_NOTE type sections by removing duplicate notes. 2089 2090@item -V 2091@itemx --version 2092Show the version number of @command{objcopy}. 2093 2094@item --verilog-data-width=@var{bytes} 2095For Verilog output, this options controls the number of bytes 2096converted for each output data element. The input target controls the 2097endianness of the conversion. 2098 2099@item -v 2100@itemx --verbose 2101Verbose output: list all object files modified. In the case of 2102archives, @samp{objcopy -V} lists all members of the archive. 2103 2104@item --help 2105Show a summary of the options to @command{objcopy}. 2106 2107@item --info 2108Display a list showing all architectures and object formats available. 2109@end table 2110 2111@c man end 2112 2113@ignore 2114@c man begin SEEALSO objcopy 2115ld(1), objdump(1), and the Info entries for @file{binutils}. 2116@c man end 2117@end ignore 2118 2119@node objdump 2120@chapter objdump 2121 2122@cindex object file information 2123@kindex objdump 2124 2125@c man title objdump display information from object files 2126 2127@smallexample 2128@c man begin SYNOPSIS objdump 2129objdump [@option{-a}|@option{--archive-headers}] 2130 [@option{-b} @var{bfdname}|@option{--target=@var{bfdname}}] 2131 [@option{-C}|@option{--demangle}[=@var{style}] ] 2132 [@option{-d}|@option{--disassemble}[=@var{symbol}]] 2133 [@option{-D}|@option{--disassemble-all}] 2134 [@option{-z}|@option{--disassemble-zeroes}] 2135 [@option{-EB}|@option{-EL}|@option{--endian=}@{big | little @}] 2136 [@option{-f}|@option{--file-headers}] 2137 [@option{-F}|@option{--file-offsets}] 2138 [@option{--file-start-context}] 2139 [@option{-g}|@option{--debugging}] 2140 [@option{-e}|@option{--debugging-tags}] 2141 [@option{-h}|@option{--section-headers}|@option{--headers}] 2142 [@option{-i}|@option{--info}] 2143 [@option{-j} @var{section}|@option{--section=}@var{section}] 2144 [@option{-l}|@option{--line-numbers}] 2145 [@option{-S}|@option{--source}] 2146 [@option{--source-comment}[=@var{text}]] 2147 [@option{-m} @var{machine}|@option{--architecture=}@var{machine}] 2148 [@option{-M} @var{options}|@option{--disassembler-options=}@var{options}] 2149 [@option{-p}|@option{--private-headers}] 2150 [@option{-P} @var{options}|@option{--private=}@var{options}] 2151 [@option{-r}|@option{--reloc}] 2152 [@option{-R}|@option{--dynamic-reloc}] 2153 [@option{-s}|@option{--full-contents}] 2154 [@option{-W[lLiaprmfFsoORtUuTgAckK]}| 2155 @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,=follow-links]] 2156 [@option{--ctf=}@var{section}] 2157 [@option{-G}|@option{--stabs}] 2158 [@option{-t}|@option{--syms}] 2159 [@option{-T}|@option{--dynamic-syms}] 2160 [@option{-x}|@option{--all-headers}] 2161 [@option{-w}|@option{--wide}] 2162 [@option{--start-address=}@var{address}] 2163 [@option{--stop-address=}@var{address}] 2164 [@option{--no-addresses}] 2165 [@option{--prefix-addresses}] 2166 [@option{--[no-]show-raw-insn}] 2167 [@option{--adjust-vma=}@var{offset}] 2168 [@option{--dwarf-depth=@var{n}}] 2169 [@option{--dwarf-start=@var{n}}] 2170 [@option{--ctf-parent=}@var{section}] 2171 [@option{--no-recurse-limit}|@option{--recurse-limit}] 2172 [@option{--special-syms}] 2173 [@option{--prefix=}@var{prefix}] 2174 [@option{--prefix-strip=}@var{level}] 2175 [@option{--insn-width=}@var{width}] 2176 [@option{--visualize-jumps[=color|=extended-color|=off]} 2177 [@option{-V}|@option{--version}] 2178 [@option{-H}|@option{--help}] 2179 @var{objfile}@dots{} 2180@c man end 2181@end smallexample 2182 2183@c man begin DESCRIPTION objdump 2184 2185@command{objdump} displays information about one or more object files. 2186The options control what particular information to display. This 2187information is mostly useful to programmers who are working on the 2188compilation tools, as opposed to programmers who just want their 2189program to compile and work. 2190 2191@var{objfile}@dots{} are the object files to be examined. When you 2192specify archives, @command{objdump} shows information on each of the member 2193object files. 2194 2195@c man end 2196 2197@c man begin OPTIONS objdump 2198 2199The long and short forms of options, shown here as alternatives, are 2200equivalent. At least one option from the list 2201@option{-a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-P,-r,-R,-s,-S,-t,-T,-V,-x} must be given. 2202 2203@table @env 2204@item -a 2205@itemx --archive-header 2206@cindex archive headers 2207If any of the @var{objfile} files are archives, display the archive 2208header information (in a format similar to @samp{ls -l}). Besides the 2209information you could list with @samp{ar tv}, @samp{objdump -a} shows 2210the object file format of each archive member. 2211 2212@item --adjust-vma=@var{offset} 2213@cindex section addresses in objdump 2214@cindex VMA in objdump 2215When dumping information, first add @var{offset} to all the section 2216addresses. This is useful if the section addresses do not correspond to 2217the symbol table, which can happen when putting sections at particular 2218addresses when using a format which can not represent section addresses, 2219such as a.out. 2220 2221@item -b @var{bfdname} 2222@itemx --target=@var{bfdname} 2223@cindex object code format 2224Specify that the object-code format for the object files is 2225@var{bfdname}. This option may not be necessary; @var{objdump} can 2226automatically recognize many formats. 2227 2228For example, 2229@example 2230objdump -b oasys -m vax -h fu.o 2231@end example 2232@noindent 2233displays summary information from the section headers (@option{-h}) of 2234@file{fu.o}, which is explicitly identified (@option{-m}) as a VAX object 2235file in the format produced by Oasys compilers. You can list the 2236formats available with the @option{-i} option. 2237@xref{Target Selection}, for more information. 2238 2239@item -C 2240@itemx --demangle[=@var{style}] 2241@cindex demangling in objdump 2242Decode (@dfn{demangle}) low-level symbol names into user-level names. 2243Besides removing any initial underscore prepended by the system, this 2244makes C++ function names readable. Different compilers have different 2245mangling styles. The optional demangling style argument can be used to 2246choose an appropriate demangling style for your compiler. @xref{c++filt}, 2247for more information on demangling. 2248 2249@item --recurse-limit 2250@itemx --no-recurse-limit 2251@itemx --recursion-limit 2252@itemx --no-recursion-limit 2253Enables or disables a limit on the amount of recursion performed 2254whilst demangling strings. Since the name mangling formats allow for 2255an inifinite level of recursion it is possible to create strings whose 2256decoding will exhaust the amount of stack space available on the host 2257machine, triggering a memory fault. The limit tries to prevent this 2258from happening by restricting recursion to 2048 levels of nesting. 2259 2260The default is for this limit to be enabled, but disabling it may be 2261necessary in order to demangle truly complicated names. Note however 2262that if the recursion limit is disabled then stack exhaustion is 2263possible and any bug reports about such an event will be rejected. 2264 2265@item -g 2266@itemx --debugging 2267Display debugging information. This attempts to parse STABS 2268debugging format information stored in the file and print it out using 2269a C like syntax. If no STABS debugging was found this option 2270falls back on the @option{-W} option to print any DWARF information in 2271the file. 2272 2273@item -e 2274@itemx --debugging-tags 2275Like @option{-g}, but the information is generated in a format compatible 2276with ctags tool. 2277 2278@item -d 2279@itemx --disassemble 2280@itemx --disassemble=@var{symbol} 2281@cindex disassembling object code 2282@cindex machine instructions 2283Display the assembler mnemonics for the machine instructions from the 2284input file. This option only disassembles those sections which are 2285expected to contain instructions. If the optional @var{symbol} 2286argument is given, then display the assembler mnemonics starting at 2287@var{symbol}. If @var{symbol} is a function name then disassembly 2288will stop at the end of the function, otherwise it will stop when the 2289next symbol is encountered. If there are no matches for @var{symbol} 2290then nothing will be displayed. 2291 2292Note if the @option{--dwarf=follow-links} option has also been enabled 2293then any symbol tables in linked debug info files will be read in and 2294used when disassembling. 2295 2296@item -D 2297@itemx --disassemble-all 2298Like @option{-d}, but disassemble the contents of all sections, not just 2299those expected to contain instructions. 2300 2301This option also has a subtle effect on the disassembly of 2302instructions in code sections. When option @option{-d} is in effect 2303objdump will assume that any symbols present in a code section occur 2304on the boundary between instructions and it will refuse to disassemble 2305across such a boundary. When option @option{-D} is in effect however 2306this assumption is supressed. This means that it is possible for the 2307output of @option{-d} and @option{-D} to differ if, for example, data 2308is stored in code sections. 2309 2310If the target is an ARM architecture this switch also has the effect 2311of forcing the disassembler to decode pieces of data found in code 2312sections as if they were instructions. 2313 2314Note if the @option{--dwarf=follow-links} option has also been enabled 2315then any symbol tables in linked debug info files will be read in and 2316used when disassembling. 2317 2318@item --no-addresses 2319When disassembling, don't print addresses on each line or for symbols 2320and relocation offsets. In combination with @option{--no-show-raw-insn} 2321this may be useful for comparing compiler output. 2322 2323@item --prefix-addresses 2324When disassembling, print the complete address on each line. This is 2325the older disassembly format. 2326 2327@item -EB 2328@itemx -EL 2329@itemx --endian=@{big|little@} 2330@cindex endianness 2331@cindex disassembly endianness 2332Specify the endianness of the object files. This only affects 2333disassembly. This can be useful when disassembling a file format which 2334does not describe endianness information, such as S-records. 2335 2336@item -f 2337@itemx --file-headers 2338@cindex object file header 2339Display summary information from the overall header of 2340each of the @var{objfile} files. 2341 2342@item -F 2343@itemx --file-offsets 2344@cindex object file offsets 2345When disassembling sections, whenever a symbol is displayed, also 2346display the file offset of the region of data that is about to be 2347dumped. If zeroes are being skipped, then when disassembly resumes, 2348tell the user how many zeroes were skipped and the file offset of the 2349location from where the disassembly resumes. When dumping sections, 2350display the file offset of the location from where the dump starts. 2351 2352@item --file-start-context 2353@cindex source code context 2354Specify that when displaying interlisted source code/disassembly 2355(assumes @option{-S}) from a file that has not yet been displayed, extend the 2356context to the start of the file. 2357 2358@item -h 2359@itemx --section-headers 2360@itemx --headers 2361@cindex section headers 2362Display summary information from the section headers of the 2363object file. 2364 2365File segments may be relocated to nonstandard addresses, for example by 2366using the @option{-Ttext}, @option{-Tdata}, or @option{-Tbss} options to 2367@command{ld}. However, some object file formats, such as a.out, do not 2368store the starting address of the file segments. In those situations, 2369although @command{ld} relocates the sections correctly, using @samp{objdump 2370-h} to list the file section headers cannot show the correct addresses. 2371Instead, it shows the usual addresses, which are implicit for the 2372target. 2373 2374Note, in some cases it is possible for a section to have both the 2375READONLY and the NOREAD attributes set. In such cases the NOREAD 2376attribute takes precedence, but @command{objdump} will report both 2377since the exact setting of the flag bits might be important. 2378 2379@item -H 2380@itemx --help 2381Print a summary of the options to @command{objdump} and exit. 2382 2383@item -i 2384@itemx --info 2385@cindex architectures available 2386@cindex object formats available 2387Display a list showing all architectures and object formats available 2388for specification with @option{-b} or @option{-m}. 2389 2390@item -j @var{name} 2391@itemx --section=@var{name} 2392@cindex section information 2393Display information only for section @var{name}. 2394 2395@item -l 2396@itemx --line-numbers 2397@cindex source filenames for object files 2398Label the display (using debugging information) with the filename and 2399source line numbers corresponding to the object code or relocs shown. 2400Only useful with @option{-d}, @option{-D}, or @option{-r}. 2401 2402@item -m @var{machine} 2403@itemx --architecture=@var{machine} 2404@cindex architecture 2405@cindex disassembly architecture 2406Specify the architecture to use when disassembling object files. This 2407can be useful when disassembling object files which do not describe 2408architecture information, such as S-records. You can list the available 2409architectures with the @option{-i} option. 2410 2411If the target is an ARM architecture then this switch has an 2412additional effect. It restricts the disassembly to only those 2413instructions supported by the architecture specified by @var{machine}. 2414If it is necessary to use this switch because the input file does not 2415contain any architecture information, but it is also desired to 2416disassemble all the instructions use @option{-marm}. 2417 2418@item -M @var{options} 2419@itemx --disassembler-options=@var{options} 2420Pass target specific information to the disassembler. Only supported on 2421some targets. If it is necessary to specify more than one 2422disassembler option then multiple @option{-M} options can be used or 2423can be placed together into a comma separated list. 2424 2425For ARC, @option{dsp} controls the printing of DSP instructions, 2426@option{spfp} selects the printing of FPX single precision FP 2427instructions, @option{dpfp} selects the printing of FPX double 2428precision FP instructions, @option{quarkse_em} selects the printing of 2429special QuarkSE-EM instructions, @option{fpuda} selects the printing 2430of double precision assist instructions, @option{fpus} selects the 2431printing of FPU single precision FP instructions, while @option{fpud} 2432selects the printing of FPU double precision FP instructions. 2433Additionally, one can choose to have all the immediates printed in 2434hexadecimal using @option{hex}. By default, the short immediates are 2435printed using the decimal representation, while the long immediate 2436values are printed as hexadecimal. 2437 2438@option{cpu=...} allows to enforce a particular ISA when disassembling 2439instructions, overriding the @option{-m} value or whatever is in the ELF file. 2440This might be useful to select ARC EM or HS ISA, because architecture is same 2441for those and disassembler relies on private ELF header data to decide if code 2442is for EM or HS. This option might be specified multiple times - only the 2443latest value will be used. Valid values are same as for the assembler 2444@option{-mcpu=...} option. 2445 2446If the target is an ARM architecture then this switch can be used to 2447select which register name set is used during disassembler. Specifying 2448@option{-M reg-names-std} (the default) will select the register names as 2449used in ARM's instruction set documentation, but with register 13 called 2450'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying 2451@option{-M reg-names-apcs} will select the name set used by the ARM 2452Procedure Call Standard, whilst specifying @option{-M reg-names-raw} will 2453just use @samp{r} followed by the register number. 2454 2455There are also two variants on the APCS register naming scheme enabled 2456by @option{-M reg-names-atpcs} and @option{-M reg-names-special-atpcs} which 2457use the ARM/Thumb Procedure Call Standard naming conventions. (Either 2458with the normal register names or the special register names). 2459 2460This option can also be used for ARM architectures to force the 2461disassembler to interpret all instructions as Thumb instructions by 2462using the switch @option{--disassembler-options=force-thumb}. This can be 2463useful when attempting to disassemble thumb code produced by other 2464compilers. 2465 2466For AArch64 targets this switch can be used to set whether instructions are 2467disassembled as the most general instruction using the @option{-M no-aliases} 2468option or whether instruction notes should be generated as comments in the 2469disasssembly using @option{-M notes}. 2470 2471For the x86, some of the options duplicate functions of the @option{-m} 2472switch, but allow finer grained control. 2473@table @code 2474@item x86-64 2475@itemx i386 2476@itemx i8086 2477Select disassembly for the given architecture. 2478 2479@item intel 2480@itemx att 2481Select between intel syntax mode and AT&T syntax mode. 2482 2483@item amd64 2484@itemx intel64 2485Select between AMD64 ISA and Intel64 ISA. 2486 2487@item intel-mnemonic 2488@itemx att-mnemonic 2489Select between intel mnemonic mode and AT&T mnemonic mode. 2490Note: @code{intel-mnemonic} implies @code{intel} and 2491@code{att-mnemonic} implies @code{att}. 2492 2493@item addr64 2494@itemx addr32 2495@itemx addr16 2496@itemx data32 2497@itemx data16 2498Specify the default address size and operand size. These five options 2499will be overridden if @code{x86-64}, @code{i386} or @code{i8086} 2500appear later in the option string. 2501 2502@item suffix 2503When in AT&T mode and also for a limited set of instructions when in Intel 2504mode, instructs the disassembler to print a mnemonic suffix even when the 2505suffix could be inferred by the operands or, for certain instructions, the 2506execution mode's defaults. 2507@end table 2508 2509For PowerPC, the @option{-M} argument @option{raw} selects 2510disasssembly of hardware insns rather than aliases. For example, you 2511will see @code{rlwinm} rather than @code{clrlwi}, and @code{addi} 2512rather than @code{li}. All of the @option{-m} arguments for 2513@command{gas} that select a CPU are supported. These are: 2514@option{403}, @option{405}, @option{440}, @option{464}, @option{476}, 2515@option{601}, @option{603}, @option{604}, @option{620}, @option{7400}, 2516@option{7410}, @option{7450}, @option{7455}, @option{750cl}, 2517@option{821}, @option{850}, @option{860}, @option{a2}, @option{booke}, 2518@option{booke32}, @option{cell}, @option{com}, @option{e200z4}, 2519@option{e300}, @option{e500}, @option{e500mc}, @option{e500mc64}, 2520@option{e500x2}, @option{e5500}, @option{e6500}, @option{efs}, 2521@option{power4}, @option{power5}, @option{power6}, @option{power7}, 2522@option{power8}, @option{power9}, @option{power10}, @option{ppc}, 2523@option{ppc32}, @option{ppc64}, @option{ppc64bridge}, @option{ppcps}, 2524@option{pwr}, @option{pwr2}, @option{pwr4}, @option{pwr5}, @option{pwr5x}, 2525@option{pwr6}, @option{pwr7}, @option{pwr8}, @option{pwr9}, @option{pwr10}, 2526@option{pwrx}, @option{titan}, and @option{vle}. 2527@option{32} and @option{64} modify the default or a prior CPU 2528selection, disabling and enabling 64-bit insns respectively. In 2529addition, @option{altivec}, @option{any}, @option{htm}, @option{vsx}, 2530and @option{spe} add capabilities to a previous @emph{or later} CPU 2531selection. @option{any} will disassemble any opcode known to 2532binutils, but in cases where an opcode has two different meanings or 2533different arguments, you may not see the disassembly you expect. 2534If you disassemble without giving a CPU selection, a default will be 2535chosen from information gleaned by BFD from the object files headers, 2536but the result again may not be as you expect. 2537 2538For MIPS, this option controls the printing of instruction mnemonic 2539names and register names in disassembled instructions. Multiple 2540selections from the following may be specified as a comma separated 2541string, and invalid options are ignored: 2542 2543@table @code 2544@item no-aliases 2545Print the 'raw' instruction mnemonic instead of some pseudo 2546instruction mnemonic. I.e., print 'daddu' or 'or' instead of 'move', 2547'sll' instead of 'nop', etc. 2548 2549@item msa 2550Disassemble MSA instructions. 2551 2552@item virt 2553Disassemble the virtualization ASE instructions. 2554 2555@item xpa 2556Disassemble the eXtended Physical Address (XPA) ASE instructions. 2557 2558@item gpr-names=@var{ABI} 2559Print GPR (general-purpose register) names as appropriate 2560for the specified ABI. By default, GPR names are selected according to 2561the ABI of the binary being disassembled. 2562 2563@item fpr-names=@var{ABI} 2564Print FPR (floating-point register) names as 2565appropriate for the specified ABI. By default, FPR numbers are printed 2566rather than names. 2567 2568@item cp0-names=@var{ARCH} 2569Print CP0 (system control coprocessor; coprocessor 0) register names 2570as appropriate for the CPU or architecture specified by 2571@var{ARCH}. By default, CP0 register names are selected according to 2572the architecture and CPU of the binary being disassembled. 2573 2574@item hwr-names=@var{ARCH} 2575Print HWR (hardware register, used by the @code{rdhwr} instruction) names 2576as appropriate for the CPU or architecture specified by 2577@var{ARCH}. By default, HWR names are selected according to 2578the architecture and CPU of the binary being disassembled. 2579 2580@item reg-names=@var{ABI} 2581Print GPR and FPR names as appropriate for the selected ABI. 2582 2583@item reg-names=@var{ARCH} 2584Print CPU-specific register names (CP0 register and HWR names) 2585as appropriate for the selected CPU or architecture. 2586@end table 2587 2588For any of the options listed above, @var{ABI} or 2589@var{ARCH} may be specified as @samp{numeric} to have numbers printed 2590rather than names, for the selected types of registers. 2591You can list the available values of @var{ABI} and @var{ARCH} using 2592the @option{--help} option. 2593 2594For VAX, you can specify function entry addresses with @option{-M 2595entry:0xf00ba}. You can use this multiple times to properly 2596disassemble VAX binary files that don't contain symbol tables (like 2597ROM dumps). In these cases, the function entry mask would otherwise 2598be decoded as VAX instructions, which would probably lead the rest 2599of the function being wrongly disassembled. 2600 2601@item -p 2602@itemx --private-headers 2603Print information that is specific to the object file format. The exact 2604information printed depends upon the object file format. For some 2605object file formats, no additional information is printed. 2606 2607@item -P @var{options} 2608@itemx --private=@var{options} 2609Print information that is specific to the object file format. The 2610argument @var{options} is a comma separated list that depends on the 2611format (the lists of options is displayed with the help). 2612 2613For XCOFF, the available options are: 2614@table @code 2615@item header 2616@item aout 2617@item sections 2618@item syms 2619@item relocs 2620@item lineno, 2621@item loader 2622@item except 2623@item typchk 2624@item traceback 2625@item toc 2626@item ldinfo 2627@end table 2628 2629Not all object formats support this option. In particular the ELF 2630format does not use it. 2631 2632@item -r 2633@itemx --reloc 2634@cindex relocation entries, in object file 2635Print the relocation entries of the file. If used with @option{-d} or 2636@option{-D}, the relocations are printed interspersed with the 2637disassembly. 2638 2639@item -R 2640@itemx --dynamic-reloc 2641@cindex dynamic relocation entries, in object file 2642Print the dynamic relocation entries of the file. This is only 2643meaningful for dynamic objects, such as certain types of shared 2644libraries. As for @option{-r}, if used with @option{-d} or 2645@option{-D}, the relocations are printed interspersed with the 2646disassembly. 2647 2648@item -s 2649@itemx --full-contents 2650@cindex sections, full contents 2651@cindex object file sections 2652Display the full contents of any sections requested. By default all 2653non-empty sections are displayed. 2654 2655@item -S 2656@itemx --source 2657@cindex source disassembly 2658@cindex disassembly, with source 2659Display source code intermixed with disassembly, if possible. Implies 2660@option{-d}. 2661 2662@item --source-comment[=@var{txt}] 2663@cindex source disassembly 2664@cindex disassembly, with source 2665Like the @option{-S} option, but all source code lines are displayed 2666with a prefix of @var{txt}. Typically @var{txt} will be a comment 2667string which can be used to distinguish the assembler code from the 2668source code. If @var{txt} is not provided then a default string of 2669@var{``# ``} (hash followed by a space), will be used. 2670 2671@item --prefix=@var{prefix} 2672@cindex Add prefix to absolute paths 2673Specify @var{prefix} to add to the absolute paths when used with 2674@option{-S}. 2675 2676@item --prefix-strip=@var{level} 2677@cindex Strip absolute paths 2678Indicate how many initial directory names to strip off the hardwired 2679absolute paths. It has no effect without @option{--prefix=}@var{prefix}. 2680 2681@item --show-raw-insn 2682When disassembling instructions, print the instruction in hex as well as 2683in symbolic form. This is the default except when 2684@option{--prefix-addresses} is used. 2685 2686@item --no-show-raw-insn 2687When disassembling instructions, do not print the instruction bytes. 2688This is the default when @option{--prefix-addresses} is used. 2689 2690@item --insn-width=@var{width} 2691@cindex Instruction width 2692Display @var{width} bytes on a single line when disassembling 2693instructions. 2694 2695@item --visualize-jumps[=color|=extended-color|=off] 2696Visualize jumps that stay inside a function by drawing ASCII art between 2697the start and target addresses. The optional @option{=color} argument 2698adds color to the output using simple terminal colors. Alternatively 2699the @option{=extended-color} argument will add color using 8bit 2700colors, but these might not work on all terminals. 2701 2702If it is necessary to disable the @option{visualize-jumps} option 2703after it has previously been enabled then use 2704@option{visualize-jumps=off}. 2705 2706@item -W[lLiaprmfFsoORtUuTgAckK] 2707@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] 2708@include debug.options.texi 2709 2710@item --dwarf-check 2711Enable additional checks for consistency of Dwarf information. 2712 2713@include ctf.options.texi 2714 2715@item -G 2716@itemx --stabs 2717@cindex stab 2718@cindex .stab 2719@cindex debug symbols 2720@cindex ELF object file format 2721Display the full contents of any sections requested. Display the 2722contents of the .stab and .stab.index and .stab.excl sections from an 2723ELF file. This is only useful on systems (such as Solaris 2.0) in which 2724@code{.stab} debugging symbol-table entries are carried in an ELF 2725section. In most other file formats, debugging symbol-table entries are 2726interleaved with linkage symbols, and are visible in the @option{--syms} 2727output. 2728 2729@item --start-address=@var{address} 2730@cindex start-address 2731Start displaying data at the specified address. This affects the output 2732of the @option{-d}, @option{-r} and @option{-s} options. 2733 2734@item --stop-address=@var{address} 2735@cindex stop-address 2736Stop displaying data at the specified address. This affects the output 2737of the @option{-d}, @option{-r} and @option{-s} options. 2738 2739@item -t 2740@itemx --syms 2741@cindex symbol table entries, printing 2742Print the symbol table entries of the file. 2743This is similar to the information provided by the @samp{nm} program, 2744although the display format is different. The format of the output 2745depends upon the format of the file being dumped, but there are two main 2746types. One looks like this: 2747 2748@smallexample 2749[ 4](sec 3)(fl 0x00)(ty 0)(scl 3) (nx 1) 0x00000000 .bss 2750[ 6](sec 1)(fl 0x00)(ty 0)(scl 2) (nx 0) 0x00000000 fred 2751@end smallexample 2752 2753where the number inside the square brackets is the number of the entry 2754in the symbol table, the @var{sec} number is the section number, the 2755@var{fl} value are the symbol's flag bits, the @var{ty} number is the 2756symbol's type, the @var{scl} number is the symbol's storage class and 2757the @var{nx} value is the number of auxilary entries associated with 2758the symbol. The last two fields are the symbol's value and its name. 2759 2760The other common output format, usually seen with ELF based files, 2761looks like this: 2762 2763@smallexample 276400000000 l d .bss 00000000 .bss 276500000000 g .text 00000000 fred 2766@end smallexample 2767 2768Here the first number is the symbol's value (sometimes refered to as 2769its address). The next field is actually a set of characters and 2770spaces indicating the flag bits that are set on the symbol. These 2771characters are described below. Next is the section with which the 2772symbol is associated or @emph{*ABS*} if the section is absolute (ie 2773not connected with any section), or @emph{*UND*} if the section is 2774referenced in the file being dumped, but not defined there. 2775 2776After the section name comes another field, a number, which for common 2777symbols is the alignment and for other symbol is the size. Finally 2778the symbol's name is displayed. 2779 2780The flag characters are divided into 7 groups as follows: 2781@table @code 2782@item l 2783@itemx g 2784@itemx u 2785@itemx ! 2786The symbol is a local (l), global (g), unique global (u), neither 2787global nor local (a space) or both global and local (!). A 2788symbol can be neither local or global for a variety of reasons, e.g., 2789because it is used for debugging, but it is probably an indication of 2790a bug if it is ever both local and global. Unique global symbols are 2791a GNU extension to the standard set of ELF symbol bindings. For such 2792a symbol the dynamic linker will make sure that in the entire process 2793there is just one symbol with this name and type in use. 2794 2795@item w 2796The symbol is weak (w) or strong (a space). 2797 2798@item C 2799The symbol denotes a constructor (C) or an ordinary symbol (a space). 2800 2801@item W 2802The symbol is a warning (W) or a normal symbol (a space). A warning 2803symbol's name is a message to be displayed if the symbol following the 2804warning symbol is ever referenced. 2805 2806@item I 2807@item i 2808The symbol is an indirect reference to another symbol (I), a function 2809to be evaluated during reloc processing (i) or a normal symbol (a 2810space). 2811 2812@item d 2813@itemx D 2814The symbol is a debugging symbol (d) or a dynamic symbol (D) or a 2815normal symbol (a space). 2816 2817@item F 2818@item f 2819@item O 2820The symbol is the name of a function (F) or a file (f) or an object 2821(O) or just a normal symbol (a space). 2822@end table 2823 2824@item -T 2825@itemx --dynamic-syms 2826@cindex dynamic symbol table entries, printing 2827Print the dynamic symbol table entries of the file. This is only 2828meaningful for dynamic objects, such as certain types of shared 2829libraries. This is similar to the information provided by the @samp{nm} 2830program when given the @option{-D} (@option{--dynamic}) option. 2831 2832The output format is similar to that produced by the @option{--syms} 2833option, except that an extra field is inserted before the symbol's 2834name, giving the version information associated with the symbol. 2835If the version is the default version to be used when resolving 2836unversioned references to the symbol then it's displayed as is, 2837otherwise it's put into parentheses. 2838 2839@item --special-syms 2840When displaying symbols include those which the target considers to be 2841special in some way and which would not normally be of interest to the 2842user. 2843 2844@item -V 2845@itemx --version 2846Print the version number of @command{objdump} and exit. 2847 2848@item -x 2849@itemx --all-headers 2850@cindex all header information, object file 2851@cindex header information, all 2852Display all available header information, including the symbol table and 2853relocation entries. Using @option{-x} is equivalent to specifying all of 2854@option{-a -f -h -p -r -t}. 2855 2856@item -w 2857@itemx --wide 2858@cindex wide output, printing 2859Format some lines for output devices that have more than 80 columns. 2860Also do not truncate symbol names when they are displayed. 2861 2862@item -z 2863@itemx --disassemble-zeroes 2864Normally the disassembly output will skip blocks of zeroes. This 2865option directs the disassembler to disassemble those blocks, just like 2866any other data. 2867@end table 2868 2869@c man end 2870 2871@ignore 2872@c man begin SEEALSO objdump 2873nm(1), readelf(1), and the Info entries for @file{binutils}. 2874@c man end 2875@end ignore 2876 2877@node ranlib 2878@chapter ranlib 2879 2880@kindex ranlib 2881@cindex archive contents 2882@cindex symbol index 2883 2884@c man title ranlib generate an index to an archive 2885 2886@smallexample 2887@c man begin SYNOPSIS ranlib 2888ranlib [@option{--plugin} @var{name}] [@option{-DhHvVt}] @var{archive} 2889@c man end 2890@end smallexample 2891 2892@c man begin DESCRIPTION ranlib 2893 2894@command{ranlib} generates an index to the contents of an archive and 2895stores it in the archive. The index lists each symbol defined by a 2896member of an archive that is a relocatable object file. 2897 2898You may use @samp{nm -s} or @samp{nm --print-armap} to list this index. 2899 2900An archive with such an index speeds up linking to the library and 2901allows routines in the library to call each other without regard to 2902their placement in the archive. 2903 2904The @sc{gnu} @command{ranlib} program is another form of @sc{gnu} @command{ar}; running 2905@command{ranlib} is completely equivalent to executing @samp{ar -s}. 2906@xref{ar}. 2907 2908@c man end 2909 2910@c man begin OPTIONS ranlib 2911 2912@table @env 2913@item -h 2914@itemx -H 2915@itemx --help 2916Show usage information for @command{ranlib}. 2917 2918@item -v 2919@itemx -V 2920@itemx --version 2921Show the version number of @command{ranlib}. 2922 2923@item -D 2924@cindex deterministic archives 2925@kindex --enable-deterministic-archives 2926Operate in @emph{deterministic} mode. The symbol map archive member's 2927header will show zero for the UID, GID, and timestamp. When this 2928option is used, multiple runs will produce identical output files. 2929 2930If @file{binutils} was configured with 2931@option{--enable-deterministic-archives}, then this mode is on by 2932default. It can be disabled with the @samp{-U} option, described 2933below. 2934 2935@item -t 2936Update the timestamp of the symbol map of an archive. 2937 2938@item -U 2939@cindex deterministic archives 2940@kindex --enable-deterministic-archives 2941Do @emph{not} operate in @emph{deterministic} mode. This is the 2942inverse of the @samp{-D} option, above: the archive index will get 2943actual UID, GID, timestamp, and file mode values. 2944 2945If @file{binutils} was configured @emph{without} 2946@option{--enable-deterministic-archives}, then this mode is on by 2947default. 2948 2949@end table 2950 2951@c man end 2952 2953@ignore 2954@c man begin SEEALSO ranlib 2955ar(1), nm(1), and the Info entries for @file{binutils}. 2956@c man end 2957@end ignore 2958 2959@node size 2960@chapter size 2961 2962@kindex size 2963@cindex section sizes 2964 2965@c man title size list section sizes and total size of binary files 2966 2967@smallexample 2968@c man begin SYNOPSIS size 2969size [@option{-A}|@option{-B}|@option{-G}|@option{--format=}@var{compatibility}] 2970 [@option{--help}] 2971 [@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}] 2972 [@option{--common}] 2973 [@option{-t}|@option{--totals}] 2974 [@option{--target=}@var{bfdname}] [@option{-V}|@option{--version}] 2975 [@var{objfile}@dots{}] 2976@c man end 2977@end smallexample 2978 2979@c man begin DESCRIPTION size 2980 2981The @sc{gnu} @command{size} utility lists the section sizes and the total 2982size for each of the binary files @var{objfile} on its argument list. 2983By default, one line of output is generated for each file or each 2984module if the file is an archive. 2985 2986@var{objfile}@dots{} are the files to be examined. If none are 2987specified, the file @code{a.out} will be used instead. 2988 2989@c man end 2990 2991@c man begin OPTIONS size 2992 2993The command-line options have the following meanings: 2994 2995@table @env 2996@item -A 2997@itemx -B 2998@itemx -G 2999@itemx --format=@var{compatibility} 3000@cindex @command{size} display format 3001Using one of these options, you can choose whether the output from @sc{gnu} 3002@command{size} resembles output from System V @command{size} (using @option{-A}, 3003or @option{--format=sysv}), or Berkeley @command{size} (using @option{-B}, or 3004@option{--format=berkeley}). The default is the one-line format similar to 3005Berkeley's. Alternatively, you can choose the GNU format output 3006(using @option{-G}, or @option{--format=gnu}), this is similar to 3007Berkeley's output format, but sizes are counted differently. 3008@c Bonus for doc-source readers: you can also say --format=strange (or 3009@c anything else that starts with 's') for sysv, and --format=boring (or 3010@c anything else that starts with 'b') for Berkeley. 3011 3012Here is an example of the Berkeley (default) format of output from 3013@command{size}: 3014@smallexample 3015$ size --format=Berkeley ranlib size 3016 text data bss dec hex filename 3017 294880 81920 11592 388392 5ed28 ranlib 3018 294880 81920 11888 388688 5ee50 size 3019@end smallexample 3020 3021The Berkeley style output counts read only data in the @code{text} 3022column, not in the @code{data} column, the @code{dec} and @code{hex} 3023columns both display the sum of the @code{text}, @code{data}, and 3024@code{bss} columns in decimal and hexadecimal respectively. 3025 3026The GNU format counts read only data in the @code{data} column, not 3027the @code{text} column, and only displays the sum of the @code{text}, 3028@code{data}, and @code{bss} columns once, in the @code{total} column. 3029The @option{--radix} option can be used to change the number base for 3030all columns. Here is the same data displayed with GNU conventions: 3031 3032@smallexample 3033$ size --format=GNU ranlib size 3034 text data bss total filename 3035 279880 96920 11592 388392 ranlib 3036 279880 96920 11888 388688 size 3037@end smallexample 3038 3039@noindent 3040This is the same data, but displayed closer to System V conventions: 3041 3042@smallexample 3043$ size --format=SysV ranlib size 3044ranlib : 3045section size addr 3046.text 294880 8192 3047.data 81920 303104 3048.bss 11592 385024 3049Total 388392 3050 3051 3052size : 3053section size addr 3054.text 294880 8192 3055.data 81920 303104 3056.bss 11888 385024 3057Total 388688 3058@end smallexample 3059 3060@item --help 3061Show a summary of acceptable arguments and options. 3062 3063@item -d 3064@itemx -o 3065@itemx -x 3066@itemx --radix=@var{number} 3067@cindex @command{size} number format 3068@cindex radix for section sizes 3069Using one of these options, you can control whether the size of each 3070section is given in decimal (@option{-d}, or @option{--radix=10}); octal 3071(@option{-o}, or @option{--radix=8}); or hexadecimal (@option{-x}, or 3072@option{--radix=16}). In @option{--radix=@var{number}}, only the three 3073values (8, 10, 16) are supported. The total size is always given in two 3074radices; decimal and hexadecimal for @option{-d} or @option{-x} output, or 3075octal and hexadecimal if you're using @option{-o}. 3076 3077@item --common 3078Print total size of common symbols in each file. When using Berkeley 3079or GNU format these are included in the bss size. 3080 3081@item -t 3082@itemx --totals 3083Show totals of all objects listed (Berkeley or GNU format mode only). 3084 3085@item --target=@var{bfdname} 3086@cindex object code format 3087Specify that the object-code format for @var{objfile} is 3088@var{bfdname}. This option may not be necessary; @command{size} can 3089automatically recognize many formats. 3090@xref{Target Selection}, for more information. 3091 3092@item -V 3093@itemx --version 3094Display the version number of @command{size}. 3095@end table 3096 3097@c man end 3098 3099@ignore 3100@c man begin SEEALSO size 3101ar(1), objdump(1), readelf(1), and the Info entries for @file{binutils}. 3102@c man end 3103@end ignore 3104 3105@node strings 3106@chapter strings 3107@kindex strings 3108@cindex listings strings 3109@cindex printing strings 3110@cindex strings, printing 3111 3112@c man title strings print the sequences of printable characters in files 3113 3114@smallexample 3115@c man begin SYNOPSIS strings 3116strings [@option{-afovV}] [@option{-}@var{min-len}] 3117 [@option{-n} @var{min-len}] [@option{--bytes=}@var{min-len}] 3118 [@option{-t} @var{radix}] [@option{--radix=}@var{radix}] 3119 [@option{-e} @var{encoding}] [@option{--encoding=}@var{encoding}] 3120 [@option{-}] [@option{--all}] [@option{--print-file-name}] 3121 [@option{-T} @var{bfdname}] [@option{--target=}@var{bfdname}] 3122 [@option{-w}] [@option{--include-all-whitespace}] 3123 [@option{-s}] [@option{--output-separator}@var{sep_string}] 3124 [@option{--help}] [@option{--version}] @var{file}@dots{} 3125@c man end 3126@end smallexample 3127 3128@c man begin DESCRIPTION strings 3129 3130For each @var{file} given, @sc{gnu} @command{strings} prints the 3131printable character sequences that are at least 4 characters long (or 3132the number given with the options below) and are followed by an 3133unprintable character. 3134 3135Depending upon how the strings program was configured it will default 3136to either displaying all the printable sequences that it can find in 3137each file, or only those sequences that are in loadable, initialized 3138data sections. If the file type is unrecognizable, or if strings is 3139reading from stdin then it will always display all of the printable 3140sequences that it can find. 3141 3142For backwards compatibility any file that occurs after a command-line 3143option of just @option{-} will also be scanned in full, regardless of 3144the presence of any @option{-d} option. 3145 3146@command{strings} is mainly useful for determining the contents of 3147non-text files. 3148 3149@c man end 3150 3151@c man begin OPTIONS strings 3152 3153@table @env 3154@item -a 3155@itemx --all 3156@itemx - 3157Scan the whole file, regardless of what sections it contains or 3158whether those sections are loaded or initialized. Normally this is 3159the default behaviour, but strings can be configured so that the 3160@option{-d} is the default instead. 3161 3162The @option{-} option is position dependent and forces strings to 3163perform full scans of any file that is mentioned after the @option{-} 3164on the command line, even if the @option{-d} option has been 3165specified. 3166 3167@item -d 3168@itemx --data 3169Only print strings from initialized, loaded data sections in the 3170file. This may reduce the amount of garbage in the output, but it 3171also exposes the strings program to any security flaws that may be 3172present in the BFD library used to scan and load sections. Strings 3173can be configured so that this option is the default behaviour. In 3174such cases the @option{-a} option can be used to avoid using the BFD 3175library and instead just print all of the strings found in the file. 3176 3177@item -f 3178@itemx --print-file-name 3179Print the name of the file before each string. 3180 3181@item --help 3182Print a summary of the program usage on the standard output and exit. 3183 3184@item -@var{min-len} 3185@itemx -n @var{min-len} 3186@itemx --bytes=@var{min-len} 3187Print sequences of characters that are at least @var{min-len} characters 3188long, instead of the default 4. 3189 3190@item -o 3191Like @samp{-t o}. Some other versions of @command{strings} have @option{-o} 3192act like @samp{-t d} instead. Since we can not be compatible with both 3193ways, we simply chose one. 3194 3195@item -t @var{radix} 3196@itemx --radix=@var{radix} 3197Print the offset within the file before each string. The single 3198character argument specifies the radix of the offset---@samp{o} for 3199octal, @samp{x} for hexadecimal, or @samp{d} for decimal. 3200 3201@item -e @var{encoding} 3202@itemx --encoding=@var{encoding} 3203Select the character encoding of the strings that are to be found. 3204Possible values for @var{encoding} are: @samp{s} = single-7-bit-byte 3205characters (ASCII, ISO 8859, etc., default), @samp{S} = 3206single-8-bit-byte characters, @samp{b} = 16-bit bigendian, @samp{l} = 320716-bit littleendian, @samp{B} = 32-bit bigendian, @samp{L} = 32-bit 3208littleendian. Useful for finding wide character strings. (@samp{l} 3209and @samp{b} apply to, for example, Unicode UTF-16/UCS-2 encodings). 3210 3211@item -T @var{bfdname} 3212@itemx --target=@var{bfdname} 3213@cindex object code format 3214Specify an object code format other than your system's default format. 3215@xref{Target Selection}, for more information. 3216 3217@item -v 3218@itemx -V 3219@itemx --version 3220Print the program version number on the standard output and exit. 3221 3222@item -w 3223@itemx --include-all-whitespace 3224By default tab and space characters are included in the strings that 3225are displayed, but other whitespace characters, such a newlines and 3226carriage returns, are not. The @option{-w} option changes this so 3227that all whitespace characters are considered to be part of a string. 3228 3229@item -s 3230@itemx --output-separator 3231By default, output strings are delimited by a new-line. This option 3232allows you to supply any string to be used as the output record 3233separator. Useful with --include-all-whitespace where strings 3234may contain new-lines internally. 3235@end table 3236 3237@c man end 3238 3239@ignore 3240@c man begin SEEALSO strings 3241ar(1), nm(1), objdump(1), ranlib(1), readelf(1) 3242and the Info entries for @file{binutils}. 3243@c man end 3244@end ignore 3245 3246@node strip 3247@chapter strip 3248 3249@kindex strip 3250@cindex removing symbols 3251@cindex discarding symbols 3252@cindex symbols, discarding 3253 3254@c man title strip discard symbols and other data from object files 3255 3256@smallexample 3257@c man begin SYNOPSIS strip 3258strip [@option{-F} @var{bfdname} |@option{--target=}@var{bfdname}] 3259 [@option{-I} @var{bfdname} |@option{--input-target=}@var{bfdname}] 3260 [@option{-O} @var{bfdname} |@option{--output-target=}@var{bfdname}] 3261 [@option{-s}|@option{--strip-all}] 3262 [@option{-S}|@option{-g}|@option{-d}|@option{--strip-debug}] 3263 [@option{--strip-dwo}] 3264 [@option{-K} @var{symbolname}|@option{--keep-symbol=}@var{symbolname}] 3265 [@option{-M}|@option{--merge-notes}][@option{--no-merge-notes}] 3266 [@option{-N} @var{symbolname} |@option{--strip-symbol=}@var{symbolname}] 3267 [@option{-w}|@option{--wildcard}] 3268 [@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}] 3269 [@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}] 3270 [@option{--keep-section=}@var{sectionpattern}] 3271 [@option{--remove-relocations=}@var{sectionpattern}] 3272 [@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}] 3273 [@option{-D}|@option{--enable-deterministic-archives}] 3274 [@option{-U}|@option{--disable-deterministic-archives}] 3275 [@option{--keep-file-symbols}] 3276 [@option{--only-keep-debug}] 3277 [@option{-v} |@option{--verbose}] [@option{-V}|@option{--version}] 3278 [@option{--help}] [@option{--info}] 3279 @var{objfile}@dots{} 3280@c man end 3281@end smallexample 3282 3283@c man begin DESCRIPTION strip 3284 3285@sc{gnu} @command{strip} discards all symbols from object files 3286@var{objfile}. The list of object files may include archives. 3287At least one object file must be given. 3288 3289@command{strip} modifies the files named in its argument, 3290rather than writing modified copies under different names. 3291 3292@c man end 3293 3294@c man begin OPTIONS strip 3295 3296@table @env 3297@item -F @var{bfdname} 3298@itemx --target=@var{bfdname} 3299Treat the original @var{objfile} as a file with the object 3300code format @var{bfdname}, and rewrite it in the same format. 3301@xref{Target Selection}, for more information. 3302 3303@item --help 3304Show a summary of the options to @command{strip} and exit. 3305 3306@item --info 3307Display a list showing all architectures and object formats available. 3308 3309@item -I @var{bfdname} 3310@itemx --input-target=@var{bfdname} 3311Treat the original @var{objfile} as a file with the object 3312code format @var{bfdname}. 3313@xref{Target Selection}, for more information. 3314 3315@item -O @var{bfdname} 3316@itemx --output-target=@var{bfdname} 3317Replace @var{objfile} with a file in the output format @var{bfdname}. 3318@xref{Target Selection}, for more information. 3319 3320@item -R @var{sectionname} 3321@itemx --remove-section=@var{sectionname} 3322Remove any section named @var{sectionname} from the output file, in 3323addition to whatever sections would otherwise be removed. This 3324option may be given more than once. Note that using this option 3325inappropriately may make the output file unusable. The wildcard 3326character @samp{*} may be given at the end of @var{sectionname}. If 3327so, then any section starting with @var{sectionname} will be removed. 3328 3329If the first character of @var{sectionpattern} is the exclamation 3330point (!) then matching sections will not be removed even if an 3331earlier use of @option{--remove-section} on the same command line 3332would otherwise remove it. For example: 3333 3334@smallexample 3335 --remove-section=.text.* --remove-section=!.text.foo 3336@end smallexample 3337 3338will remove all sections matching the pattern '.text.*', but will not 3339remove the section '.text.foo'. 3340 3341@item --keep-section=@var{sectionpattern} 3342When removing sections from the output file, keep sections that match 3343@var{sectionpattern}. 3344 3345@item --remove-relocations=@var{sectionpattern} 3346Remove relocations from the output file for any section matching 3347@var{sectionpattern}. This option may be given more than once. Note 3348that using this option inappropriately may make the output file 3349unusable. Wildcard characters are accepted in @var{sectionpattern}. 3350For example: 3351 3352@smallexample 3353 --remove-relocations=.text.* 3354@end smallexample 3355 3356will remove the relocations for all sections matching the patter 3357'.text.*'. 3358 3359If the first character of @var{sectionpattern} is the exclamation 3360point (!) then matching sections will not have their relocation 3361removed even if an earlier use of @option{--remove-relocations} on the 3362same command line would otherwise cause the relocations to be removed. 3363For example: 3364 3365@smallexample 3366 --remove-relocations=.text.* --remove-relocations=!.text.foo 3367@end smallexample 3368 3369will remove all relocations for sections matching the pattern 3370'.text.*', but will not remove relocations for the section 3371'.text.foo'. 3372 3373@item -s 3374@itemx --strip-all 3375Remove all symbols. 3376 3377@item -g 3378@itemx -S 3379@itemx -d 3380@itemx --strip-debug 3381Remove debugging symbols only. 3382 3383@item --strip-dwo 3384Remove the contents of all DWARF .dwo sections, leaving the 3385remaining debugging sections and all symbols intact. 3386See the description of this option in the @command{objcopy} section 3387for more information. 3388 3389@item --strip-unneeded 3390Remove all symbols that are not needed for relocation processing. 3391 3392@item -K @var{symbolname} 3393@itemx --keep-symbol=@var{symbolname} 3394When stripping symbols, keep symbol @var{symbolname} even if it would 3395normally be stripped. This option may be given more than once. 3396 3397@item -M 3398@itemx --merge-notes 3399@itemx --no-merge-notes 3400For ELF files, attempt (or do not attempt) to reduce the size of any 3401SHT_NOTE type sections by removing duplicate notes. The default is to 3402attempt this reduction unless stripping debug or DWO information. 3403 3404@item -N @var{symbolname} 3405@itemx --strip-symbol=@var{symbolname} 3406Remove symbol @var{symbolname} from the source file. This option may be 3407given more than once, and may be combined with strip options other than 3408@option{-K}. 3409 3410@item -o @var{file} 3411Put the stripped output in @var{file}, rather than replacing the 3412existing file. When this argument is used, only one @var{objfile} 3413argument may be specified. 3414 3415@item -p 3416@itemx --preserve-dates 3417Preserve the access and modification dates of the file. 3418 3419@item -D 3420@itemx --enable-deterministic-archives 3421@cindex deterministic archives 3422@kindex --enable-deterministic-archives 3423Operate in @emph{deterministic} mode. When copying archive members 3424and writing the archive index, use zero for UIDs, GIDs, timestamps, 3425and use consistent file modes for all files. 3426 3427If @file{binutils} was configured with 3428@option{--enable-deterministic-archives}, then this mode is on by default. 3429It can be disabled with the @samp{-U} option, below. 3430 3431@item -U 3432@itemx --disable-deterministic-archives 3433@cindex deterministic archives 3434@kindex --enable-deterministic-archives 3435Do @emph{not} operate in @emph{deterministic} mode. This is the 3436inverse of the @option{-D} option, above: when copying archive members 3437and writing the archive index, use their actual UID, GID, timestamp, 3438and file mode values. 3439 3440This is the default unless @file{binutils} was configured with 3441@option{--enable-deterministic-archives}. 3442 3443@item -w 3444@itemx --wildcard 3445Permit regular expressions in @var{symbolname}s used in other command 3446line options. The question mark (?), asterisk (*), backslash (\) and 3447square brackets ([]) operators can be used anywhere in the symbol 3448name. If the first character of the symbol name is the exclamation 3449point (!) then the sense of the switch is reversed for that symbol. 3450For example: 3451 3452@smallexample 3453 -w -K !foo -K fo* 3454@end smallexample 3455 3456would cause strip to only keep symbols that start with the letters 3457``fo'', but to discard the symbol ``foo''. 3458 3459@item -x 3460@itemx --discard-all 3461Remove non-global symbols. 3462 3463@item -X 3464@itemx --discard-locals 3465Remove compiler-generated local symbols. 3466(These usually start with @samp{L} or @samp{.}.) 3467 3468@item --keep-file-symbols 3469When stripping a file, perhaps with @option{--strip-debug} or 3470@option{--strip-unneeded}, retain any symbols specifying source file names, 3471which would otherwise get stripped. 3472 3473@item --only-keep-debug 3474Strip a file, emptying the contents of any sections that would not be 3475stripped by @option{--strip-debug} and leaving the debugging sections 3476intact. In ELF files, this preserves all the note sections in the 3477output as well. 3478 3479Note - the section headers of the stripped sections are preserved, 3480including their sizes, but the contents of the section are discarded. 3481The section headers are preserved so that other tools can match up the 3482debuginfo file with the real executable, even if that executable has 3483been relocated to a different address space. 3484 3485The intention is that this option will be used in conjunction with 3486@option{--add-gnu-debuglink} to create a two part executable. One a 3487stripped binary which will occupy less space in RAM and in a 3488distribution and the second a debugging information file which is only 3489needed if debugging abilities are required. The suggested procedure 3490to create these files is as follows: 3491 3492@enumerate 3493@item Link the executable as normal. Assuming that it is called 3494@code{foo} then... 3495@item Run @code{objcopy --only-keep-debug foo foo.dbg} to 3496create a file containing the debugging info. 3497@item Run @code{objcopy --strip-debug foo} to create a 3498stripped executable. 3499@item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo} 3500to add a link to the debugging info into the stripped executable. 3501@end enumerate 3502 3503Note---the choice of @code{.dbg} as an extension for the debug info 3504file is arbitrary. Also the @code{--only-keep-debug} step is 3505optional. You could instead do this: 3506 3507@enumerate 3508@item Link the executable as normal. 3509@item Copy @code{foo} to @code{foo.full} 3510@item Run @code{strip --strip-debug foo} 3511@item Run @code{objcopy --add-gnu-debuglink=foo.full foo} 3512@end enumerate 3513 3514i.e., the file pointed to by the @option{--add-gnu-debuglink} can be the 3515full executable. It does not have to be a file created by the 3516@option{--only-keep-debug} switch. 3517 3518Note---this switch is only intended for use on fully linked files. It 3519does not make sense to use it on object files where the debugging 3520information may be incomplete. Besides the gnu_debuglink feature 3521currently only supports the presence of one filename containing 3522debugging information, not multiple filenames on a one-per-object-file 3523basis. 3524 3525@item -V 3526@itemx --version 3527Show the version number for @command{strip}. 3528 3529@item -v 3530@itemx --verbose 3531Verbose output: list all object files modified. In the case of 3532archives, @samp{strip -v} lists all members of the archive. 3533@end table 3534 3535@c man end 3536 3537@ignore 3538@c man begin SEEALSO strip 3539the Info entries for @file{binutils}. 3540@c man end 3541@end ignore 3542 3543@node c++filt, addr2line, strip, Top 3544@chapter c++filt 3545 3546@kindex c++filt 3547@cindex demangling C++ symbols 3548 3549@c man title cxxfilt demangle C++ and Java symbols 3550 3551@smallexample 3552@c man begin SYNOPSIS cxxfilt 3553c++filt [@option{-_}|@option{--strip-underscore}] 3554 [@option{-n}|@option{--no-strip-underscore}] 3555 [@option{-p}|@option{--no-params}] 3556 [@option{-t}|@option{--types}] 3557 [@option{-i}|@option{--no-verbose}] 3558 [@option{-r}|@option{--no-recurse-limit}] 3559 [@option{-R}|@option{--recurse-limit}] 3560 [@option{-s} @var{format}|@option{--format=}@var{format}] 3561 [@option{--help}] [@option{--version}] [@var{symbol}@dots{}] 3562@c man end 3563@end smallexample 3564 3565@c man begin DESCRIPTION cxxfilt 3566 3567@kindex cxxfilt 3568The C++ and Java languages provide function overloading, which means 3569that you can write many functions with the same name, providing that 3570each function takes parameters of different types. In order to be 3571able to distinguish these similarly named functions C++ and Java 3572encode them into a low-level assembler name which uniquely identifies 3573each different version. This process is known as @dfn{mangling}. The 3574@command{c++filt} 3575@footnote{MS-DOS does not allow @kbd{+} characters in file names, so on 3576MS-DOS this program is named @command{CXXFILT}.} 3577program does the inverse mapping: it decodes (@dfn{demangles}) low-level 3578names into user-level names so that they can be read. 3579 3580Every alphanumeric word (consisting of letters, digits, underscores, 3581dollars, or periods) seen in the input is a potential mangled name. 3582If the name decodes into a C++ name, the C++ name replaces the 3583low-level name in the output, otherwise the original word is output. 3584In this way you can pass an entire assembler source file, containing 3585mangled names, through @command{c++filt} and see the same source file 3586containing demangled names. 3587 3588You can also use @command{c++filt} to decipher individual symbols by 3589passing them on the command line: 3590 3591@example 3592c++filt @var{symbol} 3593@end example 3594 3595If no @var{symbol} arguments are given, @command{c++filt} reads symbol 3596names from the standard input instead. All the results are printed on 3597the standard output. The difference between reading names from the 3598command line versus reading names from the standard input is that 3599command-line arguments are expected to be just mangled names and no 3600checking is performed to separate them from surrounding text. Thus 3601for example: 3602 3603@smallexample 3604c++filt -n _Z1fv 3605@end smallexample 3606 3607will work and demangle the name to ``f()'' whereas: 3608 3609@smallexample 3610c++filt -n _Z1fv, 3611@end smallexample 3612 3613will not work. (Note the extra comma at the end of the mangled 3614name which makes it invalid). This command however will work: 3615 3616@smallexample 3617echo _Z1fv, | c++filt -n 3618@end smallexample 3619 3620and will display ``f(),'', i.e., the demangled name followed by a 3621trailing comma. This behaviour is because when the names are read 3622from the standard input it is expected that they might be part of an 3623assembler source file where there might be extra, extraneous 3624characters trailing after a mangled name. For example: 3625 3626@smallexample 3627 .type _Z1fv, @@function 3628@end smallexample 3629 3630@c man end 3631 3632@c man begin OPTIONS cxxfilt 3633 3634@table @env 3635@item -_ 3636@itemx --strip-underscore 3637On some systems, both the C and C++ compilers put an underscore in front 3638of every name. For example, the C name @code{foo} gets the low-level 3639name @code{_foo}. This option removes the initial underscore. Whether 3640@command{c++filt} removes the underscore by default is target dependent. 3641 3642@item -n 3643@itemx --no-strip-underscore 3644Do not remove the initial underscore. 3645 3646@item -p 3647@itemx --no-params 3648When demangling the name of a function, do not display the types of 3649the function's parameters. 3650 3651@item -t 3652@itemx --types 3653Attempt to demangle types as well as function names. This is disabled 3654by default since mangled types are normally only used internally in 3655the compiler, and they can be confused with non-mangled names. For example, 3656a function called ``a'' treated as a mangled type name would be 3657demangled to ``signed char''. 3658 3659@item -i 3660@itemx --no-verbose 3661Do not include implementation details (if any) in the demangled 3662output. 3663 3664@item -r 3665@itemx -R 3666@itemx --recurse-limit 3667@itemx --no-recurse-limit 3668@itemx --recursion-limit 3669@itemx --no-recursion-limit 3670Enables or disables a limit on the amount of recursion performed 3671whilst demangling strings. Since the name mangling formats allow for 3672an inifinite level of recursion it is possible to create strings whose 3673decoding will exhaust the amount of stack space available on the host 3674machine, triggering a memory fault. The limit tries to prevent this 3675from happening by restricting recursion to 2048 levels of nesting. 3676 3677The default is for this limit to be enabled, but disabling it may be 3678necessary in order to demangle truly complicated names. Note however 3679that if the recursion limit is disabled then stack exhaustion is 3680possible and any bug reports about such an event will be rejected. 3681 3682The @option{-r} option is a synonym for the 3683@option{--no-recurse-limit} option. The @option{-R} option is a 3684synonym for the @option{--recurse-limit} option. 3685 3686@item -s @var{format} 3687@itemx --format=@var{format} 3688@command{c++filt} can decode various methods of mangling, used by 3689different compilers. The argument to this option selects which 3690method it uses: 3691 3692@table @code 3693@item auto 3694Automatic selection based on executable (the default method) 3695@item gnu 3696the one used by the @sc{gnu} C++ compiler (g++) 3697@item lucid 3698the one used by the Lucid compiler (lcc) 3699@item arm 3700the one specified by the C++ Annotated Reference Manual 3701@item hp 3702the one used by the HP compiler (aCC) 3703@item edg 3704the one used by the EDG compiler 3705@item gnu-v3 3706the one used by the @sc{gnu} C++ compiler (g++) with the V3 ABI. 3707@item java 3708the one used by the @sc{gnu} Java compiler (gcj) 3709@item gnat 3710the one used by the @sc{gnu} Ada compiler (GNAT). 3711@end table 3712 3713@item --help 3714Print a summary of the options to @command{c++filt} and exit. 3715 3716@item --version 3717Print the version number of @command{c++filt} and exit. 3718@end table 3719 3720@c man end 3721 3722@ignore 3723@c man begin SEEALSO cxxfilt 3724the Info entries for @file{binutils}. 3725@c man end 3726@end ignore 3727 3728@quotation 3729@emph{Warning:} @command{c++filt} is a new utility, and the details of its 3730user interface are subject to change in future releases. In particular, 3731a command-line option may be required in the future to decode a name 3732passed as an argument on the command line; in other words, 3733 3734@example 3735c++filt @var{symbol} 3736@end example 3737 3738@noindent 3739may in a future release become 3740 3741@example 3742c++filt @var{option} @var{symbol} 3743@end example 3744@end quotation 3745 3746@node addr2line 3747@chapter addr2line 3748 3749@kindex addr2line 3750@cindex address to file name and line number 3751 3752@c man title addr2line convert addresses into file names and line numbers 3753 3754@smallexample 3755@c man begin SYNOPSIS addr2line 3756addr2line [@option{-a}|@option{--addresses}] 3757 [@option{-b} @var{bfdname}|@option{--target=}@var{bfdname}] 3758 [@option{-C}|@option{--demangle}[=@var{style}]] 3759 [@option{-r}|@option{--no-recurse-limit}] 3760 [@option{-R}|@option{--recurse-limit}] 3761 [@option{-e} @var{filename}|@option{--exe=}@var{filename}] 3762 [@option{-f}|@option{--functions}] [@option{-s}|@option{--basename}] 3763 [@option{-i}|@option{--inlines}] 3764 [@option{-p}|@option{--pretty-print}] 3765 [@option{-j}|@option{--section=}@var{name}] 3766 [@option{-H}|@option{--help}] [@option{-V}|@option{--version}] 3767 [addr addr @dots{}] 3768@c man end 3769@end smallexample 3770 3771@c man begin DESCRIPTION addr2line 3772 3773@command{addr2line} translates addresses into file names and line numbers. 3774Given an address in an executable or an offset in a section of a relocatable 3775object, it uses the debugging information to figure out which file name and 3776line number are associated with it. 3777 3778The executable or relocatable object to use is specified with the @option{-e} 3779option. The default is the file @file{a.out}. The section in the relocatable 3780object to use is specified with the @option{-j} option. 3781 3782@command{addr2line} has two modes of operation. 3783 3784In the first, hexadecimal addresses are specified on the command line, 3785and @command{addr2line} displays the file name and line number for each 3786address. 3787 3788In the second, @command{addr2line} reads hexadecimal addresses from 3789standard input, and prints the file name and line number for each 3790address on standard output. In this mode, @command{addr2line} may be used 3791in a pipe to convert dynamically chosen addresses. 3792 3793The format of the output is @samp{FILENAME:LINENO}. By default 3794each input address generates one line of output. 3795 3796Two options can generate additional lines before each 3797@samp{FILENAME:LINENO} line (in that order). 3798 3799If the @option{-a} option is used then a line with the input address 3800is displayed. 3801 3802If the @option{-f} option is used, then a line with the 3803@samp{FUNCTIONNAME} is displayed. This is the name of the function 3804containing the address. 3805 3806One option can generate additional lines after the 3807@samp{FILENAME:LINENO} line. 3808 3809If the @option{-i} option is used and the code at the given address is 3810present there because of inlining by the compiler then additional 3811lines are displayed afterwards. One or two extra lines (if the 3812@option{-f} option is used) are displayed for each inlined function. 3813 3814Alternatively if the @option{-p} option is used then each input 3815address generates a single, long, output line containing the address, 3816the function name, the file name and the line number. If the 3817@option{-i} option has also been used then any inlined functions will 3818be displayed in the same manner, but on separate lines, and prefixed 3819by the text @samp{(inlined by)}. 3820 3821If the file name or function name can not be determined, 3822@command{addr2line} will print two question marks in their place. If the 3823line number can not be determined, @command{addr2line} will print 0. 3824 3825@c man end 3826 3827@c man begin OPTIONS addr2line 3828 3829The long and short forms of options, shown here as alternatives, are 3830equivalent. 3831 3832@table @env 3833@item -a 3834@itemx --addresses 3835Display the address before the function name, file and line number 3836information. The address is printed with a @samp{0x} prefix to easily 3837identify it. 3838 3839@item -b @var{bfdname} 3840@itemx --target=@var{bfdname} 3841@cindex object code format 3842Specify that the object-code format for the object files is 3843@var{bfdname}. 3844 3845@item -C 3846@itemx --demangle[=@var{style}] 3847@cindex demangling in objdump 3848Decode (@dfn{demangle}) low-level symbol names into user-level names. 3849Besides removing any initial underscore prepended by the system, this 3850makes C++ function names readable. Different compilers have different 3851mangling styles. The optional demangling style argument can be used to 3852choose an appropriate demangling style for your compiler. @xref{c++filt}, 3853for more information on demangling. 3854 3855@item -e @var{filename} 3856@itemx --exe=@var{filename} 3857Specify the name of the executable for which addresses should be 3858translated. The default file is @file{a.out}. 3859 3860@item -f 3861@itemx --functions 3862Display function names as well as file and line number information. 3863 3864@item -s 3865@itemx --basenames 3866Display only the base of each file name. 3867 3868@item -i 3869@itemx --inlines 3870If the address belongs to a function that was inlined, the source 3871information for all enclosing scopes back to the first non-inlined 3872function will also be printed. For example, if @code{main} inlines 3873@code{callee1} which inlines @code{callee2}, and address is from 3874@code{callee2}, the source information for @code{callee1} and @code{main} 3875will also be printed. 3876 3877@item -j 3878@itemx --section 3879Read offsets relative to the specified section instead of absolute addresses. 3880 3881@item -p 3882@itemx --pretty-print 3883Make the output more human friendly: each location are printed on one line. 3884If option @option{-i} is specified, lines for all enclosing scopes are 3885prefixed with @samp{(inlined by)}. 3886 3887@item -r 3888@itemx -R 3889@itemx --recurse-limit 3890@itemx --no-recurse-limit 3891@itemx --recursion-limit 3892@itemx --no-recursion-limit 3893Enables or disables a limit on the amount of recursion performed 3894whilst demangling strings. Since the name mangling formats allow for 3895an inifinite level of recursion it is possible to create strings whose 3896decoding will exhaust the amount of stack space available on the host 3897machine, triggering a memory fault. The limit tries to prevent this 3898from happening by restricting recursion to 2048 levels of nesting. 3899 3900The default is for this limit to be enabled, but disabling it may be 3901necessary in order to demangle truly complicated names. Note however 3902that if the recursion limit is disabled then stack exhaustion is 3903possible and any bug reports about such an event will be rejected. 3904 3905The @option{-r} option is a synonym for the 3906@option{--no-recurse-limit} option. The @option{-R} option is a 3907synonym for the @option{--recurse-limit} option. 3908 3909Note this option is only effective if the @option{-C} or 3910@option{--demangle} option has been enabled. 3911 3912@end table 3913 3914@c man end 3915 3916@ignore 3917@c man begin SEEALSO addr2line 3918Info entries for @file{binutils}. 3919@c man end 3920@end ignore 3921 3922@node windmc 3923@chapter windmc 3924 3925@command{windmc} may be used to generator Windows message resources. 3926 3927@quotation 3928@emph{Warning:} @command{windmc} is not always built as part of the binary 3929utilities, since it is only useful for Windows targets. 3930@end quotation 3931 3932@c man title windmc generates Windows message resources 3933 3934@smallexample 3935@c man begin SYNOPSIS windmc 3936windmc [options] input-file 3937@c man end 3938@end smallexample 3939 3940@c man begin DESCRIPTION windmc 3941 3942@command{windmc} reads message definitions from an input file (.mc) and 3943translate them into a set of output files. The output files may be of 3944four kinds: 3945 3946@table @code 3947@item h 3948A C header file containing the message definitions. 3949 3950@item rc 3951A resource file compilable by the @command{windres} tool. 3952 3953@item bin 3954One or more binary files containing the resource data for a specific 3955message language. 3956 3957@item dbg 3958A C include file that maps message id's to their symbolic name. 3959@end table 3960 3961The exact description of these different formats is available in 3962documentation from Microsoft. 3963 3964When @command{windmc} converts from the @code{mc} format to the @code{bin} 3965format, @code{rc}, @code{h}, and optional @code{dbg} it is acting like the 3966Windows Message Compiler. 3967 3968@c man end 3969 3970@c man begin OPTIONS windmc 3971 3972@table @env 3973@item -a 3974@itemx --ascii_in 3975Specifies that the input file specified is ASCII. This is the default 3976behaviour. 3977 3978@item -A 3979@itemx --ascii_out 3980Specifies that messages in the output @code{bin} files should be in ASCII 3981format. 3982 3983@item -b 3984@itemx --binprefix 3985Specifies that @code{bin} filenames should have to be prefixed by the 3986basename of the source file. 3987 3988@item -c 3989@itemx --customflag 3990Sets the customer bit in all message id's. 3991 3992@item -C @var{codepage} 3993@itemx --codepage_in @var{codepage} 3994Sets the default codepage to be used to convert input file to UTF16. The 3995default is ocdepage 1252. 3996 3997@item -d 3998@itemx --decimal_values 3999Outputs the constants in the header file in decimal. Default is using 4000hexadecimal output. 4001 4002@item -e @var{ext} 4003@itemx --extension @var{ext} 4004The extension for the header file. The default is .h extension. 4005 4006@item -F @var{target} 4007@itemx --target @var{target} 4008Specify the BFD format to use for a bin file as output. This 4009is a BFD target name; you can use the @option{--help} option to see a list 4010of supported targets. Normally @command{windmc} will use the default 4011format, which is the first one listed by the @option{--help} option. 4012@ifclear man 4013@ref{Target Selection}. 4014@end ifclear 4015 4016@item -h @var{path} 4017@itemx --headerdir @var{path} 4018The target directory of the generated header file. The default is the 4019current directory. 4020 4021@item -H 4022@itemx --help 4023Displays a list of command-line options and then exits. 4024 4025@item -m @var{characters} 4026@itemx --maxlength @var{characters} 4027Instructs @command{windmc} to generate a warning if the length 4028of any message exceeds the number specified. 4029 4030@item -n 4031@itemx --nullterminate 4032Terminate message text in @code{bin} files by zero. By default they are 4033terminated by CR/LF. 4034 4035@item -o 4036@itemx --hresult_use 4037Not yet implemented. Instructs @code{windmc} to generate an OLE2 header 4038file, using HRESULT definitions. Status codes are used if the flag is not 4039specified. 4040 4041@item -O @var{codepage} 4042@itemx --codepage_out @var{codepage} 4043Sets the default codepage to be used to output text files. The default 4044is ocdepage 1252. 4045 4046@item -r @var{path} 4047@itemx --rcdir @var{path} 4048The target directory for the generated @code{rc} script and the generated 4049@code{bin} files that the resource compiler script includes. The default 4050is the current directory. 4051 4052@item -u 4053@itemx --unicode_in 4054Specifies that the input file is UTF16. 4055 4056@item -U 4057@itemx --unicode_out 4058Specifies that messages in the output @code{bin} file should be in UTF16 4059format. This is the default behaviour. 4060 4061@item -v 4062@item --verbose 4063Enable verbose mode. 4064 4065@item -V 4066@item --version 4067Prints the version number for @command{windmc}. 4068 4069@item -x @var{path} 4070@itemx --xdgb @var{path} 4071The path of the @code{dbg} C include file that maps message id's to the 4072symbolic name. No such file is generated without specifying the switch. 4073@end table 4074 4075@c man end 4076 4077@ignore 4078@c man begin SEEALSO windmc 4079the Info entries for @file{binutils}. 4080@c man end 4081@end ignore 4082 4083@node windres 4084@chapter windres 4085 4086@command{windres} may be used to manipulate Windows resources. 4087 4088@quotation 4089@emph{Warning:} @command{windres} is not always built as part of the binary 4090utilities, since it is only useful for Windows targets. 4091@end quotation 4092 4093@c man title windres manipulate Windows resources 4094 4095@smallexample 4096@c man begin SYNOPSIS windres 4097windres [options] [input-file] [output-file] 4098@c man end 4099@end smallexample 4100 4101@c man begin DESCRIPTION windres 4102 4103@command{windres} reads resources from an input file and copies them into 4104an output file. Either file may be in one of three formats: 4105 4106@table @code 4107@item rc 4108A text format read by the Resource Compiler. 4109 4110@item res 4111A binary format generated by the Resource Compiler. 4112 4113@item coff 4114A COFF object or executable. 4115@end table 4116 4117The exact description of these different formats is available in 4118documentation from Microsoft. 4119 4120When @command{windres} converts from the @code{rc} format to the @code{res} 4121format, it is acting like the Windows Resource Compiler. When 4122@command{windres} converts from the @code{res} format to the @code{coff} 4123format, it is acting like the Windows @code{CVTRES} program. 4124 4125When @command{windres} generates an @code{rc} file, the output is similar 4126but not identical to the format expected for the input. When an input 4127@code{rc} file refers to an external filename, an output @code{rc} file 4128will instead include the file contents. 4129 4130If the input or output format is not specified, @command{windres} will 4131guess based on the file name, or, for the input file, the file contents. 4132A file with an extension of @file{.rc} will be treated as an @code{rc} 4133file, a file with an extension of @file{.res} will be treated as a 4134@code{res} file, and a file with an extension of @file{.o} or 4135@file{.exe} will be treated as a @code{coff} file. 4136 4137If no output file is specified, @command{windres} will print the resources 4138in @code{rc} format to standard output. 4139 4140The normal use is for you to write an @code{rc} file, use @command{windres} 4141to convert it to a COFF object file, and then link the COFF file into 4142your application. This will make the resources described in the 4143@code{rc} file available to Windows. 4144 4145@c man end 4146 4147@c man begin OPTIONS windres 4148 4149@table @env 4150@item -i @var{filename} 4151@itemx --input @var{filename} 4152The name of the input file. If this option is not used, then 4153@command{windres} will use the first non-option argument as the input file 4154name. If there are no non-option arguments, then @command{windres} will 4155read from standard input. @command{windres} can not read a COFF file from 4156standard input. 4157 4158@item -o @var{filename} 4159@itemx --output @var{filename} 4160The name of the output file. If this option is not used, then 4161@command{windres} will use the first non-option argument, after any used 4162for the input file name, as the output file name. If there is no 4163non-option argument, then @command{windres} will write to standard output. 4164@command{windres} can not write a COFF file to standard output. Note, 4165for compatibility with @command{rc} the option @option{-fo} is also 4166accepted, but its use is not recommended. 4167 4168@item -J @var{format} 4169@itemx --input-format @var{format} 4170The input format to read. @var{format} may be @samp{res}, @samp{rc}, or 4171@samp{coff}. If no input format is specified, @command{windres} will 4172guess, as described above. 4173 4174@item -O @var{format} 4175@itemx --output-format @var{format} 4176The output format to generate. @var{format} may be @samp{res}, 4177@samp{rc}, or @samp{coff}. If no output format is specified, 4178@command{windres} will guess, as described above. 4179 4180@item -F @var{target} 4181@itemx --target @var{target} 4182Specify the BFD format to use for a COFF file as input or output. This 4183is a BFD target name; you can use the @option{--help} option to see a list 4184of supported targets. Normally @command{windres} will use the default 4185format, which is the first one listed by the @option{--help} option. 4186@ifclear man 4187@ref{Target Selection}. 4188@end ifclear 4189 4190@item --preprocessor @var{program} 4191When @command{windres} reads an @code{rc} file, it runs it through the C 4192preprocessor first. This option may be used to specify the preprocessor 4193to use, including any leading arguments. The default preprocessor 4194argument is @code{gcc -E -xc-header -DRC_INVOKED}. 4195 4196@item --preprocessor-arg @var{option} 4197When @command{windres} reads an @code{rc} file, it runs it through 4198the C preprocessor first. This option may be used to specify additional 4199text to be passed to preprocessor on its command line. 4200This option can be used multiple times to add multiple options to the 4201preprocessor command line. 4202 4203@item -I @var{directory} 4204@itemx --include-dir @var{directory} 4205Specify an include directory to use when reading an @code{rc} file. 4206@command{windres} will pass this to the preprocessor as an @option{-I} 4207option. @command{windres} will also search this directory when looking for 4208files named in the @code{rc} file. If the argument passed to this command 4209matches any of the supported @var{formats} (as described in the @option{-J} 4210option), it will issue a deprecation warning, and behave just like the 4211@option{-J} option. New programs should not use this behaviour. If a 4212directory happens to match a @var{format}, simple prefix it with @samp{./} 4213to disable the backward compatibility. 4214 4215@item -D @var{target} 4216@itemx --define @var{sym}[=@var{val}] 4217Specify a @option{-D} option to pass to the preprocessor when reading an 4218@code{rc} file. 4219 4220@item -U @var{target} 4221@itemx --undefine @var{sym} 4222Specify a @option{-U} option to pass to the preprocessor when reading an 4223@code{rc} file. 4224 4225@item -r 4226Ignored for compatibility with rc. 4227 4228@item -v 4229Enable verbose mode. This tells you what the preprocessor is if you 4230didn't specify one. 4231 4232@item -c @var{val} 4233@item --codepage @var{val} 4234Specify the default codepage to use when reading an @code{rc} file. 4235@var{val} should be a hexadecimal prefixed by @samp{0x} or decimal 4236codepage code. The valid range is from zero up to 0xffff, but the 4237validity of the codepage is host and configuration dependent. 4238 4239@item -l @var{val} 4240@item --language @var{val} 4241Specify the default language to use when reading an @code{rc} file. 4242@var{val} should be a hexadecimal language code. The low eight bits are 4243the language, and the high eight bits are the sublanguage. 4244 4245@item --use-temp-file 4246Use a temporary file to instead of using popen to read the output of 4247the preprocessor. Use this option if the popen implementation is buggy 4248on the host (eg., certain non-English language versions of Windows 95 and 4249Windows 98 are known to have buggy popen where the output will instead 4250go the console). 4251 4252@item --no-use-temp-file 4253Use popen, not a temporary file, to read the output of the preprocessor. 4254This is the default behaviour. 4255 4256@item -h 4257@item --help 4258Prints a usage summary. 4259 4260@item -V 4261@item --version 4262Prints the version number for @command{windres}. 4263 4264@item --yydebug 4265If @command{windres} is compiled with @code{YYDEBUG} defined as @code{1}, 4266this will turn on parser debugging. 4267@end table 4268 4269@c man end 4270 4271@ignore 4272@c man begin SEEALSO windres 4273the Info entries for @file{binutils}. 4274@c man end 4275@end ignore 4276 4277@node dlltool 4278@chapter dlltool 4279@cindex DLL 4280@kindex dlltool 4281 4282@command{dlltool} is used to create the files needed to create dynamic 4283link libraries (DLLs) on systems which understand PE format image 4284files such as Windows. A DLL contains an export table which contains 4285information that the runtime loader needs to resolve references from a 4286referencing program. 4287 4288The export table is generated by this program by reading in a 4289@file{.def} file or scanning the @file{.a} and @file{.o} files which 4290will be in the DLL. A @file{.o} file can contain information in 4291special @samp{.drectve} sections with export information. 4292 4293@quotation 4294@emph{Note:} @command{dlltool} is not always built as part of the 4295binary utilities, since it is only useful for those targets which 4296support DLLs. 4297@end quotation 4298 4299@c man title dlltool create files needed to build and use DLLs 4300 4301@smallexample 4302@c man begin SYNOPSIS dlltool 4303dlltool [@option{-d}|@option{--input-def} @var{def-file-name}] 4304 [@option{-b}|@option{--base-file} @var{base-file-name}] 4305 [@option{-e}|@option{--output-exp} @var{exports-file-name}] 4306 [@option{-z}|@option{--output-def} @var{def-file-name}] 4307 [@option{-l}|@option{--output-lib} @var{library-file-name}] 4308 [@option{-y}|@option{--output-delaylib} @var{library-file-name}] 4309 [@option{--export-all-symbols}] [@option{--no-export-all-symbols}] 4310 [@option{--exclude-symbols} @var{list}] 4311 [@option{--no-default-excludes}] 4312 [@option{-S}|@option{--as} @var{path-to-assembler}] [@option{-f}|@option{--as-flags} @var{options}] 4313 [@option{-D}|@option{--dllname} @var{name}] [@option{-m}|@option{--machine} @var{machine}] 4314 [@option{-a}|@option{--add-indirect}] 4315 [@option{-U}|@option{--add-underscore}] [@option{--add-stdcall-underscore}] 4316 [@option{-k}|@option{--kill-at}] [@option{-A}|@option{--add-stdcall-alias}] 4317 [@option{-p}|@option{--ext-prefix-alias} @var{prefix}] 4318 [@option{-x}|@option{--no-idata4}] [@option{-c}|@option{--no-idata5}] 4319 [@option{--use-nul-prefixed-import-tables}] 4320 [@option{-I}|@option{--identify} @var{library-file-name}] [@option{--identify-strict}] 4321 [@option{-i}|@option{--interwork}] 4322 [@option{-n}|@option{--nodelete}] [@option{-t}|@option{--temp-prefix} @var{prefix}] 4323 [@option{-v}|@option{--verbose}] 4324 [@option{-h}|@option{--help}] [@option{-V}|@option{--version}] 4325 [@option{--no-leading-underscore}] [@option{--leading-underscore}] 4326 [object-file @dots{}] 4327@c man end 4328@end smallexample 4329 4330@c man begin DESCRIPTION dlltool 4331 4332@command{dlltool} reads its inputs, which can come from the @option{-d} and 4333@option{-b} options as well as object files specified on the command 4334line. It then processes these inputs and if the @option{-e} option has 4335been specified it creates a exports file. If the @option{-l} option 4336has been specified it creates a library file and if the @option{-z} option 4337has been specified it creates a def file. Any or all of the @option{-e}, 4338@option{-l} and @option{-z} options can be present in one invocation of 4339dlltool. 4340 4341When creating a DLL, along with the source for the DLL, it is necessary 4342to have three other files. @command{dlltool} can help with the creation of 4343these files. 4344 4345The first file is a @file{.def} file which specifies which functions are 4346exported from the DLL, which functions the DLL imports, and so on. This 4347is a text file and can be created by hand, or @command{dlltool} can be used 4348to create it using the @option{-z} option. In this case @command{dlltool} 4349will scan the object files specified on its command line looking for 4350those functions which have been specially marked as being exported and 4351put entries for them in the @file{.def} file it creates. 4352 4353In order to mark a function as being exported from a DLL, it needs to 4354have an @option{-export:<name_of_function>} entry in the @samp{.drectve} 4355section of the object file. This can be done in C by using the 4356asm() operator: 4357 4358@smallexample 4359 asm (".section .drectve"); 4360 asm (".ascii \"-export:my_func\""); 4361 4362 int my_func (void) @{ @dots{} @} 4363@end smallexample 4364 4365The second file needed for DLL creation is an exports file. This file 4366is linked with the object files that make up the body of the DLL and it 4367handles the interface between the DLL and the outside world. This is a 4368binary file and it can be created by giving the @option{-e} option to 4369@command{dlltool} when it is creating or reading in a @file{.def} file. 4370 4371The third file needed for DLL creation is the library file that programs 4372will link with in order to access the functions in the DLL (an `import 4373library'). This file can be created by giving the @option{-l} option to 4374dlltool when it is creating or reading in a @file{.def} file. 4375 4376If the @option{-y} option is specified, dlltool generates a delay-import 4377library that can be used instead of the normal import library to allow 4378a program to link to the dll only as soon as an imported function is 4379called for the first time. The resulting executable will need to be 4380linked to the static delayimp library containing __delayLoadHelper2(), 4381which in turn will import LoadLibraryA and GetProcAddress from kernel32. 4382 4383@command{dlltool} builds the library file by hand, but it builds the 4384exports file by creating temporary files containing assembler statements 4385and then assembling these. The @option{-S} command-line option can be 4386used to specify the path to the assembler that dlltool will use, 4387and the @option{-f} option can be used to pass specific flags to that 4388assembler. The @option{-n} can be used to prevent dlltool from deleting 4389these temporary assembler files when it is done, and if @option{-n} is 4390specified twice then this will prevent dlltool from deleting the 4391temporary object files it used to build the library. 4392 4393Here is an example of creating a DLL from a source file @samp{dll.c} and 4394also creating a program (from an object file called @samp{program.o}) 4395that uses that DLL: 4396 4397@smallexample 4398 gcc -c dll.c 4399 dlltool -e exports.o -l dll.lib dll.o 4400 gcc dll.o exports.o -o dll.dll 4401 gcc program.o dll.lib -o program 4402@end smallexample 4403 4404 4405@command{dlltool} may also be used to query an existing import library 4406to determine the name of the DLL to which it is associated. See the 4407description of the @option{-I} or @option{--identify} option. 4408 4409@c man end 4410 4411@c man begin OPTIONS dlltool 4412 4413The command-line options have the following meanings: 4414 4415@table @env 4416 4417@item -d @var{filename} 4418@itemx --input-def @var{filename} 4419@cindex input .def file 4420Specifies the name of a @file{.def} file to be read in and processed. 4421 4422@item -b @var{filename} 4423@itemx --base-file @var{filename} 4424@cindex base files 4425Specifies the name of a base file to be read in and processed. The 4426contents of this file will be added to the relocation section in the 4427exports file generated by dlltool. 4428 4429@item -e @var{filename} 4430@itemx --output-exp @var{filename} 4431Specifies the name of the export file to be created by dlltool. 4432 4433@item -z @var{filename} 4434@itemx --output-def @var{filename} 4435Specifies the name of the @file{.def} file to be created by dlltool. 4436 4437@item -l @var{filename} 4438@itemx --output-lib @var{filename} 4439Specifies the name of the library file to be created by dlltool. 4440 4441@item -y @var{filename} 4442@itemx --output-delaylib @var{filename} 4443Specifies the name of the delay-import library file to be created by dlltool. 4444 4445@item --export-all-symbols 4446Treat all global and weak defined symbols found in the input object 4447files as symbols to be exported. There is a small list of symbols which 4448are not exported by default; see the @option{--no-default-excludes} 4449option. You may add to the list of symbols to not export by using the 4450@option{--exclude-symbols} option. 4451 4452@item --no-export-all-symbols 4453Only export symbols explicitly listed in an input @file{.def} file or in 4454@samp{.drectve} sections in the input object files. This is the default 4455behaviour. The @samp{.drectve} sections are created by @samp{dllexport} 4456attributes in the source code. 4457 4458@item --exclude-symbols @var{list} 4459Do not export the symbols in @var{list}. This is a list of symbol names 4460separated by comma or colon characters. The symbol names should not 4461contain a leading underscore. This is only meaningful when 4462@option{--export-all-symbols} is used. 4463 4464@item --no-default-excludes 4465When @option{--export-all-symbols} is used, it will by default avoid 4466exporting certain special symbols. The current list of symbols to avoid 4467exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0}, 4468@samp{impure_ptr}. You may use the @option{--no-default-excludes} option 4469to go ahead and export these special symbols. This is only meaningful 4470when @option{--export-all-symbols} is used. 4471 4472@item -S @var{path} 4473@itemx --as @var{path} 4474Specifies the path, including the filename, of the assembler to be used 4475to create the exports file. 4476 4477@item -f @var{options} 4478@itemx --as-flags @var{options} 4479Specifies any specific command-line options to be passed to the 4480assembler when building the exports file. This option will work even if 4481the @option{-S} option is not used. This option only takes one argument, 4482and if it occurs more than once on the command line, then later 4483occurrences will override earlier occurrences. So if it is necessary to 4484pass multiple options to the assembler they should be enclosed in 4485double quotes. 4486 4487@item -D @var{name} 4488@itemx --dll-name @var{name} 4489Specifies the name to be stored in the @file{.def} file as the name of 4490the DLL when the @option{-e} option is used. If this option is not 4491present, then the filename given to the @option{-e} option will be 4492used as the name of the DLL. 4493 4494@item -m @var{machine} 4495@itemx -machine @var{machine} 4496Specifies the type of machine for which the library file should be 4497built. @command{dlltool} has a built in default type, depending upon how 4498it was created, but this option can be used to override that. This is 4499normally only useful when creating DLLs for an ARM processor, when the 4500contents of the DLL are actually encode using Thumb instructions. 4501 4502@item -a 4503@itemx --add-indirect 4504Specifies that when @command{dlltool} is creating the exports file it 4505should add a section which allows the exported functions to be 4506referenced without using the import library. Whatever the hell that 4507means! 4508 4509@item -U 4510@itemx --add-underscore 4511Specifies that when @command{dlltool} is creating the exports file it 4512should prepend an underscore to the names of @emph{all} exported symbols. 4513 4514@item --no-leading-underscore 4515@item --leading-underscore 4516Specifies whether standard symbol should be forced to be prefixed, or 4517not. 4518 4519@item --add-stdcall-underscore 4520Specifies that when @command{dlltool} is creating the exports file it 4521should prepend an underscore to the names of exported @emph{stdcall} 4522functions. Variable names and non-stdcall function names are not modified. 4523This option is useful when creating GNU-compatible import libs for third 4524party DLLs that were built with MS-Windows tools. 4525 4526@item -k 4527@itemx --kill-at 4528Specifies that @samp{@@<number>} suffixes should be omitted from the names 4529of stdcall functions that will be imported from the DLL. This is 4530useful when creating an import library for a DLL which exports stdcall 4531functions but without the usual @samp{@@<number>} symbol name suffix. 4532 4533This does not change the naming of symbols provided by the import library 4534to programs linked against it, but only the entries in the import table 4535(ie the .idata section). 4536 4537@item -A 4538@itemx --add-stdcall-alias 4539Specifies that when @command{dlltool} is creating the exports file it 4540should add aliases for stdcall symbols without @samp{@@ <number>} 4541in addition to the symbols with @samp{@@ <number>}. 4542 4543@item -p 4544@itemx --ext-prefix-alias @var{prefix} 4545Causes @command{dlltool} to create external aliases for all DLL 4546imports with the specified prefix. The aliases are created for both 4547external and import symbols with no leading underscore. 4548 4549@item -x 4550@itemx --no-idata4 4551Specifies that when @command{dlltool} is creating the exports and library 4552files it should omit the @code{.idata4} section. This is for compatibility 4553with certain operating systems. 4554 4555@item --use-nul-prefixed-import-tables 4556Specifies that when @command{dlltool} is creating the exports and library 4557files it should prefix the @code{.idata4} and @code{.idata5} by zero an 4558element. This emulates old gnu import library generation of 4559@code{dlltool}. By default this option is turned off. 4560 4561@item -c 4562@itemx --no-idata5 4563Specifies that when @command{dlltool} is creating the exports and library 4564files it should omit the @code{.idata5} section. This is for compatibility 4565with certain operating systems. 4566 4567@item -I @var{filename} 4568@itemx --identify @var{filename} 4569Specifies that @command{dlltool} should inspect the import library 4570indicated by @var{filename} and report, on @code{stdout}, the name(s) 4571of the associated DLL(s). This can be performed in addition to any 4572other operations indicated by the other options and arguments. 4573@command{dlltool} fails if the import library does not exist or is not 4574actually an import library. See also @option{--identify-strict}. 4575 4576@item --identify-strict 4577Modifies the behavior of the @option{--identify} option, such 4578that an error is reported if @var{filename} is associated with 4579more than one DLL. 4580 4581@item -i 4582@itemx --interwork 4583Specifies that @command{dlltool} should mark the objects in the library 4584file and exports file that it produces as supporting interworking 4585between ARM and Thumb code. 4586 4587@item -n 4588@itemx --nodelete 4589Makes @command{dlltool} preserve the temporary assembler files it used to 4590create the exports file. If this option is repeated then dlltool will 4591also preserve the temporary object files it uses to create the library 4592file. 4593 4594@item -t @var{prefix} 4595@itemx --temp-prefix @var{prefix} 4596Makes @command{dlltool} use @var{prefix} when constructing the names of 4597temporary assembler and object files. By default, the temp file prefix 4598is generated from the pid. 4599 4600@item -v 4601@itemx --verbose 4602Make dlltool describe what it is doing. 4603 4604@item -h 4605@itemx --help 4606Displays a list of command-line options and then exits. 4607 4608@item -V 4609@itemx --version 4610Displays dlltool's version number and then exits. 4611 4612@end table 4613 4614@c man end 4615 4616@menu 4617* def file format:: The format of the dlltool @file{.def} file 4618@end menu 4619 4620@node def file format 4621@section The format of the @command{dlltool} @file{.def} file 4622 4623A @file{.def} file contains any number of the following commands: 4624 4625@table @asis 4626 4627@item @code{NAME} @var{name} @code{[ ,} @var{base} @code{]} 4628The result is going to be named @var{name}@code{.exe}. 4629 4630@item @code{LIBRARY} @var{name} @code{[ ,} @var{base} @code{]} 4631The result is going to be named @var{name}@code{.dll}. 4632Note: If you want to use LIBRARY as name then you need to quote. Otherwise 4633this will fail due a necessary hack for libtool (see PR binutils/13710 for more 4634details). 4635 4636@item @code{EXPORTS ( ( (} @var{name1} @code{[ = } @var{name2} @code{] ) | ( } @var{name1} @code{=} @var{module-name} @code{.} @var{external-name} @code{) ) [ == } @var{its_name} @code{]} 4637@item @code{[} @var{integer} @code{] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *} 4638Declares @var{name1} as an exported symbol from the DLL, with optional 4639ordinal number @var{integer}, or declares @var{name1} as an alias 4640(forward) of the function @var{external-name} in the DLL. 4641If @var{its_name} is specified, this name is used as string in export table. 4642@var{module-name}. 4643Note: The @code{EXPORTS} has to be the last command in .def file, as keywords 4644are treated - beside @code{LIBRARY} - as simple name-identifiers. 4645If you want to use LIBRARY as name then you need to quote it. 4646 4647@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{]} *} 4648Declares that @var{external-name} or the exported function whose 4649ordinal number is @var{integer} is to be imported from the file 4650@var{module-name}. If @var{internal-name} is specified then this is 4651the name that the imported function will be referred to in the body of 4652the DLL. 4653If @var{its_name} is specified, this name is used as string in import table. 4654Note: The @code{IMPORTS} has to be the last command in .def file, as keywords 4655are treated - beside @code{LIBRARY} - as simple name-identifiers. 4656If you want to use LIBRARY as name then you need to quote it. 4657 4658@item @code{DESCRIPTION} @var{string} 4659Puts @var{string} into the output @file{.exp} file in the 4660@code{.rdata} section. 4661 4662@item @code{STACKSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]} 4663@item @code{HEAPSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]} 4664Generates @code{--stack} or @code{--heap} 4665@var{number-reserve},@var{number-commit} in the output @code{.drectve} 4666section. The linker will see this and act upon it. 4667 4668@item @code{CODE} @var{attr} @code{+} 4669@item @code{DATA} @var{attr} @code{+} 4670@item @code{SECTIONS (} @var{section-name} @var{attr}@code{ + ) *} 4671Generates @code{--attr} @var{section-name} @var{attr} in the output 4672@code{.drectve} section, where @var{attr} is one of @code{READ}, 4673@code{WRITE}, @code{EXECUTE} or @code{SHARED}. The linker will see 4674this and act upon it. 4675 4676@end table 4677 4678@ignore 4679@c man begin SEEALSO dlltool 4680The Info pages for @file{binutils}. 4681@c man end 4682@end ignore 4683 4684@node readelf 4685@chapter readelf 4686 4687@cindex ELF file information 4688@kindex readelf 4689 4690@c man title readelf display information about ELF files 4691 4692@smallexample 4693@c man begin SYNOPSIS readelf 4694readelf [@option{-a}|@option{--all}] 4695 [@option{-h}|@option{--file-header}] 4696 [@option{-l}|@option{--program-headers}|@option{--segments}] 4697 [@option{-S}|@option{--section-headers}|@option{--sections}] 4698 [@option{-g}|@option{--section-groups}] 4699 [@option{-t}|@option{--section-details}] 4700 [@option{-e}|@option{--headers}] 4701 [@option{-s}|@option{--syms}|@option{--symbols}] 4702 [@option{--dyn-syms}] 4703 [@option{--demangle@var{=style}}|@option{--no-demangle}] 4704 [@option{--recurse-limit}|@option{--no-recurse-limit}] 4705 [@option{-n}|@option{--notes}] 4706 [@option{-r}|@option{--relocs}] 4707 [@option{-u}|@option{--unwind}] 4708 [@option{-d}|@option{--dynamic}] 4709 [@option{-V}|@option{--version-info}] 4710 [@option{-A}|@option{--arch-specific}] 4711 [@option{-D}|@option{--use-dynamic}] 4712 [@option{-L}|@option{--lint}|@option{--enable-checks}] 4713 [@option{-x} <number or name>|@option{--hex-dump=}<number or name>] 4714 [@option{-p} <number or name>|@option{--string-dump=}<number or name>] 4715 [@option{-R} <number or name>|@option{--relocated-dump=}<number or name>] 4716 [@option{-z}|@option{--decompress}] 4717 [@option{-c}|@option{--archive-index}] 4718 [@option{-w[lLiaprmfFsoORtUuTgAckK]}| 4719 @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,=follow-links]] 4720 [@option{--dwarf-depth=@var{n}}] 4721 [@option{--dwarf-start=@var{n}}] 4722 [@option{--ctf=}@var{section}] 4723 [@option{--ctf-parent=}@var{section}] 4724 [@option{--ctf-symbols=}@var{section}] 4725 [@option{--ctf-strings=}@var{section}] 4726 [@option{-I}|@option{--histogram}] 4727 [@option{-v}|@option{--version}] 4728 [@option{-W}|@option{--wide}] 4729 [@option{-T}|@option{--silent-truncation}] 4730 [@option{-H}|@option{--help}] 4731 @var{elffile}@dots{} 4732@c man end 4733@end smallexample 4734 4735@c man begin DESCRIPTION readelf 4736 4737@command{readelf} displays information about one or more ELF format object 4738files. The options control what particular information to display. 4739 4740@var{elffile}@dots{} are the object files to be examined. 32-bit and 474164-bit ELF files are supported, as are archives containing ELF files. 4742 4743This program performs a similar function to @command{objdump} but it 4744goes into more detail and it exists independently of the @sc{bfd} 4745library, so if there is a bug in @sc{bfd} then readelf will not be 4746affected. 4747 4748@c man end 4749 4750@c man begin OPTIONS readelf 4751 4752The long and short forms of options, shown here as alternatives, are 4753equivalent. At least one option besides @samp{-v} or @samp{-H} must be 4754given. 4755 4756@table @env 4757@item -a 4758@itemx --all 4759Equivalent to specifying @option{--file-header}, 4760@option{--program-headers}, @option{--sections}, @option{--symbols}, 4761@option{--relocs}, @option{--dynamic}, @option{--notes}, 4762@option{--version-info}, @option{--arch-specific}, @option{--unwind}, 4763@option{--section-groups} and @option{--histogram}. 4764 4765Note - this option does not enable @option{--use-dynamic} itself, so 4766if that option is not present on the command line then dynamic symbols 4767and dynamic relocs will not be displayed. 4768 4769@item -h 4770@itemx --file-header 4771@cindex ELF file header information 4772Displays the information contained in the ELF header at the start of the 4773file. 4774 4775@item -l 4776@itemx --program-headers 4777@itemx --segments 4778@cindex ELF program header information 4779@cindex ELF segment information 4780Displays the information contained in the file's segment headers, if it 4781has any. 4782 4783@item -S 4784@itemx --sections 4785@itemx --section-headers 4786@cindex ELF section information 4787Displays the information contained in the file's section headers, if it 4788has any. 4789 4790@item -g 4791@itemx --section-groups 4792@cindex ELF section group information 4793Displays the information contained in the file's section groups, if it 4794has any. 4795 4796@item -t 4797@itemx --section-details 4798@cindex ELF section information 4799Displays the detailed section information. Implies @option{-S}. 4800 4801@item -s 4802@itemx --symbols 4803@itemx --syms 4804@cindex ELF symbol table information 4805Displays the entries in symbol table section of the file, if it has one. 4806If a symbol has version information associated with it then this is 4807displayed as well. The version string is displayed as a suffix to the 4808symbol name, preceded by an @@ character. For example 4809@samp{foo@@VER_1}. If the version is the default version to be used 4810when resolving unversioned references to the symbol then it is 4811displayed as a suffix preceded by two @@ characters. For example 4812@samp{foo@@@@VER_2}. 4813 4814@item --dyn-syms 4815@cindex ELF dynamic symbol table information 4816Displays the entries in dynamic symbol table section of the file, if it 4817has one. The output format is the same as the format used by the 4818@option{--syms} option. 4819 4820@item -C 4821@itemx --demangle[=@var{style}] 4822@cindex demangling in nm 4823Decode (@dfn{demangle}) low-level symbol names into user-level names. 4824This makes C++ function names readable. Different compilers have 4825different mangling styles. The optional demangling style argument can 4826be used to choose an appropriate demangling style for your 4827compiler. @xref{c++filt}, for more information on demangling. 4828 4829@item --no-demangle 4830Do not demangle low-level symbol names. This is the default. 4831 4832@item --recurse-limit 4833@itemx --no-recurse-limit 4834@itemx --recursion-limit 4835@itemx --no-recursion-limit 4836Enables or disables a limit on the amount of recursion performed 4837whilst demangling strings. Since the name mangling formats allow for 4838an inifinite level of recursion it is possible to create strings whose 4839decoding will exhaust the amount of stack space available on the host 4840machine, triggering a memory fault. The limit tries to prevent this 4841from happening by restricting recursion to 2048 levels of nesting. 4842 4843The default is for this limit to be enabled, but disabling it may be 4844necessary in order to demangle truly complicated names. Note however 4845that if the recursion limit is disabled then stack exhaustion is 4846possible and any bug reports about such an event will be rejected. 4847 4848@item -e 4849@itemx --headers 4850Display all the headers in the file. Equivalent to @option{-h -l -S}. 4851 4852@item -n 4853@itemx --notes 4854@cindex ELF notes 4855Displays the contents of the NOTE segments and/or sections, if any. 4856 4857@item -r 4858@itemx --relocs 4859@cindex ELF reloc information 4860Displays the contents of the file's relocation section, if it has one. 4861 4862@item -u 4863@itemx --unwind 4864@cindex unwind information 4865Displays the contents of the file's unwind section, if it has one. Only 4866the unwind sections for IA64 ELF files, as well as ARM unwind tables 4867(@code{.ARM.exidx} / @code{.ARM.extab}) are currently supported. If 4868support is not yet implemented for your architecture you could try 4869dumping the contents of the @var{.eh_frames} section using the 4870@option{--debug-dump=frames} or @option{--debug-dump=frames-interp} 4871options. 4872 4873@item -d 4874@itemx --dynamic 4875@cindex ELF dynamic section information 4876Displays the contents of the file's dynamic section, if it has one. 4877 4878@item -V 4879@itemx --version-info 4880@cindex ELF version sections information 4881Displays the contents of the version sections in the file, it they 4882exist. 4883 4884@item -A 4885@itemx --arch-specific 4886Displays architecture-specific information in the file, if there 4887is any. 4888 4889@item -D 4890@itemx --use-dynamic 4891When displaying symbols, this option makes @command{readelf} use the 4892symbol hash tables in the file's dynamic section, rather than the 4893symbol table sections. 4894 4895When displaying relocations, this option makes @command{readelf} 4896display the dynamic relocations rather than the static relocations. 4897 4898@item -L 4899@itemx --lint 4900@itemx --enable-checks 4901Displays warning messages about possible problems with the file(s) 4902being examined. If used on its own then all of the contents of the 4903file(s) will be examined. If used with one of the dumping options 4904then the warning messages will only be produced for the things being 4905displayed. 4906 4907@item -x <number or name> 4908@itemx --hex-dump=<number or name> 4909Displays the contents of the indicated section as a hexadecimal bytes. 4910A number identifies a particular section by index in the section table; 4911any other string identifies all sections with that name in the object file. 4912 4913@item -R <number or name> 4914@itemx --relocated-dump=<number or name> 4915Displays the contents of the indicated section as a hexadecimal 4916bytes. A number identifies a particular section by index in the 4917section table; any other string identifies all sections with that name 4918in the object file. The contents of the section will be relocated 4919before they are displayed. 4920 4921@item -p <number or name> 4922@itemx --string-dump=<number or name> 4923Displays the contents of the indicated section as printable strings. 4924A number identifies a particular section by index in the section table; 4925any other string identifies all sections with that name in the object file. 4926 4927@item -z 4928@itemx --decompress 4929Requests that the section(s) being dumped by @option{x}, @option{R} or 4930@option{p} options are decompressed before being displayed. If the 4931section(s) are not compressed then they are displayed as is. 4932 4933@item -c 4934@itemx --archive-index 4935@cindex Archive file symbol index information 4936Displays the file symbol index information contained in the header part 4937of binary archives. Performs the same function as the @option{t} 4938command to @command{ar}, but without using the BFD library. @xref{ar}. 4939 4940@item -w[lLiaprmfFsOoRtUuTgAckK] 4941@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] 4942@include debug.options.texi 4943 4944@include ctf.options.texi 4945@item --ctf-symbols=@var{section} 4946@item --ctf-strings=@var{section} 4947Specify the name of another section from which the CTF file can inherit 4948strings and symbols. By default, the @code{.symtab} and its linked 4949string table are used. 4950 4951If either of @option{--ctf-symbols} or @option{--ctf-strings} is specified, the 4952other must be specified as well. 4953 4954@item -I 4955@itemx --histogram 4956Display a histogram of bucket list lengths when displaying the contents 4957of the symbol tables. 4958 4959@item -v 4960@itemx --version 4961Display the version number of readelf. 4962 4963@item -W 4964@itemx --wide 4965Don't break output lines to fit into 80 columns. By default 4966@command{readelf} breaks section header and segment listing lines for 496764-bit ELF files, so that they fit into 80 columns. This option causes 4968@command{readelf} to print each section header resp. each segment one a 4969single line, which is far more readable on terminals wider than 80 columns. 4970 4971@item -T 4972@itemx --silent-truncation 4973Normally when readelf is displaying a symbol name, and it has to 4974truncate the name to fit into an 80 column display, it will add a 4975suffix of @code{[...]} to the name. This command line option 4976disables this behaviour, allowing 5 more characters of the name to be 4977displayed and restoring the old behaviour of readelf (prior to release 49782.35). 4979 4980@item -H 4981@itemx --help 4982Display the command-line options understood by @command{readelf}. 4983 4984@end table 4985 4986@c man end 4987 4988@ignore 4989@c man begin SEEALSO readelf 4990objdump(1), and the Info entries for @file{binutils}. 4991@c man end 4992@end ignore 4993 4994@node elfedit 4995@chapter elfedit 4996 4997@cindex Update ELF header 4998@kindex elfedit 4999 5000@c man title elfedit update ELF header and program property of ELF files 5001 5002@smallexample 5003@c man begin SYNOPSIS elfedit 5004elfedit [@option{--input-mach=}@var{machine}] 5005 [@option{--input-type=}@var{type}] 5006 [@option{--input-osabi=}@var{osabi}] 5007 @option{--output-mach=}@var{machine} 5008 @option{--output-type=}@var{type} 5009 @option{--output-osabi=}@var{osabi} 5010 @option{--enable-x86-feature=}@var{feature} 5011 @option{--disable-x86-feature=}@var{feature} 5012 [@option{-v}|@option{--version}] 5013 [@option{-h}|@option{--help}] 5014 @var{elffile}@dots{} 5015@c man end 5016@end smallexample 5017 5018@c man begin DESCRIPTION elfedit 5019 5020@command{elfedit} updates the ELF header and program property of ELF 5021files which have the matching ELF machine and file types. The options 5022control how and which fields in the ELF header and program property 5023should be updated. 5024 5025@var{elffile}@dots{} are the ELF files to be updated. 32-bit and 502664-bit ELF files are supported, as are archives containing ELF files. 5027@c man end 5028 5029@c man begin OPTIONS elfedit 5030 5031The long and short forms of options, shown here as alternatives, are 5032equivalent. At least one of the @option{--output-mach}, 5033@option{--output-type}, @option{--output-osabi}, 5034@option{--enable-x86-feature} and @option{--disable-x86-feature} 5035options must be given. 5036 5037@table @env 5038 5039@item --input-mach=@var{machine} 5040Set the matching input ELF machine type to @var{machine}. If 5041@option{--input-mach} isn't specified, it will match any ELF 5042machine types. 5043 5044The supported ELF machine types are, @var{i386}, @var{IAMCU}, @var{L1OM}, 5045@var{K1OM} and @var{x86-64}. 5046 5047@item --output-mach=@var{machine} 5048Change the ELF machine type in the ELF header to @var{machine}. The 5049supported ELF machine types are the same as @option{--input-mach}. 5050 5051@item --input-type=@var{type} 5052Set the matching input ELF file type to @var{type}. If 5053@option{--input-type} isn't specified, it will match any ELF file types. 5054 5055The supported ELF file types are, @var{rel}, @var{exec} and @var{dyn}. 5056 5057@item --output-type=@var{type} 5058Change the ELF file type in the ELF header to @var{type}. The 5059supported ELF types are the same as @option{--input-type}. 5060 5061@item --input-osabi=@var{osabi} 5062Set the matching input ELF file OSABI to @var{osabi}. If 5063@option{--input-osabi} isn't specified, it will match any ELF OSABIs. 5064 5065The supported ELF OSABIs are, @var{none}, @var{HPUX}, @var{NetBSD}, 5066@var{GNU}, @var{Linux} (alias for @var{GNU}), 5067@var{Solaris}, @var{AIX}, @var{Irix}, 5068@var{FreeBSD}, @var{TRU64}, @var{Modesto}, @var{OpenBSD}, @var{OpenVMS}, 5069@var{NSK}, @var{AROS} and @var{FenixOS}. 5070 5071@item --output-osabi=@var{osabi} 5072Change the ELF OSABI in the ELF header to @var{osabi}. The 5073supported ELF OSABI are the same as @option{--input-osabi}. 5074 5075@item --enable-x86-feature=@var{feature} 5076Set the @var{feature} bit in program property in @var{exec} or @var{dyn} 5077ELF files with machine types of @var{i386} or @var{x86-64}. The 5078supported features are, @var{ibt} and @var{shstk}. 5079 5080@item --disable-x86-feature=@var{feature} 5081Clear the @var{feature} bit in program property in @var{exec} or 5082@var{dyn} ELF files with machine types of @var{i386} or @var{x86-64}. 5083The supported features are the same as @option{--enable-x86-feature}. 5084 5085Note: @option{--enable-x86-feature} and @option{--disable-x86-feature} 5086are available only on hosts with @samp{mmap} support. 5087 5088@item -v 5089@itemx --version 5090Display the version number of @command{elfedit}. 5091 5092@item -h 5093@itemx --help 5094Display the command-line options understood by @command{elfedit}. 5095 5096@end table 5097 5098@c man end 5099 5100@ignore 5101@c man begin SEEALSO elfedit 5102readelf(1), and the Info entries for @file{binutils}. 5103@c man end 5104@end ignore 5105 5106@node Common Options 5107@chapter Common Options 5108 5109The following command-line options are supported by all of the 5110programs described in this manual. 5111 5112@c man begin OPTIONS 5113@table @env 5114@include at-file.texi 5115@c man end 5116 5117@item --help 5118Display the command-line options supported by the program. 5119 5120@item --version 5121Display the version number of the program. 5122 5123@c man begin OPTIONS 5124@end table 5125@c man end 5126 5127@node Selecting the Target System 5128@chapter Selecting the Target System 5129 5130You can specify two aspects of the target system to the @sc{gnu} 5131binary file utilities, each in several ways: 5132 5133@itemize @bullet 5134@item 5135the target 5136 5137@item 5138the architecture 5139@end itemize 5140 5141In the following summaries, the lists of ways to specify values are in 5142order of decreasing precedence. The ways listed first override those 5143listed later. 5144 5145The commands to list valid values only list the values for which the 5146programs you are running were configured. If they were configured with 5147@option{--enable-targets=all}, the commands list most of the available 5148values, but a few are left out; not all targets can be configured in at 5149once because some of them can only be configured @dfn{native} (on hosts 5150with the same type as the target system). 5151 5152@menu 5153* Target Selection:: 5154* Architecture Selection:: 5155@end menu 5156 5157@node Target Selection 5158@section Target Selection 5159 5160A @dfn{target} is an object file format. A given target may be 5161supported for multiple architectures (@pxref{Architecture Selection}). 5162A target selection may also have variations for different operating 5163systems or architectures. 5164 5165The command to list valid target values is @samp{objdump -i} 5166(the first column of output contains the relevant information). 5167 5168Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips}, 5169@samp{a.out-sunos-big}. 5170 5171You can also specify a target using a configuration triplet. This is 5172the same sort of name that is passed to @file{configure} to specify a 5173target. When you use a configuration triplet as an argument, it must be 5174fully canonicalized. You can see the canonical version of a triplet by 5175running the shell script @file{config.sub} which is included with the 5176sources. 5177 5178Some sample configuration triplets are: @samp{m68k-hp-bsd}, 5179@samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}. 5180 5181@subheading @command{objdump} Target 5182 5183Ways to specify: 5184 5185@enumerate 5186@item 5187command-line option: @option{-b} or @option{--target} 5188 5189@item 5190environment variable @code{GNUTARGET} 5191 5192@item 5193deduced from the input file 5194@end enumerate 5195 5196@subheading @command{objcopy} and @command{strip} Input Target 5197 5198Ways to specify: 5199 5200@enumerate 5201@item 5202command-line options: @option{-I} or @option{--input-target}, or @option{-F} or @option{--target} 5203 5204@item 5205environment variable @code{GNUTARGET} 5206 5207@item 5208deduced from the input file 5209@end enumerate 5210 5211@subheading @command{objcopy} and @command{strip} Output Target 5212 5213Ways to specify: 5214 5215@enumerate 5216@item 5217command-line options: @option{-O} or @option{--output-target}, or @option{-F} or @option{--target} 5218 5219@item 5220the input target (see ``@command{objcopy} and @command{strip} Input Target'' above) 5221 5222@item 5223environment variable @code{GNUTARGET} 5224 5225@item 5226deduced from the input file 5227@end enumerate 5228 5229@subheading @command{nm}, @command{size}, and @command{strings} Target 5230 5231Ways to specify: 5232 5233@enumerate 5234@item 5235command-line option: @option{--target} 5236 5237@item 5238environment variable @code{GNUTARGET} 5239 5240@item 5241deduced from the input file 5242@end enumerate 5243 5244@node Architecture Selection 5245@section Architecture Selection 5246 5247An @dfn{architecture} is a type of @sc{cpu} on which an object file is 5248to run. Its name may contain a colon, separating the name of the 5249processor family from the name of the particular @sc{cpu}. 5250 5251The command to list valid architecture values is @samp{objdump -i} (the 5252second column contains the relevant information). 5253 5254Sample values: @samp{m68k:68020}, @samp{mips:3000}, @samp{sparc}. 5255 5256@subheading @command{objdump} Architecture 5257 5258Ways to specify: 5259 5260@enumerate 5261@item 5262command-line option: @option{-m} or @option{--architecture} 5263 5264@item 5265deduced from the input file 5266@end enumerate 5267 5268@subheading @command{objcopy}, @command{nm}, @command{size}, @command{strings} Architecture 5269 5270Ways to specify: 5271 5272@enumerate 5273@item 5274deduced from the input file 5275@end enumerate 5276 5277@node debuginfod 5278@chapter debuginfod 5279@cindex separate debug files 5280 5281debuginfod is a web service that indexes ELF/DWARF debugging resources 5282by build-id and serves them over HTTP. 5283 5284Binutils can be built with the debuginfod client library 5285@code{libdebuginfod} using the @option{--with-debuginfod} configure option. 5286This option is enabled by default if @code{libdebuginfod} is installed 5287and found at configure time. This allows @command{objdump} and 5288@command{readelf} to automatically query debuginfod servers for 5289separate debug files when the files are otherwise not found. 5290 5291debuginfod is packaged with elfutils, starting with version 0.178. 5292You can get the latest version from `https://sourceware.org/elfutils/'. 5293 5294@node Reporting Bugs 5295@chapter Reporting Bugs 5296@cindex bugs 5297@cindex reporting bugs 5298 5299Your bug reports play an essential role in making the binary utilities 5300reliable. 5301 5302Reporting a bug may help you by bringing a solution to your problem, or 5303it may not. But in any case the principal function of a bug report is 5304to help the entire community by making the next version of the binary 5305utilities work better. Bug reports are your contribution to their 5306maintenance. 5307 5308In order for a bug report to serve its purpose, you must include the 5309information that enables us to fix the bug. 5310 5311@menu 5312* Bug Criteria:: Have you found a bug? 5313* Bug Reporting:: How to report bugs 5314@end menu 5315 5316@node Bug Criteria 5317@section Have You Found a Bug? 5318@cindex bug criteria 5319 5320If you are not sure whether you have found a bug, here are some guidelines: 5321 5322@itemize @bullet 5323@cindex fatal signal 5324@cindex crash 5325@item 5326If a binary utility gets a fatal signal, for any input whatever, that is 5327a bug. Reliable utilities never crash. 5328 5329@cindex error on valid input 5330@item 5331If a binary utility produces an error message for valid input, that is a 5332bug. 5333 5334@item 5335If you are an experienced user of binary utilities, your suggestions for 5336improvement are welcome in any case. 5337@end itemize 5338 5339@node Bug Reporting 5340@section How to Report Bugs 5341@cindex bug reports 5342@cindex bugs, reporting 5343 5344A number of companies and individuals offer support for @sc{gnu} 5345products. If you obtained the binary utilities from a support 5346organization, we recommend you contact that organization first. 5347 5348You can find contact information for many support companies and 5349individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 5350distribution. 5351 5352@ifset BUGURL 5353In any event, we also recommend that you send bug reports for the binary 5354utilities to @value{BUGURL}. 5355@end ifset 5356 5357The fundamental principle of reporting bugs usefully is this: 5358@strong{report all the facts}. If you are not sure whether to state a 5359fact or leave it out, state it! 5360 5361Often people omit facts because they think they know what causes the 5362problem and assume that some details do not matter. Thus, you might 5363assume that the name of a file you use in an example does not matter. 5364Well, probably it does not, but one cannot be sure. Perhaps the bug is 5365a stray memory reference which happens to fetch from the location where 5366that pathname is stored in memory; perhaps, if the pathname were 5367different, the contents of that location would fool the utility into 5368doing the right thing despite the bug. Play it safe and give a 5369specific, complete example. That is the easiest thing for you to do, 5370and the most helpful. 5371 5372Keep in mind that the purpose of a bug report is to enable us to fix the bug if 5373it is new to us. Therefore, always write your bug reports on the assumption 5374that the bug has not been reported previously. 5375 5376Sometimes people give a few sketchy facts and ask, ``Does this ring a 5377bell?'' This cannot help us fix a bug, so it is basically useless. We 5378respond by asking for enough details to enable us to investigate. 5379You might as well expedite matters by sending them to begin with. 5380 5381To enable us to fix the bug, you should include all these things: 5382 5383@itemize @bullet 5384@item 5385The version of the utility. Each utility announces it if you start it 5386with the @option{--version} argument. 5387 5388Without this, we will not know whether there is any point in looking for 5389the bug in the current version of the binary utilities. 5390 5391@item 5392Any patches you may have applied to the source, including any patches 5393made to the @code{BFD} library. 5394 5395@item 5396The type of machine you are using, and the operating system name and 5397version number. 5398 5399@item 5400What compiler (and its version) was used to compile the utilities---e.g. 5401``@code{gcc-2.7}''. 5402 5403@item 5404The command arguments you gave the utility to observe the bug. To 5405guarantee you will not omit something important, list them all. A copy 5406of the Makefile (or the output from make) is sufficient. 5407 5408If we were to try to guess the arguments, we would probably guess wrong 5409and then we might not encounter the bug. 5410 5411@item 5412A complete input file, or set of input files, that will reproduce the 5413bug. If the utility is reading an object file or files, then it is 5414generally most helpful to send the actual object files. 5415 5416If the source files were produced exclusively using @sc{gnu} programs 5417(e.g., @command{gcc}, @command{gas}, and/or the @sc{gnu} @command{ld}), then it 5418may be OK to send the source files rather than the object files. In 5419this case, be sure to say exactly what version of @command{gcc}, or 5420whatever, was used to produce the object files. Also say how 5421@command{gcc}, or whatever, was configured. 5422 5423@item 5424A description of what behavior you observe that you believe is 5425incorrect. For example, ``It gets a fatal signal.'' 5426 5427Of course, if the bug is that the utility gets a fatal signal, then we 5428will certainly notice it. But if the bug is incorrect output, we might 5429not notice unless it is glaringly wrong. You might as well not give us 5430a chance to make a mistake. 5431 5432Even if the problem you experience is a fatal signal, you should still 5433say so explicitly. Suppose something strange is going on, such as your 5434copy of the utility is out of sync, or you have encountered a bug in 5435the C library on your system. (This has happened!) Your copy might 5436crash and ours would not. If you told us to expect a crash, then when 5437ours fails to crash, we would know that the bug was not happening for 5438us. If you had not told us to expect a crash, then we would not be able 5439to draw any conclusion from our observations. 5440 5441@item 5442If you wish to suggest changes to the source, send us context diffs, as 5443generated by @command{diff} with the @option{-u}, @option{-c}, or @option{-p} 5444option. Always send diffs from the old file to the new file. If you 5445wish to discuss something in the @command{ld} source, refer to it by 5446context, not by line number. 5447 5448The line numbers in our development sources will not match those in your 5449sources. Your line numbers would convey no useful information to us. 5450@end itemize 5451 5452Here are some things that are not necessary: 5453 5454@itemize @bullet 5455@item 5456A description of the envelope of the bug. 5457 5458Often people who encounter a bug spend a lot of time investigating 5459which changes to the input file will make the bug go away and which 5460changes will not affect it. 5461 5462This is often time consuming and not very useful, because the way we 5463will find the bug is by running a single example under the debugger 5464with breakpoints, not by pure deduction from a series of examples. 5465We recommend that you save your time for something else. 5466 5467Of course, if you can find a simpler example to report @emph{instead} 5468of the original one, that is a convenience for us. Errors in the 5469output will be easier to spot, running under the debugger will take 5470less time, and so on. 5471 5472However, simplification is not vital; if you do not want to do this, 5473report the bug anyway and send us the entire test case you used. 5474 5475@item 5476A patch for the bug. 5477 5478A patch for the bug does help us if it is a good one. But do not omit 5479the necessary information, such as the test case, on the assumption that 5480a patch is all we need. We might see problems with your patch and decide 5481to fix the problem another way, or we might not understand it at all. 5482 5483Sometimes with programs as complicated as the binary utilities it is 5484very hard to construct an example that will make the program follow a 5485certain path through the code. If you do not send us the example, we 5486will not be able to construct one, so we will not be able to verify that 5487the bug is fixed. 5488 5489And if we cannot understand what bug you are trying to fix, or why your 5490patch should be an improvement, we will not install it. A test case will 5491help us to understand. 5492 5493@item 5494A guess about what the bug is or what it depends on. 5495 5496Such guesses are usually wrong. Even we cannot guess right about such 5497things without first using the debugger to find the facts. 5498@end itemize 5499 5500@node GNU Free Documentation License 5501@appendix GNU Free Documentation License 5502 5503@include fdl.texi 5504 5505@node Binutils Index 5506@unnumbered Binutils Index 5507 5508@printindex cp 5509 5510@bye 5511