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