Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
LD.LLD(1)		  BSD General Commands Manual		     LD.LLD(1)

NAME
     ld.lld -- ELF linker from the LLVM	project

SYNOPSIS
     ld.lld [options] objfile ...

DESCRIPTION
     A linker takes one	or more	object,	archive, and library files, and	com-
     bines them	into an	output file (an	executable, a shared library, or an-
     other object file).  It relocates code and	data from the input files and
     resolves symbol references	between	them.

     ld.lld is a drop-in replacement for the GNU BFD and gold linkers.	It ac-
     cepts most	of the same command line arguments and linker scripts as GNU
     linkers.

     ld.lld currently supports i386, x86-64, ARM, AArch64, PowerPC32, Pow-
     erPC64, MIPS32, MIPS64, RISC-V, AMDGPU, Hexagon and SPARC V9 targets.
     ld.lld acts as a Microsoft	link.exe-compatible linker if invoked as
     lld-link and as macOS's ld	if invoked as ld.ld64. All these targets are
     always supported however ld.lld was built,	so you can always use ld.lld
     as	a native linker	as well	as a cross linker.

OPTIONS
     Many options have both a single-letter and	long form.  When using the
     long form options other than those	beginning with the letter o may	be
     specified using either one	or two dashes preceding	the option name.  Long
     options beginning with o require two dashes to avoid confusion with the
     -o	path option.

     --allow-multiple-definition
	     Do	not error if a symbol is defined multiple times.  The first
	     definition	will be	used.

     --allow-shlib-undefined
	     Allow unresolved references in shared libraries.  This option is
	     enabled by	default	when linking a shared library.

     --apply-dynamic-relocs
	     Apply link-time values for	dynamic	relocations.

     --as-needed
	     Only set DT_NEEDED	for shared libraries if	used.

     --auxiliary=value
	     Set the DT_AUXILIARY field	to the specified name.

     --Bdynamic, --dy
	     Link against shared libraries.

     --Bstatic,	--static, --dn
	     Do	not link against shared	libraries.

     --Bsymbolic
	     Bind defined symbols locally.

     --Bsymbolic-functions
	     Bind defined function symbols locally.

     --build-id=value
	     Generate a	build ID note.	value may be one of fast, md5, sha1,
	     tree, uuid, 0xhex-string, and none.  tree is an alias for sha1.
	     Build-IDs of type fast, md5, sha1,	and tree are calculated	from
	     the object	contents.  fast	is not intended	to be cryptographi-
	     cally secure.

     --build-id
	     Synonym for --build-id=fast.

     --color-diagnostics=value
	     Use colors	in diagnostics.	 value may be one of always, auto, and
	     never.  auto enables color	if and only if output is to a termi-
	     nal.

     --color-diagnostics
	     Alias for --color-diagnostics=auto.

     --compress-debug-sections=value
	     Compress DWARF debug sections.  value may be none or zlib.

     --cref  Output cross reference table.

     --define-common, -d
	     Assign space to common symbols.

     --defsym=symbol=expression
	     Define a symbol alias.  expression	may be another symbol or a
	     linker script expression.	For example, `--defsym=foo=bar'	or
	     `--defsym=foo=bar+0x100'.

     --demangle
	     Demangle symbol names.

     --disable-new-dtags
	     Disable new dynamic tags.

     --discard-all, -x
	     Delete all	local symbols.

     --discard-locals, -X
	     Delete temporary local symbols.

     --discard-none
	     Keep all symbols in the symbol table.

     --dynamic-linker=value
	     Specify the dynamic linker	to be used for a dynamically linked
	     executable.  This is recorded in an ELF segment of	type
	     PT_INTERP.

     --dynamic-list=file
	     Read a list of dynamic symbols from file.

     --eh-frame-hdr
	     Request creation of .eh_frame_hdr section and PT_GNU_EH_FRAME
	     segment header.

     --emit-relocs, -q
	     Generate relocations in the output.

     --enable-new-dtags
	     Enable new	dynamic	tags.

     --end-lib
	     End a grouping of objects that should be treated as if they were
	     together in an archive.

     --entry=entry
	     Name of entry point symbol.

     --error-limit=value
	     Maximum number of errors to emit before stopping.	A value	of
	     zero indicates that there is no limit.

     --error-unresolved-symbols
	     Report unresolved symbols as errors.

     --execute-only
	     Mark executable sections unreadable. This option is currently
	     only supported on AArch64.

     --exclude-libs=value
	     Exclude static libraries from automatic export.

     --export-dynamic, -E
	     Put symbols in the	dynamic	symbol table.

     --export-dynamic-symbol=symbol
	     Include symbol in the dynamic symbol table.

     --fatal-warnings
	     Treat warnings as errors.

     --filter=value, -F	value
	     Set the DT_FILTER field to	the specified value.

     --fini=symbol
	     Specify a finalizer function.

     --format=input-format, -b input-format
	     Specify the format	of the inputs following	this option.
	     input-format may be one of	binary,	elf, and default.  default is
	     a synonym for elf.

     --gc-sections
	     Enable garbage collection of unused sections.

     --gdb-index
	     Generate .gdb_index section.

     --hash-style=value
	     Specify hash style.  value	may be sysv, gnu, or both.  both is
	     the default.

     --help  Print a help message.

     --icf=all
	     Enable identical code folding.

     --icf=safe
	     Enable safe identical code	folding.

     --icf=none
	     Disable identical code folding.

     --image-base=value
	     Set the base address to value.

     --init=symbol
	     Specify an	initializer function.

     --keep-unique=symbol
	     Do	not fold symbol	during ICF.

     -l	libName, --library=libName
	     Root name of library to use.

     -L	dir, --library-path=dir
	     Add a directory to	the library search path.

     --lto-aa-pipeline=value
	     AA	pipeline to run	during LTO.  Used in conjunction with
	     --lto-newpm-passes.

     --lto-newpm-passes=value
	     Passes to run during LTO.

     --lto-Oopt-level
	     Optimization level	for LTO.

     --lto-partitions=value
	     Number of LTO codegen partitions.

     -m	value
	     Set target	emulation.

     --Map=file, -M file
	     Print a link map to file.

     --no-allow-shlib-undefined
	     Do	not allow unresolved references	in shared libraries.  This op-
	     tion is enabled by	default	when linking an	executable.

     --no-as-needed
	     Always set	DT_NEEDED for shared libraries.

     --no-color-diagnostics
	     Do	not use	colors in diagnostics.

     --no-define-common
	     Do	not assign space to common symbols.

     --no-demangle
	     Do	not demangle symbol names.

     --no-dynamic-linker
	     Inhibit output of an .interp section.

     --no-gc-sections
	     Disable garbage collection	of unused sections.

     --no-gnu-unique
	     Disable STB_GNU_UNIQUE symbol binding.

     --no-rosegment
	     Do	not put	read-only non-executable sections in their own seg-
	     ment.

     --no-threads
	     Do	not run	the linker multi-threaded.

     --no-undefined-version
	     Report version scripts that refer undefined symbols.

     --no-undefined
	     Report unresolved symbols even if the linker is creating a	shared
	     library.

     --no-whole-archive
	     Restores the default behavior of loading archive members.

     --no-pie
	     Do	not create a position independent executable.

     --noinhibit-exec
	     Retain the	executable output file whenever	it is still usable.

     --nostdlib
	     Only search directories specified on the command line.

     -o	path
	     Write the output executable, library, or object to	path.  If not
	     specified,	a.out is used as a default.

     -Ovalue
	     Optimize output file size.	 value may be:

	     0	 Disable string	merging.
	     1	 Enable	string merging.
	     2	 Enable	string tail merging.

	     -O1 is the	default.

     --oformat=format
	     Specify the format	for the	output object file.  The only sup-
	     ported format is binary, which produces output with no ELF
	     header.

     --omagic, -N
	     Set the text and data sections to be readable and writable.

     --opt-remarks-filename file
	     Write optimization	remarks	in YAML	format to file.

     --opt-remarks-with-hotness
	     Include hotness information in the	optimization remarks file.

     --pic-veneer
	     Always generate position independent thunks.

     --pie   Create a position independent executable.

     --print-gc-sections
	     List removed unused sections.

     --print-icf-sections
	     List identical folded sections.

     --print-map
	     Print a link map to the standard output.

     --push-state
	     Save the current state of --as-needed, --static, and
	     --whole-archive.

     --pop-state
	     Undo the effect of	--push-state.

     --relocatable, -r
	     Create relocatable	object file.

     --reproduce=value
	     Dump linker invocation and	input files for	debugging.

     --retain-symbols-file=file
	     Retain only the symbols listed in the file.

     --rpath=value, -R value
	     Add a DT_RUNPATH to the output.

     --rsp-quoting=value
	     Quoting style for response	files.	The supported values are
	     windows and posix.

     --script=file, -T file
	     Read linker script	from file.

     --section-start=section=address
	     Set address of section.

     --shared, --Bsharable
	     Build a shared object.

     --soname=value, -h	value
	     Set DT_SONAME to value.

     --sort-section=value
	     Specifies sections	sorting	rule when linkerscript is used.

     --start-lib
	     Start a grouping of objects that should be	treated	as if they
	     were together in an archive.

     --strip-all, -s
	     Strip all symbols.

     --strip-debug, -S
	     Strip debugging information.

     --symbol-ordering-file=file
	     Lay out sections in the order specified by	file.

     --sysroot=value
	     Set the system root.

     --target1-abs
	     Interpret R_ARM_TARGET1 as	R_ARM_ABS32.

     --target1-rel
	     Interpret R_ARM_TARGET1 as	R_ARM_REL32.

     --target2=type
	     Interpret R_ARM_TARGET2 as	type, where type is one	of rel,	abs,
	     or	got-rel.

     --Tbss=value
	     Same as --section-start with .bss as the sectionname.

     --Tdata=value
	     Same as --section-start with .data	as the sectionname.

     --Ttext=value
	     Same as --section-start with .text	as the sectionname.

     --thinlto-cache-dir=value
	     Path to ThinLTO cached object file	directory.

     --thinlto-cache-policy=value
	     Pruning policy for	the ThinLTO cache.

     --thinlto-jobs=value
	     Number of ThinLTO jobs.

     --threads
	     Run the linker multi-threaded.  This option is enabled by de-
	     fault.

     --trace
	     Print the names of	the input files.

     --trace-symbol=symbol, -y symbol
	     Trace references to symbol.

     --undefined=symbol, -u symbol
	     Force symbol to be	an undefined symbol during linking.

     --unresolved-symbols=value
	     Determine how to handle unresolved	symbols.

     -v	     Display the version number	and proceed with linking if object
	     files are specified.

     -V, --version
	     Display the version number	and exit.

     --verbose
	     Verbose mode.

     --version-script=file
	     Read version script from file.

     --warn-backrefs
	     Warn about	reverse	or cyclic dependencies to or between static
	     archives.	This can be used to ensure linker invocation remains
	     compatible	with traditional Unix-like linkers.

     --warn-common
	     Warn about	duplicate common symbols.

     --warn-ifunc-textrel
	     Warn about	using ifunc symbols in conjunction with	text reloca-
	     tions.  Older versions of glibc library (2.28 and earlier)	has a
	     bug that causes the segment that includes ifunc symbols to	be
	     marked as not executable when they	are relocated. As a result,
	     although the program compiles and links successfully, it gives
	     segmentation fault	when the instruction pointer reaches an	ifunc
	     symbol. Use -warn-ifunc-textrel to	let lld	give a warning,	if the
	     code may include ifunc symbols, may do text relocations and be
	     linked with an older glibc	version. Otherwise, there is no	need
	     to	use it,	as the default value does not give a warning. This
	     flag has been introduced in late 2018, has	no counter part	in ld
	     and gold linkers, and may be removed in the future.

     --warn-unresolved-symbols
	     Report unresolved symbols as warnings.

     --whole-archive
	     Force load	of all members in a static library.

     --wrap=symbol
	     Use wrapper functions for symbol.

     -z	option
	     Linker option extensions.

	     execstack
		     Make the main stack executable.  Stack permissions	are
		     recorded in the PT_GNU_STACK segment.

	     global  Sets the DF_1_GLOBAL flag in the DYNAMIC section.	Dif-
		     ferent loaders can	decide how to handle this flag on
		     their own.

	     ifunc-noplt
		     Do	not emit PLT entries for GNU ifuncs.  Instead, pre-
		     serve relocations for ifunc call sites so that they may
		     be	applied	by a run-time loader.  Note that this feature
		     requires special loader support and will generally	result
		     in	application crashes when used outside of freestanding
		     environments.

	     initfirst
		     Sets the DF_1_INITFIRST flag to indicate the module
		     should be initialized first.

	     interpose
		     Set the DF_1_INTERPOSE flag to indicate to	the runtime
		     linker that the object is an interposer.  During symbol
		     resolution	interposers are	searched after the application
		     but before	other dependencies.

	     muldefs
		     Do	not error if a symbol is defined multiple times.  The
		     first definition will be used.  This is a synonym for
		     --allow-multiple-definition.

	     nocombreloc
		     Disable combining and sorting multiple relocation sec-
		     tions.

	     nocopyreloc
		     Disable the creation of copy relocations.

	     nodefaultlib
		     Set the DF_1_NODEFLIB flag	to indicate that default li-
		     brary search paths	should be ignored.

	     nodelete
		     Set the DF_1_NODELETE flag	to indicate that the object
		     cannot be unloaded	from a process.

	     nodlopen
		     Set the DF_1_NOOPEN flag to indicate that the object may
		     not be opened by dlopen(3).

	     norelro
		     Do	not indicate that portions of the object shold be
		     mapped read-only after initial relocation processing.
		     The object	will omit the PT_GNU_RELRO segment.

	     notext  Allow relocations against read-only segments.  Sets the
		     DT_TEXTREL	flag in	the DYNAMIC section.

	     now     Set the DF_BIND_NOW flag to indicate that the run-time
		     loader should perform all relocation processing as	part
		     of	object initialization.	By default relocations may be
		     performed on demand.

	     origin  Set the DF_ORIGIN flag to indicate	that the object	re-
		     quires $ORIGIN processing.

	     retpolineplt
		     Emit retpoline format PLT entries as a mitigation for
		     CVE-2017-5715.

	     rodynamic
		     Make the .dynamic section read-only.  The DT_DEBUG	tag
		     will not be emitted.

	     stack-size=size
		     Set the main thread's stack size to size.	The stack size
		     is	recorded as the	size of	the size.  PT_GNU_STACK	pro-
		     gram segment.

	     text    Do	not allow relocations against read-only	segments.
		     This is the default.

	     wxneeded
		     Create a PT_OPENBSD_WXNEEDED segment.

IMPLEMENTATION NOTES
     ld.lld's handing of archive files (those with a .a	file extension)	is
     different from traditional	linkers	used on	Unix-like systems.

     Traditional linkers maintain a set	of undefined symbols during linking.
     The linker	processes each file in the order in which it appears on	the
     command line, until the set of undefined symbols becomes empty.  An ob-
     ject file is linked into the output object	when it	is encountered,	with
     its undefined symbols added to the	set.  Upon encountering	an archive
     file a traditional	linker searches	the objects contained therein, and
     processes those that satisfy symbols in the unresolved set.

     Handling mutually dependent archives may be awkward when using a tradi-
     tional linker.  Archive files may have to be specified multiple times, or
     the special command line options --start-group and	--end-group may	be
     used to have the linker loop over the files in the	group until no new
     symbols are added to the set.

     ld.lld records all	symbols	found in objects and archives as it iterates
     over command line arguments.  When	ld.lld encounters an undefined symbol
     that can be resolved by an	object file contained in a previously pro-
     cessed archive file, it immediately extracts and links it into the	output
     object.

     With certain archive inputs ld.lld	may produce different results compared
     to	traditional linkers.  In practice, large bodies	of third party soft-
     ware have been linked with	ld.lld without material	issues.

     The --warn-backrefs option	may be used to identify	a linker invocation
     that may be incompatible with traditional Unix-like linker	behavior.

BSD			      September	26, 2018			   BSD

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | IMPLEMENTATION NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ld&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help