diff options
Diffstat (limited to 'binutils/binutils.texi')
| -rw-r--r-- | binutils/binutils.texi | 2904 |
1 files changed, 2904 insertions, 0 deletions
diff --git a/binutils/binutils.texi b/binutils/binutils.texi new file mode 100644 index 00000000000..5f7c646b275 --- /dev/null +++ b/binutils/binutils.texi @@ -0,0 +1,2904 @@ +\input texinfo @c -*- Texinfo -*- +@setfilename binutils.info +@include config.texi + +@ifinfo +@format +START-INFO-DIR-ENTRY +* Binutils: (binutils). The GNU binary utilities "ar", "objcopy", + "objdump", "nm", "nlmconv", "size", "readelf" + "strings", "strip", "ranlib" and "dlltool". +END-INFO-DIR-ENTRY +@end format +@end ifinfo + +@ifinfo +Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + +@synindex ky cp +@c +@c This file documents the GNU binary utilities "ar", "ld", "objcopy", +@c "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib". +@c +@c Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc. +@c +@c This text may be freely distributed under the terms of the GNU +@c General Public License. +@c + +@setchapternewpage odd +@settitle @sc{gnu} Binary Utilities +@titlepage +@finalout +@title The @sc{gnu} Binary Utilities +@subtitle Version @value{VERSION} +@sp 1 +@subtitle May 1993 +@author Roland H. Pesch +@author Jeffrey M. Osier +@author Cygnus Support +@page + +@tex +{\parskip=0pt \hfill Cygnus Support\par \hfill +\TeX{}info \texinfoversion\par } +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage + +@node Top +@top Introduction + +@cindex version +This brief manual contains preliminary documentation for the @sc{gnu} binary +utilities (collectively version @value{VERSION}): + +@iftex +@table @code +@item ar +Create, modify, and extract from archives + +@item nm +List symbols from object files + +@item objcopy +Copy and translate object files + +@item objdump +Display information from object files + +@item ranlib +Generate index to archive contents + +@item readelf +Display the contents of ELF format files. + +@item size +List file section sizes and total size + +@item strings +List printable strings from files + +@item strip +Discard symbols + +@item c++filt +Demangle encoded C++ symbols + +@item addr2line +Convert addresses into file names and line numbers + +@item nlmconv +Convert object code into a Netware Loadable Module + +@item windres +Manipulate Windows resources + +@item dlltool +Create the files needed to build and use Dynamic Link Libraries +@end table +@end iftex + +@menu +* ar:: Create, modify, and extract from archives +* nm:: List symbols from object files +* objcopy:: Copy and translate object files +* objdump:: Display information from object files +* ranlib:: Generate index to archive contents +* readelf:: Display the contents of ELF format files. +* size:: List section sizes and total size +* strings:: List printable strings from files +* strip:: Discard symbols +* c++filt:: Filter to demangle encoded C++ symbols +* addr2line:: Convert addresses to file and line +* nlmconv:: Converts object code into an NLM +* windres:: Manipulate Windows resources +* dlltool:: Create files needed to build and use DLLs +* Selecting The Target System:: How these utilities determine the target. +* Reporting Bugs:: Reporting Bugs +* Index:: Index +@end menu + +@node ar +@chapter ar + +@kindex ar +@cindex archives +@cindex collections of files +@smallexample +ar [-]@var{p}[@var{mod} [@var{relpos}]] @var{archive} [@var{member}@dots{}] +ar -M [ <mri-script ] +@end smallexample + +The @sc{gnu} @code{ar} program creates, modifies, and extracts from +archives. An @dfn{archive} is a single file holding a collection of +other files in a structure that makes it possible to retrieve +the original individual files (called @dfn{members} of the archive). + +The original files' contents, mode (permissions), timestamp, owner, and +group are preserved in the archive, and can be restored on +extraction. + +@cindex name length +@sc{gnu} @code{ar} can maintain archives whose members have names of any +length; however, depending on how @code{ar} is configured on your +system, a limit on member-name length may be imposed for compatibility +with archive formats maintained with other tools. If it exists, the +limit is often 15 characters (typical of formats related to a.out) or 16 +characters (typical of formats related to coff). + +@cindex libraries +@code{ar} is considered a binary utility because archives of this sort +are most often used as @dfn{libraries} holding commonly needed +subroutines. + +@cindex symbol index +@code{ar} creates an index to the symbols defined in relocatable +object modules in the archive when you specify the modifier @samp{s}. +Once created, this index is updated in the archive whenever @code{ar} +makes a change to its contents (save for the @samp{q} update operation). +An archive with such an index speeds up linking to the library, and +allows routines in the library to call each other without regard to +their placement in the archive. + +You may use @samp{nm -s} or @samp{nm --print-armap} to list this index +table. If an archive lacks the table, another form of @code{ar} called +@code{ranlib} can be used to add just the table. + +@cindex compatibility, @code{ar} +@cindex @code{ar} compatibility +@sc{gnu} @code{ar} is designed to be compatible with two different +facilities. You can control its activity using command-line options, +like the different varieties of @code{ar} on Unix systems; or, if you +specify the single command-line option @samp{-M}, you can control it +with a script supplied via standard input, like the MRI ``librarian'' +program. + +@menu +* ar cmdline:: Controlling @code{ar} on the command line +* ar scripts:: Controlling @code{ar} with a script +@end menu + +@page +@node ar cmdline +@section Controlling @code{ar} on the command line + +@smallexample +ar [-]@var{p}[@var{mod} [@var{relpos}]] @var{archive} [@var{member}@dots{}] +@end smallexample + +@cindex Unix compatibility, @code{ar} +When you use @code{ar} in the Unix style, @code{ar} insists on at least two +arguments to execute: one keyletter specifying the @emph{operation} +(optionally accompanied by other keyletters specifying +@emph{modifiers}), and the archive name to act on. + +Most operations can also accept further @var{member} arguments, +specifying particular files to operate on. + +@sc{gnu} @code{ar} allows you to mix the operation code @var{p} and modifier +flags @var{mod} in any order, within the first command-line argument. + +If you wish, you may begin the first command-line argument with a +dash. + +@cindex operations on archive +The @var{p} keyletter specifies what operation to execute; it may be +any of the following, but you must specify only one of them: + +@table @code +@item d +@cindex deleting from archive +@emph{Delete} modules from the archive. Specify the names of modules to +be deleted as @var{member}@dots{}; the archive is untouched if you +specify no files to delete. + +If you specify the @samp{v} modifier, @code{ar} lists each module +as it is deleted. + +@item m +@cindex moving in archive +Use this operation to @emph{move} members in an archive. + +The ordering of members in an archive can make a difference in how +programs are linked using the library, if a symbol is defined in more +than one member. + +If no modifiers are used with @code{m}, any members you name in the +@var{member} arguments are moved to the @emph{end} of the archive; +you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a +specified place instead. + +@item p +@cindex printing from archive +@emph{Print} the specified members of the archive, to the standard +output file. If the @samp{v} modifier is specified, show the member +name before copying its contents to standard output. + +If you specify no @var{member} arguments, all the files in the archive are +printed. + +@item q +@cindex quick append to archive +@emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of +@var{archive}, without checking for replacement. + +The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this +operation; new members are always placed at the end of the archive. + +The modifier @samp{v} makes @code{ar} list each file as it is appended. + +Since the point of this operation is speed, the archive's symbol table +index is not updated, even if it already existed; you can use @samp{ar s} or +@code{ranlib} explicitly to update the symbol table index. + +However, too many different systems assume quick append rebuilds the +index, so GNU ar implements @code{q} as a synonym for @code{r}. + +@item r +@cindex replacement in archive +Insert the files @var{member}@dots{} into @var{archive} (with +@emph{replacement}). This operation differs from @samp{q} in that any +previously existing members are deleted if their names match those being +added. + +If one of the files named in @var{member}@dots{} does not exist, @code{ar} +displays an error message, and leaves undisturbed any existing members +of the archive matching that name. + +By default, new members are added at the end of the file; but you may +use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request +placement relative to some existing member. + +The modifier @samp{v} used with this operation elicits a line of +output for each file inserted, along with one of the letters @samp{a} or +@samp{r} to indicate whether the file was appended (no old member +deleted) or replaced. + +@item t +@cindex contents of archive +Display a @emph{table} listing the contents of @var{archive}, or those +of the files listed in @var{member}@dots{} that are present in the +archive. Normally only the member name is shown; if you also want to +see the modes (permissions), timestamp, owner, group, and size, you can +request that by also specifying the @samp{v} modifier. + +If you do not specify a @var{member}, all files in the archive +are listed. + +@cindex repeated names in archive +@cindex name duplication in archive +If there is more than one file with the same name (say, @samp{fie}) in +an archive (say @samp{b.a}), @samp{ar t b.a fie} lists only the +first instance; to see them all, you must ask for a complete +listing---in our example, @samp{ar t b.a}. +@c WRS only; per Gumby, this is implementation-dependent, and in a more +@c recent case in fact works the other way. + +@item x +@cindex extract from archive +@emph{Extract} members (named @var{member}) from the archive. You can +use the @samp{v} modifier with this operation, to request that +@code{ar} list each name as it extracts it. + +If you do not specify a @var{member}, all files in the archive +are extracted. + +@end table + +A number of modifiers (@var{mod}) may immediately follow the @var{p} +keyletter, to specify variations on an operation's behavior: + +@table @code +@item a +@cindex relative placement in archive +Add new files @emph{after} an existing member of the +archive. If you use the modifier @samp{a}, the name of an existing archive +member must be present as the @var{relpos} argument, before the +@var{archive} specification. + +@item b +Add new files @emph{before} an existing member of the +archive. If you use the modifier @samp{b}, the name of an existing archive +member must be present as the @var{relpos} argument, before the +@var{archive} specification. (same as @samp{i}). + +@item c +@cindex creating archives +@emph{Create} the archive. The specified @var{archive} is always +created if it did not exist, when you request an update. But a warning is +issued unless you specify in advance that you expect to create it, by +using this modifier. + +@item f +Truncate names in the archive. @sc{gnu} @code{ar} will normally permit file +names of any length. This will cause it to create archives which are +not compatible with the native @code{ar} program on some systems. If +this is a concern, the @samp{f} modifier may be used to truncate file +names when putting them in the archive. + +@item i +Insert new files @emph{before} an existing member of the +archive. If you use the modifier @samp{i}, the name of an existing archive +member must be present as the @var{relpos} argument, before the +@var{archive} specification. (same as @samp{b}). + +@item l +This modifier is accepted but not used. +@c whaffor ar l modifier??? presumably compat; with +@c what???---doc@@cygnus.com, 25jan91 + +@item o +@cindex dates in archive +Preserve the @emph{original} dates of members when extracting them. If +you do not specify this modifier, files extracted from the archive +are stamped with the time of extraction. + +@item s +@cindex writing archive index +Write an object-file index into the archive, or update an existing one, +even if no other change is made to the archive. You may use this modifier +flag either with any operation, or alone. Running @samp{ar s} on an +archive is equivalent to running @samp{ranlib} on it. + +@item S +@cindex not writing archive index +Do not generate an archive symbol table. This can speed up building a +large library in several steps. The resulting archive can not be used +with the linker. In order to build a symbol table, you must omit the +@samp{S} modifier on the last execution of @samp{ar}, or you must run +@samp{ranlib} on the archive. + +@item u +@cindex updating an archive +Normally, @samp{ar r}@dots{} inserts all files +listed into the archive. If you would like to insert @emph{only} those +of the files you list that are newer than existing members of the same +names, use this modifier. The @samp{u} modifier is allowed only for the +operation @samp{r} (replace). In particular, the combination @samp{qu} is +not allowed, since checking the timestamps would lose any speed +advantage from the operation @samp{q}. + +@item v +This modifier requests the @emph{verbose} version of an operation. Many +operations display additional information, such as filenames processed, +when the modifier @samp{v} is appended. + +@item V +This modifier shows the version number of @code{ar}. +@end table + +@node ar scripts +@section Controlling @code{ar} with a script + +@smallexample +ar -M [ <@var{script} ] +@end smallexample + +@cindex MRI compatibility, @code{ar} +@cindex scripts, @code{ar} +If you use the single command-line option @samp{-M} with @code{ar}, you +can control its operation with a rudimentary command language. This +form of @code{ar} operates interactively if standard input is coming +directly from a terminal. During interactive use, @code{ar} prompts for +input (the prompt is @samp{AR >}), and continues executing even after +errors. If you redirect standard input to a script file, no prompts are +issued, and @code{ar} abandons execution (with a nonzero exit code) +on any error. + +The @code{ar} command language is @emph{not} designed to be equivalent +to the command-line options; in fact, it provides somewhat less control +over archives. The only purpose of the command language is to ease the +transition to @sc{gnu} @code{ar} for developers who already have scripts +written for the MRI ``librarian'' program. + +The syntax for the @code{ar} command language is straightforward: +@itemize @bullet +@item +commands are recognized in upper or lower case; for example, @code{LIST} +is the same as @code{list}. In the following descriptions, commands are +shown in upper case for clarity. + +@item +a single command may appear on each line; it is the first word on the +line. + +@item +empty lines are allowed, and have no effect. + +@item +comments are allowed; text after either of the characters @samp{*} +or @samp{;} is ignored. + +@item +Whenever you use a list of names as part of the argument to an @code{ar} +command, you can separate the individual names with either commas or +blanks. Commas are shown in the explanations below, for clarity. + +@item +@samp{+} is used as a line continuation character; if @samp{+} appears +at the end of a line, the text on the following line is considered part +of the current command. +@end itemize + +Here are the commands you can use in @code{ar} scripts, or when using +@code{ar} interactively. Three of them have special significance: + +@code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is +a temporary file required for most of the other commands. + +@code{SAVE} commits the changes so far specified by the script. Prior +to @code{SAVE}, commands affect only the temporary copy of the current +archive. + +@table @code +@item ADDLIB @var{archive} +@itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module}) +Add all the contents of @var{archive} (or, if specified, each named +@var{module} from @var{archive}) to the current archive. + +Requires prior use of @code{OPEN} or @code{CREATE}. + +@item ADDMOD @var{member}, @var{member}, @dots{} @var{member} +@c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}" +@c else like "ar q..." +Add each named @var{member} as a module in the current archive. + +Requires prior use of @code{OPEN} or @code{CREATE}. + +@item CLEAR +Discard the contents of the current archive, canceling the effect of +any operations since the last @code{SAVE}. May be executed (with no +effect) even if no current archive is specified. + +@item CREATE @var{archive} +Creates an archive, and makes it the current archive (required for many +other commands). The new archive is created with a temporary name; it +is not actually saved as @var{archive} until you use @code{SAVE}. +You can overwrite existing archives; similarly, the contents of any +existing file named @var{archive} will not be destroyed until @code{SAVE}. + +@item DELETE @var{module}, @var{module}, @dots{} @var{module} +Delete each listed @var{module} from the current archive; equivalent to +@samp{ar -d @var{archive} @var{module} @dots{} @var{module}}. + +Requires prior use of @code{OPEN} or @code{CREATE}. + +@item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) +@itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile} +List each named @var{module} present in @var{archive}. The separate +command @code{VERBOSE} specifies the form of the output: when verbose +output is off, output is like that of @samp{ar -t @var{archive} +@var{module}@dots{}}. When verbose output is on, the listing is like +@samp{ar -tv @var{archive} @var{module}@dots{}}. + +Output normally goes to the standard output stream; however, if you +specify @var{outputfile} as a final argument, @code{ar} directs the +output to that file. + +@item END +Exit from @code{ar}, with a @code{0} exit code to indicate successful +completion. This command does not save the output file; if you have +changed the current archive since the last @code{SAVE} command, those +changes are lost. + +@item EXTRACT @var{module}, @var{module}, @dots{} @var{module} +Extract each named @var{module} from the current archive, writing them +into the current directory as separate files. Equivalent to @samp{ar -x +@var{archive} @var{module}@dots{}}. + +Requires prior use of @code{OPEN} or @code{CREATE}. + +@ignore +@c FIXME Tokens but no commands??? +@item FULLDIR + +@item HELP +@end ignore + +@item LIST +Display full contents of the current archive, in ``verbose'' style +regardless of the state of @code{VERBOSE}. The effect is like @samp{ar +tv @var{archive}}). (This single command is a @sc{gnu} @code{ld} +enhancement, rather than present for MRI compatibility.) + +Requires prior use of @code{OPEN} or @code{CREATE}. + +@item OPEN @var{archive} +Opens an existing archive for use as the current archive (required for +many other commands). Any changes as the result of subsequent commands +will not actually affect @var{archive} until you next use @code{SAVE}. + +@item REPLACE @var{module}, @var{module}, @dots{} @var{module} +In the current archive, replace each existing @var{module} (named in +the @code{REPLACE} arguments) from files in the current working directory. +To execute this command without errors, both the file, and the module in +the current archive, must exist. + +Requires prior use of @code{OPEN} or @code{CREATE}. + +@item VERBOSE +Toggle an internal flag governing the output from @code{DIRECTORY}. +When the flag is on, @code{DIRECTORY} output matches output from +@samp{ar -tv }@dots{}. + +@item SAVE +Commit your changes to the current archive, and actually save it as a +file with the name specified in the last @code{CREATE} or @code{OPEN} +command. + +Requires prior use of @code{OPEN} or @code{CREATE}. + +@end table + +@iftex +@node ld +@chapter ld +@cindex linker +@kindex ld +The @sc{gnu} linker @code{ld} is now described in a separate manual. +@xref{Top,, Overview,, Using LD: the @sc{gnu} linker}. +@end iftex + +@node nm +@chapter nm +@cindex symbols +@kindex nm + +@smallexample +nm [ -a | --debug-syms ] [ -g | --extern-only ] + [ -B ] [ -C | --demangle ] [ -D | --dynamic ] + [ -s | --print-armap ] [ -A | -o | --print-file-name ] + [ -n | -v | --numeric-sort ] [ -p | --no-sort ] + [ -r | --reverse-sort ] [ --size-sort ] [ -u | --undefined-only ] + [ -t @var{radix} | --radix=@var{radix} ] [ -P | --portability ] + [ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ] + [ --defined-only ] [-l | --line-numbers ] + [ --no-demangle ] [ -V | --version ] [ --help ] [ @var{objfile}@dots{} ] +@end smallexample + +@sc{gnu} @code{nm} lists the symbols from object files @var{objfile}@dots{}. +If no object files are listed as arguments, @code{nm} assumes +@file{a.out}. + +For each symbol, @code{nm} shows: + +@itemize @bullet +@item +The symbol value, in the radix selected by options (see below), or +hexadecimal by default. + +@item +The symbol type. At least the following types are used; others are, as +well, depending on the object file format. If lowercase, the symbol is +local; if uppercase, the symbol is global (external). + +@c Some more detail on exactly what these symbol types are used for +@c would be nice. +@table @code +@item A +The symbol's value is absolute, and will not be changed by further +linking. + +@item B +The symbol is in the uninitialized data section (known as BSS). + +@item C +The symbol is common. Common symbols are uninitialized data. When +linking, multiple common symbols may appear with the same name. If the +symbol is defined anywhere, the common symbols are treated as undefined +references. For more details on common symbols, see the discussion of +--warn-common in @ref{Options,,Linker options,ld.info,The GNU linker}. + +@item D +The symbol is in the initialized data section. + +@item G +The symbol is in an initialized data section for small objects. Some +object file formats permit more efficient access to small data objects, +such as a global int variable as opposed to a large global array. + +@item I +The symbol is an indirect reference to another symbol. This is a GNU +extension to the a.out object file format which is rarely used. + +@item N +The symbol is a debugging symbol. + +@item R +The symbol is in a read only data section. + +@item S +The symbol is in an uninitialized data section for small objects. + +@item T +The symbol is in the text (code) section. + +@item U +The symbol is undefined. + +@item W +The symbol is weak. When a weak defined symbol is linked with a normal +defined symbol, the normal defined symbol is used with no error. When a +weak undefined symbol is linked and the symbol is not defined, the value +of the weak symbol becomes zero with no error. + +@item - +The symbol is a stabs symbol in an a.out object file. In this case, the +next values printed are the stabs other field, the stabs desc field, and +the stab type. Stabs symbols are used to hold debugging information; +for more information, see @ref{Top,Stabs,Stabs Overview,stabs.info, The +``stabs'' debug format}. + +@item ? +The symbol type is unknown, or object file format specific. +@end table + +@item +The symbol name. +@end itemize + +The long and short forms of options, shown here as alternatives, are +equivalent. + +@table @code +@item -A +@itemx -o +@itemx --print-file-name +@cindex input file name +@cindex file name +@cindex source file name +Precede each symbol by the name of the input file (or archive element) +in which it was found, rather than identifying the input file once only, +before all of its symbols. + +@item -a +@itemx --debug-syms +@cindex debugging symbols +Display all symbols, even debugger-only symbols; normally these are not +listed. + +@item -B +@cindex @code{nm} format +@cindex @code{nm} compatibility +The same as @samp{--format=bsd} (for compatibility with the MIPS @code{nm}). + +@item -C +@itemx --demangle +@cindex demangling in nm +Decode (@dfn{demangle}) low-level symbol names into user-level names. +Besides removing any initial underscore prepended by the system, this +makes C++ function names readable. @xref{c++filt}, for more information +on demangling. + +@item --no-demangle +Do not demangle low-level symbol names. This is the default. + +@item -D +@itemx --dynamic +@cindex dynamic symbols +Display the dynamic symbols rather than the normal symbols. This is +only meaningful for dynamic objects, such as certain types of shared +libraries. + +@item -f @var{format} +@itemx --format=@var{format} +@cindex @code{nm} format +@cindex @code{nm} compatibility +Use the output format @var{format}, which can be @code{bsd}, +@code{sysv}, or @code{posix}. The default is @code{bsd}. +Only the first character of @var{format} is significant; it can be +either upper or lower case. + +@item -g +@itemx --extern-only +@cindex external symbols +Display only external symbols. + +@item -l +@itemx --line-numbers +@cindex symbol line numbers +For each symbol, use debugging information to try to find a filename and +line number. For a defined symbol, look for the line number of the +address of the symbol. For an undefined symbol, look for the line +number of a relocation entry which refers to the symbol. If line number +information can be found, print it after the other symbol information. + +@item -n +@itemx -v +@itemx --numeric-sort +Sort symbols numerically by their addresses, rather than alphabetically +by their names. + +@item -p +@itemx --no-sort +@cindex sorting symbols +Do not bother to sort the symbols in any order; print them in the order +encountered. + +@item -P +@itemx --portability +Use the POSIX.2 standard output format instead of the default format. +Equivalent to @samp{-f posix}. + +@item -s +@itemx --print-armap +@cindex symbol index, listing +When listing symbols from archive members, include the index: a mapping +(stored in the archive by @code{ar} or @code{ranlib}) of which modules +contain definitions for which names. + +@item -r +@itemx --reverse-sort +Reverse the order of the sort (whether numeric or alphabetic); let the +last come first. + +@item --size-sort +Sort symbols by size. The size is computed as the difference between +the value of the symbol and the value of the symbol with the next higher +value. The size of the symbol is printed, rather than the value. + +@item -t @var{radix} +@itemx --radix=@var{radix} +Use @var{radix} as the radix for printing the symbol values. It must be +@samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal. + +@item --target=@var{bfdname} +@cindex object code format +Specify an object code format other than your system's default format. +@xref{Target Selection}, for more information. + +@item -u +@itemx --undefined-only +@cindex external symbols +@cindex undefined symbols +Display only undefined symbols (those external to each object file). + +@item --defined-only +@cindex external symbols +@cindex undefined symbols +Display only defined symbols for each object file. + +@item -V +@itemx --version +Show the version number of @code{nm} and exit. + +@item --help +Show a summary of the options to @code{nm} and exit. +@end table + +@node objcopy +@chapter objcopy + +@smallexample +objcopy [ -F @var{bfdname} | --target=@var{bfdname} ] + [ -I @var{bfdname} | --input-target=@var{bfdname} ] + [ -O @var{bfdname} | --output-target=@var{bfdname} ] + [ -S | --strip-all ] [ -g | --strip-debug ] + [ -K @var{symbolname} | --keep-symbol=@var{symbolname} ] + [ -N @var{symbolname} | --strip-symbol=@var{symbolname} ] + [ -L @var{symbolname} | --localize-symbol=@var{symbolname} ] + [ -W @var{symbolname} | --weaken-symbol=@var{symbolname} ] + [ -x | --discard-all ] [ -X | --discard-locals ] + [ -b @var{byte} | --byte=@var{byte} ] + [ -i @var{interleave} | --interleave=@var{interleave} ] + [ -R @var{sectionname} | --remove-section=@var{sectionname} ] + [ -p | --preserve-dates ] [ --debugging ] + [ --gap-fill=@var{val} ] [ --pad-to=@var{address} ] + [ --set-start=@var{val} ] [ --adjust-start=@var{incr} ] + [ --change-addresses=@var{incr} ] + [ --change-section-address=@var{section}@{=,+,-@}@var{val} ] + [ --change-section-lma=@var{section}@{=,+,-@}@var{val} ] + [ --change-section-vma=@var{section}@{=,+,-@}@var{val} ] + [ --change-warnings ] [ --no-change-warnings ] + [ --set-section-flags=@var{section}=@var{flags} ] + [ --add-section=@var{sectionname}=@var{filename} ] + [ --change-leading-char ] [ --remove-leading-char ] + [ --weaken ] + [ -v | --verbose ] [ -V | --version ] [ --help ] + @var{infile} [@var{outfile}] +@end smallexample + +The @sc{gnu} @code{objcopy} utility copies the contents of an object +file to another. @code{objcopy} uses the @sc{gnu} @sc{bfd} Library to +read and write the object files. It can write the destination object +file in a format different from that of the source object file. The +exact behavior of @code{objcopy} is controlled by command-line options. + +@code{objcopy} creates temporary files to do its translations and +deletes them afterward. @code{objcopy} uses @sc{bfd} to do all its +translation work; it has access to all the formats described in @sc{bfd} +and thus is able to recognize most formats without being told +explicitly. @xref{BFD,,BFD,ld.info,Using LD}. + +@code{objcopy} can be used to generate S-records by using an output +target of @samp{srec} (e.g., use @samp{-O srec}). + +@code{objcopy} can be used to generate a raw binary file by using an +output target of @samp{binary} (e.g., use @samp{-O binary}). When +@code{objcopy} generates a raw binary file, it will essentially produce +a memory dump of the contents of the input object file. All symbols and +relocation information will be discarded. The memory dump will start at +the load address of the lowest section copied into the output file. + +When generating an S-record or a raw binary file, it may be helpful to +use @samp{-S} to remove sections containing debugging information. In +some cases @samp{-R} will be useful to remove sections which contain +information which is not needed by the binary file. + +@table @code +@item @var{infile} +@itemx @var{outfile} +The source and output files, respectively. +If you do not specify @var{outfile}, @code{objcopy} creates a +temporary file and destructively renames the result with +the name of @var{infile}. + +@item -I @var{bfdname} +@itemx --input-target=@var{bfdname} +Consider the source file's object format to be @var{bfdname}, rather than +attempting to deduce it. @xref{Target Selection}, for more information. + +@item -O @var{bfdname} +@itemx --output-target=@var{bfdname} +Write the output file using the object format @var{bfdname}. +@xref{Target Selection}, for more information. + +@item -F @var{bfdname} +@itemx --target=@var{bfdname} +Use @var{bfdname} as the object format for both the input and the output +file; i.e., simply transfer data from source to destination with no +translation. @xref{Target Selection}, for more information. + +@item -R @var{sectionname} +@itemx --remove-section=@var{sectionname} +Remove any section named @var{sectionname} from the output file. This +option may be given more than once. Note that using this option +inappropriately may make the output file unusable. + +@item -S +@itemx --strip-all +Do not copy relocation and symbol information from the source file. + +@item -g +@itemx --strip-debug +Do not copy debugging symbols from the source file. + +@item --strip-unneeded +Strip all symbols that are not needed for relocation processing. + +@item -K @var{symbolname} +@itemx --keep-symbol=@var{symbolname} +Copy only symbol @var{symbolname} from the source file. This option may +be given more than once. + +@item -N @var{symbolname} +@itemx --strip-symbol=@var{symbolname} +Do not copy symbol @var{symbolname} from the source file. This option +may be given more than once. + +@item -L @var{symbolname} +@itemx --localize-symbol=@var{symbolname} +Make symbol @var{symbolname} local to the file, so that it is not +visible externally. This option may be given more than once. + +@item -W @var{symbolname} +@itemx --weaken-symbol=@var{symbolname} +Make symbol @var{symbolname} weak. This option may be given more than once. + +@item -x +@itemx --discard-all +Do not copy non-global symbols from the source file. +@c FIXME any reason to prefer "non-global" to "local" here? + +@item -X +@itemx --discard-locals +Do not copy compiler-generated local symbols. +(These usually start with @samp{L} or @samp{.}.) + +@item -b @var{byte} +@itemx --byte=@var{byte} +Keep only every @var{byte}th byte of the input file (header data is not +affected). @var{byte} can be in the range from 0 to @var{interleave}-1, +where @var{interleave} is given by the @samp{-i} or @samp{--interleave} +option, or the default of 4. This option is useful for creating files +to program @sc{rom}. It is typically used with an @code{srec} output +target. + +@item -i @var{interleave} +@itemx --interleave=@var{interleave} +Only copy one out of every @var{interleave} bytes. Select which byte to +copy with the @var{-b} or @samp{--byte} option. The default is 4. +@code{objcopy} ignores this option if you do not specify either @samp{-b} or +@samp{--byte}. + +@item -p +@itemx --preserve-dates +Set the access and modification dates of the output file to be the same +as those of the input file. + +@item --debugging +Convert debugging information, if possible. This is not the default +because only certain debugging formats are supported, and the +conversion process can be time consuming. + +@item --gap-fill @var{val} +Fill gaps between sections with @var{val}. This operation applies to +the @emph{load address} (LMA) of the sections. It is done by increasing +the size of the section with the lower address, and filling in the extra +space created with @var{val}. + +@item --pad-to @var{address} +Pad the output file up to the load address @var{address}. This is +done by increasing the size of the last section. The extra space is +filled in with the value specified by @samp{--gap-fill} (default zero). + +@item --set-start @var{val} +Set the address of the new file to @var{val}. Not all object file +formats support setting the start address. + +@item --change-start @var{incr} +@itemx --adjust-start @var{incr} +@cindex changing start address +Change the start address by adding @var{incr}. Not all object file +formats support setting the start address. + +@item --change-addresses @var{incr} +@itemx --adjust-vma @var{incr} +@cindex changing object addresses +Change the VMA and LMA addresses of all sections, as well as the start +address, by adding @var{incr}. Some object file formats do not permit +section addresses to be changed arbitrarily. Note that this does not +relocate the sections; if the program expects sections to be loaded at a +certain address, and this option is used to change the sections such +that they are loaded at a different address, the program may fail. + +@item --change-section-address @var{section}@{=,+,-@}@var{val} +@itemx --adjust-section-vma @var{section}@{=,+,-@}@var{val} +@cindex changing section address +Set or change both the VMA address and the LMA address of the named +@var{section}. If @samp{=} is used, the section address is set to +@var{val}. Otherwise, @var{val} is added to or subtracted from the +section address. See the comments under @samp{--change-addresses}, +above. If @var{section} does not exist in the input file, a warning will +be issued, unless @samp{--no-change-warnings} is used. + +@item --change-section-lma @var{section}@{=,+,-@}@var{val} +@cindex changing section LMA +Set or change the LMA address of the named @var{section}. The LMA +address is the address where the section will be loaded into memory at +program load time. Normally this is the same as the VMA address, which +is the address of the section at program run time, but on some systems, +especially those where a program is held in ROM, the two can be +different. If @samp{=} is used, the section address is set to +@var{val}. Otherwise, @var{val} is added to or subtracted from the +section address. See the comments under @samp{--change-addresses}, +above. If @var{section} does not exist in the input file, a warning +will be issued, unless @samp{--no-change-warnings} is used. + +@item --change-section-vma @var{section}@{=,+,-@}@var{val} +@cindex changing section VMA +Set or change the VMA address of the named @var{section}. The VMA +address is the address where the section will be located once the +program has started executing. Normally this is the same as the LMA +address, which is the address where the section will be loaded into +memory, but on some systems, especially those where a program is held in +ROM, the two can be different. If @samp{=} is used, the section address +is set to @var{val}. Otherwise, @var{val} is added to or subtracted +from the section address. See the comments under +@samp{--change-addresses}, above. If @var{section} does not exist in +the input file, a warning will be issued, unless +@samp{--no-change-warnings} is used. + +@item --change-warnings +@itemx --adjust-warnings +If @samp{--change-section-address} or @samp{--change-section-lma} or +@samp{--change-section-vma} is used, and the named section does not +exist, issue a warning. This is the default. + +@item --no-change-warnings +@itemx --no-adjust-warnings +Do not issue a warning if @samp{--change-section-address} or +@samp{--adjust-section-lma} or @samp{--adjust-section-vma} is used, even +if the named section does not exist. + +@item --set-section-flags @var{section}=@var{flags} +Set the flags for the named section. The @var{flags} argument is a +comma separated string of flag names. The recognized names are +@samp{alloc}, @samp{contents}, @samp{load}, @samp{readonly}, +@samp{code}, @samp{data}, and @samp{rom}. You can set the +@samp{contents} flag for a section which does not have contents, but it +is not meaningful to clear the @samp{contents} flag of a section which +does have contents--just remove the section instead. Not all flags are +meaningful for all object file formats. + +@item --add-section @var{sectionname}=@var{filename} +Add a new section named @var{sectionname} while copying the file. The +contents of the new section are taken from the file @var{filename}. The +size of the section will be the size of the file. This option only +works on file formats which can support sections with arbitrary names. + +@item --change-leading-char +Some object file formats use special characters at the start of +symbols. The most common such character is underscore, which compilers +often add before every symbol. This option tells @code{objcopy} to +change the leading character of every symbol when it converts between +object file formats. If the object file formats use the same leading +character, this option has no effect. Otherwise, it will add a +character, or remove a character, or change a character, as +appropriate. + +@item --remove-leading-char +If the first character of a global symbol is a special symbol leading +character used by the object file format, remove the character. The +most common symbol leading character is underscore. This option will +remove a leading underscore from all global symbols. This can be useful +if you want to link together objects of different file formats with +different conventions for symbol names. This is different from +@code{--change-leading-char} because it always changes the symbol name +when appropriate, regardless of the object file format of the output +file. + +@item --weaken +Change all global symbols in the file to be weak. This can be useful +when building an object which will be linked against other objects using +the @code{-R} option to the linker. This option is only effective when +using an object file format which supports weak symbols. + +@item -V +@itemx --version +Show the version number of @code{objcopy}. + +@item -v +@itemx --verbose +Verbose output: list all object files modified. In the case of +archives, @samp{objcopy -V} lists all members of the archive. + +@item --help +Show a summary of the options to @code{objcopy}. +@end table + +@node objdump +@chapter objdump + +@cindex object file information +@kindex objdump + +@smallexample +objdump [ -a | --archive-headers ] + [ -b @var{bfdname} | --target=@var{bfdname} ] [ --debugging ] + [ -C | --demangle ] [ -d | --disassemble ] + [ -D | --disassemble-all ] [ --disassemble-zeroes ] + [ -EB | -EL | --endian=@{big | little @} ] + [ -f | --file-headers ] + [ -h | --section-headers | --headers ] [ -i | --info ] + [ -j @var{section} | --section=@var{section} ] + [ -l | --line-numbers ] [ -S | --source ] + [ -m @var{machine} | --architecture=@var{machine} ] + [ -p | --private-headers ] + [ -r | --reloc ] [ -R | --dynamic-reloc ] + [ -s | --full-contents ] [ --stabs ] + [ -t | --syms ] [ -T | --dynamic-syms ] [ -x | --all-headers ] + [ -w | --wide ] [ --start-address=@var{address} ] + [ --stop-address=@var{address} ] + [ --prefix-addresses] [ --[no-]show-raw-insn ] + [ --adjust-vma=@var{offset} ] + [ --version ] [ --help ] + @var{objfile}@dots{} +@end smallexample + +@code{objdump} displays information about one or more object files. +The options control what particular information to display. This +information is mostly useful to programmers who are working on the +compilation tools, as opposed to programmers who just want their +program to compile and work. + +@var{objfile}@dots{} are the object files to be examined. When you +specify archives, @code{objdump} shows information on each of the member +object files. + +The long and short forms of options, shown here as alternatives, are +equivalent. At least one option besides @samp{-l} must be given. + +@table @code +@item -a +@itemx --archive-header +@cindex archive headers +If any of the @var{objfile} files are archives, display the archive +header information (in a format similar to @samp{ls -l}). Besides the +information you could list with @samp{ar tv}, @samp{objdump -a} shows +the object file format of each archive member. + +@item --adjust-vma=@var{offset} +@cindex section addresses in objdump +@cindex VMA in objdump +When dumping information, first add @var{offset} to all the section +addresses. This is useful if the section addresses do not correspond to +the symbol table, which can happen when putting sections at particular +addresses when using a format which can not represent section addresses, +such as a.out. + +@item -b @var{bfdname} +@itemx --target=@var{bfdname} +@cindex object code format +Specify that the object-code format for the object files is +@var{bfdname}. This option may not be necessary; @var{objdump} can +automatically recognize many formats. + +For example, +@example +objdump -b oasys -m vax -h fu.o +@end example +@noindent +displays summary information from the section headers (@samp{-h}) of +@file{fu.o}, which is explicitly identified (@samp{-m}) as a VAX object +file in the format produced by Oasys compilers. You can list the +formats available with the @samp{-i} option. +@xref{Target Selection}, for more information. + +@item -C +@itemx --demangle +@cindex demangling in objdump +Decode (@dfn{demangle}) low-level symbol names into user-level names. +Besides removing any initial underscore prepended by the system, this +makes C++ function names readable. @xref{c++filt}, for more information +on demangling. + +@item --debugging +Display debugging information. This attempts to parse debugging +information stored in the file and print it out using a C like syntax. +Only certain types of debugging information have been implemented. + +@item -d +@itemx --disassemble +@cindex disassembling object code +@cindex machine instructions +Display the assembler mnemonics for the machine instructions from +@var{objfile}. This option only disassembles those sections which are +expected to contain instructions. + +@item -D +@itemx --disassemble-all +Like @samp{-d}, but disassemble the contents of all sections, not just +those expected to contain instructions. + +@item --prefix-addresses +When disassembling, print the complete address on each line. This is +the older disassembly format. + +@item --disassemble-zeroes +Normally the disassembly output will skip blocks of zeroes. This +option directs the disassembler to disassemble those blocks, just like +any other data. + +@item -EB +@itemx -EL +@itemx --endian=@{big|little@} +@cindex endianness +@cindex disassembly endianness +Specify the endianness of the object files. This only affects +disassembly. This can be useful when disassembling a file format which +does not describe endianness information, such as S-records. + +@item -f +@itemx --file-header +@cindex object file header +Display summary information from the overall header of +each of the @var{objfile} files. + +@item -h +@itemx --section-header +@itemx --header +@cindex section headers +Display summary information from the section headers of the +object file. + +File segments may be relocated to nonstandard addresses, for example by +using the @samp{-Ttext}, @samp{-Tdata}, or @samp{-Tbss} options to +@code{ld}. However, some object file formats, such as a.out, do not +store the starting address of the file segments. In those situations, +although @code{ld} relocates the sections correctly, using @samp{objdump +-h} to list the file section headers cannot show the correct addresses. +Instead, it shows the usual addresses, which are implicit for the +target. + +@item --help +Print a summary of the options to @code{objdump} and exit. + +@item -i +@itemx --info +@cindex architectures available +@cindex object formats available +Display a list showing all architectures and object formats available +for specification with @samp{-b} or @samp{-m}. + +@item -j @var{name} +@itemx --section=@var{name} +@cindex section information +Display information only for section @var{name}. + +@item -l +@itemx --line-numbers +@cindex source filenames for object files +Label the display (using debugging information) with the filename and +source line numbers corresponding to the object code or relocs shown. +Only useful with @samp{-d}, @samp{-D}, or @samp{-r}. + +@item -m @var{machine} +@itemx --architecture=@var{machine} +@cindex architecture +@cindex disassembly architecture +Specify the architecture to use when disassembling object files. This +can be useful when disassembling object files which do not describe +architecture information, such as S-records. You can list the available +architectures with the @samp{-i} option. + +@item -p +@itemx --private-headers +Print information that is specific to the object file format. The exact +information printed depends upon the object file format. For some +object file formats, no additional information is printed. + +@item -r +@itemx --reloc +@cindex relocation entries, in object file +Print the relocation entries of the file. If used with @samp{-d} or +@samp{-D}, the relocations are printed interspersed with the +disassembly. + +@item -R +@itemx --dynamic-reloc +@cindex dynamic relocation entries, in object file +Print the dynamic relocation entries of the file. This is only +meaningful for dynamic objects, such as certain types of shared +libraries. + +@item -s +@itemx --full-contents +@cindex sections, full contents +@cindex object file sections +Display the full contents of any sections requested. + +@item -S +@itemx --source +@cindex source disassembly +@cindex disassembly, with source +Display source code intermixed with disassembly, if possible. Implies +@samp{-d}. + +@item --show-raw-insn +When disassembling instructions, print the instruction in hex as well as +in symbolic form. This is the default except when +@code{--prefix-addresses} is used. + +@item --no-show-raw-insn +When disassembling instructions, do not print the instruction bytes. +This is the default when @code{--prefix-addresses} is used. + +@item --stabs +@cindex stab +@cindex .stab +@cindex debug symbols +@cindex ELF object file format +Display the full contents of any sections requested. Display the +contents of the .stab and .stab.index and .stab.excl sections from an +ELF file. This is only useful on systems (such as Solaris 2.0) in which +@code{.stab} debugging symbol-table entries are carried in an ELF +section. In most other file formats, debugging symbol-table entries are +interleaved with linkage symbols, and are visible in the @samp{--syms} +output. For more information on stabs symbols, see @ref{Top,Stabs,Stabs +Overview,stabs.info, The ``stabs'' debug format}. + +@item --start-address=@var{address} +@cindex start-address +Start displaying data at the specified address. This affects the output +of the @code{-d}, @code{-r} and @code{-s} options. + +@item --stop-address=@var{address} +@cindex stop-address +Stop displaying data at the specified address. This affects the output +of the @code{-d}, @code{-r} and @code{-s} options. + +@item -t +@itemx --syms +@cindex symbol table entries, printing +Print the symbol table entries of the file. +This is similar to the information provided by the @samp{nm} program. + +@item -T +@itemx --dynamic-syms +@cindex dynamic symbol table entries, printing +Print the dynamic symbol table entries of the file. This is only +meaningful for dynamic objects, such as certain types of shared +libraries. This is similar to the information provided by the @samp{nm} +program when given the @samp{-D} (@samp{--dynamic}) option. + +@item --version +Print the version number of @code{objdump} and exit. + +@item -x +@itemx --all-header +@cindex all header information, object file +@cindex header information, all +Display all available header information, including the symbol table and +relocation entries. Using @samp{-x} is equivalent to specifying all of +@samp{-a -f -h -r -t}. + +@item -w +@itemx --wide +@cindex wide output, printing +Format some lines for output devices that have more than 80 columns. +@end table + +@node ranlib +@chapter ranlib + +@kindex ranlib +@cindex archive contents +@cindex symbol index + +@smallexample +ranlib [-vV] @var{archive} +@end smallexample + +@code{ranlib} generates an index to the contents of an archive and +stores it in the archive. The index lists each symbol defined by a +member of an archive that is a relocatable object file. + +You may use @samp{nm -s} or @samp{nm --print-armap} to list this index. + +An archive with such an index speeds up linking to the library and +allows routines in the library to call each other without regard to +their placement in the archive. + +The @sc{gnu} @code{ranlib} program is another form of @sc{gnu} @code{ar}; running +@code{ranlib} is completely equivalent to executing @samp{ar -s}. +@xref{ar}. + +@table @code +@item -v +@itemx -V +Show the version number of @code{ranlib}. +@end table + +@node size +@chapter size + +@kindex size +@cindex section sizes + +@smallexample +size [ -A | -B | --format=@var{compatibility} ] + [ --help ] [ -d | -o | -x | --radix=@var{number} ] + [ --target=@var{bfdname} ] [ -V | --version ] + [ @var{objfile}@dots{} ] +@end smallexample + +The @sc{gnu} @code{size} utility lists the section sizes---and the total +size---for each of the object or archive files @var{objfile} in its +argument list. By default, one line of output is generated for each +object file or each module in an archive. + +@var{objfile}@dots{} are the object files to be examined. +If none are specified, the file @code{a.out} will be used. + +The command line options have the following meanings: + +@table @code +@item -A +@itemx -B +@itemx --format=@var{compatibility} +@cindex @code{size} display format +Using one of these options, you can choose whether the output from @sc{gnu} +@code{size} resembles output from System V @code{size} (using @samp{-A}, +or @samp{--format=sysv}), or Berkeley @code{size} (using @samp{-B}, or +@samp{--format=berkeley}). The default is the one-line format similar to +Berkeley's. +@c Bonus for doc-source readers: you can also say --format=strange (or +@c anything else that starts with 's') for sysv, and --format=boring (or +@c anything else that starts with 'b') for Berkeley. + +Here is an example of the Berkeley (default) format of output from +@code{size}: +@smallexample +size --format=Berkeley ranlib size +text data bss dec hex filename +294880 81920 11592 388392 5ed28 ranlib +294880 81920 11888 388688 5ee50 size +@end smallexample + +@noindent +This is the same data, but displayed closer to System V conventions: + +@smallexample +size --format=SysV ranlib size +ranlib : +section size addr +.text 294880 8192 +.data 81920 303104 +.bss 11592 385024 +Total 388392 + + +size : +section size addr +.text 294880 8192 +.data 81920 303104 +.bss 11888 385024 +Total 388688 +@end smallexample + +@item --help +Show a summary of acceptable arguments and options. + +@item -d +@itemx -o +@itemx -x +@itemx --radix=@var{number} +@cindex @code{size} number format +@cindex radix for section sizes +Using one of these options, you can control whether the size of each +section is given in decimal (@samp{-d}, or @samp{--radix=10}); octal +(@samp{-o}, or @samp{--radix=8}); or hexadecimal (@samp{-x}, or +@samp{--radix=16}). In @samp{--radix=@var{number}}, only the three +values (8, 10, 16) are supported. The total size is always given in two +radices; decimal and hexadecimal for @samp{-d} or @samp{-x} output, or +octal and hexadecimal if you're using @samp{-o}. + +@item --target=@var{bfdname} +@cindex object code format +Specify that the object-code format for @var{objfile} is +@var{bfdname}. This option may not be necessary; @code{size} can +automatically recognize many formats. +@xref{Target Selection}, for more information. + +@item -V +@itemx --version +Display the version number of @code{size}. +@end table + +@node strings +@chapter strings +@kindex strings +@cindex listings strings +@cindex printing strings +@cindex strings, printing + +@smallexample +strings [-afov] [-@var{min-len}] [-n @var{min-len}] [-t @var{radix}] [-] + [--all] [--print-file-name] [--bytes=@var{min-len}] + [--radix=@var{radix}] [--target=@var{bfdname}] + [--help] [--version] @var{file}@dots{} +@end smallexample + +For each @var{file} given, @sc{gnu} @code{strings} prints the printable +character sequences that are at least 4 characters long (or the number +given with the options below) and are followed by an unprintable +character. By default, it only prints the strings from the initialized +and loaded sections of object files; for other types of files, it prints +the strings from the whole file. + +@code{strings} is mainly useful for determining the contents of non-text +files. + +@table @code +@item -a +@itemx --all +@itemx - +Do not scan only the initialized and loaded sections of object files; +scan the whole files. + +@item -f +@itemx --print-file-name +Print the name of the file before each string. + +@item --help +Print a summary of the program usage on the standard output and exit. + +@item -@var{min-len} +@itemx -n @var{min-len} +@itemx --bytes=@var{min-len} +Print sequences of characters that are at least @var{min-len} characters +long, instead of the default 4. + +@item -o +Like @samp{-t o}. Some other versions of @code{strings} have @samp{-o} +act like @samp{-t d} instead. Since we can not be compatible with both +ways, we simply chose one. + +@item -t @var{radix} +@itemx --radix=@var{radix} +Print the offset within the file before each string. The single +character argument specifies the radix of the offset---@samp{o} for +octal, @samp{x} for hexadecimal, or @samp{d} for decimal. + +@item --target=@var{bfdname} +@cindex object code format +Specify an object code format other than your system's default format. +@xref{Target Selection}, for more information. + +@item -v +@itemx --version +Print the program version number on the standard output and exit. +@end table + +@node strip +@chapter strip + +@kindex strip +@cindex removing symbols +@cindex discarding symbols +@cindex symbols, discarding + +@smallexample +strip [ -F @var{bfdname} | --target=@var{bfdname} ] + [ -I @var{bfdname} | --input-target=@var{bfdname} ] + [ -O @var{bfdname} | --output-target=@var{bfdname} ] + [ -s | --strip-all ] [ -S | -g | --strip-debug ] + [ -K @var{symbolname} | --keep-symbol=@var{symbolname} ] + [ -N @var{symbolname} | --strip-symbol=@var{symbolname} ] + [ -x | --discard-all ] [ -X | --discard-locals ] + [ -R @var{sectionname} | --remove-section=@var{sectionname} ] + [ -o @var{file} ] [ -p | --preserve-dates ] + [ -v | --verbose ] [ -V | --version ] [ --help ] + @var{objfile}@dots{} +@end smallexample + +@sc{gnu} @code{strip} discards all symbols from object files +@var{objfile}. The list of object files may include archives. +At least one object file must be given. + +@code{strip} modifies the files named in its argument, +rather than writing modified copies under different names. + +@table @code +@item -F @var{bfdname} +@itemx --target=@var{bfdname} +Treat the original @var{objfile} as a file with the object +code format @var{bfdname}, and rewrite it in the same format. +@xref{Target Selection}, for more information. + +@item --help +Show a summary of the options to @code{strip} and exit. + +@item -I @var{bfdname} +@itemx --input-target=@var{bfdname} +Treat the original @var{objfile} as a file with the object +code format @var{bfdname}. +@xref{Target Selection}, for more information. + +@item -O @var{bfdname} +@itemx --output-target=@var{bfdname} +Replace @var{objfile} with a file in the output format @var{bfdname}. +@xref{Target Selection}, for more information. + +@item -R @var{sectionname} +@itemx --remove-section=@var{sectionname} +Remove any section named @var{sectionname} from the output file. This +option may be given more than once. Note that using this option +inappropriately may make the output file unusable. + +@item -s +@itemx --strip-all +Remove all symbols. + +@item -g +@itemx -S +@itemx --strip-debug +Remove debugging symbols only. + +@item --strip-unneeded +Remove all symbols that are not needed for relocation processing. + +@item -K @var{symbolname} +@itemx --keep-symbol=@var{symbolname} +Keep only symbol @var{symbolname} from the source file. This option may +be given more than once. + +@item -N @var{symbolname} +@itemx --strip-symbol=@var{symbolname} +Remove symbol @var{symbolname} from the source file. This option may be +given more than once, and may be combined with strip options other than +@code{-K}. + +@item -o @var{file} +Put the stripped output in @var{file}, rather than replacing the +existing file. When this argument is used, only one @var{objfile} +argument may be specified. + +@item -p +@itemx --preserve-dates +Preserve the access and modification dates of the file. + +@item -x +@itemx --discard-all +Remove non-global symbols. + +@item -X +@itemx --discard-locals +Remove compiler-generated local symbols. +(These usually start with @samp{L} or @samp{.}.) + +@item -V +@itemx --version +Show the version number for @code{strip}. + +@item -v +@itemx --verbose +Verbose output: list all object files modified. In the case of +archives, @samp{strip -v} lists all members of the archive. +@end table + +@node c++filt +@chapter c++filt + +@kindex c++filt +@cindex demangling C++ symbols + +@smallexample +c++filt [ -_ | --strip-underscores ] + [ -j | --java ] + [ -n | --no-strip-underscores ] + [ -s @var{format} | --format=@var{format} ] + [ --help ] [ --version ] [ @var{symbol}@dots{} ] +@end smallexample + +The C++ and Java languages provides function overloading, which means +that you can write many functions with the same name (providing each +takes parameters of different types). All C++ and Java function names +are encoded into a low-level assembly label (this process is known as +@dfn{mangling}). The @code{c++filt} program does the inverse mapping: it +decodes (@dfn{demangles}) low-level names into user-level names so that +the linker can keep these overloaded functions from clashing. + +Every alphanumeric word (consisting of letters, digits, underscores, +dollars, or periods) seen in the input is a potential label. If the +label decodes into a C++ name, the C++ name replaces the low-level +name in the output. + +You can use @code{c++filt} to decipher individual symbols: + +@example +c++filt @var{symbol} +@end example + +If no @var{symbol} arguments are given, @code{c++filt} reads symbol +names from the standard input and writes the demangled names to the +standard output. All results are printed on the standard output. + +@table @code +@item -_ +@itemx --strip-underscores +On some systems, both the C and C++ compilers put an underscore in front +of every name. For example, the C name @code{foo} gets the low-level +name @code{_foo}. This option removes the initial underscore. Whether +@code{c++filt} removes the underscore by default is target dependent. + +@item -j +@itemx --java +Prints demangled names using Java syntax. The default is to use C++ +syntax. + +@item -n +@itemx --no-strip-underscores +Do not remove the initial underscore. + +@item -s @var{format} +@itemx --format=@var{format} +@sc{gnu} @code{nm} can decode three different methods of mangling, used by +different C++ compilers. The argument to this option selects which +method it uses: + +@table @code +@item gnu +the one used by the @sc{gnu} compiler (the default method) +@item lucid +the one used by the Lucid compiler +@item arm +the one specified by the C++ Annotated Reference Manual +@item hp +the one used by the HP compiler +@item edg +the one used by the EDG compiler +@end table + +@item --help +Print a summary of the options to @code{c++filt} and exit. + +@item --version +Print the version number of @code{c++filt} and exit. +@end table + +@quotation +@emph{Warning:} @code{c++filt} is a new utility, and the details of its +user interface are subject to change in future releases. In particular, +a command-line option may be required in the the future to decode a name +passed as an argument on the command line; in other words, + +@example +c++filt @var{symbol} +@end example + +@noindent +may in a future release become + +@example +c++filt @var{option} @var{symbol} +@end example +@end quotation + +@node addr2line +@chapter addr2line + +@kindex addr2line +@cindex address to file name and line number + +@smallexample +addr2line [ -b @var{bfdname} | --target=@var{bfdname} ] + [ -C | --demangle ] + [ -e @var{filename} | --exe=@var{filename} ] + [ -f | --functions ] [ -s | --basename ] + [ -H | --help ] [ -V | --version ] + [ addr addr ... ] +@end smallexample + +@code{addr2line} translates program addresses into file names and line +numbers. Given an address and an executable, it uses the debugging +information in the executable to figure out which file name and line +number are associated with a given address. + +The executable to use is specified with the @code{-e} option. The +default is @file{a.out}. + +@code{addr2line} has two modes of operation. + +In the first, hexadecimal addresses are specified on the command line, +and @code{addr2line} displays the file name and line number for each +address. + +In the second, @code{addr2line} reads hexadecimal addresses from +standard input, and prints the file name and line number for each +address on standard output. In this mode, @code{addr2line} may be used +in a pipe to convert dynamically chosen addresses. + +The format of the output is @samp{FILENAME:LINENO}. The file name and +line number for each address is printed on a separate line. If the +@code{-f} option is used, then each @samp{FILENAME:LINENO} line is +preceded by a @samp{FUNCTIONNAME} line which is the name of the function +containing the address. + +If the file name or function name can not be determined, +@code{addr2line} will print two question marks in their place. If the +line number can not be determined, @code{addr2line} will print 0. + +The long and short forms of options, shown here as alternatives, are +equivalent. + +@table @code +@item -b @var{bfdname} +@itemx --target=@var{bfdname} +@cindex object code format +Specify that the object-code format for the object files is +@var{bfdname}. + +@item -C +@itemx --demangle +@cindex demangling in objdump +Decode (@dfn{demangle}) low-level symbol names into user-level names. +Besides removing any initial underscore prepended by the system, this +makes C++ function names readable. @xref{c++filt}, for more information +on demangling. + +@item -e @var{filename} +@itemx --exe=@var{filename} +Specify the name of the executable for which addresses should be +translated. The default file is @file{a.out}. + +@item -f +@itemx --functions +Display function names as well as file and line number information. + +@item -s +@itemx --basenames +Display only the base of each file name. +@end table + +@node nlmconv +@chapter nlmconv + +@code{nlmconv} converts a relocatable object file into a NetWare +Loadable Module. + +@ignore +@code{nlmconv} currently works with @samp{i386} object +files in @code{coff}, @sc{elf}, or @code{a.out} format, and @sc{SPARC} +object files in @sc{elf}, or @code{a.out} format@footnote{ +@code{nlmconv} should work with any @samp{i386} or @sc{sparc} object +format in the Binary File Descriptor library. It has only been tested +with the above formats.}. +@end ignore + +@quotation +@emph{Warning:} @code{nlmconv} is not always built as part of the binary +utilities, since it is only useful for NLM targets. +@end quotation + +@smallexample +nlmconv [ -I @var{bfdname} | --input-target=@var{bfdname} ] + [ -O @var{bfdname} | --output-target=@var{bfdname} ] + [ -T @var{headerfile} | --header-file=@var{headerfile} ] + [ -d | --debug] [ -l @var{linker} | --linker=@var{linker} ] + [ -h | --help ] [ -V | --version ] + @var{infile} @var{outfile} +@end smallexample + +@code{nlmconv} converts the relocatable @samp{i386} object file +@var{infile} into the NetWare Loadable Module @var{outfile}, optionally +reading @var{headerfile} for NLM header information. For instructions +on writing the NLM command file language used in header files, see the +@samp{linkers} section, @samp{NLMLINK} in particular, of the @cite{NLM +Development and Tools Overview}, which is part of the NLM Software +Developer's Kit (``NLM SDK''), available from Novell, Inc. +@code{nlmconv} uses the @sc{gnu} Binary File Descriptor library to read +@var{infile}; see @ref{BFD,,BFD,ld.info,Using LD}, for +more information. + +@code{nlmconv} can perform a link step. In other words, you can list +more than one object file for input if you list them in the definitions +file (rather than simply specifying one input file on the command line). +In this case, @code{nlmconv} calls the linker for you. + +@table @code +@item -I @var{bfdname} +@itemx --input-target=@var{bfdname} +Object format of the input file. @code{nlmconv} can usually determine +the format of a given file (so no default is necessary). +@xref{Target Selection}, for more information. + +@item -O @var{bfdname} +@itemx --output-target=@var{bfdname} +Object format of the output file. @code{nlmconv} infers the output +format based on the input format, e.g. for a @samp{i386} input file the +output format is @samp{nlm32-i386}. +@xref{Target Selection}, for more information. + +@item -T @var{headerfile} +@itemx --header-file=@var{headerfile} +Reads @var{headerfile} for NLM header information. For instructions on +writing the NLM command file language used in header files, see@ see the +@samp{linkers} section, of the @cite{NLM Development and Tools +Overview}, which is part of the NLM Software Developer's Kit, available +from Novell, Inc. + +@item -d +@itemx --debug +Displays (on standard error) the linker command line used by @code{nlmconv}. + +@item -l @var{linker} +@itemx --linker=@var{linker} +Use @var{linker} for any linking. @var{linker} can be an absolute or a +relative pathname. + +@item -h +@itemx --help +Prints a usage summary. + +@item -V +@itemx --version +Prints the version number for @code{nlmconv}. +@end table + +@node windres +@chapter windres + +@code{windres} may be used to manipulate Windows resources. + +@quotation +@emph{Warning:} @code{windres} is not always built as part of the binary +utilities, since it is only useful for Windows targets. +@end quotation + +@smallexample +windres [options] [input-file] [output-file] +@end smallexample + +@code{windres} reads resources from an input file and copies them into +an output file. Either file may be in one of three formats: + +@table @code +@item rc +A text format read by the Resource Compiler. + +@item res +A binary format generated by the Resource Compiler. + +@item coff +A COFF object or executable. +@end table + +The exact description of these different formats is available in +documentation from Microsoft. + +When @code{windres} converts from the @code{rc} format to the @code{res} +format, it is acting like the Windows Resource Compiler. When +@code{windres} converts from the @code{res} format to the @code{coff} +format, it is acting like the Windows @code{CVTRES} program. + +When @code{windres} generates an @code{rc} file, the output is similar +but not identical to the format expected for the input. When an input +@code{rc} file refers to an external filename, an output @code{rc} file +will instead include the file contents. + +If the input or output format is not specified, @code{windres} will +guess based on the file name, or, for the input file, the file contents. +A file with an extension of @file{.rc} will be treated as an @code{rc} +file, a file with an extension of @file{.res} will be treated as a +@code{res} file, and a file with an extension of @file{.o} or +@file{.exe} will be treated as a @code{coff} file. + +If no output file is specified, @code{windres} will print the resources +in @code{rc} format to standard output. + +The normal use is for you to write an @code{rc} file, use @code{windres} +to convert it to a COFF object file, and then link the COFF file into +your application. This will make the resources described in the +@code{rc} file available to Windows. + +@table @code +@item -i @var{filename} +@itemx --input @var{filename} +The name of the input file. If this option is not used, then +@code{windres} will use the first non-option argument as the input file +name. If there are no non-option arguments, then @code{windres} will +read from standard input. @code{windres} can not read a COFF file from +standard input. + +@item -o @var{filename} +@itemx --output @var{filename} +The name of the output file. If this option is not used, then +@code{windres} will use the first non-option argument, after any used +for the input file name, as the output file name. If there is no +non-option argument, then @code{windres} will write to standard output. +@code{windres} can not write a COFF file to standard output. + +@item -I @var{format} +@itemx --input-format @var{format} +The input format to read. @var{format} may be @samp{res}, @samp{rc}, or +@samp{coff}. If no input format is specified, @code{windres} will +guess, as described above. + +@item -O @var{format} +@itemx --output-format @var{format} +The output format to generate. @var{format} may be @samp{res}, +@samp{rc}, or @samp{coff}. If no output format is specified, +@code{windres} will guess, as described above. + +@item -F @var{target} +@itemx --target @var{target} +Specify the BFD format to use for a COFF file as input or output. This +is a BFD target name; you can use the @code{--help} option to see a list +of supported targets. Normally @code{windres} will use the default +format, which is the first one listed by the @code{--help} option. +@ref{Target Selection}. + +@item --preprocessor @var{program} +When @code{windres} reads an @code{rc} file, it runs it through the C +preprocessor first. This option may be used to specify the preprocessor +to use, including any leading arguments. The default preprocessor +argument is @code{gcc -E -xc-header -DRC_INVOKED}. + +@item --include-dir @var{directory} +Specify an include directory to use when reading an @code{rc} file. +@code{windres} will pass this to the preprocessor as an @code{-I} +option. @code{windres} will also search this directory when looking for +files named in the @code{rc} file. + +@item --define @var{sym[=val]} +Specify a @code{-D} option to pass to the preprocessor when reading an +@code{rc} file. + +@item --language @var{val} +Specify the default language to use when reading an @code{rc} file. +@var{val} should be a hexadecimal language code. The low eight bits are +the language, and the high eight bits are the sublanguage. + +@item --help +Prints a usage summary. + +@item --version +Prints the version number for @code{windres}. + +@item --yydebug +If @code{windres} is compiled with @code{YYDEBUG} defined as @code{1}, +this will turn on parser debugging. +@end table + + +@node dlltool +@chapter Create files needed to build and use DLLs +@cindex DLL +@kindex dlltool + +@code{dlltool} may be used to create the files needed to build and use +dynamic link libraries (DLLs). + +@quotation +@emph{Warning:} @code{dlltool} is not always built as part of the binary +utilities, since it is only useful for those targets which support DLLs. +@end quotation + +@smallexample +dlltool [-d|--input-def @var{def-file-name}] + [-b|--base-file @var{base-file-name}] + [-e|--output-exp @var{exports-file-name}] + [-z|--output-def @var{def-file-name}] + [-l|--output-lib @var{library-file-name}] + [--export-all-symbols] [--no-export-all-symbols] + [--exclude-symbols @var{list}] + [--no-default-excludes] + [-S|--as @var{path-to-assembler}] [-f|--as-flags @var{options}] + [-D|--dllname @var{name}] [-m|--machine @var{machine}] + [-a|--add-indirect] [-U|--add-underscore] [-k|--kill-at] + [-A|--add-stdcall-alias] + [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork] + [-n|--nodelete] [-v|--verbose] [-h|--help] [-V|--version] + [object-file @dots{}] +@end smallexample + +@code{dlltool} reads its inputs, which can come from the @samp{-d} and +@samp{-b} options as well as object files specified on the command +line. It then processes these inputs and if the @samp{-e} option has +been specified it creates a exports file. If the @samp{-l} option +has been specified it creates a library file and if the @samp{-z} option +has been specified it creates a def file. Any or all of the -e, -l +and -z options can be present in one invocation of dlltool. + +When creating a DLL, along with the source for the DLL, it is necessary +to have three other files. @code{dlltool} can help with the creation of +these files. + +The first file is a @samp{.def} file which specifies which functions are +exported from the DLL, which functions the DLL imports, and so on. This +is a text file and can be created by hand, or @code{dlltool} can be used +to create it using the @samp{-z} option. In this case @code{dlltool} +will scan the object files specified on its command line looking for +those functions which have been specially marked as being exported and +put entries for them in the .def file it creates. + +In order to mark a function as being exported from a DLL, it needs to +have an @samp{-export:<name_of_function>} entry in the @samp{.drectve} +section of the object file. This can be done in C by using the +asm() operator: + +@smallexample + asm (".section .drectve"); + asm (".ascii \"-export:my_func\""); + + int my_func (void) @{ @dots{} @} +@end smallexample + +The second file needed for DLL creation is an exports file. This file +is linked with the object files that make up the body of the DLL and it +handles the interface between the DLL and the outside world. This is a +binary file and it can be created by giving the @samp{-e} option to +@code{dlltool} when it is creating or reading in a .def file. + +The third file needed for DLL creation is the library file that programs +will link with in order to access the functions in the DLL. This file +can be created by giving the @samp{-l} option to dlltool when it +is creating or reading in a .def file. + +@code{dlltool} builds the library file by hand, but it builds the +exports file by creating temporary files containing assembler statements +and then assembling these. The @samp{-S} command line option can be +used to specify the path to the assembler that dlltool will use, +and the @samp{-f} option can be used to pass specific flags to that +assembler. The @samp{-n} can be used to prevent dlltool from deleting +these temporary assembler files when it is done, and if @samp{-n} is +specified twice then this will prevent dlltool from deleting the +temporary object files it used to build the library. + +Here is an example of creating a DLL from a source file @samp{dll.c} and +also creating a program (from an object file called @samp{program.o}) +that uses that DLL: + +@smallexample + gcc -c dll.c + dlltool -e exports.o -l dll.lib dll.o + gcc dll.o exports.o -o dll.dll + gcc program.o dll.lib -o program +@end smallexample + +The command line options have the following meanings: + +@table @code + +@item -d @var{filename} +@itemx --input-def @var{filename} +@cindex input .def file +Specifies the name of a .def file to be read in and processed. + +@item -b @var{filename} +@itemx --base-file @var{filename} +@cindex base files +Specifies the name of a base file to be read in and processed. The +contents of this file will be added to the relocation section in the +exports file generated by dlltool. + +@item -e @var{filename} +@itemx --output-exp @var{filename} +Specifies the name of the export file to be created by dlltool. + +@item -z @var{filename} +@itemx --output-def @var{filename} +Specifies the name of the .def file to be created by dlltool. + +@item -l @var{filename} +@itemx --output-lib @var{filename} +Specifies the name of the library file to be created by dlltool. + +@item --export-all-symbols +Treat all global and weak defined symbols found in the input object +files as symbols to be exported. There is a small list of symbols which +are not exported by default; see the @code{--no-default-excludes} +option. You may add to the list of symbols to not export by using the +@code{--exclude-symbols} option. + +@item --no-export-all-symbols +Only export symbols explicitly listed in an input .def file or in +@samp{.drectve} sections in the input object files. This is the default +behaviour. The @samp{.drectve} sections are created by @samp{dllexport} +attributes in the source code. + +@item --exclude-symbols @var{list} +Do not export the symbols in @var{list}. This is a list of symbol names +separated by comma or colon characters. The symbol names should not +contain a leading underscore. This is only meaningful when +@code{--export-all-symbols} is used. + +@item --no-default-excludes +When @code{--export-all-symbols} is used, it will by default avoid +exporting certain special symbols. The current list of symbols to avoid +exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0}, +@samp{impure_ptr}. You may use the @code{--no-default-excludes} option +to go ahead and export these special symbols. This is only meaningful +when @code{--export-all-symbols} is used. + +@item -S @var{path} +@itemx --as @var{path} +Specifies the path, including the filename, of the assembler to be used +to create the exports file. + +@item -f @var{switches} +@itemx --as-flags @var{switches} +Specifies any specific command line switches to be passed to the +assembler when building the exports file. This option will work even if +the @samp{-S} option is not used. This option only takes one argument, +and if it occurs more than once on the command line, then later +occurrences will override earlier occurrences. So if it is necessary to +pass multiple switches to the assembler they should be enclosed in +double quotes. + +@item -D @var{name} +@itemx --dll-name @var{name} +Specifies the name to be stored in the .def file as the name of the DLL +when the @samp{-e} option is used. If this option is not present, then +the filename given to the @samp{-e} option will be used as the name of +the DLL. + +@item -m @var{machine} +@itemx -machine @var{machine} +Specifies the type of machine for which the library file should be +built. @code{dlltool} has a built in default type, depending upon how +it was created, but this option can be used to override that. This is +normally only useful when creating DLLs for an ARM processor, when the +contents of the DLL are actually encode using THUMB instructions. + +@item -a +@itemx --add-indirect +Specifies that when @code{dlltool} is creating the exports file it +should add a section which allows the exported functions to be +referenced without using the import library. Whatever the hell that +means! + +@item -U +@itemx --add-underscore +Specifies that when @code{dlltool} is creating the exports file it +should prepend an underscore to the names of the exported functions. + +@item -k +@itemx --kill-at +Specifies that when @code{dlltool} is creating the exports file it +should not append the string @samp{@@ <number>}. These numbers are +called ordinal numbers and they represent another way of accessing the +function in a DLL, other than by name. + +@item -A +@itemx --add-stdcall-alias +Specifies that when @code{dlltool} is creating the exports file it +should add aliases for stdcall symbols without @samp{@@ <number>} +in addition to the symbols with @samp{@@ <number>}. + +@item -x +@itemx --no-idata4 +Specifies that when @code{dlltool} is creating the exports and library +files it should omit the .idata4 section. This is for compatibility +with certain operating systems. + +@item -c +@itemx --no-idata5 +Specifies that when @code{dlltool} is creating the exports and library +files it should omit the .idata5 section. This is for compatibility +with certain operating systems. + +@item -i +@itemx --interwork +Specifies that @code{dlltool} should mark the objects in the library +file and exports file that it produces as supporting interworking +between ARM and THUMB code. + +@item -n +@itemx --nodelete +Makes @code{dlltool} preserve the temporary assembler files it used to +create the exports file. If this option is repeated then dlltool will +also preserve the temporary object files it uses to create the library +file. + +@item -v +@itemx --verbose +Make dlltool describe what it is doing. + +@item -h +@itemx --help +Displays a list of command line options and then exits. + +@item -V +@itemx --version +Displays dlltool's version number and then exits. + +@end table + +@node readelf +@chapter readelf + +@cindex ELF file information +@kindex readelf + +@smallexample +readelf [ -a | --all ] + [ -h | --file-header] + [ -l | --program-headers | --segments] + [ -S | --section-headers | --sections] + [ -e | --headers] + [ -s | --syms | --symbols] + [ -r | --relocs] + [ -d | --dynamic] + [ -V | --version-info] + [ -D | --use-dynamic] + [ -x <number> | --hex-dump=<number>] + [ -w[liapr] | --debug-dump[=info,=line,=abbrev,=pubnames,=ranges]] + [ --histogram] + [ -v | --version] + [ -H | --help] + @var{elffile}@dots{} +@end smallexample + +@code{readelf} displays information about one or more ELF format object +files. The options control what particular information to display. + +@var{elffile}@dots{} are the object files to be examined. At the +moment, @code{readelf} does not support examining archives, nor does it +support examing 64 bit ELF files. + +The long and short forms of options, shown here as alternatives, are +equivalent. At least one option besides @samp{-v} or @samp{-H} must be +given. + +@table @code +@item -a +@itemx --all +Equivalent to specifiying @samp{--file-header}, +@samp{--program-headers}, @samp{--sections}, @samp{--symbols}, +@samp{--relocs}, @samp{--dynamic} and @samp{--version-info}. + +@item -h +@itemx --file-header +@cindex ELF file header information +Displays the information contained in the ELF header at the start of the +file. + +@item -l +@itemx --program-headers +@itemx --segments +@cindex ELF program header information +@cindex ELF segment information +Displays the information contained in the file's segment headers, if it +has any. + +@item -S +@itemx --sections +@itemx --section-headers +@cindex ELF section information +Displays the information contained in the file's section headers, if it +has any. + +@item -s +@itemx --symbols +@itemx --syms +@cindex ELF symbol table information +Displays the entries in symbol table section of the file, if it has one. + +@item -e +@itemx --headers +Display all the headers in the file. Equivalent to @samp{-h -l -S}. + +@item -r +@itemx --relocs +@cindex ELF reloc information +Displays the contents of the file's relocation section, if it ha one. + +@item -d +@itemx --dynamic +@cindex ELF dynamic section information +Displays the contents of the file's dynamic section, if it has one. + +@item -V +@itemx --version-info +@cindex ELF version sections informations +Displays the contents of the version sections in the file, it they +exist. + +@item -D +@itemx --use-dynamic +When displaying symbols, this option makes @code{readelf} use the +symblol table in the file's dynamic section, rather than the one in the +symbols section. + +@item -x <number> +@itemx --hex-dump=<number> +Displays the contents of the indicated section as a hexadecimal dump. + +@item -w[liapr] +@itemx --debug-dump[=line,=info,=abbrev,=pubnames,=ranges] +Displays the contents of the debug sections in the file, if any are +present. If one of the optional letters or words follows the switch +then only data found in those specific sections will be dumped. + +@item --histogram +Display a histogram of bucket list lengths when displaying the contents +of the symbol tables. + +@item -v +@itemx --version +Display the version number of readelf. + +@item -H +@itemx --help +Display the command line options understood by @code{readelf}. + +@end table + + +@node Selecting The Target System +@chapter Selecting the target system + +You can specify three aspects of the target system to the @sc{gnu} +binary file utilities, each in several ways: + +@itemize @bullet +@item +the target + +@item +the architecture + +@item +the linker emulation (which applies to the linker only) +@end itemize + +In the following summaries, the lists of ways to specify values are in +order of decreasing precedence. The ways listed first override those +listed later. + +The commands to list valid values only list the values for which the +programs you are running were configured. If they were configured with +@samp{--enable-targets=all}, the commands list most of the available +values, but a few are left out; not all targets can be configured in at +once because some of them can only be configured @dfn{native} (on hosts +with the same type as the target system). + +@menu +* Target Selection:: +* Architecture Selection:: +* Linker Emulation Selection:: +@end menu + +@node Target Selection +@section Target Selection + +A @dfn{target} is an object file format. A given target may be +supported for multiple architectures (@pxref{Architecture Selection}). +A target selection may also have variations for different operating +systems or architectures. + +The command to list valid target values is @samp{objdump -i} +(the first column of output contains the relevant information). + +Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips}, +@samp{a.out-sunos-big}. + +You can also specify a target using a configuration triplet. This is +the same sort of name that is passed to configure to specify a target. +When you use a configuration triplet as an argument, it must be fully +canonicalized. You can see the canonical version of a triplet by +running the shell script @file{config.sub} which is included with the +sources. + +Some sample configuration triplets are: @samp{m68k-hp-bsd}, +@samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}. + +@subheading @code{objdump} Target + +Ways to specify: + +@enumerate +@item +command line option: @samp{-b} or @samp{--target} + +@item +environment variable @code{GNUTARGET} + +@item +deduced from the input file +@end enumerate + +@subheading @code{objcopy} and @code{strip} Input Target + +Ways to specify: + +@enumerate +@item +command line options: @samp{-I} or @samp{--input-target}, or @samp{-F} or @samp{--target} + +@item +environment variable @code{GNUTARGET} + +@item +deduced from the input file +@end enumerate + +@subheading @code{objcopy} and @code{strip} Output Target + +Ways to specify: + +@enumerate +@item +command line options: @samp{-O} or @samp{--output-target}, or @samp{-F} or @samp{--target} + +@item +the input target (see ``@code{objcopy} and @code{strip} Input Target'' above) + +@item +environment variable @code{GNUTARGET} + +@item +deduced from the input file +@end enumerate + +@subheading @code{nm}, @code{size}, and @code{strings} Target + +Ways to specify: + +@enumerate +@item +command line option: @samp{--target} + +@item +environment variable @code{GNUTARGET} + +@item +deduced from the input file +@end enumerate + +@subheading Linker Input Target + +Ways to specify: + +@enumerate +@item +command line option: @samp{-b} or @samp{--format} +(@pxref{Options,,Options,ld.info,Using LD}) + +@item +script command @code{TARGET} +(@pxref{Option Commands,,Option Commands,ld.info,Using LD}) + +@item +environment variable @code{GNUTARGET} +(@pxref{Environment,,Environment,ld.info,Using LD}) + +@item +the default target of the selected linker emulation +(@pxref{Linker Emulation Selection}) +@end enumerate + +@subheading Linker Output Target + +Ways to specify: + +@enumerate +@item +command line option: @samp{-oformat} +(@pxref{Options,,Options,ld.info,Using LD}) + +@item +script command @code{OUTPUT_FORMAT} +(@pxref{Option Commands,,Option Commands,ld.info,Using LD}) + +@item +the linker input target (see ``Linker Input Target'' above) +@end enumerate + +@node Architecture Selection +@section Architecture selection + +An @dfn{architecture} is a type of @sc{cpu} on which an object file is +to run. Its name may contain a colon, separating the name of the +processor family from the name of the particular @sc{cpu}. + +The command to list valid architecture values is @samp{objdump -i} (the +second column contains the relevant information). + +Sample values: @samp{m68k:68020}, @samp{mips:3000}, @samp{sparc}. + +@subheading @code{objdump} Architecture + +Ways to specify: + +@enumerate +@item +command line option: @samp{-m} or @samp{--architecture} + +@item +deduced from the input file +@end enumerate + +@subheading @code{objcopy}, @code{nm}, @code{size}, @code{strings} Architecture + +Ways to specify: + +@enumerate +@item +deduced from the input file +@end enumerate + +@subheading Linker Input Architecture + +Ways to specify: + +@enumerate +@item +deduced from the input file +@end enumerate + +@subheading Linker Output Architecture + +Ways to specify: + +@enumerate +@item +script command @code{OUTPUT_ARCH} +(@pxref{Option Commands,,Option Commands,ld.info,Using LD}) + +@item +the default architecture from the linker output target +(@pxref{Target Selection}) +@end enumerate + +@node Linker Emulation Selection +@section Linker emulation selection + +A linker @dfn{emulation} is a ``personality'' of the linker, which gives +the linker default values for the other aspects of the target system. +In particular, it consists of + +@itemize @bullet +@item +the linker script + +@item +the target + +@item +several ``hook'' functions that are run at certain stages of the linking +process to do special things that some targets require +@end itemize + +The command to list valid linker emulation values is @samp{ld -V}. + +Sample values: @samp{hp300bsd}, @samp{mipslit}, @samp{sun4}. + +Ways to specify: + +@enumerate +@item +command line option: @samp{-m} +(@pxref{Options,,Options,ld.info,Using LD}) + +@item +environment variable @code{LDEMULATION} + +@item +compiled-in @code{DEFAULT_EMULATION} from @file{Makefile}, +which comes from @code{EMUL} in @file{config/@var{target}.mt} +@end enumerate + +@node Reporting Bugs +@chapter Reporting Bugs +@cindex bugs +@cindex reporting bugs + +Your bug reports play an essential role in making the binary utilities +reliable. + +Reporting a bug may help you by bringing a solution to your problem, or +it may not. But in any case the principal function of a bug report is +to help the entire community by making the next version of the binary +utilities work better. Bug reports are your contribution to their +maintenance. + +In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +@menu +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs +@end menu + +@node Bug Criteria +@section Have you found a bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex crash +@item +If a binary utility gets a fatal signal, for any input whatever, that is +a bug. Reliable utilities never crash. + +@cindex error on valid input +@item +If a binary utility produces an error message for valid input, that is a +bug. + +@item +If you are an experienced user of binary utilities, your suggestions for +improvement are welcome in any case. +@end itemize + +@node Bug Reporting +@section How to report bugs +@cindex bug reports +@cindex bugs, reporting + +A number of companies and individuals offer support for @sc{gnu} +products. If you obtained the binary utilities from a support +organization, we recommend you contact that organization first. + +You can find contact information for many support companies and +individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs +distribution. + +In any event, we also recommend that you send bug reports for the binary +utilities to @samp{bug-gnu-utils@@gnu.org}. + +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! + +Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of a file you use in an example does not matter. +Well, probably it does not, but one cannot be sure. Perhaps the bug is +a stray memory reference which happens to fetch from the location where +that pathname is stored in memory; perhaps, if the pathname were +different, the contents of that location would fool the utility into +doing the right thing despite the bug. Play it safe and give a +specific, complete example. That is the easiest thing for you to do, +and the most helpful. + +Keep in mind that the purpose of a bug report is to enable us to fix the bug if +it is new to us. Therefore, always write your bug reports on the assumption +that the bug has not been reported previously. + +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' Those bug reports are useless, and we urge everyone to +@emph{refuse to respond to them} except to chide the sender to report +bugs properly. + +To enable us to fix the bug, you should include all these things: + +@itemize @bullet +@item +The version of the utility. Each utility announces it if you start it +with the @samp{--version} argument. + +Without this, we will not know whether there is any point in looking for +the bug in the current version of the binary utilities. + +@item +Any patches you may have applied to the source, including any patches +made to the @code{BFD} library. + +@item +The type of machine you are using, and the operating system name and +version number. + +@item +What compiler (and its version) was used to compile the utilities---e.g. +``@code{gcc-2.7}''. + +@item +The command arguments you gave the utility to observe the bug. To +guarantee you will not omit something important, list them all. A copy +of the Makefile (or the output from make) is sufficient. + +If we were to try to guess the arguments, we would probably guess wrong +and then we might not encounter the bug. + +@item +A complete input file, or set of input files, that will reproduce the +bug. If the utility is reading an object file or files, then it is +generally most helpful to send the actual object files, uuencoded if +necessary to get them through the mail system. Making them available +for anonymous FTP is not as good, but may be the only reasonable choice +for large object files. + +If the source files were produced exclusively using @sc{gnu} programs +(e.g., @code{gcc}, @code{gas}, and/or the @sc{gnu} @code{ld}), then it +may be OK to send the source files rather than the object files. In +this case, be sure to say exactly what version of @code{gcc}, or +whatever, was used to produce the object files. Also say how +@code{gcc}, or whatever, was configured. + +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``It gets a fatal signal.'' + +Of course, if the bug is that the utility gets a fatal signal, then we +will certainly notice it. But if the bug is incorrect output, we might +not notice unless it is glaringly wrong. You might as well not give us +a chance to make a mistake. + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of the utility is out of synch, or you have encountered a bug in +the C library on your system. (This has happened!) Your copy might +crash and ours would not. If you told us to expect a crash, then when +ours fails to crash, we would know that the bug was not happening for +us. If you had not told us to expect a crash, then we would not be able +to draw any conclusion from our observations. + +@item +If you wish to suggest changes to the source, send us context diffs, as +generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p} +option. Always send diffs from the old file to the new file. If you +even discuss something in the @code{ld} source, refer to it by context, +not by line number. + +The line numbers in our development sources will not match those in your +sources. Your line numbers would convey no useful information to us. +@end itemize + +Here are some things that are not necessary: + +@itemize @bullet +@item +A description of the envelope of the bug. + +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. + +This is often time consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger +with breakpoints, not by pure deduction from a series of examples. +We recommend that you save your time for something else. + +Of course, if you can find a simpler example to report @emph{instead} +of the original one, that is a convenience for us. Errors in the +output will be easier to spot, running under the debugger will take +less time, and so on. + +However, simplification is not vital; if you do not want to do this, +report the bug anyway and send us the entire test case you used. + +@item +A patch for the bug. + +A patch for the bug does help us if it is a good one. But do not omit +the necessary information, such as the test case, on the assumption that +a patch is all we need. We might see problems with your patch and decide +to fix the problem another way, or we might not understand it at all. + +Sometimes with programs as complicated as the binary utilities it is +very hard to construct an example that will make the program follow a +certain path through the code. If you do not send us the example, we +will not be able to construct one, so we will not be able to verify that +the bug is fixed. + +And if we cannot understand what bug you are trying to fix, or why your +patch should be an improvement, we will not install it. A test case will +help us to understand. + +@item +A guess about what the bug is or what it depends on. + +Such guesses are usually wrong. Even we cannot guess right about such +things without first using the debugger to find the facts. +@end itemize + +@node Index +@unnumbered Index + +@printindex cp + +@contents +@bye |