This brief manual contains preliminary documentation for the GNU binary utilities (collectively version 2.10.1):
ar [-]p[mod [relpos] [count]] archive [member...] ar -M [ <mri-script ]
The GNU ar program creates, modifies, and extracts from
archives. An 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 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.
GNU ar can maintain archives whose members have names of any
length; however, depending on how 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).
ar is considered a binary utility because archives of this sort
are most often used as libraries holding commonly needed
subroutines.
ar creates an index to the symbols defined in relocatable
object modules in the archive when you specify the modifier s.
Once created, this index is updated in the archive whenever ar
makes a change to its contents (save for the 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 nm -s or nm --print-armap to list this index
table. If an archive lacks the table, another form of ar called
ranlib can be used to add just the table.
GNU ar is designed to be compatible with two different
facilities. You can control its activity using command-line options,
like the different varieties of ar on Unix systems; or, if you
specify the single command-line option -M, you can control it
with a script supplied via standard input, like the MRI "librarian"
program.
ar on the command line
ar with a script
ar on the command linear [-]p[mod [relpos] [count]] archive [member...]
When you use ar in the Unix style, ar insists on at least two
arguments to execute: one keyletter specifying the operation
(optionally accompanied by other keyletters specifying
modifiers), and the archive name to act on.
Most operations can also accept further member arguments, specifying particular files to operate on.
GNU ar allows you to mix the operation code p and modifier
flags mod in any order, within the first command-line argument.
If you wish, you may begin the first command-line argument with a dash.
The p keyletter specifies what operation to execute; it may be any of the following, but you must specify only one of them:
d
If you specify the v modifier, ar lists each module
as it is deleted.
m
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 m, any members you name in the
member arguments are moved to the end of the archive;
you can use the a, b, or i modifiers to move them to a
specified place instead.
p
v modifier is specified, show the member
name before copying its contents to standard output.
If you specify no member arguments, all the files in the archive are
printed.
q
The modifiers a, b, and i do not affect this
operation; new members are always placed at the end of the archive.
The modifier v makes 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 ar s or
ranlib explicitly to update the symbol table index.
However, too many different systems assume quick append rebuilds the
index, so GNU ar implements q as a synonym for r.
r
q in that any
previously existing members are deleted if their names match those being
added.
If one of the files named in member... does not exist, 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 a, b, or i to request
placement relative to some existing member.
The modifier v used with this operation elicits a line of
output for each file inserted, along with one of the letters a or
r to indicate whether the file was appended (no old member
deleted) or replaced.
t
v modifier.
If you do not specify a member, all files in the archive are listed.
If there is more than one file with the same name (say, fie) in
an archive (say b.a), ar t b.a fie lists only the
first instance; to see them all, you must ask for a complete
listing--in our example, ar t b.a.
x
v modifier with this operation, to request that
ar list each name as it extracts it.
If you do not specify a member, all files in the archive are extracted.
A number of modifiers (mod) may immediately follow the p keyletter, to specify variations on an operation's behavior:
a
a, the name of an existing archive
member must be present as the relpos argument, before the
archive specification.
b
b, the name of an existing archive
member must be present as the relpos argument, before the
archive specification. (same as i).
c
f
ar will normally permit file
names of any length. This will cause it to create archives which are
not compatible with the native ar program on some systems. If
this is a concern, the f modifier may be used to truncate file
names when putting them in the archive.
i
i, the name of an existing archive
member must be present as the relpos argument, before the
archive specification. (same as b).
l
N
o
P
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 GNU 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.
s
ar s on an
archive is equivalent to running ranlib on it.
S
S modifier on the last execution of ar, or you must run
ranlib on the archive.
u
ar r... inserts all files
listed into the archive. If you would like to insert only those
of the files you list that are newer than existing members of the same
names, use this modifier. The u modifier is allowed only for the
operation r (replace). In particular, the combination qu is
not allowed, since checking the timestamps would lose any speed
advantage from the operation q.
v
v is appended.
V
ar.
ar with a scriptar -M [ <script ]
If you use the single command-line option -M with ar, you
can control its operation with a rudimentary command language. This
form of ar operates interactively if standard input is coming
directly from a terminal. During interactive use, ar prompts for
input (the prompt is AR >), and continues executing even after
errors. If you redirect standard input to a script file, no prompts are
issued, and ar abandons execution (with a nonzero exit code)
on any error.
The ar command language is 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 ar for developers who already have scripts
written for the MRI "librarian" program.
The syntax for the ar command language is straightforward:
LIST
is the same as list. In the following descriptions, commands are
shown in upper case for clarity.
*
or ; is ignored.
ar
command, you can separate the individual names with either commas or
blanks. Commas are shown in the explanations below, for clarity.
+ is used as a line continuation character; if + appears
at the end of a line, the text on the following line is considered part
of the current command.
Here are the commands you can use in ar scripts, or when using
ar interactively. Three of them have special significance:
OPEN or CREATE specify a current archive, which is
a temporary file required for most of the other commands.
SAVE commits the changes so far specified by the script. Prior
to SAVE, commands affect only the temporary copy of the current
archive.
ADDLIB archive
ADDLIB archive (module, module, ... module)
Requires prior use of OPEN or CREATE.
ADDMOD member, member, ... member
Requires prior use of OPEN or CREATE.
CLEAR
SAVE. May be executed (with no
effect) even if no current archive is specified.
CREATE archive
SAVE.
You can overwrite existing archives; similarly, the contents of any
existing file named archive will not be destroyed until SAVE.
DELETE module, module, ... module
ar -d archive module ... module.
Requires prior use of OPEN or CREATE.
DIRECTORY archive (module, ... module)
DIRECTORY archive (module, ... module) outputfile
VERBOSE specifies the form of the output: when verbose
output is off, output is like that of ar -t archive
module.... When verbose output is on, the listing is like
ar -tv archive module....
Output normally goes to the standard output stream; however, if you
specify outputfile as a final argument, ar directs the
output to that file.
END
ar, with a 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 SAVE command, those
changes are lost.
EXTRACT module, module, ... module
ar -x
archive module....
Requires prior use of OPEN or CREATE.
LIST
VERBOSE. The effect is like ar
tv archive. (This single command is a GNU ar
enhancement, rather than present for MRI compatibility.)
Requires prior use of OPEN or CREATE.
OPEN archive
SAVE.
REPLACE module, module, ... module
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 OPEN or CREATE.
VERBOSE
DIRECTORY.
When the flag is on, DIRECTORY output matches output from
ar -tv ....
SAVE
CREATE or OPEN
command.
Requires prior use of OPEN or CREATE.
nm [ -a | --debug-syms ] [ -g | --extern-only ] [ -B ] [ -C | --demangle ] [ -D | --dynamic ] [ -s | --print-armap ] [ -A | -o | --print-file-name ] [ -n | -v | --numeric-sort ] [ -p | --no-sort ] [ -r | --reverse-sort ] [ --size-sort ] [ -u | --undefined-only ] [ -t radix | --radix=radix ] [ -P | --portability ] [ --target=bfdname ] [ -f format | --format=format ] [ --defined-only ] [-l | --line-numbers ] [ --no-demangle ] [ -V | --version ] [ --help ] [ objfile... ]
GNU nm lists the symbols from object files objfile....
If no object files are listed as arguments, nm assumes the file
a.out.
For each symbol, nm shows:
A
B
C
D
G
I
N
R
S
T
U
V
W
-
?
The long and short forms of options, shown here as alternatives, are equivalent.
-A
-o
--print-file-name
-a
--debug-syms
-B
--format=bsd (for compatibility with the MIPS nm).
-C
--demangle
--no-demangle
-D
--dynamic
-f format
--format=format
bsd,
sysv, or posix. The default is bsd.
Only the first character of format is significant; it can be
either upper or lower case.
-g
--extern-only
-l
--line-numbers
-n
-v
--numeric-sort
-p
--no-sort
-P
--portability
-f posix.
-s
--print-armap
ar or ranlib) of which modules
contain definitions for which names.
-r
--reverse-sort
--size-sort
-t radix
--radix=radix
d for decimal, o for octal, or x for hexadecimal.
--target=bfdname
-u
--undefined-only
--defined-only
-V
--version
nm and exit.
--help
nm and exit.
objcopy [ -F bfdname | --target=bfdname ]
[ -I bfdname | --input-target=bfdname ]
[ -O bfdname | --output-target=bfdname ]
[ -S | --strip-all ] [ -g | --strip-debug ]
[ -K symbolname | --keep-symbol=symbolname ]
[ -N symbolname | --strip-symbol=symbolname ]
[ -L symbolname | --localize-symbol=symbolname ]
[ -W symbolname | --weaken-symbol=symbolname ]
[ -x | --discard-all ] [ -X | --discard-locals ]
[ -b byte | --byte=byte ]
[ -i interleave | --interleave=interleave ]
[ -j sectionname | --only-section=sectionname ]
[ -R sectionname | --remove-section=sectionname ]
[ -p | --preserve-dates ] [ --debugging ]
[ --gap-fill=val ] [ --pad-to=address ]
[ --set-start=val ] [ --adjust-start=incr ]
[ --change-addresses=incr ]
[ --change-section-address section{=,+,-}val ]
[ --change-section-lma section{=,+,-}val ]
[ --change-section-vma section{=,+,-}val ]
[ --change-warnings ] [ --no-change-warnings ]
[ --set-section-flags section=flags ]
[ --add-section sectionname=filename ]
[ --change-leading-char ] [ --remove-leading-char ]
[ --redefine-sym old=new ] [ --weaken ]
[ -v | --verbose ] [ -V | --version ] [ --help ]
infile [outfile]
The GNU objcopy utility copies the contents of an object
file to another. 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 objcopy is controlled by command-line options.
objcopy creates temporary files to do its translations and
deletes them afterward. objcopy uses BFD to do all its
translation work; it has access to all the formats described in BFD
and thus is able to recognize most formats without being told
explicitly. See BFD.
objcopy can be used to generate S-records by using an output
target of srec (e.g., use -O srec).
objcopy can be used to generate a raw binary file by using an
output target of binary (e.g., use -O binary). When
objcopy generates a raw binary file, it will essentially produce
a memory dump of the contents of the input object file. All symbols and
relocation information will be discarded. The memory dump will start at
the load address of the lowest section copied into the output file.
When generating an S-record or a raw binary file, it may be helpful to
use -S to remove sections containing debugging information. In
some cases -R will be useful to remove sections which contain
information that is not needed by the binary file.
infile
outfile
objcopy creates a
temporary file and destructively renames the result with
the name of infile.
-I bfdname
--input-target=bfdname
-O bfdname
--output-target=bfdname
-F bfdname
--target=bfdname
-j sectionname
--only-section=sectionname
-R sectionname
--remove-section=sectionname
-S
--strip-all
-g
--strip-debug
--strip-unneeded
-K symbolname
--keep-symbol=symbolname
-N symbolname
--strip-symbol=symbolname
-L symbolname
--localize-symbol=symbolname
-W symbolname
--weaken-symbol=symbolname
-x
--discard-all
-X
--discard-locals
L or ..)
-b byte
--byte=byte
-i or --interleave
option, or the default of 4. This option is useful for creating files
to program ROM. It is typically used with an srec output
target.
-i interleave
--interleave=interleave
--byte option. The default is 4.
objcopy ignores this option if you do not specify either -b or
--byte.
-p
--preserve-dates
--debugging
--gap-fill val
--pad-to address
--gap-fill (default zero).
--set-start val
--change-start incr
--adjust-start incr
--change-addresses incr
--adjust-vma incr
--change-section-address section{=,+,-}val
--adjust-section-vma section{=,+,-}val
= is used, the section address is set to
val. Otherwise, val is added to or subtracted from the
section address. See the comments under --change-addresses,
above. If section does not exist in the input file, a warning will
be issued, unless --no-change-warnings is used.
--change-section-lma section{=,+,-}val
= is used, the section address is set to
val. Otherwise, val is added to or subtracted from the
section address. See the comments under --change-addresses,
above. If section does not exist in the input file, a warning
will be issued, unless --no-change-warnings is used.
--change-section-vma section{=,+,-}val
= is used, the section address
is set to val. Otherwise, val is added to or subtracted
from the section address. See the comments under
--change-addresses, above. If section does not exist in
the input file, a warning will be issued, unless
--no-change-warnings is used.
--change-warnings
--adjust-warnings
--change-section-address or --change-section-lma or
--change-section-vma is used, and the named section does not
exist, issue a warning. This is the default.
--no-change-warnings
--no-adjust-warnings
--change-section-address or
--adjust-section-lma or --adjust-section-vma is used, even
if the named section does not exist.
--set-section-flags section=flags
alloc, contents, load, noload,
readonly, code, data, rom, share, and
debug. You can set the contents flag for a section which
does not have contents, but it is not meaningful to clear the
contents flag of a section which does have contents-just remove
the section instead. Not all flags are meaningful for all object file
formats.
--add-section sectionname=filename
--change-leading-char
objcopy to
change the leading character of every symbol when it converts between
object file formats. If the object file formats use the same leading
character, this option has no effect. Otherwise, it will add a
character, or remove a character, or change a character, as
appropriate.
--remove-leading-char
--change-leading-char because it always changes the symbol name
when appropriate, regardless of the object file format of the output
file.
--redefine-sym old=new
--weaken
-R option to the linker. This option is only effective when
using an object file format which supports weak symbols.
-V
--version
objcopy.
-v
--verbose
objcopy -V lists all members of the archive.
--help
objcopy.
objdump [ -a | --archive-headers ]
[ -b bfdname | --target=bfdname ]
[ -C | --demangle ]
[ -d | --disassemble ]
[ -D | --disassemble-all ]
[ -z | --disassemble-zeroes ]
[ -EB | -EL | --endian={big | little } ]
[ -f | --file-headers ]
[ --file-start-context ]
[ -g | --debugging ]
[ -h | --section-headers | --headers ]
[ -i | --info ]
[ -j section | --section=section ]
[ -l | --line-numbers ]
[ -S | --source ]
[ -m machine | --architecture=machine ]
[ -M options | --disassembler-options=options]
[ -p | --private-headers ]
[ -r | --reloc ]
[ -R | --dynamic-reloc ]
[ -s | --full-contents ]
[ -G | --stabs ]
[ -t | --syms ]
[ -T | --dynamic-syms ]
[ -x | --all-headers ]
[ -w | --wide ]
[ --start-address=address ]
[ --stop-address=address ]
[ --prefix-addresses]
[ --[no-]show-raw-insn ]
[ --adjust-vma=offset ]
[ -V | --version ]
[ -H | --help ]
objfile...
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.
objfile... are the object files to be examined. When you
specify archives, objdump shows information on each of the member
object files.
The long and short forms of options, shown here as alternatives, are
equivalent. At least one option from the list
-a,-d,-D,-f,-g,-G,-h,-H,-p,-r,-R,-S,-t,-T,-V,-x must be given.
-a
--archive-header
ls -l). Besides the
information you could list with ar tv, objdump -a shows
the object file format of each archive member.
--adjust-vma=offset
-b bfdname
--target=bfdname
For example,
objdump -b oasys -m vax -h fu.o
displays summary information from the section headers (-h) of
fu.o, which is explicitly identified (-m) as a VAX object
file in the format produced by Oasys compilers. You can list the
formats available with the -i option.
See Target Selection, for more information.
-C
--demangle
-G
--debugging
-d
--disassemble
-D
--disassemble-all
-d, but disassemble the contents of all sections, not just
those expected to contain instructions.
--prefix-addresses
--disassemble-zeroes
-EB
-EL
--endian={big|little}
-f
--file-header
--file-start-context
-h
--section-header
--header
File segments may be relocated to nonstandard addresses, for example by
using the -Ttext, -Tdata, or -Tbss options to
ld. However, some object file formats, such as a.out, do not
store the starting address of the file segments. In those situations,
although ld relocates the sections correctly, using objdump
-h to list the file section headers cannot show the correct addresses.
Instead, it shows the usual addresses, which are implicit for the
target.
--help
objdump and exit.
-i
--info
-b or -m.
-j name
--section=name
-l
--line-numbers
-d, -D, or -r.
-m machine
--architecture=machine
-i option.
-M options
--disassembler-options=options
If the target is an ARM architecture then this switch can be used to
select which register name set is used during disassembler. Specifying
-M 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
-M reg-names-apcs will select the name set used by the ARM
Procedure Call Standard, whilst specifying -M reg-names-raw will
just use r followed by the register number.
There are also two variants on the APCS register naming scheme enabled
by -M reg-names-atpcs and -M reg-names-special-atpcs which
use the ARM/Thumb Procedure Call Standard naming conventions. (Eiuther
with the normal register name sor the special register names).
This option can also be used for ARM architectures to force the
disassembler to interpret all instructions as THUMB instructions by
using the switch --disassembler-options=force-thumb. This can be
useful when attempting to disassemble thumb code produced by other
compilers.
-p
--private-headers
-r
--reloc
-d or
-D, the relocations are printed interspersed with the
disassembly.
-R
--dynamic-reloc
-s
--full-contents
-S
--source
-d.
--show-raw-insn
--prefix-addresses is used.
--no-show-raw-insn
--prefix-addresses is used.
-G
--stabs
.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 --syms
output. For more information on stabs symbols, see Top.
--start-address=address
-d, -r and -s options.
--stop-address=address
-d, -r and -s options.
-t
--syms
nm program.
-T
--dynamic-syms
nm
program when given the -D (--dynamic) option.
--version
objdump and exit.
-x
--all-header
-x is equivalent to specifying all of
-a -f -h -r -t.
-w
--wide
ranlib [-vV] archive
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 nm -s or 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 ranlib program is another form of GNU ar; running
ranlib is completely equivalent to executing ar -s.
See ar.
-v
-V
--version
ranlib.
size [ -A | -B | --format=compatibility ]
[ --help ] [ -d | -o | -x | --radix=number ]
[ --target=bfdname ] [ -V | --version ]
[ objfile... ]
The GNU size utility lists the section sizes--and the total
size--for each of the object or archive files objfile in its
argument list. By default, one line of output is generated for each
object file or each module in an archive.
objfile... are the object files to be examined.
If none are specified, the file a.out will be used.
The command line options have the following meanings:
-A
-B
--format=compatibility
size resembles output from System V size (using -A,
or --format=sysv), or Berkeley size (using -B, or
--format=berkeley). The default is the one-line format similar to
Berkeley's.
Here is an example of the Berkeley (default) format of output from
size:
$ size --format=Berkeley ranlib size text data bss dec hex filename 294880 81920 11592 388392 5ed28 ranlib 294880 81920 11888 388688 5ee50 size
This is the same data, but displayed closer to System V conventions:
$ 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
--help
-d
-o
-x
--radix=number
-d, or --radix=10); octal
(-o, or --radix=8); or hexadecimal (-x, or
--radix=16). In --radix=number, only the three
values (8, 10, 16) are supported. The total size is always given in two
radices; decimal and hexadecimal for -d or -x output, or
octal and hexadecimal if you're using -o.
--target=bfdname
size can
automatically recognize many formats.
See Target Selection, for more information.
-V
--version
size.
strings [-afov] [-min-len] [-n min-len] [-t radix] [-]
[--all] [--print-file-name] [--bytes=min-len]
[--radix=radix] [--target=bfdname]
[--help] [--version] file...
For each file given, GNU strings prints the printable
character sequences that are at least 4 characters long (or the number
given with the options below) and are followed by an unprintable
character. By default, it only prints the strings from the initialized
and loaded sections of object files; for other types of files, it prints
the strings from the whole file.
strings is mainly useful for determining the contents of non-text
files.
-a
--all
-
-f
--print-file-name
--help
-min-len
-n min-len
--bytes=min-len
-o
-t o. Some other versions of strings have -o
act like -t d instead. Since we can not be compatible with both
ways, we simply chose one.
-t radix
--radix=radix
o for
octal, x for hexadecimal, or d for decimal.
--target=bfdname
-v
--version
strip [ -F bfdname | --target=bfdname ]
[ -I bfdname | --input-target=bfdname ]
[ -O bfdname | --output-target=bfdname ]
[ -s | --strip-all ] [ -S | -g | --strip-debug ]
[ -K symbolname | --keep-symbol=symbolname ]
[ -N symbolname | --strip-symbol=symbolname ]
[ -x | --discard-all ] [ -X | --discard-locals ]
[ -R sectionname | --remove-section=sectionname ]
[ -o file ] [ -p | --preserve-dates ]
[ -v | --verbose ] [ -V | --version ] [ --help ]
objfile...
GNU strip discards all symbols from object files
objfile. The list of object files may include archives.
At least one object file must be given.
strip modifies the files named in its argument,
rather than writing modified copies under different names.
-F bfdname
--target=bfdname
--help
strip and exit.
-I bfdname
--input-target=bfdname
-O bfdname
--output-target=bfdname
-R sectionname
--remove-section=sectionname
-s
--strip-all
-g
-S
--strip-debug
--strip-unneeded
-K symbolname
--keep-symbol=symbolname
-N symbolname
--strip-symbol=symbolname
-K.
-o file
-p
--preserve-dates
-x
--discard-all
-X
--discard-locals
L or ..)
-V
--version
strip.
-v
--verbose
strip -v lists all members of the archive.
c++filt [ -_ | --strip-underscores ]
[ -j | --java ]
[ -n | --no-strip-underscores ]
[ -s format | --format=format ]
[ --help ] [ --version ] [ symbol... ]
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
mangling). The c++filt
1
program does the inverse mapping: it decodes (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.
You can use c++filt to decipher individual symbols:
c++filt symbol
If no symbol arguments are given, c++filt reads symbol
names from the standard input and writes the demangled names to the
standard output. All results are printed on the standard output.
-_
--strip-underscores
foo gets the low-level
name _foo. This option removes the initial underscore. Whether
c++filt removes the underscore by default is target dependent.
-j
--java
-n
--no-strip-underscores
-s format
--format=format
nm can decode three different methods of mangling, used by
different C++ compilers. The argument to this option selects which
method it uses:
gnu
lucid
arm
hp
edg
--help
c++filt and exit.
--version
c++filt and exit.
Warning:c++filtis 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,c++filt symbolmay in a future release become
c++filt option symbol
addr2line [ -b bfdname | --target=bfdname ]
[ -C | --demangle ]
[ -e filename | --exe=filename ]
[ -f | --functions ] [ -s | --basename ]
[ -H | --help ] [ -V | --version ]
[ addr addr ... ]
addr2line translates program addresses into file names and line
numbers. Given an address and an executable, it uses the debugging
information in the executable to figure out which file name and line
number are associated with a given address.
The executable to use is specified with the -e option. The
default is the file a.out.
addr2line has two modes of operation.
In the first, hexadecimal addresses are specified on the command line,
and addr2line displays the file name and line number for each
address.
In the second, addr2line reads hexadecimal addresses from
standard input, and prints the file name and line number for each
address on standard output. In this mode, addr2line may be used
in a pipe to convert dynamically chosen addresses.
The format of the output is FILENAME:LINENO. The file name and
line number for each address is printed on a separate line. If the
-f option is used, then each FILENAME:LINENO line is
preceded by a FUNCTIONNAME line which is the name of the function
containing the address.
If the file name or function name can not be determined,
addr2line will print two question marks in their place. If the
line number can not be determined, addr2line will print 0.
The long and short forms of options, shown here as alternatives, are equivalent.
-b bfdname
--target=bfdname
-C
--demangle
-e filename
--exe=filename
a.out.
-f
--functions
-s
--basenames
nlmconv converts a relocatable object file into a NetWare
Loadable Module.
Warning: nlmconv is not always built as part of the binary
utilities, since it is only useful for NLM targets.
nlmconv [ -I bfdname | --input-target=bfdname ]
[ -O bfdname | --output-target=bfdname ]
[ -T headerfile | --header-file=headerfile ]
[ -d | --debug] [ -l linker | --linker=linker ]
[ -h | --help ] [ -V | --version ]
infile outfile
nlmconv converts the relocatable i386 object file
infile into the NetWare Loadable Module outfile, optionally
reading headerfile for NLM header information. For instructions
on writing the NLM command file language used in header files, see the
linkers section, NLMLINK in particular, of the NLM
Development and Tools Overview, which is part of the NLM Software
Developer's Kit ("NLM SDK"), available from Novell, Inc.
nlmconv uses the GNU Binary File Descriptor library to read
infile; see BFD, for
more information.
nlmconv can perform a link step. In other words, you can list
more than one object file for input if you list them in the definitions
file (rather than simply specifying one input file on the command line).
In this case, nlmconv calls the linker for you.
-I bfdname
--input-target=bfdname
nlmconv can usually determine
the format of a given file (so no default is necessary).
See Target Selection, for more information.
-O bfdname
--output-target=bfdname
nlmconv infers the output
format based on the input format, e.g. for a i386 input file the
output format is nlm32-i386.
See Target Selection, for more information.
-T headerfile
--header-file=headerfile
linkers section, of the NLM Development and Tools
Overview, which is part of the NLM Software Developer's Kit, available
from Novell, Inc.
-d
--debug
nlmconv.
-l linker
--linker=linker
-h
--help
-V
--version
nlmconv.
windres may be used to manipulate Windows resources.
Warning: windres is not always built as part of the binary
utilities, since it is only useful for Windows targets.
windres [options] [input-file] [output-file]
windres reads resources from an input file and copies them into
an output file. Either file may be in one of three formats:
rc
res
coff
The exact description of these different formats is available in documentation from Microsoft.
When windres converts from the rc format to the res
format, it is acting like the Windows Resource Compiler. When
windres converts from the res format to the coff
format, it is acting like the Windows CVTRES program.
When windres generates an rc file, the output is similar
but not identical to the format expected for the input. When an input
rc file refers to an external filename, an output rc file
will instead include the file contents.
If the input or output format is not specified, windres will
guess based on the file name, or, for the input file, the file contents.
A file with an extension of .rc will be treated as an rc
file, a file with an extension of .res will be treated as a
res file, and a file with an extension of .o or
.exe will be treated as a coff file.
If no output file is specified, windres will print the resources
in rc format to standard output.
The normal use is for you to write an rc file, use windres
to convert it to a COFF object file, and then link the COFF file into
your application. This will make the resources described in the
rc file available to Windows.
-i filename
--input filename
windres will use the first non-option argument as the input file
name. If there are no non-option arguments, then windres will
read from standard input. windres can not read a COFF file from
standard input.
-o filename
--output filename
windres will use the first non-option argument, after any used
for the input file name, as the output file name. If there is no
non-option argument, then windres will write to standard output.
windres can not write a COFF file to standard output.
-I format
--input-format format
res, rc, or
coff. If no input format is specified, windres will
guess, as described above.
-O format
--output-format format
res,
rc, or coff. If no output format is specified,
windres will guess, as described above.
-F target
--target target
--help option to see a list
of supported targets. Normally windres will use the default
format, which is the first one listed by the --help option.
Target Selection.
--preprocessor program
windres reads an rc file, it runs it through the C
preprocessor first. This option may be used to specify the preprocessor
to use, including any leading arguments. The default preprocessor
argument is gcc -E -xc-header -DRC_INVOKED.
--include-dir directory
rc file.
windres will pass this to the preprocessor as an -I
option. windres will also search this directory when looking for
files named in the rc file.
-D target
--define sym[=val]
-D option to pass to the preprocessor when reading an
rc file.
-v
--language val
rc file.
val should be a hexadecimal language code. The low eight bits are
the language, and the high eight bits are the sublanguage.
--use-temp-file
--no-use-temp-file
--help
--version
windres.
--yydebug
windres is compiled with YYDEBUG defined as 1,
this will turn on parser debugging.
dlltool may be used to create the files needed to build and use
dynamic link libraries (DLLs).
Warning: dlltool is not always built as part of the binary
utilities, since it is only useful for those targets which support DLLs.
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]
[--export-all-symbols] [--no-export-all-symbols]
[--exclude-symbols list]
[--no-default-excludes]
[-S|--as path-to-assembler] [-f|--as-flags options]
[-D|--dllname name] [-m|--machine 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 ...]
dlltool reads its inputs, which can come from the -d and
-b options as well as object files specified on the command
line. It then processes these inputs and if the -e option has
been specified it creates a exports file. If the -l option
has been specified it creates a library file and if the -z option
has been specified it creates a def file. Any or all of the -e, -l
and -z options can be present in one invocation of dlltool.
When creating a DLL, along with the source for the DLL, it is necessary
to have three other files. dlltool can help with the creation of
these files.
The first file is a .def file which specifies which functions are
exported from the DLL, which functions the DLL imports, and so on. This
is a text file and can be created by hand, or dlltool can be used
to create it using the -z option. In this case dlltool
will scan the object files specified on its command line looking for
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 -export:<name_of_function> entry in the .drectve
section of the object file. This can be done in C by using the
asm() operator:
asm (".section .drectve");
asm (".ascii \"-export:my_func\"");
int my_func (void) { ... }
The second file needed for DLL creation is an exports file. This file
is linked with the object files that make up the body of the DLL and it
handles the interface between the DLL and the outside world. This is a
binary file and it can be created by giving the -e option to
dlltool when it is creating or reading in a .def file.
The third file needed for DLL creation is the library file that programs
will link with in order to access the functions in the DLL. This file
can be created by giving the -l option to dlltool when it
is creating or reading in a .def file.
dlltool builds the library file by hand, but it builds the
exports file by creating temporary files containing assembler statements
and then assembling these. The -S command line option can be
used to specify the path to the assembler that dlltool will use,
and the -f option can be used to pass specific flags to that
assembler. The -n can be used to prevent dlltool from deleting
these temporary assembler files when it is done, and if -n is
specified twice then this will prevent dlltool from deleting the
temporary object files it used to build the library.
Here is an example of creating a DLL from a source file dll.c and
also creating a program (from an object file called program.o)
that uses that DLL:
gcc -c dll.c dlltool -e exports.o -l dll.lib dll.o gcc dll.o exports.o -o dll.dll gcc program.o dll.lib -o program
The command line options have the following meanings:
-d filename
--input-def filename
-b filename
--base-file filename
-e filename
--output-exp filename
-z filename
--output-def filename
-l filename
--output-lib filename
--export-all-symbols
--no-default-excludes
option. You may add to the list of symbols to not export by using the
--exclude-symbols option.
--no-export-all-symbols
.drectve sections in the input object files. This is the default
behaviour. The .drectve sections are created by dllexport
attributes in the source code.
--exclude-symbols list
--export-all-symbols is used.
--no-default-excludes
--export-all-symbols is used, it will by default avoid
exporting certain special symbols. The current list of symbols to avoid
exporting is DllMain@12, DllEntryPoint@0,
impure_ptr. You may use the --no-default-excludes option
to go ahead and export these special symbols. This is only meaningful
when --export-all-symbols is used.
-S path
--as path
-f switches
--as-flags switches
-S option is not used. This option only takes one argument,
and if it occurs more than once on the command line, then later
occurrences will override earlier occurrences. So if it is necessary to
pass multiple switches to the assembler they should be enclosed in
double quotes.
-D name
--dll-name name
-e option is used. If this option is not present, then
the filename given to the -e option will be used as the name of
the DLL.
-m machine
-machine machine
dlltool has a built in default type, depending upon how
it was created, but this option can be used to override that. This is
normally only useful when creating DLLs for an ARM processor, when the
contents of the DLL are actually encode using THUMB instructions.
-a
--add-indirect
dlltool is creating the exports file it
should add a section which allows the exported functions to be
referenced without using the import library. Whatever the hell that
means!
-U
--add-underscore
dlltool is creating the exports file it
should prepend an underscore to the names of the exported functions.
-k
--kill-at
dlltool is creating the exports file it
should not append the string @ <number>. These numbers are
called ordinal numbers and they represent another way of accessing the
function in a DLL, other than by name.
-A
--add-stdcall-alias
dlltool is creating the exports file it
should add aliases for stdcall symbols without @ <number>
in addition to the symbols with @ <number>.
-x
--no-idata4
dlltool is creating the exports and library
files it should omit the .idata4 section. This is for compatibility
with certain operating systems.
-c
--no-idata5
dlltool is creating the exports and library
files it should omit the .idata5 section. This is for compatibility
with certain operating systems.
-i
--interwork
dlltool should mark the objects in the library
file and exports file that it produces as supporting interworking
between ARM and THUMB code.
-n
--nodelete
dlltool preserve the temporary assembler files it used to
create the exports file. If this option is repeated then dlltool will
also preserve the temporary object files it uses to create the library
file.
-v
--verbose
-h
--help
-V
--version
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]
elffile...
readelf displays information about one or more ELF format object
files. The options control what particular information to display.
elffile... are the object files to be examined. At the
moment, 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 -v or -H must be
given.
-a
--all
--file-header,
--program-headers, --sections, --symbols,
--relocs, --dynamic, --notes and
--version-info.
-h
--file-header
-l
--program-headers
--segments
-S
--sections
--section-headers
-s
--symbols
--syms
-e
--headers
-h -l -S.
-n
--notes
-r
--relocs
-d
--dynamic
-V
--version-info
-D
--use-dynamic
readelf use the
symbol table in the file's dynamic section, rather than the one in the
symbols section.
-x <number>
--hex-dump=<number>
-w[liapr]
--debug-dump[=line,=info,=abbrev,=pubnames,=ranges]
--histogram
-v
--version
-H
--help
readelf.
You can specify three aspects of the target system to the GNU binary file utilities, each in several ways:
In the following summaries, the lists of ways to specify values are in order of decreasing precedence. The ways listed first override those listed later.
The commands to list valid values only list the values for which the
programs you are running were configured. If they were configured with
--enable-targets=all, the commands list most of the available
values, but a few are left out; not all targets can be configured in at
once because some of them can only be configured native (on hosts
with the same type as the target system).
A target is an object file format. A given target may be supported for multiple architectures (see Architecture Selection). A target selection may also have variations for different operating systems or architectures.
The command to list valid target values is objdump -i
(the first column of output contains the relevant information).
Some sample values are: a.out-hp300bsd, ecoff-littlemips,
a.out-sunos-big.
You can also specify a target using a configuration triplet. This is
the same sort of name that is passed to configure to specify a
target. When you use a configuration triplet as an argument, it must be
fully canonicalized. You can see the canonical version of a triplet by
running the shell script config.sub which is included with the
sources.
Some sample configuration triplets are: m68k-hp-bsd,
mips-dec-ultrix, sparc-sun-sunos.
objdump TargetWays to specify:
-b or --target
GNUTARGET
objcopy and strip Input TargetWays to specify:
-I or --input-target, or -F or --target
GNUTARGET
objcopy and strip Output TargetWays to specify:
-O or --output-target, or -F or --target
objcopy and strip Input Target" above)
GNUTARGET
nm, size, and strings TargetWays to specify:
--target
GNUTARGET
Ways to specify:
-b or --format
(see Options)
TARGET
(see Option Commands)
GNUTARGET
(see Environment)
Ways to specify:
-oformat
(see Options)
OUTPUT_FORMAT
(see Option Commands)
An architecture is a type of CPU on which an object file is to run. Its name may contain a colon, separating the name of the processor family from the name of the particular CPU.
The command to list valid architecture values is objdump -i (the
second column contains the relevant information).
Sample values: m68k:68020, mips:3000, sparc.
objdump ArchitectureWays to specify:
-m or --architecture
objcopy, nm, size, strings ArchitectureWays to specify:
Ways to specify:
Ways to specify:
OUTPUT_ARCH
(see Option Commands)
A linker emulation is a "personality" of the linker, which gives the linker default values for the other aspects of the target system. In particular, it consists of
The command to list valid linker emulation values is ld -V.
Sample values: hp300bsd, mipslit, sun4.
Ways to specify:
-m
(see Options)
LDEMULATION
DEFAULT_EMULATION from Makefile,
which comes from EMUL in config/target.mt
Your bug reports play an essential role in making the binary utilities reliable.
Reporting a bug may help you by bringing a solution to your problem, or it may not. But in any case the principal function of a bug report is to help the entire community by making the next version of the binary utilities work better. Bug reports are your contribution to their maintenance.
In order for a bug report to serve its purpose, you must include the information that enables us to fix the bug.
If you are not sure whether you have found a bug, here are some guidelines:
A number of companies and individuals offer support for GNU products. If you obtained the binary utilities from a support organization, we recommend you contact that organization first.
You can find contact information for many support companies and
individuals in the file etc/SERVICE in the GNU Emacs
distribution.
In any event, we also recommend that you send bug reports for the binary
utilities to bug-gnu-utils@gnu.org.
The fundamental principle of reporting bugs usefully is this: report all the facts. If you are not sure whether to state a fact or leave it out, state it!
Often people omit facts because they think they know what causes the problem and assume that some details do not matter. Thus, you might assume that the name of a file you use in an example does not matter. Well, probably it does not, but one cannot be sure. Perhaps the bug is a stray memory reference which happens to fetch from the location where that pathname is stored in memory; perhaps, if the pathname were different, the contents of that location would fool the utility into doing the right thing despite the bug. Play it safe and give a specific, complete example. That is the easiest thing for you to do, and the most helpful.
Keep in mind that the purpose of a bug report is to enable us to fix the bug if it is new to us. Therefore, always write your bug reports on the assumption that the bug has not been reported previously.
Sometimes people give a few sketchy facts and ask, "Does this ring a bell?" Those bug reports are useless, and we urge everyone to refuse to respond to them except to chide the sender to report bugs properly.
To enable us to fix the bug, you should include all these things:
--version argument.
Without this, we will not know whether there is any point in looking for the bug in the current version of the binary utilities.
BFD library.
gcc-2.7".
If we were to try to guess the arguments, we would probably guess wrong and then we might not encounter the bug.
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 GNU programs
(e.g., gcc, gas, and/or the GNU ld), then it
may be OK to send the source files rather than the object files. In
this case, be sure to say exactly what version of gcc, or
whatever, was used to produce the object files. Also say how
gcc, or whatever, was configured.
Of course, if the bug is that the utility gets a fatal signal, then we will certainly notice it. But if the bug is incorrect output, we might not notice unless it is glaringly wrong. You might as well not give us a chance to make a mistake.
Even if the problem you experience is a fatal signal, you should still say so explicitly. Suppose something strange is going on, such as your copy of the utility is out of synch, or you have encountered a bug in the C library on your system. (This has happened!) Your copy might crash and ours would not. If you told us to expect a crash, then when ours fails to crash, we would know that the bug was not happening for us. If you had not told us to expect a crash, then we would not be able to draw any conclusion from our observations.
diff with the -u, -c, or -p
option. Always send diffs from the old file to the new file. If you
wish to discuss something in the ld source, refer to it by
context, not by line number.
The line numbers in our development sources will not match those in your sources. Your line numbers would convey no useful information to us.
Here are some things that are not necessary:
Often people who encounter a bug spend a lot of time investigating which changes to the input file will make the bug go away and which changes will not affect it.
This is often time consuming and not very useful, because the way we will find the bug is by running a single example under the debugger with breakpoints, not by pure deduction from a series of examples. We recommend that you save your time for something else.
Of course, if you can find a simpler example to report instead of the original one, that is a convenience for us. Errors in the output will be easier to spot, running under the debugger will take less time, and so on.
However, simplification is not vital; if you do not want to do this, report the bug anyway and send us the entire test case you used.
A patch for the bug does help us if it is a good one. But do not omit the necessary information, such as the test case, on the assumption that a patch is all we need. We might see problems with your patch and decide to fix the problem another way, or we might not understand it at all.
Sometimes with programs as complicated as the binary utilities it is very hard to construct an example that will make the program follow a certain path through the code. If you do not send us the example, we will not be able to construct one, so we will not be able to verify that the bug is fixed.
And if we cannot understand what bug you are trying to fix, or why your patch should be an improvement, we will not install it. A test case will help us to understand.
Such guesses are usually wrong. Even we cannot guess right about such things without first using the debugger to find the facts.
addr2line: addr2line
ar: ar
ar compatibility: ar
c++filt: c++filt
ar: ar
cxxfilt: c++filt
dlltool: dlltool
ar: ar scripts
nm: nm
nm compatibility: nm
nm format: nm
objdump: objdump
ranlib: ranlib
readelf: readelf
ar: ar scripts
size: size
size display format: size
size number format: size
strings: strings
strip: strip
ar: ar cmdline