llvm-objcopy - 对象复制和编辑工具¶
概要¶
llvm-objcopy [选项] 输入 [输出]
描述¶
llvm-objcopy 是一个用于复制和操作对象的工具。在基本用法中，它创建一个从输入到输出的语义副本。如果指定了任何选项，则输出可能会在此过程中被修改，例如通过删除 sections（节）。
如果未指定输出文件，则会就地修改输入文件。如果为输入文件指定了 “-”，则从程序的标准输入流读取输入。如果为输出文件指定了 “-”，则将输出写入程序的标准输出流。
如果输入是归档文件，则任何请求的操作都将单独应用于每个归档成员。
该工具仍在积极开发中，但在大多数情况下，它可以作为 GNU objcopy 的直接替代品。
通用和跨平台选项¶
以下选项与文件格式无关，或适用于多种文件格式。
- --add-gnu-debuglink <debug-file>¶
为输出添加一个用于
<debug-file>的 .gnu_debuglink 节。
- --add-section <section=file>¶
向输出添加一个名为
<section>的节，其内容来自<file>。对于 ELF 对象，如果名称以 “.note” 开头，则该节的类型将为 SHT_NOTE。否则，它将具有 SHT_PROGBITS 类型。可以多次指定以添加多个节。对于 MachO 对象，
<section>必须格式化为<segment name>,<section name>。
- --binary-architecture <arch>, -B¶
为了兼容性而被忽略。
- --disable-deterministic-archives, -U¶
在更新归档成员标头时，使用真实的 UID、GID 和时间戳值。
- --discard-all, -x¶
从输出中删除大多数本地符号。不同的文件格式可能会将此限制为本地符号的子集。例如，ELF 对象中的文件和节符号将不会被丢弃。此外，还会删除所有调试节。
- --dump-section <section>=<file>¶
将节
<section>的内容转储到文件<file>中。可以多次指定以将多个节转储到不同的文件中。<file>与提供给 llvm-objcopy 的输入和输出文件无关，因此正常的复制和编辑操作仍将执行。在转储节之前，不会对节执行任何操作。对于 MachO 对象，
<section>必须格式化为<segment name>,<section name>。
- --enable-deterministic-archives, -D¶
复制归档文件时启用确定性模式，即对归档成员标头 UID、GID 和时间戳字段使用 0。默认情况下启用。
- --globalize-symbol <symbol>¶
将任何名为
<symbol>的已定义符号标记为输出中的全局符号。可以多次指定以标记多个符号。
- --globalize-symbols <filename>¶
从文件
<filename>中读取名称列表，并将具有这些名称的已定义符号标记为输出中的全局符号。在文件中，每行代表一个符号，忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件中读取名称。
- --help, -h¶
打印命令行选项的摘要。
- --keep-global-symbol <symbol>, -G¶
将输出中的所有符号标记为本地符号，但名称为
<symbol>的符号除外。可以多次指定以忽略多个符号。
- --keep-global-symbols <filename>¶
将输出中的所有符号标记为本地符号，但文件
<filename>中命名的符号除外。在文件中，每行代表一个符号，忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件中读取名称。
- --localize-symbol <symbol>, -L¶
将任何名为
<symbol>的已定义非公共符号标记为输出中的本地符号。可以多次指定以将多个符号标记为本地符号。
- --localize-symbols <filename>¶
从文件
<filename>中读取名称列表，并将具有这些名称的已定义非公共符号标记为输出中的本地符号。在文件中，每行代表一个符号，忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件中读取名称。
- --only-keep-debug¶
生成一个调试文件作为输出，该文件仅保留对调试目的有用的节的内容。
对于 ELF 对象，这将删除 SHF_ALLOC 节的内容（非 SHT_NOTE），方法是将它们设为 SHT_NOBITS 并尽可能缩小程序头。
- --only-section <section>, -j¶
从输出中删除所有节，但名为
<section>的节除外。可以多次指定以保留多个节。对于 MachO 对象，
<section>必须格式化为<segment name>,<section name>。
- --redefine-sym <old>=<new>¶
将输出中名为
<old>的符号重命名为<new>。可以多次指定以重命名多个符号。
- --redefine-syms <filename>¶
按照文件
<filename>中的描述重命名输出中的符号。在文件中，每行代表一个要重命名的符号，旧名称和新名称之间用空格分隔。忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件中读取名称。
- --regex¶
如果指定，其他开关指定的符号和节名称将被视为扩展 POSIX 正则表达式模式。
- --remove-symbol-prefix <prefix>¶
从每个符号名称的开头删除
<prefix>。对于不以<prefix>开头的符号，不执行任何操作。
- --remove-section <section>, -R¶
从输出中删除指定的节。可以多次指定以同时删除多个节。
对于 MachO 对象，
<section>必须格式化为<segment name>,<section name>。
- --set-section-alignment <section>=<align>¶
将节
<section>的对齐方式设置为<align>。可以多次指定以更新多个节。
- --set-section-flags <section>=<flag>[,<flag>,...]¶
根据指定的
<flag>值设置输出中节<section>的节属性。可以多次指定以更新多个节。支持的标志名称为 alloc、load、noload、readonly、exclude、debug、code、data、rom、share、contents、merge、strings 和 large。并非所有标志都对所有对象文件格式或目标架构都有意义。
对于 ELF 对象，标志具有以下效果
alloc = 添加 SHF_ALLOC 标志。
load = 如果节具有 SHT_NOBITS 类型，则将其标记为 SHT_PROGBITS 节。
readonly = 如果未指定此标志，则添加 SHF_WRITE 标志。
exclude = 添加 SHF_EXCLUDE 标志。
code = 添加 SHF_EXECINSTR 标志。
merge = 添加 SHF_MERGE 标志。
strings = 添加 SHF_STRINGS 标志。
contents = 如果节具有 SHT_NOBITS 类型，则将其标记为 SHT_PROGBITS 节。
large = 在 x86_64 上添加 SHF_X86_64_LARGE；如果目标架构不是 x86_64，则拒绝。
对于 COFF 对象，标志具有以下效果
alloc = 添加 IMAGE_SCN_CNT_UNINITIALIZED_DATA 和 IMAGE_SCN_MEM_READ 标志，除非指定了 load 标志。
noload = 添加 IMAGE_SCN_LNK_REMOVE 和 IMAGE_SCN_MEM_READ 标志。
readonly = 如果未指定此标志，则添加 IMAGE_SCN_MEM_WRITE 标志。
exclude = 添加 IMAGE_SCN_LNK_REMOVE 和 IMAGE_SCN_MEM_READ 标志。
debug = 添加 IMAGE_SCN_CNT_INITIALIZED_DATA、IMAGE_SCN_MEM_DISCARDABLE 和 IMAGE_SCN_MEM_READ 标志。
code = 添加 IMAGE_SCN_CNT_CODE、IMAGE_SCN_MEM_EXECUTE 和 IMAGE_SCN_MEM_READ 标志。
data = 添加 IMAGE_SCN_CNT_INITIALIZED_DATA 和 IMAGE_SCN_MEM_READ 标志。
share = 添加 IMAGE_SCN_MEM_SHARED 和 IMAGE_SCN_MEM_READ 标志。
- --skip-symbol <symbol>¶
在执行其他可以更改符号名称、绑定或可见性的选项时，不要更改符号
<symbol>的参数。
- --skip-symbols <filename>¶
在执行其他可以更改符号名称、绑定或可见性的选项时，不要更改文件
<filename>中命名的符号的参数。在文件中，每行代表一个符号，忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件中读取名称。
- --strip-all-gnu¶
从输出中删除所有符号、调试节和重定位。此选项等效于 GNU objcopy 的
--strip-all开关。
- --strip-all, -S¶
对于 ELF 对象，从输出中删除所有符号和不在段内的非 alloc 节，但 .gnu.warning、.ARM.attribute 节和节名称表除外。
对于 COFF 和 Mach-O 对象，从输出中删除所有符号、调试节和重定位。
- --strip-debug, -g¶
从输出中删除所有调试节。
- --strip-symbol <symbol>, -N¶
从输出中删除所有名为
<symbol>的符号。可以多次指定以删除多个符号。
- --strip-symbols <filename>¶
从输出中删除所有名称出现在文件
<filename>中的符号。在文件中，每行代表一个符号名称，忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件中读取名称。
- --strip-unneeded-symbol <symbol>¶
从输出中删除所有名为
<symbol>的本地或未定义符号，且这些符号不是任何重定位所必需的。
- --strip-unneeded-symbols <filename>¶
从输出中删除所有名称出现在文件
<filename>中的符号，如果它们是本地或未定义的，并且不是任何重定位所必需的。在文件中，每行代表一个符号名称，忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件中读取名称。
- --strip-unneeded¶
从输出中删除所有本地或未定义符号，这些符号不是重定位所必需的。还会删除所有调试节。
- --update-section <name>=<file>¶
将节
<name>的内容替换为来自文件<file>的内容。如果节<name>是段的一部分，则新内容不能大于现有节。
- --version, -V¶
显示 llvm-objcopy 可执行文件的版本。
- --wildcard, -w¶
允许符号相关标志使用通配符语法。节相关标志默认启用。与 –regex 不兼容。
通配符语法允许以下特殊符号
字符
含义
等效于
**
.*??
.\\
\[a-z]字符类
[a-z][!a-z],[^a-z]否定字符类
[^a-z]此外，以 ‘!’ 开头的通配符将阻止匹配，即使另一个标志匹配也是如此。例如
-w -N '*' -N '!x'将剥离除x之外的所有符号。通配符的顺序无关紧要。例如，
-w -N '*' -N '!x'与-w -N '!x' -N '*'相同。
- @<FILE>¶
从响应文件 <FILE> 读取命令行选项和命令。
ELF 特定选项¶
以下选项仅针对 ELF 对象实现。如果与其他对象一起使用，llvm-objcopy 将发出错误或静默忽略它们。
- --add-symbol <name>=[<section>:]<value>[,<flags>]¶
向输出符号表添加一个名为
<name>的新符号，位于名为<section>的节中，值为<value>。如果未指定<section>，则将符号添加为绝对符号。<flags>影响符号属性。接受的值为global = 符号将具有全局绑定。
local = 符号将具有本地绑定。
weak = 符号将具有弱绑定。
default = 符号将具有默认可见性。
hidden = 符号将具有隐藏可见性。
protected = 符号将具有受保护的可见性。
file = 符号将是 STT_FILE 符号。
section = 符号将是 STT_SECTION 符号。
object = 符号将是 STT_OBJECT 符号。
function = 符号将是 STT_FUNC 符号。
indirect-function = 符号将是 STT_GNU_IFUNC 符号。
此外，以下标志被接受但被忽略：debug、constructor、warning、indirect、synthetic、unique-object、before。
可以多次指定以添加多个符号。
- --allow-broken-links¶
允许 llvm-objcopy 删除节，即使这会留下无效的节引用。任何无效的 sh_link 字段都将被设置为零。
- --change-section-lma \*{+-}<val>¶
将非零大小段的 LMA 移动
<val>。
- --change-section-address <section>{=+-}<val>, --adjust-section-vma¶
将与
<section>模式匹配的节的地址更改为指定值，或将+<val>/-<val>应用于当前值。可以多次指定以指定多个模式。每个节仅被一个--change-section-address参数修改。如果节名称与多个模式匹配，则应用最右边的更改。对象文件需要是 ET_REL 类型。
- --change-start <incr>, --adjust-start¶
将
<incr>添加到程序的起始地址。可以多次指定，在这种情况下，这些值将累积应用。
- --compress-debug-sections [<format>]¶
使用指定的格式压缩输出中的 DWARF 调试节。支持的格式为
zlib和zstd。如果省略<format>，则使用zlib。
- --compress-sections <section>=<format>¶
使用指定的格式压缩或解压缩与
<section>匹配的节。支持的格式为zlib和zstd。指定none进行解压缩。当一个节与多个选项匹配时，最后一个选项生效。不允许以 ‘!’ 开头的通配符<section>。段内的节无法（解）压缩。
- --decompress-debug-sections¶
解压缩输出中任何压缩的 DWARF 调试节。
- --discard-locals, -X¶
从输出中删除以 “.L” 开头的本地符号。
- --extract-dwo¶
从输出中删除所有不是 DWARF .dwo 节的节。
- --extract-main-partition¶
从输出中提取主分区。
- --extract-partition <name>¶
从输出中提取名为 partition（分区）。
- --gap-fill <value>¶
对于二进制输出，用
<value>而不是零填充节之间的间隙。该值必须是无符号 8 位整数。
- --keep-file-symbols¶
保留 STT_FILE 类型的符号，即使它们原本会被剥离。
- --keep-section <section>¶
从输出中删除节时，不要删除名为
<section>的节。可以多次指定以保留多个节。
- --keep-symbol <symbol>, -K¶
从输出中删除符号时，不要删除名为
<symbol>的符号。可以多次指定以保留多个符号。
- --keep-symbols <filename>¶
从输出中删除符号时，不要删除文件
<filename>中命名的符号。在文件中，每行代表一个符号，忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件中读取名称。
将输出中所有具有隐藏或内部可见性的符号标记为本地符号。
- --new-symbol-visibility <visibility>¶
指定使用二进制输入或
--add-symbol自动创建的符号的可见性。有效选项包括default (默认)
hidden (隐藏)
internal (内部)
protected (保护)
默认值为 default。
- --no-verify-note-sections¶
添加 note section 时，不验证 section 格式是否有效。
- --output-target <format>, -O¶
将输出写入为指定的格式。有关有效
<format>值的列表，请参阅 支持的格式。如果未指定，则假定输出格式与为--input-target指定的值相同，如果该选项也未指定，则与输入文件的格式相同。
- --pad-to <address>¶
对于二进制输出，使用零值或
--gap-fill指定的值将输出填充到加载地址<address>。
- --prefix-alloc-sections <prefix>¶
将
<prefix>添加到输出中所有可分配 section 名称的前面。
- --prefix-symbols <prefix>¶
将
<prefix>添加到输出中每个符号名称的前面。
- --preserve-dates, -p¶
在输出中保留访问和修改时间戳。
- --remove-note [<name>/]<type>¶
从不在段中的 SHT_NOTE section 中删除整数类型为
<type>且名称为<name>的 note。可以多次指定。
- --rename-section <old>=<new>[,<flag>,...]¶
在输出中将名为
<old>的 section 重命名为<new>，并应用任何指定的<flag>值。有关支持的标志列表，请参阅--set-section-flags。可以多次指定以重命名多个 section。
- --set-section-type <section>=<type>¶
将 section
<section>的类型设置为整数<type>。可以多次指定以更新多个 section。
- --set-start <addr>¶
将输出的起始地址设置为
<addr>。覆盖任何先前指定的--change-start或--adjust-start选项。
- --set-symbol-visibility <symbol>=<visibility>¶
将符号的可见性更改为指定值。
- --set-symbols-visibility <filename>=<visibility>¶
从 <filename> 读取符号列表，并将它们的可见性更改为指定值。可见性值：default, internal, hidden, protected。
- --split-dwo <dwo-file>¶
等效于运行 llvm-objcopy 并使用
--extract-dwo和<dwo-file>作为输出文件，并且没有其他选项；然后对输入文件使用--strip-dwo。
- --strip-dwo¶
从输出中删除所有 DWARF .dwo section。
- --strip-non-alloc¶
从输出中删除所有不在段内的非可分配 section。
- --strip-sections¶
从输出中删除所有 section header 和所有不在段内的 section 数据。请注意，许多工具将无法使用没有 section header 的对象。
- --target <format>, -F¶
等效于为指定格式同时设置
--input-target和--output-target。有关有效<format>值的列表，请参阅 支持的格式。
- --verify-note-sections¶
添加 note section 时，验证 section 格式是否有效。默认启用。
- --weaken-symbol <symbol>, -W¶
将名为
<symbol>的全局符号标记为输出中的弱符号。可以多次指定以将多个符号标记为弱符号。
- --weaken-symbols <filename>¶
从文件
<filename>中读取名称列表，并将具有这些名称的全局符号标记为输出中的弱符号。在该文件中，每行代表一个符号，忽略前导和尾随空格，以及 ‘#’ 之后的所有内容。可以多次指定以从多个文件读取名称。
- --weaken¶
将所有已定义的全局符号标记为输出中的弱符号。
MACH-O 专属选项¶
- --keep-undefined¶
保留未定义的符号，即使它们本来会被剥离。
COFF 专属选项¶
- --subsystem <name>[:<version>]¶
设置 PE 子系统，以及可选的子系统版本。
支持的格式¶
以下值当前受 llvm-objcopy 的 --input-target、--output-target 和 --target 选项支持。为了与 GNU objcopy 兼容，这些值都是 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
elf32-hexagon
elf32-loongarch
elf64-loongarch
elf64-s390
以下格式仅受 llvm-objcopy 的 --output-target 支持
srec
此外，除了 binary、ihex 和 srec 之外的所有目标都可以使用 -freebsd 作为后缀。
二进制输入和输出¶
如果将 binary 用作 --input-target 的值，则输入文件将作为数据 section 嵌入到 ELF 可重定位对象中，符号 _binary_<file_name>_start、_binary_<file_name>_end 和 _binary_<file_name>_size 表示数据的开始、结束和大小，其中 <file_name> 是命令行上指定的输入文件的路径，非字母数字字符转换为 _。
如果将 binary 用作 --output-target 的值，则输出文件将是一个原始二进制文件，其中包含输入文件的内存映像。符号和重定位信息将被丢弃。映像将从输出中第一个可加载 section 的地址开始。
退出状态¶
如果出现错误，llvm-objcopy 将以非零退出代码退出。否则，它将以代码 0 退出。
错误¶
要报告错误，请访问 <https://github.com/llvm/llvm-project/labels/tools:llvm-objcopy/strip/>。
关于 --input-target 和 --target 存在已知问题，导致只有 binary 和 ihex 格式才有效。其他值将被忽略，并且 llvm-objcopy 将尝试猜测输入格式。