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