contrib/llvm/tools/lld/docs/ld.lld.1

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