\input texinfo @c -*- Texinfo -*-
@setfilename binutils.info
-@c Copyright 2001, 2002, 2003, 2004 Free Software Foundation, Inc.
+@c Copyright 2001, 2002, 2003, 2004, 2005 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 Free Software Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005 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 Free Software Foundation, Inc.
+@c 2000, 2001, 2002, 2003, 2004, 2005 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 Free Software Foundation, Inc.
+2000, 2001, 2002, 2003, 2004, 2005 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{-g}|@option{--strip-debug}]
[@option{-K} @var{symbolname}|@option{--keep-symbol=}@var{symbolname}]
[@option{-N} @var{symbolname}|@option{--strip-symbol=}@var{symbolname}]
+ [@option{--strip-unneeded-symbol=}@var{symbolname}]
[@option{-G} @var{symbolname}|@option{--keep-global-symbol=}@var{symbolname}]
[@option{-L} @var{symbolname}|@option{--localize-symbol=}@var{symbolname}]
+ [@option{--globalize-symbol=}@var{symbolname}]
[@option{-W} @var{symbolname}|@option{--weaken-symbol=}@var{symbolname}]
[@option{-w}|@option{--wildcard}]
[@option{-x}|@option{--discard-all}]
[@option{--weaken}]
[@option{--keep-symbols=}@var{filename}]
[@option{--strip-symbols=}@var{filename}]
+ [@option{--strip-unneeded-symbols=}@var{filename}]
[@option{--keep-global-symbols=}@var{filename}]
[@option{--localize-symbols=}@var{filename}]
+ [@option{--globalize-symbols=}@var{filename}]
[@option{--weaken-symbols=}@var{filename}]
[@option{--alt-machine-code=}@var{index}]
[@option{--prefix-symbols=}@var{string}]
[@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}]
@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.
+When stripping symbols, keep symbol @var{symbolname} even if it would
+normally be stripped. 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.
+@item --strip-unneeded-symbol=@var{symbolname}
+Do not copy symbol @var{symbolname} from the source file unless it is needed
+by a relocation. This option may be given more than once.
+
@item -G @var{symbolname}
@itemx --keep-global-symbol=@var{symbolname}
Keep only symbol @var{symbolname} global. Make all other symbols local
@itemx --weaken-symbol=@var{symbolname}
Make symbol @var{symbolname} weak. This option may be given more than once.
+@item --globalize-symbol=@var{symbolname}
+Give symbol @var{symbolname} global scoping so that it is visible
+outside of the file in which it is defined. This option may be given
+more than once.
+
@item -w
@itemx --wildcard
Permit regular expressions in @var{symbolname}s used in other command
name per line. Line comments may be introduced by the hash character.
This option may be given more than once.
+@item --strip-unneeded-symbols=@var{filename}
+Apply @option{--strip-unneeded-symbol} option to each symbol listed in
+the file @var{filename}. @var{filename} is simply a flat file, with one
+symbol name per line. Line comments may be introduced by the hash
+character. This option may be given more than once.
+
@item --keep-global-symbols=@var{filename}
Apply @option{--keep-global-symbol} option to each symbol listed in the
file @var{filename}. @var{filename} is simply a flat file, with one
name per line. Line comments may be introduced by the hash character.
This option may be given more than once.
+@item --globalize-symbols=@var{filename}
+Apply @option{--globalize-symbol} option to each symbol listed in the file
+@var{filename}. @var{filename} is simply a flat file, with one symbol
+name per line. Line comments may be introduced by the hash character.
+This option may be given more than once.
+
@item --weaken-symbols=@var{filename}
Apply @option{--weaken-symbol} option to each symbol listed in the file
@var{filename}. @var{filename} is simply a flat file, with one symbol
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 register names in
-disassembled instructions. Multiple selections from the
-following may be specified as a comma separated string, and invalid
-options are ignored:
+For MIPS, this option controls the printing of instruction mneumonic
+names and register names in disassembled instructions. Multiple
+selections from the following may be specified as a comma separated
+string, and invalid options are ignored:
@table @code
+@item no-aliases
+Print the 'raw' instruction mneumonic instead of some pseudo
+instruction mneumonic. I.E. print 'daddu' or 'or' instead of 'move',
+'sll' instead of 'nop', etc.
+
@item gpr-names=@var{ABI}
Print GPR (general-purpose register) names as appropriate
for the specified ABI. By default, GPR names are selected according to
You can list the available values of @var{ABI} and @var{ARCH} using
the @option{--help} option.
+For VAX, you can specify function entry addresses with @option{-M
+entry:0xf00ba}. You can use this multiple times to properly
+disassemble VAX binary files that don't contain symbol tables (like
+ROM dumps). In these cases, the function entry mask would otherwise
+be decoded as VAX instructions, which would probably lead the the rest
+of the function being wrongly disassembled.
+
@item -p
@itemx --private-headers
Print information that is specific to the object file format. The exact
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}]
@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.
+When stripping symbols, keep symbol @var{symbolname} even if it would
+normally be stripped. This option may be given more than once.
@item -N @var{symbolname}
@itemx --strip-symbol=@var{symbolname}
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
-MS-DOS this program is named @command{cxxfilt}.}
+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{-H}|@option{--help}] [@option{-V}|@option{--version}]
[addr addr @dots{}]
@c man end
@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.
@end table
@c man end
[@option{-h}|@option{--file-header}]
[@option{-l}|@option{--program-headers}|@option{--segments}]
[@option{-S}|@option{--section-headers}|@option{--sections}]
+ [@option{-g}|@option{--section-groups}]
+ [@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 headers, if it
has any.
+@item -g
+@itemx --section-groups
+@cindex ELF section group information
+Displays the information contained in the file's section groups, if it
+has any.
+
+@item -t
+@itemx --section-details
+@cindex ELF section information
+Displays the detailed section information. Implies @option{-S}.
+
@item -s
@itemx --symbols
@itemx --syms
Displays the contents of the file's unwind section, if it has one. Only
the unwind sections for IA64 ELF files are currently supported.
-@item -u
-@itemx --unwind
-@cindex unwind information
-Displays the contents of the file's unwind section, if it has one. Only
-the unwind sections for IA64 ELF files are currently supported.
-
@item -d
@itemx --dynamic
@cindex ELF dynamic section information
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 @value{top_srcdir}/../libiberty/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 / deliverable / binutils-gdb.git / blobdiff