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