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