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