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