ld.1   [plain text]

.TH LD 1 "October 13, 2000" "Apple Computer, Inc."
.SH NAME
ld \- Mach object file link editor
.SH SYNOPSIS
.B ld
[ 
.I "option \&..."
] [ 
.I "file \&..."
] 
.SH DESCRIPTION
The
.I 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 simplest case several object
.I files
are given, and
.I ld
combines them, producing an object file which can either be executed or
become the input for a further
.I ld
run.  (In the latter case, the
.B \-r
option must be given to preserve the relocation information.)  Unless an output 
file is specified, 
.I ld
produces a file named
.BR a.out .
This file is made executable only if no errors occurred during the link editing
and there are no undefined symbols.
.SH "FAT FILE SUPPORT"
The link editor accepts ``fat'' (multiple-architecture) input files, but always
creates a ``thin'' (single-architecture), standard Mach-O output file.
The architecture is specified using the  
.B \-arch 
.I " arch_type"
option.  If this option is not used,
.IR ld (1)
attempts to determine the output architecture by examining the first object 
file encountered 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 ``fat'' file, the ``best'' architecture for the host is used. 
(See the explanation of the 
.B \-arch
option, below.)  
.PP
The compiler driver
.IR cc (1)
handles creating fat executables by calling
.IR ld (1)
multiple times and using
.IR lipo (1)
to create a ``fat'' file from the results of the
.IR ld (1)
executions.
.SH "OUTPUT FILE LAYOUT"
.PP
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.
.PP
Sections created from files with the
.B \-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.
.PP
If the option
.B \-seglinkedit
is specified, the segment it creates is the last segment in the output file.
.PP
The address of each segment can be specified with
.B \-segaddr,
which takes the segment's name as an argument.
The address of the first segment can alternatively be specified using
.B \-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 file.  A segment's address will be assigned
based on the ending address of the previous segment.  
If the address of the
first segment has not been specified by name, 
its assigned address will be
the specified (via
.BR \-seg1addr )
or default first segment address. 
If neither flag is used to specify the first segment's address, its
default address is zero
for all formats except the demand-paged executable format
.SM (MH_EXECUTE),
in which case the default first address is the value of the segment alignment.
.PP
For demand-paged executable format
.SM (MH_EXECUTE)
output files,
if none of the segments' addresses covers address zero through
the value of the segment alignment, a segment with no access protection 
will be created to cover those addresses.  This segment, named
.SM "``_\|_PAGEZERO'',"
is created so that any attempt to dereference a NULL pointer will cause a 
memory exception.
.PP
The entry point of the output file is the beginning of
the first section in the first segment (unless the
.B \-e
option is specified).
.SH STATIC ARCHIVE LIBRARIES
.PP
.I ld
supports two types of libraries: static archive libraries and dynamic shared libraries. Searching for undefined symbols is peformed differently for dynamic shared libraries than it is for static archive libraries. The searching of dynamic shared libraries is described later. 
.PP
When a static archive library is specified as an argument to 
.IR 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 libary's table of contents,
are loaded.  To produce the table of contents, all static archive libraries must be processed by 
.IR ranlib (1).
.PP
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
.B \-s
option to
.IR ranlib (1).
The first member
of the static archive library is named
.SM "``\_\^\_.SYMDEF SORTED'',"
which is understood to be a sorted table of contents.
.PP
If the static archive library does have multiple members that define
the same symbol, the table of contents that 
.IR 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
contents iteratively, loading members until no further references are
satisfied.  In the unsorted case, the first member of the static archive
library is named
.SM "``\_\^\_.SYMDEF'',"
which is understood to be a table of contents in
the order of the archive members.  
.PP
Static archive library members can also be loaded in response to
the
.B \-ObjC
and
.B \-all_load
flags. See their descriptions below.

.SH DYNAMIC SHARED LIBRARIES
.PP
When a dynamic shared library or an object file that was linked against a dynamic shared library is specified as an argument to 
.IR 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 encountered on the command line. All dynamic libraries libraries that the dynamic libraries are dependent upon are added to the end of the search list. 
.PP
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 module that defines the symbol.
With each undefined symbol, the search starts with the first library in the list.
This is different than for static archive libraries, where each library is searched exactly once for all undefined symbols.
.PP
The static link editor simulates dynamic linking as if all the undefined symbols are to be bound at program launch time. The dynamic linker actually binds undefined symbols as they are encountered during execution instead of at program launch. However,  
the static link editor always produces the same linking as the dynamic linker as long as none of the dynamic shared libraries define the
same symbol. Different linking can occur only when there is more than one definition of a symbol and the library modules that contain the definitions for that symbol do not define and reference exactly the same symbols.  
In this case, even 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.
.PP
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.  Searching 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. 

.SH "USING THE DYNAMIC LINK EDITOR AND DYNAMIC SHARED LIBRARIES"
.PP
The option
.B \-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
.B \-static
can be specified.
Only one of these flags can be specified.

.SH "LINK EDITOR DEFINED SYMBOLS"
.PP
There is a group of link editor defined symbols for the
.SM MH_EXECUTE,
.SM MH_DYLIB
and
.SM 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 symbols that are referenced by the object file 
appear in the output file's symbol table.
.PP
The link editor defined symbol `\_\^\_mh_execute_header'
(`\_mh_execute_header' in C) is reserved when the output file format is
.SM MH_EXECUTE.
This symbol is the address of the Mach header in a Mach-O executable (a 
file of type
.SM MH_EXECUTE). 
It does not appear in
any other Mach-O file type.  It can be used to get to the addresses and 
sizes of all the segments and sections in the executable.  This can be done by parsing the headers 
and load commands (see
.IR Mach-O (5)).
.PP
The link editor defined symbol `\_\^\_mh_dylib_header'
(`\_mh_dylib_header' in C) is reserved when the output file format is
.SM MH_DYLIB.
This symbol is the address of the Mach header in a Mach-O dynamic shared library
(a file of type
.SM MH_DYLIB)
and is a private external symbol.
It does not appear in
any other Mach-O file type.  It can be used to get to the addresses and 
sizes of all the segments and sections in a dynamic shared library.  The
addresses, however, must have the value 
.IR _dyld_get_image_vmaddr_slide (3)
added to them.
.PP
The
.SM MH_PRELOAD
file type has link editor defined symbols for the
beginning 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 \_\^\_SEGNAME\_\^\_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.)
.SH OPTIONS
.PP
.I Ld
understands several options.  Filenames and 
options that refer to libraries (such as
.B \-l
and
.BR \-framework ),
as well as options that create symbols (such as
.B \-u
and
.BR \-i ),
are position-dependent: They define the load order and affect what gets
loaded from libraries.
Some
.I ld
options overlap with compiler options.  If the compiler driver
.IR cc (1)
is used to invoke 
.I ld ,
it maybe necessary to pass the
.IR ld (1)
options to
.IR cc (1)
using
.BR \-Wl,\-option,argument1,argument2 .


The most common option is:
.TP 
.BI  \-o " name"
The output file is named
.IR name ,
instead of
.BR a.out .

.PP
The following flags are related to architectures:
.TP
.BI \-arch " arch_type"
Specifies the architecture,
.I arch_type,
for the output file. ``Fat'' input files that do not contain this specified
architecture are ignored.  Only one 
.BI \-arch " arch_type"
can be specified.  See
.IR arch (3)
for the currently known
.IR arch_type s.
If
.I " arch_type"
specifies a certain implementation of an architecture (such as
.BI \-arch " m68040"
or
.BI \-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 
.IR " arch_type" .
.IP
The default output file architecture is determined by the first object file to
be linked.  If it is a ``thin'' (standard Mach-O) file, or a ``fat'' file that 
contains only one architecture, the output file will have the same 
architecture.  Otherwise, if it is a ``fat'' file
containing an architecture that would execute on the host, then the ``best''
architecture is used, as defined by what the kernel exec(2) would select.  
Otherwise, it is an error, and a
.BI \-arch " arch_type"
must be specified.  
.TP
.B \-arch_multiple
This flag is used by the
.IR cc (1)
driver program when it is run with multiple
.BI \-arch " arch_type"
flags.  It instructs programs like
.IR ld (1)
to precede any displayed message with a line stating
the program name, in this case
.IR ld ,
and the architecture (from the
.BI \-arch " arch_type"
flag).  This helps distinguish which architecture the error messages refer to.
.TP
.BI \-force_cpusubtype_ALL
The
.B \-force_cpusubtype_ALL
flag causes the CPU subtype to remain the 
.SM ALL 
CPU subtype and not to be combined or
changed.  This flag has precedence over any
.BI \-arch " arch_type"
flag for a specific implementation.
.PP
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):
.TP
.B \-dynamic
Allows use of the features associated with dynamic link editor.  The default is
.B \-dynamic.
.TP
.B \-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 
.B \-static
are marked with the statement "when 
.B \-dynamic
 is used").
.TP
.BI \-read_only_relocs " treatment"
Specifies how relocation entries in read-only sections are to be treated when
.B \-dynamic
is used.
To get the best possible sharing, the read-only sections should not have any
relocation entries.
If they do, the dynamic linker will write on the section.
Having relocation entries appear in read-only sections is normally avoided by compiling with the option
.B \-dynamic.
But in such cases non-converted assembly code
or objects not compiled with
.B \-dynamic
relocation entries will appear in read-only sections.
The
.I treatment
can be:
.I error,
.I warning,
or
.I 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.
.TP
.B \-prebind
Have the static linker,
.IR ld (1),
prebind an executable's or dynamic shared library's undefined symbols to the
addresses of the dynamic libraries it is being linked with.
This optimization can only be done if the libraries don't overlap and
no symbols 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 normally.
This option can also be specified by setting the environment variable
.SM LD_PREBIND.
.TP
.B \-noprebind
Do not have the static linker,
.IR ld (1),
prebind the output.  If this is specified the environment variable
.SM LD_PREBIND
is ignored.
.PP
The following flags are related to libraries:
.TP 
.BI \-l x
This
option is an abbreviation for the library name
.RI `lib x .a',
where
.I x
is a string.
If 
.B \-dynamic
is specified the abbreviation for the library name is first search as
.RI `lib x .dylib'
and then
.RI `lib x .a'
is searched for.
.I ld
searches for libraries first in any directories
specified with
.B \-L
options, then in the standard directories 
.BR /lib , 
.BR /usr/lib , 
and
.BR "/usr/local/lib" .
A library is searched when its name is encountered,
so the placement of the
.B  \-l
flag is significant.  If string
.I x
is of the form
.IR x .o,
then that file is searched for in the same places, but without prepending
`lib' or appending `.a' or `.dylib' to the filename.
.TP
.BI \-L dir
Add
.I dir
to the list of directories in which to search for libraries.
Directories specified with 
.B \-L
are searched before the standard directories.
.TP
.B \-Z
Do not search the standard directories when searching for libraries.
.TP 
.BI "\-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, 
.I ld
searches for framework `\fIname\fR.framework/\fIname\fR'
first in any directories
specified with the 
.B \-F
option, then in the standard framework directories 
.BR /Library/Frameworks ,
.BR /Network/Library/Frameworks ,
and 
.BR "/System/Library/Frameworks" .
The placement of the 
.B \-framework
option is significant, as it determines 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.
.TP
.BI \-F dir
Add
.I dir
to the list of directories in which to search for frameworks.
Directories specified with 
.B \-F
are searched before the standard framework directories.
.TP
.B \-ObjC
Loads all members of static archive libraries that define an Objective C class or a category. This option does not apply to dynamic shared libraries.
.TP
.B \-all_load
Loads all members of static archive libraries.
This option does not apply to dynamic shared
libraries.
.TP
.BI \-dylib_file " install_name:file_name"
Specifies that a dynamic shared library is in a different location 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 location. 
.I install_name
specifies the path where the library normally resides.
.I 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:
\fB\-dylib_file /lib/libsys_s.A.dylib:/me/lib/libsys_s.A.dylib\fR.

.PP
The following options specify the output file format (the file type):
.TP
.B "\-execute"
Produce a Mach-O demand-paged executable format file.  The headers are placed
in the first segment, and all segments are padded to the segment alignment.
This has a file type of
.SM 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
.SM ``_\|_PAGEZERO''.
This option was previously named
.BR "\-Mach" ,
which will continue to be recognized.
.TP
.B "\-object"
Produce a Mach-O file in the relocatable object file format that is
intended for execution.  This differs from using the
.B \-r
option in that it defines common symbols, does not allow undefined symbols and
does not preserve relocation entries.  This has a file type of
.SM 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
.SM non-MH_EXECUTE
formats, 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 use with the dynamic linker.
.TP
.B "\-preload"
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
.SM MH_PRELOAD.
This option was previously
.BR "\-p" ,
which will continue to be recognized.
.TP
.B "\-dylib"
Produce a Mach-O dynamicly linked shared library format file.  The headers are
placed in the first segment.  All sections are placed in their proper segments
and they are padded to the segment alignment.  This has a file type of
.SM MH_DYLIB.
This option is used by
.IR libtool (1)
when its
.B \-dynamic
option is specified.
.TP
.B "\-bundle"
Produce a Mach-O bundle format file.  The headers are placed in the first
segment.  All sections are placed in their proper segments
and they are padded to the segment alignment.  This has a file type of
.SM MH_BUNDLE.
.TP
.B "\-dylinker"
Produces a Mach-O dynamic link editor format file.  The headers are placed in the
first segment.  All sections are placed in their proper segments, and they are
padded to the segment alignment.  This has a file type of
.SM MH_DYLINKER.
.TP
.B "\-fvmlib"
Produce a Mach-O fixed VM shared library format file.  The headers are placed
in the first segment but the first section in that segment will be placed on
the next segment alignment boundary 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
.SM MH_FVMLIB.

.PP
The following flags affect the contents of the output file:
.TP
.B  \-r
Save the relocation information in the output file
so that it can be the subject of another
.I ld
run.  The resulting file type is a Mach-O relocatable file
.SM (MH_OBJECT)
if not otherwise specified.
This flag also prevents final definitions from being
given to common symbols,
and suppresses the `undefined symbol' diagnostics.
.TP 
.B  \-d
Force definition of common storage even if the
.B \-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
.B \-r
is not specified.

.PP
The following flags support segment specifications:
.TP
.BI "\-segalign" " value"
Specifies the segment alignment.
.I value
is a hexadecimal number that must be an integral power of 2.
The default is the target pagesize (2000 hex currently).
.TP
.BI "\-seg1addr" " addr"
Specifies the starting address of the first segment in the output file.
.I addr
is a hexadecimal number and must be a multiple of the segment alignment.
This option can also be specified as
.B "\-image_base."
.TP
.BI "\-segaddr" " name addr"
Specifies the starting address of the segment named
.I name
to be
.I addr.
The address must be a hexadecimal number that is a multiple of the segment alignment.
.TP
.BI "\-segs_read_only_addr" " addr"
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.
.I addr
is a hexadecimal number and must be a multiple of the segment alignment.
.TP
.BI "\-segs_read_write_addr" " addr"
Specifies the starting address of the read-write segments in a dynamic shared
library.  When this option is used the
.B \-segs_read_only_addr
must also be used (see above).
.I addr
is a hexadecimal number and must be a multiple of the segment alignment.
.TP
.BI "\-seg_addr_table" " filename"
For dynamic shared libraries the 
.B "\-seg1addr"
or the pair of
.B "\-segs_read_only_addr"
and
.B "\-segs_read_write_addr"
are specified by an entry in the segment address table in
.I filename
that matches the install name of the library.
The entries in the table are 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
.B "\-seg1addr".
In the second form the first address is used as the
.B "\-segs_read_only_addr"
address and the second address is used as the
.B "\-segs_read_write_addr"
address.
This option can also be specified by setting the environment variable
.SM LD_SEG_ADDR_TABLE.
If the environment variable is set then any
.BR "\-seg1addr" ,
.BR "\-segs_read_only_addr" ,
.B "\-segs_read_write_addr"
and
.B "\-seg_addr_table"
options are ignored and a warning is printed.
.TP
.BI "\-segprot" " name max init"
Specifies the maximum and initial virtual memory protection of the named
segment,
.I name,
to be
.I max
and
.I init
respectfully.  The values for
.I max
and
.I 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.
The default for the initial protection for all segments is `rw' unless the
segment contains a section which contains some machine insructions, in which
case the default for the initial protection is `rwx'.
The default for the initial protection for the
.SM "``_\|_TEXT''"
segment is `rx' (not writable).
.TP
.B "\-seglinkedit"
Create the link edit segment, named
.SM "``_\|_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 
.SM MH_OBJECT
and
.SM 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
.IR Mach-O (5)).
.TP
.B "\-noseglinkedit"
Do not create the link edit segment (see
.B \-seglinkedit
above).
.TP
.BI "\-pagezero_size" " value"
Specifies the segment size of _\|_PAGEZERO to be of size
.IR value ,
where
.I value 
is a hexadecimal number rounded to the segment alignment.
The default is the target pagesize (currently, 2000 hexadecimal).
.TP
.BI "\-stack_addr" " value"
Specifies the initial address of the stack pointer
.IR value ,
where
.I value 
is a hexadecimal number rounded to the segment alignment.
The default segment alignment is the target pagesize (currently, 2000
hexadecimal).
If
.B \-stack_size
is specified and 
.B \-stack_addr
is not, a default stack address specific for the architecture being linked will
be used and its value printed as a warning message.
This creates a segment named _\|_UNIXSTACK.  Note that the initial stack address
will be either at the high address of the segment or the low address of the
segment depending on which direction the stack grows for the architecture being 
linked.
.TP
.BI "\-stack_size" " value"
Specifies the size of the stack segment
.IR value ,
where
.I value 
is a hexadecimal number rounded to the segment alignment.
The default segment alignment is the target pagesize (currently, 2000
hexadecimal).
If
.B \-stack_addr
is specified and 
.B \-stack_size
is not, a default stack size specific for the architecture being linked will be
used and its value printed as a warning message.
This creates a segment named _\|_UNIXSTACK .

.PP
The following flags support section specifications:
.TP
.BI "\-sectcreate" " segname sectname file"
The section
.I sectname
in the segment
.I segname
is created from the contents of
.I file.
The combination of
.I segname
and 
.I sectname
must be unique; there cannot already be a section 
.I (segname,sectname)
in any input object file.  
This option was previously called
.BR "\-segcreate" ,
which will continue to be recognized.
.TP
.BI "\-sectalign" " segname sectname value"
The section named
.I sectname
in the segment 
.I segname
will have its alignment set to
.IR value ,
where
.I 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 maximum
alignment of the
.SM (_\|_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 specified by a section header in an object file or on the
command line, it defaults to 10 (hex), indicating 16-byte alignment.
.TP
.BI "\-sectorder" " segname sectname orderfile"
The section
.I sectname
in the segment
.I 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
.I orderfile.
These blocks are aligned to the output file's section alignment for this
section.  Any section can be ordered in the output file except symbol pointer and symbol stub sections.  
.IP
For non-literal sections, each line of the
.I orderfile
contains an object name and a symbol name, separated by a single colon (':').  
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 sections, the easiest way to generate an order file is
with the ``\f3\-jonls +\f2segname sectname\f1'' options to
.IR nm (1).
.IP
The format of the
.I orderfile
for literal sections is specific to each type of literal section.  For C
string literal sections, each line of the order file contains one literal C 
string, which may include ANSI C escape sequences.  For four-byte literal
sections, the order file format is one 32-bit hex number with a leading 0x 
per
line, with the rest of the line treated as a comment.  For eight-byte literal
sections, the order file has two 32-bit hex numbers per line; each number 
has a leading 0x, the two numbers are separated by white
space, and the rest of the line is treated as a comment.
For literal pointer sections, the lines in the order file represent
pointers, one per line.  A 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 sections, 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 literal sections, the easiest way to generate an order file is with
the ``\f3\-X \-v \-s \f2segname sectname\f1'' options to
.IR otool (1).
.TP
.B \-sectorder_detail
When using the
.B \-sectorder
option,  any pairs of object file names and symbol names that are found in 
the loaded objects, but not specified in the 
.IR 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 symbols 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
.IR orderfile ,
as well as the number of symbol names listed in the
.I 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
.B \-sectorder_detail
flag.  If an object file-symbol name pair is listed multiple times, a 
warning is generated, and the first occurrence is used.
.TP
.BI "\-sectobjectsymbols" " segname sectname"
This causes the link editor to generate local symbols in the section 
.I sectname
in the segment
.IR 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 archive. 
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
.I (segname,sectname)
in the output file.
This symbol will placed in the symbol table just before all other local symbols
for the object file.  This feature is typically used where the section is
.SM (\_\^\_TEXT,\_\^\_text),
in order to help the debugger debug object files produced by old versions of 
the compiler or by non-Apple compilers.

.PP
The following flags are related to symbols.  These flags' arguments
are external symbols whose names have `_' prepended to the C,
.SM FORTRAN,
or Pascal variable name.
.TP
.BI \-y sym
Display each file in which
.I sym
appears, its type, and whether the file defines or references it.  Any
multiply defined symbols are automatically
traced.  Like most of the other symbol-related flags, 
.B \-y
takes only one argument; the flag may be specified more than once in the
command line to trace more than one symbol.  
.TP
.BI \-Y " number"
For the first 
.I 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 
.B \-y
option). To keep the output manageable, this option displays at most
.I number
references.
.TP
.B \-keep_private_externs
Don't turn private external symbols into static symbols, but rather leave them
as private external in the resulting output file.
.TP
.B \-m
Don't treat multiply defined symbols as a hard error; instead, simply print a 
warning.  The first such symbol is used for linking; its value is used for
the symbol in the symbol table.  The other symbols by the same name may be 
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!
.TP
.B \-whyload
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
.BI \-y sym
flag can help determine exactly why a link edit is failing due to multiply 
defined symbols.
.B
.TP 
.BI  \-u " sym"
Enter the argument
.I 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.
.TP
.BI \-e " sym"
The argument
.I 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.
.TP
.BI \-i definition:indirect
Create an indirect symbol for the symbol name
.I definition
which is defined to be the same as the symbol name
.I indirect
(which is taken to be undefined).  When a definition of the symbol named
.I indirect
is linked, both symbols will take on the defined type and value.
.IP
This option overlaps with a compiler option.
If you use the compiler driver
.IR cc (1)
to invoke \fIld\fR,
invoke this option in this way:
.BI \-Wl,\-i definition:indirect.

.TP
.BI \-undefined " treatment"
Specifies how undefined symbols are to be treated.
.I treatment
can be:
.I error,
.I warning,
or
.I suppress.
Which cause the treatment of undefined symbols as either, errors, warnings, or
suppresses the checking of undefined symbols.
The default is to treat undefined symbols as errors.
.TP
.BI  \-U " sym"
Allow the symbol
.I sym
to be undefined, even if the
.B \-r
flag is not given.  Produce an executable file if the only undefined 
symbols are those specified with
.BR \-U.
.IP
This option overlaps with a compiler option.
If you use the compiler driver
.IR cc (1)
to invoke \fIld\fR,
invoke this option in this way:
.BI \-Wl,\-U, sym.
.TP
.B \-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.

.PP
The following flags are related to stripping link edit information.  
This information can also be removed by
.IR strip (1), 
which uses the same options.  (The
exception is the
.B \-s 
flag below, but this is the same as  
.IR strip (1)
with no arguments.)
The following flags are listed in decreasing level of stripping.
.TP 
.B \-s
Completely strip the output; that is, remove the symbol table
and relocation information.
.TP 
.B \-x
Strips the non-global symbols; only saves external symbols.
.IP
This option overlaps with a compiler option.
If you use the compiler driver
.IR cc (1)
to invoke \fIld\fR,
invoke this option in this way:
.B \-Wl,\-x.
.TP
.B \-S
Strip debugging symbols; only save local and global symbols.
.TP 
.B \-X
Strip local symbols whose names begin with `L'; save all other symbols.
(The compiler and assembler currently strip these internally-generated 
labels by default, so they generally do not appear in object files 
seen by the link editor.)
.TP 
.B \-Si
Strip duplicate debugging symbols from include files.  This is
the default. 
.TP 
.B  \-b
Strip the base file's symbols from the output file.  (The base file 
is given as the argument to the 
.B \-A
option.)
.IP
This option overlaps with a compiler option.
If you use the compiler driver
.IR cc (1)
to invoke \fIld\fR,
invoke this option in this way:
.B \-Wl,\-b.
.TP
.B \-Sn
Don't strip any symbols.

.PP
The remaining options are infrequently used:
.TP
.B \-w
Suppresses all warning messages.
.TP
.B \-no_arch_warnings
Suppresses warning messages about files that have the wrong architecture for the
.B \-arch
flag.
.TP
.B \-arch_errors_fatal
Cause the errors having to do with files that have the wrong architecture to be
fatal and stop the link editor.
.TP
.B \-M
Produce a load map, listing all the segments and sections.  The list 
includes the address where each input file's section appears in the 
output file, as well as the section's size.
.IP
This option overlaps with a compiler option.
If you use the compiler driver
.IR cc (1)
to invoke \fIld\fR, 
invoke this option in this way:
.B \-Wl,\-M.
.TP
.B \-whatsloaded
Display a single line listing each object file that is
loaded.  Names of objects in archives have the form libfoo.a(bar.o).
.TP
.BI \-filelist " listfile[,dirname]"
Specifies that the linker should link the files listed in 
.I listfile .
This is an alternative to listing the files on the command 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,
.I dirname
is specified, it is prepended to each name in the list file.
.TP
.BI "\-headerpad" " value"
Specifies the minimum amount of space ("padding") following 
the headers for the
.SM MH_EXECUTE format.
.I value
is a hexadecimal number.  
When a segment'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
.B headerpad
option specifies the minimum size of this padding, 
which can be useful if the headers will be altered later.
The default value is the 2 * sizeof(struct section) so the program
/usr/bin/objcunique can always add two section headers.
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.)
.TP
.B \-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.
.TP
.BI \-A " basefile"
Incremental loading: linking is to be done in a manner 
that lets the resulting object be read into an already executing 
program, the
.IR basefile .
.I 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
.BR 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 default addresses tend to overlap with the
.I basefile.
The default format of the object file is 
.SM MH_OBJECT.
Note: It is strongly recommended that this option NOT be used, 
because the dyld package described in
.IR dyld (3)
is a much easier alternative.
.TP
.BI \-dylib_install_name " name"
For dynamic shared library files, specifies the name of the file
the library will be installed in for programs that use it.  If this is not
specified, the name specified in the
.BI \-o " name"
option will be used.
This option is used as the 
.IR libtool (1)
.BI \-install_name " name"
option when its
.B \-dynamic
option is specified.
.TP
.BI \-umbrella " framework_name"
Specifies this is a subframework where
.I framework_name
is the name of the umbrella framework this subframework is a part of.  Where
.I framework_name
is the same as the argument to the
.BI \-framework " framework_name"
option.  This subframework can then only be linked into the umbrella framework
with the same
.I framework_name
or another subframework with the same umbrella framework name.  Any other
attempt to staticly link this subframework directly will result in an error
stating to link with the umbrella framework instead.  When building the umbrella
framework that uses this subframework no addtional options are required.
However the install name of the umbrella framework, required to be specified
with
.BR \-dylib_install_name ,
must have the proper format for an install name of a framework for the
.I framework_name
of the umbrella framework to be determined.
.TP
.BI \-allowable_client " client_name"
Specifies that for this subframework the
.I 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
.I client_name
can be another framework name or a name used by bundles (see the
.BI \-client_name " client_name"
option below).
.TP
.BI \-client_name " client_name"
Specifies the
.I client_name
of a bundle for checking of allowable clients of subframeworks (see the
.BI \-allowable_client " client_name"
option above).
.TP
.BI \-sub_umbrella " framework_name"
Specifies that the
.I framework_name
being linked by a dynamic library is to be treated as it one of the
subframeworks with respect to twolevel namespace.
.TP
.BI \-init " sym"
The argument
.I 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_MODULE_BIND routines).
.TP
.BI \-run_init_lazily
Mark the dyanmic library to have its library initialization routine and
module initialization routines run lazily via catching memory faults to its
writeable segments.  The library's initialization routine must not have any
side effects that cause semantic differences as to when its initialization
routine is run.
.TP
.BI \-dylib_compatibility_version " number"
For dynamic shared library files, this specifies the compatibility version number
of the library.  When a library is used by a program, the compatibility version is checked
and if the program's version is greater that the library's version, it is an error.
The format of
.I number
is
.I X[.Y[.Z]]
where
.I X
must be a positive non-zero number less than or equal to 65535, and
.I .Y
and
.I .Z
are optional and if present must be a positive non-zero numbers less than or
equal to 255.
If the compatibility version number is not specified, it has a
value of 0 and no checking is done when the library is used.
This option is used as the
.IR libtool (1)
.BI \-compatibility_version " number"
option 
when its
.B \-dynamic
option is set.
.TP
.BI \-dylib_current_version " number"
For dynamic shared library files, specifies the current version number
of the library.  The current version of the library can be obtained
programmatically by the user of the library so it can determine exactly which version of the library it is using.
The format of
.I number
is
.I X[.Y[.Z]]
where
.I X
must be a positive non-zero number less than or equal to 65535, and
.I .Y
and
.I .Z
are optional and if present must be a positive non-zero 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 
.IR libtool (1)
.BI \-current_version " number"
option when its
.B \-dynamic
option is set.
.TP
.BI \-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.
.PP
The following environment variables are used by Apple's Build and Integration
team:
.TP
.B RC_TRACE_ARCHIVES
When this is set it causes a message of the form ``[Logging for Build &
Integration] Used static archive: 
.I filename''
for each static archive that has members linked into the output.
.TP
.B RC_TRACE_DYLIBS
When this is set it causes a message of the form ``[Logging for Build &
Integration] Used dynamic library: 
.I filename''
for each dynamic library linked into the output.
.TP
.B RC_TRACE_PREBINDING_DISABLED
When this is set it causes a message of the form ``[Logging for Build &
Integration] prebinding disabled for
.I filename
because
.I reason''.
Where
.I filename
is the value of the
.B \-final_output
argument if specified or the value of the
.B \-o
argument.
.TP
.BI \-final_output " filename"
The argument
.I filename
is used in the above message when RC_TRACE_PREBINDING_DISABLED is set.

.PP
Options available in early versions of the Mach-O link editor 
may no longer be supported.  

.SH FILES
.ta \w'/Network/Library/Frameworks/*.framework/*\ \ 'u
/lib/lib*.{a,dylib}	libraries
.br
/usr/lib/lib*.{a,dylib}
.br
/usr/local/lib/lib*.{a,dylib}
.br
/Library/Frameworks/*.framework/*	framework libraries
.br
/Network/Library/Frameworks/*.framework/*	framework libraries
.br
/System/Library/Frameworks/*.framework/*	framework libraries
.br
a.out	output file
.SH "SEE ALSO"
as(1), ar(1), cc(1), libtool(1), ranlib(1), atom(1), nm(1), otool(1) lipo(1), 
arch(3), dyld(3), Mach-O(5), strip(1), redo_prebinding(1)