327 lines
13 KiB
Groff
327 lines
13 KiB
Groff
.\" Copyright (c) 1991, 93, 94, 95, 96, 97, 98, 1999 Free Software Foundation
|
|
.\" See section COPYING for conditions for redistribution
|
|
.TH objcopy 1 "1999" "Cygnus Solutions" "GNU Development Tools"
|
|
.de BP
|
|
.sp
|
|
.ti \-.2i
|
|
\(**
|
|
..
|
|
|
|
.SH NAME
|
|
objcopy \- copy and translate object files
|
|
|
|
.SH SYNOPSIS
|
|
.hy 0
|
|
.na
|
|
.TP
|
|
.B objcopy
|
|
.RB "[\|" \-F\ \fIbfdname\fR\ |\ \fB\-\-target=\fIbfdname\fR "\|]"
|
|
.RB "[\|" \-I\ \fIbfdname\fR\ |\ \fB\-\-input\-target=\fIbfdname\fR "\|]"
|
|
.RB "[\|" \-O\ \fIbfdname\fR\ |\ \fB\-\-output\-target=\fIbfdname\fR "\|]"
|
|
.RB "[\|" \-j\ \fIsectionname\fR\ |\ \fB\-\-only\-section=\fIsectionname\fR "\|]"
|
|
.RB "[\|" \-R\ \fIsectionname\fR\ |\ \fB\-\-remove\-section=\fIsectionname\fR "\|]"
|
|
.RB "[\|" \-S\fR\ |\ \fB\-\-strip\-all\fR "\|]"
|
|
.RB "[\|" \-g\fR\ |\ \fB\-\-strip\-debug\fR "\|]"
|
|
.RB "[\|" \-\-strip\-unneeded\fR "\|]"
|
|
.RB "[\|" \-K\ \fIsymbolname\fR\ |\ \fB\-\-keep\-symbol=\fIsymbolname\fR "\|]"
|
|
.RB "[\|" \-N\ \fIsymbolname\fR\ |\ \fB\-\-strip\-symbol=\fIsymbolname\fR "\|]"
|
|
.RB "[\|" \-L\ \fIsymbolname\fR\ |\ \fB\-\-localize\-symbol=\fIsymbolname\fR "\|]"
|
|
.RB "[\|" \-W\ \fIsymbolname\fR\ |\ \fB\-\-weaken\-symbol=\fIsymbolname\fR "\|]"
|
|
.RB "[\|" \-x\fR\ |\ \fB\-\-discard\-all\fR "\|]"
|
|
.RB "[\|" \-X\fR\ |\ \fB\-\-discard\-locals\fR "\|]"
|
|
.RB "[\|" \-b\ \fIbyte\fR\ |\ \fB\-\-byte=\fIbyte\fR "\|]"
|
|
.RB "[\|" \-i\ \fIinterleave\fR\ |\ \fB\-\-interleave=\fIinterleave\fR "\|]"
|
|
.RB "[\|" \-p\fR\ |\ \fB\-\-preserve\-dates\fR "\|]"
|
|
.RB "[\|" \-\-debugging "\|]"
|
|
.RB "[\|" \-\-gap\-fill=\fIval\fR "\|]"
|
|
.RB "[\|" \-\-pad\-to=\fIaddress\fR "\|]"
|
|
.RB "[\|" \-\-set\-start=\fIval\fR "\|]"
|
|
.RB "[\|" \-\-change\-start=\fIincr\fR "\|]"
|
|
.RB "[\|" \-\-change\-addresses=\fIincr\fR "\|]"
|
|
.RB "[\|" \-\-change\-section\-address=\fIsection{=,+,-}val\fR "\|]"
|
|
.RB "[\|" \-\-change\-section\-lma=\fIsection{=,+,-}val\fR "\|]"
|
|
.RB "[\|" \-\-change\-section\-vma=\fIsection{=,+,-}val\fR "\|]"
|
|
.RB "[\|" \-\-change\-warnings\fR "\|]"
|
|
.RB "[\|" \-\-no\-change\-warnings\fR "\|]"
|
|
.RB "[\|" \-\-set\-section\-flags=\fIsection=flags\fR "\|]"
|
|
.RB "[\|" \-\-add\-section=\fIsectionname=filename\fR "\|]"
|
|
.RB "[\|" \-\-change\-leading\-char\fR "\|]"
|
|
.RB "[\|" \-\-remove\-leading\-char\fR "\|]"
|
|
.RB "[\|" \-\-weaken\fR "\|]"
|
|
.RB "[\|" \-v\ |\ \-\-verbose\fR "\|]"
|
|
.RB "[\|" \-V\ |\ \-\-version\fR "\|]"
|
|
.RB "[\|" \-\-help\fR "\|]"
|
|
.B infile
|
|
.RB "[\|" outfile\fR "\|]"
|
|
.SH DESCRIPTION
|
|
The GNU
|
|
.B objcopy
|
|
utility copies the contents of an object file to another.
|
|
.B 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
|
|
.B objcopy
|
|
is controlled by command-line options.
|
|
.PP
|
|
.B objcopy
|
|
creates temporary files to do its translations and deletes them
|
|
afterward.
|
|
.B 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.
|
|
.PP
|
|
.B objcopy
|
|
can be used to generate S-records by using an output target of
|
|
.B srec
|
|
(e.g., use
|
|
.B -O srec).
|
|
.PP
|
|
.B objcopy
|
|
can be used to generate a raw binary file by using an output target of
|
|
.B binary
|
|
(e.g., use
|
|
.B -O binary).
|
|
When
|
|
.B 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
|
|
virtual address of the lowest section copied into the output file.
|
|
.PP
|
|
When generating an S-record or a raw binary file, it may be helpful to
|
|
use
|
|
.B -S
|
|
to remove sections containing debugging information. In some cases
|
|
.B -R
|
|
will be useful to remove sections which contain information which is
|
|
not needed by the binary file.
|
|
.PP
|
|
.I infile
|
|
and
|
|
.I outfile
|
|
are the source and output files respectively. If you do not specify
|
|
.IR outfile ,
|
|
.B objcopy
|
|
creates a temporary file and destructively renames the result with the
|
|
name of the input file.
|
|
|
|
.SH OPTIONS
|
|
.TP
|
|
.B \-I \fIbfdname\fR, \fB\-\-input\-target=\fIbfdname
|
|
Consider the source file's object format to be
|
|
.IR bfdname ,
|
|
rather than attempting to deduce it.
|
|
.TP
|
|
.B \-O \fIbfdname\fR, \fB\-\-output\-target=\fIbfdname
|
|
Write the output file using the object format
|
|
.IR bfdname .
|
|
.TP
|
|
.B \-F \fIbfdname\fR, \fB\-\-target=\fIbfdname
|
|
Use
|
|
.I bfdname
|
|
as the object format for both the input and the output file; i.e.
|
|
simply transfer data from source to destination with no translation.
|
|
.TP
|
|
.B \-j \fIsectionname\fR, \fB\-\-only\-section=\fIsectionname
|
|
Copy only the named section from the input file to the output file,
|
|
discarding all other sections. This option may be given more than
|
|
once. Note that using this option inappropriately may make the output
|
|
file unusable.
|
|
.TP
|
|
.B \-R \fIsectionname\fR, \fB\-\-remove-section=\fIsectionname
|
|
Remove the named section from the file. This option may be given more
|
|
than once. Note that using this option inappropriately may make the
|
|
output file unusable.
|
|
.TP
|
|
.B \-S\fR, \fB\-\-strip\-all
|
|
Do not copy relocation and symbol information from the source file.
|
|
.TP
|
|
.B \-g\fR, \fB\-\-strip\-debug
|
|
Do not copy debugging symbols from the source file.
|
|
.TP
|
|
.B \-\-strip\-unneeded
|
|
Strip all symbols that are not needed for relocation processing.
|
|
.TP
|
|
.B \-K \fIsymbolname\fR, \fB\-\-keep\-symbol=\fIsymbolname
|
|
Copy only symbol \fIsymbolname\fP from the source file. This option
|
|
may be given more than once.
|
|
.TP
|
|
.B \-N \fIsymbolname\fR, \fB\-\-strip\-symbol=\fIsymbolname
|
|
Do not copy symbol \fIsymbolname\fP from the source file. This option
|
|
may be given more than once.
|
|
.TP
|
|
.B \-L \fIsymbolname\fR, \fB\-\-localize\-symbol=\fIsymbolname
|
|
Make symbol \fIsymbolname\fP local to the file, so that it is not
|
|
visible externally. This option may be given more than once.
|
|
.TP
|
|
.B \-W \fIsymbolname\fR, \fB\-\-weaken\-symbol=\fIsymbolname
|
|
Make symbol \fIsymbolname\fP weak. This option may be given more than once.
|
|
.TP
|
|
.B \-x\fR, \fB \-\-discard\-all
|
|
Do not copy non-global symbols from the source file.
|
|
.TP
|
|
.B \-X\fR, \fB\-\-discard\-locals
|
|
Do not copy compiler-generated local symbols. (These usually start
|
|
with "L" or ".").
|
|
.TP
|
|
.B \-b \fIbyte\fR, \fB\-\-byte=\fIbyte
|
|
Keep only every \fIbyte\fPth byte of the input file (header data is
|
|
not affected). \fIbyte\fP can be in the range from 0 to the
|
|
interleave-1. This option is useful for creating files to program
|
|
ROMs. It is typically used with an srec output target.
|
|
.TP
|
|
.B \-i \fIinterleave\fR, \fB\-\-interleave=\fIinterleave
|
|
Only copy one out of every \fIinterleave\fP bytes. Which one to copy is
|
|
selected by the \fB\-b\fP or \fB\-\-byte\fP option. The default is 4.
|
|
The interleave is ignored if neither \fB\-b\fP nor \fB\-\-byte\fP is given.
|
|
.TP
|
|
.B \-p\fR, \fB\-\-preserve\-dates
|
|
Set the access and modification dates of the output file to be the same
|
|
as those of the input file.
|
|
.TP
|
|
.B \-\-debugging
|
|
Convert debugging information, if possible. This is not the default
|
|
because only certain debugging formats are supported, and the
|
|
conversion process can be time consuming.
|
|
.TP
|
|
.B \-\-gap\-fill=\fIval
|
|
Fill gaps between sections with \fIval\fP. This operation applies to
|
|
the \fIload address\fP (LMA) of the sections. It is done by increasing
|
|
the size of the section with the lower address, and filling in the extra
|
|
space created with \fIval\fP.
|
|
.TP
|
|
.B \-\-pad\-to=\fIaddress
|
|
Pad the output file up to the load address \fIaddress\fP. This is
|
|
done by increasing the size of the last section. The extra space is
|
|
filled in with the value specified by \fB\-\-gap\-fill\fP (default
|
|
zero).
|
|
.TP
|
|
.B \fB\-\-set\-start=\fIval
|
|
Set the start address of the new file to \fIval\fP. Not all object
|
|
file formats support setting the start address.
|
|
.TP
|
|
.B \fB\-\-change\-start=\fIincr\fR, \fB\-\-adjust\-start=\fIincr
|
|
Changes the start address by adding \fIincr\fP. Not all object file
|
|
formats support setting the start address.
|
|
.TP
|
|
.B \fB\-\-change\-addresses=\fIincr\fR, \fB\-\-adjust\-vma=\fIincr
|
|
Changes the address of all sections, as well as the start address, by
|
|
adding \fIincr\fP. Some object file formats do not permit section
|
|
addresses to be changed arbitrarily. Note that this does not relocate
|
|
the sections; if the program expects sections to be loaded at a
|
|
certain address, and this option is used to change the sections such
|
|
that they are loaded at a different address, the program may fail.
|
|
.TP
|
|
.B \fB\-\-change\-section\-address=\fIsection{=,+,-}val\fR, \fB\-\-adjust\-section\-vma=\fIsection{=,+,-}val
|
|
Set or changes the VMA and LMA addresses of the named \fIsection\fP.
|
|
If \fI=\fP is used, the section address is set to \fIval\fP.
|
|
Otherwise, \fIval\fP is added to or subtracted from the section
|
|
address. See the comments under \fB\-\-change\-addresses\fP, above. If
|
|
\fIsection\fP does not exist in the input file, a warning will be
|
|
issued, unless \fB\-\-no\-change\-warnings\fP is used.
|
|
.TP
|
|
.B \fB\-\-change\-section\-lma=\fIsection{=,+,-}val
|
|
Set or change the LMA address of the named \fIsection\fP. If \fI=\fP is
|
|
used, the section address is set to \fIval\fP. Otherwise, \fIval\fP
|
|
is added to or subtracted from the section address. See the comments
|
|
under \fB\-\-change\-addresses\fP, above. If \fIsection\fP does not exist
|
|
in the input file, a warning will be issued, unless
|
|
\fB\-\-no\-change\-warnings\fP is used.
|
|
.TP
|
|
.B \fB\-\-change\-section\-vma=\fIsection{=,+,-}val
|
|
Set or change the VMA address of the named \fIsection\fP. If \fI=\fP is
|
|
used, the section address is set to \fIval\fP. Otherwise, \fIval\fP
|
|
is added to or subtracted from the section address. See the comments
|
|
under \fB\-\-change\-addresses\fP, above. If \fIsection\fP does not exist
|
|
in the input file, a warning will be issued, unless
|
|
\fB\-\-no\-change\-warnings\fP is used.
|
|
.TP
|
|
.B \fB\-\-change\-warnings\fR, \fB\-\-adjust\-warnings
|
|
If \fB\-\-change\-section\-XXX\fP is used, and the named section does
|
|
not exist, issue a warning. This is the default.
|
|
.TP
|
|
.B \fB\-\-no\-change\-warnings\fR, \fB\-\-no\-adjust\-warnings
|
|
Do not issue a warning if \fB\-\-change\-section\-XXX\fP is used, even
|
|
if the named section does not exist.
|
|
.TP
|
|
.B \fB\-\-set\-section\-flags=\fIsection=flags
|
|
Set the flags for the named section. The \fIflags\fP argument is a
|
|
comma separated string of flag names. The recognized names are
|
|
\fIalloc\fP, \fIcontents\fP, \fIload\fP, \fInoload\fP, \fIreadonly\fP,
|
|
\fIcode\fP, \fIdata\fP, \fIrom\fP, \fIshare\fP, and \fIdebug\fP. Not
|
|
all flags are meaningful for all object file formats.
|
|
.TP
|
|
.B \fB\-\-add\-section=\fIsectionname=filename
|
|
Add a new section named \fIsectionname\fR while copying the file. The
|
|
contents of the new section are taken from the file \fIfilename\fR.
|
|
The size of the section will be the size of the file. This option
|
|
only works on file formats which can support sections with arbitrary
|
|
names.
|
|
.TP
|
|
.B \-\-change\-leading\-char
|
|
Some object file formats use special characters at the start of
|
|
symbols. The most common such character is underscore, which compilers
|
|
often add before every symbol. This option tells
|
|
.B 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.
|
|
.TP
|
|
.B \-\-remove\-leading\-char
|
|
If the first character of a global symbol is a special symbol leading
|
|
character used by the object file format, remove the character. The
|
|
most common symbol leading character is underscore. This option will
|
|
remove a leading underscore from all global symbols. This can be
|
|
useful if you want to link together objects of different file formats
|
|
with different conventions for symbol names. This is different from
|
|
\fB\-\-change\-leading\-char\fP because it always changes the symbol name
|
|
when appropriate, regardless of the object file format of the output
|
|
.TP
|
|
.B \-\-weaken
|
|
Change all global symbols in the file to be weak.
|
|
.TP
|
|
.B \-v\fR, \fB\-\-verbose
|
|
Verbose output: list all object files modified. In the case of
|
|
archives, "\fBobjcopy \-V\fR" lists all members of the archive.
|
|
.TP
|
|
.B \-V\fR, \fB\-\-version
|
|
Show the version number of
|
|
.B objcopy
|
|
and exit.
|
|
.TP
|
|
.B \-\-help
|
|
Show a summary of the options to
|
|
.B objcopy
|
|
and exit.
|
|
.SH "SEE ALSO"
|
|
.RB "`\|" binutils "\|'"
|
|
entry in
|
|
.B
|
|
info\c
|
|
\&;
|
|
.I
|
|
The GNU Binary Utilities\c
|
|
\&, Roland H. Pesch (June 1993).
|
|
|
|
.SH COPYING
|
|
Copyright (c) 1993, 94, 95, 96, 97, 98, 1999 Free Software Foundation, Inc.
|
|
.PP
|
|
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.
|
|
.PP
|
|
Permission is granted to copy and distribute modified versions of this
|
|
manual under the conditions for verbatim copying, provided that the
|
|
entire resulting derived work is distributed under the terms of a
|
|
permission notice identical to this one.
|
|
.PP
|
|
Permission is granted to copy and distribute translations of this
|
|
manual into another language, under the above conditions for modified
|
|
versions, except that this permission notice may be included in
|
|
translations approved by the Free Software Foundation instead of in
|
|
the original English.
|