X-Git-Url: https://repo.jachan.dev/binutils.git/blobdiff_plain/5b0ba16d41476e10f93d1d9c9f916f1facba648b..7faa6d38bb29b66091517cfe978c633b74f05e2d:/binutils/binutils.texi

diff --git a/binutils/binutils.texi b/binutils/binutils.texi
index 06abe59518..10f466519a 100644
--- a/binutils/binutils.texi
+++ b/binutils/binutils.texi
@@ -4,14 +4,15 @@
 @ifinfo
 @format
 START-INFO-DIR-ENTRY
-* Binutils::                    The GNU binary utilities "ar", "ld", "objcopy",
-				"objdump", "nm", "size", "strings", "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 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -47,8 +48,6 @@ into another language, under the above conditions for modified versions.
 
 @setchapternewpage odd
 @settitle GNU Binary Utilities
-@c @smallbook
-@c @cropmarks
 @titlepage
 @finalout
 @title The GNU Binary Utilities
@@ -66,7 +65,7 @@ into another language, under the above conditions for modified versions.
 @end tex
 
 @vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -81,8 +80,8 @@ 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
@@ -106,19 +105,24 @@ 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
+
+@item c++filt
+Demangle encoded C++ symbols
+
+@item nlmconv
+Convert object code into a Netware Loadable Module
 @end table
 @end iftex
 
 @menu
 * ar::                          Create, modify, and extract from archives
-* ld:(ld)Overview.              Combine object and archive files
 * nm::                          List symbols from object files
 * objcopy::			Copy and translate object files
 * objdump::                     Display information from object files
@@ -128,10 +132,11 @@ Discard symbols
 * 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, nm, Top, Top
+@node ar
 @chapter ar
 
 @kindex ar
@@ -187,12 +192,12 @@ 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
+* ar cmdline::                  Controlling @code{ar} on the command line
+* ar scripts::                  Controlling @code{ar} with a script
 @end menu
 
 @page
-@node ar-cmdline, ar-scripts, ar, ar
+@node ar cmdline
 @section Controlling @code{ar} on the command line
 
 @smallexample
@@ -382,7 +387,7 @@ when the modifier @samp{v} is appended.
 This modifier shows the version number of @code{ar}.
 @end table
 
-@node ar-scripts,  , ar-cmdline, ar
+@node ar scripts
 @section Controlling @code{ar} with a script
 
 @smallexample
@@ -554,20 +559,20 @@ The GNU linker @code{ld} is now described in a separate manual.
 @xref{Top,, Overview,, Using LD: the GNU linker}.
 @end iftex
 
-@node nm, objcopy, ar, Top
+@node nm
 @chapter nm
 @cindex symbols
 @kindex nm
 
 @smallexample
 nm [ -a | --debug-syms ]  [ -g | --extern-only ]
-   [ -B ]  [ -C | --demangle ]
+   [ -B ]  [ -C | --demangle ] [ -D | --dynamic ]
    [ -s | --print-armap ]  [ -A | -o | --print-file-name ]  
    [ -n | -v | --numeric-sort ]  [ -p | --no-sort ]
    [ -r | --reverse-sort ]  [ -u | --undefined-only ]  
    [ -t @var{radix} | --radix=@var{radix} ] [ -P | --portability ]
    [ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ]
-   [ -V | --version ]  [ --help ]  [ @var{objfile}@dots{} ]
+   [ --no-demangle ] [ -V | --version ]  [ --help ]  [ @var{objfile}@dots{} ]
 @end smallexample
 
 GNU @code{nm} lists the symbols from object files @var{objfile}@dots{}.
@@ -648,6 +653,16 @@ 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
@@ -699,7 +714,7 @@ Use @var{radix} as the radix for printing the symbol values.  It must be
 @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.
+@xref{Target Selection}, for more information.
 
 @item -u
 @itemx --undefined-only 
@@ -715,53 +730,56 @@ Show the version number of @code{nm} and exit.
 Show a summary of the options to @code{nm} and exit.
 @end table
 
-@node objcopy, objdump, nm, Top
+@node objcopy
 @chapter objcopy
 
 @smallexample
-objcopy [ -F @var{format} | --format=@var{format} ]
-        [ -I @var{format} | --input-format=@var{format} ]
-        [ -O @var{format} | --output-format=@var{format} ]
+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 ]
         [ -x | --discard-all ]  [ -X | --discard-locals ]
-        [ -v | --verbose ]  [ -V | --version ]  [ --help ]
+        [ -b @var{byte} | --byte=@var{byte} ]
+        [ -i @var{interleave} | --interleave=@var{interleave} ]
+        [ -v | --verbose ] [ -V | --version ]  [ --help ]
         @var{infile} [@var{outfile}]
 @end smallexample
 
-The GNU @code{objcopy} utility copies the contents of an object file to
-another.  @code{objcopy} uses the GNU 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.
+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 BFD to do all its
-translation work; it knows about all the formats BFD knows about, and
-thus is able to recognize most formats without being told explicitly.
-@xref{BFD,,BFD,ld.info,Using LD, the GNU linker}.
+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}.
 
 @table @code
 @item @var{infile}
 @itemx @var{outfile}
-The source and output files respectively.
+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 the input file.
+the name of @var{infile}.
 
-@item -I @var{format}	
-@itemx --input-format=@var{format}
-Consider the source file's object format to be @var{format}, rather than
-attempting to deduce it.
+@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{format}
-@itemx --output-format=@var{format}
-Write the output file using the object format @var{format}.
+@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{format}
-@itemx --format=@var{format}
-Use @var{format} as the object format for both the input and the output
-file; i.e. simply transfer data from source to destination with no
-translation.
+@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 -S
 @itemx --strip-all
@@ -781,6 +799,22 @@ Do not copy non-global symbols from the source file.
 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 -V
 @itemx --version
 Show the version number of @code{objcopy}.
@@ -794,18 +828,24 @@ archives, @samp{objcopy -V} lists all members of the archive.
 Show a summary of the options to @code{objcopy}.
 @end table
 
-@node objdump, ranlib, objcopy, 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 ]  [ --stabs ]
-        [ -t | --syms ]  [ -x ]  [ --version ]  [ --help ]
-        @var{objfile}@dots{}
+objdump [ -a | --archive-headers ] 
+        [ -b @var{bfdname} | --target=@var{bfdname} ]
+        [ -d | --disassemble ]  [ -f | --file-headers ]
+        [ -h | --section-headers | --headers ]  [ -i | --info ]
+        [ -j @var{section} | --section=@var{section} ]
+        [ -l | --line-numbers ]
+        [ -m @var{machine} | --architecture=@var{machine} ]
+        [ -r | --reloc ] [ -R | --dynamic-reloc ]
+        [ -s | --full-contents ]  [ --stabs ]
+        [ -t | --syms ] [ -T | --dynamic-syms ] [ -x | --all-headers ]
+        [ --version ]  [ --help ] @var{objfile}@dots{}
 @end smallexample
 
 @code{objdump} displays information about one or more object files.
@@ -823,15 +863,15 @@ equivalent.  At least one option besides @samp{-l} must be given.
 
 @table @code
 @item -a
-@c print_arelt_descr
+@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.
 
-@c suggest longname --target or --format or --bfd
 @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
@@ -846,46 +886,61 @@ 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 -d
+@itemx --disassemble
 @cindex disassembling object code
 @cindex machine instructions
-Disassemble.  Display the assembler mnemonics for the machine
+Display the assembler mnemonics for the machine
 instructions from @var{objfile}.
 
 @item -f
+@itemx --file-header
 @cindex object file header
-File header.  Display summary information from the overall header of
+Display summary information from the overall header of
 each of the @var{objfile} files.
 
 @item -h
+@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 @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}.
 
-@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}.
 
-@c suggest longname --architecture
 @item -m @var{machine}
+@itemx --architecture=@var{machine}
 @cindex architecture
 Specify that the object files @var{objfile} are for architecture
 @var{machine}.  You can list available architectures using the @samp{-i}
@@ -894,9 +949,17 @@ option.
 @item -r
 @itemx --reloc
 @cindex relocation entries, in object file
-Relocation.  Print the relocation entries of the file.
+Print the relocation entries of the file.
+
+@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.
@@ -917,13 +980,22 @@ output.
 @item -t
 @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
@@ -931,7 +1003,7 @@ relocation entries.  Using @samp{-x} is equivalent to specifying all of
 @samp{-a -f -h -r -t}.
 @end table
 
-@node ranlib, size, objdump, Top
+@node ranlib
 @chapter ranlib
 
 @kindex ranlib
@@ -962,7 +1034,7 @@ The GNU @code{ranlib} program is another form of GNU @code{ar}; running
 Show the version number of @code{ranlib}.
 @end table
 
-@node size, strings, ranlib, Top
+@node size
 @chapter size
 
 @kindex size
@@ -1001,7 +1073,7 @@ Berkeley's.
 Here is an example of the Berkeley (default) format of output from
 @code{size}: 
 @smallexample
-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
@@ -1011,7 +1083,7 @@ text    data    bss     dec     hex     filename
 This is the same data, but displayed closer to System V conventions:
 
 @smallexample
-size --format SysV ranlib size
+size --format=SysV ranlib size
 ranlib  :
 section         size         addr
 .text         294880         8192       
@@ -1049,15 +1121,15 @@ octal and hexadecimal if you're using @samp{-o}.
 @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{objdump}, for information
-on listing available formats.
+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, strip, size, Top
+@node strings
 @chapter strings
 @kindex strings
 @cindex listings strings
@@ -1067,7 +1139,8 @@ Display the version number of @code{size}.
 @smallexample
 strings [-afov] [-@var{min-len}] [-n @var{min-len}] [-t @var{radix}] [-]
         [--all] [--print-file-name] [--bytes=@var{min-len}]
-        [--radix=@var{radix}] [--help] [--version] @var{file}@dots{}
+        [--radix=@var{radix}] [--target=@var{bfdname}]
+        [--help] [--version] @var{file}@dots{}
 @end smallexample
 
 For each @var{file} given, GNU @code{strings} prints the printable
@@ -1111,12 +1184,17 @@ 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, c++filt, strings, Top
+@node strip
 @chapter strip
 
 @kindex strip
@@ -1125,9 +1203,9 @@ Print the program version number on the standard output and exit.
 @cindex symbols, discarding
 
 @smallexample
-strip [ -F @var{format} | --format=@var{format} | --target=@var{format} ]
-      [ -I @var{format} | --input-format=@var{format} ]
-      [ -O @var{format} | --output-format=@var{format} ]
+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 ]
       [ -x | --discard-all ] [ -X | --discard-locals ]
       [ -v | --verbose ]  [ -V | --version ]  [ --help ]
@@ -1142,23 +1220,25 @@ At least one object file must be given.
 rather than writing modified copies under different names.
 
 @table @code
-@item -F @var{format}
-@itemx --format=@var{format}
-@itemx --target=@var{format}
+@item -F @var{bfdname}
+@itemx --target=@var{bfdname}
 Treat the original @var{objfile} as a file with the object
-code format @var{format}, and rewrite it in the same format.
+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{format}	
-@itemx --input-format=@var{format}
+@item -I @var{bfdname}	
+@itemx --input-target=@var{bfdname}
 Treat the original @var{objfile} as a file with the object
-code format @var{format}.
+code format @var{bfdname}.
+@xref{Target Selection}, for more information.
 
-@item -O @var{format}
-@itemx --output-format=@var{format}
-Replace @var{objfile} with a file in the output format @var{format}.
+@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 -s
 @itemx --strip-all
@@ -1188,7 +1268,7 @@ 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, nlmconv, strip, Top
+@node c++filt
 @chapter c++filt
 
 @kindex c++filt
@@ -1270,16 +1350,20 @@ c++filt @var{option} @var{symbol}
 @end example
 @end quotation
 
-@node nlmconv, Index, c++filt, Top
+@node nlmconv
 @chapter nlmconv
 
 @code{nlmconv} converts a relocatable object file into a NetWare
-Loadable Module.  @code{nlmconv} currently works with @samp{i386} object
+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
@@ -1287,9 +1371,10 @@ utilities, since it is only useful for NLM targets.
 @end quotation
 
 @smallexample
-nlmconv [ -I @var{format} | --input-format=@var{format} ]
-        [ -O @var{format} | --output-format=@var{format} ]
+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
@@ -1302,23 +1387,27 @@ on writing the NLM command file language used in header files, see the
 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, the GNU linker}, for
+@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{format}
-@itemx --input-format=@var{format}
+@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).  @var{format}
-arguments are normal BFD names; for a list of these, run
-@w{@samp{objdump -i}}.
+the format of a given file (so no default is necessary).
+@xref{Target Selection}, for more information.
 
-@item -O @var{format}
-@itemx --output-format=@var{format}
+@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}.  @var{format} arguments are normal
-BFD names; for a list of these, run @w{@samp{objdump -i}}.
+output format is @samp{nlm32-i386}.
+@xref{Target Selection}, for more information.
 
 @item -T @var{headerfile}
 @itemx --header-file=@var{headerfile}
@@ -1328,6 +1417,15 @@ writing the NLM command file language used in header files, see@ see the
 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.
@@ -1337,7 +1435,251 @@ Prints a usage summary.
 Prints the version number for @code{nlmconv}.
 @end table
 
-@node Index,  , nlmconv, Top
+@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{--with-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