\input texinfo @c -*- Texinfo -*-
@setfilename binutils.info
-@c Copyright 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c Copyright 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
+@c man begin INCLUDE
@include config.texi
+@c man end
@ifinfo
@format
@ifinfo
@c man begin COPYRIGHT
Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
@c "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib".
@c
@c Copyright (C) 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999,
-@c 2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+@c 2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
@c
@c This text may be freely distributed under the terms of the GNU
@c Free Documentation License.
@vskip 0pt plus 1filll
Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
-2000, 2001, 2002, 2003, 2004, 2005 Free Software Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1
* nlmconv:: Converts object code into an NLM
* windres:: Manipulate Windows resources
* dlltool:: Create files needed to build and use DLLs
+* Common Options:: Command-line options for all utilities
* Selecting The Target System:: How these utilities determine the target.
* Reporting Bugs:: Reporting Bugs
* GNU Free Documentation License:: GNU Free Documentation License
[@option{--prefix-sections=}@var{string}]
[@option{--prefix-alloc-sections=}@var{string}]
[@option{--add-gnu-debuglink=}@var{path-to-file}]
+ [@option{--keep-file-symbols}]
[@option{--only-keep-debug}]
[@option{--writable-text}]
[@option{--readonly-text}]
@var{index}th code instead of the default one. This is useful in case
a machine is assigned an official code and the tool-chain adopts the
new code, but other applications still depend on the original code
-being used.
+being used. For ELF based architectures if the @var{index}
+alternative does not exist then the value is treated as an absolute
+number to be stored in the e_machine field of the ELF header.
@item --writable-text
Mark the output text as writable. This option isn't meaningful for all
Creates a .gnu_debuglink section which contains a reference to @var{path-to-file}
and adds it to the output file.
+@item --keep-file-symbols
+When stripping a file, perhaps with @option{--strip-debug} or
+@option{--strip-unneeded}, retain any symbols specifying source file names,
+which would otherwise get stripped.
+
@item --only-keep-debug
-Strip a file, removing any sections that would be stripped by
-@option{--strip-debug} and leaving the debugging sections.
+Strip a file, removing contents of any sections that would not be
+stripped by @option{--strip-debug} and leaving the debugging sections
+intact.
The intention is that this option will be used in conjunction with
@option{--add-gnu-debuglink} to create a two part executable. One a
@item Run @code{objcopy --add-gnu-debuglink=foo.full foo}
@end enumerate
-ie the file pointed to by the @option{--add-gnu-debuglink} can be the
+i.e. the file pointed to by the @option{--add-gnu-debuglink} can be the
full executable. It does not have to be a file created by the
@option{--only-keep-debug} switch.
[@option{-r}|@option{--reloc}]
[@option{-R}|@option{--dynamic-reloc}]
[@option{-s}|@option{--full-contents}]
+ [@option{-W}|@option{--dwarf}]
[@option{-G}|@option{--stabs}]
[@option{-t}|@option{--syms}]
[@option{-T}|@option{--dynamic-syms}]
If the target is an ARM architecture then this switch can be used to
select which register name set is used during disassembler. Specifying
-@option{-M reg-name-std} (the default) will select the register names as
+@option{-M reg-names-std} (the default) will select the register names as
used in ARM's instruction set documentation, but with register 13 called
'sp', register 14 called 'lr' and register 15 called 'pc'. Specifying
@option{-M reg-names-apcs} will select the name set used by the ARM
For PPC, @option{booke}, @option{booke32} and @option{booke64} select
disassembly of BookE instructions. @option{32} and @option{64} select
-PowerPC and PowerPC64 disassembly, respectively.
+PowerPC and PowerPC64 disassembly, respectively. @option{e300} selects
+disassembly for the e300 family.
For MIPS, this option controls the printing of instruction mneumonic
names and register names in disassembled instructions. Multiple
When disassembling instructions, do not print the instruction bytes.
This is the default when @option{--prefix-addresses} is used.
+@item -W
+@itemx --dwarf
+@cindex DWARF
+@cindex debug symbols
+Displays the contents of the DWARF debug sections in the file, if any
+are present.
+
@item -G
@itemx --stabs
@cindex stab
[@option{-x}|@option{--discard-all}] [@option{-X} |@option{--discard-locals}]
[@option{-R} @var{sectionname} |@option{--remove-section=}@var{sectionname}]
[@option{-o} @var{file}] [@option{-p}|@option{--preserve-dates}]
+ [@option{--keep-file-symbols}]
[@option{--only-keep-debug}]
[@option{-v} |@option{--verbose}] [@option{-V}|@option{--version}]
[@option{--help}] [@option{--info}]
Remove compiler-generated local symbols.
(These usually start with @samp{L} or @samp{.}.)
+@item --keep-file-symbols
+When stripping a file, perhaps with @option{--strip-debug} or
+@option{--strip-unneeded}, retain any symbols specifying source file names,
+which would otherwise get stripped.
+
@item --only-keep-debug
Strip a file, removing any sections that would be stripped by
@option{--strip-debug} and leaving the debugging sections.
@smallexample
@c man begin SYNOPSIS cxxfilt
c++filt [@option{-_}|@option{--strip-underscores}]
- [@option{-j}|@option{--java}]
[@option{-n}|@option{--no-strip-underscores}]
[@option{-p}|@option{--no-params}]
+ [@option{-t}|@option{--types}]
+ [@option{-i}|@option{--no-verbose}]
[@option{-s} @var{format}|@option{--format=}@var{format}]
[@option{--help}] [@option{--version}] [@var{symbol}@dots{}]
@c man end
@c man begin DESCRIPTION cxxfilt
@kindex cxxfilt
-The C++ and Java languages provides function overloading, which means
-that you can write many functions with the same name (providing each
-takes parameters of different types). All C++ and Java function names
-are encoded into a low-level assembly label (this process is known as
-@dfn{mangling}). The @command{c++filt}
-@footnote{MS-DOS does not allow @kbd{+} characters in file names, so on
+The C++ and Java languages provide function overloading, which means
+that you can write many functions with the same name, providing that
+each function takes parameters of different types. In order to be
+able to distinguish these similarly named functions C++ and Java
+encode them into a low-level assembler name which uniquely identifies
+each different version. This process is known as @dfn{mangling}. The
+@command{c++filt}
+@footnote{MS-DOS does not allow @kbd{+} characters in file names, so on
MS-DOS this program is named @command{CXXFILT}.}
program does the inverse mapping: it decodes (@dfn{demangles}) low-level
-names into user-level names so that the linker can keep these overloaded
-functions from clashing.
+names into user-level names so that they can be read.
Every alphanumeric word (consisting of letters, digits, underscores,
-dollars, or periods) seen in the input is a potential label. If the
-label decodes into a C++ name, the C++ name replaces the low-level
-name in the output.
+dollars, or periods) seen in the input is a potential mangled name.
+If the name decodes into a C++ name, the C++ name replaces the
+low-level name in the output, otherwise the original word is output.
+In this way you can pass an entire assembler source file, containing
+mangled names, through @command{c++filt} and see the same source file
+containing demangled names.
-You can use @command{c++filt} to decipher individual symbols:
+You can also use @command{c++filt} to decipher individual symbols by
+passing them on the command line:
@example
c++filt @var{symbol}
@end example
If no @var{symbol} arguments are given, @command{c++filt} reads symbol
-names from the standard input and writes the demangled names to the
-standard output. All results are printed on the standard output.
+names from the standard input instead. All the results are printed on
+the standard output. The difference between reading names from the
+command line versus reading names from the standard input is that
+command line arguments are expected to be just mangled names and no
+checking is performed to seperate them from surrounding text. Thus
+for example:
+
+@smallexample
+c++filt -n _Z1fv
+@end smallexample
+
+will work and demangle the name to ``f()'' whereas:
+
+@smallexample
+c++filt -n _Z1fv,
+@end smallexample
+
+will not work. (Note the extra comma at the end of the mangled
+name which makes it invalid). This command however will work:
+
+@smallexample
+echo _Z1fv, | c++filt -n
+@end smallexample
+
+and will display ``f(),'' ie the demangled name followed by a
+trailing comma. This behaviour is because when the names are read
+from the standard input it is expected that they might be part of an
+assembler source file where there might be extra, extraneous
+characters trailing after a mangled name. eg:
+
+@smallexample
+ .type _Z1fv, @@function
+@end smallexample
@c man end
When demangling the name of a function, do not display the types of
the function's parameters.
+@item -t
+@itemx --types
+Attempt to demangle types as well as function names. This is disabled
+by default since mangled types are normally only used internally in
+the compiler, and they can be confused with non-mangled names. eg
+a function called ``a'' treated as a mangled type name would be
+demangled to ``signed char''.
+
+@item -i
+@itemx --no-verbose
+Do not include implementation details (if any) in the demangled
+output.
+
@item -s @var{format}
@itemx --format=@var{format}
@command{c++filt} can decode various methods of mangling, used by
[@option{-C}|@option{--demangle}[=@var{style}]]
[@option{-e} @var{filename}|@option{--exe=}@var{filename}]
[@option{-f}|@option{--functions}] [@option{-s}|@option{--basename}]
+ [@option{-i}|@option{--inlines}]
+ [@option{-j}|@option{--section=}@var{name}]
[@option{-H}|@option{--help}] [@option{-V}|@option{--version}]
[addr addr @dots{}]
@c man end
@c man begin DESCRIPTION addr2line
-@command{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.
+@command{addr2line} translates addresses into file names and line numbers.
+Given an address in an executable or an offset in a section of a relocatable
+object, it uses the debugging information to figure out which file name and
+line number are associated with it.
-The executable to use is specified with the @option{-e} option. The
-default is the file @file{a.out}.
+The executable or relocatable object to use is specified with the @option{-e}
+option. The default is the file @file{a.out}. The section in the relocatable
+object to use is specified with the @option{-j} option.
@command{addr2line} has two modes of operation.
@item -s
@itemx --basenames
Display only the base of each file name.
+
+@item -i
+@itemx --inlines
+If the address belongs to a function that was inlined, the source
+information for all enclosing scopes back to the first non-inlined
+function will also be printed. For example, if @code{main} inlines
+@code{callee1} which inlines @code{callee2}, and address is from
+@code{callee2}, the source information for @code{callee1} and @code{main}
+will also be printed.
+
+@item -j
+@itemx --section
+Read offsets relative to the specified section instead of absolute addresses.
@end table
@c man end
[@option{--no-default-excludes}]
[@option{-S}|@option{--as} @var{path-to-assembler}] [@option{-f}|@option{--as-flags} @var{options}]
[@option{-D}|@option{--dllname} @var{name}] [@option{-m}|@option{--machine} @var{machine}]
- [@option{-a}|@option{--add-indirect}] [@option{-U}|@option{--add-underscore}] [@option{-k}|@option{--kill-at}]
- [@option{-A}|@option{--add-stdcall-alias}]
+ [@option{-a}|@option{--add-indirect}]
+ [@option{-U}|@option{--add-underscore}] [@option{--add-stdcall-underscore}]
+ [@option{-k}|@option{--kill-at}] [@option{-A}|@option{--add-stdcall-alias}]
[@option{-p}|@option{--ext-prefix-alias} @var{prefix}]
[@option{-x}|@option{--no-idata4}] [@option{-c}|@option{--no-idata5}] [@option{-i}|@option{--interwork}]
[@option{-n}|@option{--nodelete}] [@option{-t}|@option{--temp-prefix} @var{prefix}]
@item -U
@itemx --add-underscore
Specifies that when @command{dlltool} is creating the exports file it
-should prepend an underscore to the names of the exported functions.
+should prepend an underscore to the names of @emph{all} exported symbols.
+
+@item --add-stdcall-underscore
+Specifies that when @command{dlltool} is creating the exports file it
+should prepend an underscore to the names of exported @emph{stdcall}
+functions. Variable names and non-stdcall function names are not modified.
+This option is useful when creating GNU-compatible import libs for third
+party DLLs that were built with MS-Windows tools.
@item -k
@itemx --kill-at
[@option{-l}|@option{--program-headers}|@option{--segments}]
[@option{-S}|@option{--section-headers}|@option{--sections}]
[@option{-g}|@option{--section-groups}]
- [@option{-N}|@option{--full-section-name}]
+ [@option{-t}|@option{--section-details}]
[@option{-e}|@option{--headers}]
[@option{-s}|@option{--syms}|@option{--symbols}]
[@option{-n}|@option{--notes}]
[@option{-V}|@option{--version-info}]
[@option{-A}|@option{--arch-specific}]
[@option{-D}|@option{--use-dynamic}]
- [@option{-x} <number>|@option{--hex-dump=}<number>]
+ [@option{-x} <number or name>|@option{--hex-dump=}<number or name>]
[@option{-w[liaprmfFsoR]}|
@option{--debug-dump}[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]]
[@option{-I}|@option{-histogram}]
Displays the information contained in the file's section groups, if it
has any.
-@item -N
-@itemx --full-section-name
-@cindex ELF section name information
-Displays the full section name for @option{-S}.
+@item -t
+@itemx --section-details
+@cindex ELF section information
+Displays the detailed section information. Implies @option{-S}.
@item -s
@itemx --symbols
symbol table in the file's dynamic section, rather than the one in the
symbols section.
-@item -x <number>
-@itemx --hex-dump=<number>
+@item -x <number or name>
+@itemx --hex-dump=<number or name>
Displays the contents of the indicated section as a hexadecimal dump.
+A number identifies a particular section by index in the section table;
+any other string identifies all sections with that name in the object file.
@item -w[liaprmfFsoR]
@itemx --debug-dump[=line,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges]
@c man end
@end ignore
+@node Common Options
+@chapter Common Options
+
+The following command-line options are supported by all of the
+programs described in this manual.
+
+@c man begin OPTIONS
+@table @env
+@include at-file.texi
+@c man end
+
+@item --help
+Display the command-line options supported by the program.
+
+@item --version
+Display the version number of the program.
+
+@c man begin OPTIONS
+@end table
+@c man end
+
@node Selecting The Target System
@chapter Selecting the Target System
projects / platform / upstream / binutils.git / blobdiff