| blob | e3db3a20678d955aef62aafddfa7b76a7b771c65 |
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-exception
4 .\"
5 .\" This man page documents only lld's ELF linking support, obtained originally
6 .\" from FreeBSD.
7 .Dd Feb 9, 2023
8 .Dt LD.LLD 1
9 .Os
10 .Sh NAME
11 .Nm ld.lld
12 .Nd ELF linker from the LLVM project
13 .Sh SYNOPSIS
14 .Nm ld.lld
15 .Op Ar options
16 .Ar objfile ...
17 .Sh DESCRIPTION
18 A linker takes one or more object, archive, and library files, and combines
19 them into an output file (an executable, a shared library, or another object
20 file).
21 It relocates code and data from the input files and resolves symbol
22 references between them.
23 .Pp
24 .Nm
25 is a drop-in replacement for the GNU BFD and gold linkers.
26 It accepts most of the same command line arguments and linker scripts
27 as GNU linkers.
28 .Pp
29 .Nm
30 currently supports i386, x86-64, ARM, AArch64, PowerPC32, PowerPC64,
31 MIPS32, MIPS64, RISC-V, AMDGPU, Hexagon and SPARC V9 targets.
32 .Nm
33 acts as a Microsoft link.exe-compatible linker if invoked as
34 .Nm lld-link
35 and as macOS's ld if invoked as
36 .Nm ld.ld64.
37 All these targets are always supported however
38 .Nm
39 was built, so you can always use
40 .Nm
41 as a native linker as well as a cross linker.
42 .Sh OPTIONS
43 Many options have both a single-letter and long form.
44 When using the long form options other than those beginning with the
45 letter
46 .Cm o
47 may be specified using either one or two dashes preceding the option name.
48 Long options beginning with
49 .Cm o
50 require two dashes to avoid confusion with the
51 .Fl o Ar path
52 option.
53 .Pp
54 .Bl -tag -width indent
55 .It Fl -allow-multiple-definition
56 Do not error if a symbol is defined multiple times.
57 The first definition will be used.
58 .It Fl -allow-shlib-undefined
59 Allow unresolved references in shared libraries.
60 This option is enabled by default when linking a shared library.
61 .It Fl -apply-dynamic-relocs
62 Apply link-time values for dynamic relocations.
63 .It Fl -as-needed
64 Only set
65 .Dv DT_NEEDED
66 for shared libraries if used.
67 .It Fl -auxiliary Ns = Ns Ar value
68 Set the
69 .Dv DT_AUXILIARY
70 field to the specified name.
71 .It Fl -Bdynamic , Fl -dy
72 Link against shared libraries.
73 .It Fl -Bstatic , Fl -static , Fl -dn
74 Do not link against shared libraries.
75 .It Fl Bno-symbolic
76 Don't bind default visibility defined symbols locally for
77 .Fl shared
78 (default).
79 .It Fl Bsymbolic
80 Bind default visibility defined symbols locally for
81 .Fl shared.
82 Also set the
83 .Dv DF_SYMBOLIC
84 flag.
85 .It Fl Bsymbolic-functions
86 Bind default visibility defined function symbols locally for
87 .Fl shared.
88 .It Fl Bsymbolic-non-weak-functions
89 Bind default visibility defined STB_GLOBAL function symbols locally for
90 .Fl shared.
91 .It Fl -build-id Ns = Ns Ar value
92 Generate a build ID note.
93 .Ar value
94 may be one of
95 .Cm fast ,
96 .Cm md5 ,
97 .Cm sha1 ,
98 .Cm tree ,
99 .Cm uuid ,
100 .Cm 0x Ns Ar hex-string ,
101 and
102 .Cm none .
103 .Cm tree
104 is an alias for
105 .Cm sha1 .
106 Build-IDs of type
107 .Cm fast ,
108 .Cm md5 ,
109 .Cm sha1 ,
110 and
111 .Cm tree
112 are calculated from the object contents.
113 .Cm fast
114 is not intended to be cryptographically secure.
115 .It Fl -build-id
116 Synonym for
117 .Fl -build-id Ns = Ns Cm fast .
118 .It Fl -color-diagnostics Ns = Ns Ar value
119 Use colors in diagnostics.
120 .Ar value
121 may be one of
122 .Cm always ,
123 .Cm auto ,
124 and
125 .Cm never .
126 .Cm auto
127 enables color if and only if output is to a terminal.
128 .It Fl -color-diagnostics
129 Alias for
130 .Fl -color-diagnostics Ns = Ns Cm auto .
131 .It Fl -compress-debug-sections Ns = Ns Ar value
132 Compress DWARF debug sections.
133 .Cm value
134 may be
135 .Pp
136 .Bl -tag -width 2n -compact
137 .It Cm none
138 No compression.
139 .It Cm zlib
140 The default compression level is 1 (fastest) as the debug info usually
141 compresses well at that level. If you want to compress it more,
142 you can specify
143 .Fl O2
144 to set the compression level to 6.
145 .It Cm zstd
146 The compression level is 5.
147 .El
148 .Pp
149 .It Fl -cref
150 Output cross reference table. If
151 .Fl Map
152 is specified, print to the map file.
153 .It Fl -defsym Ns = Ns Ar symbol Ns = Ns Ar expression
154 Define a symbol alias.
155 .Ar expression
156 may be another symbol or a linker script expression.
157 For example,
158 .Ql --defsym=foo=bar
159 or
160 .Ql --defsym=foo=bar+0x100 .
161 .It Fl -demangle
162 Demangle symbol names.
163 .It Fl -disable-new-dtags
164 Disable new dynamic tags.
165 .It Fl -discard-all , Fl x
166 Delete all local symbols.
167 .It Fl -discard-locals , Fl X
168 Delete temporary local symbols.
169 .It Fl -discard-none
170 Keep all symbols in the symbol table.
171 .It Fl -dynamic-linker Ns = Ns Ar value
172 Specify the dynamic linker to be used for a dynamically linked executable.
173 This is recorded in an ELF segment of type
174 .Dv PT_INTERP .
175 .It Fl -dynamic-list Ns = Ns Ar file
176 Similar to
177 .Cm --export-dynamic-symbol-list .
178 When creating a shared object, implies
179 .Cm -Bsymbolic
180 but does not set DF_SYMBOLIC
181 .It Fl -EB
182 Select the big-endian format in the OUTPUT_FORMAT command.
183 .It Fl -EL
184 Select the little-endian format in the OUTPUT_FORMAT command.
185 .It Fl -eh-frame-hdr
186 Request creation of
187 .Li .eh_frame_hdr
188 section and
189 .Dv PT_GNU_EH_FRAME
190 segment header.
191 .It Fl -emit-relocs , Fl q
192 Generate relocations in the output.
193 .It Fl -enable-new-dtags
194 Enable new dynamic tags.
195 .It Fl -end-lib
196 End a grouping of objects that should be treated as if they were together
197 in an archive.
198 .It Fl -entry Ns = Ns Ar entry
199 Name of entry point symbol.
200 .It Fl -error-limit Ns = Ns Ar value
201 Maximum number of errors to emit before stopping.
202 A value of zero indicates that there is no limit.
203 .It Fl -error-unresolved-symbols
204 Report unresolved symbols as errors.
205 .It Fl -error-handing-script Ns = Ns Ar script_path
206 Call script
207 .Ar script_path
208 upon some error, with
209 .Ar tag
210 as first argument, and an extra parameter as second argument. The script is
211 expected to return 0 on success. Any other value is considered a generic error.
212 .Ar tag
213 may be
214 .Cm missing-lib
215 followed by the name of the missing library.
216 .Cm undefined-symbol
217 followed by the name of the undefined symbol.
218 .It Fl -execute-only
219 Mark executable sections unreadable.
220 This option is currently only supported on AArch64.
221 .It Fl -exclude-libs Ns = Ns Ar value
222 Exclude static libraries from automatic export.
223 .It Fl -export-dynamic , Fl E
224 Put symbols in the dynamic symbol table.
225 .It Fl -export-dynamic-symbol Ns = Ns Ar glob
226 (executable) Put matched non-local defined symbols to the dynamic symbol table.
227 (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 to
228 .Cm -Bsymbolic
229 ,
230 .Cm -Bsymbolic-functions
231 or
232 .Cm --dynamic-list
233 .It Fl -export-dynamic-symbol-list Ns = Ns Ar file
234 Read a list of dynamic symbol patterns from
235 .Ar file .
236 Apply
237 .Cm --export-dynamic-symbol
238 on each pattern.
239 .It Fl -fatal-warnings
240 Treat warnings as errors.
241 .It Fl -filter Ns = Ns Ar value , Fl F Ar value
242 Set the
243 .Dv DT_FILTER
244 field to the specified value.
245 .It Fl -fini Ns = Ns Ar symbol
246 Specify a finalizer function.
247 .It Fl -format Ns = Ns Ar input-format , Fl b Ar input-format
248 Specify the format of the inputs following this option.
249 .Ar input-format
250 may be one of
251 .Cm binary ,
252 .Cm elf ,
253 and
254 .Cm default .
255 .Cm default
256 is a synonym for
257 .Cm elf .
258 .It Fl -gc-sections
259 Enable garbage collection of unused sections.
260 .It Fl -gdb-index
261 Generate
262 .Li .gdb_index
263 section.
264 .It Fl -hash-style Ns = Ns Ar value
265 Specify hash style.
266 .Ar value
267 may be
268 .Cm sysv ,
269 .Cm gnu ,
270 or
271 .Cm both .
272 .Cm both
273 is the default.
274 .It Fl -help
275 Print a help message.
276 .It Fl -icf Ns = Ns Cm all
277 Enable identical code folding.
278 .It Fl -icf Ns = Ns Cm safe
279 Enable safe identical code folding.
280 .It Fl -icf Ns = Ns Cm none
281 Disable identical code folding.
282 .It Fl -ignore-data-address-equality
283 Ignore address equality of data. C/C++ requires each data to have a unique
284 address.
285 This option allows lld to do unsafe optimization that breaks the
286 requirement: create copies of read-only data or merge two or more read-only data
287 that happen to have the same value.
288 .It Fl -ignore-function-address-equality
289 Ignore address equality of functions.
290 This option allows non-PIC calls to a function with non-default visibility in
291 a shared object.
292 The function may have different addresses within the executable and within the
293 shared object.
294 .It Fl -image-base Ns = Ns Ar value
295 Set the base address to
296 .Ar value .
297 .It Fl -init Ns = Ns Ar symbol
298 Specify an initializer function.
299 .It Fl -keep-unique Ns = Ns Ar symbol
300 Do not fold
301 .Ar symbol
302 during ICF.
303 .It Fl l Ar libName, Fl -library Ns = Ns Ar libName
304 Root name of library to use.
305 .It Fl L Ar dir , Fl -library-path Ns = Ns Ar dir
306 Add a directory to the library search path.
307 .It Fl -lto-aa-pipeline Ns = Ns Ar value
308 AA pipeline to run during LTO.
309 Used in conjunction with
310 .Fl -lto-newpm-passes .
311 .It Fl -lto-newpm-passes Ns = Ns Ar value
312 Passes to run during LTO.
313 .It Fl -lto-O Ns Ar opt-level
314 Optimization level for LTO.
315 .It Fl -lto-partitions Ns = Ns Ar value
316 Number of LTO codegen partitions.
317 .It Fl m Ar value
318 Set target emulation.
319 .It Fl -Map Ns = Ns Ar file , Fl M Ar file
320 Print a link map to
321 .Ar file .
322 .It Fl -nmagic , Fl n
323 Do not page align sections, link against static libraries.
324 .It Fl -no-allow-shlib-undefined
325 Do not allow unresolved references in shared libraries.
326 This option is enabled by default when linking an executable.
327 .It Fl -no-as-needed
328 Always set
329 .Dv DT_NEEDED
330 for shared libraries.
331 .It Fl -no-color-diagnostics
332 Do not use colors in diagnostics.
333 .It Fl -no-demangle
334 Do not demangle symbol names.
335 .It Fl -no-dynamic-linker
336 Inhibit output of an
337 .Li .interp
338 section.
339 .It Fl -no-fortran-common
340 Do not search archive members for definitions to override COMMON symbols.
341 .It Fl -no-gc-sections
342 Disable garbage collection of unused sections.
343 .It Fl -no-gnu-unique
344 Disable STB_GNU_UNIQUE symbol binding.
345 .It Fl -no-merge-exidx-entries
346 Disable merging .ARM.exidx entries.
347 .It Fl -no-nmagic
348 Page align sections.
349 .It Fl -no-omagic
350 Do not set the text data sections to be writable, page align sections.
351 .It Fl -no-relax
352 Disable target-specific relaxations. For x86-64 this disables R_X86_64_GOTPCRELX and R_X86_64_REX_GOTPCRELX GOT optimization.
353 .It Fl -no-rosegment
354 Do not put read-only non-executable sections in their own segment.
355 .It Fl -undefined-version
356 Do not report version scripts that refer to undefined symbols.
357 .It Fl -no-undefined
358 Report unresolved symbols even if the linker is creating a shared library.
359 .It Fl -no-warn-symbol-ordering
360 Do not warn about problems with the symbol ordering file or call graph profile.
361 .It Fl -no-warnings , Fl w
362 Suppress warnings and cancel
363 .Cm --fatal-warnings.
364 .It Fl -no-whole-archive
365 Restores the default behavior of loading archive members.
366 .It Fl -no-pie , Fl -no-pic-executable
367 Do not create a position independent executable.
368 .It Fl -noinhibit-exec
369 Retain the executable output file whenever it is still usable.
370 .It Fl -nostdlib
371 Only search directories specified on the command line.
372 .It Fl o Ar path
373 Write the output executable, library, or object to
374 .Ar path .
375 If not specified,
376 .Dv a.out
377 is used as a default.
378 .It Fl O Ns Ar value
379 Optimize output file size.
380 .Ar value
381 may be:
382 .Pp
383 .Bl -tag -width 2n -compact
384 .It Cm 0
385 Disable string merging.
386 .It Cm 1
387 Enable string merging.
388 .It Cm 2
389 Enable string tail merging. If
390 .Fl -compress-debug-sections
391 is given, compress debug sections at compression level 6 instead of 1.
392 .El
393 .Pp
394 .Fl O Ns Cm 1
395 is the default.
396 .It Fl -oformat Ns = Ns Ar format
397 Specify the format for the output object file.
398 The only supported
399 .Ar format
400 is
401 .Cm binary ,
402 which produces output with no ELF header.
403 .It Fl -omagic , Fl N
404 Set the text and data sections to be readable and writable, do not page align
405 sections, link against static libraries.
406 .It Fl -opt-remarks-filename Ar file
407 Write optimization remarks in YAML format to
408 .Ar file .
409 .It Fl -opt-remarks-passes Ar pass-regex
410 Filter optimization remarks by only allowing the passes matching
411 .Ar pass-regex .
412 .It Fl -opt-remarks-with-hotness
413 Include hotness information in the optimization remarks file.
414 .It Fl -orphan-handling Ns = Ns Ar mode
415 Control how orphan sections are handled.
416 An orphan section is one not specifically mentioned in a linker script.
417 .Ar mode
418 may be:
419 .Pp
420 .Bl -tag -width 2n -compact
421 .It Cm place
422 Place orphan sections in suitable output sections.
423 .It Cm warn
424 Place orphan sections as for
425 .Cm place
426 and also report a warning.
427 .It Cm error
428 Place orphan sections as for
429 .Cm place
430 and also report an error.
431 .El
432 .Pp
433 .Cm place
434 is the default.
435 .It Fl -pack-dyn-relocs Ns = Ns Ar format
436 Pack dynamic relocations in the given format.
437 .Ar format
438 may be:
439 .Pp
440 .Bl -tag -width 2n -compact
441 .It Cm none
442 Do not pack.
443 Dynamic relocations are encoded in SHT_REL(A).
444 .It Cm android
445 Pack dynamic relocations in SHT_ANDROID_REL(A).
446 .It Cm relr
447 Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in
448 SHT_REL(A).
449 .It Cm android+relr
450 Pack relative relocations in SHT_RELR, and the rest of dynamic relocations in
451 SHT_ANDROID_REL(A).
452 .El
453 .Pp
454 .Cm none
455 is the default.
456 If
457 .Fl -use-android-relr-tags
458 is specified, use SHT_ANDROID_RELR instead of SHT_RELR.
459 .Pp
460 .It Fl -pic-veneer
461 Always generate position independent thunks.
462 .It Fl -pie , Fl -pic-executable
463 Create a position independent executable.
464 .It Fl -power10-stubs Ns = Ns Cm mode
465 Whether to use Power10 instructions in call stubs for R_PPC64_REL24_NOTOC and TOC/NOTOC interworking.
466 .Ar mode
467 may be:
468 .Pp
469 .Bl -tag -width 2n -compact
470 .It Cm yes
471 (default) Use.
472 .It Cm auto
473 Currently the same as yes.
474 .It Cm no
475 Don't use.
476 .El
478 .It Fl -print-gc-sections
479 List removed unused sections.
480 .It Fl -print-icf-sections
481 List identical folded sections.
482 .It Fl -print-map
483 Print a link map to the standard output.
484 .It Fl -print-archive-stats Ns = Ns Ar file
485 Write archive usage statistics to the specified file.
486 Print the numbers of members and fetched members for each archive.
487 .It Fl -push-state
488 Save the current state of
489 .Fl -as-needed ,
490 .Fl -static ,
491 and
492 .Fl -whole-archive.
493 .It Fl -pop-state
494 Restore the states saved by
495 .Fl -push-state.
496 .It Fl --relax-gp
497 Enable global pointer relaxation for RISC-V.
498 .It Fl -relocatable , Fl r
499 Create relocatable object file.
500 .It Fl -remap-inputs Ns = Ns Ar from-glob=to-file
501 Input files matching
502 .Cm from-glob
503 are mapped to
504 .Cm to-file.
505 Use
506 .Cm /dev/null
507 to ignore an input file.
508 .It Fl -remap-inputs-file Ns = Ns Ar file
509 Remap input files based on patterns in
510 .Ar file .
511 Each line in the remap file is of the format
512 .Cm from-glob=to-file
513 or a comment starting with
514 .Cm # .
515 .It Fl -reproduce Ns = Ns Ar path
516 Write a tar file to
517 .Ar path,
518 containing all the input files needed to reproduce the link, a text file called
519 response.txt containing the command line options and a text file called
520 version.txt containing the output of ld.lld --version.
521 The archive when
522 unpacked can be used to re-run the linker with the same options and input files.
523 .It Fl -retain-symbols-file Ns = Ns Ar file
524 Retain only the symbols listed in the file.
525 .It Fl -rpath Ns = Ns Ar value , Fl R Ar value
526 Add a
527 .Dv DT_RUNPATH
528 to the output.
529 .It Fl -rsp-quoting Ns = Ns Ar value
530 Quoting style for response files.
531 The supported values are
532 .Cm windows
533 and
534 .Cm posix .
535 .It Fl -script Ns = Ns Ar file , Fl T Ar file
536 Read linker script from
537 .Ar file .
538 If multiple linker scripts are given, they are processed as if they
539 were concatenated in the order they appeared on the command line.
540 .It Fl -section-start Ns = Ns Ar section Ns = Ns Ar address
541 Set address of section.
542 .It Fl -shared , Fl -Bsharable
543 Build a shared object.
544 .It Fl -shuffle-sections Ns = Ns Ar seed
545 Shuffle matched sections using the given seed before mapping them to the output sections.
546 If -1, reverse the section order. If 0, use a random seed.
547 .It Fl -soname Ns = Ns Ar value , Fl h Ar value
548 Set
549 .Dv DT_SONAME
550 to
551 .Ar value .
552 .It Fl -sort-common
553 This option is ignored for GNU compatibility.
554 .It Fl -sort-section Ns = Ns Ar value
555 Specifies sections sorting rule when linkerscript is used.
556 .It Fl -start-lib
557 Start a grouping of objects that should be treated as if they were together
558 in an archive.
559 .It Fl -strip-all , Fl s
560 Strip all symbols.
561 Implies
562 .Fl -strip-debug .
563 .It Fl -strip-debug , Fl S
564 Strip debugging information.
565 .It Fl -symbol-ordering-file Ns = Ns Ar file
566 Lay out sections in the order specified by
567 .Ar file .
568 .It Fl -sysroot Ns = Ns Ar value
569 Set the system root.
570 .It Fl -target1-abs
571 Interpret
572 .Dv R_ARM_TARGET1
573 as
574 .Dv R_ARM_ABS32 .
575 .It Fl -target1-rel
576 Interpret
577 .Dv R_ARM_TARGET1
578 as
579 .Dv R_ARM_REL32 .
580 .It Fl -target2 Ns = Ns Ar type
581 Interpret
582 .Dv R_ARM_TARGET2
583 as
584 .Ar type ,
585 where
586 .Ar type
587 is one of
588 .Cm rel ,
589 .Cm abs ,
590 or
591 .Cm got-rel .
592 .It Fl -Tbss Ns = Ns Ar value
593 Same as
594 .Fl -section-start
595 with
596 .Li .bss
597 as the sectionname.
598 .It Fl -Tdata Ns = Ns Ar value
599 Same as
600 .Fl -section-start
601 with
602 .Li .data
603 as the sectionname.
604 .It Fl -Ttext Ns = Ns Ar value
605 Same as
606 .Fl -section-start
607 with
608 .Li .text
609 as the sectionname.
610 .It Fl -thinlto-cache-dir Ns = Ns Ar value
611 Path to ThinLTO cached object file directory.
612 .It Fl -thinlto-cache-policy Ns = Ns Ar value
613 Pruning policy for the ThinLTO cache.
614 .It Fl -thinlto-jobs Ns = Ns Ar value
615 Number of ThinLTO jobs.
616 .It Fl -threads Ns = Ns Ar N
617 Number of threads.
618 .Cm all
619 (default) means all of concurrent threads supported.
620 .Cm 1
621 disables multi-threading.
622 .It Fl -time-trace
623 Record time trace.
624 .It Fl -time-trace-file Ns = Ns Ar file
625 Write time trace output to
626 .Ar file .
627 .It Fl -time-trace-granularity Ns = Ns Ar value
628 Minimum time granularity (in microseconds) traced by time profiler.
629 .It Fl -trace
630 Print the names of the input files.
631 .It Fl -trace-symbol Ns = Ns Ar symbol , Fl y Ar symbol
632 Trace references to
633 .Ar symbol .
634 .It Fl -undefined Ns = Ns Ar symbol , Fl u Ar symbol
635 If
636 .Ar symbol
637 is not defined after symbol resolution, and there's a static library
638 that contains an object file defining the symbol, load the member
639 to include the object file in the output file.
640 .It Fl -undefined-glob Ns = Ns Ar pattern
641 Synonym for
642 .Fl -undefined ,
643 except that it takes a glob pattern.
644 In a glob pattern,
645 .Cm *
646 matches zero or more characters,
647 .Cm ?
648 matches any single character, and
649 .Cm [...]
650 matches the characters within brackets.
651 All symbols that match
652 a given pattern are handled as if they were given as arguments of
653 .Fl -undefined .
654 .It Fl -unique
655 Creates a separate output section for every orphan input section.
656 .It Fl -unresolved-symbols Ns = Ns Ar value
657 Determine how to handle unresolved symbols.
658 .It Fl -use-android-relr-tags
659 Use SHT_ANDROID_RELR / DT_ANDROID_RELR* tags instead of SHT_RELR / DT_RELR*.
660 .It Fl v , Fl V
661 Display the version number and proceed with linking if object files are
662 specified.
663 .It Fl -version
664 Display the version number and exit.
665 .It Fl -verbose
666 Verbose mode.
667 .It Fl -version-script Ns = Ns Ar file
668 Read version script from
669 .Ar file .
670 .It Fl -warn-backrefs
671 Warn about reverse or cyclic dependencies to or between static archives.
672 This can be used to ensure linker invocation remains compatible with
673 traditional Unix-like linkers.
674 .It Fl -warn-backrefs-exclude Ns = Ns Ar glob
675 Glob describing an archive (or an object file within --start-lib)
676 which should be ignored for
677 .Fl -warn-backrefs
678 .It Fl -warn-common
679 Warn about duplicate common symbols.
680 .It Fl -warn-ifunc-textrel
681 Warn about using ifunc symbols in conjunction with text relocations.
682 Older versions of glibc library (2.28 and earlier) has a bug that causes
683 the segment that includes ifunc symbols to be marked as not executable when
684 they are relocated.
685 As a result, although the program compiles and links
686 successfully, it gives segmentation fault when the instruction pointer reaches
687 an ifunc symbol.
688 Use -warn-ifunc-textrel to let lld give a warning, if the
689 code may include ifunc symbols, may do text relocations and be linked with
690 an older glibc version.
691 Otherwise, there is no need to use it, as the default value does not give a
692 warning.
693 This flag has been introduced in late 2018, has no counter part in ld and gold
694 linkers, and may be removed in the future.
695 .It Fl -warn-unresolved-symbols
696 Report unresolved symbols as warnings.
697 .It Fl -whole-archive
698 Force load of all members in a static library.
699 .It Fl -why-extract Ns = Ns Ar file
700 Print to a file about why archive members are extracted.
701 .It Fl -wrap Ns = Ns Ar symbol
702 Redirect
703 .Ar symbol
704 references to
705 .Ar __wrap_symbol
706 and
707 .Ar __real_symbol
708 references to
709 .Ar symbol.
710 .It Fl z Ar option
711 Linker option extensions.
712 .Bl -tag -width indent -compact
713 .Pp
714 .It Cm dead-reloc-in-nonalloc Ns = Ns Ar section_glob=value
715 Resolve a relocation in a matched non-SHF_ALLOC section referencing a discarded symbol to
716 .Ar value
717 Accepts globs, in the event of a section matching more than one option, the last
718 option takes precedence. An order of least specific to most specific match is
719 recommended.
720 .Pp
721 .It Cm execstack
722 Make the main stack executable.
723 Stack permissions are recorded in the
724 .Dv PT_GNU_STACK
725 segment.
726 .Pp
727 .It Cm bti-report Ns = Ns Ar [none|warning|error]
728 Specify how to report the missing GNU_PROPERTY_AARCH64_FEATURE_1_BTI property.
729 .Cm none
730 is the default, linker will not report the missing property otherwise will be reported as a warning or an error.
731 .Pp
732 .It Cm cet-report Ns = Ns Ar [none|warning|error]
733 Specify how to report the missing GNU_PROPERTY_X86_FEATURE_1_IBT or GNU_PROPERTY_X86_FEATURE_1_SHSTK properties.
734 .Cm none
735 is the default, linker will not report the missing property otherwise will be reported as a warning or an error.
736 .Pp
737 .It Cm force-bti
738 Force enable AArch64 BTI instruction in PLT, warn if Input ELF file does not have GNU_PROPERTY_AARCH64_FEATURE_1_BTI property.
739 .Pp
740 .It Cm force-ibt
741 Force enable Intel Indirect Branch Tracking in PLT, warn if an input ELF file
742 does not have GNU_PROPERTY_X86_FEATURE_1_IBT property.
743 .Pp
744 .It Cm global
745 Sets the
746 .Dv DF_1_GLOBAL flag in the
747 .Dv DYNAMIC
748 section.
749 Different loaders can decide how to handle this flag on their own.
750 .Pp
751 .It Cm ifunc-noplt
752 Do not emit PLT entries for ifunc symbols.
753 Instead, emit text relocations referencing the resolver.
754 This is an experimental optimization and only suitable for standalone
755 environments where text relocations do not have the usual drawbacks.
756 This option must be combined with the
757 .Fl z Li notext
758 option.
759 .Pp
760 .It Cm initfirst
761 Sets the
762 .Dv DF_1_INITFIRST
763 flag to indicate the module should be initialized first.
764 .Pp
765 .It Cm interpose
766 Set the
767 .Dv DF_1_INTERPOSE
768 flag to indicate to the runtime linker that the object is an interposer.
769 During symbol resolution interposers are searched after the application
770 but before other dependencies.
771 .Pp
772 .It Cm muldefs
773 Do not error if a symbol is defined multiple times.
774 The first definition will be used.
775 This is a synonym for
776 .Fl -allow-multiple-definition.
777 .Pp
778 .It Cm nocombreloc
779 Disable combining and sorting multiple relocation sections.
780 .Pp
781 .It Cm nocopyreloc
782 Disable the creation of copy relocations.
783 .Pp
784 .It Cm nodefaultlib
785 Set the
786 .Dv DF_1_NODEFLIB
787 flag to indicate that default library search paths should be ignored.
788 .Pp
789 .It Cm nodelete
790 Set the
791 .Dv DF_1_NODELETE
792 flag to indicate that the object cannot be unloaded from a process.
793 .Pp
794 .It Cm nodlopen
795 Set the
796 .Dv DF_1_NOOPEN
797 flag to indicate that the object may not be opened by
798 .Xr dlopen 3 .
799 .Pp
800 .It Cm nognustack
801 Do not emit the
802 .Dv PT_GNU_STACK
803 segment.
804 .Pp
805 .It Cm norelro
806 Do not indicate that portions of the object should be mapped read-only
807 after initial relocation processing.
808 The object will omit the
809 .Dv PT_GNU_RELRO
810 segment.
811 .Pp
812 .It Cm notext
813 Allow relocations against read-only segments.
814 Sets the
815 .Dv DT_TEXTREL flag in the
816 .Dv DYNAMIC
817 section.
818 .Pp
819 .It Cm now
820 Set the
821 .Dv DF_BIND_NOW
822 flag to indicate that the run-time loader should perform all relocation
823 processing as part of object initialization.
824 By default relocations may be performed on demand.
825 .Pp
826 .It Cm origin
827 Set the
828 .Dv DF_ORIGIN
829 flag to indicate that the object requires
830 $ORIGIN
831 processing.
832 .Pp
833 .It Cm pac-plt
834 AArch64 only, use pointer authentication in PLT.
835 .Pp
836 .It Cm pack-relative-relocs
837 Similar to
838 .Cm -pack-dyn-relocs=relr
839 , but synthesizes the GLIBC_ABI_DT_RELR version dependency if there is a GLIBC_2.* version dependency.
840 glibc ld.so rejects loading a dynamically linked object without the GLIBC_ABI_DT_RELR version dependency.
841 .Pp
842 .It Cm rel
843 Use REL format for dynamic relocations.
844 .Pp
845 .It Cm rela
846 Use RELA format for dynamic relocations.
847 .Pp
848 .It Cm retpolineplt
849 Emit retpoline format PLT entries as a mitigation for CVE-2017-5715.
850 .Pp
851 .It Cm rodynamic
852 Make the
853 .Li .dynamic
854 section read-only.
855 The
856 .Dv DT_DEBUG
857 tag will not be emitted.
858 .Pp
859 .It Cm separate-loadable-segments
860 .It Cm separate-code
861 .It Cm noseparate-code
862 Specify whether two adjacent PT_LOAD segments are allowed to overlap in pages.
863 .Cm noseparate-code
864 (default) allows overlap.
865 .Cm separate-code
866 allows overlap between two executable segments, or two non-executable segments.
867 .Cm separate-loadable-segments
868 disallows overlap.
869 .Pp
870 .It Cm shstk
871 x86 only, use shadow stack.
872 .Pp
873 .It Cm stack-size Ns = Ns Ar size
874 Set the main thread's stack size to
875 .Ar size .
876 The stack size is recorded as the size of the
877 .Ar size .
878 .Dv PT_GNU_STACK
879 program segment.
880 .Pp
881 .It Cm start-stop-gc
882 Don't let __start_/__stop_ references retain the associated C identifier name sections (default).
883 .Pp
884 .It Cm nostart-stop-gc
885 Let __start_/__stop_ references retain the associated C identifier name sections.
886 .Pp
887 .It Cm text
888 Do not allow relocations against read-only segments.
889 This is the default.
890 .Pp
891 .It Cm wxneeded
892 Create a
893 .Dv PT_OPENBSD_WXNEEDED
894 segment.
895 .El
896 .El
898 .Sh ENVIRONMENT VARIABLES
899 .Bl -tag -width LC_CTYPE
900 .It Ev LLD_REPRODUCE
901 Create a reproduce tarball with the specified filename. If
902 .Fl -reproduce
903 is specified,
904 .Fl -reproduce
905 takes precedence.
906 .It Ev LLD_VERSION
907 ld.lld creates a section named
908 .Cm .comment
909 containing the LLD version string. The version string can be overridden by this environment variable,
910 which is useful to eliminate differences in the binary caused by LLD version number differences.
911 .El
913 .Sh IMPLEMENTATION NOTES
914 .Nm Ap s
915 handing of archive files (those with a
916 .Pa .a
917 file extension) is different from traditional linkers used on Unix-like
918 systems.
919 .Pp
920 Traditional linkers maintain a set of undefined symbols during linking.
921 The linker processes each file in the order in which it appears on the
922 command line, until the set of undefined symbols becomes empty.
923 An object file is linked into the output object when it is encountered,
924 with its undefined symbols added to the set.
925 Upon encountering an archive file a traditional linker searches the objects
926 contained therein, and processes those that satisfy symbols in the unresolved
927 set.
928 .Pp
929 Handling mutually dependent archives may be awkward when using a traditional
930 linker.
931 Archive files may have to be specified multiple times, or the special command
932 line options
933 .Fl -start-group
934 and
935 .Fl -end-group
936 may be used to have the linker loop over the files in the group until no new
937 symbols are added to the set.
938 .Pp
939 .Nm
940 records all symbols found in objects and archives as it iterates over
941 command line arguments.
942 When
943 .Nm
944 encounters an undefined symbol that can be resolved by an object file
945 contained in a previously processed archive file, it immediately extracts
946 and links it into the output object.
947 .Pp
948 With certain archive inputs
949 .Nm
950 may produce different results compared to traditional linkers.
951 In practice, large bodies of third party software have been linked with
952 .Nm
953 without material issues.
954 .Pp
955 The
956 .Fl -warn-backrefs
957 option may be used to identify a linker invocation that may be incompatible
958 with traditional Unix-like linker behavior.