binutils/objcopy.1

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