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 de‐
72              fault.
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 re‐
100              name, 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       --set-section-flags <section>=<flag>[,<flag>,...]
122              Set section properties in the output of section <section>  based
123              on  the specified <flag> values. Can be specified multiple times
124              to update multiple sections.
125
126              Supported flag names are alloc, load, noload, readonly, exclude,
127              debug,  code, data, rom, share, contents, merge and strings. Not
128              all flags are meaningful for all object file formats.
129
130              For ELF objects, the flags have the following effects:
131
132alloc = add the SHF_ALLOC flag.
133
134load = if the section  has  SHT_NOBITS  type,  mark  it  as  a
135                SHT_PROGBITS section.
136
137readonly  =  if  this flag is not specified, add the SHF_WRITE
138                flag.
139
140exclude = add the SHF_EXCLUDE flag.
141
142code = add the SHF_EXECINSTR flag.
143
144merge = add the SHF_MERGE flag.
145
146strings = add the SHF_STRINGS flag.
147
148contents = if the section has SHT_NOBITS type, mark  it  as  a
149                SHT_PROGBITS section.
150
151              For COFF objects, the flags have the following effects:
152
153alloc  =  add  the  IMAGE_SCN_CNT_UNINITIALIZED_DATA  and  IM‐
154                AGE_SCN_MEM_READ flags, unless the load flag is specified.
155
156noload = add the IMAGE_SCN_LNK_REMOVE  and  IMAGE_SCN_MEM_READ
157                flags.
158
159readonly  =  if  this  flag  is  not  specified,  add  the IM‐
160                AGE_SCN_MEM_WRITE flag.
161
162exclude = add the IMAGE_SCN_LNK_REMOVE and  IMAGE_SCN_MEM_READ
163                flags.
164
165debug    =   add   the   IMAGE_SCN_CNT_INITIALIZED_DATA,   IM‐
166                AGE_SCN_MEM_DISCARDABLE and  IMAGE_SCN_MEM_READ flags.
167
168code = add the IMAGE_SCN_CNT_CODE,  IMAGE_SCN_MEM_EXECUTE  and
169                IMAGE_SCN_MEM_READ flags.
170
171data   =   add   the  IMAGE_SCN_CNT_INITIALIZED_DATA  and  IM‐
172                AGE_SCN_MEM_READ flags.
173
174share = add the  IMAGE_SCN_MEM_SHARED  and  IMAGE_SCN_MEM_READ
175                flags.
176
177       --strip-all-gnu
178              Remove all symbols, debug sections and relocations from the out‐
179              put. This option is  equivalent  to  GNU  objcopy's  --strip-all
180              switch.
181
182       --strip-all, -S
183              For  ELF objects, remove from the output all symbols and non-al‐
184              loc sections  not  within  segments,  except  for  .gnu.warning,
185              .ARM.attribute sections and the section name table.
186
187              For COFF and Mach-O objects, remove all symbols, debug sections,
188              and relocations from the output.
189
190       --strip-debug, -g
191              Remove all debug sections from the output.
192
193       --strip-symbol <symbol>, -N
194              Remove all symbols named <symbol> from the output. Can be speci‐
195              fied multiple times to remove multiple symbols.
196
197       --strip-symbols <filename>
198              Remove  all  symbols  whose names appear in the file <filename>,
199              from the output. In the file, each line represents a single sym‐
200              bol  name,  with  leading and trailing whitespace ignored, as is
201              anything following a '#'. Can be  specified  multiple  times  to
202              read names from multiple files.
203
204       --strip-unneeded-symbol <symbol>
205              Remove from the output all symbols named <symbol> that are local
206              or undefined and are not required by any relocation.
207
208       --strip-unneeded-symbols <filename>
209              Remove all symbols whose names appear in  the  file  <filename>,
210              from  the output, if they are local or undefined and are not re‐
211              quired by any relocation.  In the file, each line  represents  a
212              single  symbol  name,  with  leading and trailing whitespace ig‐
213              nored, as is anything following a '#'. Can be specified multiple
214              times to read names from multiple files.
215
216       --strip-unneeded
217              Remove  from  the output all local or undefined symbols that are
218              not required by relocations. Also remove all debug sections.
219
220       --version, -V
221              Display the version of the llvm-objcopy executable.
222
223       --wildcard, -w
224              Allow wildcard syntax for symbol-related flags.  On  by  default
225              for section-related flags. Incompatible with --regex.
226
227              Wildcard syntax allows the following special symbols:
228
229                    ┌───────────────┬─────────────────────┬────────────┐
230                    │Character      │ Meaning             │ Equivalent │
231                    ├───────────────┼─────────────────────┼────────────┤
232*              │ Any number of char‐ │ .*         
233                    │               │ acters              │            │
234                    ├───────────────┼─────────────────────┼────────────┤
235?              │ Any single  charac‐ │ .          
236                    │               │ ter                 │            │
237                    ├───────────────┼─────────────────────┼────────────┤
238\              │ Escape   the   next │ \          
239                    │               │ character           │            │
240                    ├───────────────┼─────────────────────┼────────────┤
241[a-z]          │ Character class     │ [a-z]      
242                    ├───────────────┼─────────────────────┼────────────┤
243[!a-z], [^a-z] │ Negated   character │ [^a-z]     
244                    │               │ class               │            │
245                    └───────────────┴─────────────────────┴────────────┘
246
247              Additionally, starting a wildcard with '!' will prevent a match,
248              even if another flag matches. For example -w -N '*' -N '!x' will
249              strip all symbols except for x.
250
251              The  order  of wildcards does not matter. For example, -w -N '*'
252              -N '!x' is the same as -w -N '!x' -N '*'.
253
254       @<FILE>
255              Read  command-line  options  and  commands  from  response  file
256              <FILE>.
257

ELF-SPECIFIC OPTIONS

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

SUPPORTED FORMATS

488       The following values are currently supported by  llvm-objcopy  for  the
489       --input-target,  --output-target, and --target options. For GNU objcopy
490       compatibility, the values are all bfdnames.
491
492binary
493
494ihex
495
496elf32-i386
497
498elf32-x86-64
499
500elf64-x86-64
501
502elf32-iamcu
503
504elf32-littlearm
505
506elf64-aarch64
507
508elf64-littleaarch64
509
510elf32-littleriscv
511
512elf64-littleriscv
513
514elf32-powerpc
515
516elf32-powerpcle
517
518elf64-powerpc
519
520elf64-powerpcle
521
522elf32-bigmips
523
524elf32-ntradbigmips
525
526elf32-ntradlittlemips
527
528elf32-tradbigmips
529
530elf32-tradlittlemips
531
532elf64-tradbigmips
533
534elf64-tradlittlemips
535
536elf32-sparc
537
538elf32-sparcel
539
540       Additionally, all targets except binary and ihex can have -freebsd as a
541       suffix.
542

BINARY INPUT AND OUTPUT

544       If  binary is used as the value for --input-target, the input file will
545       be embedded as a data section in an ELF relocatable object,  with  sym‐
546       bols   _binary_<file_name>_start,   _binary_<file_name>_end,  and  _bi‐
547       nary_<file_name>_size representing the start, end and size of the data,
548       where  <file_name>  is  the  path of the input file as specified on the
549       command line with non-alphanumeric characters converted to _.
550
551       If binary is used as the value for  --output-target,  the  output  file
552       will  be  a  raw  binary file, containing the memory image of the input
553       file.  Symbols and relocation information will be discarded. The  image
554       will start at the address of the first loadable section in the output.
555

EXIT STATUS

557       llvm-objcopy  exits  with  a  non-zero  exit code if there is an error.
558       Otherwise, it exits with code 0.
559

BUGS

561       To report bugs, please visit <https://bugs.llvm.org/>.
562
563       There is a known issue with --input-target and  --target  causing  only
564       binary  and  ihex  formats to have any effect. Other values will be ig‐
565       nored and llvm-objcopy will attempt to guess the input format.
566

SEE ALSO

568       llvm-strip(1)
569

AUTHOR

571       Maintained by the LLVM Team (https://llvm.org/).
572
574       2003-2023, LLVM Project
575
576
577
578
57911                                2023-07-20                   LLVM-OBJCOPY(1)
Impressum