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