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