.\" Copyright (c) 1991 Free Software Foundation
.\" See section COPYING for conditions for redistribution
-.TH objcopy 1 "June 1993" "cygnus support" "GNU Development Tools"
+.TH objcopy 1 "October 1994" "cygnus support" "GNU Development Tools"
.de BP
.sp
.ti \-.2i
..
.SH NAME
-objcopy\(em\© and translate object files
+objcopy \- copy and translate object files
.SH SYNOPSIS
.hy 0
.na
.TP
.B objcopy
-.RB "[\|" \-F\ \fIformat\fB\ |\ \-\-format=\fIformat\fR "\|]"
-.RB "[\|" \-I\ \fIformat\fB\ |\ \-\-input\-format=\fIformat\fR "\|]"
-.RB "[\|" \-O\ \fIformat\fB\ |\ \-\-output\-format=\fIformat\fR "\|]"
-.RB "[\|" \-S\ |\ \-\-strip\-all\fR "\|]"
-.RB "[\|" \-g\ |\ \-\-strip\-debug\fR "\|]"
-.RB "[\|" \-x\ |\ \-\-discard\-all\fR "\|]"
-.RB "[\|" \-X\ |\ \-\-discard\-locals\fR "\|]"
+.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 "[\|" \-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 "[\|" \-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 "[\|" \-\-gap\-fill=\fIval\fR "\|]"
+.RB "[\|" \-\-pad\-to=\fIaddress\fR "\|]"
+.RB "[\|" \-\-set\-start=\fIval\fR "\|]"
+.RB "[\|" \-\-adjust\-start=\fIincr\fR "\|]"
+.RB "[\|" \-\-adjust\-vma=\fIincr\fR "\|]"
+.RB "[\|" \-\-adjust\-section\-vma=\fIsection{=,+,-}val\fR "\|]"
+.RB "[\|" \-\-adjust\-warnings\fR "\|]"
+.RB "[\|" \-\-no\-adjust\-warnings\fR "\|]"
+.RB "[\|" \-\-set\-section\-flags=\fIsection=flags\fR "\|]"
+.RB "[\|" \-\-add\-section=\fIsectionname=filename\fR "\|]"
.RB "[\|" \-v\ |\ \-\-verbose\fR "\|]"
.RB "[\|" \-V\ |\ \-\-version\fR "\|]"
.RB "[\|" \-\-help\fR "\|]"
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
.SH OPTIONS
.TP
-.B \-I \fIformat\fR, \fB\-\-input\-format=\fIformat
+.B \-I \fIbfdname\fR, \fB\-\-input\-target=\fIbfdname
Consider the source file's object format to be
-.IR format ,
+.IR bfdname ,
rather than attempting to deduce it.
.TP
-.B \-O \fIformat\fR, \fB\-\-output\-format=\fIformat
+.B \-O \fIbfdname\fR, \fB\-\-output\-target=\fIbfdname
Write the output file using the object format
-.IR format .
+.IR bfdname .
.TP
-.B \-F \fIformat\fR, \fB\-\-format=\fIformat
+.B \-F \fIbfdname\fR, \fB\-\-target=\fIbfdname
Use
-.I format
+.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 \-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, and may be combined with strip options
+other than \fB\-K\fR.
+.TP
.B \-x\fR, \fB \-\-discard\-all
Do not copy non-global symbols from the source file.
.TP
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 \-\-gap\-fill=\fIval
+Fill gaps between sections with \fIval\fP. This 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 virtual 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\-\-adjust\-start=\fIincr
+Adjust the start address by adding \fIincr\fP. Not all object file
+formats support setting the start address.
+.TP
+.B \fB\-\-adjust\-vma=\fIincr
+Adjust 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\-\-adjust\-section\-vma=\fIsection{=,+,-}val
+Set or adjust the 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\-\-adjust\-vma\fP, above. If \fIsection\fP does not exist
+in the input file, a warning will be issued, unless
+\fB\-\-no\-adjust\-warnings\fP is used.
+.TP
+.B \fB\-\-adjust\-warnings
+If \fB\-\-adjust\-section\-vma\fP is used, and the named section does
+not exist, issue a warning. This is the default.
+.TP
+.B \fB\-\-no\-adjust\-warnings
+Do not issue a warning if \fB\-\-adjust\-section\-vma\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, \fIload\fP, \fIreadonly\fP, \fIcode\fP, \fIdata\fP, and
+\fIrom\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 \-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.
\&, Roland H. Pesch (June 1993).
.SH COPYING
-Copyright (c) 1993 Free Software Foundation, Inc.
+Copyright (c) 1993,1994 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
projects / binutils.git / blobdiff