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