\input texinfo @c -*- Texinfo -*-
@setfilename binutils.info
+@include config.texi
@ifinfo
@format
@end ifinfo
@ifinfo
-Copyright @copyright{} 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 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, 96, 1997 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
+@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, 1994 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@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
@item c++filt
Demangle encoded C++ symbols
+@item addr2line
+Convert addresses into file names and line numbers
+
@item nlmconv
Convert object code into a Netware Loadable Module
+
+@item windres
+Manipulate Windows resources
@end table
@end iftex
* strings:: List printable strings from files
* strip:: Discard symbols
* c++filt:: Filter to demangle encoded C++ symbols
+* addr2line:: Convert addresses to file and line
* nlmconv:: Converts object code into an NLM
+* windres:: Manipulate Windows resources
* Selecting The Target System:: How these utilities determine the target.
-* Index::
+* Reporting Bugs:: Reporting Bugs
+* Index:: Index
@end menu
@node ar
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
[ -r | --reverse-sort ] [ --size-sort ] [ -u | --undefined-only ]
[ -t @var{radix} | --radix=@var{radix} ] [ -P | --portability ]
[ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ]
+ [ --defined-only ] [-l | --line-numbers ]
[ --no-demangle ] [ -V | --version ] [ --help ] [ @var{objfile}@dots{} ]
@end smallexample
-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
@item -C
@itemx --demangle
-@cindex demangling C++ symbols
+@cindex demangling in nm
Decode (@dfn{demangle}) low-level symbol names into user-level names.
Besides removing any initial underscore prepended by the system, this
makes C++ function names readable. @xref{c++filt}, for more information
@cindex external symbols
Display only external symbols.
+@item -l
+@itemx --line-numbers
+@cindex symbol line numbers
+For each symbol, use debugging information to try to find a filename and
+line number. For a defined symbol, look for the line number of the
+address of the symbol. For an undefined symbol, look for the line
+number of a relocation entry which refers to the symbol. If line number
+information can be found, print it after the other symbol information.
+
@item -n
@itemx -v
@itemx --numeric-sort
@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 ]
[ -b @var{byte} | --byte=@var{byte} ]
[ -i @var{interleave} | --interleave=@var{interleave} ]
[ -R @var{sectionname} | --remove-section=@var{sectionname} ]
+ [ -p | --preserve-dates ] [ --debugging ]
+ [ --gap-fill=@var{val} ] [ --pad-to=@var{address} ]
[ --set-start=@var{val} ] [ --adjust-start=@var{incr} ]
[ --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} ]
+ [ --change-leading-char ] [ --remove-leading-char ]
+ [ --weaken ]
[ -v | --verbose ] [ -V | --version ] [ --help ]
@var{infile} [@var{outfile}]
@end smallexample
and thus is able to recognize most formats without being told
explicitly. @xref{BFD,,BFD,ld.info,Using LD}.
+@code{objcopy} can be used to generate S-records by using an output
+target of @samp{srec} (e.g., use @samp{-O srec}).
+
+@code{objcopy} can be used to generate a raw binary file by using an
+output target of @samp{binary} (e.g., use @samp{-O binary}). When
+@code{objcopy} generates a raw binary file, it will essentially produce
+a memory dump of the contents of the input object file. All symbols and
+relocation information will be discarded. The memory dump will start at
+the load address of the lowest section copied into the output file.
+
+When generating an S-record or a raw binary file, it may be helpful to
+use @samp{-S} to remove sections containing debugging information. In
+some cases @samp{-R} will be useful to remove sections which contain
+information which is not needed by the binary file.
+
@table @code
@item @var{infile}
@itemx @var{outfile}
@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.
@code{objcopy} ignores this option if you do not specify either @samp{-b} or
@samp{--byte}.
+@item -p
+@itemx --preserve-dates
+Set the access and modification dates of the output file to be the same
+as those of the input file.
+
+@item --debugging
+Convert debugging information, if possible. This is not the default
+because only certain debugging formats are supported, and the
+conversion process can be time consuming.
+
+@item --gap-fill @var{val}
+Fill gaps between sections with @var{val}. This 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.
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 --change-leading-char
+Some object file formats use special characters at the start of
+symbols. The most common such character is underscore, which compilers
+often add before every symbol. This option tells @code{objcopy} to
+change the leading character of every symbol when it converts between
+object file formats. If the object file formats use the same leading
+character, this option has no effect. Otherwise, it will add a
+character, or remove a character, or change a character, as
+appropriate.
+
+@item --remove-leading-char
+If the first character of a global symbol is a special symbol leading
+character used by the object file format, remove the character. The
+most common symbol leading character is underscore. This option will
+remove a leading underscore from all global symbols. This can be useful
+if you want to link together objects of different file formats with
+different conventions for symbol names. This is different from
+@code{--change-leading-char} because it always changes the symbol name
+when appropriate, regardless of the object file format of the output
+file.
+
+@item --weaken
+Change all global symbols in the file to be weak. This can be useful
+when building an object which will be linked against other objects using
+the @code{-R} option to the linker. This option is only effective when
+using an object file format which supports weak symbols.
+
@item -V
@itemx --version
Show the version number of @code{objcopy}.
@smallexample
objdump [ -a | --archive-headers ]
- [ -b @var{bfdname} | --target=@var{bfdname} ]
- [ -d | --disassemble ] [ -D | --disassemble-all ]
+ [ -b @var{bfdname} | --target=@var{bfdname} ] [ --debugging ]
+ [ -C | --demangle ] [ -d | --disassemble ]
+ [ -D | --disassemble-all ] [ --disassemble-zeroes ]
+ [ -EB | -EL | --endian=@{big | little @} ]
[ -f | --file-headers ]
[ -h | --section-headers | --headers ] [ -i | --info ]
[ -j @var{section} | --section=@var{section} ]
- [ -l | --line-numbers ]
+ [ -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 ]
- [ --version ] [ --help ] @var{objfile}@dots{}
+ [ -w | --wide ] [ --start-address=@var{address} ]
+ [ --stop-address=@var{address} ]
+ [ --prefix-addresses] [ --[no-]show-raw-insn ]
+ [ --adjust-vma=@var{offset} ]
+ [ --version ] [ --help ]
+ @var{objfile}@dots{}
@end smallexample
@code{objdump} displays information about one or more object files.
information you could list with @samp{ar tv}, @samp{objdump -a} shows
the object file format of each archive member.
+@item --adjust-vma=@var{offset}
+@cindex section addresses in objdump
+@cindex VMA in objdump
+When dumping information, first add @var{offset} to all the section
+addresses. This is useful if the section addresses do not correspond to
+the symbol table, which can happen when putting sections at particular
+addresses when using a format which can not represent section addresses,
+such as a.out.
+
@item -b @var{bfdname}
@itemx --target=@var{bfdname}
@cindex object code format
formats available with the @samp{-i} option.
@xref{Target Selection}, for more information.
+@item -C
+@itemx --demangle
+@cindex demangling in objdump
+Decode (@dfn{demangle}) low-level symbol names into user-level names.
+Besides removing any initial underscore prepended by the system, this
+makes C++ function names readable. @xref{c++filt}, for more information
+on demangling.
+
+@item --debugging
+Display debugging information. This attempts to parse debugging
+information stored in the file and print it out using a C like syntax.
+Only certain types of debugging information have been implemented.
+
@item -d
@itemx --disassemble
@cindex disassembling object code
Like @samp{-d}, but disassemble the contents of all sections, not just
those expected to contain instructions.
+@item --prefix-addresses
+When disassembling, print the complete address on each line. This is
+the older disassembly format.
+
+@item --disassemble-zeroes
+Normally the disassembly output will skip blocks of zeroes. This
+option directs the disassembler to disassemble those blocks, just like
+any other data.
+
+@item -EB
+@itemx -EL
+@itemx --endian=@{big|little@}
+@cindex endianness
+@cindex disassembly endianness
+Specify the endianness of the object files. This only affects
+disassembly. This can be useful when disassembling a file format which
+does not describe endianness information, such as S-records.
+
@item -f
@itemx --file-header
@cindex object file header
@item -l
@itemx --line-numbers
@cindex source filenames for object files
-Label the display (using debugging information) with the filename
-and source line numbers corresponding to the object code shown.
-Only useful with @samp{-d} or @samp{-D}.
+Label the display (using debugging information) with the filename and
+source line numbers corresponding to the object code or relocs shown.
+Only useful with @samp{-d}, @samp{-D}, or @samp{-r}.
@item -m @var{machine}
@itemx --architecture=@var{machine}
@cindex architecture
-Specify that the object files @var{objfile} are for architecture
-@var{machine}. You can list available architectures using the @samp{-i}
-option.
+@cindex disassembly architecture
+Specify the architecture to use when disassembling object files. This
+can be useful when disasembling object files which do not describe
+architecture information, such as S-records. You can list the available
+architectures with the @samp{-i} option.
@item -r
@itemx --reloc
@cindex object file sections
Display the full contents of any sections requested.
+@item -S
+@itemx --source
+@cindex source disassembly
+@cindex disassembly, with source
+Display source code intermixed with disassembly, if possible. Implies
+@samp{-d}.
+
+@item --show-raw-insn
+When disassembling instructions, print the instruction in hex as well as
+in symbolic form. This is the default except when
+@code{--prefix-addresses} is used.
+
+@item --no-show-raw-insn
+When disassembling instructions, do not print the instruction bytes.
+This is the default when @code{--prefix-addresses} is used.
+
@item --stabs
@cindex stab
@cindex .stab
@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
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} ]
+ [ -o @var{file} ] [ -p | --preserve-dates ]
[ -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.
@itemx --strip-debug
Remove debugging symbols only.
+@item --strip-unneeded
+Remove all symbols that are not needed for relocation processing.
+
+@item -K @var{symbolname}
+@itemx --keep-symbol=@var{symbolname}
+Keep only symbol @var{symbolname} from the source file. This option may
+be given more than once.
+
+@item -N @var{symbolname}
+@itemx --strip-symbol=@var{symbolname}
+Remove symbol @var{symbolname} from the source file. This option may be
+given more than once, and may be combined with strip options other than
+@code{-K}.
+
+@item -o @var{file}
+Put the stripped output in @var{file}, rather than replacing the
+existing file. When this argument is used, only one @var{objfile}
+argument may be specified.
+
+@item -p
+@itemx --preserve-dates
+Preserve the access and modification dates of the file.
+
@item -x
@itemx --discard-all
Remove non-global symbols.
@item -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
@end example
@end quotation
+@node addr2line
+@chapter addr2line
+
+@kindex addr2line
+@cindex address to file name and line number
+
+@smallexample
+addr2line [ -b @var{bfdname} | --target=@var{bfdname} ]
+ [ -C | --demangle ]
+ [ -e @var{filename} | --exe=@var{filename} ]
+ [ -f | --functions ] [ -s | --basename ]
+ [ -H | --help ] [ -V | --version ]
+ [ addr addr ... ]
+@end smallexample
+
+@code{addr2line} translates program addresses into file names and line
+numbers. Given an address and an executable, it uses the debugging
+information in the executable to figure out which file name and line
+number are associated with a given address.
+
+The executable to use is specified with the @code{-e} option. The
+default is @file{a.out}.
+
+@code{addr2line} has two modes of operation.
+
+In the first, hexadecimal addresses are specified on the command line,
+and @code{addr2line} displays the file name and line number for each
+address.
+
+In the second, @code{addr2line} reads hexadecimal addresses from
+standard input, and prints the file name and line number for each
+address on standard output. In this mode, @code{addr2line} may be used
+in a pipe to convert dynamically chosen addresses.
+
+The format of the output is @samp{FILENAME:LINENO}. The file name and
+line number for each address is printed on a separate line. If the
+@code{-f} option is used, then each @samp{FILENAME:LINENO} line is
+preceded by a @samp{FUNCTIONNAME} line which is the name of the function
+containing the address.
+
+If the file name or function name can not be determined,
+@code{addr2line} will print two question marks in their place. If the
+line number can not be determined, @code{addr2line} will print 0.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+
+@table @code
+@item -b @var{bfdname}
+@itemx --target=@var{bfdname}
+@cindex object code format
+Specify that the object-code format for the object files is
+@var{bfdname}.
+
+@item -C
+@itemx --demangle
+@cindex demangling in objdump
+Decode (@dfn{demangle}) low-level symbol names into user-level names.
+Besides removing any initial underscore prepended by the system, this
+makes C++ function names readable. @xref{c++filt}, for more information
+on demangling.
+
+@item -e @var{filename}
+@itemx --exe=@var{filename}
+Specify the name of the executable for which addresses should be
+translated. The default file is @file{a.out}.
+
+@item -f
+@itemx --functions
+Display function names as well as file and line number information.
+
+@item -s
+@itemx --basenames
+Display only the base of each file name.
+@end table
+
@node nlmconv
@chapter nlmconv
Prints the version number for @code{nlmconv}.
@end table
+@node windres
+@chapter windres
+
+@code{windres} may be used to manipulate Windows resources.
+
+@quotation
+@emph{Warning:} @code{windres} is not always built as part of the binary
+utilities, since it is only useful for Windows targets.
+@end quotation
+
+@smallexample
+windres [options] [input-file] [output-file]
+@end smallexample
+
+@code{windres} reads resources from an input file and copies them into
+an output file. Either file may be in one of three formats:
+
+@table @code
+@item rc
+A text format read by the Resource Compiler.
+
+@item res
+A binary format generated by the Resource Compiler.
+
+@item coff
+A COFF object or executable.
+@end table
+
+The exact description of these different formats is available in
+documentation from Microsoft.
+
+When @code{windres} converts from the @code{rc} format to the @code{res}
+format, it is acting like the Windows Resource Compiler. When
+@code{windres} converts from the @code{res} format to the @code{coff}
+format, it is acting like the Windows @code{CVTRES} program.
+
+When @code{windres} generates an @code{rc} file, the output is similar
+but not identical to the format expected for the input. When an input
+@code{rc} file refers to an external filename, an output @code{rc} file
+will instead include the file contents.
+
+If the input or output format is not specified, @code{windres} will
+guess based on the file name, or, for the input file, the file contents.
+A file with an extension of @file{.rc} will be treated as an @code{rc}
+file, a file with an extension of @file{.res} will be treated as a
+@code{res} file, and a file with an extension of @file{.o} or
+@file{.exe} will be treated as a @code{coff} file.
+
+If no output file is specified, @code{windres} will print the resources
+in @code{rc} format to standard output.
+
+The normal use is for you to write an @code{rc} file, use @code{windres}
+to convert it to a COFF object file, and then link the COFF file into
+your application. This will make the resources described in the
+@code{rc} file available to Windows.
+
+@table @code
+@item -i @var{filename}
+@itemx --input @var{filename}
+The name of the input file. If this option is not used, then
+@code{windres} will use the first non-option argument as the input file
+name. If there are no non-option arguments, then @code{windres} will
+read from standard input. @code{windres} can not read a COFF file from
+standard input.
+
+@item -o @var{filename}
+@itemx --output @var{filename}
+The name of the output file. If this option is not used, then
+@code{windres} will use the first non-option argument, after any used
+for the input file name, as the output file name. If there is no
+non-option argument, then @code{windres} will write to standard output.
+@code{windres} can not write a COFF file to standard output.
+
+@item -I @var{format}
+@itemx --input-format @var{format}
+The input format to read. @var{format} may be @samp{res}, @samp{rc}, or
+@samp{coff}. If no input format is specified, @code{windres} will
+guess, as described above.
+
+@item -O @var{format}
+@itemx --output-format @var{format}
+The output format to generate. @var{format} may be @samp{res},
+@samp{rc}, or @samp{coff}. If no output format is specified,
+@code{windres} will guess, as described above.
+
+@item -F @var{target}
+@itemx --target @var{target}
+Specify the BFD format to use for a COFF file as input or output. This
+is a BFD target name; you can use the @code{--help} option to see a list
+of supported targets. Normally @code{windres} will use the default
+format, which is the first one listed by the @code{--help} option.
+@ref{Target Selection}.
+
+@item --preprocessor @var{program}
+When @code{windres} reads an @code{rc} file, it runs it through the C
+preprocessor first. This option may be used to specify the preprocessor
+to use, including any leading arguments. The default preprocessor
+argument is @code{gcc -E -xc-header -DRC_INVOKED}.
+
+@item --include-dir @var{directory}
+Specify an include directory to use when reading an @code{rc} file.
+@code{windres} will pass this to the preprocessor as an @code{-I}
+option. @code{windres} will also search this directory when looking for
+files named in the @code{rc} file.
+
+@item --define @var{sym[=val]}
+Specify a @code{-D} option to pass to the preprocessor when reading an
+@code{rc} file.
+
+@item --language @var{val}
+Specify the default language to use when reading an @code{rc} file.
+@var{val} should be a hexadecimal language code. The low eight bits are
+the language, and the high eight bits are the sublanguage.
+
+@item --help
+Prints a usage summary.
+
+@item --version
+Prints the version number for @code{windres}.
+
+@item --yydebug
+If @code{windres} is compiled with @code{YYDEBUG} defined as @code{1},
+this will turn on parser debugging.
+@end table
+
@node Selecting The Target System
@chapter Selecting the target system
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
+@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).
Some sample values are: @samp{a.out-hp300bsd}, @samp{ecoff-littlemips},
@samp{a.out-sunos-big}.
+You can also specify a target using a configuration triplet. This is
+the same sort of name that is passed to configure to specify a target.
+When you use a configuration triplet as an argument, it must be fully
+canonicalized. You can see the canonical version of a triplet by
+running the shell script @file{config.sub} which is included with the
+sources.
+
+Some sample configuration triplets are: @samp{m68k-hp-bsd},
+@samp{mips-dec-ultrix}, @samp{sparc-sun-sunos}.
+
@subheading @code{objdump} Target
Ways to specify:
which comes from @code{EMUL} in @file{config/@var{target}.mt}
@end enumerate
+@node Reporting Bugs
+@chapter Reporting Bugs
+@cindex bugs
+@cindex reporting bugs
+
+Your bug reports play an essential role in making the binary utilities
+reliable.
+
+Reporting a bug may help you by bringing a solution to your problem, or
+it may not. But in any case the principal function of a bug report is
+to help the entire community by making the next version of the binary
+utilities work better. Bug reports are your contribution to their
+maintenance.
+
+In order for a bug report to serve its purpose, you must include the
+information that enables us to fix the bug.
+
+@menu
+* Bug Criteria:: Have you found a bug?
+* Bug Reporting:: How to report bugs
+@end menu
+
+@node Bug Criteria
+@section Have you found a bug?
+@cindex bug criteria
+
+If you are not sure whether you have found a bug, here are some guidelines:
+
+@itemize @bullet
+@cindex fatal signal
+@cindex crash
+@item
+If a binary utility gets a fatal signal, for any input whatever, that is
+a bug. Reliable utilities never crash.
+
+@cindex error on valid input
+@item
+If a binary utility produces an error message for valid input, that is a
+bug.
+
+@item
+If you are an experienced user of binary utilities, your suggestions for
+improvement are welcome in any case.
+@end itemize
+
+@node Bug Reporting
+@section How to report bugs
+@cindex bug reports
+@cindex bugs, reporting
+
+A number of companies and individuals offer support for @sc{gnu}
+products. If you obtained the binary utilities from a support
+organization, we recommend you contact that organization first.
+
+You can find contact information for many support companies and
+individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
+distribution.
+
+In any event, we also recommend that you send bug reports for the binary
+utilities to @samp{bug-gnu-utils@@prep.ai.mit.edu}.
+
+The fundamental principle of reporting bugs usefully is this:
+@strong{report all the facts}. If you are not sure whether to state a
+fact or leave it out, state it!
+
+Often people omit facts because they think they know what causes the
+problem and assume that some details do not matter. Thus, you might
+assume that the name of a file you use in an example does not matter.
+Well, probably it does not, but one cannot be sure. Perhaps the bug is
+a stray memory reference which happens to fetch from the location where
+that pathname is stored in memory; perhaps, if the pathname were
+different, the contents of that location would fool the utility into
+doing the right thing despite the bug. Play it safe and give a
+specific, complete example. That is the easiest thing for you to do,
+and the most helpful.
+
+Keep in mind that the purpose of a bug report is to enable us to fix the bug if
+it is new to us. Therefore, always write your bug reports on the assumption
+that the bug has not been reported previously.
+
+Sometimes people give a few sketchy facts and ask, ``Does this ring a
+bell?'' Those bug reports are useless, and we urge everyone to
+@emph{refuse to respond to them} except to chide the sender to report
+bugs properly.
+
+To enable us to fix the bug, you should include all these things:
+
+@itemize @bullet
+@item
+The version of the utility. Each utility announces it if you start it
+with the @samp{--version} argument.
+
+Without this, we will not know whether there is any point in looking for
+the bug in the current version of the binary utilities.
+
+@item
+Any patches you may have applied to the source, including any patches
+made to the @code{BFD} library.
+
+@item
+The type of machine you are using, and the operating system name and
+version number.
+
+@item
+What compiler (and its version) was used to compile the utilities---e.g.
+``@code{gcc-2.7}''.
+
+@item
+The command arguments you gave the utility to observe the bug. To
+guarantee you will not omit something important, list them all. A copy
+of the Makefile (or the output from make) is sufficient.
+
+If we were to try to guess the arguments, we would probably guess wrong
+and then we might not encounter the bug.
+
+@item
+A complete input file, or set of input files, that will reproduce the
+bug. If the utility is reading an object file or files, then it is
+generally most helpful to send the actual object files, uuencoded if
+necessary to get them through the mail system. Making them available
+for anonymous FTP is not as good, but may be the only reasonable choice
+for large object files.
+
+If the source files were produced exclusively using @sc{gnu} programs
+(e.g., @code{gcc}, @code{gas}, and/or the @sc{gnu} @code{ld}), then it
+may be OK to send the source files rather than the object files. In
+this case, be sure to say exactly what version of @code{gcc}, or
+whatever, was used to produce the object files. Also say how
+@code{gcc}, or whatever, was configured.
+
+@item
+A description of what behavior you observe that you believe is
+incorrect. For example, ``It gets a fatal signal.''
+
+Of course, if the bug is that the utility gets a fatal signal, then we
+will certainly notice it. But if the bug is incorrect output, we might
+not notice unless it is glaringly wrong. You might as well not give us
+a chance to make a mistake.
+
+Even if the problem you experience is a fatal signal, you should still
+say so explicitly. Suppose something strange is going on, such as, your
+copy of the utility is out of synch, or you have encountered a bug in
+the C library on your system. (This has happened!) Your copy might
+crash and ours would not. If you told us to expect a crash, then when
+ours fails to crash, we would know that the bug was not happening for
+us. If you had not told us to expect a crash, then we would not be able
+to draw any conclusion from our observations.
+
+@item
+If you wish to suggest changes to the source, send us context diffs, as
+generated by @code{diff} with the @samp{-u}, @samp{-c}, or @samp{-p}
+option. Always send diffs from the old file to the new file. If you
+even discuss something in the @code{ld} source, refer to it by context,
+not by line number.
+
+The line numbers in our development sources will not match those in your
+sources. Your line numbers would convey no useful information to us.
+@end itemize
+
+Here are some things that are not necessary:
+
+@itemize @bullet
+@item
+A description of the envelope of the bug.
+
+Often people who encounter a bug spend a lot of time investigating
+which changes to the input file will make the bug go away and which
+changes will not affect it.
+
+This is often time consuming and not very useful, because the way we
+will find the bug is by running a single example under the debugger
+with breakpoints, not by pure deduction from a series of examples.
+We recommend that you save your time for something else.
+
+Of course, if you can find a simpler example to report @emph{instead}
+of the original one, that is a convenience for us. Errors in the
+output will be easier to spot, running under the debugger will take
+less time, and so on.
+
+However, simplification is not vital; if you do not want to do this,
+report the bug anyway and send us the entire test case you used.
+
+@item
+A patch for the bug.
+
+A patch for the bug does help us if it is a good one. But do not omit
+the necessary information, such as the test case, on the assumption that
+a patch is all we need. We might see problems with your patch and decide
+to fix the problem another way, or we might not understand it at all.
+
+Sometimes with programs as complicated as the binary utilities it is
+very hard to construct an example that will make the program follow a
+certain path through the code. If you do not send us the example, we
+will not be able to construct one, so we will not be able to verify that
+the bug is fixed.
+
+And if we cannot understand what bug you are trying to fix, or why your
+patch should be an improvement, we will not install it. A test case will
+help us to understand.
+
+@item
+A guess about what the bug is or what it depends on.
+
+Such guesses are usually wrong. Even we cannot guess right about such
+things without first using the debugger to find the facts.
+@end itemize
+
@node Index
@unnumbered Index