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