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 speci‐
119              fied 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       --update-section <name>=<file>
221              Replace the contents of the section <name>  with  contents  from
222              the file <file>. If the section <name> is part of a segment, the
223              new contents cannot be larger than the existing section.
224
225       --version, -V
226              Display the version of the llvm-objcopy executable.
227
228       --wildcard, -w
229              Allow wildcard syntax for symbol-related flags.  On  by  default
230              for section-related flags. Incompatible with --regex.
231
232              Wildcard syntax allows the following special symbols:
233
234                    ┌───────────────┬─────────────────────┬────────────┐
235                    │Character      │ Meaning             │ Equivalent │
236                    ├───────────────┼─────────────────────┼────────────┤
237*              │ Any number of char‐ │ .*         
238                    │               │ acters              │            │
239                    ├───────────────┼─────────────────────┼────────────┤
240?              │ Any single  charac‐ │ .          
241                    │               │ ter                 │            │
242                    ├───────────────┼─────────────────────┼────────────┤
243\              │ Escape   the   next │ \          
244                    │               │ character           │            │
245                    ├───────────────┼─────────────────────┼────────────┤
246[a-z]          │ Character class     │ [a-z]      
247                    ├───────────────┼─────────────────────┼────────────┤
248[!a-z], [^a-z] │ Negated   character │ [^a-z]     
249                    │               │ class               │            │
250                    └───────────────┴─────────────────────┴────────────┘
251
252              Additionally, starting a wildcard with '!' will prevent a match,
253              even if another flag matches. For example -w -N '*' -N '!x' will
254              strip all symbols except for x.
255
256              The  order  of wildcards does not matter. For example, -w -N '*'
257              -N '!x' is the same as -w -N '!x' -N '*'.
258
259       @<FILE>
260              Read  command-line  options  and  commands  from  response  file
261              <FILE>.
262

ELF-SPECIFIC OPTIONS

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

MACH-O-SPECIFIC OPTIONS

483       --keep-undefined
484              Keep  undefined  symbols,  even  if  they  would  otherwise   be
485              stripped.
486

COFF-SPECIFIC OPTIONS

488       --subsystem <name>[:<version>]
489              Set the PE subsystem, and optionally subsystem version.
490

SUPPORTED FORMATS

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

BINARY INPUT AND OUTPUT

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

EXIT STATUS

561       llvm-objcopy exits with a non-zero exit code  if  there  is  an  error.
562       Otherwise, it exits with code 0.
563

BUGS

565       To         report         bugs,         please         visit         <‐
566       https://github.com/llvm/llvm-project/labels/tools:llvm-objcopy/strip/>.
567
568       There is a known issue with --input-target and  --target  causing  only
569       binary  and  ihex  formats to have any effect. Other values will be ig‐
570       nored and llvm-objcopy will attempt to guess the input format.
571

SEE ALSO

573       llvm-strip(1)
574

AUTHOR

576       Maintained by the LLVM Team (https://llvm.org/).
577
579       2003-2023, LLVM Project
580
581
582
583
58417                                2023-11-28                   LLVM-OBJCOPY(1)
Impressum