GOLD(1)

📦
version 2.44 · 3 versions
, in ubuntu resolute, ubuntu stonking

💖 GOLD 💖

okay bestie, sit DOWN, because we're talking about gold — the GNU ELF linker — from the User Commands corner of your manual pages. this is <rainbow>the</rainbow> linker for people who like their linking fast and their flags plentiful. there are a LOT of options here. like, a lot a lot. but don't panic, we're going through every single one, no skips, no cap. 🫶

✨ NAME ✨

gold — The GNU ELF linker 💅

🌸 SYNOPSIS 🌸

ld.gold [options] file...

👑 OPTIONS 👑

bestie, grab a snack. this is the main character section and it is LONG. but every single flag is here, exactly as written, so you can trust it fr fr.

  • --help — spill the usage info, please 💖
  • -v, --version — tell me the version info
  • -V — version and target info, so you know what you're linking for
  • --add-needed — not supported. nope. not a thing. 🙈
  • --no-add-needed — do NOT copy DT_NEEDED tags from shared libraries (this is the default)
  • --allow-multiple-definition — let symbols be defined multiple times, chaotic but valid
  • --no-allow-multiple-definition — do not allow multiple definitions (default)
  • --allow-shlib-undefined — allow unresolved references in shared libraries
  • --no-allow-shlib-undefined — do not allow unresolved references in shared libraries (default)
  • --apply-dynamic-relocs — apply link-time values for dynamic relocations (default)
  • --no-apply-dynamic-relocs — (aarch64 only!) do not apply link-time values for dynamic relocations
  • --as-needed — only use DT_NEEDED for shared libraries that are actually used, so no freeloaders
  • --no-as-needed — use DT_NEEDED for all shared libraries (default)
  • -assert [ignored] — ignored. literally just vibes.
  • -b [elf,binary], --format [elf,binary] — set the input format
  • --be8 — output a BE8 format image
  • --build-id [=STYLE] — generate a build ID note
  • --build-id-chunk-size-for-treehash SIZE — 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 (default)
  • -Bstatic — -l does not search for shared libraries
  • -dy — alias for -Bdynamic (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 (default)
  • -Bsymbolic-functions — bind default visibility defined function symbols locally for -shared
  • -Bsymbolic — bind default visibility defined symbols locally for -shared
  • --check-sections — check segment addresses for overlaps (default)
  • --no-check-sections — do not check segment addresses for overlaps
  • --compress-debug-sections [none,zlib,zlib-gnu,zlib-gabi,zstd] — compress .debug_* sections in the output file 🗜️
  • --copy-dt-needed-entries — not supported. sorry bestie.
  • --no-copy-dt-needed-entries — do not copy DT_NEEDED tags from shared libraries (default)
  • --cref — output a cross reference table
  • --no-cref — do not output a cross reference table (default)
  • --ctors-in-init-array — use DT_INIT_ARRAY for all constructors (default)
  • --no-ctors-in-init-array — handle constructors as directed by the compiler
  • -d, --define-common — define common symbols
  • --no-define-common — do not define common symbols in relocatable output (default)
  • -dc — alias for -d
  • -dp — alias for -d
  • --debug [all,files,script,task][,...] — turn on debugging, let it yap
  • --defsym SYMBOL=EXPRESSION — define a symbol
  • --demangle [=STYLE] — demangle C++ symbols in log messages so they're actually readable
  • --no-demangle — do not demangle C++ symbols in log messages
  • --dependency-file FILE — write a dependency file listing all files read
  • --detect-odr-violations — look for violations of the C++ One Definition Rule 👀
  • --no-detect-odr-violations — do not look for violations of the C++ One Definition Rule (default)
  • --dynamic-list-data — add data symbols to dynamic symbols
  • --dynamic-list-cpp-new — add C++ operator new/delete to dynamic symbols
  • --dynamic-list-cpp-typeinfo — add C++ typeinfo to dynamic symbols
  • --dynamic-list FILE — read a list of dynamic symbols
  • --emit-stub-syms — (PowerPC only) label linker stubs with a symbol (default)
  • --no-emit-stub-syms — (PowerPC only) do not label linker stubs with a symbol
  • -e ADDRESS, --entry ADDRESS — set program start address
  • --eh-frame-hdr — create exception frame header
  • --no-eh-frame-hdr — do not create exception frame header (default)
  • --enable-new-dtags — enable use of DT_RUNPATH (default)
  • --disable-new-dtags — disable use of DT_RUNPATH
  • --enable-linker-version — put the linker version string into the .comment section
  • --disable-linker-version — put the linker version string into the .note.gnu.gold-version section (default)
  • --no-enum-size-warning — (ARM only) do not warn about objects with incompatible enum sizes
  • --exclude-libs lib,lib ... — exclude libraries from automatic export
  • -E, --export-dynamic — export all dynamic symbols
  • --no-export-dynamic — do not export all dynamic symbols (default)
  • --export-dynamic-symbol SYMBOL — export SYMBOL to the dynamic symbol table
  • -EB — link big-endian objects.
  • -EL — link little-endian objects.
  • -f SHLIB, --auxiliary SHLIB — auxiliary filter for shared object symbol table
  • -F SHLIB, --filter SHLIB — filter for shared object symbol table
  • --fatal-warnings — treat warnings as errors, no more "it's just a warning" energy 💀
  • --no-fatal-warnings — do not treat warnings as errors (default)
  • -fini SYMBOL — call SYMBOL at unload-time
  • --fix-arm1176 — (ARM only) fix binaries for the ARM1176 erratum (default)
  • --no-fix-arm1176 — (ARM only) do not fix binaries for the ARM1176 erratum
  • --fix-cortex-a8 — (ARM only) fix binaries for the Cortex-A8 erratum
  • --no-fix-cortex-a8 — (ARM only) do not fix binaries for the Cortex-A8 erratum (default)
  • --fix-cortex-a53-843419 — (AArch64 only) fix Cortex-A53 erratum 843419
  • --no-fix-cortex-a53-843419 — (AArch64 only) do not fix Cortex-A53 erratum 843419 (default)
  • --fix-cortex-a53-835769 — (AArch64 only) fix Cortex-A53 erratum 835769
  • --no-fix-cortex-a53-835769 — (AArch64 only) do not fix Cortex-A53 erratum 835769 (default)
  • --fix-v4bx — (ARM only) rewrite BX rn as MOV pc, rn for ARMv4
  • --fix-v4bx-interworking — (ARM only) rewrite BX rn branch to ARMv4 interworking veneer
  • -fuse-ld [gold,bfd] — ignored, but it's here for GCC linker option compatibility 🫶
  • -g — ignored. just chillin'.
  • --gc-sections — remove unused sections, declutter your life 🧹
  • --no-gc-sections — do not remove unused sections (default)
  • --gdb-index — generate a .gdb_index section
  • --no-gdb-index — do not generate a .gdb_index section (default)
  • --gnu-unique — enable STB_GNU_UNIQUE symbol binding (default)
  • --no-gnu-unique — disable STB_GNU_UNIQUE symbol binding
  • -G, -shared — generate a shared library
  • -h FILENAME, -soname FILENAME — set the shared library name
  • --hash-bucket-empty-fraction FRACTION — min fraction of empty buckets in the dynamic hash
  • --hash-style [sysv,gnu,both] — dynamic hash style
  • -i — alias for -r
  • --icf [none,all,safe] — Identical Code Folding. and heads up, because this one matters: --icf=safe folds ctors, dtors and functions whose pointers are definitely not taken
  • --icf-iterations COUNT — number of iterations of ICF (default 3)
  • --incremental — do an incremental link if possible; otherwise do a full link and prepare output for incremental linking
  • --no-incremental — do a full link (default)
  • --incremental-full — do a full link and prepare output for incremental linking
  • --incremental-update — do an incremental link; exit if not possible
  • --incremental-base FILE — set base file for incremental linking (default is the output file)
  • --incremental-changed — assume files changed
  • --incremental-unchanged — assume files didn't change
  • --incremental-unknown — use timestamps to check files (default)
  • --incremental-startup-unchanged — assume 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 — set the dynamic linker path
  • --just-symbols FILE — read only symbol values from FILE
  • --keep-files-mapped — keep files mapped across passes (default on 64bit architectures)
  • --no-keep-files-mapped — release mapped files after each pass (default on 32bit architectures)
  • --keep-unique SYMBOL — do not fold this symbol during ICF
  • -l LIBNAME, --library LIBNAME — search for library LIBNAME
  • --ld-generated-unwind-info — generate unwind information for PLT (default)
  • --no-ld-generated-unwind-info — do not generate unwind information for PLT
  • -L DIR, --library-path DIR — add directory to the search path
  • --long-plt — (ARM only) generate long PLT entries
  • --no-long-plt — (ARM only) do not generate long PLT entries (default)
  • -m EMULATION — set GNU linker emulation; obsolete, so, like, retro 👵
  • --map-whole-files — map whole files to memory (default on 64bit architectures)
  • --no-map-whole-files — map relevant file parts to memory (default on 32bit architectures)
  • --merge-exidx-entries — (ARM only) merge exidx entries in debuginfo (default)
  • --no-merge-exidx-entries — (ARM only) do not merge exidx entries in debuginfo
  • --mmap-output-file — map the output file for writing (default)
  • --no-mmap-output-file — do not map the output file for writing
  • -M, --print-map — write map file on standard output
  • -Map MAPFILENAME — write map file
  • -n, --nmagic — do not page align data
  • -N, --omagic — do not page align data, do not make text readonly
  • --no-omagic — page align data, make text readonly (default)
  • --no-keep-memory — use less memory and more disk I/O (included only for compatibility with GNU ld)
  • --no-undefined — report undefined symbols (even with --shared)
  • --noinhibit-exec — create an output file even if errors occur, stubborn queen 💅
  • -nostdlib — only search directories specified on the command line
  • -o FILE, --output FILE — set output file name
  • --oformat [binary] — set output format
  • -O LEVEL, -optimize LEVEL — optimize output file size
  • --orphan-handling [place,discard,warn,error] — orphan section handling
  • -p — ignored for ARM compatibility

okay that's the options list done and honestly?? iconic. but we're NOT done bestie, there's more coming. stay tuned 💖✨

  • --package-metadata [=JSON] — ✨ generates a package metadata note. That's it, that's the whole job.
  • -pie — makes a position independent executable 💅
  • -no-pie — don't make a PIE. This one's the default, bestie.
  • --pic-executable — okay same energy as -pie: make a position independent executable.
  • --no-pic-executable — and again, no PIE. Also default. It's giving "we have two names for everything and we're not sorry".
  • --pic-veneer — forces PIC sequences for ARM/Thumb interworking veneers 🔧
  • -no-pipeline-knowledge — (ARM only) it's just... ignored, kept around for backward compatibility. default, lowkey a fossil 🦕
  • --plt-align [=P2ALIGN] — (PowerPC only) aligns PLT call stubs so they fit cache lines nicely 📐
  • --plt-localentry — (PowerPC64 only) optimizes calls to ELFv2 localentry:0 functions.
  • --no-plt-localentry — (PowerPC64 only) don't do that optimization. default.
  • --plt-static-chain — (PowerPC64 only) PLT call stubs should load r11.
  • --no-plt-static-chain — (PowerPC64 only) they should not load r11. default.
  • --plt-thread-safe — (PowerPC64 only) PLT call stubs get a load-load barrier.
  • --no-plt-thread-safe — (PowerPC64 only) no barrier. default.
  • --plugin PLUGIN — loads a plugin library 🔌
  • --plugin-opt OPTION — passes an option along to that plugin.
  • --posix-fallocate — uses posix_fallocate to reserve space in the output file. default.
  • --no-posix-fallocate — uses fallocate or ftruncate to reserve that space instead.
  • --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 — prereads archive symbols when multi-threaded 🏃♀️
  • --print-gc-sections — lists removed unused sections on stderr 🗑️
  • --no-print-gc-sections — doesn't list them. default.
  • --print-icf-sections — lists folded identical sections on stderr.
  • --no-print-icf-sections — doesn't list them. default.
  • --print-output-format — prints the default output format 🖨️
  • --print-symbol-counts FILENAME — prints symbols defined and used for each input.
  • --push-state — saves the state of flags related to input files 📌
  • --pop-state — restores the state of flags related to input files. Complementary queens, we love to see it 💖
  • -q, --emit-relocs — generates relocations in the output.
  • -Qy — ignored, for SVR4 compatibility. Yes it's just vibing there.
  • -r, -relocatable — generates relocatable output.
  • --relax — relaxes branches on certain targets 😌
  • --no-relax — no branch relaxing. default.
  • --retain-symbols-file FILE — keeps only the symbols listed in this file.
  • --rosegment — puts read-only non-executable sections in their own segment 🌹
  • --no-rosegment — doesn't do that. default.
  • --rosegment-gap OFFSET — sets the offset between executable and read-only segments.
  • -R DIR — adds DIR to the runtime search path.
  • -rpath DIR — adds DIR to the runtime search path. (Same energy, different flag, iykyk.)
  • --rpath-link DIR — adds DIR to the link time shared library search path.
  • -s, --strip-all — strips all symbols. All of them. Gone 💀
  • -S, --strip-debug — strips debugging information.
  • --strip-debug-non-line — emits only debug line number information.
  • --strip-debug-gdb — strips debug symbols that are unused by gdb (at least versions <= 7.4).
  • --strip-lto-sections — strips LTO intermediate code sections. default.
  • --section-ordering-file FILENAME — lays out sections in the order specified 📋
  • --section-start SECTION=ADDRESS — sets the address of a section.
  • --secure-plt — (PowerPC only) uses new-style PLT. default.
  • --sort-common [={ascending,descending}] — sorts common symbols by alignment.
  • --sort-section [none,name] — sorts sections by name. Heads up bestie: --no-text-reorder will override --sort-section=name for .text ⚠️
  • --spare-dynamic-tags COUNT — how many dynamic tag slots to reserve (5 is the default).
  • --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) allows a group of stubs to serve multiple output sections. default.
  • --no-stub-group-multi — (PowerPC only) each output section has its own stubs. No sharing 🙅♀️
  • --split-stack-adjust-size SIZE — stack size when a -fsplit-stack function calls a non-split one.
  • -static — does not link against shared libraries.
  • --start-lib — starts a library.
  • --end-lib — ends a library. 📚
  • --stats — prints resource usage statistics 📊
  • --sysroot DIR — sets the target system root directory.
  • -t, --trace — prints the name of each input file 👀
  • --target1-abs — (ARM only) forces R_ARM_TARGET1 type to R_ARM_ABS32.
  • --target1-rel — (ARM only) forces R_ARM_TARGET1 type to R_ARM_REL32.
  • --target2 [rel, abs, got-rel — (ARM only) sets the R_ARM_TARGET2 relocation type. (Yeah the bracket situation is a little unhinged, we're not fixing it, it's canon 💅)
  • --text-reorder — enables text section reordering for GCC section names. default.
  • --no-text-reorder — disables text section reordering for GCC section names.
  • --threads — runs the linker multi-threaded 🧵
  • --no-threads — doesn't run it multi-threaded. default.
  • --thread-count COUNT — number of threads to use.
  • --thread-count-initial COUNT — number of threads to use in the initial pass.
  • --thread-count-middle COUNT — number of threads to use in the middle pass.
  • --thread-count-final COUNT — number of threads to use in the final pass. Three passes, three thread counts, main character energy ✨
  • --tls-optimize — (PowerPC/64 only) optimizes 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) uses 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) optimizes TOC code sequences. default.
  • --no-toc-optimize — (PowerPC64 only) don't optimize TOC code sequences.
  • --toc-sort — (PowerPC64 only) sorts TOC and GOT sections. default.
  • --no-toc-sort — (PowerPC64 only) don't sort TOC and GOT sections.
  • -T FILE, --script FILE — reads a linker script 📜
  • -Tbss ADDRESS — sets the address of the bss segment.
  • -Tdata ADDRESS — sets the address of the data segment.
  • -Ttext ADDRESS — sets the address of the text segment.
  • -Ttext-segment ADDRESS — sets the address of the text segment. (Yes, again. They're different flags, don't @ me.)
  • -Trodata-segment ADDRESS — sets the address of the rodata segment.
  • -u SYMBOL, --undefined SYMBOL — creates an undefined reference to SYMBOL.
  • --unresolved-symbols — how to handle unresolved symbols. The values are:
    • ignore-all
    • report-all
    • ignore-in-object-files
    • ignore-in-shared-libs
  • --verbose — alias for --debug=files. 🗣️
  • --version-script FILE — reads a version script.
  • --warn-common — warns about duplicate common symbols.
  • --no-warn-common — doesn't warn about duplicate common symbols. default.
  • --warn-constructors — ignored.
  • --no-warn-constructors — also ignored. Both of them. Just out here taking up space 💀
  • --warn-drop-version — warns when discarding version information.
  • --no-warn-drop-version — doesn't warn when discarding version information. default.
  • --warn-execstack — warns if the stack is executable. ⚠️
  • --no-warn-execstack — doesn't warn if the stack is executable. default.
  • --no-warn-mismatch — don't warn about mismatched input files. 🤐
  • --warn-multiple-gp — ignored.
  • --warn-search-mismatch — warns when skipping an incompatible library. default.
  • --no-warn-search-mismatch — doesn't warn when skipping an incompatible library.
  • --warn-shared-textrel — warns if the text segment is not shareable.
  • --no-warn-shared-textrel — doesn't warn if the text segment is not shareable. default.
  • --warn-unresolved-symbols — reports unresolved symbols as warnings.
  • --error-unresolved-symbols — reports unresolved symbols as errors. default. 😤
  • -z buildd — dummy z option. It does nothing and it's iconic for it 👑
  • --no-wchar-size-warning — (ARM only) doesn't warn about objects with incompatible wchar_t sizes.
  • --weak-unresolved-symbols — converts unresolved symbols to weak references.
  • --whole-archive — includes all archive contents.
  • --no-whole-archive — includes only the needed archive contents. default.
  • --wrap SYMBOL — uses wrapper functions for SYMBOL.
  • -x, --discard-all — deletes all local symbols.
  • -X, --discard-locals — deletes all temporary local symbols.
  • --discard-none — keeps all local symbols. 🙌
  • -y SYMBOL, --trace-symbol SYMBOL — traces references to a symbol.
  • --undefined-version — allows unused versions in a script. default.
  • --no-undefined-version — does not allow unused versions in a script.
  • -Y PATH — default search path, for Solaris compatibility.
  • -(, --start-group — starts a library search group.
  • -), --end-group — ends a library search group. (Group hug for your libraries 🫶)
  • -z combreloc — sorts dynamic relocs. default.
  • -z nocombreloc — does not sort dynamic relocs.
  • -z common-page-size=SIZE — sets the common page size to SIZE.
  • -z defs — reports undefined symbols (even with --shared).
  • -z execstack — marks the output as requiring an executable stack. ⚠️
  • -z global — makes symbols in a DSO available for subsequently loaded objects.
  • -z initfirst — marks a DSO to be initialized first at runtime. 🥇
  • -z interpose — marks an object to interpose all DSOs but the executable.
  • -z unique — marks a DSO to be loaded at most once, and only in the main namespace.
  • -z nounique — doesn't mark the DSO as one to be loaded only in the main namespace. default.
  • -z lazy — marks the object for lazy runtime binding. default. 😴
  • -z loadfltr — marks an object as requiring immediate processing.
  • -z max-page-size=SIZE — sets the maximum page size to SIZE.
  • -z muldefs — allows multiple definitions of symbols.
  • -z nocopyreloc — does not create copy relocs.
  • -z nodefaultlib — marks an object as not using the default search paths.
  • -z nodelete — marks a DSO as non-deletable at runtime.
  • -z nodlopen — marks a DSO as not available to dlopen.
  • -z nodump — marks a DSO as not available to dldump.
  • -z noexecstack — marks the output as not requiring an executable stack. ✨
  • -z now — marks the object for immediate function binding, bestie. no lazy stalling, we bind now ✨
  • -z origin — marks the DSO to say "hey, this one needs immediate $ORIGIN processing at runtime" 💫
  • -z relro — where possible, marks variables read-only after relocation. this is the default and it's giving immovable object energy 🛡️
  • -z norelro — the opposite vibe: don't mark those variables read-only after relocation 🙈
  • *-z stack-size=SIZE* — sets the PT_GNU_STACK segment p_memsz to SIZE. yes it really is that literal 💅
  • -z start-stop-visibility=[default,internal,hidden,protected] — sets the ELF symbol visibility for the synthesized __start_* and __stop_* symbols. pick one of those four values, no freestyling 🌸
  • -z text — does not permit relocations in read-only segments. strict queen behavior 👑
  • -z notext — permits relocations in read-only segments. this is the default 🦋
  • -z textoff — also permits relocations in read-only segments. also the default. two names, same slay 💖
  • -z text-unlikely-segment — moves .text.unlikely sections into a separate segment. into their own little apartment fr fr 🏠
  • -z notext-unlikely-segment — does not move .text.unlikely sections to a separate segment. default, they stay put 🎀
  • -z keep-text-section-prefix — keeps .text.hot, .text.startup, .text.exit and .text.unlikely as separate sections in the final binary. no merging, we respect the individual ✨
  • -z nokeep-text-section-prefix — merges all .text.* prefix sections. default, everyone into the group chat 🫶

Run gold --help for a list of supported targets and emulations. like, actually do it, it's a whole menu 💅

🐛 REPORTING BUGS 🐛

Found a bug? Not the cute kind, bestie 😭 Report bugs to <https://sourceware.org/bugzilla/> — the maintainers will literally thank you.

Copyright © 2025 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. ngl, zero warranty, none, nada 💀 read the license before you come for anyone 🫶

and that's a wrap on GOLD(1) 💖 This gorgeous thing is GNU gold (GNU Binutils for Ub..., the name got a lil truncated in the footer lol), dated February 2026. Go forth and link, icon 🌈👑

📦 where this page comes from