GOLD(1)

📦
version 2.42 · 5 versions
, in ubuntu noble

🌸 NAME 🌸

okay bestie, gather round, because today we're talking about gold — the GNU ELF linker 💖. That's it, that's the whole name. It links your ELF files, it's GNU's take on the job, and it's lowkey the main character of your build pipeline. No cap.

🦋 SYNOPSIS 🦋

the vibe check of how you actually invoke her:

ld.gold [options] file...

so it's just ld.gold, then a bunch of options, then a bunch of files. That's the whole shape of it, periodt ✨.

👑 OPTIONS 👑

okay this is the big one, the iconique list, so let's go one by one, no skipping, we keep EVERY detail fr fr 🫶

  • --help — shows you the usage info. your "wait what do I type" button 🎀
  • -v, --version — spills the version info. iconique behavior honestly.
  • -V — version and target info. she's giving extra 💅
  • --add-needed — not supported, bestie. don't come for her.
  • --no-add-needed — does not copy DT_NEEDED tags from shared libraries (this is the default).
  • --allow-multiple-definition — lets symbols be defined multiple times. chaos, but consensual.
  • --no-allow-multiple-definition — does not allow multiple definitions (the default).
  • --allow-shlib-undefined — allows unresolved references in shared libraries. live a little ✨
  • --no-allow-shlib-undefined — does not allow unresolved references in shared libraries (the default).
  • --apply-dynamic-relocs — applies link-time values for dynamic relocations (the default).
  • --no-apply-dynamic-relocs — (aarch64 only) does not apply link-time values for dynamic relocations.
  • --as-needed — uses DT_NEEDED only for the shared libraries that are actually used. minimalism, we love her.
  • --no-as-needed — uses DT_NEEDED for all shared libraries (the default).
  • -assert [ignored] — literally ignored. she said nothing, she did nothing, she's just there 🫥
  • -b [elf,binary], --format [elf,binary] — sets the input format.
  • --be8 — outputs a BE8 format image.
  • --build-id [=STYLE] — generates a build ID note.
  • --build-id-chunk-size-for-treehash SIZE — the chunk size for --build-id=tree.
  • --build-id-min-file-size-for-treehash SIZE — minimum output file size for --build-id=tree to work differently than --build-id=sha1.
  • -Bdynamic — -l searches for shared libraries (the default).
  • -Bstatic — -l does not search for shared libraries.
  • -dy — alias for -Bdynamic (the default).
  • -dn — alias for -Bstatic.
  • -Bgroup — use group name lookup rules for shared library.
  • -Bshareable — generate a shared library (alias for -G/-shared).
  • -Bno-symbolic — don't bind default visibility defined symbols locally for -shared (the default).
  • -Bsymbolic-functions — bind default visibility defined function symbols locally for -shared.
  • -Bsymbolic — bind default visibility defined symbols locally for -shared.
  • --check-sections — checks segment addresses for overlaps (the default).
  • --no-check-sections — does not check segment addresses for overlaps.
  • --compress-debug-sections [none,zlib,zlib-gnu,zlib-gabi,zstd] — compresses .debug_* sections in the output file. tiny file, big energy 🦋
  • --copy-dt-needed-entries — not supported.
  • --no-copy-dt-needed-entries — do not copy DT_NEEDED tags from shared libraries (the default).
  • --cref — outputs a cross reference table.
  • --no-cref — does not output a cross reference table (the default).
  • --ctors-in-init-array — use DT_INIT_ARRAY for all constructors (the default).
  • --no-ctors-in-init-array — handles constructors as directed by the compiler.
  • -d, --define-common — defines common symbols.
  • --no-define-common — does not define common symbols in relocatable output (the default).
  • -dc — alias for -d.
  • -dp — alias for -d.
  • --debug [all,files,script,task][,...] — turns on debugging. the "why is this happening" switch 😭
  • --defsym SYMBOL=EXPRESSION — defines a symbol.
  • --demangle [=STYLE] — demangles C++ symbols in log messages so your eyes stop hurting.
  • --no-demangle — does not demangle C++ symbols in log messages.
  • --dependency-file FILE — writes a dependency file listing all files read.
  • --detect-odr-violations — looks for violations of the C++ One Definition Rule.
  • --no-detect-odr-violations — does not look for violations of the C++ One Definition Rule (the default).
  • --dynamic-list-data — adds data symbols to dynamic symbols.
  • --dynamic-list-cpp-new — adds C++ operator new/delete to dynamic symbols.
  • --dynamic-list-cpp-typeinfo — adds C++ typeinfo to dynamic symbols.
  • --dynamic-list FILE — reads a list of dynamic symbols.
  • --emit-stub-syms — (PowerPC only) labels linker stubs with a symbol (the default).
  • --no-emit-stub-syms — (PowerPC only) does not label linker stubs with a symbol.
  • -e ADDRESS, --entry ADDRESS — sets the program start address.
  • --eh-frame-hdr — creates the exception frame header.
  • --no-eh-frame-hdr — does not create the exception frame header (the default).
  • --enable-new-dtags — enables use of DT_RUNPATH (the default).
  • --disable-new-dtags — disables use of DT_RUNPATH.
  • --enable-linker-version — puts the linker version string into the .comment section.
  • --disable-linker-version — puts the linker version string into the .note.gnu.gold-version section (the default).
  • --no-enum-size-warning — (ARM only) does not warn about objects with incompatible enum sizes.
  • --exclude-libs lib,lib ... — excludes libraries from automatic export.
  • -E, --export-dynamic — exports all dynamic symbols. everyone's invited 💖
  • --no-export-dynamic — does not export all dynamic symbols (the default).
  • --export-dynamic-symbol SYMBOL — exports SYMBOL to the dynamic symbol table.
  • -EB — link big-endian objects.
  • -EL — link little-endian objects.
  • -f SHLIB, --auxiliary SHLIB — auxiliary filter for the shared object symbol table.
  • -F SHLIB, --filter SHLIB — filter for the shared object symbol table.
  • --fatal-warnings — treats warnings as errors. no warnings allowed, we're strict now 😤
  • --no-fatal-warnings — does not treat warnings as errors (the default).
  • -fini SYMBOL — call SYMBOL at unload-time.
  • --fix-arm1176 — (ARM only) fixes binaries for the ARM1176 erratum (the default).
  • --no-fix-arm1176 — (ARM only) does not fix binaries for the ARM1176 erratum.
  • --fix-cortex-a8 — (ARM only) fixes binaries for the Cortex-A8 erratum.
  • --no-fix-cortex-a8 — (ARM only) does not fix binaries for the Cortex-A8 erratum (the default).
  • --fix-cortex-a53-843419 — (AArch64 only) fixes Cortex-A53 erratum 843419.
  • --no-fix-cortex-a53-843419 — (AArch64 only) does not fix Cortex-A53 erratum 843419 (the default).
  • --fix-cortex-a53-835769 — (AArch64 only) fixes Cortex-A53 erratum 835769.
  • --no-fix-cortex-a53-835769 — (AArch64 only) does not fix Cortex-A53 erratum 835769 (the default).
  • --fix-v4bx — (ARM only) rewrites BX rn as MOV pc, rn for ARMv4.
  • --fix-v4bx-interworking — (ARM only) rewrites BX rn branch to ARMv4 interworking veneer.
  • -fuse-ld [gold,bfd] — ignored, kept around for GCC linker option compatibility. she's just here to be polite 🎀
  • -g — ignored.
  • --gc-sections — removes unused sections. spring cleaning, but for your binary ✨
  • --no-gc-sections — doesn't remove unused sections (the default).
  • --gdb-index — generates a .gdb_index section.
  • --no-gdb-index — does not generate a .gdb_index section (the default).
  • --gnu-unique — enables STB_GNU_UNIQUE symbol binding (the default).
  • --no-gnu-unique — disables STB_GNU_UNIQUE symbol binding.
  • -G, -shared — generate a shared library.
  • -h FILENAME, -soname FILENAME — sets the shared library name.
  • --hash-bucket-empty-fraction FRACTION — minimum fraction of empty buckets in the dynamic hash.
  • --hash-style [sysv,gnu,both] — the dynamic hash style.
  • -i — alias for -r.
  • --icf [none,all,safe] — Identical Code Folding. '--icf=safe' folds ctors, dtors and functions whose pointers are definitely not taken. very "if you're the same, you're the same" of her 💅
  • --icf-iterations COUNT — number of iterations of ICF (default 3).
  • --incremental — does an incremental link if possible; otherwise, does a full link and prepares output for incremental linking.
  • --no-incremental — does a full link (the default).
  • --incremental-full — does a full link and prepares output for incremental linking.
  • --incremental-update — does an incremental link; exits if it's not possible.
  • --incremental-base FILE — sets the base file for incremental linking (default is the output file).
  • --incremental-changed — assumes files changed.
  • --incremental-unchanged — assumes files didn't change.
  • --incremental-unknown — uses timestamps to check files (the default).
  • --incremental-startup-unchanged — assumes startup files unchanged (files preceding this option).
  • --incremental-patch PERCENT — amount of extra space to allocate for patches (default 10).
  • -init SYMBOL — call SYMBOL at load-time.
  • -I PROGRAM, --dynamic-linker PROGRAM — sets the dynamic linker path.
  • --just-symbols FILE — reads only symbol values from FILE. no lore, just numbers.
  • --keep-files-mapped — keeps files mapped across passes (default on 64bit architectures).
  • --no-keep-files-mapped — releases mapped files after each pass (default on 32bit architectures).
  • --keep-unique SYMBOL — do not fold this symbol during ICF. she's unique and she stays unique, periodt 👑
  • -l LIBNAME, --library LIBNAME — search for library LIBNAME.
  • --ld-generated-unwind-info — generates unwind information for PLT (the default).
  • --no-ld-generated-unwind-info — does not generate unwind information for PLT.
  • -L DIR, --library-path DIR — adds a directory to the search path.
  • --long-plt — (ARM only) generates long PLT entries.
  • --no-long-plt — (ARM only) does not generate long PLT entries (the default).
  • -m EMULATION — sets the GNU linker emulation; obsolete. she's retired bestie, respect the legacy.
  • --map-whole-files — maps whole files to memory (default on 64bit architectures).
  • --no-map-whole-files — maps relevant file parts to memory (default on 32bit architectures).
  • --merge-exidx-entries — (ARM only) merges exidx entries in debuginfo (the default).
  • --no-merge-exidx-entries — (ARM only) does not merge exidx entries in debuginfo.
  • --mmap-output-file — maps the output file for writing (the default).
  • --no-mmap-output-file — does not map the output file for writing.
  • -M, --print-map — writes the map file on standard output.
  • -Map MAPFILENAME — writes the map file.
  • -n, --nmagic — does not page align data.
  • -N, --omagic — does not page align data, and does not make text readonly.
  • --no-omagic — page aligns data, makes text readonly (the default).
  • --no-keep-memory — uses less memory and more disk I/O (included only for compatibility with GNU ld).
  • --no-undefined — reports undefined symbols (even with --shared).
  • --noinhibit-exec — creates an output file even if errors occur. messy but productive, we've all been there 🙈
  • -nostdlib — only searches directories specified on the command line.
  • -o FILE, --output FILE — sets the output file name.
  • --oformat [binary] — sets the output format.
  • -O LEVEL, -optimize LEVEL — optimizes output file size.
  • --orphan-handling [place,discard,warn,error] — orphan section handling.
  • -p — ignored, kept for ARM compatibility.
  • --package-metadata [=JSON] — drop a package metadata note in there 💌
  • -pie — make a position independent executable ✨
  • -no-pie — do NOT make a position independent executable (this is the default, bestie) 🚫
  • --pic-executable — same vibe as -pie: position independent executable, slay 👑
  • --no-pic-executable — nope, no position independent executable here (default) 🙅‍♀️
  • --pic-veneer — force PIC sequences for ARM/Thumb interworking veneers 🦾
  • -no-pipeline-knowledge — (ARM only) ignore for backward compatibility (default) 🕰️
  • --plt-align [=P2ALIGN] — (PowerPC only) align PLT call stubs so they fit cache lines 📐
  • --plt-localentry — (PowerPC64 only) optimize calls to ELFv2 localentry:0 functions 🚀
  • --no-plt-localentry — (PowerPC64 only) don't optimize those ELFv2 calls (default) 🙈
  • --plt-static-chain — (PowerPC64 only) PLT call stubs should load r11 💪
  • --no-plt-static-chain — (PowerPC64 only) PLT call stubs should not load r11 (default) 🚫
  • --plt-thread-safe — (PowerPC64 only) PLT call stubs with a load-load barrier 🧱
  • --no-plt-thread-safe — (PowerPC64 only) PLT call stubs without a barrier (default) 🌊
  • --plugin PLUGIN — load a plugin library 🔌
  • --plugin-opt OPTION — pass an option to the plugin 🗣️
  • --posix-fallocate — use posix_fallocate to reserve space in the output file (default) 📦
  • --no-posix-fallocate — use fallocate or ftruncate to reserve space ✂️
  • --power10-stubs [=auto,no,yes] — (PowerPC64 only) stubs use power10 insns ⚡
  • --no-power10-stubs — (PowerPC64 only) stubs do not use power10 insns 🚫
  • --preread-archive-symbols — preread archive symbols when multi-threaded 📚
  • --print-gc-sections — list removed unused sections on stderr 🗑️
  • --no-print-gc-sections — do not list removed unused sections (default) 🙊
  • --print-icf-sections — list folded identical sections on stderr 🪞
  • --no-print-icf-sections — do not list folded identical sections (default) 🤐
  • --print-output-format — print default output format 🖨️
  • --print-symbol-counts FILENAME — print symbols defined and used for each input 🔢
  • --push-state — save the state of flags related to input files 💾
  • --pop-state — restore the state of flags related to input files ⏪
  • -q, --emit-relocs — generate relocations in output 🛠️
  • -Qy — ignored for SVR4 compatibility 🤷‍♀️
  • -r, -relocatable — generate relocatable output 🔄
  • --relax — relax branches on certain targets 🧘
  • --no-relax — do not relax branches (default) 🚫
  • --retain-symbols-file FILE — keep only symbols listed in this file 📝
  • --rosegment — put read-only non-executable sections in their own segment 🌹
  • --no-rosegment — do not put read-only non-executable sections in their own segment (default) 🥀
  • --rosegment-gap OFFSET — set offset between executable and read-only segments 📏
  • -R DIR — add DIR to runtime search path 🔍
  • -rpath DIR — add DIR to runtime search path (same energy) 🔎
  • --rpath-link DIR — add DIR to link time shared library search path 🔗
  • -s, --strip-all — strip all symbols ✂️
  • -S, --strip-debug — strip debugging information 🐛
  • --strip-debug-non-line — emit only debug line number information 📍
  • --strip-debug-gdb — strip debug symbols that are unused by gdb (at least versions <= 7.4) 🧹
  • --strip-lto-sections — strip LTO intermediate code sections (default) 🧼
  • --section-ordering-file FILENAME — layout sections in the order specified 📋
  • --section-start SECTION=ADDRESS — set address of section 🏠
  • --secure-plt — (PowerPC only) use new-style PLT (default) 🔐
  • --sort-common [={ascending,descending}] — sort common symbols by alignment 📊
  • --sort-section [none,name] — sort sections by name. '--no-text-reorder' will override '--sort-section=name' for .text 🔤
  • --spare-dynamic-tags COUNT — dynamic tag slots to reserve (default 5) 🏷️
  • --stub-group-size SIZE — (ARM, PowerPC only) the maximum distance from instructions in a group of sections to their stubs. Negative values mean stubs are always after the group. 1 means use default size 📦
  • --stub-group-multi — (PowerPC only) allow a group of stubs to serve multiple output sections (default) 👯‍♀️
  • --no-stub-group-multi — (PowerPC only) each output section has its own stubs 🙅
  • --split-stack-adjust-size SIZE — stack size when -fsplit-stack function calls non-split 🧵
  • -static — do not link against shared libraries 🚫
  • --start-lib — start a library 🏁
  • --end-lib — end a library 🏁
  • --stats — print resource usage statistics 📈
  • --sysroot DIR — set target system root directory 🌳
  • -t, --trace — print the name of each input file 🗣️
  • --target1-abs — (ARM only) force R_ARM_TARGET1 type to R_ARM_ABS32 🎯
  • --target1-rel — (ARM only) force R_ARM_TARGET1 type to R_ARM_REL32 🎯
  • --target2 [rel, abs, got-rel — (ARM only) set R_ARM_TARGET2 relocation type 🧩
  • --text-reorder — enable text section reordering for GCC section names (default) 🔀
  • --no-text-reorder — disable text section reordering for GCC section names 🚫
  • --threads — run the linker multi-threaded 🧵
  • --no-threads — do not run the linker multi-threaded (default) 🚫
  • --thread-count COUNT — number of threads to use 🔢
  • --thread-count-initial COUNT — number of threads to use in initial pass 🏁
  • --thread-count-middle COUNT — number of threads to use in middle pass 🏃
  • --thread-count-final COUNT — number of threads to use in final pass 🏁
  • --tls-optimize — (PowerPC/64 only) optimize GD/LD/IE code to IE/LE (default) ⚡
  • --no-tls-optimize — (PowerPC/64 only) Don'''t try to optimize TLS accesses 🚫
  • --tls-get-addr-optimize — (PowerPC/64 only) use a special __tls_get_addr call (default) 📞
  • --no-tls-get-addr-optimize — (PowerPC/64 only) don't use a special __tls_get_addr call 🚫
  • --toc-optimize — (PowerPC64 only) optimize TOC code sequences (default) 🧠
  • --no-toc-optimize — (PowerPC64 only) don't optimize TOC code sequences 🚫
  • --toc-sort — (PowerPC64 only) sort TOC and GOT sections (default) 🔤
  • --no-toc-sort — (PowerPC64 only) don't sort TOC and GOT sections 🚫
  • -T FILE, --script FILE — read linker script 📜
  • -Tbss ADDRESS — set the address of the bss segment 🏠
  • -Tdata ADDRESS — set the address of the data segment 🏠
  • -Ttext ADDRESS — set the address of the text segment 🏠
  • -Ttext-segment ADDRESS — set the address of the text segment 🏠
  • -Trodata-segment ADDRESS — set the address of the rodata segment 🏠
  • -u SYMBOL, --undefined SYMBOL — create undefined reference to SYMBOL 🔗
  • --unresolved-symbols — how to handle unresolved symbols. Values: ignore-all, report-all, ignore-in-object-files, ignore-in-shared-libs 🤔
  • --verbose — alias for --debug=files 🗣️
  • --version-script FILE — read version script 📜
  • --warn-common — warn about duplicate common symbols ⚠️
  • --no-warn-common — do not warn about duplicate common symbols (default) 🤐
  • --warn-constructors — ignored 🙈
  • --no-warn-constructors — ignored 🙈
  • --warn-drop-version — warn when discarding version information ⚠️
  • --no-warn-drop-version — do not warn when discarding version information (default) 🤐
  • --warn-execstack — warn if the stack is executable ⚠️
  • --no-warn-execstack — do not warn if the stack is executable (default) 🤐
  • --no-warn-mismatch — don't warn about mismatched input files 🤐
  • --warn-multiple-gp — ignored 🙈
  • --warn-search-mismatch — warn when skipping an incompatible library (default) ⚠️
  • --no-warn-search-mismatch — don't warn when skipping an incompatible library 🤐
  • --warn-shared-textrel — warn if text segment is not shareable ⚠️
  • --no-warn-shared-textrel — do not warn if text segment is not shareable (default) 🤐
  • --warn-unresolved-symbols — report unresolved symbols as warnings ⚠️
  • --error-unresolved-symbols — report unresolved symbols as errors (default) ❌
  • -z buildd — dummy z option 🧸
  • --no-wchar-size-warning — (ARM only) do not warn about objects with incompatible wchar_t sizes 🤐
  • --weak-unresolved-symbols — convert unresolved symbols to weak references 🫠
  • --whole-archive — include all archive contents 📦
  • --no-whole-archive — include only needed archive contents (default) 🎯
  • --wrap SYMBOL — use wrapper functions for SYMBOL 🎁
  • -x, --discard-all — delete all local symbols 🗑️
  • -X, --discard-locals — delete all temporary local symbols 🗑️
  • --discard-none — keep all local symbols 💖
  • -y SYMBOL, --trace-symbol SYMBOL — trace references to symbol 🔍
  • --undefined-version — allow unused version in script (default) ✅
  • --no-undefined-version — do not allow unused version in script 🚫
  • -Y PATH — default search path for Solaris compatibility ☀️
  • -(, --start-group — start a library search group 🏁
  • -), --end-group — end a library search group 🏁
  • -z combreloc — sort dynamic relocs (default) 🔤
  • -z nocombreloc — do not sort dynamic relocs 🚫
  • -z common-page-size=SIZE — set common page size to SIZE 📏
  • -z defs — report undefined symbols (even with --shared) ❌
  • -z execstack — mark output as requiring executable stack 🥞
  • -z global — make symbols in DSO available for subsequently loaded objects 🌍
  • -z initfirst — mark DSO to be initialized first at runtime 🥇
  • -z interpose — mark object to interpose all DSOs but executable 🎭
  • -z unique — mark DSO to be loaded at most once, and only in the main namespace 1️⃣
  • -z nounique — do not mark the DSO as one to be loaded only in the main namespace (default) 🚫
  • -z lazy — mark object for lazy runtime binding (default) 😴
  • -z loadfltr — mark object requiring immediate process ⚡
  • -z max-page-size=SIZE — set maximum page size to SIZE 📏
  • -z muldefs — allow multiple definitions of symbols 🔁
  • -z nocopyreloc — do not create copy relocs 🚫
  • -z nodefaultlib — mark object not to use default search paths 🚫
  • -z nodelete — mark DSO non-deletable at runtime 🔒
  • -z nodlopen — mark DSO not available to dlopen 🚫
  • -z nodump — mark DSO not available to dldump 🚫
  • -z noexecstack — mark output as not requiring executable stack 🚫
  • -z now — marks the object for immediate function binding, like it said "no waiting, we're doing this NOW" ✨
  • -z origin — marks the DSO to say it needs immediate $ORIGIN processing at runtime 🏃‍♀️
  • -z relro — where possible, marks variables read-only after relocation. This is the default, bestie, it's the moment 💅
  • -z norelro — don't do that. don't mark variables read-only after relocation 🙈
  • -z stack-size=SIZE — sets the PT_GNU_STACK segment p_memsz to SIZE. literally just that number, queen 👑
  • -z start-stop-visibility=[default,internal,hidden,protected] — picks the ELF symbol visibility for the synthesized __start_* and __stop_* symbols 🦋
  • -z text — do not permit relocations in read-only segments 🚫
  • -z notext — permit relocations in read-only segments. this one is the default 🌸
  • -z textoff — also permits relocations in read-only segments. yep, still the default 😌
  • -z text-unlikely-segment — moves .text.unlikely sections into a separate segment ✨
  • -z notext-unlikely-segment — does not move .text.unlikely sections to a separate segment. (default, if you were wondering) 🌈
  • -z keep-text-section-prefix — keeps .text.hot, .text.startup, .text.exit and .text.unlikely as separate sections in the final binary. main character sections, they don't share a room 💖
  • -z nokeep-text-section-prefix — merges all .text.* prefix sections together. (default) 🎀

and if you ever forget all of this (you won't, you're doing amazing), just run

gold --help

for a list of supported targets and emulations 🫶

🐛 REPORTING BUGS 🐛

Found a bug? First of all, not your fault, and second of all — tell the people who can fix it:

Report bugs to <https://sourceware.org/bugzilla/>

fr fr, they want to hear about it 💜

Copyright © 2024 Free Software Foundation, Inc. This program is free software; you may redistribute it under the terms of the GNU General Public License version 3 or (at your option) a later version. This program has absolutely no warranty 😭 (yes, really — no warranty, no cap, zero, nada, don't come for them if it breaks)

okay bestie that's the whole page, you ate it, you read the entire manual 💅✨

this was GNU gold (from GNU Binutils for Ubuntu), dated December 2025 — go compile something iconic, ily, bye 🎀🦋💖

📦 where this page comes from