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