X-Git-Url: http://git.efficios.com/?a=blobdiff_plain;f=binutils%2Fbinutils.texi;h=fbec8beace86ebc16eb9844c8212005586a10ba8;hb=5351b2a08aa9d743f66495fb0c97f372e9fb1c5d;hp=d3bf221dcc054a315514c360ec3074c357bd81c0;hpb=765a273ff9cea3c5f1d7f25fec1a39035734693e;p=deliverable%2Fbinutils-gdb.git diff --git a/binutils/binutils.texi b/binutils/binutils.texi index d3bf221dcc..fbec8beace 100644 --- a/binutils/binutils.texi +++ b/binutils/binutils.texi @@ -1,54 +1,72 @@ \input texinfo @c -*- Texinfo -*- @setfilename binutils.info +@include config.texi @ifinfo @format START-INFO-DIR-ENTRY - -* Binutils: (binutils). - The GNU binary utilities "ar", "ld", "objdump", "nm", - "size", "strip", and "ranlib". - +* Binutils: (binutils). The GNU binary utilities "ar", "objcopy", + "objdump", "nm", "nlmconv", "size", + "strings", "strip", and "ranlib". END-INFO-DIR-ENTRY @end format @end ifinfo +@ifinfo +Copyright @copyright{} 1991, 1992, 1993, 1994, 1995 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", "objdump", "nm", -@c "size", "strip", and "ranlib". +@c This file documents the GNU binary utilities "ar", "ld", "objcopy", +@c "objdump", "nm", "size", "strings", "strip", and "ranlib". @c -@c Copyright (C) 1991 Free Software Foundation, Inc. +@c Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc. @c @c This text may be freely distributed under the terms of the GNU @c General Public License. @c -@c $Id$ -@iftex -@finalout -@c @smallbook -@end iftex -@c @cropmarks + @setchapternewpage odd -@settitle GNU Binary Utilities +@settitle @sc{gnu} Binary Utilities @titlepage -@title The GNU Binary Utilities -@subtitle Version 1.90 +@finalout +@title The @sc{gnu} Binary Utilities +@subtitle Version @value{VERSION} @sp 1 -@subtitle October 1991 +@subtitle May 1993 @author Roland H. Pesch +@author Jeffrey M. Osier @author Cygnus Support @page @tex -\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ -\xdef\manvers{\$Revision$} % For use in headers, footers too -{\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par \hfill +{\parskip=0pt \hfill Cygnus Support\par \hfill \TeX{}info \texinfoversion\par } @end tex @vskip 0pt plus 1filll -Copyright @copyright{} 1991 Free Software Foundation, Inc. +Copyright @copyright{} 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice @@ -63,12 +81,14 @@ 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, ar, (dir), (dir) -@chapter Introduction +@node Top +@top Introduction @cindex version -This brief manual contains preliminary documentation for the GNU binary -utilities (collectively version 1.90): +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 @@ -76,6 +96,9 @@ 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 @@ -83,79 +106,62 @@ Display information from object files Generate index to archive contents @item size -List section sizes and total size +List file section sizes and total size + +@item strings +List printable strings from files @item strip Discard symbols -@end table -@ifinfo -Copyright @copyright{} 1991 Free Software Foundation, Inc. +@item c++filt +Demangle encoded C++ symbols -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 +@item nlmconv +Convert object code into a Netware Loadable Module +@end table +@end iftex @menu -* ar:: ar -* ld:: ld -* nm:: nm -* objdump:: objdump -* ranlib:: ranlib -* size:: size -* strip:: strip -* Index:: Index - - --- The Detailed Node Listing --- - -ar - -* ar-cmdline:: Controlling @code{ar} on the command line -* ar-scripts:: Controlling @code{ar} with a script +* 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 +* size:: List section sizes and total size +* strings:: List printable strings from files +* strip:: Discard symbols +* c++filt:: Filter to demangle encoded C++ symbols +* nlmconv:: Converts object code into an NLM +* Selecting The Target System:: How these utilities determine the target. +* Index:: @end menu -@node ar, ld, Top, Top +@node ar @chapter ar @kindex ar @cindex archives @cindex collections of files @smallexample - ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{files}@dots{} - ar -M [ }), and continues executing even after errors. If you redirect standard input to a script file, no prompts are -issued, and @code{ar} will abandon execution (with a nonzero exit code) +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 GNU @code{ar} for developers who already have scripts +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: @@ -448,10 +466,10 @@ Add all the contents of @var{archive} (or, if specified, each named Requires prior use of @code{OPEN} or @code{CREATE}. -@item ADDMOD @var{file}, @var{file}, @dots{} @var{file} +@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{file} as a module in the current archive. +Add each named @var{member} as a module in the current archive. Requires prior use of @code{OPEN} or @code{CREATE}. @@ -508,7 +526,7 @@ Requires prior use of @code{OPEN} or @code{CREATE}. @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 GNU @code{ld} +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}. @@ -529,7 +547,7 @@ 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{}}. +@samp{ar -tv }@dots{}. @item SAVE Commit your changes to the current archive, and actually save it as a @@ -540,108 +558,416 @@ Requires prior use of @code{OPEN} or @code{CREATE}. @end table - -@node ld, nm, ar, Top +@iftex +@node ld @chapter ld @cindex linker @kindex ld -The GNU linker @code{ld} is now described in a separate manual. -@xref{Top,, Overview,, GLD: the GNU linker}. +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, objdump, ld, Top +@node nm @chapter nm @cindex symbols @kindex nm @smallexample - nm [ -a | +debug-syms ] [ -g | +extern-only ] - [ -s | +print-armap ] [ -o | +print-file-name ] - [ -n | +numeric-sort ] [ -p | +no-sort ] - [ -r | +reverse-sort ] [ -u | +undefined-only ] - [ +target @var{bfdname} ] - [ @var{objfiles}@dots{} ] +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 ] + [ --no-demangle ] [ -V | --version ] [ --help ] [ @var{objfile}@dots{} ] @end smallexample -GNU @code{nm} will list the symbols from object files @var{objfiles}. +@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 +Absolute. + +@item B +BSS (uninitialized data). + +@item C +Common. + +@item D +Initialized data. + +@item I +Indirect reference. + +@item T +Text (program code). + +@item U +Undefined. +@end table + +@item +The symbol name. +@end itemize The long and short forms of options, shown here as alternatives, are equivalent. @table @code -@item @var{objfiles}@dots{} -@kindex a.out -Object files whose symbols are to be listed. If no object files are -listed as arguments, @code{nm} assumes @samp{a.out}. +@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 +@itemx --debug-syms @cindex debugging symbols -Display debugger-only symbols; normally these are not listed. +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 C++ symbols +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 +@itemx --extern-only @cindex external symbols Display only external symbols. +@item -n +@itemx -v +@itemx --numeric-sort +Sort symbols numerically by their addresses, rather than alphabetically +by their names. + @item -p -@itemx +no-sort +@itemx --no-sort @cindex sorting symbols -Don't bother to sort the symbols in any order; just print them in the -order encountered. +Do not bother to sort the symbols in any order; print them in the order +encountered. -@item -n -@itemx +numeric-sort -Sort symbols numerically by their addresses, not alphabetically by their -names. +@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 +@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 what modules -contain definitions for what names. - -@item -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 where it was found, -rather than identifying the input file once only before all of its -symbols. +(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 sense of the sort (whether numeric or alphabetic); let the +@itemx --reverse-sort +Reverse the order of the sort (whether numeric or alphabetic); let the last come first. -@item +target @var{bfdname} -@c @item +target +@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{objdump}, for information on listing available formats. -@c FIXME what *does* +target/no arg do? +@xref{Target Selection}, for more information. @item -u -@itemx +undefined-only +@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} ] + [ -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} ] + [ --gap-fill=@var{val} ] [ --pad-to=@var{address} ] + [ --set-start=@var{val} ] [ --adjust-start=@var{incr} ] + [ --adjust-vma=@var{incr} ] + [ --adjust-section-vma=@var{section}@{=,+,-@}@var{val} ] + [ --adjust-warnings ] [ --no-adjust-warnings ] + [ --set-section-flags=@var{section}=@var{flags} ] + [ --add-section=@var{sectionname}=@var{filename} ] + [ -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 virtual 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, and may be combined with strip options +other than @code{-K}. + +@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 --gap-fill @var{val} +Fill gaps between sections with @var{val}. This 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 virtual 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 --adjust-start @var{incr} +Adjust the start address by adding @var{incr}. Not all object file +formats support setting the start address. + +@item --adjust-vma @var{incr} +Adjust the address 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 --adjust-section-vma @var{section}@{=,+,-@}@var{val} +Set or adjust the 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{--adjust-vma}, above. If @var{section} does not exist in the +input file, a warning will be issued, unless @samp{--no-adjust-warnings} +is used. + +@item --adjust-warnings +If @samp{--adjust-section-vma} is used, and the named section does not +exist, issue a warning. This is the default. + +@item --no-adjust-warnings +Do not issue a warning if @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{load}, @samp{readonly}, @samp{code}, @samp{data}, +and @samp{rom}. 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 -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, ranlib, nm, Top +@node objdump @chapter objdump @cindex object file information @kindex objdump @smallexample - objdump [ -a ] [ -b @var{bfdname} ] [ -d ] [ -f ] - [ -h | +header ] [ -i ] [ -j @var{section} ] [ -l ] - [ -m @var{machine} ] [ -r | +reloc ] [ -s ] - [ -t | +syms ] [ -x ] - @var{objfiles}@dots{} +objdump [ -a | --archive-headers ] + [ -b @var{bfdname} | --target=@var{bfdname} ] [ --debugging ] + [ -d | --disassemble ] [ -D | --disassemble-all ] + [ -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} ] + [ -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} ] [ --version ] [ --help ] + @var{objfile}@dots{} @end smallexample @code{objdump} displays information about one or more object files. @@ -650,104 +976,191 @@ 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. +equivalent. At least one option besides @samp{-l} must be given. @table @code -@item @var{objfiles}@dots{} -The object files to be examined. When you specify archives, -@code{objdump} shows information on each of the member object files. - @item -a -@c print_arelt_descr +@itemx --archive-header @cindex archive headers -If any files from @var{objfiles} are archives, display the archive +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. -@c suggest longname +target or +format or +bfd @item -b @var{bfdname} +@itemx --target=@var{bfdname} @cindex object code format -You can specify a particular object-code format for your object files as -@var{bfdname}. This may not be necessary; @var{objdump} can -automatically recognize many formats. For example, +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 +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 --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 -Disassemble. Display the assembler mnemonics for the machine -instructions from @var{objfiles}. +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 -f +@itemx --file-header @cindex object file header -File header. Display summary information from the overall header of -each file in @var{objfiles}. +Display summary information from the overall header of +each of the @var{objfile} files. @item -h -@itemx +header +@itemx --section-header +@itemx --header @cindex section headers -Header. Display summary information from the section headers of the +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 @code{-b} or @code{-m}. +for specification with @samp{-b} or @samp{-m}. -@c suggest longname +section @item -j @var{name} +@itemx --section=@var{name} @cindex section information -Display information only for section @var{name} +Display information only for section @var{name}. -@c suggest longname +label or +linespec @item -l +@itemx --line-numbers @cindex source filenames for object files -Label the display (using debugging information) with the source filename -and line numbers corresponding to the object code shown. +Label the display (using debugging information) with the filename +and source line numbers corresponding to the object code shown. +Only useful with @samp{-d} or @samp{-D}. -@c suggest longname +architecture @item -m @var{machine} +@itemx --architecture=@var{machine} @cindex architecture -Specify the object files @var{objfiles} are for architecture +Specify that the object files @var{objfile} are for architecture @var{machine}. You can list available architectures using the @samp{-i} option. @item -r -@itemx +reloc +@itemx --reloc @cindex relocation entries, in object file -Relocation. Print the relocation entries of the 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 --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. + +@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 +@itemx --syms @cindex symbol table entries, printing -Symbol Table. Print the symbol table entries of the file. +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 +@item --wide +@cindex wide output, printing +Format some lines for output devices that have more than 80 columns. @end table -@node ranlib, size, objdump, Top +@node ranlib @chapter ranlib @kindex ranlib @@ -755,63 +1168,69 @@ relocation entries. Using @samp{-x} is equivalent to specifying all of @cindex symbol index @smallexample - ranlib @var{archive} +ranlib [-vV] @var{archive} @end smallexample -@code{ranlib} generates an index to the contents of an archive, and +@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. +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 +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 GNU @code{ranlib} program is another form of GNU @code{ar}; running +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}. -@node size, strip, ranlib, Top +@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{objfiles}@dots{} +size [ -A | -B | --format=@var{compatibility} ] + [ --help ] [ -d | -o | -x | --radix=@var{number} ] + [ --target=@var{bfdname} ] [ -V | --version ] + @var{objfile}@dots{} @end smallexample -The GNU @code{size} utility lists the section sizes---and the total -size---for each of the object files @var{objfiles} in its argument list. -By default, one line of output is generated for each object file or each -module in an archive. +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. The command line options have the following meanings: -@table @code -@item @var{objfiles}@dots{} -The object files to be examined. +@table @code @item -A @itemx -B -@itemx +format @var{compatibility} -@cindex size display format -Using one of these options, you can choose whether the output from GNU +@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 +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 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 - eg$ size +format Berkeley ranlib size +size --format=Berkeley ranlib size text data bss dec hex filename 294880 81920 11592 388392 5ed28 ranlib 294880 81920 11888 388688 5ee50 size @@ -821,7 +1240,7 @@ text data bss dec hex filename This is the same data, but displayed closer to System V conventions: @smallexample - eg$ size +format SysV ranlib size +size --format=SysV ranlib size ranlib : section size addr .text 294880 8192 @@ -838,98 +1257,615 @@ section size addr Total 388688 @end smallexample -@item +help +@item --help Show a summary of acceptable arguments and options. @item -d @itemx -o @itemx -x -@itemx +radix @var{number} -@cindex size number format +@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 +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} +@item --target=@var{bfdname} @cindex object code format -You can specify a particular object-code format for @var{objfiles} as -@var{bfdname}. This may not be necessary; @var{size} can -automatically recognize many formats. @xref{objdump}, for information -on listing available formats. +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 version number information on @code{size} itself. +@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. + +@itemx -@var{min-len} +@item -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, Index, size, Top +@node strip @chapter strip @kindex strip @cindex removing symbols @cindex discarding symbols +@cindex symbols, discarding @smallexample - strip [ -s | +strip-all ] [ -g | -S | +strip-debug ] - [ -x | +discard-all ] [ -X | +discard-locals ] - [ -T @var{bfdname} ] - @var{objfiles}@dots{} +strip [ -F @var{bfdname} | --target=@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} ] + [ -v | --verbose ] [ -V | --version ] [ --help ] + @var{objfile}@dots{} @end smallexample -GNU @code{strip} will discard all symbols from object files -@var{objfiles}, if no options are specified; or only certain symbols, -depending on its command-line options. +@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} will not execute unless at least one object file is listed. - -@quotation -@emph{WARNING:} @code{strip} modifies the files named in its argument, +@code{strip} modifies the files named in its argument, rather than writing modified copies under different names. -@end quotation - -The long and short forms of options, shown here as alternatives, are -equivalent. @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 -@cindex all symbols, discarding -This is the default case: strip all symbol entries from @var{objfiles}. +@itemx --strip-all +Remove all symbols. @item -g @itemx -S -@itemx +strip-debug -@cindex debugging symbols, discarding -Discard only debugging symbol information from @var{objfiles}. +@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 -x -@itemx +discard-all -@cindex local symbols, discarding -Discard all symbols local to each file in @var{objfiles}. -@emph{WARNING:} Note that @code{+discard-all} discards only @emph{local} -symbols, in spite of its name. +@itemx --discard-all +Remove non-global symbols. @item -X -@itemx +discard-locals -Discard local symbols starting with @samp{L} from each file in -@var{objfiles}. (Some compilers produce internally-used symbols that -begin with @samp{L}.) +@itemx --discard-locals +Remove compiler-generated local symbols. +(These usually start with @samp{L} or @samp{.}.) -@item -T @var{bfdname} -@cindex object code format -You can specify a particular object-code format @var{bfdname} for -@var{objfiles}. This may not be necessary; @var{strip} can automatically -recognize many formats. @xref{objdump}, for information on listing -available formats. +@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 ] + [ -n | --no-strip-underscores ] + [ -s @var{format} | --format=@var{format} ] + [ --help ] [ --version ] [ @var{symbol}@dots{} ] +@end smallexample + +The C++ language provides function overloading, which means that you can +write many functions with the same name (providing each takes parameters +of different types). All C++ 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 -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 +@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 -@node Index, , strip, Top +@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 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 abosolute 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 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}. + +@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 Index @unnumbered Index @printindex cp