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