binutils/objcopy.1

   1 .\" Automatically generated by Pod::Man version 1.02
   2 .\" Wed May 30 12:24:28 2001
   3 .\"
   4 .\" Standard preamble:
   5 .\" ======================================================================
   6 .de Sh \" Subsection heading
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp \" Vertical space (when we can't use .PP)
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip \" List item
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb \" Begin verbatim text
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve \" End verbatim text
  30 .ft R
  31
  32 .fi
  33 ..
  34 .\" Set up some character translations and predefined strings.  \*(-- will
  35 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  36 .\" double quote, and \*(R" will give a right double quote.  | will give a
  37 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  38 .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  39 .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  40 .tr \(*W-|\(bv\*(Tr
  41 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  42 .ie n \{\
  43 .    ds -- \(*W-
  44 .    ds PI pi
  45 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  46 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  47 .    ds L" ""
  48 .    ds R" ""
  49 .    ds C` `
  50 .    ds C' '
  51 'br\}
  52 .el\{\
  53 .    ds -- \|\(em\|
  54 .    ds PI \(*p
  55 .    ds L" ``
  56 .    ds R" ''
  57 'br\}
  58 .\"
  59 .\" If the F register is turned on, we'll generate index entries on stderr
  60 .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  61 .\" index entries marked with X<> in POD.  Of course, you'll have to process
  62 .\" the output yourself in some meaningful fashion.
  63 .if \nF \{\
  64 .    de IX
  65 .    tm Index:\\$1\t\\n%\t"\\$2"
  66 .    .
  67 .    nr % 0
  68 .    rr F
  69 .\}
  70 .\"
  71 .\" For nroff, turn off justification.  Always turn off hyphenation; it
  72 .\" makes way too many mistakes in technical documents.
  73 .hy 0
  74 .\"
  75 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  76 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  77 .bd B 3
  78 .    \" fudge factors for nroff and troff
  79 .if n \{\
  80 .    ds #H 0
  81 .    ds #V .8m
  82 .    ds #F .3m
  83 .    ds #[ \f1
  84 .    ds #] \fP
  85 .\}
  86 .if t \{\
  87 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  88 .    ds #V .6m
  89 .    ds #F 0
  90 .    ds #[ \&
  91 .    ds #] \&
  92 .\}
  93 .    \" simple accents for nroff and troff
  94 .if n \{\
  95 .    ds ' \&
  96 .    ds ` \&
  97 .    ds ^ \&
  98 .    ds , \&
  99 .    ds ~ ~
 100 .    ds /
 101 .\}
 102 .if t \{\
 103 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 104 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 105 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 106 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 107 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 108 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 109 .\}
 110 .    \" troff and (daisy-wheel) nroff accents
 111 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 112 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 113 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 114 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 115 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 116 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 117 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 118 .ds ae a\h'-(\w'a'u*4/10)'e
 119 .ds Ae A\h'-(\w'A'u*4/10)'E
 120 .    \" corrections for vroff
 121 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 122 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 123 .    \" for low resolution devices (crt and lpr)
 124 .if \n(.H>23 .if \n(.V>19 \
 125 \{\
 126 .    ds : e
 127 .    ds 8 ss
 128 .    ds o a
 129 .    ds d- d\h'-1'\(ga
 130 .    ds D- D\h'-1'\(hy
 131 .    ds th \o'bp'
 132 .    ds Th \o'LP'
 133 .    ds ae ae
 134 .    ds Ae AE
 135 .\}
 136 .rm #[ #] #H #V #F C
 137 .\" ======================================================================
 138 .\"
 139 .IX Title "OBJCOPY.1 1"
 140 .TH OBJCOPY.1 1 "binutils-2.11.90" "2001-05-30" "GNU"
 141 .UC
 142 .SH "NAME"
 143 objcopy \- copy and translate object files
 144 .SH "SYNOPSIS"
 145 .IX Header "SYNOPSIS"
 146 objcopy [ \-F \fIbfdname\fR | \-\-target=\fIbfdname\fR ]
 147         [ \-I \fIbfdname\fR | \-\-input-target=\fIbfdname\fR ]
 148         [ \-O \fIbfdname\fR | \-\-output-target=\fIbfdname\fR ]
 149         [ \-B \fIbfdarch\fR | \-\-binary-architecture=\fIbfdarch\fR ]
 150         [ \-S | \-\-strip-all ]  [ \-g | \-\-strip-debug ]
 151         [ \-K \fIsymbolname\fR | \-\-keep-symbol=\fIsymbolname\fR ]
 152         [ \-N \fIsymbolname\fR | \-\-strip-symbol=\fIsymbolname\fR ]
 153         [ \-G \fIsymbolname\fR | \-\-keep-global-symbol=\fIsymbolname\fR]
 154         [ \-L \fIsymbolname\fR | \-\-localize-symbol=\fIsymbolname\fR ]
 155         [ \-W \fIsymbolname\fR | \-\-weaken-symbol=\fIsymbolname\fR ]
 156         [ \-x | \-\-discard-all ]  [ \-X | \-\-discard-locals ]
 157         [ \-b \fIbyte\fR | \-\-byte=\fIbyte\fR ]
 158         [ \-i \fIinterleave\fR | \-\-interleave=\fIinterleave\fR ]
 159         [ \-j \fIsectionname\fR | \-\-only-section=\fIsectionname\fR ]
 160         [ \-R \fIsectionname\fR | \-\-remove-section=\fIsectionname\fR ]
 161         [ \-p | \-\-preserve-dates ] [ \-\-debugging ]
 162         [ \-\-gap-fill=\fIval\fR ] [ \-\-pad-to=\fIaddress\fR ]
 163         [ \-\-set-start=\fIval\fR ] [ \-\-adjust-start=\fIincr\fR ]
 164         [ \-\-change-addresses=\fIincr\fR ]
 165         [ \-\-change-section-address \fIsection\fR{=,+,\-}\fIval\fR ]
 166         [ \-\-change-section-lma \fIsection\fR{=,+,\-}\fIval\fR ]
 167         [ \-\-change-section-vma \fIsection\fR{=,+,\-}\fIval\fR ]
 168         [ \-\-change-warnings ] [ \-\-no-change-warnings ]
 169         [ \-\-set-section-flags \fIsection\fR=\fIflags\fR ]
 170         [ \-\-add-section \fIsectionname\fR=\fIfilename\fR ]
 171         [ \-\-change-leading-char ] [ \-\-remove-leading-char ]
 172         [ \-\-srec-len=\fIival\fR ] [ \-\-srec-forceS3 ]
 173         [ \-\-redefine-sym \fIold\fR=\fInew\fR ] [ \-\-weaken ]
 174         [ \-\-keep-symbols=\fIfilename\fR ]
 175         [ \-\-strip-symbols=\fIfilename\fR ]
 176         [ \-\-keep-global-symbols=\fIfilename\fR ]
 177         [ \-\-localize-symbols=\fIfilename\fR ]
 178         [ \-\-weaken-symbols=\fIfilename\fR ]
 179         [ \-v | \-\-verbose ] [ \-V | \-\-version ]  [ \-\-help ]
 180         \fIinfile\fR [\fIoutfile\fR]
 181 .SH "DESCRIPTION"
 182 .IX Header "DESCRIPTION"
 183 The \s-1GNU\s0 \f(CW\*(C`objcopy\*(C'\fR utility copies the contents of an object
 184 file to another.  \f(CW\*(C`objcopy\*(C'\fR uses the \s-1GNU\s0 \s-1BFD\s0 Library to
 185 read and write the object files.  It can write the destination object
 186 file in a format different from that of the source object file.  The
 187 exact behavior of \f(CW\*(C`objcopy\*(C'\fR is controlled by command-line options.
 188 Note that \f(CW\*(C`objcopy\*(C'\fR should be able to copy a fully linked file
 189 between any two formats. However, copying a relocatable object file
 190 between any two formats may not work as expected.
 191 .PP
 192 \&\f(CW\*(C`objcopy\*(C'\fR creates temporary files to do its translations and
 193 deletes them afterward.  \f(CW\*(C`objcopy\*(C'\fR uses \s-1BFD\s0 to do all its
 194 translation work; it has access to all the formats described in \s-1BFD\s0
 195 and thus is able to recognize most formats without being told
 196 explicitly.
 197 .PP
 198 \&\f(CW\*(C`objcopy\*(C'\fR can be used to generate S-records by using an output
 199 target of \fBsrec\fR (e.g., use \fB\-O srec\fR).
 200 .PP
 201 \&\f(CW\*(C`objcopy\*(C'\fR can be used to generate a raw binary file by using an
 202 output target of \fBbinary\fR (e.g., use \fB\-O binary\fR).  When
 203 \&\f(CW\*(C`objcopy\*(C'\fR generates a raw binary file, it will essentially produce
 204 a memory dump of the contents of the input object file.  All symbols and
 205 relocation information will be discarded.  The memory dump will start at
 206 the load address of the lowest section copied into the output file.
 207 .PP
 208 When generating an S-record or a raw binary file, it may be helpful to
 209 use \fB\-S\fR to remove sections containing debugging information.  In
 210 some cases \fB\-R\fR will be useful to remove sections which contain
 211 information that is not needed by the binary file.
 212 .PP
 213 Note \- \f(CW\*(C`objcopy\*(C'\fR is not able to change the endianness of its input
 214 files.  If the input format has an endianness, (some formats do not),
 215 \&\f(CW\*(C`objcopy\*(C'\fR can only copy the inputs into file formats that have the
 216 same endianness or which have no endianness (eg \fBsrec\fR).
 217 .SH "OPTIONS"
 218 .IX Header "OPTIONS"
 219 .Ip "\f(CW\*(C`\f(CIinfile\f(CW\*(C'\fR" 4
 220 .IX Item "infile"
 221 .Ip "\f(CW\*(C`\f(CIoutfile\f(CW\*(C'\fR" 4
 222 .IX Item "outfile"
 223 The input and output files, respectively.
 224 If you do not specify \fIoutfile\fR, \f(CW\*(C`objcopy\*(C'\fR creates a
 225 temporary file and destructively renames the result with
 226 the name of \fIinfile\fR.
 227 .Ip "\f(CW\*(C`\-I \f(CIbfdname\f(CW    \*(C'\fR" 4
 228 .IX Item "-I bfdname    "
 229 .Ip "\f(CW\*(C`\-\-input\-target=\f(CIbfdname\f(CW\*(C'\fR" 4
 230 .IX Item "--input-target=bfdname"
 231 Consider the source file's object format to be \fIbfdname\fR, rather than
 232 attempting to deduce it.
 233 .Ip "\f(CW\*(C`\-O \f(CIbfdname\f(CW\*(C'\fR" 4
 234 .IX Item "-O bfdname"
 235 .Ip "\f(CW\*(C`\-\-output\-target=\f(CIbfdname\f(CW\*(C'\fR" 4
 236 .IX Item "--output-target=bfdname"
 237 Write the output file using the object format \fIbfdname\fR.
 238 .Ip "\f(CW\*(C`\-F \f(CIbfdname\f(CW\*(C'\fR" 4
 239 .IX Item "-F bfdname"
 240 .Ip "\f(CW\*(C`\-\-target=\f(CIbfdname\f(CW\*(C'\fR" 4
 241 .IX Item "--target=bfdname"
 242 Use \fIbfdname\fR as the object format for both the input and the output
 243 file; i.e., simply transfer data from source to destination with no
 244 translation.
 245 .Ip "\f(CW\*(C`\-B \f(CIbfdarch\f(CW\*(C'\fR" 4
 246 .IX Item "-B bfdarch"
 247 .Ip "\f(CW\*(C`\-\-binary\-architecture=\f(CIbfdarch\f(CW\*(C'\fR" 4
 248 .IX Item "--binary-architecture=bfdarch"
 249 Useful when transforming a raw binary input file into an object file.
 250 In this case the output architecture can be set to \fIbfdarch\fR. This
 251 option will be ignored if the input file has a known \fIbfdarch\fR. You
 252 can access this binary data inside a program by referencing the special
 253 symbols that are created by the conversion process.  These symbols are
 254 called _binary_\fIobjfile\fR_start, _binary_\fIobjfile\fR_end and
 255 _binary_\fIobjfile\fR_size.  e.g. you can transform a picture file into
 256 an object file and then access it in your code using these symbols.
 257 .Ip "\f(CW\*(C`\-j \f(CIsectionname\f(CW\*(C'\fR" 4
 258 .IX Item "-j sectionname"
 259 .Ip "\f(CW\*(C`\-\-only\-section=\f(CIsectionname\f(CW\*(C'\fR" 4
 260 .IX Item "--only-section=sectionname"
 261 Copy only the named section from the input file to the output file.
 262 This option may be given more than once.  Note that using this option
 263 inappropriately may make the output file unusable.
 264 .Ip "\f(CW\*(C`\-R \f(CIsectionname\f(CW\*(C'\fR" 4
 265 .IX Item "-R sectionname"
 266 .Ip "\f(CW\*(C`\-\-remove\-section=\f(CIsectionname\f(CW\*(C'\fR" 4
 267 .IX Item "--remove-section=sectionname"
 268 Remove any section named \fIsectionname\fR from the output file.  This
 269 option may be given more than once.  Note that using this option
 270 inappropriately may make the output file unusable.
 271 .Ip "\f(CW\*(C`\-S\*(C'\fR" 4
 272 .IX Item "-S"
 273 .Ip "\f(CW\*(C`\-\-strip\-all\*(C'\fR" 4
 274 .IX Item "--strip-all"
 275 Do not copy relocation and symbol information from the source file.
 276 .Ip "\f(CW\*(C`\-g\*(C'\fR" 4
 277 .IX Item "-g"
 278 .Ip "\f(CW\*(C`\-\-strip\-debug\*(C'\fR" 4
 279 .IX Item "--strip-debug"
 280 Do not copy debugging symbols from the source file.
 281 .Ip "\f(CW\*(C`\-\-strip\-unneeded\*(C'\fR" 4
 282 .IX Item "--strip-unneeded"
 283 Strip all symbols that are not needed for relocation processing.
 284 .Ip "\f(CW\*(C`\-K \f(CIsymbolname\f(CW\*(C'\fR" 4
 285 .IX Item "-K symbolname"
 286 .Ip "\f(CW\*(C`\-\-keep\-symbol=\f(CIsymbolname\f(CW\*(C'\fR" 4
 287 .IX Item "--keep-symbol=symbolname"
 288 Copy only symbol \fIsymbolname\fR from the source file.  This option may
 289 be given more than once.
 290 .Ip "\f(CW\*(C`\-N \f(CIsymbolname\f(CW\*(C'\fR" 4
 291 .IX Item "-N symbolname"
 292 .Ip "\f(CW\*(C`\-\-strip\-symbol=\f(CIsymbolname\f(CW\*(C'\fR" 4
 293 .IX Item "--strip-symbol=symbolname"
 294 Do not copy symbol \fIsymbolname\fR from the source file.  This option
 295 may be given more than once.
 296 .Ip "\f(CW\*(C`\-G \f(CIsymbolname\f(CW\*(C'\fR" 4
 297 .IX Item "-G symbolname"
 298 .Ip "\f(CW\*(C`\-\-keep\-global\-symbol=\f(CIsymbolname\f(CW\*(C'\fR" 4
 299 .IX Item "--keep-global-symbol=symbolname"
 300 Keep only symbol \fIsymbolname\fR global.  Make all other symbols local
 301 to the file, so that they are not visible externally.  This option may
 302 be given more than once.
 303 .Ip "\f(CW\*(C`\-L \f(CIsymbolname\f(CW\*(C'\fR" 4
 304 .IX Item "-L symbolname"
 305 .Ip "\f(CW\*(C`\-\-localize\-symbol=\f(CIsymbolname\f(CW\*(C'\fR" 4
 306 .IX Item "--localize-symbol=symbolname"
 307 Make symbol \fIsymbolname\fR local to the file, so that it is not
 308 visible externally.  This option may be given more than once.
 309 .Ip "\f(CW\*(C`\-W \f(CIsymbolname\f(CW\*(C'\fR" 4
 310 .IX Item "-W symbolname"
 311 .Ip "\f(CW\*(C`\-\-weaken\-symbol=\f(CIsymbolname\f(CW\*(C'\fR" 4
 312 .IX Item "--weaken-symbol=symbolname"
 313 Make symbol \fIsymbolname\fR weak. This option may be given more than once.
 314 .Ip "\f(CW\*(C`\-x\*(C'\fR" 4
 315 .IX Item "-x"
 316 .Ip "\f(CW\*(C`\-\-discard\-all\*(C'\fR" 4
 317 .IX Item "--discard-all"
 318 Do not copy non-global symbols from the source file.
 319 .Ip "\f(CW\*(C`\-X\*(C'\fR" 4
 320 .IX Item "-X"
 321 .Ip "\f(CW\*(C`\-\-discard\-locals\*(C'\fR" 4
 322 .IX Item "--discard-locals"
 323 Do not copy compiler-generated local symbols.
 324 (These usually start with \fBL\fR or \fB.\fR.)
 325 .Ip "\f(CW\*(C`\-b \f(CIbyte\f(CW\*(C'\fR" 4
 326 .IX Item "-b byte"
 327 .Ip "\f(CW\*(C`\-\-byte=\f(CIbyte\f(CW\*(C'\fR" 4
 328 .IX Item "--byte=byte"
 329 Keep only every \fIbyte\fRth byte of the input file (header data is not
 330 affected).  \fIbyte\fR can be in the range from 0 to \fIinterleave\fR\-1,
 331 where \fIinterleave\fR is given by the \fB\-i\fR or \fB\*(--interleave\fR
 332 option, or the default of 4.  This option is useful for creating files
 333 to program \s-1ROM\s0.  It is typically used with an \f(CW\*(C`srec\*(C'\fR output
 334 target.
 335 .Ip "\f(CW\*(C`\-i \f(CIinterleave\f(CW\*(C'\fR" 4
 336 .IX Item "-i interleave"
 337 .Ip "\f(CW\*(C`\-\-interleave=\f(CIinterleave\f(CW\*(C'\fR" 4
 338 .IX Item "--interleave=interleave"
 339 Only copy one out of every \fIinterleave\fR bytes.  Select which byte to
 340 copy with the \fI\-b\fR or \fB\*(--byte\fR option.  The default is 4.
 341 \&\f(CW\*(C`objcopy\*(C'\fR ignores this option if you do not specify either \fB\-b\fR or
 342 \&\fB\*(--byte\fR.
 343 .Ip "\f(CW\*(C`\-p\*(C'\fR" 4
 344 .IX Item "-p"
 345 .Ip "\f(CW\*(C`\-\-preserve\-dates\*(C'\fR" 4
 346 .IX Item "--preserve-dates"
 347 Set the access and modification dates of the output file to be the same
 348 as those of the input file.
 349 .Ip "\f(CW\*(C`\-\-debugging\*(C'\fR" 4
 350 .IX Item "--debugging"
 351 Convert debugging information, if possible.  This is not the default
 352 because only certain debugging formats are supported, and the
 353 conversion process can be time consuming.
 354 .Ip "\f(CW\*(C`\-\-gap\-fill \f(CIval\f(CW\*(C'\fR" 4
 355 .IX Item "--gap-fill val"
 356 Fill gaps between sections with \fIval\fR.  This operation applies to
 357 the \fIload address\fR (\s-1LMA\s0) of the sections.  It is done by increasing
 358 the size of the section with the lower address, and filling in the extra
 359 space created with \fIval\fR.
 360 .Ip "\f(CW\*(C`\-\-pad\-to \f(CIaddress\f(CW\*(C'\fR" 4
 361 .IX Item "--pad-to address"
 362 Pad the output file up to the load address \fIaddress\fR.  This is
 363 done by increasing the size of the last section.  The extra space is
 364 filled in with the value specified by \fB\*(--gap-fill\fR (default zero).
 365 .Ip "\f(CW\*(C`\-\-set\-start \f(CIval\f(CW\*(C'\fR" 4
 366 .IX Item "--set-start val"
 367 Set the start address of the new file to \fIval\fR.  Not all object file
 368 formats support setting the start address.
 369 .Ip "\f(CW\*(C`\-\-change\-start \f(CIincr\f(CW\*(C'\fR" 4
 370 .IX Item "--change-start incr"
 371 .Ip "\f(CW\*(C`\-\-adjust\-start \f(CIincr\f(CW\*(C'\fR" 4
 372 .IX Item "--adjust-start incr"
 373 Change the start address by adding \fIincr\fR.  Not all object file
 374 formats support setting the start address.
 375 .Ip "\f(CW\*(C`\-\-change\-addresses \f(CIincr\f(CW\*(C'\fR" 4
 376 .IX Item "--change-addresses incr"
 377 .Ip "\f(CW\*(C`\-\-adjust\-vma \f(CIincr\f(CW\*(C'\fR" 4
 378 .IX Item "--adjust-vma incr"
 379 Change the \s-1VMA\s0 and \s-1LMA\s0 addresses of all sections, as well as the start
 380 address, by adding \fIincr\fR.  Some object file formats do not permit
 381 section addresses to be changed arbitrarily.  Note that this does not
 382 relocate the sections; if the program expects sections to be loaded at a
 383 certain address, and this option is used to change the sections such
 384 that they are loaded at a different address, the program may fail.
 385 .Ip "\f(CW\*(C`\-\-change\-section\-address \f(CIsection\f(CW{=,+,\-}\f(CIval\f(CW\*(C'\fR" 4
 386 .IX Item "--change-section-address section{=,+,-}val"
 387 .Ip "\f(CW\*(C`\-\-adjust\-section\-vma \f(CIsection\f(CW{=,+,\-}\f(CIval\f(CW\*(C'\fR" 4
 388 .IX Item "--adjust-section-vma section{=,+,-}val"
 389 Set or change both the \s-1VMA\s0 address and the \s-1LMA\s0 address of the named
 390 \&\fIsection\fR.  If \fB=\fR is used, the section address is set to
 391 \&\fIval\fR.  Otherwise, \fIval\fR is added to or subtracted from the
 392 section address.  See the comments under \fB\*(--change-addresses\fR,
 393 above. If \fIsection\fR does not exist in the input file, a warning will
 394 be issued, unless \fB\*(--no-change-warnings\fR is used.
 395 .Ip "\f(CW\*(C`\-\-change\-section\-lma \f(CIsection\f(CW{=,+,\-}\f(CIval\f(CW\*(C'\fR" 4
 396 .IX Item "--change-section-lma section{=,+,-}val"
 397 Set or change the \s-1LMA\s0 address of the named \fIsection\fR.  The \s-1LMA\s0
 398 address is the address where the section will be loaded into memory at
 399 program load time.  Normally this is the same as the \s-1VMA\s0 address, which
 400 is the address of the section at program run time, but on some systems,
 401 especially those where a program is held in \s-1ROM\s0, the two can be
 402 different.  If \fB=\fR is used, the section address is set to
 403 \&\fIval\fR.  Otherwise, \fIval\fR is added to or subtracted from the
 404 section address.  See the comments under \fB\*(--change-addresses\fR,
 405 above.  If \fIsection\fR does not exist in the input file, a warning
 406 will be issued, unless \fB\*(--no-change-warnings\fR is used.
 407 .Ip "\f(CW\*(C`\-\-change\-section\-vma \f(CIsection\f(CW{=,+,\-}\f(CIval\f(CW\*(C'\fR" 4
 408 .IX Item "--change-section-vma section{=,+,-}val"
 409 Set or change the \s-1VMA\s0 address of the named \fIsection\fR.  The \s-1VMA\s0
 410 address is the address where the section will be located once the
 411 program has started executing.  Normally this is the same as the \s-1LMA\s0
 412 address, which is the address where the section will be loaded into
 413 memory, but on some systems, especially those where a program is held in
 414 \&\s-1ROM\s0, the two can be different.  If \fB=\fR is used, the section address
 415 is set to \fIval\fR.  Otherwise, \fIval\fR is added to or subtracted
 416 from the section address.  See the comments under
 417 \&\fB\*(--change-addresses\fR, above.  If \fIsection\fR does not exist in
 418 the input file, a warning will be issued, unless
 419 \&\fB\*(--no-change-warnings\fR is used.
 420 .Ip "\f(CW\*(C`\-\-change\-warnings\*(C'\fR" 4
 421 .IX Item "--change-warnings"
 422 .Ip "\f(CW\*(C`\-\-adjust\-warnings\*(C'\fR" 4
 423 .IX Item "--adjust-warnings"
 424 If \fB\*(--change-section-address\fR or \fB\*(--change-section-lma\fR or
 425 \&\fB\*(--change-section-vma\fR is used, and the named section does not
 426 exist, issue a warning.  This is the default.
 427 .Ip "\f(CW\*(C`\-\-no\-change\-warnings\*(C'\fR" 4
 428 .IX Item "--no-change-warnings"
 429 .Ip "\f(CW\*(C`\-\-no\-adjust\-warnings\*(C'\fR" 4
 430 .IX Item "--no-adjust-warnings"
 431 Do not issue a warning if \fB\*(--change-section-address\fR or
 432 \&\fB\*(--adjust-section-lma\fR or \fB\*(--adjust-section-vma\fR is used, even
 433 if the named section does not exist.
 434 .Ip "\f(CW\*(C`\-\-set\-section\-flags \f(CIsection\f(CW=\f(CIflags\f(CW\*(C'\fR" 4
 435 .IX Item "--set-section-flags section=flags"
 436 Set the flags for the named section.  The \fIflags\fR argument is a
 437 comma separated string of flag names.  The recognized names are
 438 \&\fBalloc\fR, \fBcontents\fR, \fBload\fR, \fBnoload\fR,
 439 \&\fBreadonly\fR, \fBcode\fR, \fBdata\fR, \fBrom\fR, \fBshare\fR, and
 440 \&\fBdebug\fR.  You can set the \fBcontents\fR flag for a section which
 441 does not have contents, but it is not meaningful to clear the
 442 \&\fBcontents\fR flag of a section which does have contents\*(--just remove
 443 the section instead.  Not all flags are meaningful for all object file
 444 formats.
 445 .Ip "\f(CW\*(C`\-\-add\-section \f(CIsectionname\f(CW=\f(CIfilename\f(CW\*(C'\fR" 4
 446 .IX Item "--add-section sectionname=filename"
 447 Add a new section named \fIsectionname\fR while copying the file.  The
 448 contents of the new section are taken from the file \fIfilename\fR.  The
 449 size of the section will be the size of the file.  This option only
 450 works on file formats which can support sections with arbitrary names.
 451 .Ip "\f(CW\*(C`\-\-change\-leading\-char\*(C'\fR" 4
 452 .IX Item "--change-leading-char"
 453 Some object file formats use special characters at the start of
 454 symbols.  The most common such character is underscore, which compilers
 455 often add before every symbol.  This option tells \f(CW\*(C`objcopy\*(C'\fR to
 456 change the leading character of every symbol when it converts between
 457 object file formats.  If the object file formats use the same leading
 458 character, this option has no effect.  Otherwise, it will add a
 459 character, or remove a character, or change a character, as
 460 appropriate.
 461 .Ip "\f(CW\*(C`\-\-remove\-leading\-char\*(C'\fR" 4
 462 .IX Item "--remove-leading-char"
 463 If the first character of a global symbol is a special symbol leading
 464 character used by the object file format, remove the character.  The
 465 most common symbol leading character is underscore.  This option will
 466 remove a leading underscore from all global symbols.  This can be useful
 467 if you want to link together objects of different file formats with
 468 different conventions for symbol names.  This is different from
 469 \&\f(CW\*(C`\-\-change\-leading\-char\*(C'\fR because it always changes the symbol name
 470 when appropriate, regardless of the object file format of the output
 471 file.
 472 .Ip "\f(CW\*(C`\-\-srec\-len=\f(CIival\f(CW\*(C'\fR" 4
 473 .IX Item "--srec-len=ival"
 474 Meaningful only for srec output.  Set the maximum length of the Srecords
 475 being produced to \fIival\fR.  This length covers both address, data and
 476 crc fields.
 477 .Ip "\f(CW\*(C`\-\-srec\-forceS3\*(C'\fR" 4
 478 .IX Item "--srec-forceS3"
 479 Meaningful only for srec output.  Avoid generation of S1/S2 records,
 480 creating S3\-only record format.
 481 .Ip "\f(CW\*(C`\-\-redefine\-sym \f(CIold\f(CW=\f(CInew\f(CW\*(C'\fR" 4
 482 .IX Item "--redefine-sym old=new"
 483 Change the name of a symbol \fIold\fR, to \fInew\fR.  This can be useful
 484 when one is trying link two things together for which you have no
 485 source, and there are name collisions.
 486 .Ip "\f(CW\*(C`\-\-weaken\*(C'\fR" 4
 487 .IX Item "--weaken"
 488 Change all global symbols in the file to be weak.  This can be useful
 489 when building an object which will be linked against other objects using
 490 the \f(CW\*(C`\-R\*(C'\fR option to the linker.  This option is only effective when
 491 using an object file format which supports weak symbols.
 492 .Ip "\f(CW\*(C`\-\-keep\-symbols=\f(CIfilename\f(CW\*(C'\fR" 4
 493 .IX Item "--keep-symbols=filename"
 494 Apply \fB\*(--keep-symbol\fR option to each symbol listed in the file
 495 \&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
 496 name per line.  Line comments may be introduced by the hash character.
 497 This option may be given more than once.
 498 .Ip "\f(CW\*(C`\-\-strip\-symbols=\f(CIfilename\f(CW\*(C'\fR" 4
 499 .IX Item "--strip-symbols=filename"
 500 Apply \fB\*(--strip-symbol\fR option to each symbol listed in the file
 501 \&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
 502 name per line.  Line comments may be introduced by the hash character.
 503 This option may be given more than once.
 504 .Ip "\f(CW\*(C`\-\-keep\-global\-symbols=\f(CIfilename\f(CW\*(C'\fR" 4
 505 .IX Item "--keep-global-symbols=filename"
 506 Apply \fB\*(--keep-global-symbol\fR option to each symbol listed in the
 507 file \fIfilename\fR.  \fIfilename\fR is simply a flat file, with one
 508 symbol name per line.  Line comments may be introduced by the hash
 509 character.  This option may be given more than once.
 510 .Ip "\f(CW\*(C`\-\-localize\-symbols=\f(CIfilename\f(CW\*(C'\fR" 4
 511 .IX Item "--localize-symbols=filename"
 512 Apply \fB\*(--localize-symbol\fR option to each symbol listed in the file
 513 \&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
 514 name per line.  Line comments may be introduced by the hash character.
 515 This option may be given more than once.
 516 .Ip "\f(CW\*(C`\-\-weaken\-symbols=\f(CIfilename\f(CW\*(C'\fR" 4
 517 .IX Item "--weaken-symbols=filename"
 518 Apply \fB\*(--weaken-symbol\fR option to each symbol listed in the file
 519 \&\fIfilename\fR.  \fIfilename\fR is simply a flat file, with one symbol
 520 name per line.  Line comments may be introduced by the hash character.
 521 This option may be given more than once.
 522 .Ip "\f(CW\*(C`\-V\*(C'\fR" 4
 523 .IX Item "-V"
 524 .Ip "\f(CW\*(C`\-\-version\*(C'\fR" 4
 525 .IX Item "--version"
 526 Show the version number of \f(CW\*(C`objcopy\*(C'\fR.
 527 .Ip "\f(CW\*(C`\-v\*(C'\fR" 4
 528 .IX Item "-v"
 529 .Ip "\f(CW\*(C`\-\-verbose\*(C'\fR" 4
 530 .IX Item "--verbose"
 531 Verbose output: list all object files modified.  In the case of
 532 archives, \fBobjcopy \-V\fR lists all members of the archive.
 533 .Ip "\f(CW\*(C`\-\-help\*(C'\fR" 4
 534 .IX Item "--help"
 535 Show a summary of the options to \f(CW\*(C`objcopy\*(C'\fR.
 536 .SH "SEE ALSO"
 537 .IX Header "SEE ALSO"
 538 \&\fIld\fR\|(1), \fIobjdump\fR\|(1), and the Info entries for \fIbinutils\fR.
 539 .SH "COPYRIGHT"
 540 .IX Header "COPYRIGHT"
 541 Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
 542 .PP
 543 Permission is granted to copy, distribute and/or modify this document
 544 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1
 545 or any later version published by the Free Software Foundation;
 546 with no Invariant Sections, with no Front-Cover Texts, and with no
 547 Back-Cover Texts.  A copy of the license is included in the
 548 section entitled \*(L"\s-1GNU\s0 Free Documentation License\*(R".