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

FreeBSD Manual Pages


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

     ld.lld -- ELF linker from the LLVM	project

     ld.lld [options] objfile ...

     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

     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.

     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.

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

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

	     Apply link-time values for	dynamic	relocations.

	     Only set DT_NEEDED	for shared libraries if	used.

	     Set the DT_AUXILIARY field	to the specified name.

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

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

	     Bind defined symbols locally.

	     Bind defined function symbols locally.

	     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.

	     Synonym for --build-id=fast.

	     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-

	     Alias for --color-diagnostics=auto.

	     Compress DWARF debug sections.  value may be none or zlib.

     --cref  Output cross reference table.

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

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

	     Demangle symbol names.

	     Disable new dynamic tags.

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

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

	     Keep all symbols in the symbol table.

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

	     Read a list of dynamic symbols from file.

	     Request creation of .eh_frame_hdr section and PT_GNU_EH_FRAME
	     segment header.

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

	     Enable new	dynamic	tags.

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

	     Name of entry point symbol.

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

	     Report unresolved symbols as errors.

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

	     Exclude static libraries from automatic export.

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

	     Include symbol in the dynamic symbol table.

	     Treat warnings as errors.

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

	     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.

	     Enable garbage collection of unused sections.

	     Generate .gdb_index section.

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

     --help  Print a help message.

	     Enable identical code folding.

	     Enable safe identical code	folding.

	     Disable identical code folding.

	     Set the base address to value.

	     Specify an	initializer function.

	     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.

	     AA	pipeline to run	during LTO.  Used in conjunction with

	     Passes to run during LTO.

	     Optimization level	for LTO.

	     Number of LTO codegen partitions.

     -m	value
	     Set target	emulation.

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

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

	     Always set	DT_NEEDED for shared libraries.

	     Do	not use	colors in diagnostics.

	     Do	not assign space to common symbols.

	     Do	not demangle symbol names.

	     Inhibit output of an .interp section.

	     Disable garbage collection	of unused sections.

	     Disable STB_GNU_UNIQUE symbol binding.

	     Do	not put	read-only non-executable sections in their own seg-

	     Do	not run	the linker multi-threaded.

	     Report version scripts that refer undefined symbols.

	     Report unresolved symbols even if the linker is creating a	shared

	     Restores the default behavior of loading archive members.

	     Do	not create a position independent executable.

	     Retain the	executable output file whenever	it is still usable.

	     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.

	     Optimize output file size.	 value may be:

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

	     -O1 is the	default.

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

     --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.

	     Include hotness information in the	optimization remarks file.

	     Always generate position independent thunks.

     --pie   Create a position independent executable.

	     List removed unused sections.

	     List identical folded sections.

	     Print a link map to the standard output.

	     Save the current state of --as-needed, --static, and

	     Undo the effect of	--push-state.

     --relocatable, -r
	     Create relocatable	object file.

	     Dump linker invocation and	input files for	debugging.

	     Retain only the symbols listed in the file.

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

	     Quoting style for response	files.	The supported values are
	     windows and posix.

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

	     Set address of section.

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

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

	     Specifies sections	sorting	rule when linkerscript is used.

	     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.

	     Lay out sections in the order specified by	file.

	     Set the system root.

	     Interpret R_ARM_TARGET1 as	R_ARM_ABS32.

	     Interpret R_ARM_TARGET1 as	R_ARM_REL32.

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

	     Same as --section-start with .bss as the sectionname.

	     Same as --section-start with .data	as the sectionname.

	     Same as --section-start with .text	as the sectionname.

	     Path to ThinLTO cached object file	directory.

	     Pruning policy for	the ThinLTO cache.

	     Number of ThinLTO jobs.

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

	     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.

	     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 mode.

	     Read version script from file.

	     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 about	duplicate common symbols.

	     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.

	     Report unresolved symbols as warnings.

	     Force load	of all members in a static library.

	     Use wrapper functions for symbol.

     -z	option
	     Linker option extensions.

		     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.

		     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

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

		     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.

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

		     Disable combining and sorting multiple relocation sec-

		     Disable the creation of copy relocations.

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

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

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

		     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.

		     Emit retpoline format PLT entries as a mitigation for

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

		     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.

		     Create a PT_OPENBSD_WXNEEDED segment.

     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

     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.

FreeBSD	13.0		      September	26, 2018		  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help