From: K. Richard Pixley <rich@cygnus>
Date: Wed, 13 Nov 1991 19:01:53 +0000 (+0000)
Subject: Initial revision
X-Git-Url: https://git.libre-soc.org/?a=commitdiff_plain;h=c72af7354314de12c2b6e324ee1a3b297685574e;p=binutils-gdb.git

Initial revision
---

diff --git a/binutils/binutils.texi b/binutils/binutils.texi
new file mode 100644
index 00000000000..d10dd62d1a5
--- /dev/null
+++ b/binutils/binutils.texi
@@ -0,0 +1,737 @@
+\input texinfo
+@setfilename binutils.info
+
+@c start-menu
+* Binutils: (binutils).	
+		The GNU binary utilities "ar", "ld", "objdump", "nm",
+		"size", "strip", and "ranlib".
+@c end-menu
+
+@synindex ky cp
+@c
+@c This file documents the GNU binary utilities "ar", "ld", "objdump", "nm", 
+@c "size", "strip", and "ranlib".
+@c
+@c Copyright (C) 1991 Free Software Foundation, Inc.
+@c 
+@c This text may be freely distributed under the terms of the GNU
+@c General Public License.
+@c
+@c $Id$
+@iftex
+@finalout
+@c @smallbook
+@end iftex
+@c @cropmarks
+@setchapternewpage odd
+@settitle GNU Binary Utilities
+@titlepage
+@title The GNU Binary Utilities
+@subtitle Version 1.90
+@sp 1
+@subtitle October 1991
+@author Roland H. Pesch
+@author Cygnus Support
+@page
+
+@tex
+\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$
+\xdef\manvers{\$Revision$} % For use in headers, footers too
+{\parskip=0pt \hfill Cygnus Support\par \hfill \manvers\par \hfill
+\TeX{}info \texinfoversion\par }
+@end tex
+
+@vskip 0pt plus 1filll
+Copyright @copyright{} 1991 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end titlepage
+
+@node Top, ar, (dir), (dir)
+@chapter Introduction
+
+@cindex version
+This brief manual contains preliminary documentation for the GNU binary
+utilities (collectively version 1.90): 
+@table @code
+@item ar
+Create, modify, and extract from archives
+
+@item nm
+List symbols from object files
+
+@item objdump
+Display information from object files
+
+@item ranlib
+Generate index to archive contents
+
+@item size
+List section sizes and total size
+
+@item strip
+Discard symbols
+@end table
+
+@ifinfo
+Copyright @copyright{} 1991 Free Software Foundation, Inc.
+
+Permission is granted to make and distribute verbatim copies of
+this manual provided the copyright notice and this permission notice
+are preserved on all copies.
+
+@ignore
+Permission is granted to process this file through TeX and print the
+results, provided the printed document carries a copying permission
+notice identical to this one except for the removal of this paragraph
+(this paragraph not being relevant to the printed manual).
+
+@end ignore
+
+Permission is granted to copy and distribute modified versions of this
+manual under the conditions for verbatim copying, provided also that
+the entire resulting derived work is distributed under the terms of a
+permission notice identical to this one.
+
+Permission is granted to copy and distribute translations of this manual
+into another language, under the above conditions for modified versions.
+@end ifinfo
+
+@menu
+* ar::                          Create, modify, and extract from archives
+* ld::                          See ld.info
+* 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
+* strip::                       Discard symbols
+* Index::
+@end menu
+
+@node ar, ld, Top, Top
+@chapter ar
+
+@kindex ar
+@cindex archives
+@cindex collections of files
+@smallexample
+  ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{files}@dots{}
+@end smallexample
+
+The GNU @code{ar} program creates, modifies, and extracts from
+archives.  An @dfn{archive} is a single file holding a collection of
+other files in a structure that makes it possible to retrieve
+the original individual files (called @dfn{members} of the archive).
+
+The original files' contents, mode (permissions), timestamp, owner, and
+group are preserved in the archive, and may be reconstituted on
+extraction.  
+
+@cindex name length
+GNU @code{ar} can maintain archives whose members have names of any
+length; however, depending on how @code{ar} is configured on your
+system, a limit on member-name length may be imposed (for compatibility
+with archive formats maintained with other tools).  If it exists, the
+limit is often 15 characters (typical of formats related to a.out) or 16
+characters (typical of formats related to coff).
+
+@cindex libraries
+@code{ar} is considered a binary utility because archives of this sort
+are most often used as @dfn{libraries} holding commonly needed
+subroutines.
+
+@cindex symbol index
+@code{ar} will create an index to the symbols defined in relocatable
+object modules in the archive when you specify the modifier @samp{s}.
+Once created, this index is updated in the archive whenever @code{ar}
+makes a change to its contents (save for the @samp{q} update operation).
+An archive with such an index speeds up linking to the library, and
+allows routines in the library to call each other without regard to
+their placement in the archive.
+
+You may use @samp{nm -s} or @samp{nm +print-armap} to list this index
+table.  If an archive lacks the table, another form of @code{ar} called
+@code{ranlib} can be used to add just the table.
+
+@code{ar} insists on at least two arguments to execute: one
+keyletter specifying the @emph{operation} (optionally accompanied by other
+keyletters specifying @emph{modifiers}), and the archive name to act on.
+
+Most operations can also accept further @var{files} arguments,
+specifying particular files to operate on.
+
+GNU @code{ar} allows you to mix the operation code @var{p} and modifier
+flags @var{mod} in any order, within the first command-line argument.
+
+If you wish, you may begin the first command-line argument with a
+dash.
+
+@cindex operations on archive
+The @var{p} keyletter specifies what operation to execute; it may be
+any of the following, but you must specify only one of them:
+
+@table @code
+@item d
+@cindex deleting from archive
+@emph{Delete} modules from the archive.  Specify the names of modules to
+be deleted as @var{files}; the archive is untouched if you
+specify no files to delete.
+
+If you specify the @samp{v} modifier, @code{ar} will list each module
+as it is deleted.
+
+@item m
+@cindex moving in archive
+Use this operation to @emph{move} members in an archive.
+
+The ordering of members in an archive can make a difference in how
+programs are linked using the library, if a symbol is defined in more
+than one member.  
+
+If no modifiers are used with @code{m}, any members you name in the
+@var{files} arguments are moved to the @emph{end} of the archive;
+you can use the @samp{a}, @samp{b}, or @samp{i} modifiers to move them to a
+specified place instead.
+
+@item p
+@cindex printing from archive
+@emph{Print} the specified members of the archive, to the standard
+output file.  If the @samp{v} modifier is specified, show the member
+name before copying its contents to standard output.
+
+If you specify no @var{files}, all the files in the archive are printed.
+
+@item q
+@cindex quick append to archive
+@emph{Quick append}; add @var{files} to the end of @var{archive},
+without checking for replacement.  
+
+The modifiers @samp{a}, @samp{b}, and @samp{i} do @emph{not} affect this
+operation; new members are always placed at the end of the archive.
+
+The modifier @samp{v} makes @code{ar} list each file as it is appended.
+
+Since the point of this operation is speed, the archive's symbol table
+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.
+
+@item r
+@cindex replacement in archive
+Insert @var{files} into @var{archive} (with @emph{replacement}). This
+operation differs from @samp{q} in that any previously existing members
+are deleted if their names match those being added.
+
+If one of the files named in @var{files} doesn't exist, @code{ar}
+displays an error message, and leaves undisturbed any existing members
+of the archive matching that name.
+
+By default, new members are added at the end of the file; but you may
+use one of the modifiers @samp{a}, @samp{b}, or @samp{i} to request
+placement relative to some existing member.
+
+The modifier @samp{v} used with this operation elicits a line of
+output for each file inserted, along with one of the letters @samp{a} or
+@samp{r} to indicate whether the file was appended (no old member
+deleted) or replaced.
+
+@item t
+@cindex contents of archive
+Display a @emph{table} listing the contents of @var{archive}, or those
+of the files listed in @var{files} that are present in the
+archive.  Normally only the member name is shown; if you also want to
+see the modes (permissions), timestamp, owner, group, and size, you can
+request that by also specifying the @samp{v} modifier.
+
+If you do not specify any @var{files}, all files in the archive
+are listed.
+
+@cindex repeated names in archive
+@cindex name duplication in archive
+If there is more than one file with the same name (say, @samp{fie}) in
+an archive (say @samp{b.a}), @samp{ar t b.a fie} will list only the
+first instance; to see them all, you must ask for a complete
+listing---in our example, @samp{ar t b.a}.
+@c WRS only; per Gumby, this is implementation-dependent, and in a more
+@c recent case in fact works the other way.
+
+@item x
+@cindex extract from archive
+@emph{Extract} members (named @var{files}) from the archive.  You can
+use the @samp{v} modifier with this operation, to request that
+@code{ar} list each name as it extracts it.
+
+If you do not specify any @var{files}, all files in the archive
+are extracted.
+
+@end table
+
+A number of modifiers (@var{mod}) may immediately follow the @var{p}
+keyletter, to specify variations on an operation's behavior:
+
+@table @code
+@item a
+@cindex relative placement in archive
+Add new files @emph{after} an existing member of the
+archive.  If you use the modifier @code{a}, the name of an existing archive
+member must be present as the @var{membername} argument, before the
+@var{archive} specification.
+
+@item b
+Add new files @emph{before} an existing member of the
+archive.  If you use the modifier @code{b}, the name of an existing archive
+member must be present as the @var{membername} argument, before the
+@var{archive} specification.  (same as @samp{i}).
+
+@item c
+@cindex creating archives
+@emph{Create} the archive.  The specified @var{archive} is always
+created if it didn't exist, when you request an update.  But a warning is
+issued unless you specify in advance that you expect to create it, by
+using this modifier.
+
+@item i
+Insert new files @emph{before} an existing member of the
+archive.  If you use the modifier @code{i}, the name of an existing archive
+member must be present as the @var{membername} argument, before the
+@var{archive} specification.  (same as @samp{b}).
+
+@item l
+This modifier is accepted but not used.
+@c whaffor ar l modifier??? presumably compat; with
+@c what???---pesch@@cygnus.com, 25jan91 
+
+@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
+will be stamped with the time of extraction.
+
+@item s
+@cindex writing archive index
+Write an object-file index into the archive, or update an existing one,
+even if no other change is made to the archive.  You may use this modifier
+flag either with any operation, or alone.  Running @samp{ar s} on an
+archive is equivalent to running @samp{ranlib} on it.
+
+@item u
+@cindex updating an archive
+Normally, @code{ar r}@dots{} inserts all files
+listed into the archive.  If you would like to insert @emph{only} those
+of the files you list that are newer than existing members of the same
+names, use this modifier.  The @samp{u} modifier is allowed only for the
+operation @samp{r} (replace).  In particular, the combination @samp{qu} is
+not allowed, since checking the timestamps would lose any speed
+advantage from the operation @samp{q}.
+
+@item v
+This modifier requests the @emph{verbose} version of an operation.  Many
+operations display additional information, such as filenames processed,
+when the modifier @samp{v} is appended.
+
+@end table
+
+@node ld, nm, ar, Top
+@chapter ld
+@cindex linker
+@kindex ld
+The GNU linker @code{ld} is now described in a separate manual.
+@xref{Top,, Overview,, GLD: the GNU linker}.
+
+@node nm, objdump, ld, 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 ]
+      [ -r | +reverse-sort ]  [ -u | +undefined-only ]  
+      [ +target @var{bfdname} ]
+      [ @var{objfiles}@dots{} ]
+@end smallexample
+
+GNU @code{nm} will list the symbols from object files @var{objfiles}.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+
+@table @code
+@item @var{objfiles}@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 +debug-syms 
+@cindex debugging symbols
+Display debugger-only symbols; normally these are not listed.
+
+@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 +numeric-sort 
+Sort symbols numerically by their addresses, not alphabetically by their
+names. 
+
+@item -s
+@itemx +print-armap
+@cindex symbol index, listing
+When listing symbols from archive members, include the index: a mapping
+(stored in the archive by @code{ar} or @code{ranlib}) of what modules
+contain definitions for what 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 sense of the sort (whether numeric or alphabetic); let the
+last come first.
+
+@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 external symbols
+@cindex undefined symbols
+Display only undefined symbols (those external to each object file).
+
+@end table
+
+@node objdump, ranlib, nm, Top
+@chapter objdump
+
+@cindex object file information
+@kindex objdump
+
+@smallexample
+  objdump [ -a ]  [ -b @var{bfdname} ]  [ -d ]  [ -f ]
+          [ -h | +header ]  [ -i ]  [ -j @var{section} ]  [ -l ]
+          [ -m @var{machine} ]  [ -r | +reloc ]  [ -s ]
+          [ -t | +syms ]  [ -x ]
+          @var{objfiles}@dots{}
+@end smallexample
+
+@code{objdump} displays information about one or more object files.
+The options control what particular information to display.  This
+information is mostly useful to programmers who are working on the
+compilation tools, as opposed to programmers who just want their
+program to compile and work.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+
+@table @code
+@item @var{objfiles}@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
+If any files from @var{objfiles} are archives, display the archive
+header information (in a format similar to @samp{ls -l}).  Besides the
+information you could list with @samp{ar tv}, @samp{objdump -a} shows
+the object file format of each archive member.
+
+@c suggest longname +target or +format or +bfd
+@item -b @var{bfdname}
+@cindex object code format
+You can specify a particular object-code format for your object files as
+@var{bfdname}.  This may not be necessary; @var{objdump} can
+automatically recognize many formats.  For example,
+@example
+objdump -b oasys -m vax -h fu.o
+@end example
+@noindent
+Displays summary information from the section headers (@samp{-h}) of
+@file{fu.o}, which is explicitly identified (@samp{-m}) as a Vax object
+file in the format produced by Oasys compilers.  You can list the
+formats available with the @samp{-i} option.
+
+@item -d
+@cindex disassembling object code
+@cindex machine instructions
+Disassemble.  Display the assembler mnemonics for the machine
+instructions from @var{objfiles}.
+
+@item -f
+@cindex object file header
+File header.  Display summary information from the overall header of
+each file in @var{objfiles}.
+
+@item -h
+@itemx +header
+@cindex section headers
+Header.  Display summary information from the section headers of the
+object file.
+
+@item -i
+@cindex architectures available
+@cindex object formats available
+Display a list showing all architectures and object formats available
+for specification with @code{-b} or @code{-m}.
+
+@c suggest longname +section
+@item -j @var{name}
+@cindex section information
+Display information only for section @var{name}
+
+@c suggest longname +label or +linespec
+@item -l
+@cindex source filenames for object files
+Label the display (using debugging information) with the source filename
+and line numbers corresponding to the object code shown.
+
+@c suggest longname +architecture
+@item -m @var{machine}
+@cindex architecture
+Specify the object files @var{objfiles} are for architecture
+@var{machine}.  You can list available architectures using the @samp{-i}
+option. 
+
+@item -r
+@itemx +reloc
+@cindex relocation entries, in object file
+Relocation.  Print the relocation entries of the file.
+
+@item -s
+@cindex sections, full contents
+@cindex object file sections
+Display the full contents of any sections requested.
+
+@item -t
+@itemx +syms
+@cindex symbol table entries, printing
+Symbol Table.  Print the symbol table entries of the file.
+This is similar to the information provided by the @samp{nm} program.
+
+@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
+@chapter ranlib
+
+@kindex ranlib
+@cindex archive contents
+@cindex symbol index
+
+@smallexample
+  ranlib @var{archive}
+@end smallexample
+
+@code{ranlib} generates an index to the contents of an archive, and
+stores it in the archive.  The index lists each symbol defined by a
+member of an archive that is a relocatable object file.  
+
+You may use @samp{nm -s} or @samp{nm +print-armap} to list this index.
+
+An archive with such an index speeds up linking to the library, and
+allows routines in the library to call each other without regard to
+their placement in the archive.
+
+The GNU @code{ranlib} program is another form of GNU @code{ar}; running
+@code{ranlib} is completely equivalent to executing @samp{ar -s}.
+@xref{ar}.
+
+@node size, strip, ranlib, Top
+@chapter size
+
+@kindex size
+@cindex section sizes
+
+@smallexample
+  size [ -A | -B | +format @var{compatibility} ]
+       [ +help ]  [ -d | -o | -x | +radix @var{number} ]
+       [ +target @var{bfdname} ]  [ -V | +version ]  
+       @var{objfiles}@dots{}
+@end smallexample
+
+The GNU @code{size} utility lists the section sizes---and the total
+size---for each of the object files @var{objfiles} in its argument list.
+By default, one line of output is generated for each object file or each
+module in an archive.
+
+The command line options have the following meanings:
+@table @code
+@item @var{objfiles}@dots{}
+The object files to be examined.
+
+@item -A
+@itemx -B
+@itemx +format @var{compatibility}
+@cindex size display format
+Using one of these options, you can choose whether the output from GNU
+@code{size} resembles output from System V @code{size} (using @samp{-A},
+or @samp{+format sysv}), or Berkeley @code{size} (using @samp{-B}, or
+@samp{+format berkeley}).  The default is the one-line format similar to
+Berkeley's.  
+@c Bonus for doc-source readers: you can also say +format=strange (or
+@c anything else that starts with 's') for sysv, and +format=boring (or
+@c anything else that starts with 'b') for Berkeley.
+
+Here is an example of the Berkeley (default) format of output from
+@code{size}: 
+@smallexample
+ eg$  size +format Berkeley ranlib size
+text    data    bss     dec     hex     filename
+294880  81920   11592   388392  5ed28   ranlib
+294880  81920   11888   388688  5ee50   size
+@end smallexample
+
+@noindent
+This is the same data, but displayed closer to System V conventions:
+
+@smallexample
+ eg$  size +format SysV ranlib size
+ranlib  :
+section         size         addr
+.text         294880         8192       
+.data          81920       303104       
+.bss           11592       385024       
+Total         388392    
+
+
+size  :
+section         size         addr
+.text         294880         8192       
+.data          81920       303104       
+.bss           11888       385024       
+Total         388688    
+@end smallexample
+
+@item +help
+Show a summary of acceptable arguments and options.
+
+@item -d
+@itemx -o
+@itemx -x
+@itemx +radix @var{number}
+@cindex size number format
+@cindex radix for section sizes
+Using one of these options, you can control whether the size of each
+section is given in decimal (@samp{-d}, or @samp{+radix 10}); octal
+(@samp{-o}, or @samp{+radix 8}); or hexadecimal (@samp{-x}, or
+@samp{+radix 16}).  In @samp{+radix @var{number}}, only the three
+values (8, 10, 16) are supported.  The total size is always given in two
+radices; decimal and hexadecimal for @samp{-d} or @samp{-x} output, or
+octal and hexadecimal if you're using @samp{-o}.
+
+@item +target @var{bfdname}
+@cindex object code format
+You can specify a particular object-code format for @var{objfiles} as
+@var{bfdname}.  This may not be necessary; @var{size} can
+automatically recognize many formats.  @xref{objdump}, for information
+on listing available formats.
+
+@item -V
+@itemx +version
+Display version number information on @code{size} itself.
+
+@end table
+
+@node strip, Index, size, Top
+@chapter strip
+
+@kindex strip
+@cindex removing symbols
+@cindex discarding symbols
+
+@smallexample
+  strip [ -s | +strip-all ]  [ -g | -S | +strip-debug ]
+         [ -x | +discard-all ]  [ -X | +discard-locals ]
+         [ -T @var{bfdname} ]
+         @var{objfiles}@dots{}
+@end smallexample
+
+GNU @code{strip} will discard all symbols from object files
+@var{objfiles}, if no options are specified; or only certain symbols,
+depending on its command-line options.
+
+@code{strip} will not execute unless at least one object file is listed.
+
+@quotation
+@emph{WARNING:} @code{strip} modifies the files named in its argument,
+rather than writing modified copies under different names.
+@end quotation
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+
+@table @code
+@item -s
+@itemx +strip-all 
+@cindex all symbols, discarding
+This is the default case: strip all symbol entries from @var{objfiles}.
+
+@item -g
+@itemx -S
+@itemx +strip-debug 
+@cindex debugging symbols, discarding
+Discard only debugging symbol information from @var{objfiles}.
+
+@item -x
+@itemx +discard-all 
+@cindex local symbols, discarding
+Discard all symbols local to each file in @var{objfiles}.
+@emph{WARNING:} Note that @code{+discard-all} discards only @emph{local}
+symbols, in spite of its name.
+
+@item -X
+@itemx +discard-locals 
+Discard local symbols starting with @samp{L} from each file in
+@var{objfiles}.  (Some compilers produce internally-used symbols that
+begin with @samp{L}.)
+
+@item -T @var{bfdname}
+@cindex object code format
+You can specify a particular object-code format @var{bfdname} for
+@var{objfiles}.  This may not be necessary; @var{strip} can automatically
+recognize many formats.  @xref{objdump}, for information on listing
+available formats.
+@end table
+
+@node Index, , strip, Top
+@unnumbered Index
+
+@printindex cp
+
+@contents
+@bye