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 3565 2017-08-31 02:24:19Z emaste $
  25 .\"
  26 .Dd August 30, 2017
  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-symbols= Ns Ar filename
  87 .Op Fl -strip-unneeded
  88 .Ar infile
  89 .Op Ar outfile
  90 .Sh DESCRIPTION
  91 The
  92 .Nm
  93 utility copies the content of the binary object named by argument
  94 .Ar infile
  95 to that named by argument
  96 .Ar outfile ,
  97 transforming it according to the command line options specified.
  98 If argument
  99 .Ar outfile
 100 is not specified,
 101 .Nm
 102 will create a temporary file and will subsequently rename it as
 103 .Ar infile .
 104 .Pp
 105 The
 106 .Nm
 107 utility supports the following options:
 108 .Bl -tag -width indent
 109 .It Fl I Ar objformat | Fl s Ar objformat | Fl -input-target= Ns Ar objformat
 110 Specify that the input file named by the argument
 111 .Ar infile
 112 is in the object format specified by the argument
 113 .Ar objformat .
 114 .It Fl K Ar symbolname | Fl -keep-symbol= Ns Ar symbolname
 115 Copy the symbol named by argument
 116 .Ar symbolname
 117 to the output.
 118 .It Fl L Ar symbolname | Fl -localize-symbol= Ns Ar symbolname
 119 Make the symbol named by argument
 120 .Ar symbolname
 121 local to the output file.
 122 .It Fl N Ar symbol | Fl -strip-symbol= Ns Ar symbolname
 123 Do not copy the symbol named by argument
 124 .Ar symbolname
 125 to the output.
 126 .It Fl O Ar objformat | Fl -output-target= Ns Ar objformat
 127 Write the output file using the object format specified in argument
 128 .Ar objformat .
 129 The argument
 130 .Ar objformat
 131 should be one of the target names recognized by
 132 .Xr elftc_bfd_find_target 3 .
 133 .It Fl R Ar sectionname | Fl -remove-section= Ns Ar sectionname
 134 Remove any section with name
 135 .Ar sectionname
 136 from the output file.
 137 .It Fl S | Fl -strip-all
 138 Do not copy symbol and relocation information to the target file.
 139 .It Fl V | Fl -version
 140 Print a version identifier and exit.
 141 .It Fl W Ar symbolname | Fl -weaken-symbol= Ns Ar symbolname
 142 Mark the symbol named by argument
 143 .Ar symbolname
 144 as weak in the output.
 145 .It Fl X | Fl -discard-locals
 146 Do not copy compiler generated local symbols to the output.
 147 .It Fl d | Fl g | Fl -strip-debug
 148 Do not copy debugging information to the target file.
 149 .It Fl h | Fl -help
 150 Display a help message and exit.
 151 .It Fl j Ar sectionname | Fl -only-section= Ns Ar sectionname
 152 Copy only the section named by argument
 153 .Ar sectionname
 154 to the output.
 155 .It Fl p | Fl -preserve-dates
 156 Set the access and modification times of the output file to the
 157 same as those of the input.
 158 .It Fl w | Fl -wildcard
 159 Use shell-style patterns to name symbols.
 160 The following meta-characters are recognized in patterns:
 161 .Bl -tag -width "...." -compact
 162 .It Li !
 163 If this is the first character of the pattern, invert the sense of the
 164 pattern match.
 165 .It Li *
 166 Matches any string of characters in a symbol name.
 167 .It Li ?
 168 Matches zero or one character in a symbol name.
 169 .It Li [
 170 Mark the start of a character class.
 171 .It Li \e
 172 Remove the special meaning of the next character in the pattern.
 173 .It Li ]
 174 Mark the end of a character class.
 175 .El
 176 .It Fl x | Fl -discard-all
 177 Do not copy non-global symbols to the output.
 178 .It Fl -add-gnu-debuglink Ns = Ns Ar filename
 179 Create a .gnu_debuglink section in the output file that references the
 180 debug data in
 181 .Ar filename .
 182 .It Fl -add-section Ar sectionname Ns = Ns Ar filename
 183 Add a new section to the output file with name
 184 .Ar sectionname .
 185 The contents of the section are taken from the file named by
 186 argument
 187 .Ar filename .
 188 The size of the section will be the number of bytes in file
 189 .Ar filename .
 190 .It Xo
 191 .Fl -adjust-section-vma Ar section Ns {+|-|=} Ns Ar val |
 192 .Fl -change-section-address Ar section Ns {+|-|=} Ns Ar val
 193 .Xc
 194 Depending on the operator specified, increase, decrease or set both
 195 the virtual memory address and the load memory address of the section
 196 named by the argument
 197 .Ar section .
 198 The argument
 199 .Ar val
 200 specifies the desired increment, decrement or new value for the
 201 address.
 202 .It Xo
 203 .Fl -adjust-start Ns = Ns Ar increment |
 204 .Fl -change-start Ns = Ns Ar increment
 205 .Xc
 206 Increase the entry point address of the output ELF object by the value
 207 specified in the argument
 208 .Ar increment .
 209 .It Xo
 210 .Fl -adjust-vma Ns = Ns Ar increment |
 211 .Fl -change-addresses Ns = Ns Ar increment
 212 .Xc
 213 Increase the virtual memory address and the load memory address of all
 214 sections by the value specified by the argument
 215 .Ar increment .
 216 .It Fl -adjust-warnings | Fl -change-warnings
 217 Issue a warning if the section specified by the options
 218 .Fl -change-section-address ,
 219 .Fl -change-section-lma
 220 or
 221 .Fl -change-section-vma
 222 does not exist in the input object.
 223 This is the default.
 224 .It Fl -change-section-lma Ar section Ns {+|-|=} Ns Ar val
 225 Change or set the load memory address of the section named by the
 226 argument
 227 .Ar section .
 228 Depending on the operator specified, the value in argument
 229 .Ar val
 230 will be used as an increment, a decrement or as the new value
 231 of the load memory address.
 232 .It Fl -change-section-vma Ar section Ns {+|-|=} Ns Ar val
 233 Change or set the virtual memory address of the section named by the
 234 argument
 235 .Ar section .
 236 Depending on the operator specified, the value in argument
 237 .Ar val
 238 will be used as an increment, a decrement or as the new value
 239 of the virtual memory address.
 240 .It Fl -extract-dwo
 241 Copy only .dwo debug sections to the output file.
 242 .It Fl -gap-fill Ns = Ns Ar val
 243 Fill the gaps between sections with the byte value specified by
 244 the argument
 245 .Ar val .
 246 .It Fl -globalize-symbol Ns = Ns Ar symbolname
 247 Make the symbol named by argument
 248 .Ar symbolname
 249 global, so that it is visible outside of the file in which it is defined.
 250 .It Fl -globalize-symbols Ns = Ns Ar filename
 251 Make each symbol listed in the file specified by
 252 .Ar filename
 253 global.
 254 .It Fl -localize-hidden
 255 Make all hidden symbols local to the output file.
 256 This includes symbols with internal visiblity.
 257 .It Fl -localize-symbols Ns = Ns Ar filename
 258 Make each symbol listed in the file specified by
 259 .Ar filename
 260 local to the output file.
 261 .It Fl -no-adjust-warnings | Fl -no-change-warnings
 262 Do not issue a warning if the section specified by the options
 263 .Fl -change-section-address ,
 264 .Fl -change-section-lma
 265 or
 266 .Fl -change-section-vma
 267 is missing in the input object.
 268 .It Fl -only-keep-debug
 269 Copy only debugging information to the output file.
 270 .It Fl -pad-to Ns = Ns Ar address
 271 Pad the load memory address of the output object to the value
 272 specified by the argument
 273 .Ar address
 274 by increasing the size of the section with the highest load memory
 275 address.
 276 .It Fl -prefix-alloc-sections Ns = Ns Ar string
 277 Prefix the section names of all the allocated sections with
 278 .Ar string .
 279 .It Fl -prefix-sections Ns = Ns Ar string
 280 Prefix the section names of all the sections with
 281 .Ar string .
 282 .It Fl -prefix-symbols Ns = Ns Ar string
 283 Prefix the symbol names of all the symbols with
 284 .Ar string .
 285 .It Fl -rename-section Ar oldname Ns = Ns Ar newname Ns Op Ar ,flags
 286 Rename the section named by argument
 287 .Ar oldname
 288 to
 289 .Ar newname ,
 290 optionally changing the sections flags to that specified by argument
 291 .Ar flags .
 292 Allowed values for the argument
 293 .Ar flags
 294 are as for option
 295 .Fl -set-section-flags
 296 below.
 297 .It Fl -set-section-flags Ar sectionname Ns = Ns Ar flags
 298 Set the flags for the section named by argument
 299 .Ar sectionname
 300 to those specified by argument
 301 .Ar flags .
 302 Argument
 303 .Ar flags
 304 is a comma separated list of the following flag names:
 305 .Bl -tag -width "readonly" -compact
 306 .It alloc
 307 The section occupies space in the output file.
 308 .It code
 309 The section contains machine instructions.
 310 .It contents
 311 This flag is accepted but is ignored.
 312 .It data
 313 The section contains writeable data.
 314 .It debug
 315 The section holds debugging information.
 316 .It load
 317 The section is loadable.
 318 .It noload
 319 The section should not be loaded into memory.
 320 .It readonly
 321 The section is not writable.
 322 .It rom
 323 The section contains ROM'able contents.
 324 .It share
 325 This flag is accepted but is ignored.
 326 .El
 327 .It Fl -set-start Ns = Ns Ar address
 328 Set the start address of the output ELF object to the value specified
 329 by the argument
 330 .Ar address .
 331 .It Fl -srec-forceS3
 332 Only generate S-records of type
 333 .Dq S3 .
 334 This option is only meaningful when the output target is set to
 335 .Dq srec .
 336 .It Fl -srec-len Ns = Ns Ar val
 337 Set the maximum length of an S-record line to
 338 .Ar val .
 339 This option is only meaningful when the output target is set to
 340 .Dq srec .
 341 .It Fl -strip-dwo
 342 Do not copy .dwo debug sections to the output file.
 343 .It Fl -strip-symbols= Ns Ar filename
 344 Do not copy any of the symbols specified by
 345 .Ar filename
 346 to the output.
 347 .It Fl -strip-unneeded
 348 Do not copy symbols that are not needed for relocation processing.
 349 .El
 350 .Sh DIAGNOSTICS
 351 .Ex -std
 352 .Sh SEE ALSO
 353 .Xr ar 1 ,
 354 .Xr ld 1 ,
 355 .Xr mcs 1 ,
 356 .Xr strip 1 ,
 357 .Xr elf 3 ,
 358 .Xr elftc_bfd_find_target 3 ,
 359 .Xr ar 5 ,
 360 .Xr elf 5
 361 .Sh COMPATIBILITY
 362 The
 363 .Nm
 364 utility is expected to be option compatible with GNU
 365 .Nm objcopy .
 366 .Sh HISTORY
 367 .Nm
 368 has been implemented by
 369 .An Kai Wang Aq Mt kaiwang27@users.sourceforge.net .