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