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