llvm-objcopy - 物件複製與編輯工具¶
概要¶
llvm-objcopy [選項] 輸入 [輸出]
描述¶
llvm-objcopy 是一個複製與操作物件的工具。在基本用法中，它會建立輸入的語義副本到輸出。如果指定任何選項，則輸出可能會在過程中被修改，例如透過移除區段。
如果未指定輸出檔案，則會就地修改輸入檔案。如果輸入檔案指定為 “-”，則會從程式的標準輸入流讀取輸入。如果輸出檔案指定為 “-”，則輸出會寫入程式的標準輸出流。
如果輸入是一個封存檔，任何請求的操作將會個別應用於每個封存成員。
此工具仍在積極開發中，但在大多數情況下，它可以作為 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>的已定義非 common 符號標記為輸出中的本地符號。可以多次指定以將多個符號標記為本地符號。
- --localize-symbols <filename>¶
從檔案
<filename>讀取名稱列表，並將具有這些名稱的已定義非 common 符號標記為輸出中的本地符號。在檔案中，每一行代表一個單一符號，忽略開頭和結尾的空白，以及 ‘#’ 後面的任何內容。可以多次指定以從多個檔案讀取名稱。
- --only-keep-debug¶
產生一個僅保留對除錯目的有用的區段內容的除錯檔案作為輸出。
對於 ELF 物件，這會移除非 SHT_NOTE 的 SHF_ALLOC 區段的內容，方法是將它們設為 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]
-
此外，以 ‘!’ 開頭的萬用字元將阻止匹配，即使另一個旗標匹配也是如此。例如，
-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>]¶
在輸出符號表中，在名為
<section>的區段中，添加一個名為<name>的新符號，其值為<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 除錯區段。
- --extract-dwo¶
從輸出中移除所有非 DWARF .dwo 區段的區段。
- --extract-main-partition¶
從輸出中提取主要分割區。
- --extract-partition <name>¶
從輸出中提取名為 <name> 的分割區。
- --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¶
新增註解區段時，不驗證區段格式是否有效。
- --output-target <format>, -O¶
以指定的格式寫入輸出。請參閱支援的格式以取得有效的
<format>值清單。如果未指定，則輸出格式預設與為--input-target指定的值相同，如果該選項也未指定，則與輸入檔案的格式相同。
- --pad-to <address>¶
對於二進位輸出，使用零值或
--gap-fill指定的值，將輸出填充到載入位址<address>。
- --prefix-alloc-sections <prefix>¶
將
<prefix>新增到輸出中所有可配置區段名稱的前面。
- --prefix-symbols <prefix>¶
將
<prefix>新增到輸出中每個符號名稱的前面。
- --preserve-dates, -p¶
在輸出中保留存取和修改時間戳記。
- --remove-note [<name>/]<type>¶
從不在區段中的 SHT_NOTE 區段中移除整數類型為
<type>且名稱為<name>的註解。可以多次指定。
- --rename-section <old>=<new>[,<flag>,...]¶
在輸出中將名為
<old>的區段重新命名為<new>，並套用任何指定的<flag>值。請參閱--set-section-flags以取得支援旗標的清單。可以多次指定以重新命名多個區段。
- --set-section-type <section>=<type>¶
將區段
<section>的類型設定為整數<type>。可以多次指定以更新多個區段。
- --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 區段。
- --strip-non-alloc¶
從輸出中移除所有不在區段內且不可配置的區段。
- --strip-sections¶
從輸出中移除所有區段標頭和所有不在區段內的區段資料。請注意，許多工具將無法使用沒有區段標頭的物件。
- --target <format>, -F¶
等同於針對指定格式的
--input-target和--output-target。請參閱支援的格式以取得有效的<format>值清單。
- --verify-note-sections¶
新增註解區段時，驗證區段格式是否有效。預設為開啟。
- --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 的值，則輸入檔案將嵌入為 ELF 可重定位物件中的資料區段，符號為 _binary_<file_name>_start、_binary_<file_name>_end 和 _binary_<file_name>_size，分別代表資料的開始、結束和大小，其中 <file_name> 是命令列上指定的輸入檔案路徑，非字母數字字元會轉換為 _。
如果將 binary 用作 --output-target 的值，則輸出檔案將是原始二進位檔案，其中包含輸入檔案的記憶體映像。符號和重定位資訊將被捨棄。映像將從輸出中第一個可載入區段的位址開始。
結束狀態¶
如果發生錯誤，llvm-objcopy 會以非零結束代碼結束。否則，它會以代碼 0 結束。
錯誤¶
若要回報錯誤，請造訪 <https://github.com/llvm/llvm-project/labels/tools:llvm-objcopy/strip/>。
已知 --input-target 和 --target 存在問題，導致只有 binary 和 ihex 格式會生效。其他值將被忽略，而 llvm-objcopy 將嘗試猜測輸入格式。