1 .\" This file is distributed under the University of Illinois Open Source
2 .\" License. See LICENSE.TXT for details.
4 .\" This man page documents only lld's ELF linking support, obtained originally
11 .Nd ELF linker from the LLVM project
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
20 It relocates code and data from the input files and resolves symbol
21 references between them.
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
28 Many options have both a single-letter and long form.
29 When using the long form options other than those beginning with the
32 may be specified using either one or two dashes preceding the option name.
33 Long options beginning with
35 require two dashes to avoid confusion with the
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.
49 for shared libraries if used.
50 .It Fl -auxiliary Ns = Ns Ar value
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.
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.
71 .Cm 0x Ns Ar hex-string ,
83 are calculated from the object contents.
85 is not intended to be cryptographically secure.
88 .Fl -build-id Ns = Ns Cm fast .
89 .It Fl -color-diagnostics Ns = Ns Ar value
90 Use colors in diagnostics.
98 enables color if and only if output is to a terminal.
99 .It Fl -color-diagnostics
101 .Fl -color-diagnostics Ns = Ns Cm auto .
102 .It Fl -compress-debug-sections Ns = Ns Ar value
103 Compress DWARF debug sections.
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.
116 may be another symbol or a linker script expression.
120 .Ql --defsym=foo=bar+0x100 .
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.
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
135 .It Fl -dynamic-list Ns = Ns Ar file
136 Read a list of dynamic symbols from
144 .It Fl -emit-relocs , Fl q
145 Generate relocations in the output.
146 .It Fl -enable-new-dtags
147 Enable new dynamic tags.
149 End a grouping of objects that should be treated as if they were together
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
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
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.
186 Enable garbage collection of unused sections.
191 .It Fl -hash-style Ns = Ns Ar value
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
212 .It Fl -init Ns = Ns Ar symbol
213 Specify an initializer function.
214 .It Fl -keep-unique Ns = Ns Ar symbol
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.
233 Set target emulation.
234 .It Fl -Map Ns = Ns Ar file , Fl M Ar file
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.
246 Do not demangle symbol names.
247 .It Fl -no-dynamic-linker
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.
256 Do not put read-only non-executable sections in their own segment.
258 Do not run the linker multi-threaded.
259 .It Fl -no-undefined-version
260 Report version scripts that refer undefined symbols.
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.
266 Do not create a position independent executable.
267 .It Fl -noinhibit-exec
268 Retain the executable output file whenever it is still usable.
270 Only search directories specified on the command line.
272 Write the output executable, library, or object to
276 is used as a default.
278 Optimize output file size.
282 .Bl -tag -width 2n -compact
284 Disable string merging.
286 Enable string merging.
288 Enable string tail merging.
293 .It Fl -oformat Ns = Ns Ar format
294 Specify the format for the output object file.
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
305 .It Fl -opt-remarks-with-hotness
306 Include hotness information in the optimization remarks file.
308 Create a position independent executable.
309 .It Fl -print-gc-sections
310 List removed unused sections.
312 Print a link map to the standard output.
314 Save the current state of
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
332 .It Fl -rsp-quoting Ns = Ns Ar value
333 Quoting style for response files.
334 The supported values are
338 .It Fl -script Ns = Ns Ar file , Fl T Ar file
339 Read linker script from
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
350 .It Fl -sort-section Ns = Ns Ar value
351 Specifies sections sorting rule when linkerscript is used.
353 Start a grouping of objects that should be treated as if they were together
355 .It Fl -strip-all , Fl s
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
362 .It Fl -sysroot Ns = Ns Ar value
374 .It Fl -target2 Ns = Ns Ar type
386 .It Fl -Tbss Ns = Ns Ar value
392 .It Fl -Tdata Ns = Ns Ar value
398 .It Fl -Ttext Ns = Ns Ar value
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.
411 Run the linker multi-threaded.
412 This option is enabled by default.
414 Print the names of the input files.
415 .It Fl -trace-symbol Ns = Ns Ar symbol , Fl y Ar symbol
418 .It Fl -undefined Ns = Ns Ar symbol , Fl u 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.
425 Display the version number and proceed with linking if object files are
427 .It Fl V , Fl -version
428 Display the version number and exit.
431 .It Fl -version-script Ns = Ns Ar file
432 Read version script from
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.
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.
447 Linker option extensions.
448 .Bl -tag -width indent
450 Make the main stack executable.
451 Stack permissions are recorded in the
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
464 flag to indicate the module should be initialized first.
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.
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.
477 Disable combining and sorting multiple relocation sections.
479 Disable the creation of copy relocations.
483 flag to indicate that the object cannot be unloaded from a process.
487 flag to indcate that the object may not be opened by
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
496 Allow relocations against read-only segments.
498 .Dv DT_TEXTREL flag in the
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.
510 flag to indicate that the object requires
514 Emit retpoline format PLT entries as a mitigation for CVE-2017-5715.
521 tag will not be emitted.
522 .It Cm stack-size Ns = Ns Ar size
523 Set the main thread's stack size to
525 The stack size is recorded as the size of the
530 Do not allow relocations against read-only segments.
534 .Dv PT_OPENBSD_WXNEEDED
538 .Sh IMPLEMENTATION NOTES
540 handing of archive files (those with a
542 file extension) is different from traditional linkers used on Unix-like
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
554 Handling mutually dependent archives may be awkward when using a traditional
556 Archive files may have to be specified multiple times, or the special command
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.
565 records all symbols found in objects and archives as it iterates over
566 command line arguments.
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.
573 With certain archive inputs
575 may produce different results compared to traditional linkers.
576 In practice, large bodies of third party software have been linked with
578 without material issues.
582 option may be used to identify a linker invocation that may be incompatible
583 with traditional Unix-like linker behavior.