contrib/elftoolchain/elfcopy/elfcopy.1

   1 .\" Copyright (c) 2008-2009,2011 Joseph Koshy.  All rights reserved.
   2 .\"
   3 .\" Redistribution and use in source and binary forms, with or without
   4 .\" modification, are permitted provided that the following conditions
   5 .\" are met:
   6 .\" 1. Redistributions of source code must retain the above copyright
   7 .\"    notice, this list of conditions and the following disclaimer.
   8 .\" 2. Redistributions in binary form must reproduce the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer in the
  10 .\"    documentation and/or other materials provided with the distribution.
  11 .\"
  12 .\" This software is provided by Joseph Koshy ``as is'' and
  13 .\" any express or implied warranties, including, but not limited to, the
  14 .\" implied warranties of merchantability and fitness for a particular purpose
  15 .\" are disclaimed.  in no event shall Joseph Koshy be liable
  16 .\" for any direct, indirect, incidental, special, exemplary, or consequential
  17 .\" damages (including, but not limited to, procurement of substitute goods
  18 .\" or services; loss of use, data, or profits; or business interruption)
  19 .\" however caused and on any theory of liability, whether in contract, strict
  20 .\" liability, or tort (including negligence or otherwise) arising in any way
  21 .\" out of the use of this software, even if advised of the possibility of
  22 .\" such damage.
  23 .\"
  24 .\" $Id: elfcopy.1 3426 2016-03-05 13:32:28Z emaste $
  25 .\"
  26 .Dd March 5, 2016
  27 .Os
  28 .Dt ELFCOPY 1
  29 .Sh NAME
  30 .Nm elfcopy ,
  31 .Nm objcopy
  32 .Nd copy and translate object files
  33 .Sh SYNOPSIS
  34 .Nm
  35 .Op Fl I Ar objformat | Fl s Ar objformat | Fl -input-target= Ns Ar objformat
  36 .Op Fl K Ar symbolname | Fl -keep-symbol= Ns Ar symbolname
  37 .Op Fl L Ar symbolname | Fl -localize-symbol= Ns Ar symbolname
  38 .Op Fl N Ar symbolname | Fl -strip-symbol= Ns Ar symbolname
  39 .Op Fl O Ar objformat | Fl -output-target= Ns Ar objformat
  40 .Op Fl R Ar sectionname | Fl -remove-section= Ns Ar sectionname
  41 .Op Fl S | Fl -strip-all
  42 .Op Fl V | Fl -version
  43 .Op Fl W Ar symbolname | Fl -weaken-symbol= Ns Ar symbolname
  44 .Op Fl X | Fl -discard-locals
  45 .Op Fl d | Fl g | Fl -strip-debug
  46 .Op Fl h | Fl -help
  47 .Op Fl j Ar sectionname | Fl -only-section= Ns Ar sectionname
  48 .Op Fl p | Fl -preserve-dates
  49 .Op Fl w | Fl -wildcard
  50 .Op Fl x | Fl -discard-all
  51 .Op Fl -add-gnu-debuglink Ns = Ns Ar filename
  52 .Op Fl -add-section Ar sectionname Ns = Ns Ar filename
  53 .Oo
  54 .Fl -adjust-section-vma Ar section Ns {+|-|=} Ns Ar val |
  55 .Fl -change-section-address Ar section Ns {+|-|=} Ns Ar val
  56 .Oc
  57 .Oo
  58 .Fl -adjust-start Ns = Ns Ar increment |
  59 .Fl -change-start Ns = Ns Ar increment
  60 .Oc
  61 .Oo
  62 .Fl -adjust-vma Ns = Ns Ar increment |
  63 .Fl -change-addresses Ns = Ns Ar increment
  64 .Oc
  65 .Op Fl -adjust-warnings | Fl -change-warnings
  66 .Op Fl -change-section-lma Ar section Ns {+|-|=} Ns Ar val
  67 .Op Fl -change-section-vma Ar section Ns {+|-|=} Ns Ar val
  68 .Op Fl -extract-dwo
  69 .Op Fl -gap-fill Ns = Ns Ar val
  70 .Op Fl -globalize-symbol Ns = Ns ar symbolname
  71 .Op Fl -globalize-symbols Ns = Ns Ar filename
  72 .Op Fl -localize-hidden
  73 .Op Fl -localize-symbols Ns = Ns Ar filename
  74 .Op Fl -no-adjust-warnings | Fl -no-change-warnings
  75 .Op Fl -only-keep-debug
  76 .Op Fl -pad-to Ns = Ns Ar address
  77 .Op Fl -prefix-alloc-sections Ns = Ns Ar string
  78 .Op Fl -prefix-sections Ns = Ns Ar string
  79 .Op Fl -prefix-symbols Ns = Ns Ar string
  80 .Op Fl -rename-section Ar oldname Ns = Ns Ar newname Ns Op Ar ,flags
  81 .Op Fl -set-section-flags Ar sectionname Ns = Ns Ar flags
  82 .Op Fl -set-start Ns = Ns Ar address
  83 .Op Fl -srec-forceS3
  84 .Op Fl -srec-len Ns = Ns Ar val
  85 .Op Fl -strip-dwo
  86 .Op Fl -strip-unneeded
  87 .Ar infile
  88 .Op Ar outfile
  89 .Sh DESCRIPTION
  90 The
  91 .Nm
  92 utility copies the content of the binary object named by argument
  93 .Ar infile
  94 to that named by argument
  95 .Ar outfile ,
  96 transforming it according to the command line options specified.
  97 If argument
  98 .Ar outfile
  99 is not specified,
 100 .Nm
 101 will create a temporary file and will subsequently rename it as
 102 .Ar infile .
 103 .Pp
 104 The
 105 .Nm
 106 utility supports the following options:
 107 .Bl -tag -width indent
 108 .It Fl I Ar objformat | Fl s Ar objformat | Fl -input-target= Ns Ar objformat
 109 Specify that the input file named by the argument
 110 .Ar infile
 111 is in the object format specified by the argument
 112 .Ar objformat .
 113 .It Fl K Ar symbolname | Fl -keep-symbol= Ns Ar symbolname
 114 Copy the symbol named by argument
 115 .Ar symbolname
 116 to the output.
 117 .It Fl L Ar symbolname | Fl -localize-symbol= Ns Ar symbolname
 118 Make the symbol named by argument
 119 .Ar symbolname
 120 local to the output file.
 121 .It Fl N Ar symbol | Fl -strip-symbol= Ns Ar symbolname
 122 Do not copy the symbol named by argument
 123 .Ar symbolname
 124 to the output.
 125 .It Fl O Ar objformat | Fl -output-target= Ns Ar objformat
 126 Write the output file using the object format specified in argument
 127 .Ar objformat .
 128 The argument
 129 .Ar objformat
 130 should be one of the target names recognized by
 131 .Xr elftc_bfd_find_target 3 .
 132 .It Fl R Ar sectionname | Fl -remove-section= Ns Ar sectionname
 133 Remove any section with name
 134 .Ar sectionname
 135 from the output file.
 136 .It Fl S | Fl -strip-all
 137 Do not copy symbol and relocation information to the target file.
 138 .It Fl V | Fl -version
 139 Print a version identifier and exit.
 140 .It Fl W Ar symbolname | Fl -weaken-symbol= Ns Ar symbolname
 141 Mark the symbol named by argument
 142 .Ar symbolname
 143 as weak in the output.
 144 .It Fl X | Fl -discard-locals
 145 Do not copy compiler generated local symbols to the output.
 146 .It Fl d | Fl g | Fl -strip-debug
 147 Do not copy debugging information to the target file.
 148 .It Fl h | Fl -help
 149 Display a help message and exit.
 150 .It Fl j Ar sectionname | Fl -only-section= Ns Ar sectionname
 151 Copy only the section named by argument
 152 .Ar sectionname
 153 to the output.
 154 .It Fl p | Fl -preserve-dates
 155 Set the access and modification times of the output file to the
 156 same as those of the input.
 157 .It Fl w | Fl -wildcard
 158 Use shell-style patterns to name symbols.
 159 The following meta-characters are recognized in patterns:
 160 .Bl -tag -width "...." -compact
 161 .It Li !
 162 If this is the first character of the pattern, invert the sense of the
 163 pattern match.
 164 .It Li *
 165 Matches any string of characters in a symbol name.
 166 .It Li ?
 167 Matches zero or one character in a symbol name.
 168 .It Li [
 169 Mark the start of a character class.
 170 .It Li \e
 171 Remove the special meaning of the next character in the pattern.
 172 .It Li ]
 173 Mark the end of a character class.
 174 .El
 175 .It Fl x | Fl -discard-all
 176 Do not copy non-global symbols to the output.
 177 .It Fl -add-gnu-debuglink Ns = Ns Ar filename
 178 Create a .gnu_debuglink section in the output file that references the
 179 debug data in
 180 .Ar filename .
 181 .It Fl -add-section Ar sectionname Ns = Ns Ar filename
 182 Add a new section to the output file with name
 183 .Ar sectionname .
 184 The contents of the section are taken from the file named by
 185 argument
 186 .Ar filename .
 187 The size of the section will be the number of bytes in file
 188 .Ar filename .
 189 .It Xo
 190 .Fl -adjust-section-vma Ar section Ns {+|-|=} Ns Ar val |
 191 .Fl -change-section-address Ar section Ns {+|-|=} Ns Ar val
 192 .Xc
 193 Depending on the operator specified, increase, decrease or set both
 194 the virtual memory address and the load memory address of the section
 195 named by the argument
 196 .Ar section .
 197 The argument
 198 .Ar val
 199 specifies the desired increment, decrement or new value for the
 200 address.
 201 .It Xo
 202 .Fl -adjust-start Ns = Ns Ar increment |
 203 .Fl -change-start Ns = Ns Ar increment
 204 .Xc
 205 Increase the entry point address of the output ELF object by the value
 206 specified in the argument
 207 .Ar increment .
 208 .It Xo
 209 .Fl -adjust-vma Ns = Ns Ar increment |
 210 .Fl -change-addresses Ns = Ns Ar increment
 211 .Xc
 212 Increase the virtual memory address and the load memory address of all
 213 sections by the value specified by the argument
 214 .Ar increment .
 215 .It Fl -adjust-warnings | Fl -change-warnings
 216 Issue a warning if the section specified by the options
 217 .Fl -change-section-address ,
 218 .Fl -change-section-lma
 219 or
 220 .Fl -change-section-vma
 221 does not exist in the input object.
 222 This is the default.
 223 .It Fl -change-section-lma Ar section Ns {+|-|=} Ns Ar val
 224 Change or set the load memory address of the section named by the
 225 argument
 226 .Ar section .
 227 Depending on the operator specified, the value in argument
 228 .Ar val
 229 will be used as an increment, a decrement or as the new value
 230 of the load memory address.
 231 .It Fl -change-section-vma Ar section Ns {+|-|=} Ns Ar val
 232 Change or set the virtual memory address of the section named by the
 233 argument
 234 .Ar section .
 235 Depending on the operator specified, the value in argument
 236 .Ar val
 237 will be used as an increment, a decrement or as the new value
 238 of the virtual memory address.
 239 .It Fl -extract-dwo
 240 Copy only .dwo debug sections to the output file.
 241 .It Fl -gap-fill Ns = Ns Ar val
 242 Fill the gaps between sections with the byte value specified by
 243 the argument
 244 .Ar val .
 245 .It Fl -globalize-symbol Ns = Ns Ar symbolname
 246 Make the symbol named by argument
 247 .Ar symbolname
 248 global, so that it is visible outside of the file in which it is defined.
 249 .It Fl -globalize-symbols Ns = Ns Ar filename
 250 Make each symbol listed in the file specified by
 251 .Ar filename
 252 global.
 253 .It Fl -localize-hidden
 254 Make all hidden symbols local to the output file.
 255 This includes symbols with internal visiblity.
 256 .It Fl -localize-symbols Ns = Ns Ar filename
 257 Make each symbol listed in the file specified by
 258 .Ar filename
 259 local to the output file.
 260 .It Fl -no-adjust-warnings | Fl -no-change-warnings
 261 Do not issue a warning if the section specified by the options
 262 .Fl -change-section-address ,
 263 .Fl -change-section-lma
 264 or
 265 .Fl -change-section-vma
 266 is missing in the input object.
 267 .It Fl -only-keep-debug
 268 Copy only debugging information to the output file.
 269 .It Fl -pad-to Ns = Ns Ar address
 270 Pad the load memory address of the output object to the value
 271 specified by the argument
 272 .Ar address
 273 by increasing the size of the section with the highest load memory
 274 address.
 275 .It Fl -prefix-alloc-sections Ns = Ns Ar string
 276 Prefix the section names of all the allocated sections with
 277 .Ar string .
 278 .It Fl -prefix-sections Ns = Ns Ar string
 279 Prefix the section names of all the sections with
 280 .Ar string .
 281 .It Fl -prefix-symbols Ns = Ns Ar string
 282 Prefix the symbol names of all the symbols with
 283 .Ar string .
 284 .It Fl -rename-section Ar oldname Ns = Ns Ar newname Ns Op Ar ,flags
 285 Rename the section named by argument
 286 .Ar oldname
 287 to
 288 .Ar newname ,
 289 optionally changing the sections flags to that specified by argument
 290 .Ar flags .
 291 Allowed values for the argument
 292 .Ar flags
 293 are as for option
 294 .Fl -set-section-flags
 295 below.
 296 .It Fl -set-section-flags Ar sectionname Ns = Ns Ar flags
 297 Set the flags for the section named by argument
 298 .Ar sectionname
 299 to those specified by argument
 300 .Ar flags .
 301 Argument
 302 .Ar flags
 303 is a comma separated list of the following flag names:
 304 .Bl -tag -width "readonly" -compact
 305 .It alloc
 306 The section occupies space in the output file.
 307 .It code
 308 The section contains machine instructions.
 309 .It contents
 310 This flag is accepted but is ignored.
 311 .It data
 312 The section contains writeable data.
 313 .It debug
 314 The section holds debugging information.
 315 .It load
 316 The section is loadable.
 317 .It noload
 318 The section should not be loaded into memory.
 319 .It readonly
 320 The section is not writable.
 321 .It rom
 322 The section contains ROM'able contents.
 323 .It share
 324 This flag is accepted but is ignored.
 325 .El
 326 .It Fl -set-start Ns = Ns Ar address
 327 Set the start address of the output ELF object to the value specified
 328 by the argument
 329 .Ar address .
 330 .It Fl -srec-forceS3
 331 Only generate S-records of type
 332 .Dq S3 .
 333 This option is only meaningful when the output target is set to
 334 .Dq srec .
 335 .It Fl -srec-len Ns = Ns Ar val
 336 Set the maximum length of an S-record line to
 337 .Ar val .
 338 This option is only meaningful when the output target is set to
 339 .Dq srec .
 340 .It Fl -strip-dwo
 341 Do not copy .dwo debug sections to the output file.
 342 .It Fl -strip-unneeded
 343 Do not copy symbols that are not needed for relocation processing.
 344 .El
 345 .Sh DIAGNOSTICS
 346 .Ex -std
 347 .Sh SEE ALSO
 348 .Xr ar 1 ,
 349 .Xr ld 1 ,
 350 .Xr mcs 1 ,
 351 .Xr strip 1 ,
 352 .Xr elf 3 ,
 353 .Xr elftc_bfd_find_target 3 ,
 354 .Xr ar 5 ,
 355 .Xr elf 5
 356 .Sh COMPATIBILITY
 357 The
 358 .Nm
 359 utility is expected to be option compatible with GNU
 360 .Nm objcopy .
 361 .Sh HISTORY
 362 .Nm
 363 has been implemented by
 364 .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .