LD(1)

NAME
ld - link editor

SYNOPSIS
ld [(] [-]) [-Bdynamic] [-Bshareable] [-Bstatic] [-I file | --dynamic-linker=file] [-L dir | --library-path=dir] [-M | --print-map] [-T script-file | --script=script-file] [-V | -v | --version] [-a linkmode] [-b input-format | --format=input-format] [-call_shared] [-d | -dc | -dp] [-dn] [-dy] [-e symbol | --entry=symbol] [-h name | -soname=name] [-l library | --library=library] [-o output-file | --output=output-file] [-q | --emit-relocs] [-r | --relocatable] [-u name | --undefined=name] [-z keyword] [--as-needed] [--eh-frame-hdr] [--end-group] [--gc-sections] [--no-as-needed] [--no-define-common] [--no-gc-sections] [--no-print-gc-sections] [--no-whole-archive] [--oformat=format] [--pic-executable | -pie] [--print-gc-sections] [--rpath=dirs] [--rpath-link=dirs] [--start-group] [-shared] [-static] [--version-script=script] [--whole-archive] file ...

DESCRIPTION
The ld utility combines ELF objects and ar(1) archives containing ELF objects into an executable or a partially relocated object.

The ld utility processes options and files in the order presented on the command line. Unlike most UNIX utilities, options and file names may be interspersed. Options seen on the command line will generally apply to subsequent files, or till overridden by another option.

OPTIONS

The ld utility supports the following options:

    ( archives... -) Start a group of archives that are to be searched repeatedly until no new undefined references are created. This option is used when there are circular references between one or more archives in the archive group.

    The files named by the arguments archives are expected to be archive files.

    Each use of the ( option starts a new archive group that is ended by a matching -) option.

-Bdynamic
    Choose dynamic libraries for the libraries specified by subsequent -l options.

-Bshareable
    Create a shared library.

-Bstatic
    Choose static libraries for the libraries specified by subsequent -l options.

-I file | --dynamic-linker=file
    Set the name of the dynamic linker when generating ELF executables.

-L dir | --library-path=dir
    Add directory dir to the list of paths that ld will search for archive libraries. This option may be specified multiple times. User supplied directories are searched in the order specified on the command line.

-M | --print-map
    Print a link map to standard output.

-T script-file | --script=script-file
    Use the file name by argument script-file as the linker script instead of the default.

-V | -v | -version
    Print a version identifier for ld and exit.

-a linkmode
    Select linking mode. The value of the argument linkmode should be one of the following literals:
    default
        Equivalent to specifying -Bdynamic.
    archive
        Equivalent to specifying -Bstatic.
    shared
        Equivalent to specifying -Bdynamic.

-b input-format | --format input-format
    Set the input format to that specified by argument input-format. The legal values for the argument input-format are those supported by elftc_bfd_find_target(3).

-d | -dc | -dp
    Assign space for common symbols even if generating a relocatable object.

-dn Equivalent to specifying option -Bstatic.

-dy Equivalent to specifying option -Bdynamic.

-e entry | --entry entry
    Set execution to start at the symbol named by the argument entry. The argument should be the name of a symbol.

-h name | -soname name
    Set the DT_SONAME field in the object to that specified by the argument name.

-l name | --library=name
    Add the archive library or shared library named by argument name to the set of files to link. This file is looked for in the list of directories specified by prior -L options on the command line.

-o output-file | --output=output-file
    Use the file specified by argument output-file for the output, instead of the default file name of ‘a.out’.

-q | --emit-relocs
    Preserve relocation information in executables, for use by post-link analysis tools.

-r | --relocatable
    Generate a relocatable output file that can be used as input for subsequent linker runs.

-u name | --undefined=name
    Add the symbol specified by argument name to the output file as an undefined symbol. This option may be specified multiple times.

-z keyword
    Recognized keywords include:
    execstack
        Require the object to use an executable stack.
    noexecstack
        Do not require the object to use an executable stack.

--as-needed
    Add DT_NEEDED tags for only those shared libraries that satisfy non-weak unresolved references from object files or other dynamic libraries seen so far on the command line.

-call_shared
    Equivalent to specifying option -Bdynamic.

--eh-frame-hdr
    Create a “.eh_frame_hdr” section, and a PT_GNU_EH_FRAME segment header, containing exception handling information.

--end-group
    Equivalent to specifying option -).

--gc-sections
    Garbage collect unused input sections.

--no-as-needed
    Insert DT_NEEDED tags for all shared libraries seen henceforth on the command line, irrespective of whether the shared library is needed to resolve an undefined symbol or not. This behavior is the default.

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

--no-gc-sections
    Do not garbage collect input sections that contain unreferenced symbols.

--no-print-gc-sections
    Do not print the list of sections removed when the --gc-sections directive is active.

--no-whole-archive
    Only include objects in an archive that satisfy an unresolved reference in the link. This behavior is the default.

-non_shared
    Equivalent to specifying option -Bstatic.

--oformat=format
    Set the desired output format to that specified by the argument format. Supported values for argument format are those understood by elftc_bfd_find_target(3).

--pic-executable | -pie
    Create a position-independent executable.

--print-gc-sections
    Print the list of sections removed when the --gc-sections directive is active. The output is printed to stderr.

--rpath=dirs
    Add the colon-separated list of directories named by the argument dirs to the runtime library search path and to the link-time search path.

--rpath-link=dirs
    Add the directories specified by the colon-separated list of directories in argument dirs to the link-time search path for libraries. The directories specified by this option are searched before those specified by --rpath options.

-shared
    Equivalent to specifying option -Bshareable.

--start-group
    Equivalent to specifying option (.

-static
    Equivalent to specifying option -Bstatic.

--version-script=script-file
    Use the version script in the file named by argument script-file.

--whole-archive
    Include the entire contents of every archive file encountered on the command line after this option in the link.

DIAGNOSTICS

SEE ALSO
ar(1), ranlib(1), archive(3), elf(3), elftc_bfd_find_target(3), dwarf(3)

IMPLEMENTATION NOTES
The ld utility differs from its GNU equivalent in the following:

•   The ld utility currently supports a limited range of output formats.

•   The -e and --entry options only accept a symbol name as an argument, and not a numeric address.

•   The -l option only searches files in the directories specified by prior -L options.

•   The -T | --script option does not search for script files in the directories specified by prior -L options.

•   The --rpath option accepts a colon-separated list of directories instead of single directory.

The following options are recognized, but are currently unimplemented: -Bgroup, -Bsymbolic, -Bsymbolic_functions, -E, -EB, -EL, -F, -Map, -N, -O, -Qy, -R, -S, -Tbss, -Tdata, -Ttext, -X, -Y, -Ur, -c, -f, -g, -i, -m, -n, -s, -t, -x, -y, --accept-unknown-input-arch, --allow-multiple-definition, --allow-shlib-undefined, --assert, --auxiliary, --build-id, --check-sections, --cref, --defsym, --demangle, --disable-new-dtags, --discard-all, --discard-locals, --error-unresolved-symbols, --export-dynamic, --emulation, --enable-new-dtags, --fatal-warnings, --filter, --fini, --hash-style, --help, --init, --just-symbols, --mri-script, --nmagic, -nostdlib, --no-accept-unknown-input-arch, --no-allow-shlib-undefined, --no-assert, --no-check-sections, --no-demangle, --no-keep-memory, --no-omagic, --no-undefined, --no-undefined-version, --no-warn-mismatch, --omagic, --qmagic, --relax, --retain-symbols-file, --runpath, --section-start, --sort-common, --split-by-file, --split-by-reloc, --stats, --strip-all, --strip-debug, --trace, --trace_symbol, --traditional-format, --unique, --unresolved-symbols, --verbose, --warn-common, --warn-constructors, --warn-multiple-gp, --warn-once, --warn-section-align, --warn-shared-textrel, --warn-unresolved-symbols, --wrap.

The following keywords are recognized by the -z option, but are currently unimplemented: allextract, defaultextract, defs, ignore, initfirst, lazyload, muldefs, nodefaultlib, nodefs, nodelete, nodlopen, nolazyload, now, origin, record, systemlibrary, weakextract.

HISTORY
A ld command first appeared in AT&T UNIX Version 1.

The Elftoolchain implementation of ld was written by Kai Wang <kaiwang27@gmail.com>.