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. Additionally, remove all debug sections.
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       --change-start <incr>, --adjust-start
304              Add <incr> to the program's start address. Can be specified mul‐
305              tiple times, in which case the values will  be  applied  cumula‐
306              tively.
307
308       --compress-debug-sections [<style>]
309              Compress DWARF debug sections in the output, using the specified
310              style.  Supported styles are zlib-gnu and zlib. Defaults to zlib
311              if no style is specified.
312
313       --decompress-debug-sections
314              Decompress any compressed DWARF debug sections in the output.
315
316       --discard-locals, -X
317              Remove local symbols starting with ".L" from the output.
318
319       --extract-dwo
320              Remove  all  sections  that are not DWARF .dwo sections from the
321              output.
322
323       --extract-main-partition
324              Extract the main partition from the output.
325
326       --extract-partition <name>
327              Extract the named partition from the output.
328
329       --globalize-symbol <symbol>
330              Mark any defined symbols named <symbol> as global symbols in the
331              output.   Can  be specified multiple times to mark multiple sym‐
332              bols.
333
334       --globalize-symbols <filename>
335              Read a list of names from the file <filename> and  mark  defined
336              symbols  with  those names as global in the output. In the file,
337              each line represents a single symbol, with leading and  trailing
338              whitespace ignored, as is anything following a '#'. Can be spec‐
339              ified multiple times to read names from multiple files.
340
341       --input-target <format>, -I
342              Read the input as the specified format.  See  SUPPORTED  FORMATS
343              for  a  list of valid <format> values. If unspecified, llvm-obj‐
344              copy will attempt to determine the format automatically.
345
346       --keep-file-symbols
347              Keep symbols of type STT_FILE, even if they would  otherwise  be
348              stripped.
349
350       --keep-global-symbol <symbol>
351              Make  all  symbols  local in the output, except for symbols with
352              the name <symbol>. Can be specified  multiple  times  to  ignore
353              multiple symbols.
354
355       --keep-global-symbols <filename>
356              Make  all  symbols local in the output, except for symbols named
357              in the file <filename>. In the file, each line represents a sin‐
358              gle  symbol, with leading and trailing whitespace ignored, as is
359              anything following a '#'. Can be  specified  multiple  times  to
360              read names from multiple files.
361
362       --keep-section <section>
363              When  removing  sections from the output, do not remove sections
364              named <section>. Can be specified multiple times to keep  multi‐
365              ple sections.
366
367       --keep-symbol <symbol>, -K
368              When  removing  symbols  from  the output, do not remove symbols
369              named <symbol>. Can be specified multiple times to keep multiple
370              symbols.
371
372       --keep-symbols <filename>
373              When  removing  symbols  from  the  output do not remove symbols
374              named in the file <filename>. In the file, each line  represents
375              a  single  symbol, with leading and trailing whitespace ignored,
376              as is anything following a '#'. Can be specified multiple  times
377              to read names from multiple files.
378
379       --localize-hidden
380              Make all symbols with hidden or internal visibility local in the
381              output.
382
383       --localize-symbol <symbol>, -L
384              Mark any defined non-common symbol named  <symbol>  as  a  local
385              symbol  in  the  output. Can be specified multiple times to mark
386              multiple symbols as local.
387
388       --localize-symbols <filename>
389              Read a list of names from the file <filename> and  mark  defined
390              non-common  symbols  with those names as local in the output. In
391              the file, each line represents a single symbol, with leading and
392              trailing whitespace ignored, as is anything following a '#'. Can
393              be specified multiple times to read names from multiple files.
394
395       --new-symbol-visibility <visibility>
396              Specify the visibility of the symbols automatically created when
397              using binary input or --add-symbol. Valid options are:
398
399default
400
401hidden
402
403internal
404
405protected
406
407              The default is default.
408
409       --output-target <format>, -O
410              Write  the output as the specified format. See SUPPORTED FORMATS
411              for a list of valid <format> values. If unspecified, the  output
412              format  is  assumed  to  be  the same as the value specified for
413              --input-target or the input file's format if that option is also
414              unspecified.
415
416       --prefix-alloc-sections <prefix>
417              Add  <prefix>  to the front of the names of all allocatable sec‐
418              tions in the output.
419
420       --prefix-symbols <prefix>
421              Add <prefix> to the front of every symbol name in the output.
422
423       --preserve-dates, -p
424              Preserve access and modification timestamps in the output.
425
426       --rename-section <old>=<new>[,<flag>,...]
427              Rename sections called <old> to <new> in the output,  and  apply
428              any  specified <flag> values. See --set-section-flags for a list
429              of supported flags. Can be specified multiple  times  to  rename
430              multiple sections.
431
432       --set-start-addr <addr>
433              Set  the  start  address  of the output to <addr>. Overrides any
434              previously specified --change-start or --adjust-start options.
435
436       --split-dwo <dwo-file>
437              Equivalent  to  running  llvm-objcopy  with  --extract-dwo   and
438              <dwo-file>  as  the  output  file and no other options, and then
439              with --strip-dwo on the input file.
440
441       --strip-dwo
442              Remove all DWARF .dwo sections from the output.
443
444       --strip-non-alloc
445              Remove from the output all non-allocatable sections that are not
446              within segments.
447
448       --strip-sections
449              Remove  from the output all section headers and all section data
450              not within segments. Note that many tools will not  be  able  to
451              use an object without section headers.
452
453       --target <format>, -F
454              Equivalent  to --input-target and --output-target for the speci‐
455              fied format. See SUPPORTED FORMATS for a list of valid  <format>
456              values.
457
458       --weaken-symbol <symbol>, -W
459              Mark  any  global  symbol named <symbol> as a weak symbol in the
460              output. Can be specified multiple times to mark multiple symbols
461              as weak.
462
463       --weaken-symbols <filename>
464              Read  a  list  of names from the file <filename> and mark global
465              symbols with those names as weak in the  output.  In  the  file,
466              each  line represents a single symbol, with leading and trailing
467              whitespace ignored, as is anything following a '#'. Can be spec‐
468              ified multiple times to read names from multiple files.
469
470       --weaken
471              Mark all defined global symbols as weak in the output.
472

MACH-O-SPECIFIC OPTIONS

474       --keep-undefined
475              Keep   undefined  symbols,  even  if  they  would  otherwise  be
476              stripped.
477

SUPPORTED FORMATS

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

BINARY INPUT AND OUTPUT

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

EXIT STATUS

548       llvm-objcopy  exits  with  a  non-zero  exit code if there is an error.
549       Otherwise, it exits with code 0.
550

BUGS

552       To report bugs, please visit <https://bugs.llvm.org/>.
553
554       There is a known issue with --input-target and  --target  causing  only
555       binary  and  ihex  formats to have any effect. Other values will be ig‐
556       nored and llvm-objcopy will attempt to guess the input format.
557

SEE ALSO

559       llvm-strip(1)
560

AUTHOR

562       Maintained by the LLVM Team (https://llvm.org/).
563
565       2003-2023, LLVM Project
566
567
568
569
57013                                2023-07-20                   LLVM-OBJCOPY(1)
Impressum