1LLVM-OBJCOPY(1)                      LLVM                      LLVM-OBJCOPY(1)
2
3
4

NAME

6       llvm-objcopy - object copying and editing tool
7

SYNOPSIS

9       llvm-objcopy [options] input [output]
10

DESCRIPTION

12       llvm-objcopy  is a tool to copy and manipulate objects. In basic usage,
13       it makes a semantic copy of the input to the output. If any options are
14       specified,  the  output may be modified along the way, e.g. by removing
15       sections.
16
17       If no output file is specified, the input file is modified in-place. If
18       "-"  is  specified  for the input file, the input is read from the pro‐
19       gram's standard input stream. If "-" is specified for the output  file,
20       the output is written to the standard output stream of the program.
21
22       If the input is an archive, any requested operations will be applied to
23       each archive member individually.
24
25       The tool is still in active development, but in most scenarios it works
26       as a drop-in replacement for GNU's objcopy.
27

GENERIC AND CROSS-PLATFORM OPTIONS

29       The  following options are either agnostic of the file format, or apply
30       to multiple file formats.
31
32       --add-gnu-debuglink <debug-file>
33              Add a .gnu_debuglink section for <debug-file> to the output.
34
35       --disable-deterministic-archives, -U
36              Use real values for UIDs, GIDs and timestamps when updating  ar‐
37              chive member headers.
38
39       --discard-all, -x
40              Remove  most  local symbols from the output. Different file for‐
41              mats may limit this to a subset of the local symbols. For  exam‐
42              ple,  file  and  section symbols in ELF objects will not be dis‐
43              carded.
44
45       --enable-deterministic-archives, -D
46              Enable deterministic mode when copying archives, i.e. use 0  for
47              archive  member  header  UIDs,  GIDs and timestamp fields. On by
48              default.
49
50       --help, -h
51              Print a summary of command line options.
52
53       --only-section <section>, -j
54              Remove all sections from the output, except for  sections  named
55              <section>.   Can  be  specified  multiple times to keep multiple
56              sections.
57
58       --regex
59              If specified,  symbol  and  section  names  specified  by  other
60              switches  are  treated as extended POSIX regular expression pat‐
61              terns.
62
63       --remove-section <section>, -R
64              Remove the specified section from the output. Can  be  specified
65              multiple times to remove multiple sections simultaneously.
66
67       --strip-all-gnu
68              Remove all symbols, debug sections and relocations from the out‐
69              put. This option is  equivalent  to  GNU  objcopy's  --strip-all
70              switch.
71
72       --strip-all, -S
73              For  ELF  objects,  remove  from  the  output  all  symbols  and
74              non-alloc sections not within segments, except for  .gnu.warning
75              sections and the section name table.
76
77              For  COFF objects, remove all symbols, debug sections, and relo‐
78              cations from the output.
79
80       --strip-debug, -g
81              Remove all debug sections from the output.
82
83       --strip-symbol <symbol>, -N
84              Remove all symbols named <symbol> from the output. Can be speci‐
85              fied multiple times to remove multiple symbols.
86
87       --strip-symbols <filename>
88              Remove  all  symbols  whose names appear in the file <filename>,
89              from the output. In the file, each line represents a single sym‐
90              bol  name,  with  leading and trailing whitespace ignored, as is
91              anything following a '#'. Can be  specified  multiple  times  to
92              read names from multiple files.
93
94       --strip-unneeded-symbol <symbol>
95              Remove from the output all symbols named <symbol> that are local
96              or undefined and are not required by any relocation.
97
98       --strip-unneeded-symbols <filename>
99              Remove all symbols whose names appear in  the  file  <filename>,
100              from  the  output,  if  they  are local or undefined and are not
101              required by any relocation.  In the file, each line represents a
102              single   symbol  name,  with  leading  and  trailing  whitespace
103              ignored, as is anything following a '#'. Can be specified multi‐
104              ple times to read names from multiple files.
105
106       --strip-unneeded
107              Remove  from  the output all local or undefined symbols that are
108              not required by relocations.
109
110       --version, -V
111              Display the version of this program.
112

COFF-SPECIFIC OPTIONS

114       The following options are implemented only for COFF  objects.  If  used
115       with  other objects, llvm-objcopy will either emit an error or silently
116       ignore them.
117
118       --only-keep-debug
119              Remove the contents of non-debug sections from the  output,  but
120              keep the section headers.
121

ELF-SPECIFIC OPTIONS

123       The  following  options  are  implemented only for ELF objects. If used
124       with other objects, llvm-objcopy will either emit an error or  silently
125       ignore them.
126
127       --add-section <section=file>
128              Add a section named <section> with the contents of <file> to the
129              output. The section will be of type SHT_NOTE, if the name starts
130              with  ".note". Otherwise, it will have type SHT_PROGBITS. Can be
131              specified multiple times to add multiple sections.
132
133       --add-symbol <name>=[<section>:]<value>[,<flags>]
134              Add a new symbol called <name> to the output  symbol  table,  in
135              the section named <section>, with value <value>. If <section> is
136              not specified, the symbol is added as an  absolute  symbol.  The
137              <flags> affect the symbol properties. Accepted values are:
138
139              · global = the symbol will have global binding.
140
141              · local = the symbol will have local binding.
142
143              · weak = the symbol will have weak binding.
144
145              · default = the symbol will have default visibility.
146
147              · hidden = the symbol will have hidden visibility.
148
149              · file = the symbol will be an STT_FILE symbol.
150
151              · section = the symbol will be an STT_SECTION symbol.
152
153              · object = the symbol will be an STT_OBJECT symbol.
154
155              · function = the symbol will be an STT_FUNC symbol.
156
157              · indirect-function  =  the symbol will be an STT_GNU_IFUNC sym‐
158                bol.
159
160              Additionally, the following  flags  are  accepted  but  ignored:
161              debug, constructor, warning, indirect, synthetic, unique-object,
162              before.
163
164              Can be specified multiple times to add multiple symbols.
165
166       --allow-broken-links
167              Allow llvm-objcopy to remove sections even  if  it  would  leave
168              invalid  section  references. Any invalid sh_link fields will be
169              set to zero.
170
171       --binary-architecture <arch>, -B
172              Specify the architecture to use, when transforming an  architec‐
173              ture-less  format (e.g. binary) to another format. Valid options
174              are:
175
176              · aarch64
177
178              · arm
179
180              · i386
181
182              · i386:x86-64
183
184              · mips
185
186              · powerpc:common64
187
188              · riscv:rv32
189
190              · riscv:rv64
191
192              · sparc
193
194              · sparcel
195
196              · x86-64
197
198       --build-id-link-dir <dir>
199              Set   the   directory   used   by   --build-id-link-input    and
200              --build-id-link-output.
201
202       --build-id-link-input <suffix>
203              Hard-link  the input to <dir>/xx/xxx<suffix>, where <dir> is the
204              directory specified by --build-id-link-dir.  The  path  used  is
205              derived from the hex build ID.
206
207       --build-id-link-output <suffix>
208              Hard-link the output to <dir>/xx/xxx<suffix>, where <dir> is the
209              directory specified by --build-id-link-dir.  The  path  used  is
210              derived from the hex build ID.
211
212       --change-start <incr>, --adjust-start
213              Add <incr> to the program's start address. Can be specified mul‐
214              tiple times, in which case the values will  be  applied  cumula‐
215              tively.
216
217       --compress-debug-sections [<style>]
218              Compress DWARF debug sections in the output, using the specified
219              style.  Supported styles are zlib-gnu and zlib. Defaults to zlib
220              if no style is specified.
221
222       --decompress-debug-sections
223              Decompress any compressed DWARF debug sections in the output.
224
225       --discard-locals, -X
226              Remove local symbols starting with ".L" from the output.
227
228       --dump-section <section>=<file>
229              Dump the contents of section <section> into the file <file>. Can
230              be specified multiple times to dump multiple sections to differ‐
231              ent  files.   <file>  is unrelated to the input and output files
232              provided to llvm-objcopy and as  such  the  normal  copying  and
233              editing  operations  will  still be performed. No operations are
234              performed on the sections prior to dumping them.
235
236       --extract-dwo
237              Remove all sections that are not DWARF .dwo  sections  from  the
238              output.
239
240       --extract-main-partition
241              Extract the main partition from the output.
242
243       --extract-partition <name>
244              Extract the named partition from the output.
245
246       --globalize-symbol <symbol>
247              Mark any defined symbols named <symbol> as global symbols in the
248              output.  Can be specified multiple times to mark  multiple  sym‐
249              bols.
250
251       --globalize-symbols <filename>
252              Read  a  list of names from the file <filename> and mark defined
253              symbols with those names as global in the output. In  the  file,
254              each  line represents a single symbol, with leading and trailing
255              whitespace ignored, as is anything following a '#'. Can be spec‐
256              ified multiple times to read names from multiple files.
257
258       --input-target <format>, -I
259              Read  the  input  as the specified format. See SUPPORTED FORMATS
260              for a list of valid <format> values. If  unspecified,  llvm-obj‐
261              copy will attempt to determine the format automatically.
262
263       --keep-file-symbols
264              Keep  symbols  of type STT_FILE, even if they would otherwise be
265              stripped.
266
267       --keep-global-symbol <symbol>
268              Make all symbols local in the output, except  for  symbols  with
269              the  name  <symbol>.  Can  be specified multiple times to ignore
270              multiple symbols.
271
272       --keep-global-symbols <filename>
273              Make all symbols local in the output, except for  symbols  named
274              in the file <filename>. In the file, each line represents a sin‐
275              gle symbol, with leading and trailing whitespace ignored, as  is
276              anything  following  a  '#'.  Can be specified multiple times to
277              read names from multiple files.
278
279       --keep-section <section>
280              When removing sections from the output, do not  remove  sections
281              named  <section>. Can be specified multiple times to keep multi‐
282              ple sections.
283
284       --keep-symbol <symbol>, -K
285              When removing symbols from the output,  do  not  remove  symbols
286              named <symbol>. Can be specified multiple times to keep multiple
287              symbols.
288
289       --keep-symbols <filename>
290              When removing symbols from the  output  do  not  remove  symbols
291              named  in the file <filename>. In the file, each line represents
292              a single symbol, with leading and trailing  whitespace  ignored,
293              as  is anything following a '#'. Can be specified multiple times
294              to read names from multiple files.
295
296       --localize-hidden
297              Make all symbols with hidden or internal visibility local in the
298              output.
299
300       --localize-symbol <symbol>, -L
301              Mark  any  defined  non-common  symbol named <symbol> as a local
302              symbol in the output. Can be specified multiple  times  to  mark
303              multiple symbols as local.
304
305       --localize-symbols <filename>
306              Read  a  list of names from the file <filename> and mark defined
307              non-common symbols with those names as local in the  output.  In
308              the file, each line represents a single symbol, with leading and
309              trailing whitespace ignored, as is anything following a '#'. Can
310              be specified multiple times to read names from multiple files.
311
312       --output-target <format>, -O
313              Write  the output as the specified format. See SUPPORTED FORMATS
314              for a list of valid <format> values. If unspecified, the  output
315              format is assumed to be the same as the input file's format.
316
317       --prefix-alloc-sections <prefix>
318              Add  <prefix>  to the front of the names of all allocatable sec‐
319              tions in the output.
320
321       --prefix-symbols <prefix>
322              Add <prefix> to the front of every symbol name in the output.
323
324       --preserve-dates, -p
325              Preserve access and modification timestamps in the output.
326
327       --redefine-sym <old>=<new>
328              Rename symbols called <old> to <new> in the output. Can be spec‐
329              ified multiple times to rename multiple symbols.
330
331       --redefine-syms <filename>
332              Rename  symbols  in  the  output as described in the file <file‐
333              name>. In the file, each line  represents  a  single  symbol  to
334              rename,  with  the  old name and new name separated by an equals
335              sign. Leading and trailing whitespace is ignored, as is anything
336              following  a  '#'. Can be specified multiple times to read names
337              from multiple files.
338
339       --rename-section <old>=<new>[,<flag>,...]
340              Rename sections called <old> to <new> in the output,  and  apply
341              any  specified <flag> values. See --set-section-flags for a list
342              of supported flags. Can be specified multiple  times  to  rename
343              multiple sections.
344
345       --set-section-flags <section>=<flag>[,<flag>,...]
346              Set  section properties in the output of section <section> based
347              on the specified <flag> values. Can be specified multiple  times
348              to update multiple sections.
349
350              Following is a list of supported flags and their effects:
351
352              · alloc = add the SHF_ALLOC flag.
353
354              · load  =  if  the  section  has  SHT_NOBITS  type, mark it as a
355                SHT_PROGBITS section.
356
357              · readonly = if this flag is not specified,  add  the  SHF_WRITE
358                flag.
359
360              · code = add the SHF_EXECINSTR flag.
361
362              · merge = add the SHF_MERGE flag.
363
364              · strings = add the SHF_STRINGS flag.
365
366              · contents  =  if  the section has SHT_NOBITS type, mark it as a
367                SHT_PROGBITS section.
368
369              The following flags are also accepted, but are ignored  for  GNU
370              compatibility: noload, debug, data, rom, share.
371
372       --set-start-addr <addr>
373              Set  the  start  address  of the output to <addr>. Overrides any
374              previously specified --change-start or --adjust-start options.
375
376       --split-dwo <dwo-file>
377              Equivalent  to  running  llvm-objcopy  with  --extract-dwo   and
378              <dwo-file>  as  the  output  file and no other options, and then
379              with --strip-dwo on the input file.
380
381       --strip-dwo
382              Remove all DWARF .dwo sections from the output.
383
384       --strip-non-alloc
385              Remove from the output all non-allocatable sections that are not
386              within segments.
387
388       --strip-sections
389              Remove  from the output all section headers and all section data
390              not within segments. Note that many tools will not  be  able  to
391              use an object without section headers.
392
393       --target <format>, -F
394              Equivalent  to --input-target and --output-target for the speci‐
395              fied format. See SUPPORTED FORMATS for a list of valid  <format>
396              values.
397
398       --weaken-symbol <symbol>, -W
399              Mark  any  global  symbol named <symbol> as a weak symbol in the
400              output. Can be specified multiple times to mark multiple symbols
401              as weak.
402
403       --weaken-symbols <filename>
404              Read  a  list  of names from the file <filename> and mark global
405              symbols with those names as weak in the  output.  In  the  file,
406              each  line represents a single symbol, with leading and trailing
407              whitespace ignored, as is anything following a '#'. Can be spec‐
408              ified multiple times to read names from multiple files.
409
410       --weaken
411              Mark all defined global symbols as weak in the output.
412

SUPPORTED FORMATS

414       The  following  values  are currently supported by llvm-objcopy for the
415       --input-target, --output-target, and --target options. For GNU  objcopy
416       compatibility, the values are all bfdnames.
417
418       · binary
419
420       · ihex
421
422       · elf32-i386
423
424       · elf32-x86-64
425
426       · elf64-x86-64
427
428       · elf32-iamcu
429
430       · elf32-littlearm
431
432       · elf64-aarch64
433
434       · elf64-littleaarch64
435
436       · elf32-littleriscv
437
438       · elf64-littleriscv
439
440       · elf32-powerpc
441
442       · elf32-powerpcle
443
444       · elf64-powerpc
445
446       · elf64-powerpcle
447
448       · elf32-bigmips
449
450       · elf32-ntradbigmips
451
452       · elf32-ntradlittlemips
453
454       · elf32-tradbigmips
455
456       · elf32-tradlittlemips
457
458       · elf64-tradbigmips
459
460       · elf64-tradlittlemips
461
462       · elf32-sparc
463
464       · elf32-sparcel
465
466       Additionally, all targets except binary and ihex can have -freebsd as a
467       suffix.
468

BINARY INPUT AND OUTPUT

470       If binary is used as the value for --input-target, the input file  will
471       be  embedded  as a data section in an ELF relocatable object, with sym‐
472       bols    _binary_<file_name>_start,     _binary_<file_name>_end,     and
473       _binary_<file_name>_size  representing  the  start, end and size of the
474       data, where <file_name> is the path of the input file as  specified  on
475       the command line with non-alphanumeric characters converted to _.
476
477       If  binary  is  used  as the value for --output-target, the output file
478       will be a raw binary file, containing the memory  image  of  the  input
479       file.   Symbols and relocation information will be discarded. The image
480       will start at the address of the first loadable section in the output.
481

EXIT STATUS

483       llvm-objcopy exits with a non-zero exit code  if  there  is  an  error.
484       Otherwise, it exits with code 0.
485

BUGS

487       To report bugs, please visit <http://llvm.org/bugs/>.
488
489       There  is  a  known issue with --input-target and --target causing only
490       binary and ihex formats to  have  any  effect.  Other  values  will  be
491       ignored and llvm-objcopy will attempt to guess the input format.
492

SEE ALSO

494       llvm-strip(1)
495

AUTHOR

497       Maintained by the LLVM Team (https://llvm.org/).
498
500       2003-2019, LLVM Project
501
502
503
504
5059                                 2019-09-19                   LLVM-OBJCOPY(1)
Impressum