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