--- /dev/null
+\input texinfo
+@setfilename binutils.info
+@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$
+@tex
+@finalout
+@c @smallbook
+@end tex
+@c @cropmarks
+@setchapternewpage odd
+@settitle GNU Binary Utilities
+@titlepage
+@title{The GNU Binary Utilities}
+@sp 1
+@subtitle January 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
+
+@ifinfo
+@node Top, ar, (dir), (dir)
+This file documents the GNU binary utilities @samp{ar}, @samp{ld},
+@samp{objdump}, @samp{nm}, @samp{size}, @samp{strip}, and
+@samp{ranlib}.@refill
+
+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:: ar
+* ld:: ld
+* nm:: nm
+* objdump:: objdump
+* ranlib:: ranlib
+* size:: size
+* strip:: strip
+
+@end menu
+
+@node ar, ld, Top, Top
+@chapter ar
+
+@smallexample
+ ar [-]@var{Op}@var{Mod} [ @var{membername} ] @var{archive} @var{files}@dots{}
+@end smallexample
+
+The GNU @code{ar} program creates, modifies, and extracts
+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.
+
+Only the first fifteen characters of a file name are kept in archives.
+@c Note: with next (BFD) version, this will depend on obj format.
+
+@code{ar} is considered a binary utility because archives of this sort
+are most often used as @dfn{libraries} holding commonly needed
+subroutines.
+
+@code{ar} will create an index to the symbols defined in relocatable
+object modules in the archive when you specify the option @samp{s}.
+Once created, this index is updated in the archive whenever @code{ar}
+makes a change to its contents. 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.
+@c This auto-update may happen-always only for WRS version; Gumby says, for
+@c instance, that it doesn't happen with 'q' updates elsewhere.
+
+You may use @samp{nm -s} or @samp{nm +print-symdefs} 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 and modifier flags in
+any order, within the first command-line argument.
+
+If you wish, you may precede the first command-line argument with a
+dash.
+
+The @var{Op} 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
+@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 wish to delete an archive's index, you can use this option to do
+it; the internal name of the index (which you will need to specify in
+@var{files} to delete it) is @samp{__.SYMDEF}.
+
+If you specify the @samp{v} option flag, @code{ar} will list each module
+as it is deleted.
+
+@item m
+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 option flags 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} options to move them to a
+specified place instead.
+
+@item p
+@emph{Print} the specified members of the archive, to the standard
+output file. If the @samp{v} option flag 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,
+save for the index (if any), which is listed only if you ask for it by
+name: @samp{__.SYMDEF}.
+
+@item q
+@emph{Quick append}; add @var{files} to the end of @var{archive},
+without checking for replacement.
+
+The options @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 option @samp{v} makes @code{ar} list each file as it is appended.
+
+@c per Gumby, versions other than WRS of this will *not* auto-update
+@c SYMDEF index on 'q' updates.
+
+@item r
+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 options @samp{a}, @samp{b}, or @samp{i} to request
+placement relative to some existing member.
+
+The option flag @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
+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} option flag.
+
+If you do not specify any @var{files}, all files in the archive
+are listed; but the index to symbols from relocatable modules, called
+@samp{__.SYMDEF}, is not listed unless you explicitly request it by
+name.
+
+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
+@emph{Extract} a member from the archive. The @samp{v} option flag
+requests 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; but the index to symbols from relocatable modules, called
+@samp{__.SYMDEF}, is not extracted unless you explicitly request it by
+name.
+
+@end table
+
+A number of modifiers may immediately follow the @var{Op} keyletter, to
+specify variations on an operation's behavior:
+
+@table @code
+@item a
+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
+@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 option flag.
+
+@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 option flag is recognized but not used; it is permitted for
+compatibility with other forms of @code{ar}.
+@c ???---pesch@@cygnus.com, 25jan91
+
+@item o
+Preserve the @emph{original} dates of members when extracting them. If
+you do not specify this option flag, files extracted from the archive
+will be stamped with the time of extraction.
+
+@item s
+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 option
+flag either with any operation, or alone. Running @samp{ar s} on an
+archive is equivalent to running @samp{ranlib} on it.
+
+@item u
+Normally, @code{ar r}@dots{} or @code{ar q}@dots{} insert 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 option. The option-flag combination @samp{qu} is
+equivalent to @samp{ru}; checking the timestamps loses any speed
+advantage, so @code{ar} treats both commands as replace operations with
+the @samp{u} option appended.
+
+@c u actually turns *anything* into a replace. I claim this is a bug;
+@c 'du' and 'tu' for example should either be rejected or equivalent to
+@c plain 'd' and 't'. ---pesch@@cygnus.com, 25jan91
+
+@item v
+This option requests the @emph{verbose} version of an operations. Many
+operations display additional information, such as filenames processed,
+when the option @samp{v} is appended.
+
+@end table
+
+@node ld, nm, ar, Top
+@chapter 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
+
+@smallexample
+ nm [ -a | +debug-syms ] [ -g | +extern-only ]
+ [ -n | +numeric-sort ] [ -o | +print-file-name ]
+ [ -p | +no-sort ] [ -r | +reverse-sort ]
+ [ -s | +print-symdefs ] [ -u | +undefined-only ]
+ [ @var{objfiles}@dots{} ]
+@end smallexample
+
+GNU @code{nm} will list the symbols from object files @var{objfiles}.
+Any command-line options must precede all object files; no option takes
+an argument.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+
+@table @code
+@item @var{objfiles}@dots{}
+Object files whose symbols are to be listed. If no object files are
+listed as arguments, @code{nm} assumes @samp{a.out}.
+
+@item -a | +debug-syms
+Display debugger-only symbols; normally these are not listed.
+
+@item -g | +extern-only
+Display only external symbols.
+
+@item -n | +numeric-sort
+Sort symbols numerically by their addresses, not alphabetically by their
+names.
+
+@item -o | +print-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 -p | +no-sort
+Don't bother to sort the symbols in any order; just print them in the
+order encountered.
+
+@item -r | +reverse-sort
+Reverse the sense of the sort (whether numeric or alphabetic); let the
+last come first.
+
+@item -s | +print-symdefs
+When listing symbols from archives, list the index: a mapping (stored in
+the archive by @code{ar} or @code{ranlib} of what modules contain
+definitions for what names.
+
+@item -u | +undefined-only
+Display only undefined symbols (those external to each object file).
+
+@end table
+
+@node objdump, ranlib, nm, Top
+@chapter objdump
+
+@smallexample
+ objdump [ -h | +header ] [ -n | +nstuff ] [ -r | +reloc ]
+ [ -t | +syms ] @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.
+
+@item -h | +header
+Header. Print summary information from the header of the object file.
+
+@item -n | +nstuff
+@samp{N_} symbols. Print the values of various macros from @file{a.out.h}
+as applied to the object file; e.g. @code{N_TXTOFF}.
+
+@item -r | +reloc
+Relocation. Print the relocation entries of the file.
+
+@item -t | +syms
+Symbol Table. Print the symbol table entries of the file.
+This is similar to the information provided by the @samp{nm} program.
+
+@end table
+
+@node ranlib, size, objdump, Top
+@chapter ranlib
+
+@smallexample
+ ranlib [ -t | +touch ] [ -v | +verbose ] @var{archive}
+@end smallexample
+
+@code{ranlib} generates the 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 @code{nm -s} or @code{nm +print-symdefs} to list this table.
+The index is internally stored in the archive under the name
+@samp{__.SYMDEF}.
+
+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}.
+
+@code{ranlib}'s options make it report on what it's doing and fake an
+update of a particular archive's index.
+
+Any command-line options must precede the archive name.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+
+@table @code
+
+@item -t | +touch
+You can use the ``touch'' option to fake an update of the index
+table in archives; @code{ranlib} will first set the current date for the
+index object module in the archive (to make it appear to have changed).
+
+@item -v | +verbose
+Use this option if you'd like informational messages about what
+@code{ranlib} is up to, while it loops through the specified archives.
+
+@end table
+
+@node size, strip, ranlib, Top
+@chapter size
+
+@smallexample
+ size @var{objfiles}@dots{}
+@end smallexample
+
+The GNU @code{size} utility lists the segment (@code{text}, @code{data},
+@code{bss} sizes ---and the total size--- for the object files
+@var{objfiles} in its argument list. For archives, one line of output
+is generated for each module.
+
+@code{size} has no command-line options.
+
+If more than one object module is listed, @code{size} labels each line
+of output with the module's name:
+@smallexample
+% size a.out libX11.a
+text data bss dec hex
+49152 49152 0 98304 18000 a.out
+1256 16 0 1272 4f8 libX11.a(Context.o)
+176 0 0 176 b0 libX11.a(Depths.o)
+1360 56 0 1416 588 libX11.a(ParseCmd.o)
+904 24 4096 5024 13a0 libX11.a(Quarks.o)
+216 0 0 216 d8 libX11.a(XAllCells.o)
+ .
+ .
+ .
+
+@end smallexample
+[sample output truncated]
+
+@node strip, , size, Top
+@chapter strip
+
+@smallexample
+ strip [ -s | +strip-all ] [ -S | +strip-debug ]
+ [ -x | +discard-all ] [ -X | +discard-locals ]
+ @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.
+
+@emph{WARNING:} @code{strip} modifies the files named in its argument,
+rather than writing modified copies under different names.
+
+The long and short forms of options, shown here as alternatives, are
+equivalent.
+
+@table @code
+@item -s | +strip-all
+This is the default case: strip all symbol entries from @var{objfiles}.
+
+@item -S | +strip-debug
+Discard only debugging symbol information from @var{objfiles}.
+
+@item -x | +discard-all
+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 | +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}.)
+@end table
+
+
+@contents
+@bye
+
+
projects / binutils-gdb.git / commitdiff