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