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