X-Git-Url: http://drtracing.org/?a=blobdiff_plain;f=binutils%2Fbinutils.texi;h=a20909ff7e491cadba628b78d91c2e64e12619d0;hb=3994e2c66d792e3ea0f48d1cf039a022a62960bb;hp=88d408ff18807b9a4d52973aea8ee1a87762b483;hpb=537b2e5e863af4192aa3e2350df5de67d92baf60;p=deliverable%2Fbinutils-gdb.git

diff --git a/binutils/binutils.texi b/binutils/binutils.texi
index 88d408ff18..a20909ff7e 100644
--- a/binutils/binutils.texi
+++ b/binutils/binutils.texi
@@ -5,15 +5,28 @@
 @ifinfo
 @format
 START-INFO-DIR-ENTRY
-* Binutils: (binutils).         The GNU binary utilities "ar", "objcopy",
-				"objdump", "nm", "nlmconv", "size", 
-                                "strings", "strip", "ranlib" and "dlltool".
+* Binutils: (binutils).         The GNU binary utilities.
+* ar: (binutils)ar.               Create, modify, and extract from archives
+* nm: (binutils)nm.               List symbols from object files
+* objcopy: (binutils)objcopy.	  Copy and translate object files
+* objdump: (binutils)objdump.     Display information from object files
+* ranlib: (binutils)ranlib.       Generate index to archive contents
+* readelf: (binutils)readelf.	  Display the contents of ELF format files.
+* size: (binutils)size.           List section sizes and total size
+* strings: (binutils)strings.     List printable strings from files
+* strip: (binutils)strip.         Discard symbols
+* c++filt: (binutils)c++filt.	  Filter to demangle encoded C++ symbols
+* cxxfilt: (binutils)c++filt.     MS-DOS name for c++filt
+* addr2line: (binutils)addr2line. Convert addresses to file and line
+* nlmconv: (binutils)nlmconv.     Converts object code into an NLM
+* windres: (binutils)windres.	  Manipulate Windows resources
+* dlltool: (binutils)dlltool.	  Create files needed to build and use DLLs
 END-INFO-DIR-ENTRY
 @end format
 @end ifinfo
 
 @ifinfo
-Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
+Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
 
 Permission is granted to make and distribute verbatim copies of
 this manual provided the copyright notice and this permission notice
@@ -39,9 +52,9 @@ into another language, under the above conditions for modified versions.
 @synindex ky cp
 @c
 @c This file documents the GNU binary utilities "ar", "ld", "objcopy",
-@c  "objdump", "nm", "size", "strings", "strip", and "ranlib".
+@c  "objdump", "nm", "size", "strings", "strip", "readelf" and "ranlib".
 @c
-@c Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 1998 Free Software Foundation, Inc.
+@c Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
 @c 
 @c This text may be freely distributed under the terms of the GNU
 @c General Public License.
@@ -105,6 +118,9 @@ Display information from object files
 @item ranlib
 Generate index to archive contents
 
+@item readelf
+Display the contents of ELF format files.
+
 @item size
 List file section sizes and total size
 
@@ -115,7 +131,8 @@ List printable strings from files
 Discard symbols
 
 @item c++filt
-Demangle encoded C++ symbols
+Demangle encoded C++ symbols (on MS-DOS, this program is named
+@code{cxxfilt})
 
 @item addr2line
 Convert addresses into file names and line numbers
@@ -137,10 +154,12 @@ Create the files needed to build and use Dynamic Link Libraries
 * objcopy::			Copy and translate object files
 * objdump::                     Display information from object files
 * ranlib::                      Generate index to archive contents
+* readelf::			Display the contents of ELF format files.
 * size::                        List section sizes and total size
 * strings::                     List printable strings from files
 * strip::                       Discard symbols
 * c++filt::			Filter to demangle encoded C++ symbols
+* cxxfilt: c++filt.             MS-DOS name for c++filt
 * addr2line::			Convert addresses to file and line
 * nlmconv::                     Converts object code into an NLM
 * windres::			Manipulate Windows resources
@@ -157,7 +176,7 @@ Create the files needed to build and use Dynamic Link Libraries
 @cindex archives
 @cindex collections of files
 @smallexample
-ar [-]@var{p}[@var{mod} [@var{relpos}]] @var{archive} [@var{member}@dots{}]
+ar [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
 ar -M [ <mri-script ]
 @end smallexample
 
@@ -215,7 +234,7 @@ program.
 @section Controlling @code{ar} on the command line
 
 @smallexample
-ar [-]@var{p}[@var{mod} [@var{relpos}]] @var{archive} [@var{member}@dots{}]
+ar [-]@var{p}[@var{mod} [@var{relpos}] [@var{count}]] @var{archive} [@var{member}@dots{}]
 @end smallexample
 
 @cindex Unix compatibility, @code{ar}
@@ -379,12 +398,25 @@ This modifier is accepted but not used.
 @c whaffor ar l modifier??? presumably compat; with
 @c what???---doc@@cygnus.com, 25jan91 
 
+@item N
+Uses the @var{count} parameter.  This is used if there are multiple
+entries in the archive with the same name.  Extract or delete instance
+@var{count} of the given name from the archive.
+
 @item o
 @cindex dates in archive
 Preserve the @emph{original} dates of members when extracting them.  If
 you do not specify this modifier, files extracted from the archive
 are stamped with the time of extraction.
 
+@item P
+Use the full path name when matching names in the archive.  @sc{gnu}
+@code{ar} can not create an archive with a full path name (such archives
+are not POSIX complaint), but other archive creators can.  This option
+will cause @sc{gnu} @code{ar} to match file names using a complete path
+name, which can be convenient when extracting a single file from an
+archive created by another tool.
+
 @item s
 @cindex writing archive index
 Write an object-file index into the archive, or update an existing one,
@@ -550,7 +582,7 @@ Requires prior use of @code{OPEN} or @code{CREATE}.
 @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 @sc{gnu} @code{ld}
+tv @var{archive}}.  (This single command is a @sc{gnu} @code{ar}
 enhancement, rather than present for MRI compatibility.)
 
 Requires prior use of @code{OPEN} or @code{CREATE}.
@@ -833,6 +865,7 @@ objcopy [ -F @var{bfdname} | --target=@var{bfdname} ]
         [ -x | --discard-all ]  [ -X | --discard-locals ]
         [ -b @var{byte} | --byte=@var{byte} ]
         [ -i @var{interleave} | --interleave=@var{interleave} ]
+        [ -j @var{sectionname} | --only-section=@var{sectionname} ]
         [ -R @var{sectionname} | --remove-section=@var{sectionname} ]
         [ -p | --preserve-dates ] [ --debugging ]
         [ --gap-fill=@var{val} ] [ --pad-to=@var{address} ]
@@ -901,6 +934,12 @@ Use @var{bfdname} as the object format for both the input and the output
 file; i.e., simply transfer data from source to destination with no
 translation.  @xref{Target Selection}, for more information.
 
+@item -j @var{sectionname}
+@itemx --only-section=@var{sectionname}
+Copy only the named section from the input file to the output file.
+This option may be given more than once.  Note that using this option
+inappropriately may make the output file unusable.
+
 @item -R @var{sectionname}
 @itemx --remove-section=@var{sectionname}
 Remove any section named @var{sectionname} from the output file.  This
@@ -1056,12 +1095,13 @@ 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{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.
+@samp{alloc}, @samp{contents}, @samp{load}, @samp{noload},
+@samp{readonly}, @samp{code}, @samp{data}, @samp{rom}, @samp{share}, and
+@samp{debug}.  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
@@ -1126,6 +1166,8 @@ objdump [ -a | --archive-headers ]
         [ -j @var{section} | --section=@var{section} ]
         [ -l | --line-numbers ] [ -S | --source ]
         [ -m @var{machine} | --architecture=@var{machine} ]
+        [ -M @var{options} | --disassembler-options=@var{options}]
+        [ -p | --private-headers ]
         [ -r | --reloc ] [ -R | --dynamic-reloc ]
         [ -s | --full-contents ]  [ --stabs ]
         [ -t | --syms ] [ -T | --dynamic-syms ] [ -x | --all-headers ]
@@ -1283,6 +1325,27 @@ can be useful when disassembling object files which do not describe
 architecture information, such as S-records.  You can list the available
 architectures with the @samp{-i} option.
 
+@item -M @var{options}
+@itemx --disassembler-options=@var{options}
+Pass target specific information to the disassembler.  Only supported on
+some targets.
+
+If the target is an ARM architecture then this switch can be used to
+select which register name set is used during disassembler.  Specifying
+@samp{--disassembler-options=reg-name-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 @samp{--disassembler-options=reg-names-apcs} will
+select the name set used by the ARM Procedure Call Standard, whilst
+specifying @samp{--disassembler-options=reg-names-raw} will just use
+@samp{r} followed by the register number.
+
+@item -p
+@itemx --private-headers
+Print information that is specific to the object file format.  The exact
+information printed depends upon the object file format.  For some
+object file formats, no additional information is printed.
+
 @item -r
 @itemx --reloc
 @cindex relocation entries, in object file
@@ -1673,7 +1736,7 @@ Verbose output: list all object files modified.  In the case of
 archives, @samp{strip -v} lists all members of the archive.
 @end table
 
-@node c++filt
+@node c++filt, addr2line, strip, Top
 @chapter c++filt
 
 @kindex c++filt
@@ -1681,18 +1744,23 @@ archives, @samp{strip -v} lists all members of the archive.
 
 @smallexample
 c++filt [ -_ | --strip-underscores ]
+        [ -j | --java ]
 	[ -n | --no-strip-underscores ]
         [ -s @var{format} | --format=@var{format} ]
         [ --help ]  [ --version ]  [ @var{symbol}@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.
+@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 @code{c++filt}
+@footnote{MS-DOS does not allow @kbd{+} characters in file names, so on
+MS-DOS this program is named @code{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.
 
 Every alphanumeric word (consisting of letters, digits, underscores,
 dollars, or periods) seen in the input is a potential label.  If the
@@ -1717,6 +1785,11 @@ of every name.  For example, the C name @code{foo} gets the low-level
 name @code{_foo}.  This option removes the initial underscore.  Whether
 @code{c++filt} removes the underscore by default is target dependent.
 
+@item -j
+@itemx --java
+Prints demangled names using Java syntax.  The default is to use C++
+syntax.
+
 @item -n
 @itemx --no-strip-underscores
 Do not remove the initial underscore.
@@ -1734,6 +1807,10 @@ the one used by the @sc{gnu} compiler (the default method)
 the one used by the Lucid compiler
 @item arm
 the one specified by the C++ Annotated Reference Manual
+@item hp
+the one used by the HP compiler
+@item edg
+the one used by the EDG compiler
 @end table
 
 @item --help
@@ -2027,10 +2104,15 @@ Specify an include directory to use when reading an @code{rc} file.
 option.  @code{windres} will also search this directory when looking for
 files named in the @code{rc} file.
 
-@item --define @var{sym[=val]}
+@item -D @var{target}
+@itemx --define @var{sym}[=@var{val}]
 Specify a @code{-D} option to pass to the preprocessor when reading an
 @code{rc} file.
 
+@item -v
+Enable verbose mode.  This tells you what the preprocessor is if you
+didn't specify one.
+
 @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
@@ -2062,14 +2144,18 @@ utilities, since it is only useful for those targets which support DLLs.
 @end quotation
 
 @smallexample
-dlltool [-d|--input-def <def-file-name>]
-        [-b|--base-file <base-file-name>]
-        [-e|--output-exp <exports-file-name>]
-        [-z|--output-def <def-file-name>]
-        [-l|--output-lib <library-file-name>]        
-        [-S|--as <path-to-assembler>] [-f|--as-flags <options>]
-        [-D|--dllname <name>] [-m|--machine <machine>]
+dlltool [-d|--input-def @var{def-file-name}]
+        [-b|--base-file @var{base-file-name}]
+        [-e|--output-exp @var{exports-file-name}]
+        [-z|--output-def @var{def-file-name}]
+        [-l|--output-lib @var{library-file-name}]        
+        [--export-all-symbols] [--no-export-all-symbols]
+        [--exclude-symbols @var{list}]
+        [--no-default-excludes]
+        [-S|--as @var{path-to-assembler}] [-f|--as-flags @var{options}]
+        [-D|--dllname @var{name}] [-m|--machine @var{machine}]
         [-a|--add-indirect] [-U|--add-underscore] [-k|--kill-at]
+        [-A|--add-stdcall-alias]
         [-x|--no-idata4] [-c|--no-idata5] [-i|--interwork]
         [-n|--nodelete] [-v|--verbose] [-h|--help] [-V|--version]
         [object-file @dots{}]
@@ -2096,12 +2182,12 @@ those functions which have been specially marked as being exported and
 put entries for them in the .def file it creates.
 
 In order to mark a function as being exported from a DLL, it needs to
-have an @samp{-export:<name_of_function>} entry in the @samp{.drective}
+have an @samp{-export:<name_of_function>} entry in the @samp{.drectve}
 section of the object file.  This can be done in C by using the
 asm() operator:
 
 @smallexample
-  asm (".section .drective");  
+  asm (".section .drectve");  
   asm (".ascii \"-export:my_func\"");
 
   int my_func (void) @{ @dots{} @}
@@ -2143,37 +2229,64 @@ The command line options have the following meanings:
 
 @table @code
 
-@item -d FILENAME
-@itemx --input-def FILENAME
+@item -d @var{filename}
+@itemx --input-def @var{filename}
 @cindex input .def file
 Specifies the name of a .def file to be read in and processed.
 
-@item -b FILENAME
-@itemx --base-file FILENAME
+@item -b @var{filename}
+@itemx --base-file @var{filename}
 @cindex base files
 Specifies the name of a base file to be read in and processed.  The
 contents of this file will be added to the relocation section in the
 exports file generated by dlltool.
 
-@item -e FILENAME
-@itemx --output-exp FILENAME
+@item -e @var{filename}
+@itemx --output-exp @var{filename}
 Specifies the name of the export file to be created by dlltool.
 
-@item -z FILENAME
-@itemx --output-def FILENAME
+@item -z @var{filename}
+@itemx --output-def @var{filename}
 Specifies the name of the .def file to be created by dlltool.
 
-@item -l FILENAME
-@itemx --output-lib FILENAME
+@item -l @var{filename}
+@itemx --output-lib @var{filename}
 Specifies the name of the library file to be created by dlltool.
 
-@item -S PATH
-@itemx --as PATH
+@item --export-all-symbols
+Treat all global and weak defined symbols found in the input object
+files as symbols to be exported.  There is a small list of symbols which
+are not exported by default; see the @code{--no-default-excludes}
+option.  You may add to the list of symbols to not export by using the
+@code{--exclude-symbols} option.
+
+@item --no-export-all-symbols
+Only export symbols explicitly listed in an input .def file or in
+@samp{.drectve} sections in the input object files.  This is the default
+behaviour.  The @samp{.drectve} sections are created by @samp{dllexport}
+attributes in the source code.
+
+@item --exclude-symbols @var{list}
+Do not export the symbols in @var{list}.  This is a list of symbol names
+separated by comma or colon characters.  The symbol names should not
+contain a leading underscore.  This is only meaningful when
+@code{--export-all-symbols} is used.
+
+@item --no-default-excludes
+When @code{--export-all-symbols} is used, it will by default avoid
+exporting certain special symbols.  The current list of symbols to avoid
+exporting is @samp{DllMain@@12}, @samp{DllEntryPoint@@0},
+@samp{impure_ptr}.  You may use the @code{--no-default-excludes} option
+to go ahead and export these special symbols.  This is only meaningful
+when @code{--export-all-symbols} is used.
+
+@item -S @var{path}
+@itemx --as @var{path}
 Specifies the path, including the filename, of the assembler to be used
 to create the exports file.
 
-@item -f SWITCHES
-@itemx --as-flags SWITCHES
+@item -f @var{switches}
+@itemx --as-flags @var{switches}
 Specifies any specific command line switches to be passed to the
 assembler when building the exports file.  This option will work even if
 the @samp{-S} option is not used.  This option only takes one argument,
@@ -2182,15 +2295,15 @@ occurrences will override earlier occurrences.  So if it is necessary to
 pass multiple switches to the assembler they should be enclosed in
 double quotes.
 
-@item -D NAME
-@itemx --dll-name NAME
+@item -D @var{name}
+@itemx --dll-name @var{name}
 Specifies the name to be stored in the .def file as the name of the DLL
 when the @samp{-e} option is used.  If this option is not present, then
 the filename given to the @samp{-e} option will be used as the name of
 the DLL.
 
-@item -m MACHINE
-@itemx -machine MACHINE
+@item -m @var{machine}
+@itemx -machine @var{machine}
 Specifies the type of machine for which the library file should be
 built.  @code{dlltool} has a built in default type, depending upon how
 it was created, but this option can be used to override that.  This is
@@ -2216,6 +2329,12 @@ should not append the string @samp{@@ <number>}.  These numbers are
 called ordinal numbers and they represent another way of accessing the
 function in a DLL, other than by name.
 
+@item -A
+@itemx --add-stdcall-alias
+Specifies that when @code{dlltool} is creating the exports file it
+should add aliases for stdcall symbols without @samp{@@ <number>}
+in addition to the symbols with @samp{@@ <number>}.
+
 @item -x
 @itemx --no-idata4
 Specifies that when @code{dlltool} is creating the exports and library
@@ -2255,6 +2374,132 @@ Displays dlltool's version number and then exits.
 
 @end table
 
+@node readelf
+@chapter readelf
+
+@cindex ELF file information
+@kindex readelf
+
+@smallexample
+readelf [ -a | --all ] 
+        [ -h | --file-header]
+        [ -l | --program-headers | --segments]
+        [ -S | --section-headers | --sections]
+        [ -e | --headers]
+        [ -s | --syms | --symbols]
+        [ -n | --notes]
+        [ -r | --relocs]
+        [ -d | --dynamic]
+        [ -V | --version-info]
+        [ -D | --use-dynamic]
+        [ -x <number> | --hex-dump=<number>]
+        [ -w[liapr] | --debug-dump[=info,=line,=abbrev,=pubnames,=ranges]]
+        [      --histogram]
+        [ -v | --version]
+        [ -H | --help]
+        @var{elffile}@dots{}
+@end smallexample
+
+@code{readelf} displays information about one or more ELF format object
+files.  The options control what particular information to display.
+
+@var{elffile}@dots{} are the object files to be examined.  At the
+moment, @code{readelf} does not support examining archives, nor does it
+support examing 64 bit ELF files.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.  At least one option besides @samp{-v} or @samp{-H} must be
+given. 
+
+@table @code
+@item -a
+@itemx --all
+Equivalent to specifiying @samp{--file-header},
+@samp{--program-headers}, @samp{--sections}, @samp{--symbols},
+@samp{--relocs}, @samp{--dynamic}, @samp{--notes} and
+@samp{--version-info}. 
+
+@item -h
+@itemx --file-header
+@cindex ELF file header information
+Displays the information contained in the ELF header at the start of the
+file.
+
+@item -l
+@itemx --program-headers
+@itemx --segments
+@cindex ELF program header information
+@cindex ELF segment information
+Displays the information contained in the file's segment headers, if it
+has any.
+
+@item -S
+@itemx --sections
+@itemx --section-headers
+@cindex ELF section information
+Displays the information contained in the file's section headers, if it
+has any.
+
+@item -s
+@itemx --symbols
+@itemx --syms
+@cindex ELF symbol table information
+Displays the entries in symbol table section of the file, if it has one.
+
+@item -e
+@itemx --headers
+Display all the headers in the file.  Equivalent to @samp{-h -l -S}.
+
+@item -n
+@itemx --notes
+@cindex ELF core notes
+Displays the contents of the NOTE segment, if it exists.
+
+@item -r
+@itemx --relocs
+@cindex ELF reloc information
+Displays the contents of the file's relocation section, if it ha one.
+
+@item -d
+@itemx --dynamic
+@cindex ELF dynamic section information
+Displays the contents of the file's dynamic section, if it has one.
+
+@item -V
+@itemx --version-info
+@cindex ELF version sections informations
+Displays the contents of the version sections in the file, it they
+exist.
+
+@item -D
+@itemx --use-dynamic
+When displaying symbols, this option makes @code{readelf} use the
+symblol table in the file's dynamic section, rather than the one in the
+symbols section.
+
+@item -x <number>
+@itemx --hex-dump=<number>
+Displays the contents of the indicated section as a hexadecimal dump.
+
+@item -w[liapr]
+@itemx --debug-dump[=line,=info,=abbrev,=pubnames,=ranges]
+Displays the contents of the debug sections in the file, if any are
+present.  If one of the optional letters or words follows the switch
+then only data found in those specific sections will be dumped.
+
+@item --histogram
+Display a histogram of bucket list lengths when displaying the contents
+of the symbol tables.
+
+@item -v
+@itemx --version
+Display the version number of readelf.
+
+@item -H
+@itemx --help
+Display the command line options understood by @code{readelf}.
+
+@end table
 
 
 @node Selecting The Target System
@@ -2630,9 +2875,10 @@ and then we might not encounter the bug.
 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.
+necessary to get them through the mail system.  Note that
+@samp{bug-gnu-utils@@gnu.org} is a mailing list, so you should avoid
+sending very large files to it.  Making the files available for
+anonymous FTP is OK.
 
 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