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