19990502 sourceware importbinu_ss_19990502

1 files changed, 319 insertions, 0 deletions

diff --git a/binutils/objcopy.1 b/binutils/objcopy.1
new file mode 100644
index 00000000000..aee77601498
--- /dev/null
+++ b/binutils/objcopy.1
@@ -0,0 +1,319 @@
+.\" Copyright (c) 1991, 93, 94, 95, 96, 97, 1998 Free Software Foundation
+.\" See section COPYING for conditions for redistribution
+.TH objcopy 1 "October 1994" "cygnus support" "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 "[\|" \-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 \-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, \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 \-\-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, 1997 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.