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       --add-section <section=file>
36              Add a section named <section> with the contents of <file> to the
37              output. For ELF objects the section will be of type SHT_NOTE, if
38              the name starts with  ".note".  Otherwise,  it  will  have  type
39              SHT_PROGBITS.  Can  be  specified multiple times to add multiple
40              sections.
41
42              For MachO objects,  <section>  must  be  formatted  as  <segment
43              name>,<section name>.
44
45       --binary-architecture <arch>, -B
46              Ignored for compatibility.
47
48       --disable-deterministic-archives, -U
49              Use  real values for UIDs, GIDs and timestamps when updating ar‐
50              chive member headers.
51
52       --discard-all, -x
53              Remove most local symbols from the output. Different  file  for‐
54              mats  may limit this to a subset of the local symbols. For exam‐
55              ple, file and section symbols in ELF objects will  not  be  dis‐
56              carded.
57
58       --dump-section <section>=<file>
59              Dump the contents of section <section> into the file <file>. Can
60              be specified multiple times to dump multiple sections to differ‐
61              ent  files.   <file>  is unrelated to the input and output files
62              provided to llvm-objcopy and as  such  the  normal  copying  and
63              editing  operations  will  still be performed. No operations are
64              performed on the sections prior to dumping them.
65
66              For MachO objects,  <section>  must  be  formatted  as  <segment
67              name>,<section name>.
68
69       --enable-deterministic-archives, -D
70              Enable  deterministic mode when copying archives, i.e. use 0 for
71              archive member header UIDs, GIDs and  timestamp  fields.  On  by
72              default.
73
74       --help, -h
75              Print a summary of command line options.
76
77       --only-keep-debug
78              Produce  a debug file as the output that only preserves contents
79              of sections useful for debugging purposes.
80
81              For ELF objects, this removes the contents of SHF_ALLOC sections
82              that  are  not  SHT_NOTE by making them SHT_NOBITS and shrinking
83              the program headers where possible.
84
85       --only-section <section>, -j
86              Remove all sections from the output, except for  sections  named
87              <section>.   Can  be  specified  multiple times to keep multiple
88              sections.
89
90              For MachO objects,  <section>  must  be  formatted  as  <segment
91              name>,<section name>.
92
93       --redefine-sym <old>=<new>
94              Rename symbols called <old> to <new> in the output. Can be spec‐
95              ified multiple times to rename multiple symbols.
96
97       --redefine-syms <filename>
98              Rename symbols in the output as described  in  the  file  <file‐
99              name>.  In  the  file,  each  line represents a single symbol to
100              rename, with the old name and new name separated by  whitespace.
101              Leading  and trailing whitespace is ignored, as is anything fol‐
102              lowing a '#'. Can be specified multiple times to read names from
103              multiple files.
104
105       --regex
106              If  specified,  symbol  and  section  names  specified  by other
107              switches are treated as extended POSIX regular  expression  pat‐
108              terns.
109
110       --remove-section <section>, -R
111              Remove  the  specified section from the output. Can be specified
112              multiple times to remove multiple sections simultaneously.
113
114              For MachO objects,  <section>  must  be  formatted  as  <segment
115              name>,<section name>.
116
117       --set-section-alignment <section>=<align>
118              Set the alignment of section <section> to <align>`. Can be spec‐
119              ified multiple times to update multiple sections.
120
121       --strip-all-gnu
122              Remove all symbols, debug sections and relocations from the out‐
123              put.  This  option  is  equivalent  to GNU objcopy's --strip-all
124              switch.
125
126       --strip-all, -S
127              For  ELF  objects,  remove  from  the  output  all  symbols  and
128              non-alloc sections not within segments, except for .gnu.warning,
129              .ARM.attribute sections and the section name table.
130
131              For COFF and Mach-O objects, remove all symbols, debug sections,
132              and relocations from the output.
133
134       --strip-debug, -g
135              Remove all debug sections from the output.
136
137       --strip-symbol <symbol>, -N
138              Remove all symbols named <symbol> from the output. Can be speci‐
139              fied multiple times to remove multiple symbols.
140
141       --strip-symbols <filename>
142              Remove all symbols whose names appear in  the  file  <filename>,
143              from the output. In the file, each line represents a single sym‐
144              bol name, with leading and trailing whitespace  ignored,  as  is
145              anything  following  a  '#'.  Can be specified multiple times to
146              read names from multiple files.
147
148       --strip-unneeded-symbol <symbol>
149              Remove from the output all symbols named <symbol> that are local
150              or undefined and are not required by any relocation.
151
152       --strip-unneeded-symbols <filename>
153              Remove  all  symbols  whose names appear in the file <filename>,
154              from the output, if they are local  or  undefined  and  are  not
155              required by any relocation.  In the file, each line represents a
156              single  symbol  name,  with  leading  and  trailing   whitespace
157              ignored, as is anything following a '#'. Can be specified multi‐
158              ple times to read names from multiple files.
159
160       --strip-unneeded
161              Remove from the output all local or undefined symbols  that  are
162              not required by relocations. Also remove all debug sections.
163
164       --version, -V
165              Display the version of the llvm-objcopy executable.
166
167       @<FILE>
168              Read  command-line  options  and  commands  from  response  file
169              <FILE>.
170
171       --wildcard, -w
172              Allow wildcard syntax for symbol-related flags.  On  by  default
173              for section-related flags. Incompatible with --regex.
174
175              Wildcard syntax allows the following special symbols:
176
177                    ┌───────────────┬─────────────────────┬────────────┐
178                    │Character      │ Meaning             │ Equivalent │
179                    ├───────────────┼─────────────────────┼────────────┤
180*              │ Any number of char‐ │ .*         
181                    │               │ acters              │            │
182                    ├───────────────┼─────────────────────┼────────────┤
183?              │ Any single  charac‐ │ .          
184                    │               │ ter                 │            │
185                    ├───────────────┼─────────────────────┼────────────┤
186\              │ Escape   the   next │ \          
187                    │               │ character           │            │
188                    ├───────────────┼─────────────────────┼────────────┤
189[a-z]          │ Character class     │ [a-z]      
190                    ├───────────────┼─────────────────────┼────────────┤
191[!a-z], [^a-z] │ Negated   character │ [^a-z]     
192                    │               │ class               │            │
193                    └───────────────┴─────────────────────┴────────────┘
194
195              Additionally, starting a wildcard with '!' will prevent a match,
196              even if another flag matches. For example -w -N '*' -N '!x' will
197              strip all symbols except for x.
198
199              The  order  of wildcards does not matter. For example, -w -N '*'
200              -N '!x' is the same as -w -N '!x' -N '*'.
201

COFF-SPECIFIC OPTIONS

203       The following options are implemented only for COFF  objects.  If  used
204       with  other objects, llvm-objcopy will either emit an error or silently
205       ignore them.
206

ELF-SPECIFIC OPTIONS

208       The following options are implemented only for  ELF  objects.  If  used
209       with  other objects, llvm-objcopy will either emit an error or silently
210       ignore them.
211
212       --add-symbol <name>=[<section>:]<value>[,<flags>]
213              Add a new symbol called <name> to the output  symbol  table,  in
214              the section named <section>, with value <value>. If <section> is
215              not specified, the symbol is added as an  absolute  symbol.  The
216              <flags> affect the symbol properties. Accepted values are:
217
218              · global = the symbol will have global binding.
219
220              · local = the symbol will have local binding.
221
222              · weak = the symbol will have weak binding.
223
224              · default = the symbol will have default visibility.
225
226              · hidden = the symbol will have hidden visibility.
227
228              · protected = the symbol will have protected visibility.
229
230              · file = the symbol will be an STT_FILE symbol.
231
232              · section = the symbol will be an STT_SECTION symbol.
233
234              · object = the symbol will be an STT_OBJECT symbol.
235
236              · function = the symbol will be an STT_FUNC symbol.
237
238              · indirect-function  =  the symbol will be an STT_GNU_IFUNC sym‐
239                bol.
240
241              Additionally, the following  flags  are  accepted  but  ignored:
242              debug, constructor, warning, indirect, synthetic, unique-object,
243              before.
244
245              Can be specified multiple times to add multiple symbols.
246
247       --allow-broken-links
248              Allow llvm-objcopy to remove sections even  if  it  would  leave
249              invalid  section  references. Any invalid sh_link fields will be
250              set to zero.
251
252       --build-id-link-dir <dir>
253              Set   the   directory   used   by   --build-id-link-input    and
254              --build-id-link-output.
255
256       --build-id-link-input <suffix>
257              Hard-link  the input to <dir>/xx/xxx<suffix>, where <dir> is the
258              directory specified by --build-id-link-dir.  The  path  used  is
259              derived from the hex build ID.
260
261       --build-id-link-output <suffix>
262              Hard-link the output to <dir>/xx/xxx<suffix>, where <dir> is the
263              directory specified by --build-id-link-dir.  The  path  used  is
264              derived from the hex build ID.
265
266       --change-start <incr>, --adjust-start
267              Add <incr> to the program's start address. Can be specified mul‐
268              tiple times, in which case the values will  be  applied  cumula‐
269              tively.
270
271       --compress-debug-sections [<style>]
272              Compress DWARF debug sections in the output, using the specified
273              style.  Supported styles are zlib-gnu and zlib. Defaults to zlib
274              if no style is specified.
275
276       --decompress-debug-sections
277              Decompress any compressed DWARF debug sections in the output.
278
279       --discard-locals, -X
280              Remove local symbols starting with ".L" from the output.
281
282       --extract-dwo
283              Remove  all  sections  that are not DWARF .dwo sections from the
284              output.
285
286       --extract-main-partition
287              Extract the main partition from the output.
288
289       --extract-partition <name>
290              Extract the named partition from the output.
291
292       --globalize-symbol <symbol>
293              Mark any defined symbols named <symbol> as global symbols in the
294              output.   Can  be specified multiple times to mark multiple sym‐
295              bols.
296
297       --globalize-symbols <filename>
298              Read a list of names from the file <filename> and  mark  defined
299              symbols  with  those names as global in the output. In the file,
300              each line represents a single symbol, with leading and  trailing
301              whitespace ignored, as is anything following a '#'. Can be spec‐
302              ified multiple times to read names from multiple files.
303
304       --input-target <format>, -I
305              Read the input as the specified format.  See  SUPPORTED  FORMATS
306              for  a  list of valid <format> values. If unspecified, llvm-obj‐
307              copy will attempt to determine the format automatically.
308
309       --keep-file-symbols
310              Keep symbols of type STT_FILE, even if they would  otherwise  be
311              stripped.
312
313       --keep-global-symbol <symbol>
314              Make  all  symbols  local in the output, except for symbols with
315              the name <symbol>. Can be specified  multiple  times  to  ignore
316              multiple symbols.
317
318       --keep-global-symbols <filename>
319              Make  all  symbols local in the output, except for symbols named
320              in the file <filename>. In the file, each line represents a sin‐
321              gle  symbol, with leading and trailing whitespace ignored, as is
322              anything following a '#'. Can be  specified  multiple  times  to
323              read names from multiple files.
324
325       --keep-section <section>
326              When  removing  sections from the output, do not remove sections
327              named <section>. Can be specified multiple times to keep  multi‐
328              ple sections.
329
330       --keep-symbol <symbol>, -K
331              When  removing  symbols  from  the output, do not remove symbols
332              named <symbol>. Can be specified multiple times to keep multiple
333              symbols.
334
335       --keep-symbols <filename>
336              When  removing  symbols  from  the  output do not remove symbols
337              named in the file <filename>. In the file, each line  represents
338              a  single  symbol, with leading and trailing whitespace ignored,
339              as is anything following a '#'. Can be specified multiple  times
340              to read names from multiple files.
341
342       --localize-hidden
343              Make all symbols with hidden or internal visibility local in the
344              output.
345
346       --localize-symbol <symbol>, -L
347              Mark any defined non-common symbol named  <symbol>  as  a  local
348              symbol  in  the  output. Can be specified multiple times to mark
349              multiple symbols as local.
350
351       --localize-symbols <filename>
352              Read a list of names from the file <filename> and  mark  defined
353              non-common  symbols  with those names as local in the output. In
354              the file, each line represents a single symbol, with leading and
355              trailing whitespace ignored, as is anything following a '#'. Can
356              be specified multiple times to read names from multiple files.
357
358       --new-symbol-visibility <visibility>
359              Specify the visibility of the symbols automatically created when
360              using binary input or --add-symbol. Valid options are:
361
362              · default
363
364              · hidden
365
366              · internal
367
368              · protected
369
370              The default is default.
371
372       --output-target <format>, -O
373              Write  the output as the specified format. See SUPPORTED FORMATS
374              for a list of valid <format> values. If unspecified, the  output
375              format is assumed to be the same as the input file's format.
376
377       --prefix-alloc-sections <prefix>
378              Add  <prefix>  to the front of the names of all allocatable sec‐
379              tions in the output.
380
381       --prefix-symbols <prefix>
382              Add <prefix> to the front of every symbol name in the output.
383
384       --preserve-dates, -p
385              Preserve access and modification timestamps in the output.
386
387       --rename-section <old>=<new>[,<flag>,...]
388              Rename sections called <old> to <new> in the output,  and  apply
389              any  specified <flag> values. See --set-section-flags for a list
390              of supported flags. Can be specified multiple  times  to  rename
391              multiple sections.
392
393       --set-section-flags <section>=<flag>[,<flag>,...]
394              Set  section properties in the output of section <section> based
395              on the specified <flag> values. Can be specified multiple  times
396              to update multiple sections.
397
398              Following is a list of supported flags and their effects:
399
400              · alloc = add the SHF_ALLOC flag.
401
402              · load  =  if  the  section  has  SHT_NOBITS  type, mark it as a
403                SHT_PROGBITS section.
404
405              · readonly = if this flag is not specified,  add  the  SHF_WRITE
406                flag.
407
408              · code = add the SHF_EXECINSTR flag.
409
410              · merge = add the SHF_MERGE flag.
411
412              · strings = add the SHF_STRINGS flag.
413
414              · contents  =  if  the section has SHT_NOBITS type, mark it as a
415                SHT_PROGBITS section.
416
417              The following flags are also accepted, but are ignored  for  GNU
418              compatibility: noload, debug, data, rom, share.
419
420       --set-start-addr <addr>
421              Set  the  start  address  of the output to <addr>. Overrides any
422              previously specified --change-start or --adjust-start options.
423
424       --split-dwo <dwo-file>
425              Equivalent  to  running  llvm-objcopy  with  --extract-dwo   and
426              <dwo-file>  as  the  output  file and no other options, and then
427              with --strip-dwo on the input file.
428
429       --strip-dwo
430              Remove all DWARF .dwo sections from the output.
431
432       --strip-non-alloc
433              Remove from the output all non-allocatable sections that are not
434              within segments.
435
436       --strip-sections
437              Remove  from the output all section headers and all section data
438              not within segments. Note that many tools will not  be  able  to
439              use an object without section headers.
440
441       --target <format>, -F
442              Equivalent  to --input-target and --output-target for the speci‐
443              fied format. See SUPPORTED FORMATS for a list of valid  <format>
444              values.
445
446       --weaken-symbol <symbol>, -W
447              Mark  any  global  symbol named <symbol> as a weak symbol in the
448              output. Can be specified multiple times to mark multiple symbols
449              as weak.
450
451       --weaken-symbols <filename>
452              Read  a  list  of names from the file <filename> and mark global
453              symbols with those names as weak in the  output.  In  the  file,
454              each  line represents a single symbol, with leading and trailing
455              whitespace ignored, as is anything following a '#'. Can be spec‐
456              ified multiple times to read names from multiple files.
457
458       --weaken
459              Mark all defined global symbols as weak in the output.
460

SUPPORTED FORMATS

462       The  following  values  are currently supported by llvm-objcopy for the
463       --input-target, --output-target, and --target options. For GNU  objcopy
464       compatibility, the values are all bfdnames.
465
466       · binary
467
468       · ihex
469
470       · elf32-i386
471
472       · elf32-x86-64
473
474       · elf64-x86-64
475
476       · elf32-iamcu
477
478       · elf32-littlearm
479
480       · elf64-aarch64
481
482       · elf64-littleaarch64
483
484       · elf32-littleriscv
485
486       · elf64-littleriscv
487
488       · elf32-powerpc
489
490       · elf32-powerpcle
491
492       · elf64-powerpc
493
494       · elf64-powerpcle
495
496       · elf32-bigmips
497
498       · elf32-ntradbigmips
499
500       · elf32-ntradlittlemips
501
502       · elf32-tradbigmips
503
504       · elf32-tradlittlemips
505
506       · elf64-tradbigmips
507
508       · elf64-tradlittlemips
509
510       · elf32-sparc
511
512       · elf32-sparcel
513
514       Additionally, all targets except binary and ihex can have -freebsd as a
515       suffix.
516

BINARY INPUT AND OUTPUT

518       If binary is used as the value for --input-target, the input file  will
519       be  embedded  as a data section in an ELF relocatable object, with sym‐
520       bols    _binary_<file_name>_start,     _binary_<file_name>_end,     and
521       _binary_<file_name>_size  representing  the  start, end and size of the
522       data, where <file_name> is the path of the input file as  specified  on
523       the command line with non-alphanumeric characters converted to _.
524
525       If  binary  is  used  as the value for --output-target, the output file
526       will be a raw binary file, containing the memory  image  of  the  input
527       file.   Symbols and relocation information will be discarded. The image
528       will start at the address of the first loadable section in the output.
529

EXIT STATUS

531       llvm-objcopy exits with a non-zero exit code  if  there  is  an  error.
532       Otherwise, it exits with code 0.
533

BUGS

535       To report bugs, please visit <http://llvm.org/bugs/>.
536
537       There  is  a  known issue with --input-target and --target causing only
538       binary and ihex formats to  have  any  effect.  Other  values  will  be
539       ignored and llvm-objcopy will attempt to guess the input format.
540

SEE ALSO

542       llvm-strip(1)
543

AUTHOR

545       Maintained by the LLVM Team (https://llvm.org/).
546
548       2003-2020, LLVM Project
549
550
551
552
55310                                2020-08-04                   LLVM-OBJCOPY(1)
Impressum