1163 lines
37 KiB
Plaintext
1163 lines
37 KiB
Plaintext
\input texinfo @c -*- Texinfo -*-
|
|
@setfilename binutils.info
|
|
|
|
@ifinfo
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* Binutils: (binutils). The GNU binary utilities "ar", "ld", "objcopy",
|
|
"objdump", "nm", "size", "strip", and "ranlib".
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
@end ifinfo
|
|
|
|
@ifinfo
|
|
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
|
|
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
|
|
|
|
@synindex ky cp
|
|
@c
|
|
@c This file documents the GNU binary utilities "ar", "ld", "objcopy",
|
|
@c "objdump", "nm", "size", "strip", and "ranlib".
|
|
@c
|
|
@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.
|
|
@c
|
|
|
|
@setchapternewpage odd
|
|
@settitle GNU Binary Utilities
|
|
@c @smallbook
|
|
@c @cropmarks
|
|
@titlepage
|
|
@finalout
|
|
@title The GNU Binary Utilities
|
|
@subtitle Version 2.2
|
|
@sp 1
|
|
@subtitle May 1993
|
|
@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, 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
|
|
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 2.2):
|
|
|
|
@iftex
|
|
@table @code
|
|
@item ar
|
|
Create, modify, and extract from archives
|
|
|
|
@item objcopy
|
|
Copy and translate object files
|
|
|
|
@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
|
|
@end iftex
|
|
|
|
@menu
|
|
* ar:: Create, modify, and extract from archives
|
|
* 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
|
|
* strip:: Discard symbols
|
|
* c++filt:: Filter to demangle encoded C++ symbols
|
|
* Index::
|
|
@end menu
|
|
|
|
@node ar, objcopy, Top, Top
|
|
@chapter ar
|
|
|
|
@kindex ar
|
|
@cindex archives
|
|
@cindex collections of files
|
|
@smallexample
|
|
ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{file}@dots{}
|
|
ar -M [ <mri-script ]
|
|
@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 can be restored 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} creates 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.
|
|
|
|
@cindex compatibility, @code{ar}
|
|
@cindex @code{ar} compatibility
|
|
GNU @code{ar} is designed to be compatible with two different
|
|
facilities. You can control its activity using command-line options,
|
|
like the different varieties of @code{ar} on Unix systems; or, if you
|
|
specify the single command-line option @samp{-M}, you can control it
|
|
with a script supplied via standard input, like the MRI ``librarian''
|
|
program.
|
|
|
|
@menu
|
|
* ar-cmdline:: Controlling @code{ar} on the command line
|
|
* ar-scripts:: Controlling @code{ar} with a script
|
|
@end menu
|
|
|
|
@page
|
|
@node ar-cmdline, ar-scripts, ar, ar
|
|
@section Controlling @code{ar} on the command line
|
|
|
|
@smallexample
|
|
ar [-]@var{p}@var{mod} [ @var{membername} ] @var{archive} @var{file}@dots{}
|
|
@end smallexample
|
|
|
|
@cindex Unix compatibility, @code{ar}
|
|
When you use @code{ar} in the Unix style, @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{file} 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{file}@dots{}; the archive is untouched if you
|
|
specify no files to delete.
|
|
|
|
If you specify the @samp{v} modifier, @code{ar} lists 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{file} 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{file} arguments, all the files in the archive are
|
|
printed.
|
|
|
|
@item q
|
|
@cindex quick append to archive
|
|
@emph{Quick append}; add the files @var{file}@dots{} 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 the files @var{file}@dots{} 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{file}@dots{} 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{file}@dots{} 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 a @var{file}, 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} lists 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{file}) 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 a @var{file}, 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 @samp{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 @samp{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 @samp{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
|
|
are 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, @samp{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.
|
|
|
|
@item V
|
|
This modifier shows the version number of @code{ar}.
|
|
@end table
|
|
|
|
@node ar-scripts, , ar-cmdline, ar
|
|
@section Controlling @code{ar} with a script
|
|
|
|
@smallexample
|
|
ar -M [ <@var{script} ]
|
|
@end smallexample
|
|
|
|
@cindex MRI compatibility, @code{ar}
|
|
@cindex scripts, @code{ar}
|
|
If you use the single command-line option @samp{-M} with @code{ar}, you
|
|
can control its operation with a rudimentary command language. This
|
|
form of @code{ar} operates interactively if standard input is coming
|
|
directly from a terminal. During interactive use, @code{ar} prompts for
|
|
input (the prompt is @samp{AR >}), and continues executing even after
|
|
errors. If you redirect standard input to a script file, no prompts are
|
|
issued, and @code{ar} abandons execution (with a nonzero exit code)
|
|
on any error.
|
|
|
|
The @code{ar} command language is @emph{not} designed to be equivalent
|
|
to the command-line options; in fact, it provides somewhat less control
|
|
over archives. The only purpose of the command language is to ease the
|
|
transition to GNU @code{ar} for developers who already have scripts
|
|
written for the MRI ``librarian'' program.
|
|
|
|
The syntax for the @code{ar} command language is straightforward:
|
|
@itemize @bullet
|
|
@item
|
|
commands are recognized in upper or lower case; for example, @code{LIST}
|
|
is the same as @code{list}. In the following descriptions, commands are
|
|
shown in upper case for clarity.
|
|
|
|
@item
|
|
a single command may appear on each line; it is the first word on the
|
|
line.
|
|
|
|
@item
|
|
empty lines are allowed, and have no effect.
|
|
|
|
@item
|
|
comments are allowed; text after either of the characters @samp{*}
|
|
or @samp{;} is ignored.
|
|
|
|
@item
|
|
Whenever you use a list of names as part of the argument to an @code{ar}
|
|
command, you can separate the individual names with either commas or
|
|
blanks. Commas are shown in the explanations below, for clarity.
|
|
|
|
@item
|
|
@samp{+} is used as a line continuation character; if @samp{+} appears
|
|
at the end of a line, the text on the following line is considered part
|
|
of the current command.
|
|
@end itemize
|
|
|
|
Here are the commands you can use in @code{ar} scripts, or when using
|
|
@code{ar} interactively. Three of them have special significance:
|
|
|
|
@code{OPEN} or @code{CREATE} specify a @dfn{current archive}, which is
|
|
a temporary file required for most of the other commands.
|
|
|
|
@code{SAVE} commits the changes so far specified by the script. Prior
|
|
to @code{SAVE}, commands affect only the temporary copy of the current
|
|
archive.
|
|
|
|
@table @code
|
|
@item ADDLIB @var{archive}
|
|
@itemx ADDLIB @var{archive} (@var{module}, @var{module}, @dots{} @var{module})
|
|
Add all the contents of @var{archive} (or, if specified, each named
|
|
@var{module} from @var{archive}) to the current archive.
|
|
|
|
Requires prior use of @code{OPEN} or @code{CREATE}.
|
|
|
|
@item ADDMOD @var{file}, @var{file}, @dots{} @var{file}
|
|
@c FIXME! w/Replacement?? If so, like "ar r @var{archive} @var{names}"
|
|
@c else like "ar q..."
|
|
Add each named @var{file} as a module in the current archive.
|
|
|
|
Requires prior use of @code{OPEN} or @code{CREATE}.
|
|
|
|
@item CLEAR
|
|
Discard the contents of the current archive, cancelling the effect of
|
|
any operations since the last @code{SAVE}. May be executed (with no
|
|
effect) even if no current archive is specified.
|
|
|
|
@item CREATE @var{archive}
|
|
Creates an archive, and makes it the current archive (required for many
|
|
other commands). The new archive is created with a temporary name; it
|
|
is not actually saved as @var{archive} until you use @code{SAVE}.
|
|
You can overwrite existing archives; similarly, the contents of any
|
|
existing file named @var{archive} will not be destroyed until @code{SAVE}.
|
|
|
|
@item DELETE @var{module}, @var{module}, @dots{} @var{module}
|
|
Delete each listed @var{module} from the current archive; equivalent to
|
|
@samp{ar -d @var{archive} @var{module} @dots{} @var{module}}.
|
|
|
|
Requires prior use of @code{OPEN} or @code{CREATE}.
|
|
|
|
@item DIRECTORY @var{archive} (@var{module}, @dots{} @var{module})
|
|
@itemx DIRECTORY @var{archive} (@var{module}, @dots{} @var{module}) @var{outputfile}
|
|
List each named @var{module} present in @var{archive}. The separate
|
|
command @code{VERBOSE} specifies the form of the output: when verbose
|
|
output is off, output is like that of @samp{ar -t @var{archive}
|
|
@var{module}@dots{}}. When verbose output is on, the listing is like
|
|
@samp{ar -tv @var{archive} @var{module}@dots{}}.
|
|
|
|
Output normally goes to the standard output stream; however, if you
|
|
specify @var{outputfile} as a final argument, @code{ar} directs the
|
|
output to that file.
|
|
|
|
@item END
|
|
Exit from @code{ar}, with a @code{0} exit code to indicate successful
|
|
completion. This command does not save the output file; if you have
|
|
changed the current archive since the last @code{SAVE} command, those
|
|
changes are lost.
|
|
|
|
@item EXTRACT @var{module}, @var{module}, @dots{} @var{module}
|
|
Extract each named @var{module} from the current archive, writing them
|
|
into the current directory as separate files. Equivalent to @samp{ar -x
|
|
@var{archive} @var{module}@dots{}}.
|
|
|
|
Requires prior use of @code{OPEN} or @code{CREATE}.
|
|
|
|
@ignore
|
|
@c FIXME Tokens but no commands???
|
|
@item FULLDIR
|
|
|
|
@item HELP
|
|
@end ignore
|
|
|
|
@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 GNU @code{ld}
|
|
enhancement, rather than present for MRI compatibility.)
|
|
|
|
Requires prior use of @code{OPEN} or @code{CREATE}.
|
|
|
|
@item OPEN @var{archive}
|
|
Opens an existing archive for use as the current archive (required for
|
|
many other commands). Any changes as the result of subsequent commands
|
|
will not actually affect @var{archive} until you next use @code{SAVE}.
|
|
|
|
@item REPLACE @var{module}, @var{module}, @dots{} @var{module}
|
|
In the current archive, replace each existing @var{module} (named in
|
|
the @code{REPLACE} arguments) from files in the current working directory.
|
|
To execute this command without errors, both the file, and the module in
|
|
the current archive, must exist.
|
|
|
|
Requires prior use of @code{OPEN} or @code{CREATE}.
|
|
|
|
@item VERBOSE
|
|
Toggle an internal flag governing the output from @code{DIRECTORY}.
|
|
When the flag is on, @code{DIRECTORY} output matches output from
|
|
@samp{ar -tv }@dots{}.
|
|
|
|
@item SAVE
|
|
Commit your changes to the current archive, and actually save it as a
|
|
file with the name specified in the last @code{CREATE} or @code{OPEN}
|
|
command.
|
|
|
|
Requires prior use of @code{OPEN} or @code{CREATE}.
|
|
|
|
@end table
|
|
|
|
@node objcopy, nm, ar, Top
|
|
@chapter objcopy
|
|
|
|
@smallexample
|
|
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 ]
|
|
@var{infile} [@var{outfile}]
|
|
@end smallexample
|
|
|
|
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{objcopy} is controlled by command-line options.
|
|
|
|
@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}.
|
|
|
|
@table @code
|
|
@item @var{infile}
|
|
@itemx @var{outfile}
|
|
The source and output files respectively.
|
|
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 -I @var{format}
|
|
@itemx --input-format=@var{format}
|
|
Consider the source file's object format to be @var{format}, rather than
|
|
attempting to deduce it.
|
|
|
|
@item -O @var{format}
|
|
@itemx --output-format=@var{format}
|
|
Write the output file using the object format @var{format}.
|
|
|
|
@item -F @var{format}
|
|
@itemx --format=@var{format}
|
|
Use @var{format} as the object format for both the input and the output
|
|
file; i.e. simply transfer data from source to destination with no
|
|
translation.
|
|
|
|
@item -S
|
|
@itemx --strip-all
|
|
Do not copy relocation and symbol information from the source file.
|
|
|
|
@item -g
|
|
@itemx --strip-debug
|
|
Do not copy debugging symbols from the source file.
|
|
|
|
@item -x
|
|
@itemx --discard-all
|
|
Do not copy non-global symbols from the source file.
|
|
@c FIXME any reason to prefer "non-global" to "local" here?
|
|
|
|
@item -X
|
|
@itemx --discard-locals
|
|
Do not copy compiler-generated local symbols.
|
|
(These usually start with @samp{L} or @samp{.}.)
|
|
|
|
@item -V
|
|
@itemx --version
|
|
Show the version number of @code{objcopy}.
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
Verbose output: list all object files modified. In the case of
|
|
archives, @samp{objcopy -V} lists all members of the archive.
|
|
@end table
|
|
|
|
@iftex
|
|
@node ld
|
|
@chapter ld
|
|
@cindex linker
|
|
@kindex ld
|
|
The GNU linker @code{ld} is now described in a separate manual.
|
|
@xref{Top,, Overview,, Using LD: the GNU linker}.
|
|
@end iftex
|
|
|
|
@node nm, objdump, objcopy, Top
|
|
@chapter nm
|
|
@cindex symbols
|
|
@kindex nm
|
|
|
|
@smallexample
|
|
nm [ -a | --debug-syms ] [ -g | --extern-only ]
|
|
[ -s | --print-armap ] [ -A | -o | --print-file-name ]
|
|
[ -n | -v | --numeric-sort ] [ -p | --no-sort ]
|
|
[ -r | --reverse-sort ] [ -u | --undefined-only ]
|
|
[ -t @var{radix} | --radix=@var{radix} ] [ -P | --portability ]
|
|
[ --target=@var{bfdname} ] [ -f @var{format} | --format=@var{format} ]
|
|
[ -V | --version ] [ @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 -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 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; 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 -n
|
|
@itemx -v
|
|
@itemx --numeric-sort
|
|
Sort symbols numerically by their addresses, rather than 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 which modules
|
|
contain definitions for which names.
|
|
|
|
@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}
|
|
@cindex object code format
|
|
Specify an object code format other than your system's default format.
|
|
@xref{objdump}, for information on listing available formats.
|
|
|
|
@item -u
|
|
@itemx --undefined-only
|
|
@cindex external symbols
|
|
@cindex undefined symbols
|
|
Display only undefined symbols (those external to each object file).
|
|
|
|
@item -V
|
|
@itemx --version
|
|
Show the version number of @code{nm}.
|
|
@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 ]
|
|
[ --stabs ] [ -t | --syms ] [ -x ]
|
|
@var{objfile}@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{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
|
|
If any of the @var{objfile} files 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
|
|
Specify that the object-code format for the object files is
|
|
@var{bfdname}. This option 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{objfile}.
|
|
|
|
@item -f
|
|
@cindex object file header
|
|
File header. Display summary information from the overall header of
|
|
each of the @var{objfile} files.
|
|
|
|
@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 @samp{-b} or @samp{-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 that the object files @var{objfile} 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 --stabs
|
|
@cindex stab
|
|
@cindex .stab
|
|
@cindex debug symbols
|
|
@cindex ELF object file format
|
|
Display the full contents of any sections requested. Display the
|
|
contents of the .stab and .stab.index and .stab.excl sections from an
|
|
ELF file. This is only useful on systems (such as Solaris 2.0) in which
|
|
@code{.stab} debugging symbol-table entries are carried in an ELF
|
|
section. In most other file formats, debugging symbol-table entries are
|
|
interleaved with linkage symbols, and are visible in the @samp{--syms}
|
|
output.
|
|
|
|
@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 [-vV] @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}.
|
|
|
|
@table @code
|
|
@item -v
|
|
@itemx -V
|
|
Show the version number of @code{ranlib}.
|
|
@end table
|
|
|
|
@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{objfile}@dots{}
|
|
@end smallexample
|
|
|
|
The GNU @code{size} utility lists the section sizes---and the total
|
|
size---for each of the object or archive files @var{objfile} 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{objfile}@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
|
|
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
|
|
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
|
|
Specify that the object-code format for @var{objfile} is
|
|
@var{bfdname}. This option may not be necessary; @code{size} can
|
|
automatically recognize many formats. @xref{objdump}, for information
|
|
on listing available formats.
|
|
|
|
@item -V
|
|
@itemx --version
|
|
Display the version number of @code{size}.
|
|
@end table
|
|
|
|
@node strip, c++filt, size, Top
|
|
@chapter strip
|
|
|
|
@kindex strip
|
|
@cindex removing symbols
|
|
@cindex discarding symbols
|
|
@cindex symbols, discarding
|
|
|
|
@smallexample
|
|
strip [ -F @var{format} | --format=@var{format} | --target=@var{format} ]
|
|
[ -I @var{format} | --input-format=@var{format} ]
|
|
[ -O @var{format} | --output-format=@var{format} ]
|
|
[ -s | --strip-all ] [ -S | -g | --strip-debug ]
|
|
[ -x | --discard-all ] [ -X | --discard-locals ]
|
|
[ -v | --verbose ] [ -V | --version ]
|
|
@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.
|
|
|
|
@code{strip} modifies the files named in its argument,
|
|
rather than writing modified copies under different names.
|
|
|
|
@table @code
|
|
@item -I @var{format}
|
|
@itemx --input-format=@var{format}
|
|
Treat the original @var{objfile} as a file with the object
|
|
code format @var{format}.
|
|
|
|
@item -O @var{format}
|
|
@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.
|
|
|
|
@item -g
|
|
@itemx -S
|
|
@itemx --strip-debug
|
|
Remove debugging symbols only.
|
|
|
|
@item -x
|
|
@itemx --discard-all
|
|
Remove non-global symbols.
|
|
|
|
@item -X
|
|
@itemx --discard-locals
|
|
Remove compiler-generated local symbols.
|
|
(These usually start with @samp{L} or @samp{.}.)
|
|
|
|
@item -V
|
|
@itemx --version
|
|
Show the version number for @code{strip}.
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
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, Index, strip, Top
|
|
@chapter c++filt
|
|
|
|
@kindex c++filt
|
|
@cindex demangling C++ symbols
|
|
|
|
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 (in some circles this is described 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.
|
|
|
|
Note that on some systems, both the C and C++ compilers put an
|
|
underscore in front of every name. (I.e. the C name @code{foo} gets the
|
|
low-level name @code{_foo}.) On such systems, @code{c++filt} removes
|
|
any initial underscore of a potential label.
|
|
|
|
@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{flag} @var{SYMBOL}
|
|
@end example
|
|
@end quotation
|
|
|
|
@node Index, , c++filt, Top
|
|
@unnumbered Index
|
|
|
|
@printindex cp
|
|
|
|
@contents
|
|
@bye
|