usr.bin/clang/lld/ld.lld.1

   1 .\"-
   2 .\" Copyright (c) 2018 Kirill Ponomarev
   3 .\" Copyright (c) 2018 The FreeBSD Foundation
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .Dd September 14, 2018
  29 .Dt LD.LLD 1
  30 .Os
  31 .Sh NAME
  32 .Nm ld.lld
  33 .Nd ELF linker from the LLVM project
  34 .Sh SYNOPSIS
  35 .Nm ld.lld
  36 .Op Ar options
  37 .Ar objfile ...
  38 .Sh DESCRIPTION
  39 A linker takes one or more object, archive, and library files, and combines
  40 them into an output file (an executable, a shared library, or another object
  41 file).
  42 It relocates code and data from the input files and resolves symbol
  43 references between them.
  44 .Pp
  45 .Nm
  46 is a drop-in replacement for the GNU BFD and gold linkers.
  47 It accepts most of the same command line arguments and linker scripts
  48 as GNU linkers.
  49 .Pp
  50 Many options have both a single-letter and long form.
  51 When using the long form options other than those beginning with the
  52 letter
  53 .Cm o
  54 may be specified using either one or two dashes preceeding the option name.
  55 Long options beginning with
  56 .Cm o
  57 require two dashes to avoid confusion with the
  58 .Fl o Ar path
  59 option.
  60 .Pp
  61 These options are available:
  62 .Bl -tag -width indent
  63 .It Fl -allow-multiple-definition
  64 Do not error if a symbol is defined multiple times.
  65 The first definition will be used.
  66 .It Fl -as-needed
  67 Only set
  68 .Dv DT_NEEDED
  69 for shared libraries if used.
  70 .It Fl -auxiliary Ar value
  71 Set the
  72 .Dv DT_AUXILIARY
  73 field to the specified name.
  74 .It Fl -Bdynamic
  75 Link against shared libraries.
  76 .It Fl -Bstatic
  77 Do not link against shared libraries.
  78 .It Fl -Bsymbolic-functions
  79 Bind defined function symbols locally.
  80 .It Fl -Bsymbolic
  81 Bind defined symbols locally.
  82 .It Fl -build-id= Ns Ar value
  83 Generate a build ID note.
  84 .Ar value
  85 may be one of
  86 .Cm md5 ,
  87 .Cm sha1 ,
  88 .Cm tree ,
  89 .Cm uuid ,
  90 .Cm 0x Ns Ar hex-string ,
  91 and
  92 .Cm none .
  93 .Cm tree
  94 is an alias for
  95 .Cm sha1 .
  96 Build-IDs of type
  97 .Cm md5 ,
  98 .Cm sha1 ,
  99 and
 100 .Cm tree
 101 are calculated from the object contents.
 102 .It Fl -build-id
 103 Generate a build ID note.
 104 .It Fl -color-diagnostics= 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 Cm auto .
 117 .It Fl -compress-debug-sections= 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 -define-common
 125 Assign space to common symbols.
 126 .It Fl -defsym= Ns Ar symbol= Ns Ar expression
 127 Define a symbol alias.
 128 .Ar expression
 129 may be another symbol or a linker script expression.
 130 For example,
 131 .Fl -defsym= Ns Cm foo= Ns Cm bar
 132 or
 133 .Fl -defsym= Ns Cm foo= Ns Cm bar+0x100 .
 134 .It Fl -demangle
 135 Demangle symbol names.
 136 .It Fl -disable-new-dtags
 137 Disable new dynamic tags.
 138 .It Fl -discard-all
 139 Delete all local symbols.
 140 .It Fl -discard-locals
 141 Delete temporary local symbols.
 142 .It Fl -discard-none
 143 Keep all symbols in the symbol table.
 144 .It Fl -dynamic-linker Ar value
 145 Specify the dynamic linker to be used for a dynamically linked executable.
 146 This is recorded in an ELF segment of type
 147 .Dv PT_INTERP .
 148 .It Fl -dynamic-list Ar file
 149 Read a list of dynamic symbols from
 150 .Ar file .
 151 .It Fl -eh-frame-hdr
 152 Request creation of
 153 .Li .eh_frame_hdr
 154 section and
 155 .Dv PT_GNU_EH_FRAME
 156 segment header.
 157 .It Fl -emit-relocs
 158 Generate relocations in the output.
 159 .It Fl -enable-new-dtags
 160 Enable new dynamic tags.
 161 .It Fl -end-lib
 162 End a grouping of objects that should be treated as if they were together
 163 in an archive.
 164 .It Fl -entry Ar entry
 165 Name of entry point symbol.
 166 .It Fl -error-limit Ar value
 167 Maximum number of errors to emit before stopping.
 168 A value of zero indicates that there is no limit.
 169 .It Fl -error-unresolved-symbols
 170 Report unresolved symbols as errors.
 171 .It Fl -exclude-libs Ar value
 172 Exclude static libraries from automatic export.
 173 .It Fl -export-dynamic-symbol Ar symbol
 174 Include
 175 .Ar symbol
 176 in the dynamic symbol table.
 177 .It Fl -export-dynamic
 178 Put symbols in the dynamic symbol table.
 179 .It Fl -fatal-warnings
 180 Treat warnings as errors.
 181 .It Fl -filter= Ns Ar value
 182 Set the
 183 .Dv DT_FILTER
 184 field to the specified value.
 185 .It Fl -fini Ar symbol
 186 Specify a finalizer function.
 187 .It Fl -format= Ns Ar input-format
 188 Specify the format of the inputs following this option.
 189 .Ar input-format
 190 may be one of
 191 .Cm binary ,
 192 .Cm elf ,
 193 and
 194 .Cm default .
 195 .Cm default
 196 is a synonym for
 197 .Cm elf .
 198 .It Fl -gc-sections
 199 Enable garbage collection of unused sections.
 200 .It Fl -gdb-index
 201 Generate
 202 .Li .gdb_index
 203 section.
 204 .It Fl -hash-style Ar value
 205 Specify hash style.
 206 .Ar value
 207 may be
 208 .Cm sysv ,
 209 .Cm gnu ,
 210 or
 211 .Cm both .
 212 .Cm both
 213 is the default.
 214 .It Fl -help
 215 Print a usage message.
 216 .It Fl -icf=all
 217 Enable identical code folding.
 218 .It Fl -icf=none
 219 Disable identical code folding.
 220 .It Fl -image-base= Ns Ar value
 221 Set the base address to
 222 .Ar value .
 223 .It Fl -init Ar symbol
 224 Specify an initializer function.
 225 .It Fl -lto-aa-pipeline= Ns Ar value
 226 AA pipeline to run during LTO.
 227 Used in conjunction with
 228 .Fl -lto-newpm-passes .
 229 .It Fl -lto-newpm-passes= Ns Ar value
 230 Passes to run during LTO.
 231 .It Fl -lto-O Ar opt-level
 232 Optimization level for LTO.
 233 .It Fl -lto-partitions= Ns Ar value
 234 Number of LTO codegen partitions.
 235 .It Fl L Ar dir
 236 Add a directory to the library search path.
 237 .It Fl l Ar libName
 238 Root name of library to use.
 239 .It Fl -Map Ar file
 240 Print a link map to
 241 .Ar file .
 242 .It Fl m Ar value
 243 Set target emulation.
 244 .It Fl -no-as-needed
 245 Always set
 246 .Dv DT_NEEDED
 247 for shared libraries.
 248 .It Fl -no-color-diagnostics
 249 Do not use colors in diagnostics.
 250 .It Fl -no-define-common
 251 Do not assign space to common symbols.
 252 .It Fl -no-demangle
 253 Do not demangle symbol names.
 254 .It Fl -no-dynamic-linker
 255 Inhibit output of an
 256 .Li .interp
 257 section.
 258 .It Fl -no-gc-sections
 259 Disable garbage collection of unused sections.
 260 .It Fl -no-gnu-unique
 261 Disable STB_GNU_UNIQUE symbol binding.
 262 .It Fl -no-rosegment
 263 Do not put read-only non-executable sections in their own segment.
 264 .It Fl -no-threads
 265 Do not run the linker multi-threaded.
 266 .It Fl -no-undefined-version
 267 Report version scripts that refer undefined symbols.
 268 .It Fl -no-undefined
 269 Report unresolved symbols even if the linker is creating a shared library.
 270 .It Fl -no-whole-archive
 271 Restores the default behavior of loading archive members.
 272 .It Fl -noinhibit-exec
 273 Retain the executable output file whenever it is still usable.
 274 .It Fl -no-pie
 275 Do not create a position independent executable.
 276 .It Fl -nostdlib
 277 Only search directories specified on the command line.
 278 .It Fl -oformat Ar format
 279 Specify the format for the output object file.
 280 The only supported
 281 .Ar format
 282 is
 283 .Cm binary ,
 284 which produces output with no ELF header.
 285 .It Fl -omagic
 286 Set the text and data sections to be readable and writable.
 287 .It Fl -opt-remarks-filename Ar file
 288 Write optimization remarks in YAML format to
 289 .Ar file .
 290 .It Fl -opt-remarks-with-hotness
 291 Include hotness information in the optimization remarks file.
 292 .It Fl O Ar value
 293 Optimize output file size.
 294 .Ar value
 295 may be:
 296 .Bl -tag -width indent
 297 .It Cm O0
 298 Disable string merging.
 299 .It Cm O1
 300 Enable string merging.
 301 .It Cm O2
 302 Enable string tail merging.
 303 .El
 304 .Cm O1
 305 is the default.
 306 .It Fl o Ar path
 307 Write the output executable, library, or object to
 308 .Ar path .
 309 If not specified,
 310 .Dv a.out
 311 is used as a default.
 312 .It Fl -pie
 313 Create a position independent executable.
 314 .It Fl -print-gc-sections
 315 List removed unused sections.
 316 .It Fl -print-map
 317 Print a link map to the standard output.
 318 .It Fl -relocatable
 319 Create relocatable object file.
 320 .It Fl -reproduce Ar value
 321 Dump linker invocation and input files for debugging.
 322 .It Fl -retain-symbols-file= Ns Ar file
 323 Retain only the symbols listed in the file.
 324 .It Fl -rpath Ar value
 325 Add a
 326 .Dv DT_RUNPATH
 327 to the output.
 328 .It Fl -rsp-quoting= Ns Ar value
 329 Quoting style for response files.
 330 The supported values are
 331 .Ar windows
 332 and
 333 .Ar posix .
 334 .It Fl -script Ar file
 335 Read linker script from
 336 .Ar file .
 337 .It Fl -section-start Ar address
 338 Set address of section.
 339 .It Fl -shared
 340 Build a shared object.
 341 .It Fl -soname= Ns Ar value
 342 Set
 343 .Dv DT_SONAME
 344 to
 345 .Ar value .
 346 .It Fl -sort-section Ar value
 347 Specifies sections sorting rule when linkerscript is used.
 348 .It Fl -start-lib
 349 Start a grouping of objects that should be treated as if they were together
 350 in an archive.
 351 .It Fl -strip-all
 352 Strip all symbols.
 353 .It Fl -strip-debug
 354 Strip debugging information.
 355 .It Fl -symbol-ordering-file Ar file
 356 Lay out sections in the order specified by
 357 .Ar file .
 358 .It Fl -sysroot= Ns Ar value
 359 Set the system root.
 360 .It Fl -target1-abs
 361 Interpret
 362 .Dv R_ARM_TARGET1
 363 as
 364 .Dv R_ARM_ABS32 .
 365 .It Fl -target1-rel
 366 Interpret
 367 .Dv R_ARM_TARGET1
 368 as
 369 .Dv R_ARM_REL32 .
 370 .It Fl -target2=type
 371 Interpret
 372 .Dv R_ARM_TARGET2
 373 as
 374 .Ar type ,
 375 where
 376 .Ar type
 377 is one of
 378 .Li rel ,
 379 .Li abs ,
 380 or
 381 .Li got-rel .
 382 .It Fl -Tbss Ar value
 383 Same as
 384 .Fl -section-start
 385 with
 386 .Li .bss
 387 as the sectionname.
 388 .It Fl -Tdata Ar value
 389 Same as
 390 .Fl -section-start
 391 with
 392 .Li .data
 393 as the sectionname.
 394 .It Fl -thinlto-cache-dir= Ns Ar value
 395 Path to ThinLTO cached object file directory.
 396 .It Fl -thinlto-cache-policy Ar value
 397 Pruning policy for the ThinLTO cache.
 398 .It Fl -thinlto-jobs= Ns Ar value
 399 Number of ThinLTO jobs.
 400 .It Fl -threads
 401 Run the linker multi-threaded.
 402 This option is enabled by default.
 403 .It Fl -trace-symbol Ar symbol
 404 Trace references to
 405 .Ar symbol .
 406 .It Fl -trace
 407 Print the names of the input files.
 408 .It Fl -Ttext Ar value
 409 Same as
 410 .Fl -section-start
 411 with
 412 .Li .text
 413 as the sectionname.
 414 .It Fl -undefined Ar symbol
 415 Force
 416 .Ar symbol
 417 to be an undefined symbol during linking.
 418 .It Fl -unresolved-symbols= Ns Ar value
 419 Determine how to handle unresolved symbols.
 420 .It Fl -verbose
 421 Verbose mode.
 422 .It Fl -version-script Ar file
 423 Read version script from
 424 .Ar file .
 425 .It Fl V , Fl -version
 426 Display the version number and exit.
 427 .It Fl v
 428 Display the version number and proceed with linking if object files are
 429 specified.
 430 .It Fl -warn-common
 431 Warn about duplicate common symbols.
 432 .It Fl -warn-unresolved-symbols
 433 Report unresolved symbols as warnings.
 434 .It Fl -whole-archive
 435 Force load of all members in a static library.
 436 .It Fl -wrap Ar symbol
 437 Use wrapper functions for symbol.
 438 .It Fl z Ar option
 439 Linker option extensions.
 440 .Bl -tag -width indent
 441 .It Cm execstack
 442 Make the main stack executable.
 443 Stack permissions are recorded in the
 444 .Dv PT_GNU_STACK
 445 segment.
 446 .It Cm ifunc-noplt
 447 Do not emit PLT entries for GNU ifuncs.
 448 Instead, preserve relocations for ifunc call sites so that they may
 449 be applied by a run-time loader.
 450 Note that this feature requires special loader support and will
 451 generally result in application crashes when used outside of freestanding
 452 environments.
 453 .It Cm interpose
 454 Set the
 455 .Dv DF_1_INTERPOSE
 456 flag to indicate that the object is an interposer.
 457 Runtime linkers perform symbol resolution by first searching the application,
 458 followed by interposers, and then any other dependencies.
 459 .It Cm muldefs
 460 Do not error if a symbol is defined multiple times.
 461 The first definition will be used.
 462 This is a synonym for
 463 .Fl -allow-multiple-definition.
 464 .It Cm nocombreloc
 465 Disable combining and sorting multiple relocation sections.
 466 .It Cm nocopyreloc
 467 Disable the creation of copy relocations.
 468 .It Cm nodelete
 469 Set the
 470 .Dv DF_1_NODELETE
 471 flag to indicate that the object cannot be unloaded from a process.
 472 .It Cm nodlopen
 473 Set the
 474 .Dv DF_1_NOOPEN
 475 flag to indcate that the object may not be opened by
 476 .Xr dlopen 3 .
 477 .It Cm norelro
 478 Do not indicate that portions of the object shold be mapped read-only
 479 after initial relocation processing.
 480 The object will omit the
 481 .Dv PT_GNU_RELRO
 482 segment.
 483 .It Cm notext
 484 Allow relocations against read-only segments.
 485 Sets the
 486 .Dv DT_TEXTREL flag in the
 487 .Dv DYNAMIC
 488 section.
 489 .It Cm now
 490 Set the
 491 .Dv DF_BIND_NOW
 492 flag to indicate that the run-time loader should perform all relocation
 493 processing as part of object initialization.
 494 By default relocations may be performed on demand.
 495 .It Cm origin
 496 Set the
 497 .Dv DF_ORIGIN
 498 flag to indicate that the object requires
 499 $ORIGIN
 500 processing.
 501 .It Cm retpolineplt
 502 Emit retpoline format PLT entries as a mitigation for CVE-2017-5715.
 503 .It Cm rodynamic
 504 Make the
 505 .Li .dynamic
 506 section read-only.
 507 The
 508 .Dv DT_DEBUG
 509 tag will not be emitted.
 510 .It Cm stack-size= Ns Ar size
 511 Set the main thread's stack size to
 512 .Ar size .
 513 The stack size is recorded as the size of the
 514 .Ar size .
 515 .Dv PT_GNU_STACK
 516 program segment.
 517 .It Cm text
 518 Do not allow relocations against read-only segments.
 519 This is the default.
 520 .It Cm wxneeded
 521 Create a
 522 .Dv PT_OPENBSD_WXNEEDED
 523 segment.
 524 .El
 525 .El