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