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