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