llvm/docs/CommandGuide/llvm-objcopy.rst

   1 llvm-objcopy - object copying and editing tool
   2 ==============================================
   3
   4 .. program:: llvm-objcopy
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-objcopy` [*options*] *input* [*output*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 :program:`llvm-objcopy` is a tool to copy and manipulate objects. In basic
  15 usage, it makes a semantic copy of the input to the output. If any options are
  16 specified, the output may be modified along the way, e.g. by removing sections.
  17
  18 If no output file is specified, the input file is modified in-place. If "-" is
  19 specified for the input file, the input is read from the program's standard
  20 input stream. If "-" is specified for the output file, the output is written to
  21 the standard output stream of the program.
  22
  23 If the input is an archive, any requested operations will be applied to each
  24 archive member individually.
  25
  26 The tool is still in active development, but in most scenarios it works as a
  27 drop-in replacement for GNU's :program:`objcopy`.
  28
  29 GENERIC AND CROSS-PLATFORM OPTIONS
  30 ----------------------------------
  31
  32 The following options are either agnostic of the file format, or apply to
  33 multiple file formats.
  34
  35 .. option:: --add-gnu-debuglink <debug-file>
  36
  37  Add a .gnu_debuglink section for ``<debug-file>`` to the output.
  38
  39 .. option:: --add-section <section=file>
  40
  41  Add a section named ``<section>`` with the contents of ``<file>`` to the
  42  output. For ELF objects the section will be of type `SHT_NOTE`, if the name
  43  starts with ".note". Otherwise, it will have type `SHT_PROGBITS`. Can be
  44  specified multiple times to add multiple sections.
  45
  46  For MachO objects, ``<section>`` must be formatted as
  47  ``<segment name>,<section name>``.
  48
  49 .. option:: --binary-architecture <arch>, -B
  50
  51  Ignored for compatibility.
  52
  53 .. option:: --disable-deterministic-archives, -U
  54
  55  Use real values for UIDs, GIDs and timestamps when updating archive member
  56  headers.
  57
  58 .. option:: --discard-all, -x
  59
  60  Remove most local symbols from the output. Different file formats may limit
  61  this to a subset of the local symbols. For example, file and section symbols in
  62  ELF objects will not be discarded. Additionally, remove all debug sections.
  63
  64 .. option:: --dump-section <section>=<file>
  65
  66  Dump the contents of section ``<section>`` into the file ``<file>``. Can be
  67  specified multiple times to dump multiple sections to different files.
  68  ``<file>`` is unrelated to the input and output files provided to
  69  :program:`llvm-objcopy` and as such the normal copying and editing
  70  operations will still be performed. No operations are performed on the sections
  71  prior to dumping them.
  72
  73  For MachO objects, ``<section>`` must be formatted as
  74  ``<segment name>,<section name>``.
  75
  76 .. option:: --enable-deterministic-archives, -D
  77
  78  Enable deterministic mode when copying archives, i.e. use 0 for archive member
  79  header UIDs, GIDs and timestamp fields. On by default.
  80
  81 .. option:: --help, -h
  82
  83  Print a summary of command line options.
  84
  85 .. option:: --only-keep-debug
  86
  87  Produce a debug file as the output that only preserves contents of sections
  88  useful for debugging purposes.
  89
  90  For ELF objects, this removes the contents of `SHF_ALLOC` sections that are not
  91  `SHT_NOTE` by making them `SHT_NOBITS` and shrinking the program headers where
  92  possible.
  93
  94 .. option:: --only-section <section>, -j
  95
  96  Remove all sections from the output, except for sections named ``<section>``.
  97  Can be specified multiple times to keep multiple sections.
  98
  99  For MachO objects, ``<section>`` must be formatted as
 100  ``<segment name>,<section name>``.
 101
 102 .. option:: --redefine-sym <old>=<new>
 103
 104  Rename symbols called ``<old>`` to ``<new>`` in the output. Can be specified
 105  multiple times to rename multiple symbols.
 106
 107 .. option:: --redefine-syms <filename>
 108
 109  Rename symbols in the output as described in the file ``<filename>``. In the
 110  file, each line represents a single symbol to rename, with the old name and new
 111  name separated by whitespace. Leading and trailing whitespace is ignored, as is
 112  anything following a '#'. Can be specified multiple times to read names from
 113  multiple files.
 114
 115 .. option:: --regex
 116
 117  If specified, symbol and section names specified by other switches are treated
 118  as extended POSIX regular expression patterns.
 119
 120 .. option:: --remove-section <section>, -R
 121
 122  Remove the specified section from the output. Can be specified multiple times
 123  to remove multiple sections simultaneously.
 124
 125  For MachO objects, ``<section>`` must be formatted as
 126  ``<segment name>,<section name>``.
 127
 128 .. option:: --set-section-alignment <section>=<align>
 129
 130  Set the alignment of section ``<section>`` to ``<align>``. Can be specified
 131  multiple times to update multiple sections.
 132
 133 .. option:: --set-section-flags <section>=<flag>[,<flag>,...]
 134
 135  Set section properties in the output of section ``<section>`` based on the
 136  specified ``<flag>`` values. Can be specified multiple times to update multiple
 137  sections.
 138
 139  Supported flag names are `alloc`, `load`, `noload`, `readonly`, `exclude`,
 140  `debug`, `code`, `data`, `rom`, `share`, `contents`, `merge`, `strings`, and
 141  `large`. Not all flags are meaningful for all object file formats or target
 142  architectures.
 143
 144  For ELF objects, the flags have the following effects:
 145
 146  - `alloc` = add the `SHF_ALLOC` flag.
 147  - `load` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
 148    section.
 149  - `readonly` = if this flag is not specified, add the `SHF_WRITE` flag.
 150  - `exclude` = add the `SHF_EXCLUDE` flag.
 151  - `code` = add the `SHF_EXECINSTR` flag.
 152  - `merge` = add the `SHF_MERGE` flag.
 153  - `strings` = add the `SHF_STRINGS` flag.
 154  - `contents` = if the section has `SHT_NOBITS` type, mark it as a `SHT_PROGBITS`
 155    section.
 156  - `large` = add the `SHF_X86_64_LARGE` on x86_64; rejected if the target
 157    architecture is not x86_64.
 158
 159  For COFF objects, the flags have the following effects:
 160
 161  - `alloc` = add the `IMAGE_SCN_CNT_UNINITIALIZED_DATA` and `IMAGE_SCN_MEM_READ`
 162    flags, unless the `load` flag is specified.
 163  - `noload` = add the `IMAGE_SCN_LNK_REMOVE` and `IMAGE_SCN_MEM_READ` flags.
 164  - `readonly` = if this flag is not specified, add the `IMAGE_SCN_MEM_WRITE`
 165    flag.
 166  - `exclude` = add the `IMAGE_SCN_LNK_REMOVE` and `IMAGE_SCN_MEM_READ` flags.
 167  - `debug` = add the `IMAGE_SCN_CNT_INITIALIZED_DATA`,
 168    `IMAGE_SCN_MEM_DISCARDABLE` and  `IMAGE_SCN_MEM_READ` flags.
 169  - `code` = add the `IMAGE_SCN_CNT_CODE`, `IMAGE_SCN_MEM_EXECUTE` and
 170    `IMAGE_SCN_MEM_READ` flags.
 171  - `data` = add the `IMAGE_SCN_CNT_INITIALIZED_DATA` and `IMAGE_SCN_MEM_READ`
 172    flags.
 173  - `share` = add the `IMAGE_SCN_MEM_SHARED` and `IMAGE_SCN_MEM_READ` flags.
 174
 175 .. option:: --strip-all-gnu
 176
 177  Remove all symbols, debug sections and relocations from the output. This option
 178  is equivalent to GNU :program:`objcopy`'s ``--strip-all`` switch.
 179
 180 .. option:: --strip-all, -S
 181
 182  For ELF objects, remove from the output all symbols and non-alloc sections not
 183  within segments, except for .gnu.warning, .ARM.attribute sections and the
 184  section name table.
 185
 186  For COFF and Mach-O objects, remove all symbols, debug sections, and
 187  relocations from the output.
 188
 189 .. option:: --strip-debug, -g
 190
 191  Remove all debug sections from the output.
 192
 193 .. option:: --strip-symbol <symbol>, -N
 194
 195  Remove all symbols named ``<symbol>`` from the output. Can be specified
 196  multiple times to remove multiple symbols.
 197
 198 .. option:: --strip-symbols <filename>
 199
 200  Remove all symbols whose names appear in the file ``<filename>``, from the
 201  output. In the file, each line represents a single symbol name, with leading
 202  and trailing whitespace ignored, as is anything following a '#'. Can be
 203  specified multiple times to read names from multiple files.
 204
 205 .. option:: --strip-unneeded-symbol <symbol>
 206
 207  Remove from the output all symbols named ``<symbol>`` that are local or
 208  undefined and are not required by any relocation.
 209
 210 .. option:: --strip-unneeded-symbols <filename>
 211
 212  Remove all symbols whose names appear in the file ``<filename>``, from the
 213  output, if they are local or undefined and are not required by any relocation.
 214  In the file, each line represents a single symbol name, with leading and
 215  trailing whitespace ignored, as is anything following a '#'. Can be specified
 216  multiple times to read names from multiple files.
 217
 218 .. option:: --strip-unneeded
 219
 220  Remove from the output all local or undefined symbols that are not required by
 221  relocations. Also remove all debug sections.
 222
 223 .. option:: --update-section <name>=<file>
 224
 225  Replace the contents of the section ``<name>`` with contents from the file
 226  ``<file>``. If the section ``<name>`` is part of a segment, the new contents
 227  cannot be larger than the existing section.
 228
 229 .. option:: --version, -V
 230
 231  Display the version of the :program:`llvm-objcopy` executable.
 232
 233 .. option:: --wildcard, -w
 234
 235   Allow wildcard syntax for symbol-related flags. On by default for
 236   section-related flags. Incompatible with --regex.
 237
 238   Wildcard syntax allows the following special symbols:
 239
 240   ====================== ========================= ==================
 241    Character              Meaning                   Equivalent
 242   ====================== ========================= ==================
 243   ``*``                  Any number of characters  ``.*``
 244   ``?``                  Any single character      ``.``
 245   ``\``                  Escape the next character ``\``
 246   ``[a-z]``              Character class           ``[a-z]``
 247   ``[!a-z]``, ``[^a-z]`` Negated character class   ``[^a-z]``
 248   ====================== ========================= ==================
 249
 250   Additionally, starting a wildcard with '!' will prevent a match, even if
 251   another flag matches. For example ``-w -N '*' -N '!x'`` will strip all symbols
 252   except for ``x``.
 253
 254   The order of wildcards does not matter. For example, ``-w -N '*' -N '!x'`` is
 255   the same as ``-w -N '!x' -N '*'``.
 256
 257 .. option:: @<FILE>
 258
 259  Read command-line options and commands from response file `<FILE>`.
 260
 261 ELF-SPECIFIC OPTIONS
 262 --------------------
 263
 264 The following options are implemented only for ELF objects. If used with other
 265 objects, :program:`llvm-objcopy` will either emit an error or silently ignore
 266 them.
 267
 268 .. option:: --add-symbol <name>=[<section>:]<value>[,<flags>]
 269
 270  Add a new symbol called ``<name>`` to the output symbol table, in the section
 271  named ``<section>``, with value ``<value>``. If ``<section>`` is not specified,
 272  the symbol is added as an absolute symbol. The ``<flags>`` affect the symbol
 273  properties. Accepted values are:
 274
 275  - `global` = the symbol will have global binding.
 276  - `local` = the symbol will have local binding.
 277  - `weak` = the symbol will have weak binding.
 278  - `default` = the symbol will have default visibility.
 279  - `hidden` = the symbol will have hidden visibility.
 280  - `protected` = the symbol will have protected visibility.
 281  - `file` = the symbol will be an `STT_FILE` symbol.
 282  - `section` = the symbol will be an `STT_SECTION` symbol.
 283  - `object` = the symbol will be an `STT_OBJECT` symbol.
 284  - `function` = the symbol will be an `STT_FUNC` symbol.
 285  - `indirect-function` = the symbol will be an `STT_GNU_IFUNC` symbol.
 286
 287  Additionally, the following flags are accepted but ignored: `debug`,
 288  `constructor`, `warning`, `indirect`, `synthetic`, `unique-object`, `before`.
 289
 290  Can be specified multiple times to add multiple symbols.
 291
 292 .. option:: --allow-broken-links
 293
 294  Allow :program:`llvm-objcopy` to remove sections even if it would leave invalid
 295  section references. Any invalid sh_link fields will be set to zero.
 296
 297 .. option:: --change-start <incr>, --adjust-start
 298
 299  Add ``<incr>`` to the program's start address. Can be specified multiple
 300  times, in which case the values will be applied cumulatively.
 301
 302 .. option:: --compress-debug-sections [<format>]
 303
 304  Compress DWARF debug sections in the output, using the specified format.
 305  Supported formats are ``zlib`` and ``zstd``. Use ``zlib`` if ``<format>`` is omitted.
 306
 307 .. option:: --decompress-debug-sections
 308
 309  Decompress any compressed DWARF debug sections in the output.
 310
 311 .. option:: --discard-locals, -X
 312
 313  Remove local symbols starting with ".L" from the output.
 314
 315 .. option:: --extract-dwo
 316
 317  Remove all sections that are not DWARF .dwo sections from the output.
 318
 319 .. option:: --extract-main-partition
 320
 321  Extract the main partition from the output.
 322
 323 .. option:: --extract-partition <name>
 324
 325  Extract the named partition from the output.
 326
 327 .. option:: --globalize-symbol <symbol>
 328
 329  Mark any defined symbols named ``<symbol>`` as global symbols in the output.
 330  Can be specified multiple times to mark multiple symbols.
 331
 332 .. option:: --globalize-symbols <filename>
 333
 334  Read a list of names from the file ``<filename>`` and mark defined symbols with
 335  those names as global in the output. In the file, each line represents a single
 336  symbol, with leading and trailing whitespace ignored, as is anything following
 337  a '#'. Can be specified multiple times to read names from multiple files.
 338
 339 .. option:: --input-target <format>, -I
 340
 341  Read the input as the specified format. See `SUPPORTED FORMATS`_ for a list of
 342  valid ``<format>`` values. If unspecified, :program:`llvm-objcopy` will attempt
 343  to determine the format automatically.
 344
 345 .. option:: --keep-file-symbols
 346
 347  Keep symbols of type `STT_FILE`, even if they would otherwise be stripped.
 348
 349 .. option:: --keep-global-symbol <symbol>, -G
 350
 351  Make all symbols local in the output, except for symbols with the name
 352  ``<symbol>``. Can be specified multiple times to ignore multiple symbols.
 353
 354 .. option:: --keep-global-symbols <filename>
 355
 356  Make all symbols local in the output, except for symbols named in the file
 357  ``<filename>``. In the file, each line represents a single symbol, with leading
 358  and trailing whitespace ignored, as is anything following a '#'. Can be
 359  specified multiple times to read names from multiple files.
 360
 361 .. option:: --keep-section <section>
 362
 363  When removing sections from the output, do not remove sections named
 364  ``<section>``. Can be specified multiple times to keep multiple sections.
 365
 366 .. option:: --keep-symbol <symbol>, -K
 367
 368  When removing symbols from the output, do not remove symbols named
 369  ``<symbol>``. Can be specified multiple times to keep multiple symbols.
 370
 371 .. option:: --keep-symbols <filename>
 372
 373  When removing symbols from the output do not remove symbols named in the file
 374  ``<filename>``. In the file, each line represents a single symbol, with leading
 375  and trailing whitespace ignored, as is anything following a '#'. Can be
 376  specified multiple times to read names from multiple files.
 377
 378 .. option:: --localize-hidden
 379
 380  Make all symbols with hidden or internal visibility local in the output.
 381
 382 .. option:: --localize-symbol <symbol>, -L
 383
 384  Mark any defined non-common symbol named ``<symbol>`` as a local symbol in the
 385  output. Can be specified multiple times to mark multiple symbols as local.
 386
 387 .. option:: --localize-symbols <filename>
 388
 389  Read a list of names from the file ``<filename>`` and mark defined non-common
 390  symbols with those names as local in the output. In the file, each line
 391  represents a single symbol, with leading and trailing whitespace ignored, as is
 392  anything following a '#'. Can be specified multiple times to read names from
 393  multiple files.
 394
 395 .. option:: --new-symbol-visibility <visibility>
 396
 397  Specify the visibility of the symbols automatically created when using binary
 398  input or :option:`--add-symbol`. Valid options are:
 399
 400  - `default`
 401  - `hidden`
 402  - `internal`
 403  - `protected`
 404
 405  The default is `default`.
 406
 407 .. option:: --output-target <format>, -O
 408
 409  Write the output as the specified format. See `SUPPORTED FORMATS`_ for a list
 410  of valid ``<format>`` values. If unspecified, the output format is assumed to
 411  be the same as the value specified for :option:`--input-target` or the input
 412  file's format if that option is also unspecified.
 413
 414 .. option:: --prefix-alloc-sections <prefix>
 415
 416  Add ``<prefix>`` to the front of the names of all allocatable sections in the
 417  output.
 418
 419 .. option:: --prefix-symbols <prefix>
 420
 421  Add ``<prefix>`` to the front of every symbol name in the output.
 422
 423 .. option:: --preserve-dates, -p
 424
 425  Preserve access and modification timestamps in the output.
 426
 427 .. option:: --rename-section <old>=<new>[,<flag>,...]
 428
 429  Rename sections called ``<old>`` to ``<new>`` in the output, and apply any
 430  specified ``<flag>`` values. See :option:`--set-section-flags` for a list of
 431  supported flags. Can be specified multiple times to rename multiple sections.
 432
 433 .. option:: --set-section-type <section>=<type>
 434
 435  Set the type of section ``<section>`` to the integer ``<type>``. Can be
 436  specified multiple times to update multiple sections.
 437
 438 .. option:: --set-start-addr <addr>
 439
 440  Set the start address of the output to ``<addr>``. Overrides any previously
 441  specified :option:`--change-start` or :option:`--adjust-start` options.
 442
 443 .. option:: --split-dwo <dwo-file>
 444
 445  Equivalent to running :program:`llvm-objcopy` with :option:`--extract-dwo` and
 446  ``<dwo-file>`` as the output file and no other options, and then with
 447  :option:`--strip-dwo` on the input file.
 448
 449 .. option:: --strip-dwo
 450
 451  Remove all DWARF .dwo sections from the output.
 452
 453 .. option:: --strip-non-alloc
 454
 455  Remove from the output all non-allocatable sections that are not within
 456  segments.
 457
 458 .. option:: --strip-sections
 459
 460  Remove from the output all section headers and all section data not within
 461  segments. Note that many tools will not be able to use an object without
 462  section headers.
 463
 464 .. option:: --target <format>, -F
 465
 466  Equivalent to :option:`--input-target` and :option:`--output-target` for the
 467  specified format. See `SUPPORTED FORMATS`_ for a list of valid ``<format>``
 468  values.
 469
 470 .. option:: --weaken-symbol <symbol>, -W
 471
 472  Mark any global symbol named ``<symbol>`` as a weak symbol in the output. Can
 473  be specified multiple times to mark multiple symbols as weak.
 474
 475 .. option:: --weaken-symbols <filename>
 476
 477  Read a list of names from the file ``<filename>`` and mark global symbols with
 478  those names as weak in the output. In the file, each line represents a single
 479  symbol, with leading and trailing whitespace ignored, as is anything following
 480  a '#'. Can be specified multiple times to read names from multiple files.
 481
 482 .. option:: --weaken
 483
 484  Mark all defined global symbols as weak in the output.
 485
 486 MACH-O-SPECIFIC OPTIONS
 487 -----------------------
 488
 489 .. option:: --keep-undefined
 490
 491  Keep undefined symbols, even if they would otherwise be stripped.
 492
 493 COFF-SPECIFIC OPTIONS
 494 ---------------------
 495
 496 .. option:: --subsystem <name>[:<version>]
 497
 498  Set the PE subsystem, and optionally subsystem version.
 499
 500 SUPPORTED FORMATS
 501 -----------------
 502
 503 The following values are currently supported by :program:`llvm-objcopy` for the
 504 :option:`--input-target`, :option:`--output-target`, and :option:`--target`
 505 options. For GNU :program:`objcopy` compatibility, the values are all bfdnames.
 506
 507 - `binary`
 508 - `ihex`
 509 - `elf32-i386`
 510 - `elf32-x86-64`
 511 - `elf64-x86-64`
 512 - `elf32-iamcu`
 513 - `elf32-littlearm`
 514 - `elf64-aarch64`
 515 - `elf64-littleaarch64`
 516 - `elf32-littleriscv`
 517 - `elf64-littleriscv`
 518 - `elf32-powerpc`
 519 - `elf32-powerpcle`
 520 - `elf64-powerpc`
 521 - `elf64-powerpcle`
 522 - `elf32-bigmips`
 523 - `elf32-ntradbigmips`
 524 - `elf32-ntradlittlemips`
 525 - `elf32-tradbigmips`
 526 - `elf32-tradlittlemips`
 527 - `elf64-tradbigmips`
 528 - `elf64-tradlittlemips`
 529 - `elf32-sparc`
 530 - `elf32-sparcel`
 531
 532 Additionally, all targets except `binary` and `ihex` can have `-freebsd` as a
 533 suffix.
 534
 535 BINARY INPUT AND OUTPUT
 536 -----------------------
 537
 538 If `binary` is used as the value for :option:`--input-target`, the input file
 539 will be embedded as a data section in an ELF relocatable object, with symbols
 540 ``_binary_<file_name>_start``, ``_binary_<file_name>_end``, and
 541 ``_binary_<file_name>_size`` representing the start, end and size of the data,
 542 where ``<file_name>`` is the path of the input file as specified on the command
 543 line with non-alphanumeric characters converted to ``_``.
 544
 545 If `binary` is used as the value for :option:`--output-target`, the output file
 546 will be a raw binary file, containing the memory image of the input file.
 547 Symbols and relocation information will be discarded. The image will start at
 548 the address of the first loadable section in the output.
 549
 550 EXIT STATUS
 551 -----------
 552
 553 :program:`llvm-objcopy` exits with a non-zero exit code if there is an error.
 554 Otherwise, it exits with code 0.
 555
 556 BUGS
 557 ----
 558
 559 To report bugs, please visit <https://github.com/llvm/llvm-project/labels/tools:llvm-objcopy/strip/>.
 560
 561 There is a known issue with :option:`--input-target` and :option:`--target`
 562 causing only ``binary`` and ``ihex`` formats to have any effect. Other values
 563 will be ignored and :program:`llvm-objcopy` will attempt to guess the input
 564 format.
 565
 566 SEE ALSO
 567 --------
 568
 569 :manpage:`llvm-strip(1)`