1LD.LLD(1) BSD General Commands Manual LD.LLD(1)
2
4 ld.lld — ELF linker from the LLVM project
5
7 ld.lld [options] objfile ...
8
10 A linker takes one or more object, archive, and library files, and com‐
11 bines them into an output file (an executable, a shared library, or an‐
12 other object file). It relocates code and data from the input files and
13 resolves symbol references between them.
14 ld.lld is a drop-in replacement for the GNU BFD and gold linkers. It ac‐
16 cepts most of the same command line arguments and linker scripts as GNU
17 linkers.
18 ld.lld currently supports i386, x86-64, ARM, AArch64, PowerPC32, Pow‐
20 erPC64, MIPS32, MIPS64, RISC-V, AMDGPU, Hexagon and SPARC V9 targets.
21 ld.lld acts as a Microsoft link.exe-compatible linker if invoked as
22 lld-link and as macOS's ld if invoked as ld.ld64. All these targets are
23 always supported however ld.lld was built, so you can always use ld.lld
24 as a native linker as well as a cross linker.
25
27 Many options have both a single-letter and long form. When using the
28 long form options other than those beginning with the letter o may be
29 specified using either one or two dashes preceding the option name. Long
30 options beginning with o require two dashes to avoid confusion with the
31 -o path option.
32 --allow-multiple-definition
34 Do not error if a symbol is defined multiple times. The first
35 definition will be used.
36 --allow-shlib-undefined
38 Allow unresolved references in shared libraries. This option is
39 enabled by default when linking a shared library.
40 --apply-dynamic-relocs
42 Apply link-time values for dynamic relocations.
43 --as-needed
45 Only set DT_NEEDED for shared libraries if used.
46 --auxiliary=value
48 Set the DT_AUXILIARY field to the specified name.
49 --Bdynamic, --dy
51 Link against shared libraries.
52 --Bstatic, --static, --dn
54 Do not link against shared libraries.
55 -Bno-symbolic
57 Don't bind default visibility defined symbols locally for -shared
58 (default).
59 -Bsymbolic
61 Bind default visibility defined symbols locally for -shared. Also
62 set the DF_SYMBOLIC flag.
63 -Bsymbolic-functions
65 Bind default visibility defined function symbols locally for
66 -shared.
67 -Bsymbolic-non-weak-functions
69 Bind default visibility defined STB_GLOBAL function symbols lo‐
70 cally for -shared.
71 --build-id=value
73 Generate a build ID note. value may be one of fast, md5, sha1,
74 tree, uuid, 0xhex-string, and none. tree is an alias for sha1.
75 Build-IDs of type fast, md5, sha1, and tree are calculated from
76 the object contents. fast is not intended to be cryptographi‐
77 cally secure.
78 --build-id
80 Synonym for --build-id=fast.
81 --color-diagnostics=value
83 Use colors in diagnostics. value may be one of always, auto, and
84 never. auto enables color if and only if output is to a termi‐
85 nal.
86 --color-diagnostics
88 Alias for --color-diagnostics=auto.
89 --compress-debug-sections=value
91 Compress DWARF debug sections. value may be
92 none
94 No compression.
95 zlib
96 The default compression level is 1 (fastest) as the debug
97 info usually compresses well at that level. If you want to
98 compress it more, you can specify -O2 to set the compression
99 level to 6.
100 zstd
101 The compression level is 5.
102 --cref Output cross reference table. If -Map is specified, print to the
104 map file.
105 --defsym=symbol=expression
107 Define a symbol alias. expression may be another symbol or a
108 linker script expression. For example, ‘--defsym=foo=bar’ or
109 ‘--defsym=foo=bar+0x100’.
110 --demangle
112 Demangle symbol names.
113 --disable-new-dtags
115 Disable new dynamic tags.
116 --discard-all, -x
118 Delete all local symbols.
119 --discard-locals, -X
121 Delete temporary local symbols.
122 --discard-none
124 Keep all symbols in the symbol table.
125 --dynamic-linker=value
127 Specify the dynamic linker to be used for a dynamically linked
128 executable. This is recorded in an ELF segment of type
129 PT_INTERP.
130 --dynamic-list=file
132 Similar to --export-dynamic-symbol-list. When creating a shared
133 object, implies -Bsymbolic but does not set DF_SYMBOLIC
134 --EB Select the big-endian format in the OUTPUT_FORMAT command.
136 --EL Select the little-endian format in the OUTPUT_FORMAT command.
138 --eh-frame-hdr
140 Request creation of .eh_frame_hdr section and PT_GNU_EH_FRAME
141 segment header.
142 --emit-relocs, -q
144 Generate relocations in the output.
145 --enable-new-dtags
147 Enable new dynamic tags.
148 --end-lib
150 End a grouping of objects that should be treated as if they were
151 together in an archive.
152 --entry=entry
154 Name of entry point symbol.
155 --error-limit=value
157 Maximum number of errors to emit before stopping. A value of
158 zero indicates that there is no limit.
159 --error-unresolved-symbols
161 Report unresolved symbols as errors.
162 --error-handing-script=script_path
164 Call script script_path upon some error, with tag as first argu‐
165 ment, and an extra parameter as second argument. The script is
166 expected to return 0 on success. Any other value is considered a
167 generic error. tag may be missing-lib followed by the name of
168 the missing library. undefined-symbol followed by the name of
169 the undefined symbol.
170 --execute-only
172 Mark executable sections unreadable. This option is currently
173 only supported on AArch64.
174 --exclude-libs=value
176 Exclude static libraries from automatic export.
177 --export-dynamic, -E
179 Put symbols in the dynamic symbol table.
180 --export-dynamic-symbol=glob
182 (executable) Put matched non-local defined symbols to the dynamic
183 symbol table. (shared object) References to matched non-local
184 STV_DEFAULT symbols shouldn't be bound to definitions within the
185 shared object even if they would otherwise be due to -Bsymbolic ,
186 -Bsymbolic-functions or --dynamic-list
187 --export-dynamic-symbol-list=file
189 Read a list of dynamic symbol patterns from file. Apply
190 --export-dynamic-symbol on each pattern.
191 --fatal-warnings
193 Treat warnings as errors.
194 --filter=value, -F value
196 Set the DT_FILTER field to the specified value.
197 --fini=symbol
199 Specify a finalizer function.
200 --format=input-format, -b input-format
202 Specify the format of the inputs following this option.
203 input-format may be one of binary, elf, and default. default is
204 a synonym for elf.
205 --gc-sections
207 Enable garbage collection of unused sections.
208 --gdb-index
210 Generate .gdb_index section.
211 --hash-style=value
213 Specify hash style. value may be sysv, gnu, or both. both is
214 the default.
215 --help Print a help message.
217 --icf=all
219 Enable identical code folding.
220 --icf=safe
222 Enable safe identical code folding.
223 --icf=none
225 Disable identical code folding.
226 --ignore-data-address-equality
228 Ignore address equality of data. C/C++ requires each data to have
229 a unique address. This option allows lld to do unsafe optimiza‐
230 tion that breaks the requirement: create copies of read-only data
231 or merge two or more read-only data that happen to have the same
232 value.
233 --ignore-function-address-equality
235 Ignore address equality of functions. This option allows non-PIC
236 calls to a function with non-default visibility in a shared ob‐
237 ject. The function may have different addresses within the exe‐
238 cutable and within the shared object.
239 --image-base=value
241 Set the base address to value.
242 --init=symbol
244 Specify an initializer function.
245 --keep-unique=symbol
247 Do not fold symbol during ICF.
248 -l libName, --library=libName
250 Root name of library to use.
251 -L dir, --library-path=dir
253 Add a directory to the library search path.
254 --lto-aa-pipeline=value
256 AA pipeline to run during LTO. Used in conjunction with
257 --lto-newpm-passes.
258 --lto-newpm-passes=value
260 Passes to run during LTO.
261 --lto-Oopt-level
263 Optimization level for LTO.
264 --lto-partitions=value
266 Number of LTO codegen partitions.
267 -m value
269 Set target emulation.
270 --Map=file, -M file
272 Print a link map to file.
273 --nmagic, -n
275 Do not page align sections, link against static libraries.
276 --no-allow-shlib-undefined
278 Do not allow unresolved references in shared libraries. This op‐
279 tion is enabled by default when linking an executable.
280 --no-as-needed
282 Always set DT_NEEDED for shared libraries.
283 --no-color-diagnostics
285 Do not use colors in diagnostics.
286 --no-demangle
288 Do not demangle symbol names.
289 --no-dynamic-linker
291 Inhibit output of an .interp section.
292 --no-fortran-common
294 Do not search archive members for definitions to override COMMON
295 symbols.
296 --no-gc-sections
298 Disable garbage collection of unused sections.
299 --no-gnu-unique
301 Disable STB_GNU_UNIQUE symbol binding.
302 --no-merge-exidx-entries
304 Disable merging .ARM.exidx entries.
305 --no-nmagic
307 Page align sections.
308 --no-omagic
310 Do not set the text data sections to be writable, page align sec‐
311 tions.
312 --no-relax
314 Disable target-specific relaxations. For x86-64 this disables
315 R_X86_64_GOTPCRELX and R_X86_64_REX_GOTPCRELX GOT optimization.
316 --no-rosegment
318 Do not put read-only non-executable sections in their own seg‐
319 ment.
320 --undefined-version
322 Do not report version scripts that refer to undefined symbols.
323 --no-undefined
325 Report unresolved symbols even if the linker is creating a shared
326 library.
327 --no-warn-symbol-ordering
329 Do not warn about problems with the symbol ordering file or call
330 graph profile.
331 --no-warnings, -w
333 Suppress warnings and cancel --fatal-warnings.
334 --no-whole-archive
336 Restores the default behavior of loading archive members.
337 --no-pie, --no-pic-executable
339 Do not create a position independent executable.
340 --noinhibit-exec
342 Retain the executable output file whenever it is still usable.
343 --nostdlib
345 Only search directories specified on the command line.
346 -o path
348 Write the output executable, library, or object to path. If not
349 specified, a.out is used as a default.
350 -Ovalue
352 Optimize output file size. value may be:
353 0 Disable string merging.
355 1 Enable string merging.
356 2 Enable string tail merging. If --compress-debug-sections is
357 given, compress debug sections at compression level 6 instead
358 of 1.
359 -O1 is the default.
361 --oformat=format
363 Specify the format for the output object file. The only sup‐
364 ported format is binary, which produces output with no ELF
365 header.
366 --omagic, -N
368 Set the text and data sections to be readable and writable, do
369 not page align sections, link against static libraries.
370 --opt-remarks-filename file
372 Write optimization remarks in YAML format to file.
373 --opt-remarks-passes pass-regex
375 Filter optimization remarks by only allowing the passes matching
376 pass-regex.
377 --opt-remarks-with-hotness
379 Include hotness information in the optimization remarks file.
380 --orphan-handling=mode
382 Control how orphan sections are handled. An orphan section is
383 one not specifically mentioned in a linker script. mode may be:
384 place
386 Place orphan sections in suitable output sections.
387 warn
388 Place orphan sections as for place and also report a warning.
389 error
390 Place orphan sections as for place and also report an error.
391 place is the default.
393 --pack-dyn-relocs=format
395 Pack dynamic relocations in the given format. format may be:
396 none
398 Do not pack. Dynamic relocations are encoded in SHT_REL(A).
399 android
400 Pack dynamic relocations in SHT_ANDROID_REL(A).
401 relr
402 Pack relative relocations in SHT_RELR, and the rest of dy‐
403 namic relocations in SHT_REL(A).
404 android+relr
405 Pack relative relocations in SHT_RELR, and the rest of dy‐
406 namic relocations in SHT_ANDROID_REL(A).
407 none is the default. If --use-android-relr-tags is specified,
409 use SHT_ANDROID_RELR instead of SHT_RELR.
410 --pic-veneer
412 Always generate position independent thunks.
413 --pie, --pic-executable
415 Create a position independent executable.
416 --power10-stubs=mode
418 Whether to use Power10 instructions in call stubs for
419 R_PPC64_REL24_NOTOC and TOC/NOTOC interworking. mode may be:
420 yes
422 (default) Use.
423 auto
424 Currently the same as yes.
425 no Don't use.
426 --print-gc-sections
429 List removed unused sections.
430 --print-icf-sections
432 List identical folded sections.
433 --print-map
435 Print a link map to the standard output.
436 --print-archive-stats=file
438 Write archive usage statistics to the specified file. Print the
439 numbers of members and fetched members for each archive.
440 --push-state
442 Save the current state of --as-needed, --static, and
443 --whole-archive.
444 --pop-state
446 Restore the states saved by --push-state.
447 --relocatable, -r
449 Create relocatable object file.
450 --reproduce=path
452 Write a tar file to path, containing all the input files needed
453 to reproduce the link, a text file called response.txt containing
454 the command line options and a text file called version.txt con‐
455 taining the output of ld.lld --version. The archive when un‐
456 packed can be used to re-run the linker with the same options and
457 input files.
458 --retain-symbols-file=file
460 Retain only the symbols listed in the file.
461 --rpath=value, -R value
463 Add a DT_RUNPATH to the output.
464 --rsp-quoting=value
466 Quoting style for response files. The supported values are
467 windows and posix.
468 --script=file, -T file
470 Read linker script from file. If multiple linker scripts are
471 given, they are processed as if they were concatenated in the or‐
472 der they appeared on the command line.
473 --section-start=section=address
475 Set address of section.
476 --shared, --Bsharable
478 Build a shared object.
479 --shuffle-sections=seed
481 Shuffle matched sections using the given seed before mapping them
482 to the output sections. If -1, reverse the section order. If 0,
483 use a random seed.
484 --soname=value, -h value
486 Set DT_SONAME to value.
487 --sort-common
489 This option is ignored for GNU compatibility.
490 --sort-section=value
492 Specifies sections sorting rule when linkerscript is used.
493 --start-lib
495 Start a grouping of objects that should be treated as if they
496 were together in an archive.
497 --strip-all, -s
499 Strip all symbols. Implies --strip-debug.
500 --strip-debug, -S
502 Strip debugging information.
503 --symbol-ordering-file=file
505 Lay out sections in the order specified by file.
506 --sysroot=value
508 Set the system root.
509 --target1-abs
511 Interpret R_ARM_TARGET1 as R_ARM_ABS32.
512 --target1-rel
514 Interpret R_ARM_TARGET1 as R_ARM_REL32.
515 --target2=type
517 Interpret R_ARM_TARGET2 as type, where type is one of rel, abs,
518 or got-rel.
519 --Tbss=value
521 Same as --section-start with .bss as the sectionname.
522 --Tdata=value
524 Same as --section-start with .data as the sectionname.
525 --Ttext=value
527 Same as --section-start with .text as the sectionname.
528 --thinlto-cache-dir=value
530 Path to ThinLTO cached object file directory.
531 --thinlto-cache-policy=value
533 Pruning policy for the ThinLTO cache.
534 --thinlto-jobs=value
536 Number of ThinLTO jobs.
537 --threads=N
539 Number of threads. all (default) means all of concurrent threads
540 supported. 1 disables multi-threading.
541 --time-trace
543 Record time trace.
544 --time-trace-file=file
546 Write time trace output to file.
547 --time-trace-granularity=value
549 Minimum time granularity (in microseconds) traced by time pro‐
550 filer.
551 --trace
553 Print the names of the input files.
554 --trace-symbol=symbol, -y symbol
556 Trace references to symbol.
557 --undefined=symbol, -u symbol
559 If symbol is not defined after symbol resolution, and there's a
560 static library that contains an object file defining the symbol,
561 load the member to include the object file in the output file.
562 --undefined-glob=pattern
564 Synonym for --undefined, except that it takes a glob pattern. In
565 a glob pattern, * matches zero or more characters, ? matches any
566 single character, and [...] matches the characters within brack‐
567 ets. All symbols that match a given pattern are handled as if
568 they were given as arguments of --undefined.
569 --unique
571 Creates a separate output section for every orphan input section.
572 --unresolved-symbols=value
574 Determine how to handle unresolved symbols.
575 --use-android-relr-tags
577 Use SHT_ANDROID_RELR / DT_ANDROID_RELR* tags instead of SHT_RELR
578 / DT_RELR*.
579 -v, -V Display the version number and proceed with linking if object
581 files are specified.
582 --version
584 Display the version number and exit.
585 --verbose
587 Verbose mode.
588 --version-script=file
590 Read version script from file.
591 --warn-backrefs
593 Warn about reverse or cyclic dependencies to or between static
594 archives. This can be used to ensure linker invocation remains
595 compatible with traditional Unix-like linkers.
596 --warn-backrefs-exclude=glob
598 Glob describing an archive (or an object file within --start-lib)
599 which should be ignored for --warn-backrefs
600 --warn-common
602 Warn about duplicate common symbols.
603 --warn-ifunc-textrel
605 Warn about using ifunc symbols in conjunction with text reloca‐
606 tions. Older versions of glibc library (2.28 and earlier) has a
607 bug that causes the segment that includes ifunc symbols to be
608 marked as not executable when they are relocated. As a result,
609 although the program compiles and links successfully, it gives
610 segmentation fault when the instruction pointer reaches an ifunc
611 symbol. Use -warn-ifunc-textrel to let lld give a warning, if
612 the code may include ifunc symbols, may do text relocations and
613 be linked with an older glibc version. Otherwise, there is no
614 need to use it, as the default value does not give a warning.
615 This flag has been introduced in late 2018, has no counter part
616 in ld and gold linkers, and may be removed in the future.
617 --warn-unresolved-symbols
619 Report unresolved symbols as warnings.
620 --whole-archive
622 Force load of all members in a static library.
623 --why-extract=file
625 Print to a file about why archive members are extracted.
626 --wrap=symbol
628 Redirect symbol references to __wrap_symbol and __real_symbol
629 references to symbol.
630 -z option
632 Linker option extensions.
633 dead-reloc-in-nonalloc=section_glob=value
635 Resolve a relocation in a matched non-SHF_ALLOC section
636 referencing a discarded symbol to value Accepts globs, in
637 the event of a section matching more than one option, the
638 last option takes precedence. An order of least specific
639 to most specific match is recommended.
640 execstack
642 Make the main stack executable. Stack permissions are
643 recorded in the PT_GNU_STACK segment.
644 bti-report=[none|warning|error]
646 Specify how to report the missing GNU_PROP‐
647 ERTY_AARCH64_FEATURE_1_BTI property. none is the de‐
648 fault, linker will not report the missing property other‐
649 wise will be reported as a warning or an error.
650 cet-report=[none|warning|error]
652 Specify how to report the missing GNU_PROPERTY_X86_FEA‐
653 TURE_1_IBT or GNU_PROPERTY_X86_FEATURE_1_SHSTK proper‐
654 ties. none is the default, linker will not report the
655 missing property otherwise will be reported as a warning
656 or an error.
657 force-bti
659 Force enable AArch64 BTI instruction in PLT, warn if In‐
660 put ELF file does not have GNU_PROPERTY_AARCH64_FEA‐
661 TURE_1_BTI property.
662 force-ibt
664 Force enable Intel Indirect Branch Tracking in PLT, warn
665 if an input ELF file does not have GNU_PROPERTY_X86_FEA‐
666 TURE_1_IBT property.
667 global Sets the DF_1_GLOBAL flag in the DYNAMIC section. Dif‐
669 ferent loaders can decide how to handle this flag on
670 their own.
671 ifunc-noplt
673 Do not emit PLT entries for ifunc symbols. Instead, emit
674 text relocations referencing the resolver. This is an
675 experimental optimization and only suitable for stand‐
676 alone environments where text relocations do not have the
677 usual drawbacks. This option must be combined with the
678 -z notext option.
679 initfirst
681 Sets the DF_1_INITFIRST flag to indicate the module
682 should be initialized first.
683 interpose
685 Set the DF_1_INTERPOSE flag to indicate to the runtime
686 linker that the object is an interposer. During symbol
687 resolution interposers are searched after the application
688 but before other dependencies.
689 muldefs
691 Do not error if a symbol is defined multiple times. The
692 first definition will be used. This is a synonym for
693 --allow-multiple-definition.
694 nocombreloc
696 Disable combining and sorting multiple relocation sec‐
697 tions.
698 nocopyreloc
700 Disable the creation of copy relocations.
701 nodefaultlib
703 Set the DF_1_NODEFLIB flag to indicate that default li‐
704 brary search paths should be ignored.
705 nodelete
707 Set the DF_1_NODELETE flag to indicate that the object
708 cannot be unloaded from a process.
709 nodlopen
711 Set the DF_1_NOOPEN flag to indicate that the object may
712 not be opened by dlopen(3).
713 nognustack
715 Do not emit the PT_GNU_STACK segment.
716 norelro
718 Do not indicate that portions of the object should be
719 mapped read-only after initial relocation processing.
720 The object will omit the PT_GNU_RELRO segment.
721 notext Allow relocations against read-only segments. Sets the
723 DT_TEXTREL flag in the DYNAMIC section.
724 now Set the DF_BIND_NOW flag to indicate that the run-time
726 loader should perform all relocation processing as part
727 of object initialization. By default relocations may be
728 performed on demand.
729 origin Set the DF_ORIGIN flag to indicate that the object re‐
731 quires $ORIGIN processing.
732 pac-plt
734 AArch64 only, use pointer authentication in PLT.
735 pack-relative-relocs
737 Similar to -pack-dyn-relocs=relr , but synthesizes the
738 GLIBC_ABI_DT_RELR version dependency if there is a
739 GLIBC_2.* version dependency. glibc ld.so rejects load‐
740 ing a dynamically linked object without the
741 GLIBC_ABI_DT_RELR version dependency.
742 rel Use REL format for dynamic relocations.
744 rela Use RELA format for dynamic relocations.
746 retpolineplt
748 Emit retpoline format PLT entries as a mitigation for
749 CVE-2017-5715.
750 rodynamic
752 Make the .dynamic section read-only. The DT_DEBUG tag
753 will not be emitted.
754 separate-loadable-segments
756 separate-code
757 noseparate-code
758 Specify whether two adjacent PT_LOAD segments are allowed
759 to overlap in pages. noseparate-code (default) allows
760 overlap. separate-code allows overlap between two exe‐
761 cutable segments, or two non-executable segments.
762 separate-loadable-segments disallows overlap.
763 shstk x86 only, use shadow stack.
765 stack-size=size
767 Set the main thread's stack size to size. The stack size
768 is recorded as the size of the size. PT_GNU_STACK pro‐
769 gram segment.
770 start-stop-gc
772 Don't let __start_/__stop_ references retain the associ‐
773 ated C identifier name sections (default).
774 nostart-stop-gc
776 Let __start_/__stop_ references retain the associated C
777 identifier name sections.
778 text Do not allow relocations against read-only segments.
780 This is the default.
781 wxneeded
783 Create a PT_OPENBSD_WXNEEDED segment.
784
786 ld.lld's handing of archive files (those with a .a file extension) is
787 different from traditional linkers used on Unix-like systems.
788 Traditional linkers maintain a set of undefined symbols during linking.
790 The linker processes each file in the order in which it appears on the
791 command line, until the set of undefined symbols becomes empty. An ob‐
792 ject file is linked into the output object when it is encountered, with
793 its undefined symbols added to the set. Upon encountering an archive
794 file a traditional linker searches the objects contained therein, and
795 processes those that satisfy symbols in the unresolved set.
796 Handling mutually dependent archives may be awkward when using a tradi‐
798 tional linker. Archive files may have to be specified multiple times, or
799 the special command line options --start-group and --end-group may be
800 used to have the linker loop over the files in the group until no new
801 symbols are added to the set.
802 ld.lld records all symbols found in objects and archives as it iterates
804 over command line arguments. When ld.lld encounters an undefined symbol
805 that can be resolved by an object file contained in a previously pro‐
806 cessed archive file, it immediately extracts and links it into the output
807 object.
808 With certain archive inputs ld.lld may produce different results compared
810 to traditional linkers. In practice, large bodies of third party soft‐
811 ware have been linked with ld.lld without material issues.
812 The --warn-backrefs option may be used to identify a linker invocation
814 that may be incompatible with traditional Unix-like linker behavior.
815BSD May 12, 2019 BSD