@end ifinfo
@ifinfo
-Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@c This file documents the GNU binary utilities "ar", "ld", "objcopy",
@c "objdump", "nm", "size", "strings", "strip", and "ranlib".
@c
-@c Copyright (C) 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
+@c Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
@c
@c This text may be freely distributed under the terms of the GNU
@c General Public License.
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 1997 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@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.
* Reporting Bugs:: Reporting Bugs
* Index:: Index
@item q
@cindex quick append to archive
-@emph{Quick append}; add the files @var{member}@dots{} to the end of
+@emph{Quick append}; Historically, add the files @var{member}@dots{} to the end of
@var{archive}, without checking for replacement.
The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this
index is not updated, even if it already existed; you can use @samp{ar s} or
@code{ranlib} explicitly to update the symbol table index.
+However, too many different systems assume quick append rebuilds the
+index, so GNU ar implements @code{q} as a synonym for @code{r}.
+
@item r
@cindex replacement in archive
Insert the files @var{member}@dots{} into @var{archive} (with
flag either with any operation, or alone. Running @samp{ar s} on an
archive is equivalent to running @samp{ranlib} on it.
+@item S
+@cindex not writing archive index
+Do not generate an archive symbol table. This can speed up building a
+large library in several steps. The resulting archive can not be used
+with the linker. In order to build a symbol table, you must omit the
+@samp{S} modifier on the last execution of @samp{ar}, or you must run
+@samp{ranlib} on the archive.
+
@item u
@cindex updating an archive
Normally, @samp{ar r}@dots{} inserts all files
@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
[ -S | --strip-all ] [ -g | --strip-debug ]
[ -K @var{symbolname} | --keep-symbol=@var{symbolname} ]
[ -N @var{symbolname} | --strip-symbol=@var{symbolname} ]
+ [ -L @var{symbolname} | --localize-symbol=@var{symbolname} ]
+ [ -W @var{symbolname} | --weaken-symbol=@var{symbolname} ]
[ -x | --discard-all ] [ -X | --discard-locals ]
[ -b @var{byte} | --byte=@var{byte} ]
[ -i @var{interleave} | --interleave=@var{interleave} ]
[ -R @var{sectionname} | --remove-section=@var{sectionname} ]
- [ --debugging ]
+ [ -p | --preserve-dates ] [ --debugging ]
[ --gap-fill=@var{val} ] [ --pad-to=@var{address} ]
[ --set-start=@var{val} ] [ --adjust-start=@var{incr} ]
[ --adjust-vma=@var{incr} ]
@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}.
+may be given more than once.
+
+@item -L @var{symbolname}
+@itemx --localize-symbol=@var{symbolname}
+Make symbol @var{symbolname} local to the file, so that it is not
+visible externally. This option may be given more than once.
+
+@item -W @var{symbolname}
+@itemx --weaken-symbol=@var{symbolname}
+Make symbol @var{symbolname} weak. This option may be given more than once.
@item -x
@itemx --discard-all
@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
+Fill gaps between sections with @var{val}. This operation applies to
+the @emph{load address} (LMA) of the sections. It is done by increasing
the size of the section with the lower address, and filling in the extra
space created with @var{val}.
@item --pad-to @var{address}
-Pad the output file up to the virtual address @var{address}. This is
+Pad the output file up to the load address @var{address}. This is
done by increasing the size of the last section. The extra space is
filled in with the value specified by @samp{--gap-fill} (default zero).
@item --set-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.
+@samp{alloc}, @samp{contents}, @samp{load}, @samp{readonly},
+@samp{code}, @samp{data}, and @samp{rom}. You can set the
+@samp{contents} flag for a section which does not have contents, but it
+is not meaningful to clear the @samp{contents} flag of a section which
+does have contents--just remove the section instead. Not all flags are
+meaningful for all object file formats.
@item --add-section @var{sectionname}=@var{filename}
Add a new section named @var{sectionname} while copying the file. The
@smallexample
objdump [ -a | --archive-headers ]
[ -b @var{bfdname} | --target=@var{bfdname} ] [ --debugging ]
- [ -d | --disassemble ] [ -D | --disassemble-all ]
- [ --disassemble-zeroes ]
+ [ -C | --demangle ] [ -d | --disassemble ]
+ [ -D | --disassemble-all ] [ --disassemble-zeroes ]
[ -EB | -EL | --endian=@{big | little @} ]
[ -f | --file-headers ]
[ -h | --section-headers | --headers ] [ -i | --info ]
[ -t | --syms ] [ -T | --dynamic-syms ] [ -x | --all-headers ]
[ -w | --wide ] [ --start-address=@var{address} ]
[ --stop-address=@var{address} ]
- [ --prefix-addresses] [ --show-raw-insn ]
+ [ --prefix-addresses] [ --[no-]show-raw-insn ]
[ --adjust-vma=@var{offset} ]
[ --version ] [ --help ]
@var{objfile}@dots{}
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.
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
@samp{-a -f -h -r -t}.
@item -w
-@item --wide
+@itemx --wide
@cindex wide output, printing
Format some lines for output devices that have more than 80 columns.
@end table
size [ -A | -B | --format=@var{compatibility} ]
[ --help ] [ -d | -o | -x | --radix=@var{number} ]
[ --target=@var{bfdname} ] [ -V | --version ]
- @var{objfile}@dots{}
+ [ @var{objfile}@dots{} ]
@end smallexample
The @sc{gnu} @code{size} utility lists the section sizes---and the total
object file or each module in an archive.
@var{objfile}@dots{} are the object files to be examined.
+If none are specified, the file @code{a.out} will be used.
The command line options have the following meanings:
@item --help
Print a summary of the program usage on the standard output and exit.
-@itemx -@var{min-len}
-@item -n @var{min-len}
+@item -@var{min-len}
+@itemx -n @var{min-len}
@itemx --bytes=@var{min-len}
Print sequences of characters that are at least @var{min-len} characters
long, instead of the default 4.
@cindex symbols, discarding
@smallexample
-strip [ -F @var{bfdname} | --target=@var{bfdname} | --target=@var{bfdname} ]
+strip [ -F @var{bfdname} | --target=@var{bfdname} ]
[ -I @var{bfdname} | --input-target=@var{bfdname} ]
[ -O @var{bfdname} | --output-target=@var{bfdname} ]
[ -s | --strip-all ] [ -S | -g | --strip-debug ]
[ -N @var{symbolname} | --strip-symbol=@var{symbolname} ]
[ -x | --discard-all ] [ -X | --discard-locals ]
[ -R @var{sectionname} | --remove-section=@var{sectionname} ]
- [ -o @var{file} ]
+ [ -o @var{file} ] [ -p | --preserve-dates ]
[ -v | --verbose ] [ -V | --version ] [ --help ]
@var{objfile}@dots{}
@end smallexample
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.
@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
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}.
+utilities to @samp{bug-gnu-utils@@gnu.org}.
The fundamental principle of reporting bugs usefully is this:
@strong{report all the facts}. If you are not sure whether to state a
projects / deliverable / binutils-gdb.git / blobdiff