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