blob: 0119280625d90ae1e66e8e653766d66af2220ae3 [file] [log] [blame]
James Hendersone26ca962019-07-03 14:21:48 +00001llvm-objcopy - object copying and editing tool
2==============================================
3
4.. program:: llvm-objcopy
5
6SYNOPSIS
7--------
8
9:program:`llvm-objcopy` [*options*] *input* [*output*]
10
11DESCRIPTION
12-----------
13
14:program:`llvm-objcopy` is a tool to copy and manipulate objects. In basic
15usage, it makes a semantic copy of the input to the output. If any options are
16specified, the output may be modified along the way, e.g. by removing sections.
17
18If no output file is specified, the input file is modified in-place. If "-" is
19specified for the input file, the input is read from the program's standard
20input stream. If "-" is specified for the output file, the output is written to
21the standard output stream of the program.
22
23If the input is an archive, any requested operations will be applied to each
24archive member individually.
25
26The tool is still in active development, but in most scenarios it works as a
27drop-in replacement for GNU's :program:`objcopy`.
28
29GENERIC AND CROSS-PLATFORM OPTIONS
30----------------------------------
31
32The following options are either agnostic of the file format, or apply to
33multiple file formats.
34
35.. option:: --add-gnu-debuglink <debug-file>
36
37 Add a .gnu_debuglink section for ``<debug-file>`` to the output.
38
39.. option:: --disable-deterministic-archives, -U
40
41 Use real values for UIDs, GIDs and timestamps when updating archive member
42 headers.
43
44.. option:: --discard-all, -x
45
46 Remove most local symbols from the output. Different file formats may limit
47 this to a subset of the local symbols. For example, file and section symbols in
48 ELF objects will not be discarded.
49
50.. option:: --enable-deterministic-archives, -D
51
52 Enable deterministic mode when copying archives, i.e. use 0 for archive member
53 header UIDs, GIDs and timestamp fields. On by default.
54
55.. option:: --help, -h
56
57 Print a summary of command line options.
58
59.. option:: --only-section <section>, -j
60
61 Remove all sections from the output, except for sections named ``<section>``.
62 Can be specified multiple times to keep multiple sections.
63
64.. option:: --regex
65
66 If specified, symbol and section names specified by other switches are treated
67 as extended POSIX regular expression patterns.
68
69.. option:: --remove-section <section>, -R
70
71 Remove the specified section from the output. Can be specified multiple times
72 to remove multiple sections simultaneously.
73
74.. option:: --strip-all-gnu
75
76 Remove all symbols, debug sections and relocations from the output. This option
77 is equivalent to GNU :program:`objcopy`'s ``--strip-all`` switch.
78
79.. option:: --strip-all, -S
80
81 For ELF objects, remove from the output all symbols and non-alloc sections not
82 within segments, except for .gnu.warning sections and the section name table.
83
84 For COFF objects, remove all symbols, debug sections, and relocations from the
85 output.
86
87.. option:: --strip-debug, -g
88
89 Remove all debug sections from the output.
90
91.. option:: --strip-symbol <symbol>, -N
92
93 Remove all symbols named ``<symbol>`` from the output. Can be specified
94 multiple times to remove multiple symbols.
95
96.. option:: --strip-symbols <filename>
97
98 Remove all symbols whose names appear in the file ``<filename>``, from the
99 output. In the file, each line represents a single symbol name, with leading
100 and trailing whitespace ignored, as is anything following a '#'. Can be
101 specified multiple times to read names from multiple files.
102
103.. option:: --strip-unneeded-symbol <symbol>
104
105 Remove from the output all symbols named ``<symbol>`` that are local or
106 undefined and are not required by any relocation.
107
108.. option:: --strip-unneeded-symbols <filename>
109
110 Remove all symbols whose names appear in the file ``<filename>``, from the
111 output, if they are local or undefined and are not required by any relocation.
112 In the file, each line represents a single symbol name, with leading and
113 trailing whitespace ignored, as is anything following a '#'. Can be specified
114 multiple times to read names from multiple files.
115
116.. option:: --strip-unneeded
117
118 Remove from the output all local or undefined symbols that are not required by
119 relocations.
120
121.. option:: --version, -V
122
123 Display the version of this program.
124
125COFF-SPECIFIC OPTIONS
126---------------------
127
128The following options are implemented only for COFF objects. If used with other
129objects, :program:`llvm-objcopy` will either emit an error or silently ignore
130them.
131
132.. option:: --only-keep-debug
133
134 Remove the contents of non-debug sections from the output, but keep the section
135 headers.
136
137ELF-SPECIFIC OPTIONS
138--------------------
139
140The following options are implemented only for ELF objects. If used with other
141objects, :program:`llvm-objcopy` will either emit an error or silently ignore
142them.
143
144.. option:: --add-section <section=file>
145
146 Add a section named ``<section>`` with the contents of ``<file>`` to the
147 output. The section will be of type `SHT_NOTE`, if the name starts with
148 ".note". Otherwise, it will have type `SHT_PROGBITS`. Can be specified multiple
149 times to add multiple sections.
150
151.. option:: --add-symbol <name>=[<section>:]<value>[,<flags>]
152
153 Add to the output a new symbol called ``<name>`` to the symbol table, in the
154 section named ``<section>``, with value ``<value>``. If ``<section>`` is not
155 specified, the symbol is added as an absolute symbol. The ``<flags>`` affect
156 the symbol properties. Accepted values are:
157
158 - `global` = the symbol will have global binding.
159 - `local` = the symbol will have local binding.
160 - `weak` = the symbol will have weak binding.
161 - `default` = the symbol will have default visibility.
162 - `hidden` = the symbol will have hidden visibility.
163 - `file` = the symbol will be an `STT_FILE` symbol.
164 - `section` = the symbol will be an `STT_SECTION` symbol.
165 - `object` = the symbol will be an `STT_OBJECT` symbol.
166 - `function` = the symbol will be an `STT_FUNC` symbol.
167 - `indirect-function` = the symbol will be an `STT_GNU_IFUNC` symbol.
168
169 Additionally, the following flags are accepted but ignored: `debug`,
170 `constructor`, `warning`, `indirect`, `synthetic`, `unique-object`, `before`.
171
172 Can be specified multiple times to add multiple symbols.
173
174.. option:: --allow-broken-links
175
176 Allow llvm-objcopy to remove sections even if it would leave invalid section
177 references. Any invalid sh_link fields will be set to zero.
178
179.. option:: --binary-architecture <arch>, -B
180
181 Specify the architecture to use, when transforming an architecture-less format
182 (e.g. binary) to another format. Valid options are:
183
184 - `aarch64`
185 - `arm`
186 - `i386`
187 - `i386:x86-64`
188 - `mips`
189 - `powerpc:common64`
190 - `riscv:rv32`
191 - `riscv:rv64`
192 - `sparc`
193 - `sparcel`
194 - `x86-64`
195
196.. option:: --build-id-link-dir <dir>
197
198 Set the directory used by :option:`--build-id-link-input` and
199 :option:`--build-id-link-output`.
200
201.. option:: --build-id-link-input <suffix>
202
203 Hard-link the input to ``<dir>/xx/xxx<suffix>``, where ``<dir>`` is the directory
204 specified by :option:`--build-id-link-dir`. The path used is derived from the
205 hex build ID.
206
207.. option:: --build-id-link-output <suffix>
208
209 Hard-link the output to ``<dir>/xx/xxx<suffix>``, where ``<dir>`` is the directory
210 specified by :option:`--build-id-link-dir`. The path used is derived from the
211 hex build ID.
212
213.. option:: --change-start <incr>, --adjust-start
214
215 Add ``<incr>`` to the program's start address. Can be specified multiple
216 times, in which case the values will be applied cumulatively.
217
218.. option:: --compress-debug-sections [<style>]
219
220 Compress DWARF debug sections in the output, using the specified style.
221 Supported styles are `zlib-gnu` and `zlib`. Defaults to `zlib` if no style is
222 specified.
223
224.. option:: --decompress-debug-sections
225
226 Decompress any compressed DWARF debug sections in the output.
227
228.. option:: --discard-locals, -X
229
230 Remove local symbols starting with ".L" from the output.
231
232.. option:: --dump-section <section>=<file>
233
234 Dump the contents of section ``<section>`` into the file ``<file>``. Can be
235 specified multiple times to dump multiple sections to different files.
236 ``<file>`` is unrelated to the input and output files provided to
237 :program:`llvm-objcopy` and as such the normal copying and editing
238 operations will still be performed. No operations are performed on the sections
239 prior to dumping them.
240
241.. option:: --extract-dwo
242
243 Remove all sections that are not DWARF .dwo sections from the output.
244
245.. option:: --extract-main-partition
246
247 Extract the main partition from the output.
248
249.. option:: --extract-partition <name>
250
251 Extract the named partition from the output.
252
253.. option:: --globalize-symbol <symbol>
254
255 Mark any defined symbols named ``<symbol>`` as global symbols in the output.
256 Can be specified multiple times to mark multiple symbols.
257
258.. option:: --globalize-symbols <filename>
259
260 Read a list of names from the file ``<filename>`` and mark defined symbols with
261 those names as global in the output. In the file, each line represents a single
262 symbol, with leading and trailing whitespace ignored, as is anything following
263 a '#'. Can be specified multiple times to read names from multiple files.
264
265.. option:: --input-target <format>, -I
266
267 Read the input as the specified format. See `SUPPORTED FORMATS`_ for a list of
268 valid ``<format>`` values. If unspecified, :program:`llvm-objcopy` will attempt
269 to determine the format automatically.
270
271.. option:: --keep-file-symbols
272
273 Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
274
275.. option:: --keep-global-symbol <symbol>
276
277 Make all symbols local in the output, except for symbols with the name
278 ``<symbol>``. Can be specified multiple times to ignore multiple symbols.
279
280.. option:: --keep-global-symbols <filename>
281
282 Make all symbols local in the output, except for symbols named in the file
283 ``<filename>``. In the file, each line represents a single symbol, with leading
284 and trailing whitespace ignored, as is anything following a '#'. Can be
285 specified multiple times to read names from multiple files.
286
287.. option:: --keep-section <section>
288
289 When removing sections from the output, do not remove sections named
290 ``<section>``. Can be specified multiple times to keep multiple sections.
291
292.. option:: --keep-symbol <symbol>, -K
293
294 When removing symbols from the output, do not remove symbols named
295 ``<symbol>``. Can be specified multiple times to keep multiple symbols.
296
297.. option:: --keep-symbols <filename>
298
299 When removing symbols from the output do not remove symbols named in the file
300 ``<filename>``. In the file, each line represents a single symbol, with leading
301 and trailing whitespace ignored, as is anything following a '#'. Can be
302 specified multiple times to read names from multiple files.
303
304.. option:: --localize-hidden
305
306 Make all symbols with hidden or internal visibility local in the output.
307
308.. option:: --localize-symbol <symbol>, -L
309
310 Mark any defined non-common symbol named ``<symbol>`` as a local symbol in the
311 output. Can be specified multiple times to mark multiple symbols as local.
312
313.. option:: --localize-symbols <filename>
314
315 Read a list of names from the file ``<filename>`` and mark defined non-common
316 symbols with those names as local in the output. In the file, each line
317 represents a single symbol, with leading and trailing whitespace ignored, as is
318 anything following a '#'. Can be specified multiple times to read names from
319 multiple files.
320
321.. option:: --output-target <format>, -O
322
323 Write the output as the specified format. See `SUPPORTED FORMATS`_ for a list
324 of valid ``<format>`` values. If unspecified, the output format is assumed to
325 be the same as the input file's format.
326
327.. option:: --prefix-alloc-sections <prefix>
328
329 Add ``<prefix>`` to the front of the names of all allocatable sections in the
330 output.
331
332.. option:: --prefix-symbols <prefix>
333
334 Add ``<prefix>`` to the front of every symbol name in the output.
335
336.. option:: --preserve-dates, -p
337
338 Preserve access and modification timestamps in the output.
339
340.. option:: --redefine-sym <old>=<new>
341
342 Rename symbols called ``<old>`` to ``<new>`` in the output. Can be specified
343 multiple times to rename multiple symbols.
344
345.. option:: --redefine-syms <filename>
346
347 Rename symbols in the output as described in the file ``<filename>``. In the
348 file, each line represents a single symbol to rename, with the old name and new
349 name separated by an equals sign. Leading and trailing whitespace is ignored,
350 as is anything following a '#'. Can be specified multiple times to read names
351 from multiple files.
352
353.. option:: --rename-section <old>=<new>[,<flag>,...]
354
355 Rename sections called ``<old>`` to ``<new>`` in the output, and apply any
356 specified ``<flag>`` values. See :option:`--set-section-flags` for a list of
357 supported flags. Can be specified multiple times to rename multiple sections.
358
359.. option:: --set-section-flags <section>=<flag>[,<flag>,...]
360
361 Set section properties in the output of section ``<section>`` based on the
362 specified ``<flag>`` values. Can be specified multiple times to update multiple
363 sections.
364
365 Following is a list of supported flags and their effects:
366
367 - `alloc` = add the `SHF_ALLOC` flag.
368 - `load` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
369 section.
370 - `readonly` = if this flag is not specified, add the `SHF_WRITE` flag.
371 - `code` = add the `SHF_EXECINSTR` flag.
372 - `merge` = add the `SHF_MERGE` flag.
373 - `strings` = add the `SHF_STRINGS` flag.
374 - `contents` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
375 section.
376
377 The following flags are also accepted, but are ignored for GNU compatibility:
378 `noload`, `debug`, `data`, `rom`, `share`.
379
380.. option:: --set-start-addr <addr>
381
382 Set the start address of the output to ``<addr>``. Overrides any previously
383 specified :option:`--change-start` or :option:`--adjust-start` options.
384
385.. option:: --split-dwo <dwo-file>
386
387 Equivalent to running :program:`llvm-objcopy` with :option:`--extract-dwo` and
388 ``<dwo-file>`` as the output file and no other options, and then with
389 :option:`--strip-dwo` on the input file.
390
391.. option:: --strip-dwo
392
393 Remove all DWARF .dwo sections from the output.
394
395.. option:: --strip-non-alloc
396
397 Remove from the output all non-allocatable sections that are not within
398 segments.
399
400.. option:: --strip-sections
401
402 Remove from the output all section headers and all section data not within
403 segments. Note that many tools will not be able to use an object without
404 section headers.
405
406.. option:: --target <format>, -F
407
408 Equivalent to :option:`--input-target` and :option:`--output-target` for the
409 specified format. See `SUPPORTED FORMATS`_ for a list of valid ``<format>``
410 values.
411
412.. option:: --weaken-symbol <symbol>, -W
413
414 Mark any global symbol named ``<symbol>`` as a weak symbol in the output. Can
415 be specified multiple times to mark multiple symbols as weak.
416
417.. option:: --weaken-symbols <filename>
418
419 Read a list of names from the file ``<filename>`` and mark global symbols with
420 those names as weak in the output. In the file, each line represents a single
421 symbol, with leading and trailing whitespace ignored, as is anything following
422 a '#'. Can be specified multiple times to read names from multiple files.
423
424.. option:: --weaken
425
426 Mark all defined global symbols as weak in the output.
427
428SUPPORTED FORMATS
429-----------------
430
431The following values are currently supported by :program:`llvm-objcopy` for the
432:option:`--input-target`, :option:`--output-target`, and :option:`--target`
433options. For GNU :program:`objcopy` compatibility, the values are all bfdnames.
434
435- `binary`
436- `ihex`
437- `elf32-i386`
438- `elf32-x86-64`
439- `elf64-x86-64`
440- `elf32-iamcu`
441- `elf32-littlearm`
442- `elf64-aarch64`
443- `elf64-littleaarch64`
444- `elf32-littleriscv`
445- `elf64-littleriscv`
446- `elf32-powerpc`
447- `elf32-powerpcle`
448- `elf64-powerpc`
449- `elf64-powerpcle`
450- `elf32-bigmips`
451- `elf32-ntradbigmips`
452- `elf32-ntradlittlemips`
453- `elf32-tradbigmips`
454- `elf32-tradlittlemips`
455- `elf64-tradbigmips`
456- `elf64-tradlittlemips`
457- `elf32-sparc`
458- `elf32-sparcel`
459
460Additionally, all targets except ``binary`` and ``ihex`` can have ``-freebsd``
461as a suffix.
462
463EXIT STATUS
464-----------
465
466:program:`llvm-objcopy` exits with a non-zero exit code if there is an error.
467Otherwise, it exits with code 0.
468
469BUGS
470----
471
472To report bugs, please visit <http://llvm.org/bugs/>.
473
474There is a known issue with :option:`--input-target` and :option:`--target`
475causing only ``binary`` and ``ihex`` formats to have any effect. Other values
476will be ignored and :program:`llvm-objcopy` will attempt to guess the input
477format.
478
479SEE ALSO
480--------
481
482:manpage:`llvm-strip(1)`