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