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