\input texinfo @c -*- Texinfo -*-
@setfilename binutils.info
+@include config.texi
@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, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@c This file documents the GNU binary utilities "ar", "ld", "objcopy",
@c "objdump", "nm", "size", "strings", "strip", and "ranlib".
@c
-@c Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
+@c Copyright (C) 1991, 92, 93, 94, 95, 1996 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 GNU Binary Utilities
-@c @smallbook
-@c @cropmarks
+@settitle @sc{gnu} Binary Utilities
@titlepage
@finalout
-@title The GNU Binary Utilities
-@subtitle Version 2.2
+@title The @sc{gnu} Binary Utilities
+@subtitle Version @value{VERSION}
@sp 1
@subtitle May 1993
@author Roland H. Pesch
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 1996 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@end titlepage
@node Top
-@top
-@chapter Introduction
+@top Introduction
@cindex version
-This brief manual contains preliminary documentation for the GNU binary
-utilities (collectively version 2.2):
+This brief manual contains preliminary documentation for the @sc{gnu} binary
+utilities (collectively version @value{VERSION}):
@iftex
@table @code
ar -M [ <mri-script ]
@end smallexample
-The GNU @code{ar} program creates, modifies, and extracts from
+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).
extraction.
@cindex name length
-GNU @code{ar} can maintain archives whose members have names of any
+@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
@cindex compatibility, @code{ar}
@cindex @code{ar} compatibility
-GNU @code{ar} is designed to be compatible with two different
+@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
Most operations can also accept further @var{member} arguments,
specifying particular files to operate on.
-GNU @code{ar} allows you to mix the operation code @var{p} and modifier
+@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
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
@item l
This modifier is accepted but not used.
@c whaffor ar l modifier??? presumably compat; with
-@c what???---pesch@@cygnus.com, 25jan91
+@c what???---doc@@cygnus.com, 25jan91
@item o
@cindex dates in archive
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:
@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}.
@chapter ld
@cindex linker
@kindex ld
-The GNU linker @code{ld} is now described in a separate manual.
-@xref{Top,, Overview,, Using LD: 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
@smallexample
nm [ -a | --debug-syms ] [ -g | --extern-only ]
- [ -B ] [ -C | --demangle ]
- [ -s | --print-armap ] [ -A | -o | --print-file-name ]
+ [ -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 ]
+ [ -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} ]
- [ -V | --version ] [ --help ] [ @var{objfile}@dots{} ]
+ [ --defined-only ]
+ [ --no-demangle ] [ -V | --version ] [ --help ] [ @var{objfile}@dots{} ]
@end smallexample
-GNU @code{nm} lists the symbols from object files @var{objfile}@dots{}.
+@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}.
@c would be nice.
@table @code
@item A
-Absolute.
+The symbol's value is absolute, and will not be changed by further
+linking.
@item B
-BSS (uninitialized data).
+The symbol is in the uninitialized data section (known as BSS).
@item C
-Common.
+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
-Initialized data.
+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
-Indirect reference.
+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
-Text (program code).
+The symbol is in the text (code) section.
@item U
-Undefined.
+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
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
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
@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.
[ -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 ]
- [ -v | --verbose ] [ -V | --version ] [ --help ]
+ [ -b @var{byte} | --byte=@var{byte} ]
+ [ -i @var{interleave} | --interleave=@var{interleave} ]
+ [ -R @var{sectionname} | --remove-section=@var{sectionname} ]
+ [ --debugging ]
+ [ --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} ]
+ [ --remove-leading-char ]
+ [ -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}.
+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.
+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{bfdname}
@itemx --input-target=@var{bfdname}
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.
@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.
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 --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 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 --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.
+
@item -V
@itemx --version
Show the version number of @code{objcopy}.
@kindex objdump
@smallexample
-objdump [ -a | --archive-headers ] [ -b @var{bfdname} | --target=@var{bfdname} ]
- [ -d | --disassemble ] [ -f | --file-headers ]
+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 ]
- [ -m @var{machine} | --architecture=@var{machine} ] [ -r | --reloc ]
- [ -s | --full-contents ] [ --stabs ] [ -t | --syms ]
- [ -x | --all-headers ] [ --version ] [ --help ]
+ [ -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} ] [ --show-raw-insn ]
+ [ --version ] [ --help ]
@var{objfile}@dots{}
@end smallexample
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
-Display the assembler mnemonics for the machine
-instructions from @var{objfile}.
+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
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.
@cindex source filenames for object files
Label the display (using debugging information) with the filename
and source line numbers corresponding to the object code shown.
-Only useful with @samp{-d}.
+Only useful with @samp{-d} or @samp{-D}.
@item -m @var{machine}
@itemx --architecture=@var{machine}
@item -r
@itemx --reloc
@cindex relocation entries, in object file
-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 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. Not all targets handle this correctly yet.
+
@item --stabs
@cindex stab
@cindex .stab
@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.
+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
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.
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
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}.
@var{objfile}@dots{}
@end smallexample
-The GNU @code{size} utility lists the section sizes---and the total
+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.
@itemx -B
@itemx --format=@var{compatibility}
@cindex @code{size} display format
-Using one of these options, you can choose whether the output from GNU
+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
[--help] [--version] @var{file}@dots{}
@end smallexample
-For each @var{file} given, GNU @code{strings} prints the printable
+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 a NUL or newline
+given with the options below) and are followed by an unprintable
character. By default, it only prints the strings from the initialized
-data sections of object files; for other types of files, it prints the
-strings from the whole file.
+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.
@item -a
@itemx --all
@itemx -
-Do not scan only the initialized data section of object files; scan
-the whole files.
+Do not scan only the initialized and loaded sections of object files;
+scan the whole files.
@item -f
@itemx --print-file-name
[ -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} discards all symbols from object files
+@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.
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.
@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
Remove non-global symbols.
@smallexample
c++filt [ -_ | --strip-underscores ]
+ [ -n | --no-strip-underscores ]
[ -s @var{format} | --format=@var{format} ]
[ --help ] [ --version ] [ @var{symbol}@dots{} ]
@end smallexample
@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.
+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}
-GNU @code{nm} can decode three different methods of mangling, used by
+@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 GNU compiler (the default method)
+the one used by the @sc{gnu} compiler (the default method)
@item lucid
the one used by the Lucid compiler
@item arm
@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
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
@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}
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.
@node Selecting The Target System
@chapter Selecting the target system
-You can specify three aspects of the target system to the GNU binary
-file utilities, each in several ways. The three aspects of the target
-system that you can specify are
+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,
+the target
@item
-the architecture, and
+the architecture
@item
-the linker emulation (which applies to the linker only).
+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. In other words, the ways listed earlier
-override the ways listed later.
+order of decreasing precedence. The ways listed first override those
+listed later.
-The commands to list valid values only list the values that the programs
-you are running were configured for. If they were configured with
-@samp{--with-targets=all}, the commands list most of the available
+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 compiled ``native'' (on hosts with
-the same type as the target system).
+once because some of them can only be configured @dfn{native} (on hosts
+with the same type as the target system).
@menu
* Target Selection::
@end menu
@node Target Selection
-@section 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}).
-It may also have variations for different operating systems or architectures.
+A target selection may also have variations for different operating
+systems or architectures.
-Command to list valid values: @samp{objdump -i} (first column).
+The command to list valid target values is @samp{objdump -i}
+(the first column of output contains the relevant information).
-Sample values: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips}, @samp{a.out-sunos-big}.
+Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips},
+@samp{a.out-sunos-big}.
-@menu
-* objdump Target::
-* objcopy strip Input Target::
-* objcopy strip Output Target::
-* nm size strings Target::
-* Linker Input Target::
-* Linker Output Target::
-@end menu
-
-@node objdump Target
-@subsection @code{objdump} target
+@subheading @code{objdump} Target
Ways to specify:
@enumerate
@item
-command line option @samp{-b}, @samp{--target}
+command line option: @samp{-b} or @samp{--target}
@item
environment variable @code{GNUTARGET}
deduced from the input file
@end enumerate
-@node objcopy strip Input Target
-@subsection @code{objcopy} and @code{strip} input target
+@subheading @code{objcopy} and @code{strip} Input Target
Ways to specify:
@enumerate
@item
-command line option @samp{-I}, @samp{--input-target}, @samp{-F}, @samp{--target}
+command line options: @samp{-I} or @samp{--input-target}, or @samp{-F} or @samp{--target}
@item
environment variable @code{GNUTARGET}
deduced from the input file
@end enumerate
-@node objcopy strip Output Target
-@subsection @code{objcopy} and @code{strip} output target
+@subheading @code{objcopy} and @code{strip} Output Target
Ways to specify:
@enumerate
@item
-command line option @samp{-O}, @samp{-F}, @samp{--output-target}, @samp{--target}
+command line options: @samp{-O} or @samp{--output-target}, or @samp{-F} or @samp{--target}
@item
-the input target (@pxref{objcopy strip Input Target})
+the input target (see ``@code{objcopy} and @code{strip} Input Target'' above)
@item
environment variable @code{GNUTARGET}
deduced from the input file
@end enumerate
-@node nm size strings Target
-@subsection @code{nm}, @code{size}, and @code{strings} target
+@subheading @code{nm}, @code{size}, and @code{strings} Target
Ways to specify:
@enumerate
@item
-command line option @samp{--target}
+command line option: @samp{--target}
@item
environment variable @code{GNUTARGET}
deduced from the input file
@end enumerate
-@node Linker Input Target
-@subsection Linker input target
+@subheading Linker Input Target
Ways to specify:
@enumerate
@item
-command line option @samp{-b}, @samp{-format}
+command line option: @samp{-b} or @samp{--format}
(@pxref{Options,,Options,ld.info,Using LD})
@item
(@pxref{Linker Emulation Selection})
@end enumerate
-@node Linker Output Target
-@subsection Linker output target
+@subheading Linker Output Target
Ways to specify:
@enumerate
@item
-command line option @samp{-oformat}
+command line option: @samp{-oformat}
(@pxref{Options,,Options,ld.info,Using LD})
@item
(@pxref{Option Commands,,Option Commands,ld.info,Using LD})
@item
-the linker input target (@pxref{Linker Input Target})
+the linker input target (see ``Linker Input Target'' above)
@end enumerate
@node Architecture Selection
@section Architecture selection
-An @dfn{architecture} is a type of 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 CPU.
+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}.
-Command to list valid values: @samp{objdump -i} (second column).
+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}.
-@menu
-* objdump Architecture::
-* objcopy nm size strings Architecture::
-* Linker Input Architecture::
-* Linker Output Architecture::
-@end menu
-
-@node objdump Architecture
-@subsection @code{objdump} architecture
+@subheading @code{objdump} Architecture
Ways to specify:
@enumerate
@item
-command line option @samp{-m}, @samp{--architecture}
+command line option: @samp{-m} or @samp{--architecture}
@item
deduced from the input file
@end enumerate
-@node objcopy nm size strings Architecture
-@subsection @code{objcopy}, @code{nm}, @code{size}, @code{strings} architecture
+@subheading @code{objcopy}, @code{nm}, @code{size}, @code{strings} Architecture
Ways to specify:
deduced from the input file
@end enumerate
-@node Linker Input Architecture
-@subsection Linker input architecture
+@subheading Linker Input Architecture
Ways to specify:
deduced from the input file
@end enumerate
-@node Linker Output Architecture
-@subsection Linker output architecture
+@subheading Linker Output Architecture
Ways to specify:
@item
the default architecture from the linker output target
-(@pxref{Linker Output Target})
+(@pxref{Target Selection})
@end enumerate
@node Linker Emulation Selection
@itemize @bullet
@item
-the linker script,
+the linker script
@item
-the target, and
+the target
@item
several ``hook'' functions that are run at certain stages of the linking
-process to do special things that some targets require.
+process to do special things that some targets require
@end itemize
-Command to list valid values: @samp{ld -V}.
+The command to list valid linker emulation values is @samp{ld -V}.
Sample values: @samp{hp300bsd}, @samp{mipslit}, @samp{sun4}.
@enumerate
@item
-command line option @samp{-m}
+command line option: @samp{-m}
(@pxref{Options,,Options,ld.info,Using LD})
@item
projects / binutils.git / blobdiff