189857Sobrien\input texinfo @c -*- Texinfo -*- 289857Sobrien@setfilename binutils.info 3218822Sdim@c Copyright 2001, 2002, 2003, 2004, 2005, 2006, 2007 4218822Sdim@c Free Software Foundation, Inc. 589857Sobrien 6218822Sdim@c man begin INCLUDE 7218822Sdim@include bfdver.texi 8218822Sdim@c man end 989857Sobrien 1089857Sobrien@ifinfo 1189857Sobrien@format 1289857SobrienSTART-INFO-DIR-ENTRY 1389857Sobrien* Binutils: (binutils). The GNU binary utilities. 1489857Sobrien* ar: (binutils)ar. Create, modify, and extract from archives 1589857Sobrien* nm: (binutils)nm. List symbols from object files 1689857Sobrien* objcopy: (binutils)objcopy. Copy and translate object files 1789857Sobrien* objdump: (binutils)objdump. Display information from object files 1889857Sobrien* ranlib: (binutils)ranlib. Generate index to archive contents 1989857Sobrien* readelf: (binutils)readelf. Display the contents of ELF format files. 2089857Sobrien* size: (binutils)size. List section sizes and total size 2189857Sobrien* strings: (binutils)strings. List printable strings from files 2289857Sobrien* strip: (binutils)strip. Discard symbols 2389857Sobrien* c++filt: (binutils)c++filt. Filter to demangle encoded C++ symbols 2489857Sobrien* cxxfilt: (binutils)c++filt. MS-DOS name for c++filt 2589857Sobrien* addr2line: (binutils)addr2line. Convert addresses to file and line 2689857Sobrien* nlmconv: (binutils)nlmconv. Converts object code into an NLM 2789857Sobrien* windres: (binutils)windres. Manipulate Windows resources 28218822Sdim* windmc: (binutils)windmc. Generator for Windows message resources 2989857Sobrien* dlltool: (binutils)dlltool. Create files needed to build and use DLLs 3089857SobrienEND-INFO-DIR-ENTRY 3189857Sobrien@end format 3289857Sobrien@end ifinfo 3389857Sobrien 34218822Sdim@copying 3589857Sobrien@c man begin COPYRIGHT 36218822SdimCopyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 37218822Sdim2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 3889857Sobrien 3989857SobrienPermission is granted to copy, distribute and/or modify this document 4089857Sobrienunder the terms of the GNU Free Documentation License, Version 1.1 4189857Sobrienor any later version published by the Free Software Foundation; 4289857Sobrienwith no Invariant Sections, with no Front-Cover Texts, and with no 4389857SobrienBack-Cover Texts. A copy of the license is included in the 44130561Sobriensection entitled ``GNU Free Documentation License''. 4589857Sobrien 4689857Sobrien@c man end 47218822Sdim@end copying 4889857Sobrien 4989857Sobrien@synindex ky cp 5089857Sobrien@c 5189857Sobrien@c This file documents the GNU binary utilities "ar", "ld", "objcopy", 5289857Sobrien@c "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib". 5389857Sobrien@c 54218822Sdim@c Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 55218822Sdim@c 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 56218822Sdim@c 5789857Sobrien@c This text may be freely distributed under the terms of the GNU 5889857Sobrien@c Free Documentation License. 5989857Sobrien@c 6089857Sobrien 6189857Sobrien@setchapternewpage odd 6289857Sobrien@settitle @sc{gnu} Binary Utilities 6389857Sobrien@titlepage 6489857Sobrien@finalout 6589857Sobrien@title The @sc{gnu} Binary Utilities 66218822Sdim@ifset VERSION_PACKAGE 67218822Sdim@subtitle @value{VERSION_PACKAGE} 68218822Sdim@end ifset 6989857Sobrien@subtitle Version @value{VERSION} 7089857Sobrien@sp 1 71218822Sdim@subtitle @value{UPDATED} 7289857Sobrien@author Roland H. Pesch 7389857Sobrien@author Jeffrey M. Osier 7489857Sobrien@author Cygnus Support 7589857Sobrien@page 7689857Sobrien 7789857Sobrien@tex 7889857Sobrien{\parskip=0pt \hfill Cygnus Support\par \hfill 7989857Sobrien\TeX{}info \texinfoversion\par } 8089857Sobrien@end tex 8189857Sobrien 8289857Sobrien@vskip 0pt plus 1filll 83218822SdimCopyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 84218822Sdim2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc. 8589857Sobrien 8689857Sobrien Permission is granted to copy, distribute and/or modify this document 8789857Sobrien under the terms of the GNU Free Documentation License, Version 1.1 8889857Sobrien or any later version published by the Free Software Foundation; 8989857Sobrien with no Invariant Sections, with no Front-Cover Texts, and with no 9089857Sobrien Back-Cover Texts. A copy of the license is included in the 91130561Sobrien section entitled ``GNU Free Documentation License''. 9289857Sobrien 9389857Sobrien@end titlepage 94218822Sdim@contents 9589857Sobrien 9689857Sobrien@node Top 9789857Sobrien@top Introduction 9889857Sobrien 9989857Sobrien@cindex version 100130561SobrienThis brief manual contains documentation for the @sc{gnu} binary 101218822Sdimutilities 102218822Sdim@ifset VERSION_PACKAGE 103218822Sdim@value{VERSION_PACKAGE} 104218822Sdim@end ifset 105218822Sdimversion @value{VERSION}: 10689857Sobrien 10789857Sobrien@iftex 10889857Sobrien@table @code 10989857Sobrien@item ar 11089857SobrienCreate, modify, and extract from archives 11189857Sobrien 11289857Sobrien@item nm 11389857SobrienList symbols from object files 11489857Sobrien 11589857Sobrien@item objcopy 11689857SobrienCopy and translate object files 11789857Sobrien 11889857Sobrien@item objdump 11989857SobrienDisplay information from object files 12089857Sobrien 12189857Sobrien@item ranlib 12289857SobrienGenerate index to archive contents 12389857Sobrien 12489857Sobrien@item readelf 12589857SobrienDisplay the contents of ELF format files. 12689857Sobrien 12789857Sobrien@item size 12889857SobrienList file section sizes and total size 12989857Sobrien 13089857Sobrien@item strings 13189857SobrienList printable strings from files 13289857Sobrien 13389857Sobrien@item strip 13489857SobrienDiscard symbols 13589857Sobrien 13689857Sobrien@item c++filt 13789857SobrienDemangle encoded C++ symbols (on MS-DOS, this program is named 13889857Sobrien@code{cxxfilt}) 13989857Sobrien 14089857Sobrien@item addr2line 14189857SobrienConvert addresses into file names and line numbers 14289857Sobrien 14389857Sobrien@item nlmconv 14489857SobrienConvert object code into a Netware Loadable Module 14589857Sobrien 14689857Sobrien@item windres 14789857SobrienManipulate Windows resources 14889857Sobrien 149218822Sdim@item windmc 150218822SdimGenertor for Windows message resources 151218822Sdim 15289857Sobrien@item dlltool 15389857SobrienCreate the files needed to build and use Dynamic Link Libraries 15489857Sobrien@end table 15589857Sobrien@end iftex 15689857Sobrien 15789857SobrienThis document is distributed under the terms of the GNU Free 15889857SobrienDocumentation License. A copy of the license is included in the 15989857Sobriensection entitled "GNU Free Documentation License". 16089857Sobrien 16189857Sobrien@menu 16289857Sobrien* ar:: Create, modify, and extract from archives 16389857Sobrien* nm:: List symbols from object files 16489857Sobrien* objcopy:: Copy and translate object files 16589857Sobrien* objdump:: Display information from object files 16689857Sobrien* ranlib:: Generate index to archive contents 16789857Sobrien* readelf:: Display the contents of ELF format files. 16889857Sobrien* size:: List section sizes and total size 16989857Sobrien* strings:: List printable strings from files 17089857Sobrien* strip:: Discard symbols 17189857Sobrien* c++filt:: Filter to demangle encoded C++ symbols 17289857Sobrien* cxxfilt: c++filt. MS-DOS name for c++filt 17389857Sobrien* addr2line:: Convert addresses to file and line 17489857Sobrien* nlmconv:: Converts object code into an NLM 17589857Sobrien* windres:: Manipulate Windows resources 176218822Sdim* windmc:: Generator for Windows message resources 17789857Sobrien* dlltool:: Create files needed to build and use DLLs 178218822Sdim* Common Options:: Command-line options for all utilities 17989857Sobrien* Selecting The Target System:: How these utilities determine the target. 18089857Sobrien* Reporting Bugs:: Reporting Bugs 18189857Sobrien* GNU Free Documentation License:: GNU Free Documentation License 182218822Sdim* Binutils Index:: Binutils Index 18389857Sobrien@end menu 18489857Sobrien 18589857Sobrien@node ar 18689857Sobrien@chapter ar 18789857Sobrien 18889857Sobrien@kindex ar 18989857Sobrien@cindex archives 19089857Sobrien@cindex collections of files 19189857Sobrien 19289857Sobrien@c man title ar create, modify, and extract from archives 19389857Sobrien 19489857Sobrien@smallexample 19589857Sobrienar [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}] 19689857Sobrienar -M [ <mri-script ] 19789857Sobrien@end smallexample 19889857Sobrien 19989857Sobrien@c man begin DESCRIPTION ar 20089857Sobrien 20189857SobrienThe @sc{gnu} @command{ar} program creates, modifies, and extracts from 20289857Sobrienarchives. An @dfn{archive} is a single file holding a collection of 20389857Sobrienother files in a structure that makes it possible to retrieve 20489857Sobrienthe original individual files (called @dfn{members} of the archive). 20589857Sobrien 20689857SobrienThe original files' contents, mode (permissions), timestamp, owner, and 20789857Sobriengroup are preserved in the archive, and can be restored on 208218822Sdimextraction. 20989857Sobrien 21089857Sobrien@cindex name length 21189857Sobrien@sc{gnu} @command{ar} can maintain archives whose members have names of any 21289857Sobrienlength; however, depending on how @command{ar} is configured on your 21389857Sobriensystem, a limit on member-name length may be imposed for compatibility 21489857Sobrienwith archive formats maintained with other tools. If it exists, the 21589857Sobrienlimit is often 15 characters (typical of formats related to a.out) or 16 21689857Sobriencharacters (typical of formats related to coff). 21789857Sobrien 21889857Sobrien@cindex libraries 21989857Sobrien@command{ar} is considered a binary utility because archives of this sort 22089857Sobrienare most often used as @dfn{libraries} holding commonly needed 22189857Sobriensubroutines. 22289857Sobrien 22389857Sobrien@cindex symbol index 22489857Sobrien@command{ar} creates an index to the symbols defined in relocatable 22589857Sobrienobject modules in the archive when you specify the modifier @samp{s}. 22689857SobrienOnce created, this index is updated in the archive whenever @command{ar} 22789857Sobrienmakes a change to its contents (save for the @samp{q} update operation). 22889857SobrienAn archive with such an index speeds up linking to the library, and 22989857Sobrienallows routines in the library to call each other without regard to 23089857Sobrientheir placement in the archive. 23189857Sobrien 23289857SobrienYou may use @samp{nm -s} or @samp{nm --print-armap} to list this index 23389857Sobrientable. If an archive lacks the table, another form of @command{ar} called 23489857Sobrien@command{ranlib} can be used to add just the table. 23589857Sobrien 23689857Sobrien@cindex compatibility, @command{ar} 23789857Sobrien@cindex @command{ar} compatibility 23889857Sobrien@sc{gnu} @command{ar} is designed to be compatible with two different 23989857Sobrienfacilities. You can control its activity using command-line options, 24089857Sobrienlike the different varieties of @command{ar} on Unix systems; or, if you 24189857Sobrienspecify the single command-line option @option{-M}, you can control it 24289857Sobrienwith a script supplied via standard input, like the MRI ``librarian'' 24389857Sobrienprogram. 24489857Sobrien 24589857Sobrien@c man end 24689857Sobrien 24789857Sobrien@menu 24889857Sobrien* ar cmdline:: Controlling @command{ar} on the command line 24989857Sobrien* ar scripts:: Controlling @command{ar} with a script 25089857Sobrien@end menu 25189857Sobrien 25289857Sobrien@page 25389857Sobrien@node ar cmdline 254130561Sobrien@section Controlling @command{ar} on the Command Line 25589857Sobrien 25689857Sobrien@smallexample 25789857Sobrien@c man begin SYNOPSIS ar 25889857Sobrienar [@option{-X32_64}] [@option{-}]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}] 25989857Sobrien@c man end 26089857Sobrien@end smallexample 26189857Sobrien 26289857Sobrien@cindex Unix compatibility, @command{ar} 26389857SobrienWhen you use @command{ar} in the Unix style, @command{ar} insists on at least two 26489857Sobrienarguments to execute: one keyletter specifying the @emph{operation} 26589857Sobrien(optionally accompanied by other keyletters specifying 26689857Sobrien@emph{modifiers}), and the archive name to act on. 26789857Sobrien 26889857SobrienMost operations can also accept further @var{member} arguments, 26989857Sobrienspecifying particular files to operate on. 27089857Sobrien 27189857Sobrien@c man begin OPTIONS ar 27289857Sobrien 27389857Sobrien@sc{gnu} @command{ar} allows you to mix the operation code @var{p} and modifier 27489857Sobrienflags @var{mod} in any order, within the first command-line argument. 27589857Sobrien 27689857SobrienIf you wish, you may begin the first command-line argument with a 27789857Sobriendash. 27889857Sobrien 27989857Sobrien@cindex operations on archive 28089857SobrienThe @var{p} keyletter specifies what operation to execute; it may be 28189857Sobrienany of the following, but you must specify only one of them: 28289857Sobrien 28389857Sobrien@table @samp 28489857Sobrien@item d 28589857Sobrien@cindex deleting from archive 28689857Sobrien@emph{Delete} modules from the archive. Specify the names of modules to 28789857Sobrienbe deleted as @var{member}@dots{}; the archive is untouched if you 28889857Sobrienspecify no files to delete. 28989857Sobrien 29089857SobrienIf you specify the @samp{v} modifier, @command{ar} lists each module 29189857Sobrienas it is deleted. 29289857Sobrien 29389857Sobrien@item m 29489857Sobrien@cindex moving in archive 29589857SobrienUse this operation to @emph{move} members in an archive. 29689857Sobrien 29789857SobrienThe ordering of members in an archive can make a difference in how 29889857Sobrienprograms are linked using the library, if a symbol is defined in more 299218822Sdimthan one member. 30089857Sobrien 30189857SobrienIf no modifiers are used with @code{m}, any members you name in the 30289857Sobrien@var{member} arguments are moved to the @emph{end} of the archive; 30389857Sobrienyou can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a 30489857Sobrienspecified place instead. 30589857Sobrien 30689857Sobrien@item p 30789857Sobrien@cindex printing from archive 30889857Sobrien@emph{Print} the specified members of the archive, to the standard 30989857Sobrienoutput file. If the @samp{v} modifier is specified, show the member 31089857Sobrienname before copying its contents to standard output. 31189857Sobrien 31289857SobrienIf you specify no @var{member} arguments, all the files in the archive are 31389857Sobrienprinted. 31489857Sobrien 31589857Sobrien@item q 31689857Sobrien@cindex quick append to archive 31789857Sobrien@emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of 31889857Sobrien@var{archive}, without checking for replacement. 31989857Sobrien 32089857SobrienThe modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this 32189857Sobrienoperation; new members are always placed at the end of the archive. 32289857Sobrien 32389857SobrienThe modifier @samp{v} makes @command{ar} list each file as it is appended. 32489857Sobrien 32589857SobrienSince the point of this operation is speed, the archive's symbol table 32689857Sobrienindex is not updated, even if it already existed; you can use @samp{ar s} or 32789857Sobrien@command{ranlib} explicitly to update the symbol table index. 32889857Sobrien 32989857SobrienHowever, too many different systems assume quick append rebuilds the 330130561Sobrienindex, so @sc{gnu} @command{ar} implements @samp{q} as a synonym for @samp{r}. 33189857Sobrien 33289857Sobrien@item r 33389857Sobrien@cindex replacement in archive 33489857SobrienInsert the files @var{member}@dots{} into @var{archive} (with 33589857Sobrien@emph{replacement}). This operation differs from @samp{q} in that any 33689857Sobrienpreviously existing members are deleted if their names match those being 33789857Sobrienadded. 33889857Sobrien 33989857SobrienIf one of the files named in @var{member}@dots{} does not exist, @command{ar} 34089857Sobriendisplays an error message, and leaves undisturbed any existing members 34189857Sobrienof the archive matching that name. 34289857Sobrien 34389857SobrienBy default, new members are added at the end of the file; but you may 34489857Sobrienuse one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request 34589857Sobrienplacement relative to some existing member. 34689857Sobrien 34789857SobrienThe modifier @samp{v} used with this operation elicits a line of 34889857Sobrienoutput for each file inserted, along with one of the letters @samp{a} or 34989857Sobrien@samp{r} to indicate whether the file was appended (no old member 35089857Sobriendeleted) or replaced. 35189857Sobrien 35289857Sobrien@item t 35389857Sobrien@cindex contents of archive 35489857SobrienDisplay a @emph{table} listing the contents of @var{archive}, or those 35589857Sobrienof the files listed in @var{member}@dots{} that are present in the 35689857Sobrienarchive. Normally only the member name is shown; if you also want to 35789857Sobriensee the modes (permissions), timestamp, owner, group, and size, you can 35889857Sobrienrequest that by also specifying the @samp{v} modifier. 35989857Sobrien 36089857SobrienIf you do not specify a @var{member}, all files in the archive 36189857Sobrienare listed. 36289857Sobrien 36389857Sobrien@cindex repeated names in archive 36489857Sobrien@cindex name duplication in archive 36589857SobrienIf there is more than one file with the same name (say, @samp{fie}) in 36689857Sobrienan archive (say @samp{b.a}), @samp{ar t b.a fie} lists only the 36789857Sobrienfirst instance; to see them all, you must ask for a complete 36889857Sobrienlisting---in our example, @samp{ar t b.a}. 36989857Sobrien@c WRS only; per Gumby, this is implementation-dependent, and in a more 37089857Sobrien@c recent case in fact works the other way. 37189857Sobrien 37289857Sobrien@item x 37389857Sobrien@cindex extract from archive 37489857Sobrien@emph{Extract} members (named @var{member}) from the archive. You can 37589857Sobrienuse the @samp{v} modifier with this operation, to request that 37689857Sobrien@command{ar} list each name as it extracts it. 37789857Sobrien 37889857SobrienIf you do not specify a @var{member}, all files in the archive 37989857Sobrienare extracted. 38089857Sobrien 38189857Sobrien@end table 38289857Sobrien 38389857SobrienA number of modifiers (@var{mod}) may immediately follow the @var{p} 38489857Sobrienkeyletter, to specify variations on an operation's behavior: 38589857Sobrien 38689857Sobrien@table @samp 38789857Sobrien@item a 38889857Sobrien@cindex relative placement in archive 38989857SobrienAdd new files @emph{after} an existing member of the 39089857Sobrienarchive. If you use the modifier @samp{a}, the name of an existing archive 39189857Sobrienmember must be present as the @var{relpos} argument, before the 39289857Sobrien@var{archive} specification. 39389857Sobrien 39489857Sobrien@item b 39589857SobrienAdd new files @emph{before} an existing member of the 39689857Sobrienarchive. If you use the modifier @samp{b}, the name of an existing archive 39789857Sobrienmember must be present as the @var{relpos} argument, before the 39889857Sobrien@var{archive} specification. (same as @samp{i}). 39989857Sobrien 40089857Sobrien@item c 40189857Sobrien@cindex creating archives 40289857Sobrien@emph{Create} the archive. The specified @var{archive} is always 40389857Sobriencreated if it did not exist, when you request an update. But a warning is 40489857Sobrienissued unless you specify in advance that you expect to create it, by 40589857Sobrienusing this modifier. 40689857Sobrien 40789857Sobrien@item f 40889857SobrienTruncate names in the archive. @sc{gnu} @command{ar} will normally permit file 40989857Sobriennames of any length. This will cause it to create archives which are 41089857Sobriennot compatible with the native @command{ar} program on some systems. If 41189857Sobrienthis is a concern, the @samp{f} modifier may be used to truncate file 41289857Sobriennames when putting them in the archive. 41389857Sobrien 41489857Sobrien@item i 41589857SobrienInsert new files @emph{before} an existing member of the 41689857Sobrienarchive. If you use the modifier @samp{i}, the name of an existing archive 41789857Sobrienmember must be present as the @var{relpos} argument, before the 41889857Sobrien@var{archive} specification. (same as @samp{b}). 41989857Sobrien 42089857Sobrien@item l 42189857SobrienThis modifier is accepted but not used. 42289857Sobrien@c whaffor ar l modifier??? presumably compat; with 423218822Sdim@c what???---doc@@cygnus.com, 25jan91 42489857Sobrien 42589857Sobrien@item N 42689857SobrienUses the @var{count} parameter. This is used if there are multiple 42789857Sobrienentries in the archive with the same name. Extract or delete instance 42889857Sobrien@var{count} of the given name from the archive. 42989857Sobrien 43089857Sobrien@item o 43189857Sobrien@cindex dates in archive 43289857SobrienPreserve the @emph{original} dates of members when extracting them. If 43389857Sobrienyou do not specify this modifier, files extracted from the archive 43489857Sobrienare stamped with the time of extraction. 43589857Sobrien 43689857Sobrien@item P 43789857SobrienUse the full path name when matching names in the archive. @sc{gnu} 43889857Sobrien@command{ar} can not create an archive with a full path name (such archives 43989857Sobrienare not POSIX complaint), but other archive creators can. This option 44089857Sobrienwill cause @sc{gnu} @command{ar} to match file names using a complete path 44189857Sobrienname, which can be convenient when extracting a single file from an 44289857Sobrienarchive created by another tool. 44389857Sobrien 44489857Sobrien@item s 44589857Sobrien@cindex writing archive index 44689857SobrienWrite an object-file index into the archive, or update an existing one, 44789857Sobrieneven if no other change is made to the archive. You may use this modifier 44889857Sobrienflag either with any operation, or alone. Running @samp{ar s} on an 44989857Sobrienarchive is equivalent to running @samp{ranlib} on it. 45089857Sobrien 45189857Sobrien@item S 45289857Sobrien@cindex not writing archive index 45389857SobrienDo not generate an archive symbol table. This can speed up building a 45489857Sobrienlarge library in several steps. The resulting archive can not be used 45589857Sobrienwith the linker. In order to build a symbol table, you must omit the 45689857Sobrien@samp{S} modifier on the last execution of @samp{ar}, or you must run 45789857Sobrien@samp{ranlib} on the archive. 45889857Sobrien 45989857Sobrien@item u 46089857Sobrien@cindex updating an archive 46189857SobrienNormally, @samp{ar r}@dots{} inserts all files 46289857Sobrienlisted into the archive. If you would like to insert @emph{only} those 46389857Sobrienof the files you list that are newer than existing members of the same 46489857Sobriennames, use this modifier. The @samp{u} modifier is allowed only for the 46589857Sobrienoperation @samp{r} (replace). In particular, the combination @samp{qu} is 46689857Sobriennot allowed, since checking the timestamps would lose any speed 46789857Sobrienadvantage from the operation @samp{q}. 46889857Sobrien 46989857Sobrien@item v 47089857SobrienThis modifier requests the @emph{verbose} version of an operation. Many 47189857Sobrienoperations display additional information, such as filenames processed, 47289857Sobrienwhen the modifier @samp{v} is appended. 47389857Sobrien 47489857Sobrien@item V 47589857SobrienThis modifier shows the version number of @command{ar}. 47689857Sobrien@end table 47789857Sobrien 47889857Sobrien@command{ar} ignores an initial option spelt @samp{-X32_64}, for 47989857Sobriencompatibility with AIX. The behaviour produced by this option is the 480130561Sobriendefault for @sc{gnu} @command{ar}. @command{ar} does not support any of the other 48189857Sobrien@samp{-X} options; in particular, it does not support @option{-X32} 48289857Sobrienwhich is the default for AIX @command{ar}. 48389857Sobrien 48489857Sobrien@c man end 48589857Sobrien 48689857Sobrien@ignore 48789857Sobrien@c man begin SEEALSO ar 48889857Sobriennm(1), ranlib(1), and the Info entries for @file{binutils}. 48989857Sobrien@c man end 49089857Sobrien@end ignore 49189857Sobrien 49289857Sobrien@node ar scripts 493130561Sobrien@section Controlling @command{ar} with a Script 49489857Sobrien 49589857Sobrien@smallexample 49689857Sobrienar -M [ <@var{script} ] 49789857Sobrien@end smallexample 49889857Sobrien 49989857Sobrien@cindex MRI compatibility, @command{ar} 50089857Sobrien@cindex scripts, @command{ar} 50189857SobrienIf you use the single command-line option @samp{-M} with @command{ar}, you 50289857Sobriencan control its operation with a rudimentary command language. This 50389857Sobrienform of @command{ar} operates interactively if standard input is coming 50489857Sobriendirectly from a terminal. During interactive use, @command{ar} prompts for 50589857Sobrieninput (the prompt is @samp{AR >}), and continues executing even after 50689857Sobrienerrors. If you redirect standard input to a script file, no prompts are 50789857Sobrienissued, and @command{ar} abandons execution (with a nonzero exit code) 50889857Sobrienon any error. 50989857Sobrien 51089857SobrienThe @command{ar} command language is @emph{not} designed to be equivalent 51189857Sobriento the command-line options; in fact, it provides somewhat less control 51289857Sobrienover archives. The only purpose of the command language is to ease the 51389857Sobrientransition to @sc{gnu} @command{ar} for developers who already have scripts 51489857Sobrienwritten for the MRI ``librarian'' program. 51589857Sobrien 51689857SobrienThe syntax for the @command{ar} command language is straightforward: 51789857Sobrien@itemize @bullet 51889857Sobrien@item 51989857Sobriencommands are recognized in upper or lower case; for example, @code{LIST} 52089857Sobrienis the same as @code{list}. In the following descriptions, commands are 52189857Sobrienshown in upper case for clarity. 52289857Sobrien 52389857Sobrien@item 52489857Sobriena single command may appear on each line; it is the first word on the 52589857Sobrienline. 52689857Sobrien 52789857Sobrien@item 52889857Sobrienempty lines are allowed, and have no effect. 52989857Sobrien 53089857Sobrien@item 53189857Sobriencomments are allowed; text after either of the characters @samp{*} 53289857Sobrienor @samp{;} is ignored. 53389857Sobrien 53489857Sobrien@item 53589857SobrienWhenever you use a list of names as part of the argument to an @command{ar} 53689857Sobriencommand, you can separate the individual names with either commas or 53789857Sobrienblanks. Commas are shown in the explanations below, for clarity. 53889857Sobrien 53989857Sobrien@item 54089857Sobrien@samp{+} is used as a line continuation character; if @samp{+} appears 54189857Sobrienat the end of a line, the text on the following line is considered part 54289857Sobrienof the current command. 54389857Sobrien@end itemize 54489857Sobrien 54589857SobrienHere are the commands you can use in @command{ar} scripts, or when using 54689857Sobrien@command{ar} interactively. Three of them have special significance: 54789857Sobrien 54889857Sobrien@code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is 54989857Sobriena temporary file required for most of the other commands. 55089857Sobrien 55189857Sobrien@code{SAVE} commits the changes so far specified by the script. Prior 55289857Sobriento @code{SAVE}, commands affect only the temporary copy of the current 55389857Sobrienarchive. 55489857Sobrien 55589857Sobrien@table @code 556218822Sdim@item ADDLIB @var{archive} 55789857Sobrien@itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module}) 55889857SobrienAdd all the contents of @var{archive} (or, if specified, each named 55989857Sobrien@var{module} from @var{archive}) to the current archive. 56089857Sobrien 56189857SobrienRequires prior use of @code{OPEN} or @code{CREATE}. 56289857Sobrien 56389857Sobrien@item ADDMOD @var{member}, @var{member}, @dots{} @var{member} 56489857Sobrien@c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}" 56589857Sobrien@c else like "ar q..." 56689857SobrienAdd each named @var{member} as a module in the current archive. 56789857Sobrien 56889857SobrienRequires prior use of @code{OPEN} or @code{CREATE}. 56989857Sobrien 57089857Sobrien@item CLEAR 57189857SobrienDiscard the contents of the current archive, canceling the effect of 57289857Sobrienany operations since the last @code{SAVE}. May be executed (with no 57389857Sobrieneffect) even if no current archive is specified. 57489857Sobrien 57589857Sobrien@item CREATE @var{archive} 57689857SobrienCreates an archive, and makes it the current archive (required for many 57789857Sobrienother commands). The new archive is created with a temporary name; it 57889857Sobrienis not actually saved as @var{archive} until you use @code{SAVE}. 57989857SobrienYou can overwrite existing archives; similarly, the contents of any 58089857Sobrienexisting file named @var{archive} will not be destroyed until @code{SAVE}. 58189857Sobrien 58289857Sobrien@item DELETE @var{module}, @var{module}, @dots{} @var{module} 58389857SobrienDelete each listed @var{module} from the current archive; equivalent to 58489857Sobrien@samp{ar -d @var{archive} @var{module} @dots{} @var{module}}. 58589857Sobrien 58689857SobrienRequires prior use of @code{OPEN} or @code{CREATE}. 58789857Sobrien 58889857Sobrien@item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) 58989857Sobrien@itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile} 59089857SobrienList each named @var{module} present in @var{archive}. The separate 59189857Sobriencommand @code{VERBOSE} specifies the form of the output: when verbose 59289857Sobrienoutput is off, output is like that of @samp{ar -t @var{archive} 59389857Sobrien@var{module}@dots{}}. When verbose output is on, the listing is like 59489857Sobrien@samp{ar -tv @var{archive} @var{module}@dots{}}. 59589857Sobrien 59689857SobrienOutput normally goes to the standard output stream; however, if you 59789857Sobrienspecify @var{outputfile} as a final argument, @command{ar} directs the 59889857Sobrienoutput to that file. 59989857Sobrien 60089857Sobrien@item END 60189857SobrienExit from @command{ar}, with a @code{0} exit code to indicate successful 60289857Sobriencompletion. This command does not save the output file; if you have 60389857Sobrienchanged the current archive since the last @code{SAVE} command, those 60489857Sobrienchanges are lost. 60589857Sobrien 60689857Sobrien@item EXTRACT @var{module}, @var{module}, @dots{} @var{module} 60789857SobrienExtract each named @var{module} from the current archive, writing them 60889857Sobrieninto the current directory as separate files. Equivalent to @samp{ar -x 60989857Sobrien@var{archive} @var{module}@dots{}}. 61089857Sobrien 61189857SobrienRequires prior use of @code{OPEN} or @code{CREATE}. 61289857Sobrien 61389857Sobrien@ignore 61489857Sobrien@c FIXME Tokens but no commands??? 61589857Sobrien@item FULLDIR 61689857Sobrien 61789857Sobrien@item HELP 61889857Sobrien@end ignore 61989857Sobrien 62089857Sobrien@item LIST 62189857SobrienDisplay full contents of the current archive, in ``verbose'' style 62289857Sobrienregardless of the state of @code{VERBOSE}. The effect is like @samp{ar 62389857Sobrientv @var{archive}}. (This single command is a @sc{gnu} @command{ar} 62489857Sobrienenhancement, rather than present for MRI compatibility.) 62589857Sobrien 62689857SobrienRequires prior use of @code{OPEN} or @code{CREATE}. 62789857Sobrien 62889857Sobrien@item OPEN @var{archive} 62989857SobrienOpens an existing archive for use as the current archive (required for 63089857Sobrienmany other commands). Any changes as the result of subsequent commands 63189857Sobrienwill not actually affect @var{archive} until you next use @code{SAVE}. 63289857Sobrien 63389857Sobrien@item REPLACE @var{module}, @var{module}, @dots{} @var{module} 63489857SobrienIn the current archive, replace each existing @var{module} (named in 63589857Sobrienthe @code{REPLACE} arguments) from files in the current working directory. 63689857SobrienTo execute this command without errors, both the file, and the module in 637218822Sdimthe current archive, must exist. 63889857Sobrien 63989857SobrienRequires prior use of @code{OPEN} or @code{CREATE}. 64089857Sobrien 64189857Sobrien@item VERBOSE 64289857SobrienToggle an internal flag governing the output from @code{DIRECTORY}. 64389857SobrienWhen the flag is on, @code{DIRECTORY} output matches output from 64489857Sobrien@samp{ar -tv }@dots{}. 64589857Sobrien 64689857Sobrien@item SAVE 64789857SobrienCommit your changes to the current archive, and actually save it as a 64889857Sobrienfile with the name specified in the last @code{CREATE} or @code{OPEN} 649218822Sdimcommand. 65089857Sobrien 65189857SobrienRequires prior use of @code{OPEN} or @code{CREATE}. 65289857Sobrien 65389857Sobrien@end table 65489857Sobrien 65589857Sobrien@iftex 65689857Sobrien@node ld 65789857Sobrien@chapter ld 65889857Sobrien@cindex linker 65989857Sobrien@kindex ld 66089857SobrienThe @sc{gnu} linker @command{ld} is now described in a separate manual. 66189857Sobrien@xref{Top,, Overview,, Using LD: the @sc{gnu} linker}. 66289857Sobrien@end iftex 66389857Sobrien 66489857Sobrien@node nm 66589857Sobrien@chapter nm 66689857Sobrien@cindex symbols 66789857Sobrien@kindex nm 66889857Sobrien 66989857Sobrien@c man title nm list symbols from object files 67089857Sobrien 67189857Sobrien@smallexample 67289857Sobrien@c man begin SYNOPSIS nm 67389857Sobriennm [@option{-a}|@option{--debug-syms}] [@option{-g}|@option{--extern-only}] 67489857Sobrien [@option{-B}] [@option{-C}|@option{--demangle}[=@var{style}]] [@option{-D}|@option{--dynamic}] 675104834Sobrien [@option{-S}|@option{--print-size}] [@option{-s}|@option{--print-armap}] 676218822Sdim [@option{-A}|@option{-o}|@option{--print-file-name}][@option{--special-syms}] 67789857Sobrien [@option{-n}|@option{-v}|@option{--numeric-sort}] [@option{-p}|@option{--no-sort}] 67889857Sobrien [@option{-r}|@option{--reverse-sort}] [@option{--size-sort}] [@option{-u}|@option{--undefined-only}] 67989857Sobrien [@option{-t} @var{radix}|@option{--radix=}@var{radix}] [@option{-P}|@option{--portability}] 68089857Sobrien [@option{--target=}@var{bfdname}] [@option{-f}@var{format}|@option{--format=}@var{format}] 68189857Sobrien [@option{--defined-only}] [@option{-l}|@option{--line-numbers}] [@option{--no-demangle}] 68289857Sobrien [@option{-V}|@option{--version}] [@option{-X 32_64}] [@option{--help}] [@var{objfile}@dots{}] 68389857Sobrien@c man end 68489857Sobrien@end smallexample 68589857Sobrien 68689857Sobrien@c man begin DESCRIPTION nm 68789857Sobrien@sc{gnu} @command{nm} lists the symbols from object files @var{objfile}@dots{}. 68889857SobrienIf no object files are listed as arguments, @command{nm} assumes the file 68989857Sobrien@file{a.out}. 69089857Sobrien 69189857SobrienFor each symbol, @command{nm} shows: 69289857Sobrien 69389857Sobrien@itemize @bullet 69489857Sobrien@item 69589857SobrienThe symbol value, in the radix selected by options (see below), or 69689857Sobrienhexadecimal by default. 69789857Sobrien 69889857Sobrien@item 69989857SobrienThe symbol type. At least the following types are used; others are, as 70089857Sobrienwell, depending on the object file format. If lowercase, the symbol is 70189857Sobrienlocal; if uppercase, the symbol is global (external). 70289857Sobrien 70389857Sobrien@c Some more detail on exactly what these symbol types are used for 70489857Sobrien@c would be nice. 70589857Sobrien@table @code 70689857Sobrien@item A 70789857SobrienThe symbol's value is absolute, and will not be changed by further 70889857Sobrienlinking. 70989857Sobrien 71089857Sobrien@item B 71189857SobrienThe symbol is in the uninitialized data section (known as BSS). 71289857Sobrien 71389857Sobrien@item C 71489857SobrienThe symbol is common. Common symbols are uninitialized data. When 71589857Sobrienlinking, multiple common symbols may appear with the same name. If the 71689857Sobriensymbol is defined anywhere, the common symbols are treated as undefined 71789857Sobrienreferences. 71889857Sobrien@ifclear man 71989857SobrienFor more details on common symbols, see the discussion of 72089857Sobrien--warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}. 72189857Sobrien@end ifclear 72289857Sobrien 72389857Sobrien@item D 72489857SobrienThe symbol is in the initialized data section. 72589857Sobrien 72689857Sobrien@item G 72789857SobrienThe symbol is in an initialized data section for small objects. Some 72889857Sobrienobject file formats permit more efficient access to small data objects, 72989857Sobriensuch as a global int variable as opposed to a large global array. 73089857Sobrien 73189857Sobrien@item I 732130561SobrienThe symbol is an indirect reference to another symbol. This is a @sc{gnu} 73389857Sobrienextension to the a.out object file format which is rarely used. 73489857Sobrien 73589857Sobrien@item N 73689857SobrienThe symbol is a debugging symbol. 73789857Sobrien 73889857Sobrien@item R 73989857SobrienThe symbol is in a read only data section. 74089857Sobrien 74189857Sobrien@item S 74289857SobrienThe symbol is in an uninitialized data section for small objects. 74389857Sobrien 74489857Sobrien@item T 74589857SobrienThe symbol is in the text (code) section. 74689857Sobrien 74789857Sobrien@item U 74889857SobrienThe symbol is undefined. 74989857Sobrien 75089857Sobrien@item V 75189857SobrienThe symbol is a weak object. When a weak defined symbol is linked with 75289857Sobriena normal defined symbol, the normal defined symbol is used with no error. 75389857SobrienWhen a weak undefined symbol is linked and the symbol is not defined, 75489857Sobrienthe value of the weak symbol becomes zero with no error. 75589857Sobrien 75689857Sobrien@item W 75789857SobrienThe symbol is a weak symbol that has not been specifically tagged as a 75889857Sobrienweak object symbol. When a weak defined symbol is linked with a normal 75989857Sobriendefined symbol, the normal defined symbol is used with no error. 76089857SobrienWhen a weak undefined symbol is linked and the symbol is not defined, 761218822Sdimthe value of the symbol is determined in a system-specific manner without 762218822Sdimerror. On some systems, uppercase indicates that a default value has been 763218822Sdimspecified. 76489857Sobrien 765218822Sdim 76689857Sobrien@item - 76789857SobrienThe symbol is a stabs symbol in an a.out object file. In this case, the 76889857Sobriennext values printed are the stabs other field, the stabs desc field, and 76989857Sobrienthe stab type. Stabs symbols are used to hold debugging information. 77089857Sobrien@ifclear man 77189857SobrienFor more information, see @ref{Top,Stabs,Stabs Overview,stabs.info, The 77289857Sobrien``stabs'' debug format}. 77389857Sobrien@end ifclear 77489857Sobrien 77589857Sobrien@item ? 77689857SobrienThe symbol type is unknown, or object file format specific. 77789857Sobrien@end table 77889857Sobrien 77989857Sobrien@item 78089857SobrienThe symbol name. 78189857Sobrien@end itemize 78289857Sobrien 78389857Sobrien@c man end 78489857Sobrien 78589857Sobrien@c man begin OPTIONS nm 78689857SobrienThe long and short forms of options, shown here as alternatives, are 78789857Sobrienequivalent. 78889857Sobrien 78989857Sobrien@table @env 79089857Sobrien@item -A 79189857Sobrien@itemx -o 792218822Sdim@itemx --print-file-name 79389857Sobrien@cindex input file name 79489857Sobrien@cindex file name 79589857Sobrien@cindex source file name 79689857SobrienPrecede each symbol by the name of the input file (or archive member) 79789857Sobrienin which it was found, rather than identifying the input file once only, 79889857Sobrienbefore all of its symbols. 79989857Sobrien 80089857Sobrien@item -a 801218822Sdim@itemx --debug-syms 80289857Sobrien@cindex debugging symbols 80389857SobrienDisplay all symbols, even debugger-only symbols; normally these are not 80489857Sobrienlisted. 80589857Sobrien 80689857Sobrien@item -B 80789857Sobrien@cindex @command{nm} format 80889857Sobrien@cindex @command{nm} compatibility 80989857SobrienThe same as @option{--format=bsd} (for compatibility with the MIPS @command{nm}). 81089857Sobrien 81189857Sobrien@item -C 81289857Sobrien@itemx --demangle[=@var{style}] 81389857Sobrien@cindex demangling in nm 81489857SobrienDecode (@dfn{demangle}) low-level symbol names into user-level names. 81589857SobrienBesides removing any initial underscore prepended by the system, this 81689857Sobrienmakes C++ function names readable. Different compilers have different 817218822Sdimmangling styles. The optional demangling style argument can be used to 818218822Sdimchoose an appropriate demangling style for your compiler. @xref{c++filt}, 81989857Sobrienfor more information on demangling. 82089857Sobrien 82189857Sobrien@item --no-demangle 82289857SobrienDo not demangle low-level symbol names. This is the default. 82389857Sobrien 82489857Sobrien@item -D 82589857Sobrien@itemx --dynamic 82689857Sobrien@cindex dynamic symbols 82789857SobrienDisplay the dynamic symbols rather than the normal symbols. This is 82889857Sobrienonly meaningful for dynamic objects, such as certain types of shared 82989857Sobrienlibraries. 83089857Sobrien 83189857Sobrien@item -f @var{format} 83289857Sobrien@itemx --format=@var{format} 83389857Sobrien@cindex @command{nm} format 83489857Sobrien@cindex @command{nm} compatibility 83589857SobrienUse the output format @var{format}, which can be @code{bsd}, 83689857Sobrien@code{sysv}, or @code{posix}. The default is @code{bsd}. 83789857SobrienOnly the first character of @var{format} is significant; it can be 83889857Sobrieneither upper or lower case. 83989857Sobrien 84089857Sobrien@item -g 841218822Sdim@itemx --extern-only 84289857Sobrien@cindex external symbols 84389857SobrienDisplay only external symbols. 84489857Sobrien 84589857Sobrien@item -l 84689857Sobrien@itemx --line-numbers 84789857Sobrien@cindex symbol line numbers 84889857SobrienFor each symbol, use debugging information to try to find a filename and 84989857Sobrienline number. For a defined symbol, look for the line number of the 85089857Sobrienaddress of the symbol. For an undefined symbol, look for the line 85189857Sobriennumber of a relocation entry which refers to the symbol. If line number 85289857Sobrieninformation can be found, print it after the other symbol information. 85389857Sobrien 85489857Sobrien@item -n 85589857Sobrien@itemx -v 856218822Sdim@itemx --numeric-sort 85789857SobrienSort symbols numerically by their addresses, rather than alphabetically 858218822Sdimby their names. 85989857Sobrien 86089857Sobrien@item -p 861218822Sdim@itemx --no-sort 86289857Sobrien@cindex sorting symbols 86389857SobrienDo not bother to sort the symbols in any order; print them in the order 86489857Sobrienencountered. 86589857Sobrien 86689857Sobrien@item -P 86789857Sobrien@itemx --portability 86889857SobrienUse the POSIX.2 standard output format instead of the default format. 86989857SobrienEquivalent to @samp{-f posix}. 87089857Sobrien 871104834Sobrien@item -S 872104834Sobrien@itemx --print-size 873130561SobrienPrint size, not the value, of defined symbols for the @code{bsd} output format. 874104834Sobrien 87589857Sobrien@item -s 87689857Sobrien@itemx --print-armap 87789857Sobrien@cindex symbol index, listing 87889857SobrienWhen listing symbols from archive members, include the index: a mapping 87989857Sobrien(stored in the archive by @command{ar} or @command{ranlib}) of which modules 88089857Sobriencontain definitions for which names. 88189857Sobrien 88289857Sobrien@item -r 883218822Sdim@itemx --reverse-sort 88489857SobrienReverse the order of the sort (whether numeric or alphabetic); let the 88589857Sobrienlast come first. 88689857Sobrien 88789857Sobrien@item --size-sort 88889857SobrienSort symbols by size. The size is computed as the difference between 88989857Sobrienthe value of the symbol and the value of the symbol with the next higher 890218822Sdimvalue. If the @code{bsd} output format is used the size of the symbol 891218822Sdimis printed, rather than the value, and @samp{-S} must be used in order 892130561Sobrienboth size and value to be printed. 89389857Sobrien 894218822Sdim@item --special-syms 895218822SdimDisplay symbols which have a target-specific special meaning. These 896218822Sdimsymbols are usually used by the target for some special processing and 897218822Sdimare not normally helpful when included included in the normal symbol 898218822Sdimlists. For example for ARM targets this option would skip the mapping 899218822Sdimsymbols used to mark transitions between ARM code, THUMB code and 900218822Sdimdata. 901218822Sdim 90289857Sobrien@item -t @var{radix} 90389857Sobrien@itemx --radix=@var{radix} 90489857SobrienUse @var{radix} as the radix for printing the symbol values. It must be 90589857Sobrien@samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal. 90689857Sobrien 90789857Sobrien@item --target=@var{bfdname} 90889857Sobrien@cindex object code format 90989857SobrienSpecify an object code format other than your system's default format. 91089857Sobrien@xref{Target Selection}, for more information. 91189857Sobrien 91289857Sobrien@item -u 913218822Sdim@itemx --undefined-only 91489857Sobrien@cindex external symbols 91589857Sobrien@cindex undefined symbols 91689857SobrienDisplay only undefined symbols (those external to each object file). 91789857Sobrien 91889857Sobrien@item --defined-only 91989857Sobrien@cindex external symbols 92089857Sobrien@cindex undefined symbols 92189857SobrienDisplay only defined symbols for each object file. 92289857Sobrien 92389857Sobrien@item -V 92489857Sobrien@itemx --version 92589857SobrienShow the version number of @command{nm} and exit. 92689857Sobrien 92789857Sobrien@item -X 92889857SobrienThis option is ignored for compatibility with the AIX version of 92989857Sobrien@command{nm}. It takes one parameter which must be the string 93089857Sobrien@option{32_64}. The default mode of AIX @command{nm} corresponds 93189857Sobriento @option{-X 32}, which is not supported by @sc{gnu} @command{nm}. 93289857Sobrien 93389857Sobrien@item --help 93489857SobrienShow a summary of the options to @command{nm} and exit. 93589857Sobrien@end table 93689857Sobrien 93789857Sobrien@c man end 93889857Sobrien 93989857Sobrien@ignore 94089857Sobrien@c man begin SEEALSO nm 94189857Sobrienar(1), objdump(1), ranlib(1), and the Info entries for @file{binutils}. 94289857Sobrien@c man end 94389857Sobrien@end ignore 94489857Sobrien 94589857Sobrien@node objcopy 94689857Sobrien@chapter objcopy 94789857Sobrien 94889857Sobrien@c man title objcopy copy and translate object files 94989857Sobrien 95089857Sobrien@smallexample 95189857Sobrien@c man begin SYNOPSIS objcopy 95289857Sobrienobjcopy [@option{-F} @var{bfdname}|@option{--target=}@var{bfdname}] 95389857Sobrien [@option{-I} @var{bfdname}|@option{--input-target=}@var{bfdname}] 95489857Sobrien [@option{-O} @var{bfdname}|@option{--output-target=}@var{bfdname}] 95589857Sobrien [@option{-B} @var{bfdarch}|@option{--binary-architecture=}@var{bfdarch}] 956130561Sobrien [@option{-S}|@option{--strip-all}] 957130561Sobrien [@option{-g}|@option{--strip-debug}] 95889857Sobrien [@option{-K} @var{symbolname}|@option{--keep-symbol=}@var{symbolname}] 95989857Sobrien [@option{-N} @var{symbolname}|@option{--strip-symbol=}@var{symbolname}] 960218822Sdim [@option{--strip-unneeded-symbol=}@var{symbolname}] 96189857Sobrien [@option{-G} @var{symbolname}|@option{--keep-global-symbol=}@var{symbolname}] 962218822Sdim [@option{--localize-hidden}] 96389857Sobrien [@option{-L} @var{symbolname}|@option{--localize-symbol=}@var{symbolname}] 964218822Sdim [@option{--globalize-symbol=}@var{symbolname}] 96589857Sobrien [@option{-W} @var{symbolname}|@option{--weaken-symbol=}@var{symbolname}] 966130561Sobrien [@option{-w}|@option{--wildcard}] 967130561Sobrien [@option{-x}|@option{--discard-all}] 968130561Sobrien [@option{-X}|@option{--discard-locals}] 96989857Sobrien [@option{-b} @var{byte}|@option{--byte=}@var{byte}] 97089857Sobrien [@option{-i} @var{interleave}|@option{--interleave=}@var{interleave}] 97189857Sobrien [@option{-j} @var{sectionname}|@option{--only-section=}@var{sectionname}] 97289857Sobrien [@option{-R} @var{sectionname}|@option{--remove-section=}@var{sectionname}] 97389857Sobrien [@option{-p}|@option{--preserve-dates}] 97489857Sobrien [@option{--debugging}] 975130561Sobrien [@option{--gap-fill=}@var{val}] 976130561Sobrien [@option{--pad-to=}@var{address}] 977130561Sobrien [@option{--set-start=}@var{val}] 978130561Sobrien [@option{--adjust-start=}@var{incr}] 97989857Sobrien [@option{--change-addresses=}@var{incr}] 98089857Sobrien [@option{--change-section-address} @var{section}@{=,+,-@}@var{val}] 98189857Sobrien [@option{--change-section-lma} @var{section}@{=,+,-@}@var{val}] 98289857Sobrien [@option{--change-section-vma} @var{section}@{=,+,-@}@var{val}] 98389857Sobrien [@option{--change-warnings}] [@option{--no-change-warnings}] 98489857Sobrien [@option{--set-section-flags} @var{section}=@var{flags}] 98589857Sobrien [@option{--add-section} @var{sectionname}=@var{filename}] 98689857Sobrien [@option{--rename-section} @var{oldname}=@var{newname}[,@var{flags}]] 987130561Sobrien [@option{--change-leading-char}] [@option{--remove-leading-char}] 988218822Sdim [@option{--reverse-bytes=}@var{num}] 989130561Sobrien [@option{--srec-len=}@var{ival}] [@option{--srec-forceS3}] 990130561Sobrien [@option{--redefine-sym} @var{old}=@var{new}] 991130561Sobrien [@option{--redefine-syms=}@var{filename}] 99289857Sobrien [@option{--weaken}] 99389857Sobrien [@option{--keep-symbols=}@var{filename}] 99489857Sobrien [@option{--strip-symbols=}@var{filename}] 995218822Sdim [@option{--strip-unneeded-symbols=}@var{filename}] 99689857Sobrien [@option{--keep-global-symbols=}@var{filename}] 99789857Sobrien [@option{--localize-symbols=}@var{filename}] 998218822Sdim [@option{--globalize-symbols=}@var{filename}] 99989857Sobrien [@option{--weaken-symbols=}@var{filename}] 1000130561Sobrien [@option{--alt-machine-code=}@var{index}] 1001130561Sobrien [@option{--prefix-symbols=}@var{string}] 1002130561Sobrien [@option{--prefix-sections=}@var{string}] 1003130561Sobrien [@option{--prefix-alloc-sections=}@var{string}] 1004130561Sobrien [@option{--add-gnu-debuglink=}@var{path-to-file}] 1005218822Sdim [@option{--keep-file-symbols}] 1006130561Sobrien [@option{--only-keep-debug}] 1007218822Sdim [@option{--extract-symbol}] 1008130561Sobrien [@option{--writable-text}] 1009130561Sobrien [@option{--readonly-text}] 1010130561Sobrien [@option{--pure}] 1011130561Sobrien [@option{--impure}] 101289857Sobrien [@option{-v}|@option{--verbose}] 1013218822Sdim [@option{-V}|@option{--version}] 1014130561Sobrien [@option{--help}] [@option{--info}] 101589857Sobrien @var{infile} [@var{outfile}] 101689857Sobrien@c man end 101789857Sobrien@end smallexample 101889857Sobrien 101989857Sobrien@c man begin DESCRIPTION objcopy 102089857SobrienThe @sc{gnu} @command{objcopy} utility copies the contents of an object 102189857Sobrienfile to another. @command{objcopy} uses the @sc{gnu} @sc{bfd} Library to 102289857Sobrienread and write the object files. It can write the destination object 102389857Sobrienfile in a format different from that of the source object file. The 102489857Sobrienexact behavior of @command{objcopy} is controlled by command-line options. 102589857SobrienNote that @command{objcopy} should be able to copy a fully linked file 102689857Sobrienbetween any two formats. However, copying a relocatable object file 102789857Sobrienbetween any two formats may not work as expected. 102889857Sobrien 102989857Sobrien@command{objcopy} creates temporary files to do its translations and 103089857Sobriendeletes them afterward. @command{objcopy} uses @sc{bfd} to do all its 103189857Sobrientranslation work; it has access to all the formats described in @sc{bfd} 103289857Sobrienand thus is able to recognize most formats without being told 103389857Sobrienexplicitly. @xref{BFD,,BFD,ld.info,Using LD}. 103489857Sobrien 103589857Sobrien@command{objcopy} can be used to generate S-records by using an output 103689857Sobrientarget of @samp{srec} (e.g., use @samp{-O srec}). 103789857Sobrien 103889857Sobrien@command{objcopy} can be used to generate a raw binary file by using an 103989857Sobrienoutput target of @samp{binary} (e.g., use @option{-O binary}). When 104089857Sobrien@command{objcopy} generates a raw binary file, it will essentially produce 104189857Sobriena memory dump of the contents of the input object file. All symbols and 104289857Sobrienrelocation information will be discarded. The memory dump will start at 104389857Sobrienthe load address of the lowest section copied into the output file. 104489857Sobrien 104589857SobrienWhen generating an S-record or a raw binary file, it may be helpful to 104689857Sobrienuse @option{-S} to remove sections containing debugging information. In 104789857Sobriensome cases @option{-R} will be useful to remove sections which contain 104889857Sobrieninformation that is not needed by the binary file. 104989857Sobrien 1050130561SobrienNote---@command{objcopy} is not able to change the endianness of its input 1051130561Sobrienfiles. If the input format has an endianness (some formats do not), 105289857Sobrien@command{objcopy} can only copy the inputs into file formats that have the 1053130561Sobriensame endianness or which have no endianness (e.g., @samp{srec}). 1054218822Sdim(However, see the @option{--reverse-bytes} option.) 105589857Sobrien 105689857Sobrien@c man end 105789857Sobrien 105889857Sobrien@c man begin OPTIONS objcopy 105989857Sobrien 106089857Sobrien@table @env 106189857Sobrien@item @var{infile} 106289857Sobrien@itemx @var{outfile} 106389857SobrienThe input and output files, respectively. 106489857SobrienIf you do not specify @var{outfile}, @command{objcopy} creates a 106589857Sobrientemporary file and destructively renames the result with 106689857Sobrienthe name of @var{infile}. 106789857Sobrien 106889857Sobrien@item -I @var{bfdname} 106989857Sobrien@itemx --input-target=@var{bfdname} 107089857SobrienConsider the source file's object format to be @var{bfdname}, rather than 107189857Sobrienattempting to deduce it. @xref{Target Selection}, for more information. 107289857Sobrien 107389857Sobrien@item -O @var{bfdname} 107489857Sobrien@itemx --output-target=@var{bfdname} 107589857SobrienWrite the output file using the object format @var{bfdname}. 107689857Sobrien@xref{Target Selection}, for more information. 107789857Sobrien 107889857Sobrien@item -F @var{bfdname} 107989857Sobrien@itemx --target=@var{bfdname} 108089857SobrienUse @var{bfdname} as the object format for both the input and the output 108189857Sobrienfile; i.e., simply transfer data from source to destination with no 108289857Sobrientranslation. @xref{Target Selection}, for more information. 108389857Sobrien 108489857Sobrien@item -B @var{bfdarch} 108589857Sobrien@itemx --binary-architecture=@var{bfdarch} 108689857SobrienUseful when transforming a raw binary input file into an object file. 108789857SobrienIn this case the output architecture can be set to @var{bfdarch}. This 108889857Sobrienoption will be ignored if the input file has a known @var{bfdarch}. You 108989857Sobriencan access this binary data inside a program by referencing the special 109089857Sobriensymbols that are created by the conversion process. These symbols are 109189857Sobriencalled _binary_@var{objfile}_start, _binary_@var{objfile}_end and 109289857Sobrien_binary_@var{objfile}_size. e.g. you can transform a picture file into 1093218822Sdiman object file and then access it in your code using these symbols. 109489857Sobrien 109589857Sobrien@item -j @var{sectionname} 109689857Sobrien@itemx --only-section=@var{sectionname} 109789857SobrienCopy only the named section from the input file to the output file. 109889857SobrienThis option may be given more than once. Note that using this option 109989857Sobrieninappropriately may make the output file unusable. 110089857Sobrien 110189857Sobrien@item -R @var{sectionname} 110289857Sobrien@itemx --remove-section=@var{sectionname} 110389857SobrienRemove any section named @var{sectionname} from the output file. This 110489857Sobrienoption may be given more than once. Note that using this option 110589857Sobrieninappropriately may make the output file unusable. 110689857Sobrien 110789857Sobrien@item -S 110889857Sobrien@itemx --strip-all 110989857SobrienDo not copy relocation and symbol information from the source file. 111089857Sobrien 111189857Sobrien@item -g 111289857Sobrien@itemx --strip-debug 1113130561SobrienDo not copy debugging symbols or sections from the source file. 111489857Sobrien 111589857Sobrien@item --strip-unneeded 111689857SobrienStrip all symbols that are not needed for relocation processing. 111789857Sobrien 111889857Sobrien@item -K @var{symbolname} 111989857Sobrien@itemx --keep-symbol=@var{symbolname} 1120218822SdimWhen stripping symbols, keep symbol @var{symbolname} even if it would 1121218822Sdimnormally be stripped. This option may be given more than once. 112289857Sobrien 112389857Sobrien@item -N @var{symbolname} 112489857Sobrien@itemx --strip-symbol=@var{symbolname} 112589857SobrienDo not copy symbol @var{symbolname} from the source file. This option 112689857Sobrienmay be given more than once. 112789857Sobrien 1128218822Sdim@item --strip-unneeded-symbol=@var{symbolname} 1129218822SdimDo not copy symbol @var{symbolname} from the source file unless it is needed 1130218822Sdimby a relocation. This option may be given more than once. 1131218822Sdim 113289857Sobrien@item -G @var{symbolname} 113389857Sobrien@itemx --keep-global-symbol=@var{symbolname} 113489857SobrienKeep only symbol @var{symbolname} global. Make all other symbols local 113589857Sobriento the file, so that they are not visible externally. This option may 113689857Sobrienbe given more than once. 113789857Sobrien 1138218822Sdim@item --localize-hidden 1139218822SdimIn an ELF object, mark all symbols that have hidden or internal visibility 1140218822Sdimas local. This option applies on top of symbol-specific localization options 1141218822Sdimsuch as @option{-L}. 1142218822Sdim 114389857Sobrien@item -L @var{symbolname} 114489857Sobrien@itemx --localize-symbol=@var{symbolname} 114589857SobrienMake symbol @var{symbolname} local to the file, so that it is not 114689857Sobrienvisible externally. This option may be given more than once. 114789857Sobrien 114889857Sobrien@item -W @var{symbolname} 114989857Sobrien@itemx --weaken-symbol=@var{symbolname} 115089857SobrienMake symbol @var{symbolname} weak. This option may be given more than once. 115189857Sobrien 1152218822Sdim@item --globalize-symbol=@var{symbolname} 1153218822SdimGive symbol @var{symbolname} global scoping so that it is visible 1154218822Sdimoutside of the file in which it is defined. This option may be given 1155218822Sdimmore than once. 1156218822Sdim 1157130561Sobrien@item -w 1158130561Sobrien@itemx --wildcard 1159130561SobrienPermit regular expressions in @var{symbolname}s used in other command 1160130561Sobrienline options. The question mark (?), asterisk (*), backslash (\) and 1161130561Sobriensquare brackets ([]) operators can be used anywhere in the symbol 1162130561Sobrienname. If the first character of the symbol name is the exclamation 1163130561Sobrienpoint (!) then the sense of the switch is reversed for that symbol. 1164130561SobrienFor example: 1165130561Sobrien 1166130561Sobrien@smallexample 1167130561Sobrien -w -W !foo -W fo* 1168130561Sobrien@end smallexample 1169130561Sobrien 1170130561Sobrienwould cause objcopy to weaken all symbols that start with ``fo'' 1171130561Sobrienexcept for the symbol ``foo''. 1172130561Sobrien 117389857Sobrien@item -x 117489857Sobrien@itemx --discard-all 117589857SobrienDo not copy non-global symbols from the source file. 117689857Sobrien@c FIXME any reason to prefer "non-global" to "local" here? 117789857Sobrien 117889857Sobrien@item -X 117989857Sobrien@itemx --discard-locals 118089857SobrienDo not copy compiler-generated local symbols. 118189857Sobrien(These usually start with @samp{L} or @samp{.}.) 118289857Sobrien 118389857Sobrien@item -b @var{byte} 118489857Sobrien@itemx --byte=@var{byte} 118589857SobrienKeep only every @var{byte}th byte of the input file (header data is not 118689857Sobrienaffected). @var{byte} can be in the range from 0 to @var{interleave}-1, 118789857Sobrienwhere @var{interleave} is given by the @option{-i} or @option{--interleave} 118889857Sobrienoption, or the default of 4. This option is useful for creating files 118989857Sobriento program @sc{rom}. It is typically used with an @code{srec} output 119089857Sobrientarget. 119189857Sobrien 119289857Sobrien@item -i @var{interleave} 119389857Sobrien@itemx --interleave=@var{interleave} 119489857SobrienOnly copy one out of every @var{interleave} bytes. Select which byte to 119589857Sobriencopy with the @option{-b} or @option{--byte} option. The default is 4. 119689857Sobrien@command{objcopy} ignores this option if you do not specify either @option{-b} or 119789857Sobrien@option{--byte}. 119889857Sobrien 119989857Sobrien@item -p 120089857Sobrien@itemx --preserve-dates 120189857SobrienSet the access and modification dates of the output file to be the same 120289857Sobrienas those of the input file. 120389857Sobrien 120489857Sobrien@item --debugging 120589857SobrienConvert debugging information, if possible. This is not the default 120689857Sobrienbecause only certain debugging formats are supported, and the 120789857Sobrienconversion process can be time consuming. 120889857Sobrien 120989857Sobrien@item --gap-fill @var{val} 121089857SobrienFill gaps between sections with @var{val}. This operation applies to 121189857Sobrienthe @emph{load address} (LMA) of the sections. It is done by increasing 121289857Sobrienthe size of the section with the lower address, and filling in the extra 121389857Sobrienspace created with @var{val}. 121489857Sobrien 121589857Sobrien@item --pad-to @var{address} 121689857SobrienPad the output file up to the load address @var{address}. This is 121789857Sobriendone by increasing the size of the last section. The extra space is 121889857Sobrienfilled in with the value specified by @option{--gap-fill} (default zero). 121989857Sobrien 122089857Sobrien@item --set-start @var{val} 122189857SobrienSet the start address of the new file to @var{val}. Not all object file 122289857Sobrienformats support setting the start address. 122389857Sobrien 122489857Sobrien@item --change-start @var{incr} 122589857Sobrien@itemx --adjust-start @var{incr} 122689857Sobrien@cindex changing start address 122789857SobrienChange the start address by adding @var{incr}. Not all object file 122889857Sobrienformats support setting the start address. 122989857Sobrien 123089857Sobrien@item --change-addresses @var{incr} 123189857Sobrien@itemx --adjust-vma @var{incr} 123289857Sobrien@cindex changing object addresses 123389857SobrienChange the VMA and LMA addresses of all sections, as well as the start 123489857Sobrienaddress, by adding @var{incr}. Some object file formats do not permit 123589857Sobriensection addresses to be changed arbitrarily. Note that this does not 123689857Sobrienrelocate the sections; if the program expects sections to be loaded at a 123789857Sobriencertain address, and this option is used to change the sections such 1238218822Sdimthat they are loaded at a different address, the program may fail. 123989857Sobrien 124089857Sobrien@item --change-section-address @var{section}@{=,+,-@}@var{val} 124189857Sobrien@itemx --adjust-section-vma @var{section}@{=,+,-@}@var{val} 124289857Sobrien@cindex changing section address 124389857SobrienSet or change both the VMA address and the LMA address of the named 124489857Sobrien@var{section}. If @samp{=} is used, the section address is set to 124589857Sobrien@var{val}. Otherwise, @var{val} is added to or subtracted from the 124689857Sobriensection address. See the comments under @option{--change-addresses}, 124789857Sobrienabove. If @var{section} does not exist in the input file, a warning will 124889857Sobrienbe issued, unless @option{--no-change-warnings} is used. 124989857Sobrien 125089857Sobrien@item --change-section-lma @var{section}@{=,+,-@}@var{val} 125189857Sobrien@cindex changing section LMA 125289857SobrienSet or change the LMA address of the named @var{section}. The LMA 125389857Sobrienaddress is the address where the section will be loaded into memory at 125489857Sobrienprogram load time. Normally this is the same as the VMA address, which 125589857Sobrienis the address of the section at program run time, but on some systems, 125689857Sobrienespecially those where a program is held in ROM, the two can be 125789857Sobriendifferent. If @samp{=} is used, the section address is set to 125889857Sobrien@var{val}. Otherwise, @var{val} is added to or subtracted from the 125989857Sobriensection address. See the comments under @option{--change-addresses}, 126089857Sobrienabove. If @var{section} does not exist in the input file, a warning 1261218822Sdimwill be issued, unless @option{--no-change-warnings} is used. 126289857Sobrien 126389857Sobrien@item --change-section-vma @var{section}@{=,+,-@}@var{val} 126489857Sobrien@cindex changing section VMA 126589857SobrienSet or change the VMA address of the named @var{section}. The VMA 126689857Sobrienaddress is the address where the section will be located once the 126789857Sobrienprogram has started executing. Normally this is the same as the LMA 126889857Sobrienaddress, which is the address where the section will be loaded into 126989857Sobrienmemory, but on some systems, especially those where a program is held in 127089857SobrienROM, the two can be different. If @samp{=} is used, the section address 127189857Sobrienis set to @var{val}. Otherwise, @var{val} is added to or subtracted 127289857Sobrienfrom the section address. See the comments under 127389857Sobrien@option{--change-addresses}, above. If @var{section} does not exist in 127489857Sobrienthe input file, a warning will be issued, unless 1275218822Sdim@option{--no-change-warnings} is used. 127689857Sobrien 127789857Sobrien@item --change-warnings 127889857Sobrien@itemx --adjust-warnings 127989857SobrienIf @option{--change-section-address} or @option{--change-section-lma} or 128089857Sobrien@option{--change-section-vma} is used, and the named section does not 1281218822Sdimexist, issue a warning. This is the default. 128289857Sobrien 128389857Sobrien@item --no-change-warnings 128489857Sobrien@itemx --no-adjust-warnings 128589857SobrienDo not issue a warning if @option{--change-section-address} or 128689857Sobrien@option{--adjust-section-lma} or @option{--adjust-section-vma} is used, even 1287218822Sdimif the named section does not exist. 128889857Sobrien 128989857Sobrien@item --set-section-flags @var{section}=@var{flags} 129089857SobrienSet the flags for the named section. The @var{flags} argument is a 129189857Sobriencomma separated string of flag names. The recognized names are 129289857Sobrien@samp{alloc}, @samp{contents}, @samp{load}, @samp{noload}, 129389857Sobrien@samp{readonly}, @samp{code}, @samp{data}, @samp{rom}, @samp{share}, and 129489857Sobrien@samp{debug}. You can set the @samp{contents} flag for a section which 129589857Sobriendoes not have contents, but it is not meaningful to clear the 129689857Sobrien@samp{contents} flag of a section which does have contents--just remove 129789857Sobrienthe section instead. Not all flags are meaningful for all object file 129889857Sobrienformats. 129989857Sobrien 130089857Sobrien@item --add-section @var{sectionname}=@var{filename} 130189857SobrienAdd a new section named @var{sectionname} while copying the file. The 130289857Sobriencontents of the new section are taken from the file @var{filename}. The 130389857Sobriensize of the section will be the size of the file. This option only 130489857Sobrienworks on file formats which can support sections with arbitrary names. 130589857Sobrien 130689857Sobrien@item --rename-section @var{oldname}=@var{newname}[,@var{flags}] 130789857SobrienRename a section from @var{oldname} to @var{newname}, optionally 130889857Sobrienchanging the section's flags to @var{flags} in the process. This has 130989857Sobrienthe advantage over usng a linker script to perform the rename in that 131089857Sobrienthe output stays as an object file and does not become a linked 131189857Sobrienexecutable. 131289857Sobrien 131389857SobrienThis option is particularly helpful when the input format is binary, 131489857Sobriensince this will always create a section called .data. If for example, 131589857Sobrienyou wanted instead to create a section called .rodata containing binary 131689857Sobriendata you could use the following command line to achieve it: 131789857Sobrien 131889857Sobrien@smallexample 131989857Sobrien objcopy -I binary -O <output_format> -B <architecture> \ 132089857Sobrien --rename-section .data=.rodata,alloc,load,readonly,data,contents \ 132189857Sobrien <input_binary_file> <output_object_file> 132289857Sobrien@end smallexample 132389857Sobrien 132489857Sobrien@item --change-leading-char 132589857SobrienSome object file formats use special characters at the start of 132689857Sobriensymbols. The most common such character is underscore, which compilers 132789857Sobrienoften add before every symbol. This option tells @command{objcopy} to 132889857Sobrienchange the leading character of every symbol when it converts between 132989857Sobrienobject file formats. If the object file formats use the same leading 133089857Sobriencharacter, this option has no effect. Otherwise, it will add a 133189857Sobriencharacter, or remove a character, or change a character, as 133289857Sobrienappropriate. 133389857Sobrien 133489857Sobrien@item --remove-leading-char 133589857SobrienIf the first character of a global symbol is a special symbol leading 133689857Sobriencharacter used by the object file format, remove the character. The 133789857Sobrienmost common symbol leading character is underscore. This option will 133889857Sobrienremove a leading underscore from all global symbols. This can be useful 133989857Sobrienif you want to link together objects of different file formats with 134089857Sobriendifferent conventions for symbol names. This is different from 134189857Sobrien@option{--change-leading-char} because it always changes the symbol name 134289857Sobrienwhen appropriate, regardless of the object file format of the output 134389857Sobrienfile. 134489857Sobrien 1345218822Sdim@item --reverse-bytes=@var{num} 1346218822SdimReverse the bytes in a section with output contents. A section length must 1347218822Sdimbe evenly divisible by the value given in order for the swap to be able to 1348218822Sdimtake place. Reversing takes place before the interleaving is performed. 1349218822Sdim 1350218822SdimThis option is used typically in generating ROM images for problematic 1351218822Sdimtarget systems. For example, on some target boards, the 32-bit words 1352218822Sdimfetched from 8-bit ROMs are re-assembled in little-endian byte order 1353218822Sdimregardless of the CPU byte order. Depending on the programming model, the 1354218822Sdimendianness of the ROM may need to be modified. 1355218822Sdim 1356218822SdimConsider a simple file with a section containing the following eight 1357218822Sdimbytes: @code{12345678}. 1358218822Sdim 1359218822SdimUsing @samp{--reverse-bytes=2} for the above example, the bytes in the 1360218822Sdimoutput file would be ordered @code{21436587}. 1361218822Sdim 1362218822SdimUsing @samp{--reverse-bytes=4} for the above example, the bytes in the 1363218822Sdimoutput file would be ordered @code{43218765}. 1364218822Sdim 1365218822SdimBy using @samp{--reverse-bytes=2} for the above example, followed by 1366218822Sdim@samp{--reverse-bytes=4} on the output file, the bytes in the second 1367218822Sdimoutput file would be ordered @code{34127856}. 1368218822Sdim 136989857Sobrien@item --srec-len=@var{ival} 137089857SobrienMeaningful only for srec output. Set the maximum length of the Srecords 137189857Sobrienbeing produced to @var{ival}. This length covers both address, data and 137289857Sobriencrc fields. 137389857Sobrien 137489857Sobrien@item --srec-forceS3 1375218822SdimMeaningful only for srec output. Avoid generation of S1/S2 records, 137689857Sobriencreating S3-only record format. 137789857Sobrien 137889857Sobrien@item --redefine-sym @var{old}=@var{new} 137989857SobrienChange the name of a symbol @var{old}, to @var{new}. This can be useful 138089857Sobrienwhen one is trying link two things together for which you have no 138189857Sobriensource, and there are name collisions. 138289857Sobrien 1383130561Sobrien@item --redefine-syms=@var{filename} 1384130561SobrienApply @option{--redefine-sym} to each symbol pair "@var{old} @var{new}" 1385130561Sobrienlisted in the file @var{filename}. @var{filename} is simply a flat file, 1386130561Sobrienwith one symbol pair per line. Line comments may be introduced by the hash 1387130561Sobriencharacter. This option may be given more than once. 1388130561Sobrien 138989857Sobrien@item --weaken 139089857SobrienChange all global symbols in the file to be weak. This can be useful 139189857Sobrienwhen building an object which will be linked against other objects using 139289857Sobrienthe @option{-R} option to the linker. This option is only effective when 139389857Sobrienusing an object file format which supports weak symbols. 139489857Sobrien 139589857Sobrien@item --keep-symbols=@var{filename} 139689857SobrienApply @option{--keep-symbol} option to each symbol listed in the file 139789857Sobrien@var{filename}. @var{filename} is simply a flat file, with one symbol 139889857Sobrienname per line. Line comments may be introduced by the hash character. 139989857SobrienThis option may be given more than once. 140089857Sobrien 140189857Sobrien@item --strip-symbols=@var{filename} 140289857SobrienApply @option{--strip-symbol} option to each symbol listed in the file 140389857Sobrien@var{filename}. @var{filename} is simply a flat file, with one symbol 140489857Sobrienname per line. Line comments may be introduced by the hash character. 140589857SobrienThis option may be given more than once. 140689857Sobrien 1407218822Sdim@item --strip-unneeded-symbols=@var{filename} 1408218822SdimApply @option{--strip-unneeded-symbol} option to each symbol listed in 1409218822Sdimthe file @var{filename}. @var{filename} is simply a flat file, with one 1410218822Sdimsymbol name per line. Line comments may be introduced by the hash 1411218822Sdimcharacter. This option may be given more than once. 1412218822Sdim 141389857Sobrien@item --keep-global-symbols=@var{filename} 141489857SobrienApply @option{--keep-global-symbol} option to each symbol listed in the 141589857Sobrienfile @var{filename}. @var{filename} is simply a flat file, with one 141689857Sobriensymbol name per line. Line comments may be introduced by the hash 141789857Sobriencharacter. This option may be given more than once. 141889857Sobrien 141989857Sobrien@item --localize-symbols=@var{filename} 142089857SobrienApply @option{--localize-symbol} option to each symbol listed in the file 142189857Sobrien@var{filename}. @var{filename} is simply a flat file, with one symbol 142289857Sobrienname per line. Line comments may be introduced by the hash character. 142389857SobrienThis option may be given more than once. 142489857Sobrien 1425218822Sdim@item --globalize-symbols=@var{filename} 1426218822SdimApply @option{--globalize-symbol} option to each symbol listed in the file 1427218822Sdim@var{filename}. @var{filename} is simply a flat file, with one symbol 1428218822Sdimname per line. Line comments may be introduced by the hash character. 1429218822SdimThis option may be given more than once. 1430218822Sdim 143189857Sobrien@item --weaken-symbols=@var{filename} 143289857SobrienApply @option{--weaken-symbol} option to each symbol listed in the file 143389857Sobrien@var{filename}. @var{filename} is simply a flat file, with one symbol 143489857Sobrienname per line. Line comments may be introduced by the hash character. 143589857SobrienThis option may be given more than once. 143689857Sobrien 143789857Sobrien@item --alt-machine-code=@var{index} 143889857SobrienIf the output architecture has alternate machine codes, use the 143989857Sobrien@var{index}th code instead of the default one. This is useful in case 1440218822Sdima machine is assigned an official code and the tool-chain adopts the 144189857Sobriennew code, but other applications still depend on the original code 1442218822Sdimbeing used. For ELF based architectures if the @var{index} 1443218822Sdimalternative does not exist then the value is treated as an absolute 1444218822Sdimnumber to be stored in the e_machine field of the ELF header. 144589857Sobrien 1446130561Sobrien@item --writable-text 1447130561SobrienMark the output text as writable. This option isn't meaningful for all 1448130561Sobrienobject file formats. 1449130561Sobrien 1450130561Sobrien@item --readonly-text 1451130561SobrienMake the output text write protected. This option isn't meaningful for all 1452130561Sobrienobject file formats. 1453130561Sobrien 1454130561Sobrien@item --pure 1455130561SobrienMark the output file as demand paged. This option isn't meaningful for all 1456130561Sobrienobject file formats. 1457130561Sobrien 1458130561Sobrien@item --impure 1459130561SobrienMark the output file as impure. This option isn't meaningful for all 1460130561Sobrienobject file formats. 1461130561Sobrien 1462130561Sobrien@item --prefix-symbols=@var{string} 1463130561SobrienPrefix all symbols in the output file with @var{string}. 1464130561Sobrien 1465130561Sobrien@item --prefix-sections=@var{string} 1466130561SobrienPrefix all section names in the output file with @var{string}. 1467130561Sobrien 1468130561Sobrien@item --prefix-alloc-sections=@var{string} 1469130561SobrienPrefix all the names of all allocated sections in the output file with 1470130561Sobrien@var{string}. 1471130561Sobrien 1472130561Sobrien@item --add-gnu-debuglink=@var{path-to-file} 1473130561SobrienCreates a .gnu_debuglink section which contains a reference to @var{path-to-file} 1474130561Sobrienand adds it to the output file. 1475130561Sobrien 1476218822Sdim@item --keep-file-symbols 1477218822SdimWhen stripping a file, perhaps with @option{--strip-debug} or 1478218822Sdim@option{--strip-unneeded}, retain any symbols specifying source file names, 1479218822Sdimwhich would otherwise get stripped. 1480218822Sdim 1481130561Sobrien@item --only-keep-debug 1482218822SdimStrip a file, removing contents of any sections that would not be 1483218822Sdimstripped by @option{--strip-debug} and leaving the debugging sections 1484218822Sdimintact. In ELF files, this preserves all note sections in the output. 1485130561Sobrien 1486130561SobrienThe intention is that this option will be used in conjunction with 1487130561Sobrien@option{--add-gnu-debuglink} to create a two part executable. One a 1488130561Sobrienstripped binary which will occupy less space in RAM and in a 1489130561Sobriendistribution and the second a debugging information file which is only 1490130561Sobrienneeded if debugging abilities are required. The suggested procedure 1491130561Sobriento create these files is as follows: 1492130561Sobrien 1493130561Sobrien@enumerate 1494130561Sobrien@item Link the executable as normal. Assuming that is is called 1495130561Sobrien@code{foo} then... 1496130561Sobrien@item Run @code{objcopy --only-keep-debug foo foo.dbg} to 1497130561Sobriencreate a file containing the debugging info. 1498130561Sobrien@item Run @code{objcopy --strip-debug foo} to create a 1499130561Sobrienstripped executable. 1500130561Sobrien@item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo} 1501130561Sobriento add a link to the debugging info into the stripped executable. 1502130561Sobrien@end enumerate 1503130561Sobrien 1504130561SobrienNote - the choice of @code{.dbg} as an extension for the debug info 1505130561Sobrienfile is arbitrary. Also the @code{--only-keep-debug} step is 1506130561Sobrienoptional. You could instead do this: 1507130561Sobrien 1508130561Sobrien@enumerate 1509130561Sobrien@item Link the executable as normal. 1510130561Sobrien@item Copy @code{foo} to @code{foo.full} 1511130561Sobrien@item Run @code{objcopy --strip-debug foo} 1512130561Sobrien@item Run @code{objcopy --add-gnu-debuglink=foo.full foo} 1513130561Sobrien@end enumerate 1514130561Sobrien 1515218822Sdimi.e., the file pointed to by the @option{--add-gnu-debuglink} can be the 1516130561Sobrienfull executable. It does not have to be a file created by the 1517130561Sobrien@option{--only-keep-debug} switch. 1518130561Sobrien 1519218822SdimNote - this switch is only intended for use on fully linked files. It 1520218822Sdimdoes not make sense to use it on object files where the debugging 1521218822Sdiminformation may be incomplete. Besides the gnu_debuglink feature 1522218822Sdimcurrently only supports the presence of one filename containing 1523218822Sdimdebugging information, not multiple filenames on a one-per-object-file 1524218822Sdimbasis. 1525218822Sdim 1526218822Sdim@item --extract-symbol 1527218822SdimKeep the file's section flags and symbols but remove all section data. 1528218822SdimSpecifically, the option: 1529218822Sdim 1530218822Sdim@itemize 1531218822Sdim@item sets the virtual and load addresses of every section to zero; 1532218822Sdim@item removes the contents of all sections; 1533218822Sdim@item sets the size of every section to zero; and 1534218822Sdim@item sets the file's start address to zero. 1535218822Sdim@end itemize 1536218822Sdim 1537218822SdimThis option is used to build a @file{.sym} file for a VxWorks kernel. 1538218822SdimIt can also be a useful way of reducing the size of a @option{--just-symbols} 1539218822Sdimlinker input file. 1540218822Sdim 154189857Sobrien@item -V 154289857Sobrien@itemx --version 154389857SobrienShow the version number of @command{objcopy}. 154489857Sobrien 154589857Sobrien@item -v 154689857Sobrien@itemx --verbose 154789857SobrienVerbose output: list all object files modified. In the case of 154889857Sobrienarchives, @samp{objcopy -V} lists all members of the archive. 154989857Sobrien 155089857Sobrien@item --help 155189857SobrienShow a summary of the options to @command{objcopy}. 1552130561Sobrien 1553130561Sobrien@item --info 1554130561SobrienDisplay a list showing all architectures and object formats available. 155589857Sobrien@end table 155689857Sobrien 155789857Sobrien@c man end 155889857Sobrien 155989857Sobrien@ignore 156089857Sobrien@c man begin SEEALSO objcopy 156189857Sobrienld(1), objdump(1), and the Info entries for @file{binutils}. 156289857Sobrien@c man end 156389857Sobrien@end ignore 156489857Sobrien 156589857Sobrien@node objdump 156689857Sobrien@chapter objdump 156789857Sobrien 156889857Sobrien@cindex object file information 156989857Sobrien@kindex objdump 157089857Sobrien 157189857Sobrien@c man title objdump display information from object files. 157289857Sobrien 157389857Sobrien@smallexample 157489857Sobrien@c man begin SYNOPSIS objdump 157589857Sobrienobjdump [@option{-a}|@option{--archive-headers}] 157689857Sobrien [@option{-b} @var{bfdname}|@option{--target=@var{bfdname}}] 157789857Sobrien [@option{-C}|@option{--demangle}[=@var{style}] ] 157889857Sobrien [@option{-d}|@option{--disassemble}] 157989857Sobrien [@option{-D}|@option{--disassemble-all}] 158089857Sobrien [@option{-z}|@option{--disassemble-zeroes}] 158189857Sobrien [@option{-EB}|@option{-EL}|@option{--endian=}@{big | little @}] 158289857Sobrien [@option{-f}|@option{--file-headers}] 158389857Sobrien [@option{--file-start-context}] 158489857Sobrien [@option{-g}|@option{--debugging}] 1585130561Sobrien [@option{-e}|@option{--debugging-tags}] 158689857Sobrien [@option{-h}|@option{--section-headers}|@option{--headers}] 158789857Sobrien [@option{-i}|@option{--info}] 158889857Sobrien [@option{-j} @var{section}|@option{--section=}@var{section}] 158989857Sobrien [@option{-l}|@option{--line-numbers}] 159089857Sobrien [@option{-S}|@option{--source}] 159189857Sobrien [@option{-m} @var{machine}|@option{--architecture=}@var{machine}] 159289857Sobrien [@option{-M} @var{options}|@option{--disassembler-options=}@var{options}] 159389857Sobrien [@option{-p}|@option{--private-headers}] 159489857Sobrien [@option{-r}|@option{--reloc}] 159589857Sobrien [@option{-R}|@option{--dynamic-reloc}] 159689857Sobrien [@option{-s}|@option{--full-contents}] 1597218822Sdim [@option{-W}|@option{--dwarf}] 159889857Sobrien [@option{-G}|@option{--stabs}] 159989857Sobrien [@option{-t}|@option{--syms}] 160089857Sobrien [@option{-T}|@option{--dynamic-syms}] 160189857Sobrien [@option{-x}|@option{--all-headers}] 160289857Sobrien [@option{-w}|@option{--wide}] 160389857Sobrien [@option{--start-address=}@var{address}] 160489857Sobrien [@option{--stop-address=}@var{address}] 160589857Sobrien [@option{--prefix-addresses}] 160689857Sobrien [@option{--[no-]show-raw-insn}] 160789857Sobrien [@option{--adjust-vma=}@var{offset}] 1608218822Sdim [@option{--special-syms}] 160989857Sobrien [@option{-V}|@option{--version}] 161089857Sobrien [@option{-H}|@option{--help}] 161189857Sobrien @var{objfile}@dots{} 161289857Sobrien@c man end 161389857Sobrien@end smallexample 161489857Sobrien 161589857Sobrien@c man begin DESCRIPTION objdump 161689857Sobrien 161789857Sobrien@command{objdump} displays information about one or more object files. 161889857SobrienThe options control what particular information to display. This 161989857Sobrieninformation is mostly useful to programmers who are working on the 162089857Sobriencompilation tools, as opposed to programmers who just want their 162189857Sobrienprogram to compile and work. 162289857Sobrien 162389857Sobrien@var{objfile}@dots{} are the object files to be examined. When you 162489857Sobrienspecify archives, @command{objdump} shows information on each of the member 162589857Sobrienobject files. 162689857Sobrien 162789857Sobrien@c man end 162889857Sobrien 162989857Sobrien@c man begin OPTIONS objdump 163089857Sobrien 163189857SobrienThe long and short forms of options, shown here as alternatives, are 163289857Sobrienequivalent. At least one option from the list 1633130561Sobrien@option{-a,-d,-D,-e,-f,-g,-G,-h,-H,-p,-r,-R,-s,-S,-t,-T,-V,-x} must be given. 163489857Sobrien 163589857Sobrien@table @env 163689857Sobrien@item -a 163789857Sobrien@itemx --archive-header 163889857Sobrien@cindex archive headers 163989857SobrienIf any of the @var{objfile} files are archives, display the archive 164089857Sobrienheader information (in a format similar to @samp{ls -l}). Besides the 164189857Sobrieninformation you could list with @samp{ar tv}, @samp{objdump -a} shows 164289857Sobrienthe object file format of each archive member. 164389857Sobrien 164489857Sobrien@item --adjust-vma=@var{offset} 164589857Sobrien@cindex section addresses in objdump 164689857Sobrien@cindex VMA in objdump 164789857SobrienWhen dumping information, first add @var{offset} to all the section 164889857Sobrienaddresses. This is useful if the section addresses do not correspond to 164989857Sobrienthe symbol table, which can happen when putting sections at particular 165089857Sobrienaddresses when using a format which can not represent section addresses, 165189857Sobriensuch as a.out. 165289857Sobrien 165389857Sobrien@item -b @var{bfdname} 165489857Sobrien@itemx --target=@var{bfdname} 165589857Sobrien@cindex object code format 165689857SobrienSpecify that the object-code format for the object files is 165789857Sobrien@var{bfdname}. This option may not be necessary; @var{objdump} can 165889857Sobrienautomatically recognize many formats. 165989857Sobrien 166089857SobrienFor example, 166189857Sobrien@example 166289857Sobrienobjdump -b oasys -m vax -h fu.o 166389857Sobrien@end example 166489857Sobrien@noindent 166589857Sobriendisplays summary information from the section headers (@option{-h}) of 166689857Sobrien@file{fu.o}, which is explicitly identified (@option{-m}) as a VAX object 166789857Sobrienfile in the format produced by Oasys compilers. You can list the 166889857Sobrienformats available with the @option{-i} option. 166989857Sobrien@xref{Target Selection}, for more information. 167089857Sobrien 167189857Sobrien@item -C 167289857Sobrien@itemx --demangle[=@var{style}] 167389857Sobrien@cindex demangling in objdump 167489857SobrienDecode (@dfn{demangle}) low-level symbol names into user-level names. 167589857SobrienBesides removing any initial underscore prepended by the system, this 167689857Sobrienmakes C++ function names readable. Different compilers have different 1677218822Sdimmangling styles. The optional demangling style argument can be used to 1678218822Sdimchoose an appropriate demangling style for your compiler. @xref{c++filt}, 167989857Sobrienfor more information on demangling. 168089857Sobrien 1681130561Sobrien@item -g 1682130561Sobrien@itemx --debugging 168389857SobrienDisplay debugging information. This attempts to parse debugging 168489857Sobrieninformation stored in the file and print it out using a C like syntax. 168589857SobrienOnly certain types of debugging information have been implemented. 1686130561SobrienSome other types are supported by @command{readelf -w}. 1687130561Sobrien@xref{readelf}. 168889857Sobrien 1689130561Sobrien@item -e 1690130561Sobrien@itemx --debugging-tags 1691130561SobrienLike @option{-g}, but the information is generated in a format compatible 1692130561Sobrienwith ctags tool. 1693130561Sobrien 169489857Sobrien@item -d 169589857Sobrien@itemx --disassemble 169689857Sobrien@cindex disassembling object code 169789857Sobrien@cindex machine instructions 169889857SobrienDisplay the assembler mnemonics for the machine instructions from 169989857Sobrien@var{objfile}. This option only disassembles those sections which are 170089857Sobrienexpected to contain instructions. 170189857Sobrien 170289857Sobrien@item -D 170389857Sobrien@itemx --disassemble-all 170489857SobrienLike @option{-d}, but disassemble the contents of all sections, not just 170589857Sobrienthose expected to contain instructions. 170689857Sobrien 170789857Sobrien@item --prefix-addresses 170889857SobrienWhen disassembling, print the complete address on each line. This is 170989857Sobrienthe older disassembly format. 171089857Sobrien 171189857Sobrien@item -EB 171289857Sobrien@itemx -EL 171389857Sobrien@itemx --endian=@{big|little@} 171489857Sobrien@cindex endianness 171589857Sobrien@cindex disassembly endianness 171689857SobrienSpecify the endianness of the object files. This only affects 171789857Sobriendisassembly. This can be useful when disassembling a file format which 171889857Sobriendoes not describe endianness information, such as S-records. 171989857Sobrien 172089857Sobrien@item -f 1721130561Sobrien@itemx --file-headers 172289857Sobrien@cindex object file header 172389857SobrienDisplay summary information from the overall header of 172489857Sobrieneach of the @var{objfile} files. 172589857Sobrien 172689857Sobrien@item --file-start-context 172789857Sobrien@cindex source code context 172889857SobrienSpecify that when displaying interlisted source code/disassembly 172989857Sobrien(assumes @option{-S}) from a file that has not yet been displayed, extend the 173089857Sobriencontext to the start of the file. 173189857Sobrien 173289857Sobrien@item -h 1733130561Sobrien@itemx --section-headers 1734130561Sobrien@itemx --headers 173589857Sobrien@cindex section headers 173689857SobrienDisplay summary information from the section headers of the 173789857Sobrienobject file. 173889857Sobrien 173989857SobrienFile segments may be relocated to nonstandard addresses, for example by 174089857Sobrienusing the @option{-Ttext}, @option{-Tdata}, or @option{-Tbss} options to 174189857Sobrien@command{ld}. However, some object file formats, such as a.out, do not 174289857Sobrienstore the starting address of the file segments. In those situations, 174389857Sobrienalthough @command{ld} relocates the sections correctly, using @samp{objdump 174489857Sobrien-h} to list the file section headers cannot show the correct addresses. 174589857SobrienInstead, it shows the usual addresses, which are implicit for the 174689857Sobrientarget. 174789857Sobrien 1748130561Sobrien@item -H 1749130561Sobrien@itemx --help 175089857SobrienPrint a summary of the options to @command{objdump} and exit. 175189857Sobrien 175289857Sobrien@item -i 175389857Sobrien@itemx --info 175489857Sobrien@cindex architectures available 175589857Sobrien@cindex object formats available 175689857SobrienDisplay a list showing all architectures and object formats available 175789857Sobrienfor specification with @option{-b} or @option{-m}. 175889857Sobrien 175989857Sobrien@item -j @var{name} 176089857Sobrien@itemx --section=@var{name} 176189857Sobrien@cindex section information 176289857SobrienDisplay information only for section @var{name}. 176389857Sobrien 176489857Sobrien@item -l 176589857Sobrien@itemx --line-numbers 176689857Sobrien@cindex source filenames for object files 176789857SobrienLabel the display (using debugging information) with the filename and 176889857Sobriensource line numbers corresponding to the object code or relocs shown. 176989857SobrienOnly useful with @option{-d}, @option{-D}, or @option{-r}. 177089857Sobrien 177189857Sobrien@item -m @var{machine} 177289857Sobrien@itemx --architecture=@var{machine} 177389857Sobrien@cindex architecture 177489857Sobrien@cindex disassembly architecture 177589857SobrienSpecify the architecture to use when disassembling object files. This 177689857Sobriencan be useful when disassembling object files which do not describe 177789857Sobrienarchitecture information, such as S-records. You can list the available 177889857Sobrienarchitectures with the @option{-i} option. 177989857Sobrien 178089857Sobrien@item -M @var{options} 178189857Sobrien@itemx --disassembler-options=@var{options} 178289857SobrienPass target specific information to the disassembler. Only supported on 1783130561Sobriensome targets. If it is necessary to specify more than one 1784130561Sobriendisassembler option then multiple @option{-M} options can be used or 1785130561Sobriencan be placed together into a comma separated list. 178689857Sobrien 178789857SobrienIf the target is an ARM architecture then this switch can be used to 178889857Sobrienselect which register name set is used during disassembler. Specifying 1789218822Sdim@option{-M reg-names-std} (the default) will select the register names as 179089857Sobrienused in ARM's instruction set documentation, but with register 13 called 179189857Sobrien'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying 179289857Sobrien@option{-M reg-names-apcs} will select the name set used by the ARM 179389857SobrienProcedure Call Standard, whilst specifying @option{-M reg-names-raw} will 179489857Sobrienjust use @samp{r} followed by the register number. 179589857Sobrien 179689857SobrienThere are also two variants on the APCS register naming scheme enabled 179789857Sobrienby @option{-M reg-names-atpcs} and @option{-M reg-names-special-atpcs} which 179889857Sobrienuse the ARM/Thumb Procedure Call Standard naming conventions. (Either 1799130561Sobrienwith the normal register names or the special register names). 180089857Sobrien 180189857SobrienThis option can also be used for ARM architectures to force the 180289857Sobriendisassembler to interpret all instructions as Thumb instructions by 180389857Sobrienusing the switch @option{--disassembler-options=force-thumb}. This can be 180489857Sobrienuseful when attempting to disassemble thumb code produced by other 180589857Sobriencompilers. 180689857Sobrien 180789857SobrienFor the x86, some of the options duplicate functions of the @option{-m} 180889857Sobrienswitch, but allow finer grained control. Multiple selections from the 180989857Sobrienfollowing may be specified as a comma separated string. 181089857Sobrien@option{x86-64}, @option{i386} and @option{i8086} select disassembly for 181189857Sobrienthe given architecture. @option{intel} and @option{att} select between 1812218822Sdimintel syntax mode and AT&T syntax mode. @option{addr64}, @option{addr32}, 181389857Sobrien@option{addr16}, @option{data32} and @option{data16} specify the default 181489857Sobrienaddress size and operand size. These four options will be overridden if 181589857Sobrien@option{x86-64}, @option{i386} or @option{i8086} appear later in the 181689857Sobrienoption string. Lastly, @option{suffix}, when in AT&T mode, 1817130561Sobrieninstructs the disassembler to print a mnemonic suffix even when the 181889857Sobriensuffix could be inferred by the operands. 181989857Sobrien 182089857SobrienFor PPC, @option{booke}, @option{booke32} and @option{booke64} select 182189857Sobriendisassembly of BookE instructions. @option{32} and @option{64} select 1822218822SdimPowerPC and PowerPC64 disassembly, respectively. @option{e300} selects 1823218822Sdimdisassembly for the e300 family. @option{440} selects disassembly for 1824218822Sdimthe PowerPC 440. 182589857Sobrien 1826218822SdimFor MIPS, this option controls the printing of instruction mnemonic 1827218822Sdimnames and register names in disassembled instructions. Multiple 1828218822Sdimselections from the following may be specified as a comma separated 1829218822Sdimstring, and invalid options are ignored: 1830130561Sobrien 1831130561Sobrien@table @code 1832218822Sdim@item no-aliases 1833218822SdimPrint the 'raw' instruction mnemonic instead of some pseudo 1834218822Sdiminstruction mnemonic. I.e., print 'daddu' or 'or' instead of 'move', 1835218822Sdim'sll' instead of 'nop', etc. 1836218822Sdim 1837130561Sobrien@item gpr-names=@var{ABI} 1838130561SobrienPrint GPR (general-purpose register) names as appropriate 1839130561Sobrienfor the specified ABI. By default, GPR names are selected according to 1840130561Sobrienthe ABI of the binary being disassembled. 1841130561Sobrien 1842130561Sobrien@item fpr-names=@var{ABI} 1843130561SobrienPrint FPR (floating-point register) names as 1844130561Sobrienappropriate for the specified ABI. By default, FPR numbers are printed 1845130561Sobrienrather than names. 1846130561Sobrien 1847130561Sobrien@item cp0-names=@var{ARCH} 1848130561SobrienPrint CP0 (system control coprocessor; coprocessor 0) register names 1849130561Sobrienas appropriate for the CPU or architecture specified by 1850130561Sobrien@var{ARCH}. By default, CP0 register names are selected according to 1851130561Sobrienthe architecture and CPU of the binary being disassembled. 1852130561Sobrien 1853130561Sobrien@item hwr-names=@var{ARCH} 1854130561SobrienPrint HWR (hardware register, used by the @code{rdhwr} instruction) names 1855130561Sobrienas appropriate for the CPU or architecture specified by 1856130561Sobrien@var{ARCH}. By default, HWR names are selected according to 1857130561Sobrienthe architecture and CPU of the binary being disassembled. 1858130561Sobrien 1859130561Sobrien@item reg-names=@var{ABI} 1860130561SobrienPrint GPR and FPR names as appropriate for the selected ABI. 1861130561Sobrien 1862130561Sobrien@item reg-names=@var{ARCH} 1863130561SobrienPrint CPU-specific register names (CP0 register and HWR names) 1864130561Sobrienas appropriate for the selected CPU or architecture. 1865130561Sobrien@end table 1866130561Sobrien 1867130561SobrienFor any of the options listed above, @var{ABI} or 1868130561Sobrien@var{ARCH} may be specified as @samp{numeric} to have numbers printed 1869130561Sobrienrather than names, for the selected types of registers. 1870130561SobrienYou can list the available values of @var{ABI} and @var{ARCH} using 1871130561Sobrienthe @option{--help} option. 1872130561Sobrien 1873218822SdimFor VAX, you can specify function entry addresses with @option{-M 1874218822Sdimentry:0xf00ba}. You can use this multiple times to properly 1875218822Sdimdisassemble VAX binary files that don't contain symbol tables (like 1876218822SdimROM dumps). In these cases, the function entry mask would otherwise 1877218822Sdimbe decoded as VAX instructions, which would probably lead the rest 1878218822Sdimof the function being wrongly disassembled. 1879218822Sdim 188089857Sobrien@item -p 188189857Sobrien@itemx --private-headers 188289857SobrienPrint information that is specific to the object file format. The exact 188389857Sobrieninformation printed depends upon the object file format. For some 188489857Sobrienobject file formats, no additional information is printed. 188589857Sobrien 188689857Sobrien@item -r 188789857Sobrien@itemx --reloc 188889857Sobrien@cindex relocation entries, in object file 188989857SobrienPrint the relocation entries of the file. If used with @option{-d} or 189089857Sobrien@option{-D}, the relocations are printed interspersed with the 189189857Sobriendisassembly. 189289857Sobrien 189389857Sobrien@item -R 189489857Sobrien@itemx --dynamic-reloc 189589857Sobrien@cindex dynamic relocation entries, in object file 189689857SobrienPrint the dynamic relocation entries of the file. This is only 189789857Sobrienmeaningful for dynamic objects, such as certain types of shared 189889857Sobrienlibraries. 189989857Sobrien 190089857Sobrien@item -s 190189857Sobrien@itemx --full-contents 190289857Sobrien@cindex sections, full contents 190389857Sobrien@cindex object file sections 1904130561SobrienDisplay the full contents of any sections requested. By default all 1905130561Sobriennon-empty sections are displayed. 190689857Sobrien 190789857Sobrien@item -S 190889857Sobrien@itemx --source 190989857Sobrien@cindex source disassembly 191089857Sobrien@cindex disassembly, with source 191189857SobrienDisplay source code intermixed with disassembly, if possible. Implies 191289857Sobrien@option{-d}. 191389857Sobrien 191489857Sobrien@item --show-raw-insn 191589857SobrienWhen disassembling instructions, print the instruction in hex as well as 191689857Sobrienin symbolic form. This is the default except when 191789857Sobrien@option{--prefix-addresses} is used. 191889857Sobrien 191989857Sobrien@item --no-show-raw-insn 192089857SobrienWhen disassembling instructions, do not print the instruction bytes. 192189857SobrienThis is the default when @option{--prefix-addresses} is used. 192289857Sobrien 1923218822Sdim@item -W 1924218822Sdim@itemx --dwarf 1925218822Sdim@cindex DWARF 1926218822Sdim@cindex debug symbols 1927218822SdimDisplays the contents of the DWARF debug sections in the file, if any 1928218822Sdimare present. 1929218822Sdim 193089857Sobrien@item -G 1931130561Sobrien@itemx --stabs 193289857Sobrien@cindex stab 193389857Sobrien@cindex .stab 193489857Sobrien@cindex debug symbols 193589857Sobrien@cindex ELF object file format 193689857SobrienDisplay the full contents of any sections requested. Display the 193789857Sobriencontents of the .stab and .stab.index and .stab.excl sections from an 193889857SobrienELF file. This is only useful on systems (such as Solaris 2.0) in which 193989857Sobrien@code{.stab} debugging symbol-table entries are carried in an ELF 194089857Sobriensection. In most other file formats, debugging symbol-table entries are 194189857Sobrieninterleaved with linkage symbols, and are visible in the @option{--syms} 194289857Sobrienoutput. 194389857Sobrien@ifclear man 194489857SobrienFor more information on stabs symbols, see @ref{Top,Stabs,Stabs 194589857SobrienOverview,stabs.info, The ``stabs'' debug format}. 194689857Sobrien@end ifclear 194789857Sobrien 194889857Sobrien@item --start-address=@var{address} 194989857Sobrien@cindex start-address 195089857SobrienStart displaying data at the specified address. This affects the output 195189857Sobrienof the @option{-d}, @option{-r} and @option{-s} options. 195289857Sobrien 195389857Sobrien@item --stop-address=@var{address} 195489857Sobrien@cindex stop-address 195589857SobrienStop displaying data at the specified address. This affects the output 195689857Sobrienof the @option{-d}, @option{-r} and @option{-s} options. 195789857Sobrien 195889857Sobrien@item -t 195989857Sobrien@itemx --syms 196089857Sobrien@cindex symbol table entries, printing 196189857SobrienPrint the symbol table entries of the file. 196289857SobrienThis is similar to the information provided by the @samp{nm} program. 196389857Sobrien 196489857Sobrien@item -T 196589857Sobrien@itemx --dynamic-syms 196689857Sobrien@cindex dynamic symbol table entries, printing 196789857SobrienPrint the dynamic symbol table entries of the file. This is only 196889857Sobrienmeaningful for dynamic objects, such as certain types of shared 196989857Sobrienlibraries. This is similar to the information provided by the @samp{nm} 197089857Sobrienprogram when given the @option{-D} (@option{--dynamic}) option. 197189857Sobrien 1972218822Sdim@item --special-syms 1973218822SdimWhen displaying symbols include those which the target considers to be 1974218822Sdimspecial in some way and which would not normally be of interest to the 1975218822Sdimuser. 1976218822Sdim 1977130561Sobrien@item -V 1978130561Sobrien@itemx --version 197989857SobrienPrint the version number of @command{objdump} and exit. 198089857Sobrien 198189857Sobrien@item -x 1982130561Sobrien@itemx --all-headers 198389857Sobrien@cindex all header information, object file 198489857Sobrien@cindex header information, all 198589857SobrienDisplay all available header information, including the symbol table and 198689857Sobrienrelocation entries. Using @option{-x} is equivalent to specifying all of 1987218822Sdim@option{-a -f -h -p -r -t}. 198889857Sobrien 198989857Sobrien@item -w 199089857Sobrien@itemx --wide 199189857Sobrien@cindex wide output, printing 199289857SobrienFormat some lines for output devices that have more than 80 columns. 199389857SobrienAlso do not truncate symbol names when they are displayed. 1994130561Sobrien 1995130561Sobrien@item -z 1996130561Sobrien@itemx --disassemble-zeroes 1997130561SobrienNormally the disassembly output will skip blocks of zeroes. This 1998130561Sobrienoption directs the disassembler to disassemble those blocks, just like 1999130561Sobrienany other data. 200089857Sobrien@end table 200189857Sobrien 200289857Sobrien@c man end 200389857Sobrien 200489857Sobrien@ignore 200589857Sobrien@c man begin SEEALSO objdump 200689857Sobriennm(1), readelf(1), and the Info entries for @file{binutils}. 200789857Sobrien@c man end 200889857Sobrien@end ignore 200989857Sobrien 201089857Sobrien@node ranlib 201189857Sobrien@chapter ranlib 201289857Sobrien 201389857Sobrien@kindex ranlib 201489857Sobrien@cindex archive contents 201589857Sobrien@cindex symbol index 201689857Sobrien 201789857Sobrien@c man title ranlib generate index to archive. 201889857Sobrien 201989857Sobrien@smallexample 202089857Sobrien@c man begin SYNOPSIS ranlib 202189857Sobrienranlib [@option{-vV}] @var{archive} 202289857Sobrien@c man end 202389857Sobrien@end smallexample 202489857Sobrien 202589857Sobrien@c man begin DESCRIPTION ranlib 202689857Sobrien 202789857Sobrien@command{ranlib} generates an index to the contents of an archive and 202889857Sobrienstores it in the archive. The index lists each symbol defined by a 2029218822Sdimmember of an archive that is a relocatable object file. 203089857Sobrien 203189857SobrienYou may use @samp{nm -s} or @samp{nm --print-armap} to list this index. 203289857Sobrien 203389857SobrienAn archive with such an index speeds up linking to the library and 203489857Sobrienallows routines in the library to call each other without regard to 203589857Sobrientheir placement in the archive. 203689857Sobrien 203789857SobrienThe @sc{gnu} @command{ranlib} program is another form of @sc{gnu} @command{ar}; running 203889857Sobrien@command{ranlib} is completely equivalent to executing @samp{ar -s}. 203989857Sobrien@xref{ar}. 204089857Sobrien 204189857Sobrien@c man end 204289857Sobrien 204389857Sobrien@c man begin OPTIONS ranlib 204489857Sobrien 204589857Sobrien@table @env 204689857Sobrien@item -v 204789857Sobrien@itemx -V 204889857Sobrien@itemx --version 204989857SobrienShow the version number of @command{ranlib}. 205089857Sobrien@end table 205189857Sobrien 205289857Sobrien@c man end 205389857Sobrien 205489857Sobrien@ignore 205589857Sobrien@c man begin SEEALSO ranlib 205689857Sobrienar(1), nm(1), and the Info entries for @file{binutils}. 205789857Sobrien@c man end 205889857Sobrien@end ignore 205989857Sobrien 206089857Sobrien@node size 206189857Sobrien@chapter size 206289857Sobrien 206389857Sobrien@kindex size 206489857Sobrien@cindex section sizes 206589857Sobrien 206689857Sobrien@c man title size list section sizes and total size. 206789857Sobrien 206889857Sobrien@smallexample 206989857Sobrien@c man begin SYNOPSIS size 207089857Sobriensize [@option{-A}|@option{-B}|@option{--format=}@var{compatibility}] 207189857Sobrien [@option{--help}] 207289857Sobrien [@option{-d}|@option{-o}|@option{-x}|@option{--radix=}@var{number}] 207389857Sobrien [@option{-t}|@option{--totals}] 2074218822Sdim [@option{--target=}@var{bfdname}] [@option{-V}|@option{--version}] 207589857Sobrien [@var{objfile}@dots{}] 207689857Sobrien@c man end 207789857Sobrien@end smallexample 207889857Sobrien 207989857Sobrien@c man begin DESCRIPTION size 208089857Sobrien 208189857SobrienThe @sc{gnu} @command{size} utility lists the section sizes---and the total 208289857Sobriensize---for each of the object or archive files @var{objfile} in its 208389857Sobrienargument list. By default, one line of output is generated for each 208489857Sobrienobject file or each module in an archive. 208589857Sobrien 208689857Sobrien@var{objfile}@dots{} are the object files to be examined. 208789857SobrienIf none are specified, the file @code{a.out} will be used. 208889857Sobrien 208989857Sobrien@c man end 209089857Sobrien 209189857Sobrien@c man begin OPTIONS size 209289857Sobrien 209389857SobrienThe command line options have the following meanings: 209489857Sobrien 209589857Sobrien@table @env 209689857Sobrien@item -A 209789857Sobrien@itemx -B 209889857Sobrien@itemx --format=@var{compatibility} 209989857Sobrien@cindex @command{size} display format 210089857SobrienUsing one of these options, you can choose whether the output from @sc{gnu} 210189857Sobrien@command{size} resembles output from System V @command{size} (using @option{-A}, 210289857Sobrienor @option{--format=sysv}), or Berkeley @command{size} (using @option{-B}, or 210389857Sobrien@option{--format=berkeley}). The default is the one-line format similar to 2104218822SdimBerkeley's. 210589857Sobrien@c Bonus for doc-source readers: you can also say --format=strange (or 210689857Sobrien@c anything else that starts with 's') for sysv, and --format=boring (or 210789857Sobrien@c anything else that starts with 'b') for Berkeley. 210889857Sobrien 210989857SobrienHere is an example of the Berkeley (default) format of output from 2110218822Sdim@command{size}: 211189857Sobrien@smallexample 211289857Sobrien$ size --format=Berkeley ranlib size 211389857Sobrientext data bss dec hex filename 211489857Sobrien294880 81920 11592 388392 5ed28 ranlib 211589857Sobrien294880 81920 11888 388688 5ee50 size 211689857Sobrien@end smallexample 211789857Sobrien 211889857Sobrien@noindent 211989857SobrienThis is the same data, but displayed closer to System V conventions: 212089857Sobrien 212189857Sobrien@smallexample 212289857Sobrien$ size --format=SysV ranlib size 212389857Sobrienranlib : 212489857Sobriensection size addr 2125218822Sdim.text 294880 8192 2126218822Sdim.data 81920 303104 2127218822Sdim.bss 11592 385024 2128218822SdimTotal 388392 212989857Sobrien 213089857Sobrien 213189857Sobriensize : 213289857Sobriensection size addr 2133218822Sdim.text 294880 8192 2134218822Sdim.data 81920 303104 2135218822Sdim.bss 11888 385024 2136218822SdimTotal 388688 213789857Sobrien@end smallexample 213889857Sobrien 213989857Sobrien@item --help 214089857SobrienShow a summary of acceptable arguments and options. 214189857Sobrien 214289857Sobrien@item -d 214389857Sobrien@itemx -o 214489857Sobrien@itemx -x 214589857Sobrien@itemx --radix=@var{number} 214689857Sobrien@cindex @command{size} number format 214789857Sobrien@cindex radix for section sizes 214889857SobrienUsing one of these options, you can control whether the size of each 214989857Sobriensection is given in decimal (@option{-d}, or @option{--radix=10}); octal 215089857Sobrien(@option{-o}, or @option{--radix=8}); or hexadecimal (@option{-x}, or 215189857Sobrien@option{--radix=16}). In @option{--radix=@var{number}}, only the three 215289857Sobrienvalues (8, 10, 16) are supported. The total size is always given in two 215389857Sobrienradices; decimal and hexadecimal for @option{-d} or @option{-x} output, or 215489857Sobrienoctal and hexadecimal if you're using @option{-o}. 215589857Sobrien 215689857Sobrien@item -t 215789857Sobrien@itemx --totals 215889857SobrienShow totals of all objects listed (Berkeley format listing mode only). 215989857Sobrien 216089857Sobrien@item --target=@var{bfdname} 216189857Sobrien@cindex object code format 216289857SobrienSpecify that the object-code format for @var{objfile} is 216389857Sobrien@var{bfdname}. This option may not be necessary; @command{size} can 216489857Sobrienautomatically recognize many formats. 216589857Sobrien@xref{Target Selection}, for more information. 216689857Sobrien 216789857Sobrien@item -V 216889857Sobrien@itemx --version 216989857SobrienDisplay the version number of @command{size}. 217089857Sobrien@end table 217189857Sobrien 217289857Sobrien@c man end 217389857Sobrien 217489857Sobrien@ignore 217589857Sobrien@c man begin SEEALSO size 217689857Sobrienar(1), objdump(1), readelf(1), and the Info entries for @file{binutils}. 217789857Sobrien@c man end 217889857Sobrien@end ignore 217989857Sobrien 218089857Sobrien@node strings 218189857Sobrien@chapter strings 218289857Sobrien@kindex strings 218389857Sobrien@cindex listings strings 218489857Sobrien@cindex printing strings 218589857Sobrien@cindex strings, printing 218689857Sobrien 218789857Sobrien@c man title strings print the strings of printable characters in files. 218889857Sobrien 218989857Sobrien@smallexample 219089857Sobrien@c man begin SYNOPSIS strings 219189857Sobrienstrings [@option{-afov}] [@option{-}@var{min-len}] 219289857Sobrien [@option{-n} @var{min-len}] [@option{--bytes=}@var{min-len}] 219389857Sobrien [@option{-t} @var{radix}] [@option{--radix=}@var{radix}] 219489857Sobrien [@option{-e} @var{encoding}] [@option{--encoding=}@var{encoding}] 219589857Sobrien [@option{-}] [@option{--all}] [@option{--print-file-name}] 2196218822Sdim [@option{-T} @var{bfdname}] [@option{--target=}@var{bfdname}] 219789857Sobrien [@option{--help}] [@option{--version}] @var{file}@dots{} 219889857Sobrien@c man end 219989857Sobrien@end smallexample 220089857Sobrien 220189857Sobrien@c man begin DESCRIPTION strings 220289857Sobrien 220389857SobrienFor each @var{file} given, @sc{gnu} @command{strings} prints the printable 220489857Sobriencharacter sequences that are at least 4 characters long (or the number 220589857Sobriengiven with the options below) and are followed by an unprintable 220689857Sobriencharacter. By default, it only prints the strings from the initialized 220789857Sobrienand loaded sections of object files; for other types of files, it prints 220889857Sobrienthe strings from the whole file. 220989857Sobrien 221089857Sobrien@command{strings} is mainly useful for determining the contents of non-text 221189857Sobrienfiles. 221289857Sobrien 221389857Sobrien@c man end 221489857Sobrien 221589857Sobrien@c man begin OPTIONS strings 221689857Sobrien 221789857Sobrien@table @env 221889857Sobrien@item -a 221989857Sobrien@itemx --all 222089857Sobrien@itemx - 222189857SobrienDo not scan only the initialized and loaded sections of object files; 222289857Sobrienscan the whole files. 222389857Sobrien 222489857Sobrien@item -f 222589857Sobrien@itemx --print-file-name 222689857SobrienPrint the name of the file before each string. 222789857Sobrien 222889857Sobrien@item --help 222989857SobrienPrint a summary of the program usage on the standard output and exit. 223089857Sobrien 223189857Sobrien@item -@var{min-len} 223289857Sobrien@itemx -n @var{min-len} 223389857Sobrien@itemx --bytes=@var{min-len} 223489857SobrienPrint sequences of characters that are at least @var{min-len} characters 223589857Sobrienlong, instead of the default 4. 223689857Sobrien 223789857Sobrien@item -o 223889857SobrienLike @samp{-t o}. Some other versions of @command{strings} have @option{-o} 223989857Sobrienact like @samp{-t d} instead. Since we can not be compatible with both 224089857Sobrienways, we simply chose one. 224189857Sobrien 224289857Sobrien@item -t @var{radix} 224389857Sobrien@itemx --radix=@var{radix} 224489857SobrienPrint the offset within the file before each string. The single 224589857Sobriencharacter argument specifies the radix of the offset---@samp{o} for 224689857Sobrienoctal, @samp{x} for hexadecimal, or @samp{d} for decimal. 224789857Sobrien 224889857Sobrien@item -e @var{encoding} 224989857Sobrien@itemx --encoding=@var{encoding} 225089857SobrienSelect the character encoding of the strings that are to be found. 2251130561SobrienPossible values for @var{encoding} are: @samp{s} = single-7-bit-byte 2252130561Sobriencharacters (ASCII, ISO 8859, etc., default), @samp{S} = 2253130561Sobriensingle-8-bit-byte characters, @samp{b} = 16-bit bigendian, @samp{l} = 2254130561Sobrien16-bit littleendian, @samp{B} = 32-bit bigendian, @samp{L} = 32-bit 2255130561Sobrienlittleendian. Useful for finding wide character strings. 225689857Sobrien 2257218822Sdim@item -T @var{bfdname} 2258218822Sdim@itemx --target=@var{bfdname} 225989857Sobrien@cindex object code format 226089857SobrienSpecify an object code format other than your system's default format. 226189857Sobrien@xref{Target Selection}, for more information. 226289857Sobrien 226389857Sobrien@item -v 226489857Sobrien@itemx --version 226589857SobrienPrint the program version number on the standard output and exit. 226689857Sobrien@end table 226789857Sobrien 226889857Sobrien@c man end 226989857Sobrien 227089857Sobrien@ignore 227189857Sobrien@c man begin SEEALSO strings 227289857Sobrienar(1), nm(1), objdump(1), ranlib(1), readelf(1) 227389857Sobrienand the Info entries for @file{binutils}. 227489857Sobrien@c man end 227589857Sobrien@end ignore 227689857Sobrien 227789857Sobrien@node strip 227889857Sobrien@chapter strip 227989857Sobrien 228089857Sobrien@kindex strip 228189857Sobrien@cindex removing symbols 228289857Sobrien@cindex discarding symbols 228389857Sobrien@cindex symbols, discarding 228489857Sobrien 228589857Sobrien@c man title strip Discard symbols from object files. 228689857Sobrien 228789857Sobrien@smallexample 228889857Sobrien@c man begin SYNOPSIS strip 2289130561Sobrienstrip [@option{-F} @var{bfdname} |@option{--target=}@var{bfdname}] 2290130561Sobrien [@option{-I} @var{bfdname} |@option{--input-target=}@var{bfdname}] 2291130561Sobrien [@option{-O} @var{bfdname} |@option{--output-target=}@var{bfdname}] 2292130561Sobrien [@option{-s}|@option{--strip-all}] 2293130561Sobrien [@option{-S}|@option{-g}|@option{-d}|@option{--strip-debug}] 2294130561Sobrien [@option{-K} @var{symbolname} |@option{--keep-symbol=}@var{symbolname}] 2295130561Sobrien [@option{-N} @var{symbolname} |@option{--strip-symbol=}@var{symbolname}] 2296130561Sobrien [@option{-w}|@option{--wildcard}] 2297130561Sobrien [@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}] 2298130561Sobrien [@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}] 2299130561Sobrien [@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}] 2300218822Sdim [@option{--keep-file-symbols}] 2301130561Sobrien [@option{--only-keep-debug}] 2302130561Sobrien [@option{-v} |@option{--verbose}] [@option{-V}|@option{--version}] 2303130561Sobrien [@option{--help}] [@option{--info}] 230489857Sobrien @var{objfile}@dots{} 230589857Sobrien@c man end 230689857Sobrien@end smallexample 230789857Sobrien 230889857Sobrien@c man begin DESCRIPTION strip 230989857Sobrien 231089857Sobrien@sc{gnu} @command{strip} discards all symbols from object files 231189857Sobrien@var{objfile}. The list of object files may include archives. 231289857SobrienAt least one object file must be given. 231389857Sobrien 231489857Sobrien@command{strip} modifies the files named in its argument, 231589857Sobrienrather than writing modified copies under different names. 231689857Sobrien 231789857Sobrien@c man end 231889857Sobrien 231989857Sobrien@c man begin OPTIONS strip 232089857Sobrien 232189857Sobrien@table @env 232289857Sobrien@item -F @var{bfdname} 232389857Sobrien@itemx --target=@var{bfdname} 232489857SobrienTreat the original @var{objfile} as a file with the object 232589857Sobriencode format @var{bfdname}, and rewrite it in the same format. 232689857Sobrien@xref{Target Selection}, for more information. 232789857Sobrien 232889857Sobrien@item --help 232989857SobrienShow a summary of the options to @command{strip} and exit. 233089857Sobrien 2331130561Sobrien@item --info 2332130561SobrienDisplay a list showing all architectures and object formats available. 2333130561Sobrien 2334130561Sobrien@item -I @var{bfdname} 233589857Sobrien@itemx --input-target=@var{bfdname} 233689857SobrienTreat the original @var{objfile} as a file with the object 233789857Sobriencode format @var{bfdname}. 233889857Sobrien@xref{Target Selection}, for more information. 233989857Sobrien 234089857Sobrien@item -O @var{bfdname} 234189857Sobrien@itemx --output-target=@var{bfdname} 234289857SobrienReplace @var{objfile} with a file in the output format @var{bfdname}. 234389857Sobrien@xref{Target Selection}, for more information. 234489857Sobrien 234589857Sobrien@item -R @var{sectionname} 234689857Sobrien@itemx --remove-section=@var{sectionname} 234789857SobrienRemove any section named @var{sectionname} from the output file. This 234889857Sobrienoption may be given more than once. Note that using this option 234989857Sobrieninappropriately may make the output file unusable. 235089857Sobrien 235189857Sobrien@item -s 235289857Sobrien@itemx --strip-all 235389857SobrienRemove all symbols. 235489857Sobrien 235589857Sobrien@item -g 235689857Sobrien@itemx -S 235789857Sobrien@itemx -d 235889857Sobrien@itemx --strip-debug 235989857SobrienRemove debugging symbols only. 236089857Sobrien 236189857Sobrien@item --strip-unneeded 236289857SobrienRemove all symbols that are not needed for relocation processing. 236389857Sobrien 236489857Sobrien@item -K @var{symbolname} 236589857Sobrien@itemx --keep-symbol=@var{symbolname} 2366218822SdimWhen stripping symbols, keep symbol @var{symbolname} even if it would 2367218822Sdimnormally be stripped. This option may be given more than once. 236889857Sobrien 236989857Sobrien@item -N @var{symbolname} 237089857Sobrien@itemx --strip-symbol=@var{symbolname} 237189857SobrienRemove symbol @var{symbolname} from the source file. This option may be 237289857Sobriengiven more than once, and may be combined with strip options other than 237389857Sobrien@option{-K}. 237489857Sobrien 237589857Sobrien@item -o @var{file} 237689857SobrienPut the stripped output in @var{file}, rather than replacing the 237789857Sobrienexisting file. When this argument is used, only one @var{objfile} 237889857Sobrienargument may be specified. 237989857Sobrien 238089857Sobrien@item -p 238189857Sobrien@itemx --preserve-dates 238289857SobrienPreserve the access and modification dates of the file. 238389857Sobrien 2384130561Sobrien@item -w 2385130561Sobrien@itemx --wildcard 2386130561SobrienPermit regular expressions in @var{symbolname}s used in other command 2387130561Sobrienline options. The question mark (?), asterisk (*), backslash (\) and 2388130561Sobriensquare brackets ([]) operators can be used anywhere in the symbol 2389130561Sobrienname. If the first character of the symbol name is the exclamation 2390130561Sobrienpoint (!) then the sense of the switch is reversed for that symbol. 2391130561SobrienFor example: 2392130561Sobrien 2393130561Sobrien@smallexample 2394130561Sobrien -w -K !foo -K fo* 2395130561Sobrien@end smallexample 2396130561Sobrien 2397130561Sobrienwould cause strip to only keep symbols that start with the letters 2398130561Sobrien``fo'', but to discard the symbol ``foo''. 2399130561Sobrien 240089857Sobrien@item -x 240189857Sobrien@itemx --discard-all 240289857SobrienRemove non-global symbols. 240389857Sobrien 240489857Sobrien@item -X 240589857Sobrien@itemx --discard-locals 240689857SobrienRemove compiler-generated local symbols. 240789857Sobrien(These usually start with @samp{L} or @samp{.}.) 240889857Sobrien 2409218822Sdim@item --keep-file-symbols 2410218822SdimWhen stripping a file, perhaps with @option{--strip-debug} or 2411218822Sdim@option{--strip-unneeded}, retain any symbols specifying source file names, 2412218822Sdimwhich would otherwise get stripped. 2413218822Sdim 2414130561Sobrien@item --only-keep-debug 2415218822SdimStrip a file, removing contents of any sections that would not be 2416218822Sdimstripped by @option{--strip-debug} and leaving the debugging sections 2417218822Sdimintact. In ELF files, this preserves all note sections in the output. 2418130561Sobrien 2419130561SobrienThe intention is that this option will be used in conjunction with 2420130561Sobrien@option{--add-gnu-debuglink} to create a two part executable. One a 2421130561Sobrienstripped binary which will occupy less space in RAM and in a 2422130561Sobriendistribution and the second a debugging information file which is only 2423130561Sobrienneeded if debugging abilities are required. The suggested procedure 2424130561Sobriento create these files is as follows: 2425130561Sobrien 2426130561Sobrien@enumerate 2427130561Sobrien@item Link the executable as normal. Assuming that is is called 2428130561Sobrien@code{foo} then... 2429130561Sobrien@item Run @code{objcopy --only-keep-debug foo foo.dbg} to 2430130561Sobriencreate a file containing the debugging info. 2431130561Sobrien@item Run @code{objcopy --strip-debug foo} to create a 2432130561Sobrienstripped executable. 2433130561Sobrien@item Run @code{objcopy --add-gnu-debuglink=foo.dbg foo} 2434130561Sobriento add a link to the debugging info into the stripped executable. 2435130561Sobrien@end enumerate 2436130561Sobrien 2437130561SobrienNote - the choice of @code{.dbg} as an extension for the debug info 2438130561Sobrienfile is arbitrary. Also the @code{--only-keep-debug} step is 2439130561Sobrienoptional. You could instead do this: 2440130561Sobrien 2441130561Sobrien@enumerate 2442130561Sobrien@item Link the executable as normal. 2443130561Sobrien@item Copy @code{foo} to @code{foo.full} 2444130561Sobrien@item Run @code{strip --strip-debug foo} 2445130561Sobrien@item Run @code{objcopy --add-gnu-debuglink=foo.full foo} 2446130561Sobrien@end enumerate 2447130561Sobrien 2448130561Sobrienie the file pointed to by the @option{--add-gnu-debuglink} can be the 2449130561Sobrienfull executable. It does not have to be a file created by the 2450130561Sobrien@option{--only-keep-debug} switch. 2451130561Sobrien 2452218822SdimNote - this switch is only intended for use on fully linked files. It 2453218822Sdimdoes not make sense to use it on object files where the debugging 2454218822Sdiminformation may be incomplete. Besides the gnu_debuglink feature 2455218822Sdimcurrently only supports the presence of one filename containing 2456218822Sdimdebugging information, not multiple filenames on a one-per-object-file 2457218822Sdimbasis. 2458218822Sdim 245989857Sobrien@item -V 246089857Sobrien@itemx --version 246189857SobrienShow the version number for @command{strip}. 246289857Sobrien 246389857Sobrien@item -v 246489857Sobrien@itemx --verbose 246589857SobrienVerbose output: list all object files modified. In the case of 246689857Sobrienarchives, @samp{strip -v} lists all members of the archive. 246789857Sobrien@end table 246889857Sobrien 246989857Sobrien@c man end 247089857Sobrien 247189857Sobrien@ignore 247289857Sobrien@c man begin SEEALSO strip 247389857Sobrienthe Info entries for @file{binutils}. 247489857Sobrien@c man end 247589857Sobrien@end ignore 247689857Sobrien 247789857Sobrien@node c++filt, addr2line, strip, Top 247889857Sobrien@chapter c++filt 247989857Sobrien 248089857Sobrien@kindex c++filt 248189857Sobrien@cindex demangling C++ symbols 248289857Sobrien 248389857Sobrien@c man title cxxfilt Demangle C++ and Java symbols. 248489857Sobrien 248589857Sobrien@smallexample 248689857Sobrien@c man begin SYNOPSIS cxxfilt 248789857Sobrienc++filt [@option{-_}|@option{--strip-underscores}] 248889857Sobrien [@option{-n}|@option{--no-strip-underscores}] 2489130561Sobrien [@option{-p}|@option{--no-params}] 2490218822Sdim [@option{-t}|@option{--types}] 2491218822Sdim [@option{-i}|@option{--no-verbose}] 249289857Sobrien [@option{-s} @var{format}|@option{--format=}@var{format}] 249389857Sobrien [@option{--help}] [@option{--version}] [@var{symbol}@dots{}] 249489857Sobrien@c man end 249589857Sobrien@end smallexample 249689857Sobrien 249789857Sobrien@c man begin DESCRIPTION cxxfilt 249889857Sobrien 249989857Sobrien@kindex cxxfilt 2500218822SdimThe C++ and Java languages provide function overloading, which means 2501218822Sdimthat you can write many functions with the same name, providing that 2502218822Sdimeach function takes parameters of different types. In order to be 2503218822Sdimable to distinguish these similarly named functions C++ and Java 2504218822Sdimencode them into a low-level assembler name which uniquely identifies 2505218822Sdimeach different version. This process is known as @dfn{mangling}. The 2506218822Sdim@command{c++filt} 250789857Sobrien@footnote{MS-DOS does not allow @kbd{+} characters in file names, so on 2508218822SdimMS-DOS this program is named @command{CXXFILT}.} 250989857Sobrienprogram does the inverse mapping: it decodes (@dfn{demangles}) low-level 2510218822Sdimnames into user-level names so that they can be read. 251189857Sobrien 251289857SobrienEvery alphanumeric word (consisting of letters, digits, underscores, 2513218822Sdimdollars, or periods) seen in the input is a potential mangled name. 2514218822SdimIf the name decodes into a C++ name, the C++ name replaces the 2515218822Sdimlow-level name in the output, otherwise the original word is output. 2516218822SdimIn this way you can pass an entire assembler source file, containing 2517218822Sdimmangled names, through @command{c++filt} and see the same source file 2518218822Sdimcontaining demangled names. 251989857Sobrien 2520218822SdimYou can also use @command{c++filt} to decipher individual symbols by 2521218822Sdimpassing them on the command line: 252289857Sobrien 252389857Sobrien@example 252489857Sobrienc++filt @var{symbol} 252589857Sobrien@end example 252689857Sobrien 252789857SobrienIf no @var{symbol} arguments are given, @command{c++filt} reads symbol 2528218822Sdimnames from the standard input instead. All the results are printed on 2529218822Sdimthe standard output. The difference between reading names from the 2530218822Sdimcommand line versus reading names from the standard input is that 2531218822Sdimcommand line arguments are expected to be just mangled names and no 2532218822Sdimchecking is performed to separate them from surrounding text. Thus 2533218822Sdimfor example: 253489857Sobrien 2535218822Sdim@smallexample 2536218822Sdimc++filt -n _Z1fv 2537218822Sdim@end smallexample 2538218822Sdim 2539218822Sdimwill work and demangle the name to ``f()'' whereas: 2540218822Sdim 2541218822Sdim@smallexample 2542218822Sdimc++filt -n _Z1fv, 2543218822Sdim@end smallexample 2544218822Sdim 2545218822Sdimwill not work. (Note the extra comma at the end of the mangled 2546218822Sdimname which makes it invalid). This command however will work: 2547218822Sdim 2548218822Sdim@smallexample 2549218822Sdimecho _Z1fv, | c++filt -n 2550218822Sdim@end smallexample 2551218822Sdim 2552218822Sdimand will display ``f(),'' ie the demangled name followed by a 2553218822Sdimtrailing comma. This behaviour is because when the names are read 2554218822Sdimfrom the standard input it is expected that they might be part of an 2555218822Sdimassembler source file where there might be extra, extraneous 2556218822Sdimcharacters trailing after a mangled name. eg: 2557218822Sdim 2558218822Sdim@smallexample 2559218822Sdim .type _Z1fv, @@function 2560218822Sdim@end smallexample 2561218822Sdim 256289857Sobrien@c man end 256389857Sobrien 256489857Sobrien@c man begin OPTIONS cxxfilt 256589857Sobrien 256689857Sobrien@table @env 256789857Sobrien@item -_ 256889857Sobrien@itemx --strip-underscores 256989857SobrienOn some systems, both the C and C++ compilers put an underscore in front 257089857Sobrienof every name. For example, the C name @code{foo} gets the low-level 257189857Sobrienname @code{_foo}. This option removes the initial underscore. Whether 257289857Sobrien@command{c++filt} removes the underscore by default is target dependent. 257389857Sobrien 257489857Sobrien@item -j 257589857Sobrien@itemx --java 257689857SobrienPrints demangled names using Java syntax. The default is to use C++ 257789857Sobriensyntax. 257889857Sobrien 257989857Sobrien@item -n 258089857Sobrien@itemx --no-strip-underscores 258189857SobrienDo not remove the initial underscore. 258289857Sobrien 2583130561Sobrien@item -p 2584130561Sobrien@itemx --no-params 2585130561SobrienWhen demangling the name of a function, do not display the types of 2586130561Sobrienthe function's parameters. 2587130561Sobrien 2588218822Sdim@item -t 2589218822Sdim@itemx --types 2590218822SdimAttempt to demangle types as well as function names. This is disabled 2591218822Sdimby default since mangled types are normally only used internally in 2592218822Sdimthe compiler, and they can be confused with non-mangled names. eg 2593218822Sdima function called ``a'' treated as a mangled type name would be 2594218822Sdimdemangled to ``signed char''. 2595218822Sdim 2596218822Sdim@item -i 2597218822Sdim@itemx --no-verbose 2598218822SdimDo not include implementation details (if any) in the demangled 2599218822Sdimoutput. 2600218822Sdim 260189857Sobrien@item -s @var{format} 260289857Sobrien@itemx --format=@var{format} 2603130561Sobrien@command{c++filt} can decode various methods of mangling, used by 2604130561Sobriendifferent compilers. The argument to this option selects which 260589857Sobrienmethod it uses: 260689857Sobrien 260789857Sobrien@table @code 2608130561Sobrien@item auto 2609130561SobrienAutomatic selection based on executable (the default method) 261089857Sobrien@item gnu 2611130561Sobrienthe one used by the @sc{gnu} C++ compiler (g++) 261289857Sobrien@item lucid 2613130561Sobrienthe one used by the Lucid compiler (lcc) 261489857Sobrien@item arm 261589857Sobrienthe one specified by the C++ Annotated Reference Manual 261689857Sobrien@item hp 2617130561Sobrienthe one used by the HP compiler (aCC) 261889857Sobrien@item edg 261989857Sobrienthe one used by the EDG compiler 2620130561Sobrien@item gnu-v3 2621130561Sobrienthe one used by the @sc{gnu} C++ compiler (g++) with the V3 ABI. 2622130561Sobrien@item java 2623130561Sobrienthe one used by the @sc{gnu} Java compiler (gcj) 2624130561Sobrien@item gnat 2625130561Sobrienthe one used by the @sc{gnu} Ada compiler (GNAT). 262689857Sobrien@end table 262789857Sobrien 262889857Sobrien@item --help 262989857SobrienPrint a summary of the options to @command{c++filt} and exit. 263089857Sobrien 263189857Sobrien@item --version 263289857SobrienPrint the version number of @command{c++filt} and exit. 263389857Sobrien@end table 263489857Sobrien 263589857Sobrien@c man end 263689857Sobrien 263789857Sobrien@ignore 263889857Sobrien@c man begin SEEALSO cxxfilt 263989857Sobrienthe Info entries for @file{binutils}. 264089857Sobrien@c man end 264189857Sobrien@end ignore 264289857Sobrien 264389857Sobrien@quotation 264489857Sobrien@emph{Warning:} @command{c++filt} is a new utility, and the details of its 264589857Sobrienuser interface are subject to change in future releases. In particular, 2646218822Sdima command-line option may be required in the future to decode a name 2647218822Sdimpassed as an argument on the command line; in other words, 264889857Sobrien 264989857Sobrien@example 265089857Sobrienc++filt @var{symbol} 265189857Sobrien@end example 265289857Sobrien 265389857Sobrien@noindent 265489857Sobrienmay in a future release become 265589857Sobrien 265689857Sobrien@example 265789857Sobrienc++filt @var{option} @var{symbol} 265889857Sobrien@end example 265989857Sobrien@end quotation 266089857Sobrien 266189857Sobrien@node addr2line 266289857Sobrien@chapter addr2line 266389857Sobrien 266489857Sobrien@kindex addr2line 266589857Sobrien@cindex address to file name and line number 266689857Sobrien 266789857Sobrien@c man title addr2line convert addresses into file names and line numbers. 266889857Sobrien 266989857Sobrien@smallexample 267089857Sobrien@c man begin SYNOPSIS addr2line 267189857Sobrienaddr2line [@option{-b} @var{bfdname}|@option{--target=}@var{bfdname}] 2672104834Sobrien [@option{-C}|@option{--demangle}[=@var{style}]] 267389857Sobrien [@option{-e} @var{filename}|@option{--exe=}@var{filename}] 267489857Sobrien [@option{-f}|@option{--functions}] [@option{-s}|@option{--basename}] 2675218822Sdim [@option{-i}|@option{--inlines}] 2676218822Sdim [@option{-j}|@option{--section=}@var{name}] 267789857Sobrien [@option{-H}|@option{--help}] [@option{-V}|@option{--version}] 267889857Sobrien [addr addr @dots{}] 267989857Sobrien@c man end 268089857Sobrien@end smallexample 268189857Sobrien 268289857Sobrien@c man begin DESCRIPTION addr2line 268389857Sobrien 2684218822Sdim@command{addr2line} translates addresses into file names and line numbers. 2685218822SdimGiven an address in an executable or an offset in a section of a relocatable 2686218822Sdimobject, it uses the debugging information to figure out which file name and 2687218822Sdimline number are associated with it. 268889857Sobrien 2689218822SdimThe executable or relocatable object to use is specified with the @option{-e} 2690218822Sdimoption. The default is the file @file{a.out}. The section in the relocatable 2691218822Sdimobject to use is specified with the @option{-j} option. 269289857Sobrien 269389857Sobrien@command{addr2line} has two modes of operation. 269489857Sobrien 269589857SobrienIn the first, hexadecimal addresses are specified on the command line, 269689857Sobrienand @command{addr2line} displays the file name and line number for each 269789857Sobrienaddress. 269889857Sobrien 269989857SobrienIn the second, @command{addr2line} reads hexadecimal addresses from 270089857Sobrienstandard input, and prints the file name and line number for each 270189857Sobrienaddress on standard output. In this mode, @command{addr2line} may be used 270289857Sobrienin a pipe to convert dynamically chosen addresses. 270389857Sobrien 270489857SobrienThe format of the output is @samp{FILENAME:LINENO}. The file name and 270589857Sobrienline number for each address is printed on a separate line. If the 270689857Sobrien@command{-f} option is used, then each @samp{FILENAME:LINENO} line is 270789857Sobrienpreceded by a @samp{FUNCTIONNAME} line which is the name of the function 270889857Sobriencontaining the address. 270989857Sobrien 271089857SobrienIf the file name or function name can not be determined, 271189857Sobrien@command{addr2line} will print two question marks in their place. If the 271289857Sobrienline number can not be determined, @command{addr2line} will print 0. 271389857Sobrien 271489857Sobrien@c man end 271589857Sobrien 271689857Sobrien@c man begin OPTIONS addr2line 271789857Sobrien 271889857SobrienThe long and short forms of options, shown here as alternatives, are 271989857Sobrienequivalent. 272089857Sobrien 272189857Sobrien@table @env 272289857Sobrien@item -b @var{bfdname} 272389857Sobrien@itemx --target=@var{bfdname} 272489857Sobrien@cindex object code format 272589857SobrienSpecify that the object-code format for the object files is 272689857Sobrien@var{bfdname}. 272789857Sobrien 272889857Sobrien@item -C 272989857Sobrien@itemx --demangle[=@var{style}] 273089857Sobrien@cindex demangling in objdump 273189857SobrienDecode (@dfn{demangle}) low-level symbol names into user-level names. 273289857SobrienBesides removing any initial underscore prepended by the system, this 273389857Sobrienmakes C++ function names readable. Different compilers have different 2734218822Sdimmangling styles. The optional demangling style argument can be used to 2735218822Sdimchoose an appropriate demangling style for your compiler. @xref{c++filt}, 273689857Sobrienfor more information on demangling. 273789857Sobrien 273889857Sobrien@item -e @var{filename} 273989857Sobrien@itemx --exe=@var{filename} 274089857SobrienSpecify the name of the executable for which addresses should be 274189857Sobrientranslated. The default file is @file{a.out}. 274289857Sobrien 274389857Sobrien@item -f 274489857Sobrien@itemx --functions 274589857SobrienDisplay function names as well as file and line number information. 274689857Sobrien 274789857Sobrien@item -s 274889857Sobrien@itemx --basenames 274989857SobrienDisplay only the base of each file name. 2750218822Sdim 2751218822Sdim@item -i 2752218822Sdim@itemx --inlines 2753218822SdimIf the address belongs to a function that was inlined, the source 2754218822Sdiminformation for all enclosing scopes back to the first non-inlined 2755218822Sdimfunction will also be printed. For example, if @code{main} inlines 2756218822Sdim@code{callee1} which inlines @code{callee2}, and address is from 2757218822Sdim@code{callee2}, the source information for @code{callee1} and @code{main} 2758218822Sdimwill also be printed. 2759218822Sdim 2760218822Sdim@item -j 2761218822Sdim@itemx --section 2762218822SdimRead offsets relative to the specified section instead of absolute addresses. 276389857Sobrien@end table 276489857Sobrien 276589857Sobrien@c man end 276689857Sobrien 276789857Sobrien@ignore 276889857Sobrien@c man begin SEEALSO addr2line 276989857SobrienInfo entries for @file{binutils}. 277089857Sobrien@c man end 277189857Sobrien@end ignore 277289857Sobrien 277389857Sobrien@node nlmconv 277489857Sobrien@chapter nlmconv 277589857Sobrien 277689857Sobrien@command{nlmconv} converts a relocatable object file into a NetWare 277789857SobrienLoadable Module. 277889857Sobrien 277989857Sobrien@ignore 278089857Sobrien@command{nlmconv} currently works with @samp{i386} object 278189857Sobrienfiles in @code{coff}, @sc{elf}, or @code{a.out} format, and @sc{SPARC} 278289857Sobrienobject files in @sc{elf}, or @code{a.out} format@footnote{ 278389857Sobrien@command{nlmconv} should work with any @samp{i386} or @sc{sparc} object 278489857Sobrienformat in the Binary File Descriptor library. It has only been tested 278589857Sobrienwith the above formats.}. 278689857Sobrien@end ignore 278789857Sobrien 278889857Sobrien@quotation 278989857Sobrien@emph{Warning:} @command{nlmconv} is not always built as part of the binary 279089857Sobrienutilities, since it is only useful for NLM targets. 279189857Sobrien@end quotation 279289857Sobrien 279389857Sobrien@c man title nlmconv converts object code into an NLM. 279489857Sobrien 279589857Sobrien@smallexample 279689857Sobrien@c man begin SYNOPSIS nlmconv 279789857Sobriennlmconv [@option{-I} @var{bfdname}|@option{--input-target=}@var{bfdname}] 279889857Sobrien [@option{-O} @var{bfdname}|@option{--output-target=}@var{bfdname}] 279989857Sobrien [@option{-T} @var{headerfile}|@option{--header-file=}@var{headerfile}] 280089857Sobrien [@option{-d}|@option{--debug}] [@option{-l} @var{linker}|@option{--linker=}@var{linker}] 280189857Sobrien [@option{-h}|@option{--help}] [@option{-V}|@option{--version}] 280289857Sobrien @var{infile} @var{outfile} 280389857Sobrien@c man end 280489857Sobrien@end smallexample 280589857Sobrien 280689857Sobrien@c man begin DESCRIPTION nlmconv 280789857Sobrien 280889857Sobrien@command{nlmconv} converts the relocatable @samp{i386} object file 280989857Sobrien@var{infile} into the NetWare Loadable Module @var{outfile}, optionally 281089857Sobrienreading @var{headerfile} for NLM header information. For instructions 281189857Sobrienon writing the NLM command file language used in header files, see the 281289857Sobrien@samp{linkers} section, @samp{NLMLINK} in particular, of the @cite{NLM 281389857SobrienDevelopment and Tools Overview}, which is part of the NLM Software 281489857SobrienDeveloper's Kit (``NLM SDK''), available from Novell, Inc. 281589857Sobrien@command{nlmconv} uses the @sc{gnu} Binary File Descriptor library to read 281689857Sobrien@var{infile}; 281789857Sobrien@ifclear man 281889857Sobriensee @ref{BFD,,BFD,ld.info,Using LD}, for more information. 281989857Sobrien@end ifclear 282089857Sobrien 282189857Sobrien@command{nlmconv} can perform a link step. In other words, you can list 282289857Sobrienmore than one object file for input if you list them in the definitions 282389857Sobrienfile (rather than simply specifying one input file on the command line). 282489857SobrienIn this case, @command{nlmconv} calls the linker for you. 282589857Sobrien 282689857Sobrien@c man end 282789857Sobrien 282889857Sobrien@c man begin OPTIONS nlmconv 282989857Sobrien 283089857Sobrien@table @env 283189857Sobrien@item -I @var{bfdname} 283289857Sobrien@itemx --input-target=@var{bfdname} 283389857SobrienObject format of the input file. @command{nlmconv} can usually determine 283489857Sobrienthe format of a given file (so no default is necessary). 283589857Sobrien@xref{Target Selection}, for more information. 283689857Sobrien 283789857Sobrien@item -O @var{bfdname} 283889857Sobrien@itemx --output-target=@var{bfdname} 283989857SobrienObject format of the output file. @command{nlmconv} infers the output 284089857Sobrienformat based on the input format, e.g. for a @samp{i386} input file the 284189857Sobrienoutput format is @samp{nlm32-i386}. 284289857Sobrien@xref{Target Selection}, for more information. 284389857Sobrien 284489857Sobrien@item -T @var{headerfile} 284589857Sobrien@itemx --header-file=@var{headerfile} 284689857SobrienReads @var{headerfile} for NLM header information. For instructions on 284789857Sobrienwriting the NLM command file language used in header files, see@ see the 284889857Sobrien@samp{linkers} section, of the @cite{NLM Development and Tools 284989857SobrienOverview}, which is part of the NLM Software Developer's Kit, available 285089857Sobrienfrom Novell, Inc. 285189857Sobrien 285289857Sobrien@item -d 285389857Sobrien@itemx --debug 285489857SobrienDisplays (on standard error) the linker command line used by @command{nlmconv}. 285589857Sobrien 285689857Sobrien@item -l @var{linker} 285789857Sobrien@itemx --linker=@var{linker} 285889857SobrienUse @var{linker} for any linking. @var{linker} can be an absolute or a 285989857Sobrienrelative pathname. 286089857Sobrien 286189857Sobrien@item -h 286289857Sobrien@itemx --help 286389857SobrienPrints a usage summary. 286489857Sobrien 286589857Sobrien@item -V 286689857Sobrien@itemx --version 286789857SobrienPrints the version number for @command{nlmconv}. 286889857Sobrien@end table 286989857Sobrien 287089857Sobrien@c man end 287189857Sobrien 287289857Sobrien@ignore 287389857Sobrien@c man begin SEEALSO nlmconv 287489857Sobrienthe Info entries for @file{binutils}. 287589857Sobrien@c man end 287689857Sobrien@end ignore 287789857Sobrien 2878218822Sdim@node windmc 2879218822Sdim@chapter windmc 2880218822Sdim 2881218822Sdim@command{windmc} may be used to generator Windows message resources. 2882218822Sdim 2883218822Sdim@quotation 2884218822Sdim@emph{Warning:} @command{windmc} is not always built as part of the binary 2885218822Sdimutilities, since it is only useful for Windows targets. 2886218822Sdim@end quotation 2887218822Sdim 2888218822Sdim@c man title windmc generates Windows message resources. 2889218822Sdim 2890218822Sdim@smallexample 2891218822Sdim@c man begin SYNOPSIS windres 2892218822Sdimwindmc [options] input-file 2893218822Sdim@c man end 2894218822Sdim@end smallexample 2895218822Sdim 2896218822Sdim@c man begin DESCRIPTION windmc 2897218822Sdim 2898218822Sdim@command{windmc} reads message definitions from an input file (.mc) and 2899218822Sdimtranslate them into a set of output files. The output files may be of 2900218822Sdimfour kinds: 2901218822Sdim 2902218822Sdim@table @code 2903218822Sdim@item h 2904218822SdimA C header file containing the message definitions. 2905218822Sdim 2906218822Sdim@item rc 2907218822SdimA resource file compilable by the @command{windres} tool. 2908218822Sdim 2909218822Sdim@item bin 2910218822SdimOne or more binary files containing the resource data for a specific 2911218822Sdimmessage language. 2912218822Sdim 2913218822Sdim@item dbg 2914218822SdimA C include file that maps message id's to their symbolic name. 2915218822Sdim@end table 2916218822Sdim 2917218822SdimThe exact description of these different formats is available in 2918218822Sdimdocumentation from Microsoft. 2919218822Sdim 2920218822SdimWhen @command{windmc} converts from the @code{mc} format to the @code{bin} 2921218822Sdimformat, @code{rc}, @code{h}, and optional @code{dbg} it is acting like the 2922218822SdimWindows Message Compiler. 2923218822Sdim 2924218822Sdim@c man end 2925218822Sdim 2926218822Sdim@c man begin OPTIONS windmc 2927218822Sdim 2928218822Sdim@table @env 2929218822Sdim@item -a 2930218822Sdim@itemx --ascii_in 2931218822SdimSpecifies that the input file specified is ANSI. This is the default 2932218822Sdimbehaviour. 2933218822Sdim 2934218822Sdim@item -A 2935218822Sdim@itemx --ascii_out 2936218822SdimSpecifies that messages in the output @code{bin} files should be in ANSI 2937218822Sdimformat. 2938218822Sdim 2939218822Sdim@item -b 2940218822Sdim@itemx --binprefix 2941218822SdimSpecifies that @code{bin} filenames should have to be prefixed by the 2942218822Sdimbasename of the source file. 2943218822Sdim 2944218822Sdim@item -c 2945218822Sdim@itemx --customflag 2946218822SdimSets the customer bit in all message id's. 2947218822Sdim 2948218822Sdim@item -C @var{codepage} 2949218822Sdim@itemx --codepage_in @var{codepage} 2950218822SdimSets the default codepage to be used to convert input file to UTF16. The 2951218822Sdimdefault is ocdepage 1252. 2952218822Sdim 2953218822Sdim@item -d 2954218822Sdim@itemx --decimal_values 2955218822SdimOutputs the constants in the header file in decimal. Default is using 2956218822Sdimhexadecimal output. 2957218822Sdim 2958218822Sdim@item -e @var{ext} 2959218822Sdim@itemx --extension @var{ext} 2960218822SdimThe extension for the header file. The default is .h extension. 2961218822Sdim 2962218822Sdim@item -F @var{target} 2963218822Sdim@itemx --target @var{target} 2964218822SdimSpecify the BFD format to use for a bin file as output. This 2965218822Sdimis a BFD target name; you can use the @option{--help} option to see a list 2966218822Sdimof supported targets. Normally @command{windmc} will use the default 2967218822Sdimformat, which is the first one listed by the @option{--help} option. 2968218822Sdim@ifclear man 2969218822Sdim@ref{Target Selection}. 2970218822Sdim@end ifclear 2971218822Sdim 2972218822Sdim@item -h @var{path} 2973218822Sdim@itemx --headerdir @var{path} 2974218822SdimThe target directory of the generated header file. The default is the 2975218822Sdimcurrent directory. 2976218822Sdim 2977218822Sdim@item -H 2978218822Sdim@itemx --help 2979218822SdimDisplays a list of command line options and then exits. 2980218822Sdim 2981218822Sdim@item -m @var{characters} 2982218822Sdim@itemx --maxlength @var{characters} 2983218822SdimInstructs @command{windmc} to generate a warning if the length 2984218822Sdimof any message exceeds the number specified. 2985218822Sdim 2986218822Sdim@item -n 2987218822Sdim@itemx --nullterminate 2988218822SdimTerminate message text in @code{bin} files by zero. By default they are 2989218822Sdimterminated by CR/LF. 2990218822Sdim 2991218822Sdim@item -o 2992218822Sdim@itemx --hresult_use 2993218822SdimNot yet implemented. Instructs @code{windmc} to generate an OLE2 header 2994218822Sdimfile, using HRESULT definitions. Status codes are used if the flag is not 2995218822Sdimspecified. 2996218822Sdim 2997218822Sdim@item -O @var{codepage} 2998218822Sdim@itemx --codepage_out @var{codepage} 2999218822SdimSets the default codepage to be used to output text files. The default 3000218822Sdimis ocdepage 1252. 3001218822Sdim 3002218822Sdim@item -r @var{path} 3003218822Sdim@itemx --rcdir @var{path} 3004218822SdimThe target directory for the generated @code{rc} script and the generated 3005218822Sdim@code{bin} files that the resource compiler script includes. The default 3006218822Sdimis the current directory. 3007218822Sdim 3008218822Sdim@item -u 3009218822Sdim@itemx --unicode_in 3010218822SdimSpecifies that the input file is UTF16. 3011218822Sdim 3012218822Sdim@item -U 3013218822Sdim@itemx --unicode_out 3014218822SdimSpecifies that messages in the output @code{bin} file should be in UTF16 3015218822Sdimformat. This is the default behaviour. 3016218822Sdim 3017218822Sdim@item -v 3018218822Sdim@item --verbose 3019218822SdimEnable verbose mode. This tells you what the preprocessor is if you 3020218822Sdimdidn't specify one. 3021218822Sdim 3022218822Sdim@item -V 3023218822Sdim@item --version 3024218822SdimPrints the version number for @command{windres}. 3025218822Sdim 3026218822Sdim@item -x @var{path} 3027218822Sdim@itemx --xdgb @var{path} 3028218822SdimThe path of the @code{dbg} C include file that maps message id's to the 3029218822Sdimsymbolic name. No such file is generated without specifying the switch. 3030218822Sdim@end table 3031218822Sdim 3032218822Sdim@c man end 3033218822Sdim 3034218822Sdim@ignore 3035218822Sdim@c man begin SEEALSO windmc 3036218822Sdimthe Info entries for @file{binutils}. 3037218822Sdim@c man end 3038218822Sdim@end ignore 3039218822Sdim 304089857Sobrien@node windres 304189857Sobrien@chapter windres 304289857Sobrien 304389857Sobrien@command{windres} may be used to manipulate Windows resources. 304489857Sobrien 304589857Sobrien@quotation 304689857Sobrien@emph{Warning:} @command{windres} is not always built as part of the binary 304789857Sobrienutilities, since it is only useful for Windows targets. 304889857Sobrien@end quotation 304989857Sobrien 305089857Sobrien@c man title windres manipulate Windows resources. 305189857Sobrien 305289857Sobrien@smallexample 305389857Sobrien@c man begin SYNOPSIS windres 305489857Sobrienwindres [options] [input-file] [output-file] 305589857Sobrien@c man end 305689857Sobrien@end smallexample 305789857Sobrien 305889857Sobrien@c man begin DESCRIPTION windres 305989857Sobrien 306089857Sobrien@command{windres} reads resources from an input file and copies them into 306189857Sobrienan output file. Either file may be in one of three formats: 306289857Sobrien 306389857Sobrien@table @code 306489857Sobrien@item rc 306589857SobrienA text format read by the Resource Compiler. 306689857Sobrien 306789857Sobrien@item res 306889857SobrienA binary format generated by the Resource Compiler. 306989857Sobrien 307089857Sobrien@item coff 307189857SobrienA COFF object or executable. 307289857Sobrien@end table 307389857Sobrien 307489857SobrienThe exact description of these different formats is available in 307589857Sobriendocumentation from Microsoft. 307689857Sobrien 307789857SobrienWhen @command{windres} converts from the @code{rc} format to the @code{res} 307889857Sobrienformat, it is acting like the Windows Resource Compiler. When 307989857Sobrien@command{windres} converts from the @code{res} format to the @code{coff} 308089857Sobrienformat, it is acting like the Windows @code{CVTRES} program. 308189857Sobrien 308289857SobrienWhen @command{windres} generates an @code{rc} file, the output is similar 308389857Sobrienbut not identical to the format expected for the input. When an input 308489857Sobrien@code{rc} file refers to an external filename, an output @code{rc} file 308589857Sobrienwill instead include the file contents. 308689857Sobrien 308789857SobrienIf the input or output format is not specified, @command{windres} will 308889857Sobrienguess based on the file name, or, for the input file, the file contents. 308989857SobrienA file with an extension of @file{.rc} will be treated as an @code{rc} 309089857Sobrienfile, a file with an extension of @file{.res} will be treated as a 309189857Sobrien@code{res} file, and a file with an extension of @file{.o} or 309289857Sobrien@file{.exe} will be treated as a @code{coff} file. 309389857Sobrien 309489857SobrienIf no output file is specified, @command{windres} will print the resources 309589857Sobrienin @code{rc} format to standard output. 309689857Sobrien 309789857SobrienThe normal use is for you to write an @code{rc} file, use @command{windres} 309889857Sobriento convert it to a COFF object file, and then link the COFF file into 309989857Sobrienyour application. This will make the resources described in the 310089857Sobrien@code{rc} file available to Windows. 310189857Sobrien 310289857Sobrien@c man end 310389857Sobrien 310489857Sobrien@c man begin OPTIONS windres 310589857Sobrien 310689857Sobrien@table @env 310789857Sobrien@item -i @var{filename} 310889857Sobrien@itemx --input @var{filename} 310989857SobrienThe name of the input file. If this option is not used, then 311089857Sobrien@command{windres} will use the first non-option argument as the input file 311189857Sobrienname. If there are no non-option arguments, then @command{windres} will 311289857Sobrienread from standard input. @command{windres} can not read a COFF file from 311389857Sobrienstandard input. 311489857Sobrien 311589857Sobrien@item -o @var{filename} 311689857Sobrien@itemx --output @var{filename} 311789857SobrienThe name of the output file. If this option is not used, then 311889857Sobrien@command{windres} will use the first non-option argument, after any used 311989857Sobrienfor the input file name, as the output file name. If there is no 312089857Sobriennon-option argument, then @command{windres} will write to standard output. 3121130561Sobrien@command{windres} can not write a COFF file to standard output. Note, 3122218822Sdimfor compatibility with @command{rc} the option @option{-fo} is also 3123130561Sobrienaccepted, but its use is not recommended. 312489857Sobrien 3125130561Sobrien@item -J @var{format} 312689857Sobrien@itemx --input-format @var{format} 312789857SobrienThe input format to read. @var{format} may be @samp{res}, @samp{rc}, or 312889857Sobrien@samp{coff}. If no input format is specified, @command{windres} will 312989857Sobrienguess, as described above. 313089857Sobrien 313189857Sobrien@item -O @var{format} 313289857Sobrien@itemx --output-format @var{format} 313389857SobrienThe output format to generate. @var{format} may be @samp{res}, 313489857Sobrien@samp{rc}, or @samp{coff}. If no output format is specified, 313589857Sobrien@command{windres} will guess, as described above. 313689857Sobrien 313789857Sobrien@item -F @var{target} 313889857Sobrien@itemx --target @var{target} 313989857SobrienSpecify the BFD format to use for a COFF file as input or output. This 314089857Sobrienis a BFD target name; you can use the @option{--help} option to see a list 314189857Sobrienof supported targets. Normally @command{windres} will use the default 314289857Sobrienformat, which is the first one listed by the @option{--help} option. 314389857Sobrien@ifclear man 314489857Sobrien@ref{Target Selection}. 314589857Sobrien@end ifclear 314689857Sobrien 314789857Sobrien@item --preprocessor @var{program} 314889857SobrienWhen @command{windres} reads an @code{rc} file, it runs it through the C 314989857Sobrienpreprocessor first. This option may be used to specify the preprocessor 315089857Sobriento use, including any leading arguments. The default preprocessor 315189857Sobrienargument is @code{gcc -E -xc-header -DRC_INVOKED}. 315289857Sobrien 3153130561Sobrien@item -I @var{directory} 3154130561Sobrien@itemx --include-dir @var{directory} 315589857SobrienSpecify an include directory to use when reading an @code{rc} file. 315689857Sobrien@command{windres} will pass this to the preprocessor as an @option{-I} 315789857Sobrienoption. @command{windres} will also search this directory when looking for 3158130561Sobrienfiles named in the @code{rc} file. If the argument passed to this command 3159218822Sdimmatches any of the supported @var{formats} (as described in the @option{-J} 3160130561Sobrienoption), it will issue a deprecation warning, and behave just like the 3161130561Sobrien@option{-J} option. New programs should not use this behaviour. If a 3162130561Sobriendirectory happens to match a @var{format}, simple prefix it with @samp{./} 3163130561Sobriento disable the backward compatibility. 316489857Sobrien 316589857Sobrien@item -D @var{target} 316689857Sobrien@itemx --define @var{sym}[=@var{val}] 316789857SobrienSpecify a @option{-D} option to pass to the preprocessor when reading an 316889857Sobrien@code{rc} file. 316989857Sobrien 3170130561Sobrien@item -U @var{target} 3171130561Sobrien@itemx --undefine @var{sym} 3172130561SobrienSpecify a @option{-U} option to pass to the preprocessor when reading an 3173130561Sobrien@code{rc} file. 3174130561Sobrien 3175130561Sobrien@item -r 3176130561SobrienIgnored for compatibility with rc. 3177130561Sobrien 317889857Sobrien@item -v 317989857SobrienEnable verbose mode. This tells you what the preprocessor is if you 318089857Sobriendidn't specify one. 318189857Sobrien 3182218822Sdim@item -c @var{val} 3183218822Sdim@item --codepage @var{val} 3184218822SdimSpecify the default codepage to use when reading an @code{rc} file. 3185218822Sdim@var{val} should be a hexadecimal prefixed by @samp{0x} or decimal 3186218822Sdimcodepage code. The valid range is from zero up to 0xffff, but the 3187218822Sdimvalidity of the codepage is host and configuration dependent. 3188218822Sdim 3189130561Sobrien@item -l @var{val} 319089857Sobrien@item --language @var{val} 319189857SobrienSpecify the default language to use when reading an @code{rc} file. 319289857Sobrien@var{val} should be a hexadecimal language code. The low eight bits are 319389857Sobrienthe language, and the high eight bits are the sublanguage. 319489857Sobrien 319589857Sobrien@item --use-temp-file 319689857SobrienUse a temporary file to instead of using popen to read the output of 3197218822Sdimthe preprocessor. Use this option if the popen implementation is buggy 3198218822Sdimon the host (eg., certain non-English language versions of Windows 95 and 319989857SobrienWindows 98 are known to have buggy popen where the output will instead 320089857Sobriengo the console). 320189857Sobrien 320289857Sobrien@item --no-use-temp-file 320389857SobrienUse popen, not a temporary file, to read the output of the preprocessor. 320489857SobrienThis is the default behaviour. 320589857Sobrien 3206130561Sobrien@item -h 320789857Sobrien@item --help 320889857SobrienPrints a usage summary. 320989857Sobrien 3210130561Sobrien@item -V 321189857Sobrien@item --version 321289857SobrienPrints the version number for @command{windres}. 321389857Sobrien 321489857Sobrien@item --yydebug 321589857SobrienIf @command{windres} is compiled with @code{YYDEBUG} defined as @code{1}, 321689857Sobrienthis will turn on parser debugging. 321789857Sobrien@end table 321889857Sobrien 321989857Sobrien@c man end 322089857Sobrien 322189857Sobrien@ignore 322289857Sobrien@c man begin SEEALSO windres 322389857Sobrienthe Info entries for @file{binutils}. 322489857Sobrien@c man end 322589857Sobrien@end ignore 322689857Sobrien 322789857Sobrien@node dlltool 3228218822Sdim@chapter dlltool 322989857Sobrien@cindex DLL 323089857Sobrien@kindex dlltool 323189857Sobrien 3232218822Sdim@command{dlltool} is used to create the files needed to create dynamic 3233218822Sdimlink libraries (DLLs) on systems which understand PE format image 3234218822Sdimfiles such as Windows. A DLL contains an export table which contains 3235218822Sdiminformation that the runtime loader needs to resolve references from a 3236218822Sdimreferencing program. 323789857Sobrien 3238218822SdimThe export table is generated by this program by reading in a 3239218822Sdim@file{.def} file or scanning the @file{.a} and @file{.o} files which 3240218822Sdimwill be in the DLL. A @file{.o} file can contain information in 3241218822Sdimspecial @samp{.drectve} sections with export information. 3242218822Sdim 324389857Sobrien@quotation 3244218822Sdim@emph{Note:} @command{dlltool} is not always built as part of the 3245218822Sdimbinary utilities, since it is only useful for those targets which 3246218822Sdimsupport DLLs. 324789857Sobrien@end quotation 324889857Sobrien 324989857Sobrien@c man title dlltool Create files needed to build and use DLLs. 325089857Sobrien 325189857Sobrien@smallexample 325289857Sobrien@c man begin SYNOPSIS dlltool 325389857Sobriendlltool [@option{-d}|@option{--input-def} @var{def-file-name}] 325489857Sobrien [@option{-b}|@option{--base-file} @var{base-file-name}] 325589857Sobrien [@option{-e}|@option{--output-exp} @var{exports-file-name}] 325689857Sobrien [@option{-z}|@option{--output-def} @var{def-file-name}] 3257218822Sdim [@option{-l}|@option{--output-lib} @var{library-file-name}] 325889857Sobrien [@option{--export-all-symbols}] [@option{--no-export-all-symbols}] 325989857Sobrien [@option{--exclude-symbols} @var{list}] 326089857Sobrien [@option{--no-default-excludes}] 326189857Sobrien [@option{-S}|@option{--as} @var{path-to-assembler}] [@option{-f}|@option{--as-flags} @var{options}] 326289857Sobrien [@option{-D}|@option{--dllname} @var{name}] [@option{-m}|@option{--machine} @var{machine}] 3263218822Sdim [@option{-a}|@option{--add-indirect}] 3264218822Sdim [@option{-U}|@option{--add-underscore}] [@option{--add-stdcall-underscore}] 3265218822Sdim [@option{-k}|@option{--kill-at}] [@option{-A}|@option{--add-stdcall-alias}] 3266218822Sdim [@option{-p}|@option{--ext-prefix-alias} @var{prefix}] 326789857Sobrien [@option{-x}|@option{--no-idata4}] [@option{-c}|@option{--no-idata5}] [@option{-i}|@option{--interwork}] 3268130561Sobrien [@option{-n}|@option{--nodelete}] [@option{-t}|@option{--temp-prefix} @var{prefix}] 3269218822Sdim [@option{-v}|@option{--verbose}] 327089857Sobrien [@option{-h}|@option{--help}] [@option{-V}|@option{--version}] 327189857Sobrien [object-file @dots{}] 327289857Sobrien@c man end 327389857Sobrien@end smallexample 327489857Sobrien 327589857Sobrien@c man begin DESCRIPTION dlltool 327689857Sobrien 327789857Sobrien@command{dlltool} reads its inputs, which can come from the @option{-d} and 327889857Sobrien@option{-b} options as well as object files specified on the command 327989857Sobrienline. It then processes these inputs and if the @option{-e} option has 328089857Sobrienbeen specified it creates a exports file. If the @option{-l} option 328189857Sobrienhas been specified it creates a library file and if the @option{-z} option 3282218822Sdimhas been specified it creates a def file. Any or all of the @option{-e}, 3283218822Sdim@option{-l} and @option{-z} options can be present in one invocation of 328489857Sobriendlltool. 328589857Sobrien 328689857SobrienWhen creating a DLL, along with the source for the DLL, it is necessary 328789857Sobriento have three other files. @command{dlltool} can help with the creation of 328889857Sobrienthese files. 328989857Sobrien 3290218822SdimThe first file is a @file{.def} file which specifies which functions are 329189857Sobrienexported from the DLL, which functions the DLL imports, and so on. This 329289857Sobrienis a text file and can be created by hand, or @command{dlltool} can be used 329389857Sobriento create it using the @option{-z} option. In this case @command{dlltool} 329489857Sobrienwill scan the object files specified on its command line looking for 329589857Sobrienthose functions which have been specially marked as being exported and 3296218822Sdimput entries for them in the @file{.def} file it creates. 329789857Sobrien 329889857SobrienIn order to mark a function as being exported from a DLL, it needs to 329989857Sobrienhave an @option{-export:<name_of_function>} entry in the @samp{.drectve} 330089857Sobriensection of the object file. This can be done in C by using the 330189857Sobrienasm() operator: 330289857Sobrien 330389857Sobrien@smallexample 3304218822Sdim asm (".section .drectve"); 330589857Sobrien asm (".ascii \"-export:my_func\""); 330689857Sobrien 330789857Sobrien int my_func (void) @{ @dots{} @} 330889857Sobrien@end smallexample 330989857Sobrien 331089857SobrienThe second file needed for DLL creation is an exports file. This file 331189857Sobrienis linked with the object files that make up the body of the DLL and it 331289857Sobrienhandles the interface between the DLL and the outside world. This is a 331389857Sobrienbinary file and it can be created by giving the @option{-e} option to 3314218822Sdim@command{dlltool} when it is creating or reading in a @file{.def} file. 331589857Sobrien 331689857SobrienThe third file needed for DLL creation is the library file that programs 331789857Sobrienwill link with in order to access the functions in the DLL. This file 331889857Sobriencan be created by giving the @option{-l} option to dlltool when it 3319218822Sdimis creating or reading in a @file{.def} file. 332089857Sobrien 332189857Sobrien@command{dlltool} builds the library file by hand, but it builds the 332289857Sobrienexports file by creating temporary files containing assembler statements 332389857Sobrienand then assembling these. The @option{-S} command line option can be 332489857Sobrienused to specify the path to the assembler that dlltool will use, 332589857Sobrienand the @option{-f} option can be used to pass specific flags to that 332689857Sobrienassembler. The @option{-n} can be used to prevent dlltool from deleting 332789857Sobrienthese temporary assembler files when it is done, and if @option{-n} is 332889857Sobrienspecified twice then this will prevent dlltool from deleting the 332989857Sobrientemporary object files it used to build the library. 333089857Sobrien 333189857SobrienHere is an example of creating a DLL from a source file @samp{dll.c} and 333289857Sobrienalso creating a program (from an object file called @samp{program.o}) 333389857Sobrienthat uses that DLL: 333489857Sobrien 333589857Sobrien@smallexample 333689857Sobrien gcc -c dll.c 333789857Sobrien dlltool -e exports.o -l dll.lib dll.o 333889857Sobrien gcc dll.o exports.o -o dll.dll 333989857Sobrien gcc program.o dll.lib -o program 334089857Sobrien@end smallexample 334189857Sobrien 334289857Sobrien@c man end 334389857Sobrien 334489857Sobrien@c man begin OPTIONS dlltool 334589857Sobrien 334689857SobrienThe command line options have the following meanings: 334789857Sobrien 334889857Sobrien@table @env 334989857Sobrien 335089857Sobrien@item -d @var{filename} 335189857Sobrien@itemx --input-def @var{filename} 335289857Sobrien@cindex input .def file 3353218822SdimSpecifies the name of a @file{.def} file to be read in and processed. 335489857Sobrien 335589857Sobrien@item -b @var{filename} 335689857Sobrien@itemx --base-file @var{filename} 335789857Sobrien@cindex base files 335889857SobrienSpecifies the name of a base file to be read in and processed. The 335989857Sobriencontents of this file will be added to the relocation section in the 336089857Sobrienexports file generated by dlltool. 336189857Sobrien 336289857Sobrien@item -e @var{filename} 336389857Sobrien@itemx --output-exp @var{filename} 336489857SobrienSpecifies the name of the export file to be created by dlltool. 336589857Sobrien 336689857Sobrien@item -z @var{filename} 336789857Sobrien@itemx --output-def @var{filename} 3368218822SdimSpecifies the name of the @file{.def} file to be created by dlltool. 336989857Sobrien 337089857Sobrien@item -l @var{filename} 337189857Sobrien@itemx --output-lib @var{filename} 337289857SobrienSpecifies the name of the library file to be created by dlltool. 337389857Sobrien 337489857Sobrien@item --export-all-symbols 337589857SobrienTreat all global and weak defined symbols found in the input object 337689857Sobrienfiles as symbols to be exported. There is a small list of symbols which 337789857Sobrienare not exported by default; see the @option{--no-default-excludes} 337889857Sobrienoption. You may add to the list of symbols to not export by using the 337989857Sobrien@option{--exclude-symbols} option. 338089857Sobrien 338189857Sobrien@item --no-export-all-symbols 3382218822SdimOnly export symbols explicitly listed in an input @file{.def} file or in 338389857Sobrien@samp{.drectve} sections in the input object files. This is the default 338489857Sobrienbehaviour. The @samp{.drectve} sections are created by @samp{dllexport} 338589857Sobrienattributes in the source code. 338689857Sobrien 338789857Sobrien@item --exclude-symbols @var{list} 338889857SobrienDo not export the symbols in @var{list}. This is a list of symbol names 338989857Sobrienseparated by comma or colon characters. The symbol names should not 339089857Sobriencontain a leading underscore. This is only meaningful when 339189857Sobrien@option{--export-all-symbols} is used. 339289857Sobrien 339389857Sobrien@item --no-default-excludes 339489857SobrienWhen @option{--export-all-symbols} is used, it will by default avoid 339589857Sobrienexporting certain special symbols. The current list of symbols to avoid 339689857Sobrienexporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0}, 339789857Sobrien@samp{impure_ptr}. You may use the @option{--no-default-excludes} option 339889857Sobriento go ahead and export these special symbols. This is only meaningful 339989857Sobrienwhen @option{--export-all-symbols} is used. 340089857Sobrien 340189857Sobrien@item -S @var{path} 340289857Sobrien@itemx --as @var{path} 340389857SobrienSpecifies the path, including the filename, of the assembler to be used 340489857Sobriento create the exports file. 340589857Sobrien 340689857Sobrien@item -f @var{options} 340789857Sobrien@itemx --as-flags @var{options} 340889857SobrienSpecifies any specific command line options to be passed to the 340989857Sobrienassembler when building the exports file. This option will work even if 341089857Sobrienthe @option{-S} option is not used. This option only takes one argument, 341189857Sobrienand if it occurs more than once on the command line, then later 341289857Sobrienoccurrences will override earlier occurrences. So if it is necessary to 341389857Sobrienpass multiple options to the assembler they should be enclosed in 341489857Sobriendouble quotes. 341589857Sobrien 341689857Sobrien@item -D @var{name} 341789857Sobrien@itemx --dll-name @var{name} 3418218822SdimSpecifies the name to be stored in the @file{.def} file as the name of 3419218822Sdimthe DLL when the @option{-e} option is used. If this option is not 3420218822Sdimpresent, then the filename given to the @option{-e} option will be 3421218822Sdimused as the name of the DLL. 342289857Sobrien 342389857Sobrien@item -m @var{machine} 342489857Sobrien@itemx -machine @var{machine} 342589857SobrienSpecifies the type of machine for which the library file should be 342689857Sobrienbuilt. @command{dlltool} has a built in default type, depending upon how 342789857Sobrienit was created, but this option can be used to override that. This is 342889857Sobriennormally only useful when creating DLLs for an ARM processor, when the 342989857Sobriencontents of the DLL are actually encode using Thumb instructions. 343089857Sobrien 343189857Sobrien@item -a 343289857Sobrien@itemx --add-indirect 343389857SobrienSpecifies that when @command{dlltool} is creating the exports file it 343489857Sobrienshould add a section which allows the exported functions to be 343589857Sobrienreferenced without using the import library. Whatever the hell that 3436218822Sdimmeans! 343789857Sobrien 343889857Sobrien@item -U 343989857Sobrien@itemx --add-underscore 344089857SobrienSpecifies that when @command{dlltool} is creating the exports file it 3441218822Sdimshould prepend an underscore to the names of @emph{all} exported symbols. 344289857Sobrien 3443218822Sdim@item --add-stdcall-underscore 3444218822SdimSpecifies that when @command{dlltool} is creating the exports file it 3445218822Sdimshould prepend an underscore to the names of exported @emph{stdcall} 3446218822Sdimfunctions. Variable names and non-stdcall function names are not modified. 3447218822SdimThis option is useful when creating GNU-compatible import libs for third 3448218822Sdimparty DLLs that were built with MS-Windows tools. 3449218822Sdim 345089857Sobrien@item -k 345189857Sobrien@itemx --kill-at 345289857SobrienSpecifies that when @command{dlltool} is creating the exports file it 345389857Sobrienshould not append the string @samp{@@ <number>}. These numbers are 345489857Sobriencalled ordinal numbers and they represent another way of accessing the 345589857Sobrienfunction in a DLL, other than by name. 345689857Sobrien 345789857Sobrien@item -A 345889857Sobrien@itemx --add-stdcall-alias 345989857SobrienSpecifies that when @command{dlltool} is creating the exports file it 346089857Sobrienshould add aliases for stdcall symbols without @samp{@@ <number>} 346189857Sobrienin addition to the symbols with @samp{@@ <number>}. 346289857Sobrien 3463218822Sdim@item -p 3464218822Sdim@itemx --ext-prefix-alias @var{prefix} 3465218822SdimCauses @command{dlltool} to create external aliases for all DLL 3466218822Sdimimports with the specified prefix. The aliases are created for both 3467218822Sdimexternal and import symbols with no leading underscore. 3468218822Sdim 346989857Sobrien@item -x 347089857Sobrien@itemx --no-idata4 347189857SobrienSpecifies that when @command{dlltool} is creating the exports and library 347289857Sobrienfiles it should omit the @code{.idata4} section. This is for compatibility 347389857Sobrienwith certain operating systems. 347489857Sobrien 347589857Sobrien@item -c 347689857Sobrien@itemx --no-idata5 347789857SobrienSpecifies that when @command{dlltool} is creating the exports and library 347889857Sobrienfiles it should omit the @code{.idata5} section. This is for compatibility 347989857Sobrienwith certain operating systems. 348089857Sobrien 348189857Sobrien@item -i 348289857Sobrien@itemx --interwork 348389857SobrienSpecifies that @command{dlltool} should mark the objects in the library 348489857Sobrienfile and exports file that it produces as supporting interworking 348589857Sobrienbetween ARM and Thumb code. 348689857Sobrien 348789857Sobrien@item -n 348889857Sobrien@itemx --nodelete 348989857SobrienMakes @command{dlltool} preserve the temporary assembler files it used to 349089857Sobriencreate the exports file. If this option is repeated then dlltool will 349189857Sobrienalso preserve the temporary object files it uses to create the library 3492130561Sobrienfile. 349389857Sobrien 3494130561Sobrien@item -t @var{prefix} 3495130561Sobrien@itemx --temp-prefix @var{prefix} 3496130561SobrienMakes @command{dlltool} use @var{prefix} when constructing the names of 3497130561Sobrientemporary assembler and object files. By default, the temp file prefix 3498218822Sdimis generated from the pid. 3499130561Sobrien 350089857Sobrien@item -v 350189857Sobrien@itemx --verbose 350289857SobrienMake dlltool describe what it is doing. 350389857Sobrien 350489857Sobrien@item -h 350589857Sobrien@itemx --help 350689857SobrienDisplays a list of command line options and then exits. 350789857Sobrien 350889857Sobrien@item -V 350989857Sobrien@itemx --version 351089857SobrienDisplays dlltool's version number and then exits. 351189857Sobrien 351289857Sobrien@end table 351389857Sobrien 351489857Sobrien@c man end 351589857Sobrien 3516218822Sdim@menu 3517218822Sdim* def file format:: The format of the dlltool @file{.def} file 3518218822Sdim@end menu 3519218822Sdim 3520218822Sdim@node def file format 3521218822Sdim@section The format of the @command{dlltool} @file{.def} file 3522218822Sdim 3523218822SdimA @file{.def} file contains any number of the following commands: 3524218822Sdim 3525218822Sdim@table @asis 3526218822Sdim 3527218822Sdim@item @code{NAME} @var{name} @code{[ ,} @var{base} @code{]} 3528218822SdimThe result is going to be named @var{name}@code{.exe}. 3529218822Sdim 3530218822Sdim@item @code{LIBRARY} @var{name} @code{[ ,} @var{base} @code{]} 3531218822SdimThe result is going to be named @var{name}@code{.dll}. 3532218822Sdim 3533218822Sdim@item @code{EXPORTS ( ( (} @var{name1} @code{[ = } @var{name2} @code{] ) | ( } @var{name1} @code{=} @var{module-name} @code{.} @var{external-name} @code{) )} 3534218822Sdim@item @code{[} @var{integer} @code{] [ NONAME ] [ CONSTANT ] [ DATA ] [ PRIVATE ] ) *} 3535218822SdimDeclares @var{name1} as an exported symbol from the DLL, with optional 3536218822Sdimordinal number @var{integer}, or declares @var{name1} as an alias 3537218822Sdim(forward) of the function @var{external-name} in the DLL 3538218822Sdim@var{module-name}. 3539218822Sdim 3540218822Sdim@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{) ) *} 3541218822SdimDeclares that @var{external-name} or the exported function whose 3542218822Sdimordinal number is @var{integer} is to be imported from the file 3543218822Sdim@var{module-name}. If @var{internal-name} is specified then this is 3544218822Sdimthe name that the imported function will be referred to in the body of 3545218822Sdimthe DLL. 3546218822Sdim 3547218822Sdim@item @code{DESCRIPTION} @var{string} 3548218822SdimPuts @var{string} into the output @file{.exp} file in the 3549218822Sdim@code{.rdata} section. 3550218822Sdim 3551218822Sdim@item @code{STACKSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]} 3552218822Sdim@item @code{HEAPSIZE} @var{number-reserve} @code{[, } @var{number-commit} @code{]} 3553218822SdimGenerates @code{--stack} or @code{--heap} 3554218822Sdim@var{number-reserve},@var{number-commit} in the output @code{.drectve} 3555218822Sdimsection. The linker will see this and act upon it. 3556218822Sdim 3557218822Sdim@item @code{CODE} @var{attr} @code{+} 3558218822Sdim@item @code{DATA} @var{attr} @code{+} 3559218822Sdim@item @code{SECTIONS (} @var{section-name} @var{attr}@code{ + ) *} 3560218822SdimGenerates @code{--attr} @var{section-name} @var{attr} in the output 3561218822Sdim@code{.drectve} section, where @var{attr} is one of @code{READ}, 3562218822Sdim@code{WRITE}, @code{EXECUTE} or @code{SHARED}. The linker will see 3563218822Sdimthis and act upon it. 3564218822Sdim 3565218822Sdim@end table 3566218822Sdim 356789857Sobrien@ignore 356889857Sobrien@c man begin SEEALSO dlltool 3569218822SdimThe Info pages for @file{binutils}. 357089857Sobrien@c man end 357189857Sobrien@end ignore 357289857Sobrien 357389857Sobrien@node readelf 357489857Sobrien@chapter readelf 357589857Sobrien 357689857Sobrien@cindex ELF file information 357789857Sobrien@kindex readelf 357889857Sobrien 357989857Sobrien@c man title readelf Displays information about ELF files. 358089857Sobrien 358189857Sobrien@smallexample 358289857Sobrien@c man begin SYNOPSIS readelf 3583218822Sdimreadelf [@option{-a}|@option{--all}] 358489857Sobrien [@option{-h}|@option{--file-header}] 358589857Sobrien [@option{-l}|@option{--program-headers}|@option{--segments}] 358689857Sobrien [@option{-S}|@option{--section-headers}|@option{--sections}] 3587218822Sdim [@option{-g}|@option{--section-groups}] 3588218822Sdim [@option{-t}|@option{--section-details}] 358989857Sobrien [@option{-e}|@option{--headers}] 359089857Sobrien [@option{-s}|@option{--syms}|@option{--symbols}] 359189857Sobrien [@option{-n}|@option{--notes}] 359289857Sobrien [@option{-r}|@option{--relocs}] 359389857Sobrien [@option{-u}|@option{--unwind}] 359489857Sobrien [@option{-d}|@option{--dynamic}] 359589857Sobrien [@option{-V}|@option{--version-info}] 3596130561Sobrien [@option{-A}|@option{--arch-specific}] 359789857Sobrien [@option{-D}|@option{--use-dynamic}] 3598218822Sdim [@option{-x} <number or name>|@option{--hex-dump=}<number or name>] 3599218822Sdim [@option{-w[liaprmfFsoR]}| 3600218822Sdim @option{--debug-dump}[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]] 3601130561Sobrien [@option{-I}|@option{-histogram}] 360289857Sobrien [@option{-v}|@option{--version}] 360389857Sobrien [@option{-W}|@option{--wide}] 360489857Sobrien [@option{-H}|@option{--help}] 360589857Sobrien @var{elffile}@dots{} 360689857Sobrien@c man end 360789857Sobrien@end smallexample 360889857Sobrien 360989857Sobrien@c man begin DESCRIPTION readelf 361089857Sobrien 361189857Sobrien@command{readelf} displays information about one or more ELF format object 361289857Sobrienfiles. The options control what particular information to display. 361389857Sobrien 3614130561Sobrien@var{elffile}@dots{} are the object files to be examined. 32-bit and 3615130561Sobrien64-bit ELF files are supported, as are archives containing ELF files. 361689857Sobrien 3617130561SobrienThis program performs a similar function to @command{objdump} but it 3618130561Sobriengoes into more detail and it exists independently of the @sc{bfd} 3619130561Sobrienlibrary, so if there is a bug in @sc{bfd} then readelf will not be 3620130561Sobrienaffected. 3621130561Sobrien 362289857Sobrien@c man end 362389857Sobrien 362489857Sobrien@c man begin OPTIONS readelf 362589857Sobrien 362689857SobrienThe long and short forms of options, shown here as alternatives, are 362789857Sobrienequivalent. At least one option besides @samp{-v} or @samp{-H} must be 3628218822Sdimgiven. 362989857Sobrien 363089857Sobrien@table @env 363189857Sobrien@item -a 363289857Sobrien@itemx --all 3633218822SdimEquivalent to specifying @option{--file-header}, 363489857Sobrien@option{--program-headers}, @option{--sections}, @option{--symbols}, 363589857Sobrien@option{--relocs}, @option{--dynamic}, @option{--notes} and 3636218822Sdim@option{--version-info}. 363789857Sobrien 363889857Sobrien@item -h 363989857Sobrien@itemx --file-header 364089857Sobrien@cindex ELF file header information 364189857SobrienDisplays the information contained in the ELF header at the start of the 364289857Sobrienfile. 364389857Sobrien 364489857Sobrien@item -l 364589857Sobrien@itemx --program-headers 364689857Sobrien@itemx --segments 364789857Sobrien@cindex ELF program header information 364889857Sobrien@cindex ELF segment information 364989857SobrienDisplays the information contained in the file's segment headers, if it 365089857Sobrienhas any. 365189857Sobrien 365289857Sobrien@item -S 365389857Sobrien@itemx --sections 365489857Sobrien@itemx --section-headers 365589857Sobrien@cindex ELF section information 365689857SobrienDisplays the information contained in the file's section headers, if it 365789857Sobrienhas any. 365889857Sobrien 3659218822Sdim@item -g 3660218822Sdim@itemx --section-groups 3661218822Sdim@cindex ELF section group information 3662218822SdimDisplays the information contained in the file's section groups, if it 3663218822Sdimhas any. 3664218822Sdim 3665218822Sdim@item -t 3666218822Sdim@itemx --section-details 3667218822Sdim@cindex ELF section information 3668218822SdimDisplays the detailed section information. Implies @option{-S}. 3669218822Sdim 367089857Sobrien@item -s 367189857Sobrien@itemx --symbols 367289857Sobrien@itemx --syms 367389857Sobrien@cindex ELF symbol table information 367489857SobrienDisplays the entries in symbol table section of the file, if it has one. 367589857Sobrien 367689857Sobrien@item -e 367789857Sobrien@itemx --headers 367889857SobrienDisplay all the headers in the file. Equivalent to @option{-h -l -S}. 367989857Sobrien 368089857Sobrien@item -n 368189857Sobrien@itemx --notes 3682218822Sdim@cindex ELF notes 3683218822SdimDisplays the contents of the NOTE segments and/or sections, if any. 368489857Sobrien 368589857Sobrien@item -r 368689857Sobrien@itemx --relocs 368789857Sobrien@cindex ELF reloc information 368889857SobrienDisplays the contents of the file's relocation section, if it has one. 368989857Sobrien 369089857Sobrien@item -u 369189857Sobrien@itemx --unwind 369289857Sobrien@cindex unwind information 369389857SobrienDisplays the contents of the file's unwind section, if it has one. Only 369489857Sobrienthe unwind sections for IA64 ELF files are currently supported. 369589857Sobrien 369689857Sobrien@item -d 369789857Sobrien@itemx --dynamic 369889857Sobrien@cindex ELF dynamic section information 369989857SobrienDisplays the contents of the file's dynamic section, if it has one. 370089857Sobrien 370189857Sobrien@item -V 370289857Sobrien@itemx --version-info 370389857Sobrien@cindex ELF version sections informations 370489857SobrienDisplays the contents of the version sections in the file, it they 370589857Sobrienexist. 370689857Sobrien 3707130561Sobrien@item -A 3708130561Sobrien@itemx --arch-specific 3709130561SobrienDisplays architecture-specific information in the file, if there 3710130561Sobrienis any. 3711130561Sobrien 371289857Sobrien@item -D 371389857Sobrien@itemx --use-dynamic 371489857SobrienWhen displaying symbols, this option makes @command{readelf} use the 371589857Sobriensymbol table in the file's dynamic section, rather than the one in the 371689857Sobriensymbols section. 371789857Sobrien 3718218822Sdim@item -x <number or name> 3719218822Sdim@itemx --hex-dump=<number or name> 372089857SobrienDisplays the contents of the indicated section as a hexadecimal dump. 3721218822SdimA number identifies a particular section by index in the section table; 3722218822Sdimany other string identifies all sections with that name in the object file. 372389857Sobrien 3724218822Sdim@item -w[liaprmfFsoR] 3725218822Sdim@itemx --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges] 372689857SobrienDisplays the contents of the debug sections in the file, if any are 372789857Sobrienpresent. If one of the optional letters or words follows the switch 372889857Sobrienthen only data found in those specific sections will be dumped. 372989857Sobrien 3730130561Sobrien@item -I 3731130561Sobrien@itemx --histogram 373289857SobrienDisplay a histogram of bucket list lengths when displaying the contents 373389857Sobrienof the symbol tables. 373489857Sobrien 373589857Sobrien@item -v 373689857Sobrien@itemx --version 373789857SobrienDisplay the version number of readelf. 373889857Sobrien 373989857Sobrien@item -W 374089857Sobrien@itemx --wide 374189857SobrienDon't break output lines to fit into 80 columns. By default 374289857Sobrien@command{readelf} breaks section header and segment listing lines for 374389857Sobrien64-bit ELF files, so that they fit into 80 columns. This option causes 374489857Sobrien@command{readelf} to print each section header resp. each segment one a 374589857Sobriensingle line, which is far more readable on terminals wider than 80 columns. 374689857Sobrien 374789857Sobrien@item -H 374889857Sobrien@itemx --help 374989857SobrienDisplay the command line options understood by @command{readelf}. 375089857Sobrien 375189857Sobrien@end table 375289857Sobrien 375389857Sobrien@c man end 375489857Sobrien 375589857Sobrien@ignore 375689857Sobrien@c man begin SEEALSO readelf 375789857Sobrienobjdump(1), and the Info entries for @file{binutils}. 375889857Sobrien@c man end 375989857Sobrien@end ignore 376089857Sobrien 3761218822Sdim@node Common Options 3762218822Sdim@chapter Common Options 3763218822Sdim 3764218822SdimThe following command-line options are supported by all of the 3765218822Sdimprograms described in this manual. 3766218822Sdim 3767218822Sdim@c man begin OPTIONS 3768218822Sdim@table @env 3769218822Sdim@include at-file.texi 3770218822Sdim@c man end 3771218822Sdim 3772218822Sdim@item --help 3773218822SdimDisplay the command-line options supported by the program. 3774218822Sdim 3775218822Sdim@item --version 3776218822SdimDisplay the version number of the program. 3777218822Sdim 3778218822Sdim@c man begin OPTIONS 3779218822Sdim@end table 3780218822Sdim@c man end 3781218822Sdim 378289857Sobrien@node Selecting The Target System 3783130561Sobrien@chapter Selecting the Target System 378489857Sobrien 3785130561SobrienYou can specify two aspects of the target system to the @sc{gnu} 378689857Sobrienbinary file utilities, each in several ways: 378789857Sobrien 378889857Sobrien@itemize @bullet 378989857Sobrien@item 379089857Sobrienthe target 379189857Sobrien 379289857Sobrien@item 379389857Sobrienthe architecture 379489857Sobrien@end itemize 379589857Sobrien 379689857SobrienIn the following summaries, the lists of ways to specify values are in 379789857Sobrienorder of decreasing precedence. The ways listed first override those 379889857Sobrienlisted later. 379989857Sobrien 380089857SobrienThe commands to list valid values only list the values for which the 380189857Sobrienprograms you are running were configured. If they were configured with 380289857Sobrien@option{--enable-targets=all}, the commands list most of the available 380389857Sobrienvalues, but a few are left out; not all targets can be configured in at 380489857Sobrienonce because some of them can only be configured @dfn{native} (on hosts 380589857Sobrienwith the same type as the target system). 380689857Sobrien 380789857Sobrien@menu 3808218822Sdim* Target Selection:: 3809218822Sdim* Architecture Selection:: 381089857Sobrien@end menu 381189857Sobrien 381289857Sobrien@node Target Selection 381389857Sobrien@section Target Selection 381489857Sobrien 381589857SobrienA @dfn{target} is an object file format. A given target may be 381689857Sobriensupported for multiple architectures (@pxref{Architecture Selection}). 381789857SobrienA target selection may also have variations for different operating 381889857Sobriensystems or architectures. 381989857Sobrien 382089857SobrienThe command to list valid target values is @samp{objdump -i} 382189857Sobrien(the first column of output contains the relevant information). 382289857Sobrien 382389857SobrienSome sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips}, 382489857Sobrien@samp{a.out-sunos-big}. 382589857Sobrien 382689857SobrienYou can also specify a target using a configuration triplet. This is 382789857Sobrienthe same sort of name that is passed to @file{configure} to specify a 382889857Sobrientarget. When you use a configuration triplet as an argument, it must be 382989857Sobrienfully canonicalized. You can see the canonical version of a triplet by 383089857Sobrienrunning the shell script @file{config.sub} which is included with the 383189857Sobriensources. 383289857Sobrien 383389857SobrienSome sample configuration triplets are: @samp{m68k-hp-bsd}, 383489857Sobrien@samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}. 383589857Sobrien 383689857Sobrien@subheading @command{objdump} Target 383789857Sobrien 383889857SobrienWays to specify: 383989857Sobrien 384089857Sobrien@enumerate 384189857Sobrien@item 384289857Sobriencommand line option: @option{-b} or @option{--target} 384389857Sobrien 384489857Sobrien@item 384589857Sobrienenvironment variable @code{GNUTARGET} 384689857Sobrien 384789857Sobrien@item 384889857Sobriendeduced from the input file 384989857Sobrien@end enumerate 385089857Sobrien 385189857Sobrien@subheading @command{objcopy} and @command{strip} Input Target 385289857Sobrien 385389857SobrienWays to specify: 385489857Sobrien 385589857Sobrien@enumerate 385689857Sobrien@item 385789857Sobriencommand line options: @option{-I} or @option{--input-target}, or @option{-F} or @option{--target} 385889857Sobrien 385989857Sobrien@item 386089857Sobrienenvironment variable @code{GNUTARGET} 386189857Sobrien 386289857Sobrien@item 386389857Sobriendeduced from the input file 386489857Sobrien@end enumerate 386589857Sobrien 386689857Sobrien@subheading @command{objcopy} and @command{strip} Output Target 386789857Sobrien 386889857SobrienWays to specify: 386989857Sobrien 387089857Sobrien@enumerate 387189857Sobrien@item 387289857Sobriencommand line options: @option{-O} or @option{--output-target}, or @option{-F} or @option{--target} 387389857Sobrien 387489857Sobrien@item 387589857Sobrienthe input target (see ``@command{objcopy} and @command{strip} Input Target'' above) 387689857Sobrien 387789857Sobrien@item 387889857Sobrienenvironment variable @code{GNUTARGET} 387989857Sobrien 388089857Sobrien@item 388189857Sobriendeduced from the input file 388289857Sobrien@end enumerate 388389857Sobrien 388489857Sobrien@subheading @command{nm}, @command{size}, and @command{strings} Target 388589857Sobrien 388689857SobrienWays to specify: 388789857Sobrien 388889857Sobrien@enumerate 388989857Sobrien@item 389089857Sobriencommand line option: @option{--target} 389189857Sobrien 389289857Sobrien@item 389389857Sobrienenvironment variable @code{GNUTARGET} 389489857Sobrien 389589857Sobrien@item 389689857Sobriendeduced from the input file 389789857Sobrien@end enumerate 389889857Sobrien 389989857Sobrien@node Architecture Selection 3900130561Sobrien@section Architecture Selection 390189857Sobrien 390289857SobrienAn @dfn{architecture} is a type of @sc{cpu} on which an object file is 390389857Sobriento run. Its name may contain a colon, separating the name of the 390489857Sobrienprocessor family from the name of the particular @sc{cpu}. 390589857Sobrien 390689857SobrienThe command to list valid architecture values is @samp{objdump -i} (the 390789857Sobriensecond column contains the relevant information). 390889857Sobrien 390989857SobrienSample values: @samp{m68k:68020}, @samp{mips:3000}, @samp{sparc}. 391089857Sobrien 391189857Sobrien@subheading @command{objdump} Architecture 391289857Sobrien 391389857SobrienWays to specify: 391489857Sobrien 391589857Sobrien@enumerate 391689857Sobrien@item 391789857Sobriencommand line option: @option{-m} or @option{--architecture} 391889857Sobrien 391989857Sobrien@item 392089857Sobriendeduced from the input file 392189857Sobrien@end enumerate 392289857Sobrien 392389857Sobrien@subheading @command{objcopy}, @command{nm}, @command{size}, @command{strings} Architecture 392489857Sobrien 392589857SobrienWays to specify: 392689857Sobrien 392789857Sobrien@enumerate 392889857Sobrien@item 392989857Sobriendeduced from the input file 393089857Sobrien@end enumerate 393189857Sobrien 393289857Sobrien@node Reporting Bugs 393389857Sobrien@chapter Reporting Bugs 393489857Sobrien@cindex bugs 393589857Sobrien@cindex reporting bugs 393689857Sobrien 393789857SobrienYour bug reports play an essential role in making the binary utilities 393889857Sobrienreliable. 393989857Sobrien 394089857SobrienReporting a bug may help you by bringing a solution to your problem, or 394189857Sobrienit may not. But in any case the principal function of a bug report is 394289857Sobriento help the entire community by making the next version of the binary 394389857Sobrienutilities work better. Bug reports are your contribution to their 394489857Sobrienmaintenance. 394589857Sobrien 394689857SobrienIn order for a bug report to serve its purpose, you must include the 394789857Sobrieninformation that enables us to fix the bug. 394889857Sobrien 394989857Sobrien@menu 395089857Sobrien* Bug Criteria:: Have you found a bug? 395189857Sobrien* Bug Reporting:: How to report bugs 395289857Sobrien@end menu 395389857Sobrien 395489857Sobrien@node Bug Criteria 3955130561Sobrien@section Have You Found a Bug? 395689857Sobrien@cindex bug criteria 395789857Sobrien 395889857SobrienIf you are not sure whether you have found a bug, here are some guidelines: 395989857Sobrien 396089857Sobrien@itemize @bullet 396189857Sobrien@cindex fatal signal 396289857Sobrien@cindex crash 396389857Sobrien@item 396489857SobrienIf a binary utility gets a fatal signal, for any input whatever, that is 396589857Sobriena bug. Reliable utilities never crash. 396689857Sobrien 396789857Sobrien@cindex error on valid input 396889857Sobrien@item 396989857SobrienIf a binary utility produces an error message for valid input, that is a 397089857Sobrienbug. 397189857Sobrien 397289857Sobrien@item 397389857SobrienIf you are an experienced user of binary utilities, your suggestions for 397489857Sobrienimprovement are welcome in any case. 397589857Sobrien@end itemize 397689857Sobrien 397789857Sobrien@node Bug Reporting 3978130561Sobrien@section How to Report Bugs 397989857Sobrien@cindex bug reports 398089857Sobrien@cindex bugs, reporting 398189857Sobrien 398289857SobrienA number of companies and individuals offer support for @sc{gnu} 398389857Sobrienproducts. If you obtained the binary utilities from a support 398489857Sobrienorganization, we recommend you contact that organization first. 398589857Sobrien 398689857SobrienYou can find contact information for many support companies and 398789857Sobrienindividuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs 398889857Sobriendistribution. 398989857Sobrien 3990218822Sdim@ifset BUGURL 399189857SobrienIn any event, we also recommend that you send bug reports for the binary 3992218822Sdimutilities to @value{BUGURL}. 3993218822Sdim@end ifset 399489857Sobrien 399589857SobrienThe fundamental principle of reporting bugs usefully is this: 399689857Sobrien@strong{report all the facts}. If you are not sure whether to state a 399789857Sobrienfact or leave it out, state it! 399889857Sobrien 399989857SobrienOften people omit facts because they think they know what causes the 400089857Sobrienproblem and assume that some details do not matter. Thus, you might 400189857Sobrienassume that the name of a file you use in an example does not matter. 400289857SobrienWell, probably it does not, but one cannot be sure. Perhaps the bug is 400389857Sobriena stray memory reference which happens to fetch from the location where 400489857Sobrienthat pathname is stored in memory; perhaps, if the pathname were 400589857Sobriendifferent, the contents of that location would fool the utility into 400689857Sobriendoing the right thing despite the bug. Play it safe and give a 400789857Sobrienspecific, complete example. That is the easiest thing for you to do, 400889857Sobrienand the most helpful. 400989857Sobrien 401089857SobrienKeep in mind that the purpose of a bug report is to enable us to fix the bug if 401189857Sobrienit is new to us. Therefore, always write your bug reports on the assumption 401289857Sobrienthat the bug has not been reported previously. 401389857Sobrien 401489857SobrienSometimes people give a few sketchy facts and ask, ``Does this ring a 4015130561Sobrienbell?'' This cannot help us fix a bug, so it is basically useless. We 4016130561Sobrienrespond by asking for enough details to enable us to investigate. 4017130561SobrienYou might as well expedite matters by sending them to begin with. 401889857Sobrien 401989857SobrienTo enable us to fix the bug, you should include all these things: 402089857Sobrien 402189857Sobrien@itemize @bullet 402289857Sobrien@item 402389857SobrienThe version of the utility. Each utility announces it if you start it 402489857Sobrienwith the @option{--version} argument. 402589857Sobrien 402689857SobrienWithout this, we will not know whether there is any point in looking for 402789857Sobrienthe bug in the current version of the binary utilities. 402889857Sobrien 402989857Sobrien@item 403089857SobrienAny patches you may have applied to the source, including any patches 403189857Sobrienmade to the @code{BFD} library. 403289857Sobrien 403389857Sobrien@item 403489857SobrienThe type of machine you are using, and the operating system name and 403589857Sobrienversion number. 403689857Sobrien 403789857Sobrien@item 403889857SobrienWhat compiler (and its version) was used to compile the utilities---e.g. 403989857Sobrien``@code{gcc-2.7}''. 404089857Sobrien 404189857Sobrien@item 404289857SobrienThe command arguments you gave the utility to observe the bug. To 404389857Sobrienguarantee you will not omit something important, list them all. A copy 404489857Sobrienof the Makefile (or the output from make) is sufficient. 404589857Sobrien 404689857SobrienIf we were to try to guess the arguments, we would probably guess wrong 404789857Sobrienand then we might not encounter the bug. 404889857Sobrien 404989857Sobrien@item 405089857SobrienA complete input file, or set of input files, that will reproduce the 405189857Sobrienbug. If the utility is reading an object file or files, then it is 4052218822Sdimgenerally most helpful to send the actual object files. 405389857Sobrien 405489857SobrienIf the source files were produced exclusively using @sc{gnu} programs 405589857Sobrien(e.g., @command{gcc}, @command{gas}, and/or the @sc{gnu} @command{ld}), then it 405689857Sobrienmay be OK to send the source files rather than the object files. In 405789857Sobrienthis case, be sure to say exactly what version of @command{gcc}, or 405889857Sobrienwhatever, was used to produce the object files. Also say how 405989857Sobrien@command{gcc}, or whatever, was configured. 406089857Sobrien 406189857Sobrien@item 406289857SobrienA description of what behavior you observe that you believe is 406389857Sobrienincorrect. For example, ``It gets a fatal signal.'' 406489857Sobrien 406589857SobrienOf course, if the bug is that the utility gets a fatal signal, then we 406689857Sobrienwill certainly notice it. But if the bug is incorrect output, we might 406789857Sobriennot notice unless it is glaringly wrong. You might as well not give us 406889857Sobriena chance to make a mistake. 406989857Sobrien 407089857SobrienEven if the problem you experience is a fatal signal, you should still 407189857Sobriensay so explicitly. Suppose something strange is going on, such as your 4072218822Sdimcopy of the utility is out of sync, or you have encountered a bug in 407389857Sobrienthe C library on your system. (This has happened!) Your copy might 407489857Sobriencrash and ours would not. If you told us to expect a crash, then when 407589857Sobrienours fails to crash, we would know that the bug was not happening for 407689857Sobrienus. If you had not told us to expect a crash, then we would not be able 407789857Sobriento draw any conclusion from our observations. 407889857Sobrien 407989857Sobrien@item 408089857SobrienIf you wish to suggest changes to the source, send us context diffs, as 408189857Sobriengenerated by @command{diff} with the @option{-u}, @option{-c}, or @option{-p} 408289857Sobrienoption. Always send diffs from the old file to the new file. If you 408389857Sobrienwish to discuss something in the @command{ld} source, refer to it by 408489857Sobriencontext, not by line number. 408589857Sobrien 408689857SobrienThe line numbers in our development sources will not match those in your 408789857Sobriensources. Your line numbers would convey no useful information to us. 408889857Sobrien@end itemize 408989857Sobrien 409089857SobrienHere are some things that are not necessary: 409189857Sobrien 409289857Sobrien@itemize @bullet 409389857Sobrien@item 409489857SobrienA description of the envelope of the bug. 409589857Sobrien 409689857SobrienOften people who encounter a bug spend a lot of time investigating 409789857Sobrienwhich changes to the input file will make the bug go away and which 409889857Sobrienchanges will not affect it. 409989857Sobrien 410089857SobrienThis is often time consuming and not very useful, because the way we 410189857Sobrienwill find the bug is by running a single example under the debugger 410289857Sobrienwith breakpoints, not by pure deduction from a series of examples. 410389857SobrienWe recommend that you save your time for something else. 410489857Sobrien 410589857SobrienOf course, if you can find a simpler example to report @emph{instead} 410689857Sobrienof the original one, that is a convenience for us. Errors in the 410789857Sobrienoutput will be easier to spot, running under the debugger will take 410889857Sobrienless time, and so on. 410989857Sobrien 411089857SobrienHowever, simplification is not vital; if you do not want to do this, 411189857Sobrienreport the bug anyway and send us the entire test case you used. 411289857Sobrien 411389857Sobrien@item 411489857SobrienA patch for the bug. 411589857Sobrien 411689857SobrienA patch for the bug does help us if it is a good one. But do not omit 411789857Sobrienthe necessary information, such as the test case, on the assumption that 411889857Sobriena patch is all we need. We might see problems with your patch and decide 411989857Sobriento fix the problem another way, or we might not understand it at all. 412089857Sobrien 412189857SobrienSometimes with programs as complicated as the binary utilities it is 412289857Sobrienvery hard to construct an example that will make the program follow a 412389857Sobriencertain path through the code. If you do not send us the example, we 412489857Sobrienwill not be able to construct one, so we will not be able to verify that 412589857Sobrienthe bug is fixed. 412689857Sobrien 412789857SobrienAnd if we cannot understand what bug you are trying to fix, or why your 412889857Sobrienpatch should be an improvement, we will not install it. A test case will 412989857Sobrienhelp us to understand. 413089857Sobrien 413189857Sobrien@item 413289857SobrienA guess about what the bug is or what it depends on. 413389857Sobrien 413489857SobrienSuch guesses are usually wrong. Even we cannot guess right about such 413589857Sobrienthings without first using the debugger to find the facts. 413689857Sobrien@end itemize 413789857Sobrien 4138130561Sobrien@include fdl.texi 413989857Sobrien 4140218822Sdim@node Binutils Index 4141218822Sdim@unnumbered Binutils Index 414289857Sobrien 414389857Sobrien@printindex cp 414489857Sobrien 414589857Sobrien@bye 4146