llvm.org GIT mirror llvm / master docs / CommandGuide / llvm-objcopy.rst
master

Tree @master (Download .tar.gz)

llvm-objcopy.rst @masterview markup · raw · history · blame

llvm-objcopy - object copying and editing tool

SYNOPSIS

:program:`llvm-objcopy` [options] input [output]

DESCRIPTION

:program:`llvm-objcopy` is a tool to copy and manipulate objects. In basic usage, it makes a semantic copy of the input to the output. If any options are specified, the output may be modified along the way, e.g. by removing sections.

If no output file is specified, the input file is modified in-place. If "-" is specified for the input file, the input is read from the program's standard input stream. If "-" is specified for the output file, the output is written to the standard output stream of the program.

If the input is an archive, any requested operations will be applied to each archive member individually.

The tool is still in active development, but in most scenarios it works as a drop-in replacement for GNU's :program:`objcopy`.

GENERIC AND CROSS-PLATFORM OPTIONS

The following options are either agnostic of the file format, or apply to multiple file formats.

COFF-SPECIFIC OPTIONS

The following options are implemented only for COFF objects. If used with other objects, :program:`llvm-objcopy` will either emit an error or silently ignore them.

ELF-SPECIFIC OPTIONS

The following options are implemented only for ELF objects. If used with other objects, :program:`llvm-objcopy` will either emit an error or silently ignore them.

SUPPORTED FORMATS

The following values are currently supported by :program:`llvm-objcopy` for the :option:`--input-target`, :option:`--output-target`, and :option:`--target` options. For GNU :program:`objcopy` compatibility, the values are all bfdnames.

  • binary
  • ihex
  • elf32-i386
  • elf32-x86-64
  • elf64-x86-64
  • elf32-iamcu
  • elf32-littlearm
  • elf64-aarch64
  • elf64-littleaarch64
  • elf32-littleriscv
  • elf64-littleriscv
  • elf32-powerpc
  • elf32-powerpcle
  • elf64-powerpc
  • elf64-powerpcle
  • elf32-bigmips
  • elf32-ntradbigmips
  • elf32-ntradlittlemips
  • elf32-tradbigmips
  • elf32-tradlittlemips
  • elf64-tradbigmips
  • elf64-tradlittlemips
  • elf32-sparc
  • elf32-sparcel

Additionally, all targets except binary and ihex can have -freebsd as a suffix.

BINARY INPUT AND OUTPUT

If binary is used as the value for :option:`--input-target`, the input file will be embedded as a data section in an ELF relocatable object, with symbols _binary_<file_name>_start, _binary_<file_name>_end, and _binary_<file_name>_size representing the start, end and size of the data, where <file_name> is the path of the input file as specified on the command line with non-alphanumeric characters converted to _.

If binary is used as the value for :option:`--output-target`, the output file will be a raw binary file, containing the memory image of the input file. Symbols and relocation information will be discarded. The image will start at the address of the first loadable section in the output.

EXIT STATUS

:program:`llvm-objcopy` exits with a non-zero exit code if there is an error. Otherwise, it exits with code 0.

BUGS

To report bugs, please visit <http://llvm.org/bugs/>.

There is a known issue with :option:`--input-target` and :option:`--target` causing only binary and ihex formats to have any effect. Other values will be ignored and :program:`llvm-objcopy` will attempt to guess the input format.