binutils/objcopy.1

   1 .\" Copyright (c) 1991, 93, 94, 95, 96, 97, 1998 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\fR\ |\ \fB\-\-target=\fIbfdname\fR "\|]"
  19 .RB "[\|" \-I\ \fIbfdname\fR\ |\ \fB\-\-input\-target=\fIbfdname\fR "\|]"
  20 .RB "[\|" \-O\ \fIbfdname\fR\ |\ \fB\-\-output\-target=\fIbfdname\fR "\|]"
  21 .RB "[\|" \-R\ \fIsectionname\fR\ |\ \fB\-\-remove\-section=\fIsectionname\fR "\|]"
  22 .RB "[\|" \-S\fR\ |\ \fB\-\-strip\-all\fR "\|]"
  23 .RB "[\|" \-g\fR\ |\ \fB\-\-strip\-debug\fR "\|]"
  24 .RB "[\|" \-\-strip\-unneeded\fR "\|]"
  25 .RB "[\|" \-K\ \fIsymbolname\fR\ |\ \fB\-\-keep\-symbol=\fIsymbolname\fR "\|]"
  26 .RB "[\|" \-N\ \fIsymbolname\fR\ |\ \fB\-\-strip\-symbol=\fIsymbolname\fR "\|]"
  27 .RB "[\|" \-L\ \fIsymbolname\fR\ |\ \fB\-\-localize\-symbol=\fIsymbolname\fR "\|]"
  28 .RB "[\|" \-W\ \fIsymbolname\fR\ |\ \fB\-\-weaken\-symbol=\fIsymbolname\fR "\|]"
  29 .RB "[\|" \-x\fR\ |\ \fB\-\-discard\-all\fR "\|]"
  30 .RB "[\|" \-X\fR\ |\ \fB\-\-discard\-locals\fR "\|]"
  31 .RB "[\|" \-b\ \fIbyte\fR\ |\ \fB\-\-byte=\fIbyte\fR "\|]"
  32 .RB "[\|" \-i\ \fIinterleave\fR\ |\ \fB\-\-interleave=\fIinterleave\fR "\|]"
  33 .RB "[\|" \-p\fR\ |\ \fB\-\-preserve\-dates\fR "\|]"
  34 .RB "[\|" \-\-debugging "\|]"
  35 .RB "[\|" \-\-gap\-fill=\fIval\fR "\|]"
  36 .RB "[\|" \-\-pad\-to=\fIaddress\fR "\|]"
  37 .RB "[\|" \-\-set\-start=\fIval\fR "\|]"
  38 .RB "[\|" \-\-change\-start=\fIincr\fR "\|]"
  39 .RB "[\|" \-\-change\-addresses=\fIincr\fR "\|]"
  40 .RB "[\|" \-\-change\-section\-address=\fIsection{=,+,-}val\fR "\|]"
  41 .RB "[\|" \-\-change\-section\-lma=\fIsection{=,+,-}val\fR "\|]"
  42 .RB "[\|" \-\-change\-section\-vma=\fIsection{=,+,-}val\fR "\|]"
  43 .RB "[\|" \-\-change\-warnings\fR "\|]"
  44 .RB "[\|" \-\-no\-change\-warnings\fR "\|]"
  45 .RB "[\|" \-\-set\-section\-flags=\fIsection=flags\fR "\|]"
  46 .RB "[\|" \-\-add\-section=\fIsectionname=filename\fR "\|]"
  47 .RB "[\|" \-\-change\-leading\-char\fR "\|]"
  48 .RB "[\|" \-\-remove\-leading\-char\fR "\|]"
  49 .RB "[\|" \-\-weaken\fR "\|]"
  50 .RB "[\|" \-v\ |\ \-\-verbose\fR "\|]"
  51 .RB "[\|" \-V\ |\ \-\-version\fR "\|]"
  52 .RB "[\|" \-\-help\fR "\|]"
  53 .B infile
  54 .RB "[\|" outfile\fR "\|]"
  55 .SH DESCRIPTION
  56 The GNU
  57 .B objcopy
  58 utility copies the contents of an object file to another.
  59 .B objcopy
  60 uses the GNU BFD Library to read and write the object files.  It can
  61 write the destination object file in a format different from that of
  62 the source object file.  The exact behavior of
  63 .B objcopy
  64 is controlled by command-line options.
  65 .PP
  66 .B objcopy
  67 creates temporary files to do its translations and deletes them
  68 afterward.
  69 .B objcopy
  70 uses BFD to do all its translation work; it knows about all the
  71 formats BFD knows about, and thus is able to recognize most formats
  72 without being told explicitly.
  73 .PP
  74 .B objcopy
  75 can be used to generate S-records by using an output target of
  76 .B srec
  77 (e.g., use
  78 .B -O srec).
  79 .PP
  80 .B objcopy
  81 can be used to generate a raw binary file by using an output target of
  82 .B binary
  83 (e.g., use
  84 .B -O binary).
  85 When
  86 .B objcopy
  87 generates a raw binary file, it will essentially produce a memory dump
  88 of the contents of the input object file.  All symbols and relocation
  89 information will be discarded.  The memory dump will start at the
  90 virtual address of the lowest section copied into the output file.
  91 .PP
  92 When generating an S-record or a raw binary file, it may be helpful to
  93 use
  94 .B -S
  95 to remove sections containing debugging information.  In some cases
  96 .B -R
  97 will be useful to remove sections which contain information which is
  98 not needed by the binary file.
  99 .PP
 100 .I infile
 101 and
 102 .I outfile
 103 are the source and output files respectively.  If you do not specify
 104 .IR outfile ,
 105 .B objcopy
 106 creates a temporary file and destructively renames the result with the
 107 name of the input file.
 108
 109 .SH OPTIONS
 110 .TP
 111 .B \-I \fIbfdname\fR, \fB\-\-input\-target=\fIbfdname
 112 Consider the source file's object format to be
 113 .IR bfdname ,
 114 rather than attempting to deduce it.
 115 .TP
 116 .B \-O \fIbfdname\fR, \fB\-\-output\-target=\fIbfdname
 117 Write the output file using the object format
 118 .IR bfdname .
 119 .TP
 120 .B \-F \fIbfdname\fR, \fB\-\-target=\fIbfdname
 121 Use
 122 .I bfdname
 123 as the object format for both the input and the output file; i.e.
 124 simply transfer data from source to destination with no translation.
 125 .TP
 126 .B \-R \fIsectionname\fR, \fB\-\-remove-section=\fIsectionname
 127 Remove the named section from the file.  This option may be given more
 128 than once.  Note that using this option inappropriately may make the
 129 output file unusable.
 130 .TP
 131 .B \-S\fR, \fB\-\-strip\-all
 132 Do not copy relocation and symbol information from the source file.
 133 .TP
 134 .B \-g\fR, \fB\-\-strip\-debug
 135 Do not copy debugging symbols from the source file.
 136 .TP
 137 .B \-\-strip\-unneeded
 138 Strip all symbols that are not needed for relocation processing.
 139 .TP
 140 .B \-K \fIsymbolname\fR, \fB\-\-keep\-symbol=\fIsymbolname
 141 Copy only symbol \fIsymbolname\fP from the source file. This option
 142 may be given more than once.
 143 .TP
 144 .B \-N \fIsymbolname\fR, \fB\-\-strip\-symbol=\fIsymbolname
 145 Do not copy symbol \fIsymbolname\fP from the source file. This option
 146 may be given more than once.
 147 .TP
 148 .B \-L \fIsymbolname\fR, \fB\-\-localize\-symbol=\fIsymbolname
 149 Make symbol \fIsymbolname\fP local to the file, so that it is not
 150 visible externally.  This option may be given more than once.
 151 .TP
 152 .B \-W \fIsymbolname\fR, \fB\-\-weaken\-symbol=\fIsymbolname
 153 Make symbol \fIsymbolname\fP weak. This option may be given more than once.
 154 .TP
 155 .B \-x\fR, \fB \-\-discard\-all
 156 Do not copy non-global symbols from the source file.
 157 .TP
 158 .B \-X\fR, \fB\-\-discard\-locals
 159 Do not copy compiler-generated local symbols. (These usually start
 160 with "L" or ".").
 161 .TP
 162 .B \-b \fIbyte\fR, \fB\-\-byte=\fIbyte
 163 Keep only every \fIbyte\fPth byte of the input file (header data is
 164 not affected).  \fIbyte\fP can be in the range from 0 to the
 165 interleave-1.  This option is useful for creating files to program
 166 ROMs.  It is typically used with an srec output target.
 167 .TP
 168 .B \-i \fIinterleave\fR, \fB\-\-interleave=\fIinterleave
 169 Only copy one out of every \fIinterleave\fP bytes.  Which one to copy is
 170 selected by the \fB\-b\fP or \fB\-\-byte\fP option.  The default is 4.
 171 The interleave is ignored if neither \fB\-b\fP nor \fB\-\-byte\fP is given.
 172 .TP
 173 .B \-p\fR, \fB\-\-preserve\-dates
 174 Set the access and modification dates of the output file to be the same
 175 as those of the input file.
 176 .TP
 177 .B \-\-debugging
 178 Convert debugging information, if possible.  This is not the default
 179 because only certain debugging formats are supported, and the
 180 conversion process can be time consuming.
 181 .TP
 182 .B \-\-gap\-fill=\fIval
 183 Fill gaps between sections with \fIval\fP.  This operation applies to
 184 the \fIload address\fP (LMA) of the sections.  It is done by increasing
 185 the size of the section with the lower address, and filling in the extra
 186 space created with \fIval\fP.
 187 .TP
 188 .B \-\-pad\-to=\fIaddress
 189 Pad the output file up to the load address \fIaddress\fP.  This is
 190 done by increasing the size of the last section.  The extra space is
 191 filled in with the value specified by \fB\-\-gap\-fill\fP (default
 192 zero).
 193 .TP
 194 .B \fB\-\-set\-start=\fIval
 195 Set the start address of the new file to \fIval\fP.  Not all object
 196 file formats support setting the start address.
 197 .TP
 198 .B \fB\-\-change\-start=\fIincr\fR, \fB\-\-adjust\-start=\fIincr
 199 Changes the start address by adding \fIincr\fP.  Not all object file
 200 formats support setting the start address.
 201 .TP
 202 .B \fB\-\-change\-addresses=\fIincr\fR, \fB\-\-adjust\-vma=\fIincr
 203 Changes the address of all sections, as well as the start address, by
 204 adding \fIincr\fP.  Some object file formats do not permit section
 205 addresses to be changed arbitrarily.  Note that this does not relocate
 206 the sections; if the program expects sections to be loaded at a
 207 certain address, and this option is used to change the sections such
 208 that they are loaded at a different address, the program may fail.
 209 .TP
 210 .B \fB\-\-change\-section\-address=\fIsection{=,+,-}val\fR, \fB\-\-adjust\-section\-vma=\fIsection{=,+,-}val
 211 Set or changes the VMA and LMA addresses of the named \fIsection\fP.
 212 If \fI=\fP is used, the section address is set to \fIval\fP.
 213 Otherwise, \fIval\fP is added to or subtracted from the section
 214 address.  See the comments under \fB\-\-change\-addresses\fP, above.  If
 215 \fIsection\fP does not exist in the input file, a warning will be
 216 issued, unless \fB\-\-no\-change\-warnings\fP is used.
 217 .TP
 218 .B \fB\-\-change\-section\-lma=\fIsection{=,+,-}val
 219 Set or change the LMA address of the named \fIsection\fP.  If \fI=\fP is
 220 used, the section address is set to \fIval\fP.  Otherwise, \fIval\fP
 221 is added to or subtracted from the section address.  See the comments
 222 under \fB\-\-change\-addresses\fP, above.  If \fIsection\fP does not exist
 223 in the input file, a warning will be issued, unless
 224 \fB\-\-no\-change\-warnings\fP is used.
 225 .TP
 226 .B \fB\-\-change\-section\-vma=\fIsection{=,+,-}val
 227 Set or change the VMA address of the named \fIsection\fP.  If \fI=\fP is
 228 used, the section address is set to \fIval\fP.  Otherwise, \fIval\fP
 229 is added to or subtracted from the section address.  See the comments
 230 under \fB\-\-change\-addresses\fP, above.  If \fIsection\fP does not exist
 231 in the input file, a warning will be issued, unless
 232 \fB\-\-no\-change\-warnings\fP is used.
 233 .TP
 234 .B \fB\-\-change\-warnings\fR, \fB\-\-adjust\-warnings
 235 If \fB\-\-change\-section\-XXX\fP is used, and the named section does
 236 not exist, issue a warning.  This is the default.
 237 .TP
 238 .B \fB\-\-no\-change\-warnings\fR, \fB\-\-no\-adjust\-warnings
 239 Do not issue a warning if \fB\-\-change\-section\-XXX\fP is used, even
 240 if the named section does not exist.
 241 .TP
 242 .B \fB\-\-set\-section\-flags=\fIsection=flags
 243 Set the flags for the named section.  The \fIflags\fP argument is a
 244 comma separated string of flag names.  The recognized names are
 245 \fIalloc\fP, \fIload\fP, \fIreadonly\fP, \fIcode\fP, \fIdata\fP, and
 246 \fIrom\fP.  Not all flags are meaningful for all object file
 247 formats.
 248 .TP
 249 .B \fB\-\-add\-section=\fIsectionname=filename
 250 Add a new section named \fIsectionname\fR while copying the file.  The
 251 contents of the new section are taken from the file \fIfilename\fR.
 252 The size of the section will be the size of the file.  This option
 253 only works on file formats which can support sections with arbitrary
 254 names.
 255 .TP
 256 .B \-\-change\-leading\-char
 257 Some object file formats use special characters at the start of
 258 symbols.  The most common such character is underscore, which compilers
 259 often add before every symbol.  This option tells
 260 .B objcopy
 261 to change the leading character of every symbol when it converts
 262 between object file formats.  If the object file formats use the same
 263 leading character, this option has no effect.  Otherwise, it will add
 264 a character, or remove a character, or change a character, as
 265 appropriate.
 266 .TP
 267 .B \-\-remove\-leading\-char
 268 If the first character of a global symbol is a special symbol leading
 269 character used by the object file format, remove the character.  The
 270 most common symbol leading character is underscore.  This option will
 271 remove a leading underscore from all global symbols.  This can be
 272 useful if you want to link together objects of different file formats
 273 with different conventions for symbol names.  This is different from
 274 \fB\-\-change\-leading\-char\fP because it always changes the symbol name
 275 when appropriate, regardless of the object file format of the output
 276 .TP
 277 .B \-\-weaken
 278 Change all global symbols in the file to be weak.
 279 .TP
 280 .B \-v\fR, \fB\-\-verbose
 281 Verbose output: list all object files modified.  In the case of
 282 archives, "\fBobjcopy \-V\fR" lists all members of the archive.
 283 .TP
 284 .B \-V\fR, \fB\-\-version
 285 Show the version number of
 286 .B objcopy
 287 and exit.
 288 .TP
 289 .B \-\-help
 290 Show a summary of the options to
 291 .B objcopy
 292 and exit.
 293 .SH "SEE ALSO"
 294 .RB "`\|" binutils "\|'"
 295 entry in
 296 .B
 297 info\c
 298 \&;
 299 .I
 300 The GNU Binary Utilities\c
 301 \&, Roland H. Pesch (June 1993).
 302
 303 .SH COPYING
 304 Copyright (c) 1993, 94, 95, 96, 1997 Free Software Foundation, Inc.
 305 .PP
 306 Permission is granted to make and distribute verbatim copies of
 307 this manual provided the copyright notice and this permission notice
 308 are preserved on all copies.
 309 .PP
 310 Permission is granted to copy and distribute modified versions of this
 311 manual under the conditions for verbatim copying, provided that the
 312 entire resulting derived work is distributed under the terms of a
 313 permission notice identical to this one.
 314 .PP
 315 Permission is granted to copy and distribute translations of this
 316 manual into another language, under the above conditions for modified
 317 versions, except that this permission notice may be included in
 318 translations approved by the Free Software Foundation instead of in
 319 the original English.