@ifinfo
@format
START-INFO-DIR-ENTRY
-* Binutils: (binutils). The GNU binary utilities "ar", "ld", "copy",
- "objdump", "nm", "size", "strip", and "ranlib".
+* Binutils:: The GNU binary utilities "ar", "ld", "objcopy",
+ "objdump", "nm", "size", "strings", "strip", and "ranlib".
END-INFO-DIR-ENTRY
@end format
@end ifinfo
@ifinfo
-Copyright @copyright{} 1991 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@synindex ky cp
@c
-@c This file documents the GNU binary utilities "ar", "ld", "copy", "objdump",
-@c "nm", "size", "strip", and "ranlib".
+@c This file documents the GNU binary utilities "ar", "ld", "objcopy",
+@c "objdump", "nm", "size", "strings", "strip", and "ranlib".
@c
-@c Copyright (C) 1991 Free Software Foundation, Inc.
+@c Copyright (C) 1991, 1992, 1993 Free Software Foundation, Inc.
@c
@c This text may be freely distributed under the terms of the GNU
@c General Public License.
@titlepage
@finalout
@title The GNU Binary Utilities
-@subtitle Version 2.01
+@subtitle Version 2.2
@sp 1
-@subtitle April 1993
+@subtitle May 1993
@author Roland H. Pesch
@author Cygnus Support
@page
@end tex
@vskip 0pt plus 1filll
-Copyright @copyright{} 1991 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 1992, 1993 Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@cindex version
This brief manual contains preliminary documentation for the GNU binary
-utilities (collectively version 2.1):
+utilities (collectively version 2.2):
@iftex
@table @code
@item ar
Create, modify, and extract from archives
-@item copy
+@item objcopy
Copy and translate object files
@item nm
@item size
List section sizes and total size
+@item strings
+List printable strings from files
+
@item strip
Discard symbols
@end table
@menu
* ar:: Create, modify, and extract from archives
-* copy:: Copy and translate object files
+* objcopy:: Copy and translate object files
* ld:(ld)Overview. Combine object and archive files
* nm:: List symbols from object files
* objdump:: Display information from object files
* ranlib:: Generate index to archive contents
* size:: List section sizes and total size
+* strings:: List printable strings from files
* strip:: Discard symbols
+* c++filt:: Filter to demangle encoded C++ symbols
* Index::
@end menu
-@node ar, copy, Top, Top
+@node ar, objcopy, Top, Top
@chapter ar
@kindex ar
@end table
-@node copy, nm, ar, Top
-@chapter copy
+@node objcopy, nm, ar, Top
+@chapter objcopy
@smallexample
-copy [ -F @var{format} | --format=@var{format} ]
- [ -I @var{format} | --input-format=@var{format} ]
- [ -O @var{format} | --output-format=@var{format} ]
- [ -S | --strip-all ] [ -g | --strip-debug ]
- [ -x | --discard-all ] [ -X | --discard-locals ]
- [ -v | --verbose ] [ -V | --version ]
- @var{infile} [@var{outfile}]
+objcopy [ -F @var{format} | --format=@var{format} ]
+ [ -I @var{format} | --input-format=@var{format} ]
+ [ -O @var{format} | --output-format=@var{format} ]
+ [ -S | --strip-all ] [ -g | --strip-debug ]
+ [ -x | --discard-all ] [ -X | --discard-locals ]
+ [ -v | --verbose ] [ -V | --version ] [ --help ]
+ @var{infile} [@var{outfile}]
@end smallexample
-The GNU @code{copy} utility copies the contents of an object file to
-another. @code{copy} uses the GNU BFD Library to read and write the
+The GNU @code{objcopy} utility copies the contents of an object file to
+another. @code{objcopy} uses the GNU BFD Library to read and write the
object files. It can write the destination object file in a format
different from that of the source object file. The exact behavior of
-@code{copy} is controlled by command-line options.
+@code{objcopy} is controlled by command-line options.
-@code{copy} creates temporary files to do its translations and
-deletes them afterward. @code{copy} uses BFD to do all its
+@code{objcopy} creates temporary files to do its translations and
+deletes them afterward. @code{objcopy} uses BFD to do all its
translation work; it knows about all the formats BFD knows about, and
thus is able to recognize most formats without being told explicitly.
@xref{BFD,,BFD,ld.info,Using LD, the GNU linker}.
@item @var{infile}
@itemx @var{outfile}
The source and output files respectively.
-If you do not specify @var{outfile}, @code{copy} creates a
+If you do not specify @var{outfile}, @code{objcopy} creates a
temporary file and destructively renames the result with
the name of the input file.
@item -V
@itemx --version
-Show the version number of @code{copy}.
+Show the version number of @code{objcopy}.
@item -v
@itemx --verbose
Verbose output: list all object files modified. In the case of
-archives, @samp{copy -V} lists all members of the archive.
+archives, @samp{objcopy -V} lists all members of the archive.
+
+@item --help
+Show a summary of the options to @code{objcopy}.
@end table
@iftex
@xref{Top,, Overview,, Using LD: the GNU linker}.
@end iftex
-@node nm, objdump, copy, Top
+@node nm, objdump, objcopy, Top
@chapter nm
@cindex symbols
@kindex nm
@smallexample
nm [ -a | --debug-syms ] [ -g | --extern-only ]
- [ -s | --print-armap ] [ -o | --print-file-name ]
- [ -n | --numeric-sort ] [ -p | --no-sort ]
+ [ -s | --print-armap ] [ -A | -o | --print-file-name ]
+ [ -n | -v | --numeric-sort ] [ -p | --no-sort ]
[ -r | --reverse-sort ] [ -u | --undefined-only ]
- [ --target=@var{bfdname} ]
- [ @var{objfile}@dots{} ]
+ [ -t @var{radix} | --radix=@var{radix} ] [ -P | --portability ]
+ [ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ]
+ [ -V | --version ] [ --help ] [ @var{objfile}@dots{} ]
@end smallexample
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}.
+
+For each symbol, @code{nm} shows:
+
+@itemize @bullet
+@item
+The symbol value, in the radix selected by options (see below), or
+hexadecimal by default.
+
+@item
+The symbol type. At least the following types are used; others are, as
+well, depending on the object file format. If lowercase, the symbol is
+local; if uppercase, the symbol is global (external).
+
+@c Some more detail on exactly what these symbol types are used for
+@c would be nice.
+@table @code
+@item A
+Absolute.
+
+@item B
+BSS (uninitialized data).
+
+@item C
+Common.
+
+@item D
+Initialized data.
+
+@item I
+Indirect reference.
+
+@item T
+Text (program code).
+
+@item U
+Undefined.
+@end table
+
+@item
+The symbol name.
+@end itemize
The long and short forms of options, shown here as alternatives, are
equivalent.
@table @code
-@item @var{objfile}@dots{}
-@kindex a.out
-Object files whose symbols are to be listed. If no object files are
-listed as arguments, @code{nm} assumes @samp{a.out}.
+@item -A
+@itemx -o
+@itemx --print-file-name
+@cindex input file name
+@cindex file name
+@cindex source file name
+Precede each symbol by the name of the input file (or archive element)
+in which it was found, rather than identifying the input file once only,
+before all of its symbols.
@item -a
@itemx --debug-syms
@cindex debugging symbols
-Display debugger-only symbols; normally these are not listed.
+Display all symbols, even debugger-only symbols; normally these are not
+listed.
+
+@item -f @var{format}
+@itemx --format=@var{format}
+Use the output format @var{format}, which can be @code{bsd},
+@code{sysv}, or @code{posix}. The default is @code{bsd}.
+Only the first character of @var{format} is significant; it can be
+either upper or lower case.
@item -g
@itemx --extern-only
@cindex external symbols
Display only external symbols.
-@item -p
-@itemx --no-sort
-@cindex sorting symbols
-Don't bother to sort the symbols in any order; just print them in the
-order encountered.
-
@item -n
+@itemx -v
@itemx --numeric-sort
Sort symbols numerically by their addresses, rather than alphabetically
by their names.
+@item -p
+@itemx --no-sort
+@cindex sorting symbols
+Don't bother to sort the symbols in any order; print them in the order
+encountered.
+
+@item -P
+@itemx --portability
+Use the POSIX.2 standard output format instead of the default format.
+Equivalent to @samp{-f posix}.
+
@item -s
@itemx --print-armap
@cindex symbol index, listing
(stored in the archive by @code{ar} or @code{ranlib}) of which modules
contain definitions for which names.
-@item -o
-@itemx --print-file-name
-@cindex input file name
-@cindex file name
-@cindex source file name
-Precede each symbol by the name of the input file where it was found,
-rather than identifying the input file once only before all of its
-symbols.
-
@item -r
@itemx --reverse-sort
Reverse the order of the sort (whether numeric or alphabetic); let the
last come first.
+@item -t @var{radix}
+@itemx --radix=@var{radix}
+Use @var{radix} as the radix for printing the symbol values. It must be
+@samp{d} for decimal, @samp{o} for octal, or @samp{x} for hexadecimal.
+
@item --target=@var{bfdname}
-@c @item --target
@cindex object code format
Specify an object code format other than your system's default format.
@xref{objdump}, for information on listing available formats.
-@c FIXME what *does* --target/no arg do?
@item -u
@itemx --undefined-only
@cindex undefined symbols
Display only undefined symbols (those external to each object file).
+@item -V
+@itemx --version
+Show the version number of @code{nm} and exit.
+
+@item --help
+Show a summary of the options to @code{nm} and exit.
@end table
@node objdump, ranlib, nm, Top
@smallexample
objdump [ -a ] [ -b @var{bfdname} ] [ -d ] [ -f ]
[ -h | --header ] [ -i ] [ -j @var{section} ] [ -l ]
- [ -m @var{machine} ] [ -r | --reloc ] [ -s ]
- [ --stabs ] [ -t | --syms ] [ -x ]
+ [ -m @var{machine} ] [ -r | --reloc ] [ -s ] [ --stabs ]
+ [ -t | --syms ] [ -x ] [ --version ] [ --help ]
@var{objfile}@dots{}
@end smallexample
compilation tools, as opposed to programmers who just want their
program to compile and work.
+@var{objfile}@dots{} are the object files to be examined. When you
+specify archives, @code{objdump} shows information on each of the member
+object files.
+
The long and short forms of options, shown here as alternatives, are
equivalent.
@table @code
-@item @var{objfile}@dots{}
-The object files to be examined. When you specify archives,
-@code{objdump} shows information on each of the member object files.
-
@item -a
@c print_arelt_descr
@cindex archive headers
Header. Display summary information from the section headers of the
object file.
+@item --help
+Print a summary of the options to @code{objdump} and exit.
+
@item -i
@cindex architectures available
@cindex object formats available
Symbol Table. Print the symbol table entries of the file.
This is similar to the information provided by the @samp{nm} program.
+@item --version
+Print the version number of @code{objdump} and exit.
+
@item -x
@cindex all header information, object file
@cindex header information, all
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}.
-
@end table
@node ranlib, size, objdump, Top
Show the version number of @code{ranlib}.
@end table
-@node size, strip, ranlib, Top
+@node size, strings, ranlib, Top
@chapter size
@kindex size
argument list. By default, one line of output is generated for each
object file or each module in an archive.
+@var{objfile}@dots{} are the object files to be examined.
+
The command line options have the following meanings:
-@table @code
-@item @var{objfile}@dots{}
-The object files to be examined.
+@table @code
@item -A
@itemx -B
@itemx --format=@var{compatibility}
Display the version number of @code{size}.
@end table
-@node strip, Index, size, Top
+@node strings, strip, size, Top
+@chapter strings
+@kindex strings
+@cindex listings strings
+@cindex printing strings
+@cindex strings, printing
+
+@smallexample
+strings [-afov] [-@var{min-len}] [-n @var{min-len}] [-t @var{radix}] [-]
+ [--all] [--print-file-name] [--bytes=@var{min-len}] [--radix=@var{radix}]
+ [--help] [--version] @var{file}@dots{}
+@end smallexample
+
+For each @var{file} given, 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
+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.
+
+@code{strings} is mainly useful for determining the contents of non-text
+files.
+
+@table @code
+@item -a
+@itemx --all
+@itemx -
+Do not scan only the initialized data section of object files; scan
+the whole files.
+
+@item -f
+@itemx --print-file-name
+Print the name of the file before each string.
+
+@item --help
+Print a summary of the program usage on the standard output and exit.
+
+@itemx -@var{min-len}
+@item -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.
+
+@item -o
+Like @samp{-t o}. Some other versions of @code{strings} have @samp{-o}
+act like @samp{-t d} instead. Since we can not be compatible with both
+ways, we simply chose one.
+
+@item -t @var{radix}
+@itemx --radix=@var{radix}
+Print the offset within the file before each string. The single
+character argument specifies the radix of the offset---@samp{o} for
+octal, @samp{x} for hexadecimal, or @samp{d} for decimal.
+
+@item -v
+@itemx --version
+Print the program version number on the standard output and exit.
+@end table
+
+@node strip, c++filt, strings, Top
@chapter strip
@kindex strip
[ -O @var{format} | --output-format=@var{format} ]
[ -s | --strip-all ] [ -S | -g | --strip-debug ]
[ -x | --discard-all ] [ -X | --discard-locals ]
- [ -v | --verbose ] [ -V | --version ]
+ [ -v | --verbose ] [ -V | --version ] [ --help ]
@var{objfile}@dots{}
@end smallexample
GNU @code{strip} discards all symbols from object files
@var{objfile}. The list of object files may include archives.
-
-@code{strip} will not execute unless at least one object file is listed.
+At least one object file must be given.
@code{strip} modifies the files named in its argument,
rather than writing modified copies under different names.
@table @code
+@item -F @var{format}
+@itemx --format=@var{format}
+@itemx --target=@var{format}
+Treat the original @var{objfile} as a file with the object
+code format @var{format}, and rewrite it in the same format.
+
+@item --help
+Show a summary of the options to @code{strip} and exit.
+
@item -I @var{format}
@itemx --input-format=@var{format}
Treat the original @var{objfile} as a file with the object
@itemx --output-format=@var{format}
Replace @var{objfile} with a file in the output format @var{format}.
-@item -F @var{format}
-@itemx --format=@var{format}
-@itemx --target=@var{format}
-Treat the original @var{objfile} as a file with the object
-code format @var{format}, and rewrite it in the same format.
-
@item -s
@itemx --strip-all
Remove all symbols.
archives, @samp{strip -v} lists all members of the archive.
@end table
-@node Index, , strip, Top
+@node c++filt, Index, strip, Top
+@chapter c++filt
+
+@kindex c++filt
+@cindex demangling C++ symbols
+
+@smallexample
+c++filt [ -_ | --strip-underscores ]
+ [ -s @var{format} | --format=@var{format} ]
+ [ --help ] [ --version ] [ @var{arg}@dots{} ]
+@end smallexample
+
+The C++ language provides function overloading, which means that you can
+write many functions with the same name (providing each takes parameters
+of different types). All C++ function names are encoded into a
+low-level assembly label (this process is known as
+@dfn{mangling}). The @code{c++filt} 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.
+
+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.
+
+A typical use of @code{c++filt} is to pipe the output of @code{nm}
+though it, using @code{c++filt} as a filter:
+
+@example
+nm @var{objfile} | c++filt
+@end example
+
+You can also use @code{c++filt} to decipher individual symbols:
+
+@example
+c++filt @var{symbol}
+@end example
+
+All results are printed on the standard output.
+
+@table @code
+@item -_
+@item --strip-underscores
+On some systems, both the C and C++ compilers put an underscore in front
+of every name. For example, the C name @code{foo} gets the low-level
+name @code{_foo}. This option removes the initial underscore.
+
+@item -s @var{format}
+@itemx --format=@var{format}
+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)
+@item lucid
+the one used by the Lucid compiler
+@item arm
+the one specified by the C++ Annotated Reference Manual
+@end table
+
+@item --help
+Print a summary of the options to @code{c++filt} and exit.
+
+@item --version
+Print the version number of @code{c++filt} and exit.
+@end table
+
+@quotation
+@emph{Warning:} @code{c++filt} is a new utility, and the details of its
+user interface are subject to change in future releases. In particular,
+a command-line option may be required in the the future to decode a name
+passed as an argument on the command line; in other words,
+
+@example
+c++filt @var{symbol}
+@end example
+
+@noindent
+may in a future release become
+
+@example
+c++filt @var{option} @var{symbol}
+@end example
+@end quotation
+
+@node Index, , c++filt, Top
@unnumbered Index
@printindex cp
projects / deliverable / binutils-gdb.git / blobdiff