binutils/objcopy.1

   1 .\" Copyright (c) 1991 Free Software Foundation
   2 .\" See section COPYING for conditions for redistribution
   3 .TH objcopy 1 "October 1994" "cygnus support" "GNU Development Tools"
   4 .de BP
   5 .sp
   6 .ti \-.2i
   7 \(**
   8 ..
   9
  10 .SH NAME
  11 objcopy \- copy and translate object files
  12
  13 .SH SYNOPSIS
  14 .hy 0
  15 .na
  16 .TP
  17 .B objcopy
  18 .RB "[\|" \-F\ \fIbfdname\fB\ |\ \-\-target=\fIbfdname\fR "\|]"
  19 .RB "[\|" \-I\ \fIbfdname\fB\ |\ \-\-input\-target=\fIbfdname\fR "\|]"
  20 .RB "[\|" \-O\ \fIbfdname\fB\ |\ \-\-output\-target=\fIbfdname\fR "\|]"
  21 .RB "[\|" \-R\ \fIsectionname\fB\ |\ \-\-remove\-section=\fIsectionname\fR "\|]"
  22 .RB "[\|" \-S\ |\ \-\-strip\-all\fR "\|]"
  23 .RB "[\|" \-g\ |\ \-\-strip\-debug\fR "\|]"
  24 .RB "[\|" \-x\ |\ \-\-discard\-all\fR "\|]"
  25 .RB "[\|" \-X\ |\ \-\-discard\-locals\fR "\|]"
  26 .RB "[\|" \-b\ \fIbyte\fP |\ \-\-byte=\fIbyte\fP "\|]"
  27 .RB "[\|" \-i\ \fIinterleave\fP |\ \-\-interleave=\fIinterleave\fP "\|]"
  28 .RB "[\|" \-\-set\-start=\fIval\fP "\|]"
  29 .RB "[\|" \-\-adjust\-start=\fIincr\fP "\|]"
  30 .RB "[\|" \-\-adjust\-vma=\fIincr\fP "\|]"
  31 .RB "[\|" \-\-adjust\-section\-vma=\fIsection{=,+,-}val\fP "\|]"
  32 .RB "[\|" \-\-adjust\-warnings "\|]"
  33 .RB "[\|" \-\-no\-adjust\-warnings "\|]"
  34 .RB "[\|" \-v\ |\ \-\-verbose\fR "\|]"
  35 .RB "[\|" \-V\ |\ \-\-version\fR "\|]"
  36 .RB "[\|" \-\-help\fR "\|]"
  37 .B infile
  38 .RB "[\|" outfile\fR "\|]"
  39 .SH DESCRIPTION
  40 The GNU
  41 .B objcopy
  42 utility copies the contents of an object file to another.
  43 .B objcopy
  44 uses the GNU BFD Library to read and write the object files.  It can
  45 write the destination object file in a format different from that of
  46 the source object file.  The exact behavior of
  47 .B objcopy
  48 is controlled by command-line options.
  49 .PP
  50 .B objcopy
  51 creates temporary files to do its translations and deletes them
  52 afterward.
  53 .B objcopy
  54 uses BFD to do all its translation work; it knows about all the
  55 formats BFD knows about, and thus is able to recognize most formats
  56 without being told explicitly.
  57 .PP
  58 .I infile
  59 and
  60 .I outfile
  61 are the source and output files respectively.  If you do not specify
  62 .IR outfile ,
  63 .B objcopy
  64 creates a temporary file and destructively renames the result with the
  65 name of the input file.
  66
  67 .SH OPTIONS
  68 .TP
  69 .B \-I \fIbfdname\fR, \fB\-\-input\-target=\fIbfdname
  70 Consider the source file's object format to be
  71 .IR bfdname ,
  72 rather than attempting to deduce it.
  73 .TP
  74 .B \-O \fIbfdname\fR, \fB\-\-output\-target=\fIbfdname
  75 Write the output file using the object format
  76 .IR bfdname .
  77 .TP
  78 .B \-F \fIbfdname\fR, \fB\-\-target=\fIbfdname
  79 Use
  80 .I bfdname
  81 as the object format for both the input and the output file; i.e.
  82 simply transfer data from source to destination with no translation.
  83 .TP
  84 .B \-R \fIsectionname\fR, \fB\-\-remove-section=\fIsectionname
  85 Remove the named section from the file.  This option may be given more
  86 than once.  Note that using this option inappropriately may make the
  87 output file unusable.
  88 .TP
  89 .B \-S\fR, \fB\-\-strip\-all
  90 Do not copy relocation and symbol information from the source file.
  91 .TP
  92 .B \-g\fR, \fB\-\-strip\-debug
  93 Do not copy debugging symbols from the source file.
  94 .TP
  95 .B \-x\fR, \fB \-\-discard\-all
  96 Do not copy non-global symbols from the source file.
  97 .TP
  98 .B \-X\fR, \fB\-\-discard\-locals
  99 Do not copy compiler-generated local symbols. (These usually start
 100 with "L" or ".").
 101 .TP
 102 .B \-b \fIbyte\fR, \fB\-\-byte=\fIbyte
 103 Keep only every \fIbyte\fPth byte of the input file (header data is
 104 not affected).  \fIbyte\fP can be in the range from 0 to the
 105 interleave-1.  This option is useful for creating files to program
 106 ROMs.  It is typically used with an srec output target.
 107 .TP
 108 .B \-i \fIinterleave\fR, \fB\-\-interleave=\fIinterleave
 109 Only copy one out of every \fIinterleave\fP bytes.  Which one to copy is
 110 selected by the \fB\-b\fP or \fB\-\-byte\fP option.  The default is 4.
 111 The interleave is ignored if neither \fB\-b\fP nor \fB\-\-byte\fP is given.
 112 .TP
 113 .B \fB\-\-set\-start=\fIval
 114 Set the start address of the new file to \fIval\fP.  Not all object
 115 file formats support setting the start address.
 116 .TP
 117 .B \fB\-\-adjust\-start=\fIincr
 118 Adjust the start address by adding \fIincr\fP.  Not all object file
 119 formats support setting the start address.
 120 .TP
 121 .B \fB\-\-adjust\-vma=\fIincr
 122 Adjust the address of all sections, as well as the start address, by
 123 adding \fIincr\fP.  Some object file formats do not permit section
 124 addresses to be changed arbitrarily.  Note that this does not relocate
 125 the sections; if the program expects sections to be loaded at a
 126 certain address, and this option is used to change the sections such
 127 that they are loaded at a different address, the program may fail.
 128 .TP
 129 .B \fB\-\-adjust\-section\-vma=\fIsection{=,+,-}val
 130 Set or adjust the address of the named \fIsection\fP.  If \fI=\fP is
 131 used, the section address is set to \fIval\fP.  Otherwise, \fIval\fP
 132 is added to or subtracted from the section address.  See the comments
 133 under \fB\-\-adjust\-vma\fP, above.  If \fIsection\fP does not exist
 134 in the input file, a warning will be issued, unless
 135 \fB\-\-no\-adjust\-warnings\fP is used.
 136 .TP
 137 .B \fB\-\-adjust\-warnings
 138 If \fB\-\-adjust\-section\-vma\fP is used, and the named section does
 139 not exist, issue a warning.  This is the default.
 140 .TP
 141 .B \fB\-\-no\-adjust\-warnings
 142 Do not issue a warning if \fB\-\-adjust\-section\-vma\fP is used, even
 143 if the named section does not exist.
 144 .TP
 145 .B \-v\fR, \fB\-\-verbose
 146 Verbose output: list all object files modified.  In the case of
 147 archives, "\fBobjcopy \-V\fR" lists all members of the archive.
 148 .TP
 149 .B \-V\fR, \fB\-\-version
 150 Show the version number of
 151 .B objcopy
 152 and exit.
 153 .TP
 154 .B \-\-help
 155 Show a summary of the options to
 156 .B objcopy
 157 and exit.
 158 .SH "SEE ALSO"
 159 .RB "`\|" binutils "\|'"
 160 entry in
 161 .B
 162 info\c
 163 \&;
 164 .I
 165 The GNU Binary Utilities\c
 166 \&, Roland H. Pesch (June 1993).
 167
 168 .SH COPYING
 169 Copyright (c) 1993,1994 Free Software Foundation, Inc.
 170 .PP
 171 Permission is granted to make and distribute verbatim copies of
 172 this manual provided the copyright notice and this permission notice
 173 are preserved on all copies.
 174 .PP
 175 Permission is granted to copy and distribute modified versions of this
 176 manual under the conditions for verbatim copying, provided that the
 177 entire resulting derived work is distributed under the terms of a
 178 permission notice identical to this one.
 179 .PP
 180 Permission is granted to copy and distribute translations of this
 181 manual into another language, under the above conditions for modified
 182 versions, except that this permission notice may be included in
 183 translations approved by the Free Software Foundation instead of in
 184 the original English.