1080 lines · plain
1.\" Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.2.\" See https://llvm.org/LICENSE.txt for license information.3.\" SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception4.\"5.\" This man page documents only lld's ELF linking support, obtained originally6.\" from FreeBSD.7.Dd Jul 25, 20238.Dt LD.LLD 19.Os10.Sh NAME11.Nm ld.lld12.Nd ELF linker from the LLVM project13.Sh SYNOPSIS14.Nm ld.lld15.Op Ar options16.Ar objfile ...17.Sh DESCRIPTION18A linker takes one or more object, archive, and library files, and combines19them into an output file (an executable, a shared library, or another object20file).21It relocates code and data from the input files and resolves symbol22references between them.23.Pp24.Nm25is a drop-in replacement for the GNU BFD and gold linkers.26It accepts most of the same command line arguments and linker scripts27as GNU linkers.28.Pp29.Nm30currently supports i386, x86-64, ARM, AArch64, LoongArch, PowerPC32,31PowerPC64, MIPS32, MIPS64, RISC-V, AMDGPU, Hexagon and SPARC V9 targets.32.Nm33acts as a Microsoft link.exe-compatible linker if invoked as34.Nm lld-link35and as macOS's ld if invoked as36.Nm ld.ld64.37All these targets are always supported however38.Nm39was built, so you can always use40.Nm41as a native linker as well as a cross linker.42.Sh OPTIONS43Many options have both a single-letter and long form.44When using the long form options other than those beginning with the45letter46.Cm o47may be specified using either one or two dashes preceding the option name.48Long options beginning with49.Cm o50require two dashes to avoid confusion with the51.Fl o Ar path52option.53.Pp54.Bl -tag -width indent55.It Fl -allow-multiple-definition56Do not error if a symbol is defined multiple times.57The first definition will be used.58.It Fl -allow-shlib-undefined59Allow unresolved references in shared libraries.60This option is enabled by default when linking a shared library.61.It Fl -apply-dynamic-relocs62Apply link-time values for dynamic relocations.63.It Fl -as-needed64Only set65.Dv DT_NEEDED66for shared libraries if used.67.It Fl -auxiliary Ns = Ns Ar value68Set the69.Dv DT_AUXILIARY70field to the specified name.71.It Fl -Bdynamic , Fl -dy72Link against shared libraries.73.It Fl -Bstatic , Fl -static , Fl -dn74Do not link against shared libraries.75.It Fl Bno-symbolic76Don't bind default visibility defined symbols locally for77.Fl shared78(default).79.It Fl Bsymbolic80Bind default visibility defined symbols locally for81.Fl shared.82Also set the83.Dv DF_SYMBOLIC84flag.85.It Fl Bsymbolic-non-weak86Bind default visibility defined STB_GLOBAL symbols locally for87.Fl shared.88.It Fl Bsymbolic-functions89Bind default visibility defined function symbols locally for90.Fl shared.91.It Fl Bsymbolic-non-weak-functions92Bind default visibility defined STB_GLOBAL function symbols locally for93.Fl shared.94.It Fl -be895Write a Big Endian ELF File using BE8 format(AArch32 only)96.It Fl -branch-to-branch97Enable the branch-to-branch optimizations: a branch whose target is98another branch instruction is rewritten to point to the latter branch99target (AArch64 and X86_64 only). Enabled by default at100.Fl O2 Ns .101.It Fl -build-id Ns = Ns Ar value102Generate a build ID note.103.Ar value104may be one of105.Cm fast ,106.Cm md5 ,107.Cm sha1 ,108.Cm tree ,109.Cm uuid ,110.Cm 0x Ns Ar hex-string ,111and112.Cm none .113.Cm tree114is an alias for115.Cm sha1 .116Build-IDs of type117.Cm fast ,118.Cm md5 ,119.Cm sha1 ,120and121.Cm tree122are calculated from the object contents.123.Cm fast124is not intended to be cryptographically secure.125.It Fl -build-id126Synonym for127.Fl -build-id Ns = Ns Cm sha1 .128.It Fl -call-graph-profile-sort Ns = Ns Ar algorithm129.Ar algorithm130may be:131.Pp132.Bl -tag -width 2n -compact133.It Cm none134Ignore call graph profile.135.It Cm hfsort136Use hfsort.137.It Cm cdsort138Use cdsort (default).139.El140.Pp141.It Fl -color-diagnostics Ns = Ns Ar value142Use colors in diagnostics.143.Ar value144may be one of145.Cm always ,146.Cm auto ,147and148.Cm never .149.Cm auto150enables color if and only if output is to a terminal.151.It Fl -color-diagnostics152Alias for153.Fl -color-diagnostics Ns = Ns Cm auto .154.It Fl -compress-debug-sections Ns = Ns Ar value155Compress DWARF debug sections.156The sections remain uncompressed if compressed content would be larger.157.Cm value158may be159.Pp160.Bl -tag -width 2n -compact161.It Cm none162No compression.163.It Cm zlib164The default compression level is 1 (fastest) as the debug info usually165compresses well at that level.166.It Cm zstd167Use the default compression level in zstd.168.El169.Pp170.It Fl -compress-sections Ns = Ns Ar section-glob={none,zlib,zstd}[:level]171Compress output sections that match the glob and do not have the SHF_ALLOC flag.172The matched sections remain uncompressed if compressed content would be larger.173The compression level is174.Cm level175(if specified) or a default speed-focused level.176This is like a generalized177.Cm --compress-debug-sections.178.It Fl -cref179Output cross reference table. If180.Fl Map181is specified, print to the map file.182.It Fl -debug-names183Generate a merged184.Li .debug_names185section.186.It Fl -default-script Ns = Ns Ar file , Fl dT Ar file187In the absence of188.Fl -script ,189read this default linker script.190.It Fl -defsym Ns = Ns Ar symbol Ns = Ns Ar expression191Define a symbol alias.192.Ar expression193may be another symbol or a linker script expression.194For example,195.Ql --defsym=foo=bar196or197.Ql --defsym=foo=bar+0x100 .198.It Fl -demangle199Demangle symbol names.200.It Fl -disable-new-dtags201Disable new dynamic tags.202.It Fl -discard-all , Fl x203Delete all local symbols.204.It Fl -discard-locals , Fl X205Delete temporary local symbols.206.It Fl -discard-none207Keep all symbols in the symbol table.208.It Fl -dynamic-linker Ns = Ns Ar value209Specify the dynamic linker to be used for a dynamically linked executable.210This is recorded in an ELF segment of type211.Dv PT_INTERP .212.It Fl -dynamic-list Ns = Ns Ar file213Similar to214.Cm --export-dynamic-symbol-list .215When creating a shared object, implies216.Cm -Bsymbolic217but does not set DF_SYMBOLIC218.It Fl -EB219Select the big-endian format in the OUTPUT_FORMAT command.220.It Fl -EL221Select the little-endian format in the OUTPUT_FORMAT command.222.It Fl -eh-frame-hdr223Request creation of224.Li .eh_frame_hdr225section and226.Dv PT_GNU_EH_FRAME227segment header.228.It Fl -emit-relocs , Fl q229Generate relocations in the output.230.It Fl -enable-new-dtags231Enable new dynamic tags.232.It Fl -enable-non-contiguous-regions233Spill input sections to later matching output sections to avoid memory region overflow.234.It Fl -end-lib235End a grouping of objects that should be treated as if they were together236in an archive.237.It Fl -entry Ns = Ns Ar entry238Name of entry point symbol.239.It Fl -error-limit Ns = Ns Ar value240Maximum number of errors to emit before stopping.241A value of zero indicates that there is no limit.242.It Fl -error-unresolved-symbols243Report unresolved symbols as errors.244.It Fl -error-handing-script Ns = Ns Ar script_path245Call script246.Ar script_path247upon some error, with248.Ar tag249as first argument, and an extra parameter as second argument. The script is250expected to return 0 on success. Any other value is considered a generic error.251.Ar tag252may be253.Cm missing-lib254followed by the name of the missing library.255.Cm undefined-symbol256followed by the name of the undefined symbol.257.It Fl -execute-only258Mark executable sections unreadable.259This option is currently only supported on AArch64.260.It Fl -exclude-libs Ns = Ns Ar value261Exclude static libraries from automatic export.262.It Fl -export-dynamic , Fl E263Put symbols in the dynamic symbol table.264.It Fl -export-dynamic-symbol Ns = Ns Ar glob265(executable) Put matched non-local defined symbols to the dynamic symbol table.266(shared object) References to matched non-local STV_DEFAULT symbols shouldn't be bound to definitions within the shared object even if they would otherwise be due to267.Cm -Bsymbolic268,269.Cm -Bsymbolic-functions270or271.Cm --dynamic-list272.It Fl -export-dynamic-symbol-list Ns = Ns Ar file273Read a list of dynamic symbol patterns from274.Ar file .275Apply276.Cm --export-dynamic-symbol277on each pattern.278.It Fl -fatal-warnings279Treat warnings as errors.280.It Fl -filter Ns = Ns Ar value , Fl F Ar value281Set the282.Dv DT_FILTER283field to the specified value.284.It Fl -fini Ns = Ns Ar symbol285Specify a finalizer function.286.It Fl -force-group-allocation287Only meaningful for -r. Section groups are discarded. If two section group members are placed to the same output section, combine their relocations as well.288.It Fl -format Ns = Ns Ar input-format , Fl b Ar input-format289Specify the format of the inputs following this option.290.Ar input-format291may be one of292.Cm binary ,293.Cm elf ,294and295.Cm default .296.Cm default297is a synonym for298.Cm elf .299.It Fl -gc-sections300Enable garbage collection of unused sections.301.It Fl -gdb-index302Generate303.Li .gdb_index304section.305.It Fl -hash-style Ns = Ns Ar value306Specify hash style.307.Ar value308may be309.Cm sysv ,310.Cm gnu ,311or312.Cm both .313.Cm both314is the default.315.It Fl -help316Print a help message.317.It Fl -icf Ns = Ns Cm all318Enable identical code folding.319.It Fl -icf Ns = Ns Cm safe320Enable safe identical code folding.321.It Fl -icf Ns = Ns Cm none322Disable identical code folding.323.It Fl -ignore-data-address-equality324Ignore address equality of data. C/C++ requires each data to have a unique325address.326This option allows lld to do unsafe optimization that breaks the327requirement: create copies of read-only data or merge two or more read-only data328that happen to have the same value.329.It Fl -ignore-function-address-equality330Ignore address equality of functions.331This option allows non-PIC calls to a function with non-default visibility in332a shared object.333The function may have different addresses within the executable and within the334shared object.335.It Fl -image-base Ns = Ns Ar value336Set the base address to337.Ar value .338.It Fl -init Ns = Ns Ar symbol339Specify an initializer function.340.It Fl -keep-unique Ns = Ns Ar symbol341Do not fold342.Ar symbol343during ICF.344.It Fl l Ar libName, Fl -library Ns = Ns Ar libName345Root name of library to use.346.It Fl L Ar dir , Fl -library-path Ns = Ns Ar dir347Add a directory to the library search path.348.It Fl -lto-aa-pipeline Ns = Ns Ar value349AA pipeline to run during LTO.350Used in conjunction with351.Fl -lto-newpm-passes .352.It Fl -lto-newpm-passes Ns = Ns Ar value353Passes to run during LTO.354.It Fl -lto-O Ns Ar opt-level355Optimization level for LTO.356.It Fl -lto-partitions Ns = Ns Ar value357Number of LTO codegen partitions.358.It Fl m Ar value359Set target emulation.360.It Fl -Map Ns = Ns Ar file , Fl M Ar file361Print a link map to362.Ar file .363.It Fl -nmagic , Fl n364Do not page align sections, link against static libraries.365.It Fl -no-allow-shlib-undefined366Do not allow unresolved references in shared libraries.367This option is enabled by default when linking an executable.368.It Fl -no-as-needed369Always set370.Dv DT_NEEDED371for shared libraries.372.It Fl -no-color-diagnostics373Do not use colors in diagnostics.374.It Fl -no-demangle375Do not demangle symbol names.376.It Fl -no-dynamic-linker377Inhibit output of an378.Li .interp379section.380.It Fl -no-fortran-common381Do not search archive members for definitions to override COMMON symbols.382.It Fl -no-gc-sections383Disable garbage collection of unused sections.384.It Fl -no-gnu-unique385Disable STB_GNU_UNIQUE symbol binding.386.It Fl -no-merge-exidx-entries387Disable merging .ARM.exidx entries.388.It Fl -no-nmagic389Page align sections.390.It Fl -no-omagic391Do not set the text data sections to be writable, page align sections.392.It Fl -no-relax393Disable target-specific relaxations. For x86-64 this disables R_X86_64_GOTPCRELX and R_X86_64_REX_GOTPCRELX GOT optimization.394.It Fl -no-rosegment395Do not put read-only non-executable sections in their own segment.396.It Fl -undefined-version397Do not report version scripts that refer to undefined symbols.398.It Fl -no-undefined399Report unresolved symbols even if the linker is creating a shared library.400.It Fl -no-warn-mismatch401Do not reject unknown section types.402.It Fl -no-warn-symbol-ordering403Do not warn about problems with the symbol ordering file or call graph profile.404.It Fl -no-warnings , Fl w405Suppress warnings and cancel406.Cm --fatal-warnings.407.It Fl -no-whole-archive408Restores the default behavior of loading archive members.409.It Fl -no-pie , Fl -no-pic-executable410Do not create a position independent executable.411.It Fl -noinhibit-exec412Retain the executable output file whenever it is still usable.413.It Fl -nostdlib414Only search directories specified on the command line.415.It Fl o Ar path416Write the output executable, library, or object to417.Ar path .418If not specified,419.Dv a.out420is used as a default.421.It Fl O Ns Ar value422Optimize output file.423.Ar value424may be:425.Pp426.Bl -tag -width 2n -compact427.It Cm 0428Disable string merging.429.It Cm 1430Enable string merging.431.It Cm 2432Enable string tail merging and branch-to-branch optimization.433.El434.Pp435.Fl O Ns Cm 1436is the default.437.It Fl -oformat Ns = Ns Ar format438Specify the format for the output object file.439The only supported440.Ar format441is442.Cm binary ,443which produces output with no ELF header.444.It Fl -omagic , Fl N445Set the text and data sections to be readable and writable, do not page align446sections, link against static libraries.447.It Fl -opt-remarks-filename Ar file448Write optimization remarks in YAML format to449.Ar file .450.It Fl -opt-remarks-passes Ar pass-regex451Filter optimization remarks by only allowing the passes matching452.Ar pass-regex .453.It Fl -opt-remarks-with-hotness454Include hotness information in the optimization remarks file.455.It Fl -orphan-handling Ns = Ns Ar mode456Control how orphan sections are handled.457An orphan section is one not specifically mentioned in a linker script.458.Ar mode459may be:460.Pp461.Bl -tag -width 2n -compact462.It Cm place463Place orphan sections in suitable output sections.464.It Cm warn465Place orphan sections as for466.Cm place467and also report a warning.468.It Cm error469Place orphan sections as for470.Cm place471and also report an error.472.El473.Pp474.Cm place475is the default.476.It Fl -pack-dyn-relocs Ns = Ns Ar format477Pack dynamic relocations in the given format.478.Ar format479may be:480.Pp481.Bl -tag -width 2n -compact482.It Cm none483Do not pack.484Dynamic relocations are encoded in SHT_REL(A).485.It Cm android486Pack dynamic relocations in SHT_ANDROID_REL(A).487.It Cm relr488Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in489SHT_REL(A).490.It Cm android+relr491Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in492SHT_ANDROID_REL(A).493.El494.Pp495.Cm none496is the default.497If498.Fl -use-android-relr-tags499is specified, use SHT_ANDROID_RELR instead of SHT_RELR.500.Pp501.It Fl -package-metadata502Emit a percent-encoded string to the503.Cm .note.package504section. For example, %25 decodes to a single %.505.It Fl -pic-veneer506Always generate position independent thunks.507.It Fl -pie , Fl -pic-executable508Create a position independent executable.509.It Fl -power10-stubs Ns = Ns Cm mode510Whether to use Power10 instructions in call stubs for R_PPC64_REL24_NOTOC and TOC/NOTOC interworking.511.Ar mode512may be:513.Pp514.Bl -tag -width 2n -compact515.It Cm yes516(default) Use.517.It Cm auto518Currently the same as yes.519.It Cm no520Don't use.521.El522 523.It Fl -print-gc-sections524List removed unused sections.525.It Fl -print-gc-sections Ns = Ns Ar file526List removed unused sections to the specified file.527.It Fl -print-icf-sections528List identical folded sections.529.It Fl -print-map530Print a link map to the standard output.531.It Fl -print-archive-stats Ns = Ns Ar file532Write archive usage statistics to the specified file.533Print the numbers of members and fetched members for each archive.534.It Fl -push-state535Save the current state of536.Fl -as-needed ,537.Fl -static ,538and539.Fl -whole-archive.540.It Fl -pop-state541Restore the states saved by542.Fl -push-state.543.It Fl -randomize-section-padding Ns = Ns Ar seed544Randomly insert padding between input sections and at the start of each segment using the given seed.545Padding is inserted into output sections with names matching the following patterns:546.Cm .bss ,547.Cm .data ,548.Cm .data.rel.ro ,549.Cm .lbss ,550.Cm .ldata ,551.Cm .lrodata ,552.Cm .ltext ,553.Cm .rodata554and555.Cm .text* .556.It Fl --relax-gp557Enable global pointer relaxation for RISC-V.558.It Fl -relocatable , Fl r559Create relocatable object file.560.It Fl -remap-inputs Ns = Ns Ar from-glob=to-file561Input files matching562.Cm from-glob563are mapped to564.Cm to-file.565Use566.Cm /dev/null567to ignore an input file.568.It Fl -remap-inputs-file Ns = Ns Ar file569Remap input files based on patterns in570.Ar file .571Each line in the remap file is of the format572.Cm from-glob=to-file573or a comment starting with574.Cm # .575.It Fl -reproduce Ns = Ns Ar path576Write a tar file to577.Ar path,578containing all the input files needed to reproduce the link, a text file called579response.txt containing the command line options and a text file called580version.txt containing the output of ld.lld --version.581The archive when582unpacked can be used to re-run the linker with the same options and input files.583.It Fl -retain-symbols-file Ns = Ns Ar file584Retain only the symbols listed in the file.585.It Fl -rpath Ns = Ns Ar value , Fl R Ar value586Add a587.Dv DT_RUNPATH588to the output.589.It Fl -rsp-quoting Ns = Ns Ar value590Quoting style for response files.591The supported values are592.Cm windows593and594.Cm posix .595.It Fl -script Ns = Ns Ar file , Fl T Ar file596Read linker script from597.Ar file .598If multiple linker scripts are given, they are processed as if they599were concatenated in the order they appeared on the command line.600.It Fl -section-start Ns = Ns Ar section Ns = Ns Ar address601Set address of section.602.It Fl -shared , Fl -Bsharable603Build a shared object.604.It Fl -shuffle-sections Ns = Ns Ar seed605Shuffle matched sections using the given seed before mapping them to the output sections.606If -1, reverse the section order. If 0, use a random seed.607.It Fl -soname Ns = Ns Ar value , Fl h Ar value608Set609.Dv DT_SONAME610to611.Ar value .612.It Fl -sort-common613This option is ignored for GNU compatibility.614.It Fl -sort-section Ns = Ns Ar value615Specifies sections sorting rule when linkerscript is used.616.It Fl -start-lib617Start a grouping of objects that should be treated as if they were together618in an archive.619.It Fl -strip-all , Fl s620Strip all symbols.621Implies622.Fl -strip-debug .623.It Fl -strip-debug , Fl S624Strip debugging information.625.It Fl -symbol-ordering-file Ns = Ns Ar file626Lay out sections in the order specified by627.Ar file .628.It Fl -sysroot Ns = Ns Ar value629Set the system root.630.It Fl -target1-abs631Interpret632.Dv R_ARM_TARGET1633as634.Dv R_ARM_ABS32 .635.It Fl -target1-rel636Interpret637.Dv R_ARM_TARGET1638as639.Dv R_ARM_REL32 .640.It Fl -target2 Ns = Ns Ar type641Interpret642.Dv R_ARM_TARGET2643as644.Ar type ,645where646.Ar type647is one of648.Cm rel ,649.Cm abs ,650or651.Cm got-rel .652.It Fl -Tbss Ns = Ns Ar value653Same as654.Fl -section-start655with656.Li .bss657as the sectionname.658.It Fl -Tdata Ns = Ns Ar value659Same as660.Fl -section-start661with662.Li .data663as the sectionname.664.It Fl -Ttext Ns = Ns Ar value665Same as666.Fl -section-start667with668.Li .text669as the sectionname.670.It Fl -thinlto-cache-dir Ns = Ns Ar value671Path to ThinLTO cached object file directory.672.It Fl -thinlto-cache-policy Ns = Ns Ar value673Pruning policy for the ThinLTO cache.674.It Fl -thinlto-jobs Ns = Ns Ar value675Number of ThinLTO jobs.676.It Fl -threads Ns = Ns Ar N677Number of threads.678.Cm all679(default) means all of concurrent threads supported.680.Cm 1681disables multi-threading.682.It Fl -fat-lto-objects683Use the .llvm.lto section, which contains LLVM bitcode, in fat LTO object files to perform LTO.684.It Fl -no-fat-lto-objects685Ignore the .llvm.lto section in relocatable object files (default).686.It Fl -time-trace687Record time trace.688.It Fl -time-trace-file Ns = Ns Ar file689Write time trace output to690.Ar file .691.It Fl -time-trace-granularity Ns = Ns Ar value692Minimum time granularity (in microseconds) traced by time profiler.693.It Fl -trace694Print the names of the input files.695.It Fl -trace-symbol Ns = Ns Ar symbol , Fl y Ar symbol696Trace references to697.Ar symbol .698.It Fl -undefined Ns = Ns Ar symbol , Fl u Ar symbol699If700.Ar symbol701is not defined after symbol resolution, and there's a static library702that contains an object file defining the symbol, load the member703to include the object file in the output file.704.It Fl -undefined-glob Ns = Ns Ar pattern705Synonym for706.Fl -undefined ,707except that it takes a glob pattern.708In a glob pattern,709.Cm *710matches zero or more characters,711.Cm ?712matches any single character, and713.Cm [...]714matches the characters within brackets.715All symbols that match716a given pattern are handled as if they were given as arguments of717.Fl -undefined .718.It Fl -unique719Creates a separate output section for every orphan input section.720.It Fl -unresolved-symbols Ns = Ns Ar value721Determine how to handle unresolved symbols.722.Ar value723may be:724.Pp725.Bl -tag -width 2n -compact726.It Cm report-all727Report unresolved symbols (default).728.It Cm ignore-in-object-files729Only report unresolved symbols contained in shared libraries.730.It Cm ignore-in-shared-libs731Only report unresolved symbols contained in object files.732.It Cm ignore-all733Do not report unresolved symbols.734.El735.It Fl -use-android-relr-tags736Use SHT_ANDROID_RELR / DT_ANDROID_RELR* tags instead of SHT_RELR / DT_RELR*.737.It Fl v , Fl V738Display the version number and proceed with linking if object files are739specified.740.It Fl -version741Display the version number and exit.742.It Fl -verbose743Verbose mode.744.It Fl -version-script Ns = Ns Ar file745Read version script from746.Ar file .747.It Fl -warn-backrefs748Warn about reverse or cyclic dependencies to or between static archives.749This can be used to ensure linker invocation remains compatible with750traditional Unix-like linkers.751.It Fl -warn-backrefs-exclude Ns = Ns Ar glob752Glob describing an archive (or an object file within --start-lib)753which should be ignored for754.Fl -warn-backrefs755.It Fl -warn-common756Warn about duplicate common symbols.757.It Fl -warn-ifunc-textrel758Warn about using ifunc symbols in conjunction with text relocations.759Older versions of glibc library (2.28 and earlier) has a bug that causes760the segment that includes ifunc symbols to be marked as not executable when761they are relocated.762As a result, although the program compiles and links763successfully, it gives segmentation fault when the instruction pointer reaches764an ifunc symbol.765Use -warn-ifunc-textrel to let lld give a warning, if the766code may include ifunc symbols, may do text relocations and be linked with767an older glibc version.768Otherwise, there is no need to use it, as the default value does not give a769warning.770This flag has been introduced in late 2018, has no counter part in ld and gold771linkers, and may be removed in the future.772.It Fl -warn-unresolved-symbols773Report unresolved symbols as warnings.774.It Fl -whole-archive775Force load of all members in a static library.776.It Fl -why-extract Ns = Ns Ar file777Print to a file about why archive members are extracted.778.It Fl -why-live Ns = Ns Ar glob779Report a chain of references preventing garbage collection for each symbol matching the glob.780.It Fl -wrap Ns = Ns Ar symbol781Redirect782.Ar symbol783references to784.Ar __wrap_symbol785and786.Ar __real_symbol787references to788.Ar symbol.789.It Fl z Ar option790Linker option extensions.791.Bl -tag -width indent -compact792.Pp793.It Cm dead-reloc-in-nonalloc Ns = Ns Ar section_glob=value794Resolve a relocation in a matched non-SHF_ALLOC section referencing a discarded symbol to795.Ar value796Accepts globs, in the event of a section matching more than one option, the last797option takes precedence. An order of least specific to most specific match is798recommended.799.Pp800.It Cm execstack801Make the main stack executable.802Stack permissions are recorded in the803.Dv PT_GNU_STACK804segment.805.Pp806.It Cm bti-report Ns = Ns Ar [none|warning|error]807Specify how to report the missing GNU_PROPERTY_AARCH64_FEATURE_1_BTI property.808.Cm none809is the default, linker will not report the missing property otherwise will be reported as a warning or an error.810.Pp811.It Cm cet-report Ns = Ns Ar [none|warning|error]812Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT or GNU_PROPERTY_X86_FEATURE_1_SHSTK properties.813.Cm none814is the default, linker will not report the missing property otherwise will be reported as a warning or an error.815.Pp816.It Cm gcs-report Ns = Ns Ar [none|warning|error]817Specify how to report missing818.Cm GNU_PROPERTY_AARCH64_FEATURE_1_GCS819property. GNU_PROPERTY_AARCH64_FEATURE_1_GCS indicates object file support for the Guarded Control Stack security feature.820.Cm none821is the default, linker will not report the missing property otherwise will be reported as a warning or an error.822.Pp823.It Cm dynamic-undefined-weak824Make undefined weak symbols dynamic when the dynamic symbol table is present, if they are referenced from825relocatable object files and not forced local by symbol visibility or versioning. Do not make them dynamic when826.Cm nodynamic-undefined-weak827is specified.828.Cm dynamic-undefined-weak829is the default when building a shared object, or when an input shared object is present.830.Pp831.It Cm pauth-report Ns = Ns Ar [none|warning|error]832Specify how to report the missing GNU_PROPERTY_AARCH64_FEATURE_PAUTH property.833.Cm none834is the default, linker will not report the missing property otherwise will be reported as a warning or an error.835.Pp836.It Cm force-bti837Force enable AArch64 BTI instruction in PLT, warn if Input ELF file does not have GNU_PROPERTY_AARCH64_FEATURE_1_BTI property.838.Pp839.It Cm force-ibt840Force enable Intel Indirect Branch Tracking in PLT, warn if an input ELF file841does not have GNU_PROPERTY_X86_FEATURE_1_IBT property.842.Pp843.It Cm global844Sets the845.Dv DF_1_GLOBAL flag in the846.Dv DYNAMIC847section.848Different loaders can decide how to handle this flag on their own.849.Pp850.It Cm ifunc-noplt851Do not emit PLT entries for ifunc symbols.852Instead, emit text relocations referencing the resolver.853This is an experimental optimization and only suitable for standalone854environments where text relocations do not have the usual drawbacks.855This option must be combined with the856.Fl z Li notext857option.858.Pp859.It Cm initfirst860Sets the861.Dv DF_1_INITFIRST862flag to indicate the module should be initialized first.863.Pp864.It Cm interpose865Set the866.Dv DF_1_INTERPOSE867flag to indicate to the runtime linker that the object is an interposer.868During symbol resolution interposers are searched after the application869but before other dependencies.870.Pp871.It Cm lrodata-after-bss872Place .lrodata after .bss.873.Pp874.It Cm muldefs875Do not error if a symbol is defined multiple times.876The first definition will be used.877This is a synonym for878.Fl -allow-multiple-definition.879.Pp880.It Cm nocombreloc881Disable combining and sorting multiple relocation sections.882.Pp883.It Cm nocopyreloc884Disable the creation of copy relocations.885.Pp886.It Cm nodefaultlib887Set the888.Dv DF_1_NODEFLIB889flag to indicate that default library search paths should be ignored.890.Pp891.It Cm nodelete892Set the893.Dv DF_1_NODELETE894flag to indicate that the object cannot be unloaded from a process.895.Pp896.It Cm nodlopen897Set the898.Dv DF_1_NOOPEN899flag to indicate that the object may not be opened by900.Xr dlopen 3 .901.Pp902.It Cm nognustack903Do not emit the904.Dv PT_GNU_STACK905segment.906.Pp907.It Cm norelro908Do not indicate that portions of the object should be mapped read-only909after initial relocation processing.910The object will omit the911.Dv PT_GNU_RELRO912segment.913.Pp914.It Cm nosectionheader915Don't generate the section header table.916.Pp917.It Cm notext918Allow relocations against read-only segments.919Sets the920.Dv DT_TEXTREL flag in the921.Dv DYNAMIC922section.923.Pp924.It Cm now925Set the926.Dv DF_BIND_NOW927flag to indicate that the run-time loader should perform all relocation928processing as part of object initialization.929By default relocations may be performed on demand.930.Pp931.It Cm origin932Set the933.Dv DF_ORIGIN934flag to indicate that the object requires935$ORIGIN936processing.937.Pp938.It Cm pac-plt939AArch64 only, use pointer authentication in PLT.940.Pp941.It Cm pack-relative-relocs942Similar to943.Cm -pack-dyn-relocs=relr944, but synthesizes the GLIBC_ABI_DT_RELR version dependency if there is a GLIBC_2.* version dependency.945glibc ld.so rejects loading a dynamically linked object without the GLIBC_ABI_DT_RELR version dependency.946.Pp947.It Cm rel948Use REL format for dynamic relocations.949.Pp950.It Cm rela951Use RELA format for dynamic relocations.952.Pp953.It Cm retpolineplt954Emit retpoline format PLT entries as a mitigation for CVE-2017-5715.955.Pp956.It Cm rodynamic957Make the958.Li .dynamic959section read-only.960The961.Dv DT_DEBUG962tag will not be emitted.963.Pp964.It Cm separate-loadable-segments965.It Cm separate-code966.It Cm noseparate-code967Specify whether two adjacent PT_LOAD segments are allowed to overlap in pages.968.Cm noseparate-code969(default) allows overlap.970.Cm separate-code971allows overlap between two executable segments, or two non-executable segments.972.Cm separate-loadable-segments973disallows overlap.974.Pp975.It Cm shstk976x86 only, use shadow stack.977.Pp978.It Cm gcs Ns = Ns Ar [implicit|never|always]979Specifies how the980.Cm GNU_PROPERTY_AARCH64_FEATURE_1_GCS981bit is set in the output ELF file. When set, it indicates support for the Guarded Control Stack (GCS) security feature.982.Cm implicit983(default) The GCS feature bit is set if all input relocatable files have a .note.gnu.property section containing the GNU_PROPERTY_AARCH64_FEATURE_1_GCS bit.984.Cm never985clears the GCS feature bit regardless of input relocatable files' markings.986.Cm always987sets the GCS feature bit regardless of input object markings.988.Pp989.It Cm stack-size Ns = Ns Ar size990Set the main thread's stack size to991.Ar size .992The stack size is recorded as the size of the993.Ar size .994.Dv PT_GNU_STACK995program segment.996.Pp997.It Cm start-stop-gc998Don't let __start_/__stop_ references retain the associated C identifier name sections (default).999.Pp1000.It Cm nostart-stop-gc1001Let __start_/__stop_ references retain the associated C identifier name sections.1002.Pp1003.It Cm text1004Do not allow relocations against read-only segments.1005This is the default.1006.Pp1007.It Cm nobtcfi1008Create a1009.Dv PT_OPENBSD_NOBTCFI1010segment.1011.Pp1012.It Cm wxneeded1013Create a1014.Dv PT_OPENBSD_WXNEEDED1015segment.1016.El1017.El1018 1019.Sh ENVIRONMENT VARIABLES1020.Bl -tag -width LC_CTYPE1021.It Ev LLD_REPRODUCE1022Create a reproduce tarball with the specified filename. If1023.Fl -reproduce1024is specified,1025.Fl -reproduce1026takes precedence.1027.It Ev LLD_VERSION1028ld.lld creates a section named1029.Cm .comment1030containing the LLD version string. The version string can be overridden by this environment variable,1031which is useful to eliminate differences in the binary caused by LLD version number differences.1032.El1033 1034.Sh IMPLEMENTATION NOTES1035.Nm Ap s1036handing of archive files (those with a1037.Pa .a1038file extension) is different from traditional linkers used on Unix-like1039systems.1040.Pp1041Traditional linkers maintain a set of undefined symbols during linking.1042The linker processes each file in the order in which it appears on the1043command line, until the set of undefined symbols becomes empty.1044An object file is linked into the output object when it is encountered,1045with its undefined symbols added to the set.1046Upon encountering an archive file a traditional linker searches the objects1047contained therein, and processes those that satisfy symbols in the unresolved1048set.1049.Pp1050Handling mutually dependent archives may be awkward when using a traditional1051linker.1052Archive files may have to be specified multiple times, or the special command1053line options1054.Fl -start-group1055and1056.Fl -end-group1057may be used to have the linker loop over the files in the group until no new1058symbols are added to the set.1059.Pp1060.Nm1061records all symbols found in objects and archives as it iterates over1062command line arguments.1063When1064.Nm1065encounters an undefined symbol that can be resolved by an object file1066contained in a previously processed archive file, it immediately extracts1067and links it into the output object.1068.Pp1069With certain archive inputs1070.Nm1071may produce different results compared to traditional linkers.1072In practice, large bodies of third party software have been linked with1073.Nm1074without material issues.1075.Pp1076The1077.Fl -warn-backrefs1078option may be used to identify a linker invocation that may be incompatible1079with traditional Unix-like linker behavior.1080