SYNOPSIS
ld [ option ... ] [ file ... ]
DESCRIPTION
The ld command combines several Mach-O (Mach object) files into one by
combining like sections in like segments from all the object files,
resolving external references, and searching libraries. In the sim-
plest case several object files are given, and ld combines them, pro-
ducing an object file which can either be executed or become the input
for a further ld run. (In the latter case, the -r option must be given
to preserve the relocation information.) Unless an output file is
specified, ld produces a file named a.out. This file is made exe-
cutable only if no errors occurred during the link editing and there
are no undefined symbols.
UNIVERSAL FILE SUPPORT
The link editor accepts ``universal'' (multiple-architecture) input
files, but always creates a ``thin'' (single-architecture), standard
Mach-O output file. The architecture is specified using the -arch
arch_type option. If this option is not used, ld(1) attempts to deter-
mine the output architecture by examining the first object file encoun-
tered on the command line. If it is a ``thin'' file, its architecture
determines that of the output file. If the first input file is a
``universal'' file, the ``best'' architecture for the host is used.
(See the explanation of the -arch option, below.)
The compiler driver cc(1) handles creating universal executables by
calling ld(1) multiple times and using lipo(1) to create a ``univer-
sal'' file from the results of the ld(1) executions.
OUTPUT FILE LAYOUT
The object files are loaded in the order in which they are specified on
the command line. The segments and the sections in those segments will
appear in the output file in the order they are encountered in the
object files being linked. All zero fill sections will appear after
all non-zero fill sections in their segments.
Sections created from files with the -sectcreate option will appear in
the output file last. Section names for sections created from files
are not allowed to overlap with a section name in the same segment as a
section coming from an object file. Sections created from files may be
in a segment which has sections from object files and if so will be
loaded at the end of the non-zero fill sections for that segment.
If the option -seglinkedit is specified, the segment it creates is the
last segment in the output file.
The address of each segment can be specified with -segaddr, which takes
the segment's name as an argument. The address of the first segment
can alternatively be specified using -seg1addr, in which case a segment
name is not used. Segments that do not have a specified address will
be assigned addresses in the order in which they appear in the output
memory exception.
The entry point of the output file is the beginning of the first sec-
tion in the first segment (unless the -e option is specified).
STATIC ARCHIVE LIBRARIES
ld supports two types of libraries: static archive libraries and
dynamic shared libraries. Searching for undefined symbols is performed
differently for dynamic shared libraries than it is for static archive
libraries. The searching of dynamic shared libraries is described
later.
When a static archive library is specified as an argument to ld, it is
searched exactly once, at the point it is encountered in the argument
list. Only those members defining an unresolved external reference, as
defined by the static archive library's table of contents, are loaded.
To produce the table of contents, all static archive libraries must be
processed by ranlib(1).
Generally, a static archive library does not have multiple members that
define the same symbol. For these types of libraries, the order of the
members is not important, so the table of contents can be sorted for
faster link editing using the -s option to ranlib(1). The first member
of the static archive library is named ``__.SYMDEF SORTED'', which is
understood to be a sorted table of contents.
If the static archive library does have multiple members that define
the same symbol, the table of contents that ranlib(1) produces can't be
sorted. Instead, it follows the order in which the members appear in
the static archive library. The link editor searches the table of con-
tents iteratively, loading members until no further references are sat-
isfied. In the unsorted case, the first member of the static archive
library is named ``__.SYMDEF'', which is understood to be a table of
contents in the order of the archive members.
Static archive library members can also be loaded in response to the
-ObjC and -all_load flags. See their descriptions below.
DYNAMIC SHARED LIBRARIES
When a dynamic shared library or an object file that was linked against
a dynamic shared library is specified as an argument to ld, that
library is placed in the dynamic shared library search list. The order
of the search list is always the same order the libraries were encoun-
tered on the command line. When linking -flat_namespace, all dynamic
libraries that the dynamic libraries are dependent upon are added to
the end of the search list.
Once the search list is constructed, the static link editor checks for
undefined symbols by simulating the way the dynamic linker will search
for undefined symbols at runtime. For each undefined symbol, the static
link editor searches each library in the search list until it finds a
different executions of the same program can produce different linking
because the dynamic linker binds undefined functions as they are
called, and this affects the order in which undefined symbols are
bound. Because it can produce different dynamic linking, using dynamic
shared libraries that define the same symbols in the same program is
strongly discouraged.
If a static archive library appears after a dynamic shared library on
the command line, the static library is placed in the dynamic library
search list and is searched as a dynamic library. In this way, when a
dynamic library has undefined symbols, it will cause the appropriate
members of the static libraries to be loaded into the output. Search-
ing static libraries as dynamic libraries can cause problems if the
dynamic library later changes to reference symbols from the static
library that it did not previously reference. In this case when the
program runs, the dynamic linker will report these symbols as undefined
because the members for these symbols were not loaded into the output.
TWO-LEVEL AND FLAT NAMESPACES
Two-level and flat namespaces refer to how references to symbols in
dynamic libraries are resolved to a definition in specific dynamic
library. For two-level namespace that resolution is done at static
link time when each image (program, bundle and shared library) is
built. When a program is using images built with two-level namespace
there may be different global symbols with the same name being used by
different images in the program (this is now the default). When a pro-
gram is using all flat namespace images then only one global symbol for
each global symbol name is used by all images of the program (this was
the default in MacOS X 10.0).
When creating an output file with the static link editor that links
against dynamic libraries, the references to symbols in those libraries
can be recorded at static link time to bind to a specific library defi-
nition (two-level namespace) or left to be bound at execution time to
the first library in the search order of the program (flat namespace).
A program, its dynamic libraries and its bundles may each be either
two-level or flat namespace images. The dynamic linker will bind each
image according to how it was built.
When creating an output file with the static link editor when
-twolevel_namespace is in effect (now the default) all undefined refer-
ences must be satisfied at static link time. The flags to allow unde-
fined references, -Usymbol_name, -undefined warning and -undefined sup-
press can't be used. When the environment variable MACOSX_DEPLOY-
MENT_TARGET is set to 10.3 or higher then -undefined dynamic_lookup can
also be used. The specific library definition recorded for each refer-
ence is the first library that has a definition as listed on the link
line. Listing an umbrella framework implies all of its sub-frameworks,
sub-umbrellas and sub-libraries. For any reference to a definition
found in an umbrella framework's sub-framework, sub-umbrella or sub-
library will be recorded as coming from the umbrella framework. Then
When creating a output file with the static link editor when
-flat_namespace is in effect (the MacOS X 10.0 default) all
undefined references must be satisfied at static link time when
-undefined error (the default) is used. The static link editor
checks the undefined references by searching all the libraries
listed on the link line then all dependent libraries. The unde-
fined symbols in the created output file are left to be resolved
at execution time by the dynamic link editor in the dynamic
libraries in the search order of the program.
MULTIPLY DEFINED SYMBOLS
If there are multiply defined symbols in the object files being linked
into the output file being created this always results in a multiply
defined symbol error.
When the static link editor links symbols in from a dynamic library
that result in multiply defined symbols the handling depends on the
type of name space of output file being created and possibly the type
of name space of the dynamic library.
When the static link editor is creating a two-level namespace image and
a there is a multiply defined symbol from dynamic library then that
generates a multiply defined symbol warning (by default), where the
treatment of this warning can be changed with the -multiply_defined
flag.
When the static link editor is creating a flat namespace image and a
there is a multiply defined symbol from dynamic library, if the library
is a flat namespace image then that generates a multiply defined symbol
error. If the library is a two-level namespace image then that gener-
ates a multiply defined symbol warning (by default), where the treat-
ment of this warning can be changed with the -multiply_defined flag.
USING THE DYNAMIC LINK EDITOR AND DYNAMIC SHARED LIBRARIES
The option -dynamic must be specified in order to use dynamic shared
libraries (and any of the features used to implement them) and/or the
dynamic link editor. To make sure that the output is not using any
features that would require the dynamic link editor, the flag -static
can be specified. Only one of these flags can be specified.
LINK EDITOR DEFINED SYMBOLS
There is a group of link editor defined symbols for the MH_EXECUTE,
MH_DYLIB and MH_PRELOAD file types (see the header file <mach-
o/ldsyms.h>). Link editor symbols are reserved; it is an error if an
input object file defines such a symbol. Only those link editor sym-
bols that are referenced by the object file appear in the output file's
symbol table.
The link editor defined symbol `__mh_execute_header' (`_mh_exe-
_dyld_get_image_vmaddr_slide(3) added to them.
The MH_PRELOAD file type has link editor defined symbols for the begin-
ning and ending of each segment, and for the beginning and ending of
each section within a segment. These names are provided for use in a
Mach-O preloaded file, since it does not have its headers loaded as
part of the first segment. The names of the symbols for a segment's
beginning and end have the form: __SEGNAME__begin and __SEGNAME__end,
where __SEGNAME is the name of the segment. Similarly, the symbols for
a section have the form: __SEGNAME__sectname__begin and __SEG-
NAME__sectname__end, where __sectname is the name of the section in the
segment __SEGNAME. These symbols' types are those of the section that
the names refer to. (A symbol that refers to the end of a section
actually has, as its value, the beginning address of the next section,
but the symbol's type is still that of the section mentioned in the
symbol's name.)
OPTIONS
Ld understands several options. Filenames and options that refer to
libraries (such as -l and -framework), as well as options that create
symbols (such as -u and -i), are position-dependent: They define the
load order and affect what gets loaded from libraries. Some ld options
overlap with compiler options. If the compiler driver cc(1) is used to
invoke ld , it maybe necessary to pass the ld(1) options to cc(1) using
-Wl,-option,argument1,argument2.
In this release of the static link editor, 64-bit code (-arch ppc64)
are processed by a separate tool /usr/bin/ld64. Not all of the ld com-
mand line options are recognized by this tool. The options not cur-
rently support for building 64-bit binaries are flagged (32-bit only).
The most common option is:
-o name
The output file is named name, instead of a.out.
The following flags are related to architectures:
-arch arch_type
Specifies the architecture, arch_type, for the output file.
``Universal'' input files that do not contain this specified
architecture are ignored. Only one -arch arch_type can be spec-
ified. See arch(3) for the currently known arch_types. If
arch_type specifies a certain implementation of an architecture
(such as -arch m68040 or -arch i486 ), the resulting object file
has that specific CPU subtype, and it is an error if any input
file has a CPU subtype that will not combine to the CPU subtype
for arch_type.
The default output file architecture is determined by the first
object file to be linked. If it is a ``thin'' (standard Mach-O)
ture the error messages refer to.
-force_cpusubtype_ALL
The -force_cpusubtype_ALL flag causes the CPU subtype to remain
the ALL CPU subtype and not to be combined or changed. This
flag has precedence over any -arch arch_type flag for a specific
implementation. This is the default for all x86 architectures.
The following flags are related to using the dynamic link editor and/or
dynamic shared libraries (and any of the features used to implement
them):
-dynamic
Allows use of the features associated with dynamic link editor.
The default is -dynamic.
-static
Causes those features associated with dynamic link editor to be
treated as an error. (The description for the options that will
cause an error if you use them in conjunction with -static are
marked with the statement "when -dynamic
is used").
-read_only_relocs treatment
Specifies how relocation entries in read-only sections are to be
treated when -dynamic is used. To get the best possible shar-
ing, the read-only sections should not have any relocation
entries. If they do, the dynamic linker will write on the sec-
tion. Having relocation entries appear in read-only sections is
normally avoided by compiling with the option -dynamic. But in
such cases non-converted assembly code or objects not compiled
with -dynamic relocation entries will appear in read-only sec-
tions. The treatment can be: error, warning, or suppress.
Which cause the treatment of relocation entries in read-only
sections as either, errors, warnings, or suppressed messages.
The default is to treat these as errors.
-sect_diff_relocs treatment
Specifies how section difference relocation enries are to be
treated when -dynamic and -execute are used. To get the best
possible code generation the compiler should not generate code
for executables (MH_EXECUTE format outputs) that have any sec-
tion difference relocation entries. The gcc(1) compiler has the
-mdynamic-no-pic flag for generating code for executables. The
default treatment is suppress, where no message is printed. The
other treatments are error or warning. This option can also be
specified by setting the environment variable
LD_SECT_DIFF_RELOCS to the treatment values.
-weak_reference_mismatches treatment
Specifies how to treat mismatches of symbol references in the
the object files being linked. Normally the all the undefined
the dynamic libraries it is being linked with. This optimiza-
tion can only be done if the libraries don't overlap and no sym-
bols are overridden. When the resulting program is run and the
same libraries are used to run the program as when the program
was linked, the dynamic linker can use the prebound addresses.
If not, the dynamic linker undoes the prebinding and binds nor-
mally. This option can also be specified by setting the envi-
ronment variable LD_PREBIND. If the environment variable
LD_FORCE_NO_PREBIND is set both the option -prebind LD_PREBIND
environment variable are ignore and the output is not prebound.
Or if the environment variable MACOSX_DEPLOYMENT_TARGET is set
to 10.4 or greater and the output is not a split a dynamic
library the output is not prebound.
-noprebind (32-bit only)
Do not have the static linker, ld(1), prebind the output. If
this is specified the environment variable LD_PREBIND is
ignored.
-prebind_allow_overlap (32-bit only)
Have the static linker, ld(1), prebind the output even if the
addresses of the dynamic libraries it uses overlap. The result-
ing output can then have redo_prebinding(1) run on it to fix up
the prebinding after the overlapping dynamic libraries have been
rebuilt. This option can also be specified by setting the envi-
ronment variable LD_PREBIND_ALLOW_OVERLAP.
-prebind_all_twolevel_modules (32-bit only)
Have the static linker, ld(1), mark all modules from prebound
two-level namespace dynamic libraries as used by the program
even if they are not statically referenced. This can provide
improved launch time for programs like Objective-C programs that
use symbols indirectly through NIB files. This option can also
be specified by setting the environment variable LD_PRE-
BIND_ALL_TWOLEVEL_MODULES.
-noprebind_all_twolevel_modules (32-bit only)
Don't have the static linker, ld(1), mark all modules from pre-
bound two-level namespace dynamic libraries as used by the pro-
gram. This flag overrides the setting of the environment vari-
able LD_PREBIND_ALL_TWOLEVEL_MODULES.
-nofixprebinding (32-bit only)
Have the static linker, ld(1), mark the executable so that the
dynamic linker will never notify the prebinding agent if this
launched and its prebinding is out of date. This is used when
building the prebinding agent itself.
The following flags are related to libraries:
-lx This option is an abbreviation for the library name `libx.a',
where x is a string. If -dynamic is specified the abbreviation
when using this as the use of the non-weak symbol references in
an object file may cause the program to crash when the symbol or
library is not present at execution time.
-weak_library file_name_path_to_library
This is the same as listing a file name path to a library on the
link line except that it forces the library and all references
to it to be marked as weak imports. Care must be taken when
using this as the use of the non-weak symbol references in an
object file may cause the program to crash when the symbol or
library is not present at execution time.
-Ldir Add dir to the list of directories in which to search for
libraries. Directories specified with -L are searched before
the standard directories.
-Z Do not search the standard directories when searching for
libraries.
-syslibroot rootdir (32-bit only)
Prepend rootdir to the standard directories when searching for
libraries or frameworks.
-search_paths_first
By default when the -dynamic flag is in effect, the -lx and
-weak-lx options first search for a file of the form
`libx.dylib' in each directory in the library search path, then
a file of the form `libx.a' is searched for in the library
search paths. This option changes it so that in each path
`libx.dylib' is searched for then `libx.a' before the next path
in the library search path is searched.
-framework name[,suffix]
Specifies a framework to link against. Frameworks are dynamic
shared libraries, but they are stored in different locations,
and therefore must be searched for differently. When this option
is specified, ld searches for framework `name.framework/name'
first in any directories specified with the -F option, then in
the standard framework directories /Library/Frameworks, /Net-
work/Library/Frameworks, and /System/Library/Frameworks. The
placement of the -framework option is significant, as it deter-
mines when and how the framework is searched. If the optional
suffix is specified the framework is first searched for the name
with the suffix and then without.
-weak_framework name[,suffix]
This is the same as the -framework name[,suffix] but forces the
framework and all references to it to be marked as weak imports.
Care must be taken when using this as the use of the non-weak
symbol references in an object file may cause the program to
crash when the symbol or framework is not present at execution
time.
Specifies that a dynamic shared library is in a different loca-
tion than its standard location. Use this option when you link
with a library that is dependent on a dynamic library, and the
dynamic library is in a location other than its default loca-
tion. install_name specifies the path where the library nor-
mally resides. file_name specifies the path of the library you
want to use instead. For example, if you link to a library that
depends upon the dynamic library libsys and you have libsys
installed in a nondefault location, you would use this option:
-dylib_file /lib/libsys_s.A.dylib:/me/lib/libsys_s.A.dylib.
-executable_path path_name(32-bitonly)
Specifies that path_name is used to replace @executable_path for
dependent libraries.
The following options specify the output file format (the file type):
-execute
Produce a Mach-O demand-paged executable format file. The head-
ers are placed in the first segment, and all segments are padded
to the segment alignment. This has a file type of MH_EXECUTE.
This is the default. If no segment address is specified at
address zero, a segment with no protection (no read, write, or
execute permission) is created at address zero. This segment,
whose size is that of the segment alignment, is named
``__PAGEZERO''. This option was previously named -Mach, which
will continue to be recognized.
-object (32-bit only)
Produce a Mach-O file in the relocatable object file format that
is intended for execution. This differs from using the -r
option in that it defines common symbols, does not allow unde-
fined symbols and does not preserve relocation entries. This
has a file type of MH_OBJECT. In this format all sections are
placed in one unnamed segment with all protections (read, write,
execute) allowed on that segment. This is intended for
extremely small programs that would otherwise be large due to
segment padding. In this format, and all non-MH_EXECUTE for-
mats, the link editor defined symbol ``__mh_execute_header'' is
not defined since the headers are not part of the segment. This
format file can't be used with the dynamic linker.
-preload (32-bit only)
Produce a Mach-O preloaded executable format file. The headers
are not placed in any segment. All sections are placed in their
proper segments and they are padded to the segment alignment.
This has a file type of MH_PRELOAD. This option was previously
-p, which will continue to be recognized.
-dylib Produce a Mach-O dynamically linked shared library format file.
The headers are placed in the first segment. All sections are
ment. This has a file type of MH_DYLINKER.
-fvmlib (32-bit only)
Produce a Mach-O fixed VM shared library format file. The head-
ers are placed in the first segment but the first section in
that segment will be placed on the next segment alignment bound-
ary in that segment. All sections are placed in their proper
segments and they are padded to the segment alignment. This has
a file type of MH_FVMLIB.
The following flags affect the contents of the output file:
-r Save the relocation information in the output file so that it
can be the subject of another ld run. The resulting file type
is a Mach-O relocatable file (MH_OBJECT) if not otherwise speci-
fied. This flag also prevents final definitions from being
given to common symbols, and suppresses the `undefined symbol'
diagnostics.
-d (32-bit only)
Force definition of common storage even if the -r option is
present. This option also forces link editor defined symbols to
be defined. This option is assumed when there is a dynamic link
editor load command in the input and -r is not specified.
The following flags support segment specifications:
-segalign value (32-bit only)
Specifies the segment alignment. value is a hexadecimal number
that must be an integral power of 2. The default is the target
pagesize (currently 1000 hex for the PowerPC and i386).
-seg1addr addr
Specifies the starting address of the first segment in the out-
put file. addr is a hexadecimal number and must be a multiple
of the segment alignment. This option can also be specified as
-image_base.
-segaddr name addr (32-bit only)
Specifies the starting address of the segment named name to be
addr. The address must be a hexadecimal number that is a multi-
ple of the segment alignment.
-segs_read_only_addr addr (32-bit only)
Specifies the starting address of the read-only segments in a
dynamic shared library. When this option is used the dynamic
shared library is built such that the read-only and read-write
segments are split into separate address ranges. By default the
read-write segments are 256meg (0x10000000) after the read-only
segments. addr is a hexadecimal number and must be a multiple
lines containing either a single hex address and an install name
or two hex addresses and an install name. In the first form the
single hex address is used as the -seg1addr . In the second
form the first address is used as the -segs_read_only_addr
address and the second address is used as the
-segs_read_write_addr address. This option can also be speci-
fied by setting the environment variable LD_SEG_ADDR_TABLE. If
the environment variable is set then any -seg1addr,
-segs_read_only_addr, -segs_read_write_addr and -seg_addr_table
options are ignored and a warning is printed.
-seg_addr_table_filename pathname (32-bit only)
Use pathname instead of the install name of the library for
matching an entry in the segment address table.
-segprot name max init (32-bit only)
Specifies the maximum and initial virtual memory protection of
the named segment, name, to be max and init ,respectively. The
values for max and init are any combination of the characters
`r' (for read), `w' (for write), `x' (for execute) and '-' (no
access). The default is `rwx' for the maximum protection for
all segments for PowerPC architecures and `rw` for the all Intel
architecures. The default for the initial protection for all
segments is `rw' unless the segment contains a section which
contains some machine instructions, in which case the default
for the initial protection is `rwx' (and for Intel architecures
it also sets the maximum protection to `rwx' in this case). The
default for the initial protection for the ``__TEXT'' segment is
`rx' (not writable).
-seglinkedit (32-bit only)
Create the link edit segment, named ``__LINKEDIT'' (this is the
default). This segment contains all the link edit information
(relocation information, symbol table, string table, etc.) in
the object file. If the segment protection for this segment is
not specified, the initial protection is not writable. This can
only be specified when the output file type is not MH_OBJECT and
MH_PRELOAD output file types. To get at the contents of this
section, the Mach header and load commands must be parsed from
the link editor defined symbols like `__mh_execute_header' (see
Mach-O(5)).
-noseglinkedit (32-bit only)
Do not create the link edit segment (see -seglinkedit above).
-pagezero_size value
Specifies the segment size of __PAGEZERO to be of size value,
where value is a hexadecimal number rounded to the segment
alignment. The default is the target pagesize (currently, 1000
hexadecimal for the PowerPC and for i386).
-stack_addr value
hexadecimal number rounded to the segment alignment. The
default segment alignment is the target pagesize (currently,
1000 hexadecimal for the PowerPC and for i386). If -stack_addr
is specified and -stack_size is not, a default stack size spe-
cific for the architecture being linked will be used and its
value printed as a warning message. This creates a segment
named __UNIXSTACK .
-allow_stack_execute
Marks executable so that all stacks in the task will be given
stack execution privilege. This includes pthread stacks.
The following flags support section specifications:
-sectcreate segname sectname file
The section sectname in the segment segname is created from the
contents of file. The combination of segname and sectname must
be unique; there cannot already be a section (segname,sectname)
in any input object file. This option was previously called
-segcreate, which will continue to be recognized.
-sectalign segname sectname value
The section named sectname in the segment segname will have its
alignment set to value, where value is a hexadecimal number that
must be an integral power of 2. This can be used to set the
alignment of a section created from a file, or to increase the
alignment of a section from an object file, or to set the maxi-
mum alignment of the (__DATA,__common) section, where common
symbols are defined by the link editor. Setting the alignment
of a literal section causes the individual literals to be
aligned on that boundary. If the section alignment is not spec-
ified by a section header in an object file or on the command
line, it defaults to 10 (hex), indicating 16-byte alignment.
-sectorder segname sectname orderfile(32-bitonly)
The section sectname in the segment segname of the input files
will be broken up into blocks associated with symbols in the
section. The output section will be created by ordering the
blocks as specified by the lines in the orderfile. These blocks
are aligned to the output file's section alignment for this sec-
tion. Any section can be ordered in the output file except sym-
bol pointer and symbol stub sections.
For non-literal sections, each line of the orderfile contains an
object name and a symbol name, separated by a single colon
(':'). Lines that start with # are ignored and treated as com-
ments. If the object file is in an archive, the archive name,
followed by a single colon, must precede the object file name.
The object file names and archive names should be exactly the
names as seen by the link editor, but if not, the link editor
attempts to match up the names the best it can. For non-literal
literal pointer is represented by the name of the segment that
contains the literal being pointed to, followed by the section
name, followed by the literal. These three strings are separated
by colons with no extra white space. For all the literal sec-
tions, each line in the the order file is simply entered into
the literal section and will appear in the output file in the
same order as in the order file. There is no check to see
whether the literal is present in the loaded objects. For lit-
eral sections, the easiest way to generate an order file is with
the ``-X -v -s segname sectname'' options to otool(1).
-sectorder_detail (32-bit only)
When using the -sectorder option, any pairs of object file
names and symbol names that are found in the loaded objects, but
not specified in the orderfile, are placed last in the output
file's section. These pairs are ordered by object file (as the
filenames appear on the command line), with the different sym-
bols from a given object file being ordered by increasing symbol
address (that is, the order in which the symbols occurred in the
object file, not their order in the symbol table). By default,
the link editor displays a summary that simply shows the number
of symbol names found in the loaded objects but not in the
orderfile, as well as the number of symbol names listed in the
orderfile but not found in the loaded objects. (The summary is
omitted if both values are zero.) To instead produce a detailed
list of these symbols, use the -sectorder_detail flag. If an
object file-symbol name pair is listed multiple times, a warning
is generated, and the first occurrence is used.
-sectobjectsymbols segname sectname (32-bit only)
This causes the link editor to generate local symbols in the
section sectname in the segment segname. Each object file that
has one of these sections will have a local symbol created whose
name is that of the object file, or of the member of the ar-
chive. The symbol's value will be the first address where that
object file's section was loaded. The symbol has the type
N_SECT and its section number is the the same as that of the
section (segname,sectname) in the output file. This symbol will
be placed in the symbol table just before all other local sym-
bols for the object file. This feature is typically used where
the section is (__TEXT,__text), in order to help the debugger
debug object files produced by old versions of the compiler or
by non-Apple compilers.
The following flags are related to name spaces:
-twolevel_namespace
Specifies the output to be built as a two-level namespace image.
This option can also be specified by setting the environment
variable LD_TWOLEVEL_NAMESPACE. This is the default.
checked against the specified executable like it was one of the
dynamic libraries the bundle was linked with. If the bundle
being created with -twolevel_namespace in effect then the
searching of the executable for symbols is based on the place-
ment of the -bundle_loader flag relative to the dynamic
libraries. If the the bundle being created with -flat_namespace
then the searching of the executable is done before all dynamic
libraries.
-private_bundle (32-bit only)
This allows symbols defined in the output to also be defined in
executable in the -bundle_loader argument when -flat_namespace
is in effect. This implies that the bundle output file being
created is going to be loaded by the executable with the
NSLINKMODULE_OPTION_PRIVATE option to NSLinkModule(3).
-twolevel_namespace_hints (32-bit only)
Specifies to create the output with the two-level namespace
hints table to be used by the dynamic linker. This is the
default except when the -bundle flag is specified. If this is
used when the -bundle flag is specified the bundle will fail to
load on a MacOS X 10.0 system with a malformed object error.
-multiply_defined treatment (32-bit only)
Specifies how multiply defined symbols in dynamic libraries when
-twolevel_namespace is in effect are to be treated. treatment
can be: error, warning, or suppress. Which cause the treatment
of multiply defined symbols in dynamic libraries as either,
errors, warnings, or suppresses the checking of multiply symbols
from dynamic libraries when -twolevel_namespace is in effect.
The default is to treat multiply defined symbols in dynamic
libraries as warnings when -twolevel_namespace is in effect.
-multiply_defined_unused treatment (32-bit only)
Specifies how unused multiply defined symbols in dynamic
libraries when -twolevel_namespace is in effect are to be
treated. An unused multiply defined symbol is one in which
there is a symbol defined in the output that is also defined in
the dynamic libraries the output is linked with but the symbol
in the dynamic library is not used by any reference in the out-
put. treatment can be: error, warning, or suppress. The
default for unused multiply defined symbols is to suppress these
messages.
-nomultidefs (32-bit only)
specifying this flag marks the umbrella being created such that
the dynamic linker is guaranteed that no multiple definitions of
symbols in the umbrella's sub-images will ever exist. This
allows the dynamic linker to always use the two-level namespace
lookup hints even if the timestamps of the sub-images do not
match. This flag implies -multiply_defined error.
For the first number undefined symbols, displays each file in
which the symbol appears, its type and whether the file defines
or references it (that is, the same style of output produced by
the -y option). To keep the output manageable, this option dis-
plays at most number references.
-keep_private_externs
Don't turn private external symbols into static symbols, but
rather leave them as private external in the resulting output
file.
-m (32-bit only)
Don't treat multiply defined symbols from the linked objects as
a hard error; instead, simply print a warning. The first linked
object defining such a symbol is used for linking; its value is
used for the symbol in the symbol table. The code and data for
all such symbols are copied into the output. The duplicate sym-
bols other than the first symbol may still end up being used in
the resulting output file through local references. This can
still produce a resulting output file that is in error. This
flag's use is strongly discouraged!
-whyload (32-bit only)
Indicate why each member of a library is loaded. In other
words, indicate which currently undefined symbol is being
resolved, causing that member to be loaded. This in combination
with the above -ysym flag can help determine exactly why a link
edit is failing due to multiply defined symbols.
-u sym Enter the argument sym into the symbol table as an undefined
symbol. This is useful for loading wholly from a library, since
initially the symbol table is empty and an unresolved reference
is needed to force the loading of the first object file.
-e sym The argument sym is taken to be the symbol name of the entry
point of the resulting file. By default, the entry point is the
address of the first section in the first segment.
-idefinition:indirect (32-bit only)
Create an indirect symbol for the symbol name definition which
is defined to be the same as the symbol name indirect (which is
taken to be undefined). When a definition of the symbol named
indirect is linked, both symbols will take on the defined type
and value.
This option overlaps with a compiler option. If you use the
compiler driver cc(1) to invoke ld, invoke this option in this
way: -Wl,-idefinition:indirect.
-undefined treatment
Specifies how undefined symbols are to be treated. treatment
-U sym Allow the symbol sym to be undefined, even if the -r flag is not
given. Produce an executable file if the only undefined symbols
are those specified with -U.
This option overlaps with a compiler option. If you use the
compiler driver cc(1) to invoke ld, invoke this option in this
way: -Wl,-U,sym.
-bind_at_load
Causes the output file to be marked such that the dynamic linker
will bind all undefined references when the file is loaded or
launched.
-commons treatment (64-bit only)
Specifies how common symbols (tentative defintions) from object
files interact with dynamic libraries. treatment can be:
ignore_dylibs, use_dylibs, or error. The default is
ignore_dylibs which means the static linker will use a common
defintion from an object file even if a true definition exisits
in a dynamic library. If you want your code to use a dynamic
library definition, then add the extern keyword to your tenta-
tive definition (e.g. change int foo; to extern int foo; ). The
treatment use_dylibs means a definition form a dynamic library
should override a common symbol in an object file. Note, the
32-bit linker always uses this treatment. The treatment error
means the linker should abort whenever if finds a common symbol
in an object file and an external definition with the same name
in a dynamic library.
-warn_commons (64-bit only)
Causes the static linker to write a diagnostic line about how
common symbols were processed. This is useful for debugging
problems with common symbols.
The following flags are related to stripping link edit information.
This information can also be removed by strip(1), which uses the same
options. (The exception is the -s flag below, but this is the same as
strip(1) with no arguments.) The following flags are listed in
decreasing level of stripping.
-s (32-bit only)
Completely strip the output; that is, remove the symbol table
and relocation information.
-x (32-bit only)
Strips the non-global symbols; only saves external symbols.
This option overlaps with a compiler option. If you use the
compiler driver cc(1) to invoke ld, invoke this option in this
way: -Wl,-x.
the default.
-b (32-bit only)
Strip the base file's symbols from the output file. (The base
file is given as the argument to the -A option.)
This option overlaps with a compiler option. If you use the
compiler driver cc(1) to invoke ld, invoke this option in this
way: -Wl,-b.
-Sn (32-bit only)
Don't strip any symbols.
-exported_symbols_list filename
The specified filename contains lists of global symbol names
that will remain as global symbols in the output file. All
other global symbols will be treated as if they were marked as
__private_extern__ and will not be global in the output file.
The symbol names listed in filename must be one per line. Lead-
ing and trailing white space are not part of the symbol name.
Lines starting with # are ignored, as are lines with only white
space.
-unexported_symbols_list filename
The specified filename contains lists of global symbol names
that will not remain as global symbols in the output file. The
symbols will be treated as if they were marked as __pri-
vate_extern__ and will not be global in the output file. The
symbol names listed in filename must be one per line. Leading
and trailing white space are not part of the symbol name. Lines
starting with # are ignored, as are lines with only white space.
-no_uuid
Do not emit an LC_UUID load command in the linked output file.
-dead_strip (32-bit only)
Remove blocks of code and data that are unreachable by the entry
point or exported symbols.
-no_dead_strip_inits_and_terms (32-bit only)
When specified along with -dead_strip cause all constructors and
destructors to never be dead stripped.
The remaining options are infrequently used:
-v Print the version of the linker.
-w (32-bit only)
Suppresses all warning messages.
compiler driver cc(1) to invoke ld, invoke this option in this
way: -Wl,-M.
-whatsloaded (32-bit only)
Display a single line listing each object file that is loaded.
Names of objects in archives have the form libfoo.a(bar.o).
-filelist listfile[,dirname]
Specifies that the linker should link the files listed in list-
file . This is an alternative to listing the files on the com-
mand line. The file names are listed one per line separated only
by newlines. (Spaces and tabs are assumed to be part of the file
name.) If the optional directory name, dirname is specified, it
is prepended to each name in the list file.
-headerpad value
Specifies the minimum amount of space ("padding") following the
headers for the MH_EXECUTE format and all output file types with
the dynamic linker. value is a hexadecimal number. When a seg-
ment's size is rounded up to the segment alignment, there is
extra space left over, which is placed between the headers and
the sections, rather than at the end of the segment. The head-
erpad option specifies the minimum size of this padding, which
can be useful if the headers will be altered later. The default
value is the larger of 2 * sizeof(struct section) so the program
/usr/bin/objcunique can always add two section headers, or if
the output is an MH_EXECUTE filetype and -prebind is specified 3
times the size of the LC_PREBOUND_DYLIB load commands. The
actual amount of pad will be as large as the amount of the first
segment's round-off. (That is, take the total size of the first
segments' headers and non-zerofill sections, round this size up
to the segment alignment, and use the difference between the
rounded and unrounded sizes as the minimum amount of padding.)
-headerpad_max_install_names (32-bit only)
Add to the header padding enough space to allow changing all
dynamic shared library paths recorded in the output file to be
changed to MAXPATHLEN in length.
-t Trace the progress of the link editor; display the name of each
file that is loaded as it is processed in the first and second
pass of the link editor.
-A basefile (32-bit only)
Incremental loading: linking is to be done in a manner that lets
the resulting object be read into an already executing program,
the basefile. basefile is the name of a file whose symbol table
will be taken as a basis on which to define additional symbols.
Only newly linked material will be entered into the a.out file,
but the new symbol table will reflect every symbol defined in
the base file and the newly linked files. Option(s) to specify
the addresses of the segments are typically needed, since the
name of the umbrella framework this subframework is a part of.
Where framework_name is the same as the argument to the -frame-
work framework_name option. This subframework can then only be
linked into the umbrella framework with the same framework_name
or another subframework with the same umbrella framework name.
Any other attempt to statically link this subframework directly
will result in an error stating to link with the umbrella frame-
work instead. When building the umbrella framework that uses
this subframework no additional options are required. However
the install name of the umbrella framework, required to be spec-
ified with -dylib_install_name, must have the proper format for
an install name of a framework for the framework_name of the
umbrella framework to be determined.
-allowable_client client_name (32-bit only)
Specifies that for this subframework the client_name can link
with this subframework without error even though it is not part
of the umbrella framework that this subframework is part of.
The client_name can be another framework name or a name used by
bundles (see the -client_name client_name option below).
-client_name client_name (32-bit only)
Specifies the client_name of a bundle for checking of allowable
clients of subframeworks (see the -allowable_client client_name
option above).
-sub_umbrella framework_name
Specifies that the framework_name being linked by a dynamic
library is to be treated as one of the subframeworks with
respect to twolevel namespace.
-sub_library library_name
Specifies that the library_name being linked by a dynamic
library is to be treated as one of the sublibraries with respect
to twolevel namespace. For example the library_name for
/usr/lib/libobjc_profile.A.dylib would be libobjc.
-init sym
The argument sym is taken to be the symbol name of the dynamic
shared library initialization routine. If any module is used
from the dynamic library the library initialization routine is
called before any symbol is used from the library including C++
static initializers (and #pragma CALL_ON_LOAD routines).
-run_init_lazily (32-bit only)
This option is obsolete.
-dylib_compatibility_version number
For dynamic shared library files, this specifies the compatibil-
ity version number of the library. When a library is used by a
program, the compatibility version is checked and if the pro-
gram's version is greater that the library's version, it is an
The format of number is X[.Y[.Z]] where X must be a positive
non-zero number less than or equal to 65535, and .Y and .Z are
optional and if present must be non-negative numbers less than
or equal to 255. If the version number is not specified, it has
a value of 0. This option is used as the libtool(1) -cur-
rent_version number option when its -dynamic option is set.
-single_module
When building a dynamic library build the library so that it
contains only one module.
-multi_module(32-bitonly)
When building a dynamic library build the library so that it
contains one module for each object file linked in. This is the
default.
-dylinker_install_name name
For dynamic link editor files, specifies the name of the file
the dynamic link editor will be installed in for programs that
use it.
-macosx_version_min version
This overrides the MACOSX_DEPLOYMENT_TARGET environment variable
(see below). Unlike other linker options, this one may be spec-
ified multiple times; only the last occurrence is effective.
The following environment variable is used to control the use of incom-
patible features in the output with respect to Mac OS X releases.
MACOSX_DEPLOYMENT_TARGET
This is set to indicate the oldest Mac OS X version that that
the output is to be used on. When this is set to a release that
is older than the current release features that are incompatible
with that release will be disabled. If a feature is seen in the
input that can't be in the output due to this setting a warning
is issued. The current allowable values for this are 10.1, 10.2
10.3, and 10.4 with the default being 10.4 for the i386 archi-
tecture and 10.1 for all other architectures.
The following environment variables are used by Apple's Build and Inte-
gration team:
LD_TRACE_ARCHIVES
When this is set it causes a message of the form ``[Logging for
XBS] Used static archive: filename'' for each static archive
that has members linked into the output.
LD_TRACE_DYLIBS
When this is set it causes a message of the form ``[Logging for
XBS] Used dynamic library: filename'' for each dynamic library
linked into the output.
specified by this variable instead of stdout.
LD_SPLITSEGS_NEW_LIBRARIES
When set and MACOSX_DEPLOYMENT_TARGET is set to 10.4 or greater
and the output is a dynamic library, and if the install name of
the library is not listed the segment address table, and if the
environment variable LD_UNPREBOUND_LIBRARIES is set with a file
name with a list of library install names and the install name
is not listed, then this is built as a split shared library.
Options available in early versions of the Mach-O link editor may no
longer be supported.
FILES
/lib/lib*.{a,dylib} libraries
/usr/lib/lib*.{a,dylib}
/usr/local/lib/lib*.{a,dylib}
/Library/Frameworks/*.framework/* framework libraries
/Network/Library/Frameworks/*.framework/* framework libraries
/System/Library/Frameworks/*.framework/* framework libraries
a.out output file
SEE ALSO
as(1), ar(1), cc(1), libtool(1), ranlib(1), nm(1), otool(1) lipo(1),
arch(3), dyld(3), Mach-O(5), strip(1), redo_prebinding(1)
Apple Computer, Inc. March 18, 2006 LD(1)
Man(1) output converted with
man2html