-.TH LD 1 "March 18, 2006" "Apple Computer, Inc."
-.SH NAME
-ld \- Mach object file link editor
-.SH SYNOPSIS
-.B ld
-[
-.I "option \&..."
-] [
-.I "file \&..."
-]
-.SH DESCRIPTION
+.Dd December 8, 2006
+.Dt ld 1
+.Os Darwin
+.Sh NAME
+.Nm ld
+.Nd "linker"
+.Sh SYNOPSIS
+.Nm
+files...
+.Op options
+.Op Fl o Ar outputfile
+.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 "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
-.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 ``universal'' 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 universal executables by calling
-.IR ld (1)
-multiple times and using
-.IR lipo (1)
-to create a ``universal'' file from the results of the
-.IR ld (1)
-executions.
-.SH "OUTPUT FILE LAYOUT"
-.PP
+.Nm ld
+command combines several object files and libraries, resolves references, and
+produces an ouput file.
+.Nm ld
+can produce a final linked image (executable, dylib, or bundle), or with the -r
+option, produce another object file. If the -o option is not used, the output
+file produced is named "a.out".
+.Ss Universal
+The linker accepts universal (multiple-architecture) input files, but
+always creates a "thin" (single-architecture), standard Mach-O output file.
+The architecture for the output file is specified using the -arch option.
+If this option is not used,
+.Nm ld
+attempts to determine the output architecture by examining the object
+files in command line order. The first "thin"
+architecture determines that of the output file. If no input
+object file is a "thin" file, the native 32-bit architecture for the host is used.
+.Pp
+Usually,
+.Nm ld
+is not used directly. Instead the
+.Xr gcc(1)
+compiler driver invokes
+.Nm ld.
+The compiler driver can be passed multiple -arch options and it will create a
+universal final linked image by invoking
+.Nm ld
+multiple times and then running
+.Xr lipo(1)
+merge the outputs into a universal file.
+.Ss 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.
-.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 performed 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 library'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. When linking -flat_namespace, all dynamic 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 TWO-LEVEL AND FLAT NAMESPACES
-.PP
-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 program 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).
-.PP
-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 definition (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.
-.PP
-When creating an output file with the static link editor when
-.B \-twolevel_namespace
-is in effect (now the default) all undefined references must be satisfied at
-static link time. The flags to allow undefined references,
-.BI \-U symbol_name,
-.BI \-undefined " warning"
-and
-.BI \-undefined " suppress"
-can't be used.
-When the environment variable
-.B MACOSX_DEPLOYMENT_TARGET
-is set to
-.B 10.3
-or higher then
-.BI \-undefined " dynamic_lookup"
-can also be used. The specific library definition recorded
-for each reference 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 at execution time the
-dynamic linker will search that umbrella framework's sub-frameworks,
-sub-umbrellas and sub-libraries for those references.
-Also when two-level namespace is in effect only those frameworks listed on the
-link line (and sub-frameworks, sub-umbrellas and sub-libraries of umbrella
-frameworks) are searched. Other dependent libraries which are not
-sub-frameworks, sub-umbrellas or sub-libraries of umbrella frameworks are not
-searched.
-.RS
-.PP
-When creating bundles (MH_BUNDLE outputs) with the static link editor when
-two-level namespace is in effect (now the default) and the bundle has
-references to symbols
-expected to be defined in the program loading the bundle, then the
-.BI \-bundle_loader " executable"
-must be used.
-.PP
-When creating a output file with the static link editor when
-.B \-flat_namespace
-is in effect (the MacOS X 10.0 default) all undefined references must be
-satisfied at static link time when
-.BI \-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 undefined 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.
-
-.SH MULTIPLY DEFINED SYMBOLS
-.PP
-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.
-.PP
-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.
-.PP
-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
-.B \-multiply_defined
-flag.
-.PP
-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 generates a multiply defined
-symbol warning (by default), where the treatment of this warning can be changed
-with the
-.B \-multiply_defined
-flag.
-
-.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 .
-
-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 command line options are recognized by this tool.
-The options not currently support for building 64-bit binaries are flagged
-.BR "(32-bit only)" .
-
-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. ``Universal'' 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 ``universal'' file
-that contains only one architecture, the output file will have the same
-architecture. Otherwise, if it is a ``universal'' 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
-.B \-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.
-This is the default for all x86 architectures.
-.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
-.BI \-sect_diff_relocs " treatment"
-Specifies how section difference relocation enries are to be treated when
-.B \-dynamic
-and
-.B \-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 section difference
-relocation entries. The
-.IR gcc (1)
-compiler has the
-.B \-mdynamic-no-pic
-flag for generating code for executables. The default treatment is
-.I suppress,
-where no message is printed. The other treatments are
-.I error
-or
-.I warning.
-This option can also be specified by setting the environment variable
-.SM LD_SECT_DIFF_RELOCS
-to the treatment values.
-.TP
-.BI \-weak_reference_mismatches " treatment"
-Specifies how to treat mismatches of symbol references in the the object files
-being linked. Normally the all the undefined symbol references of the object
-files being linked should be consistent for each undefined symbol. That is all
-undefined symbols should either be weak or non-weak references. The default
-treatment is
-.I error,
-where the link fails with an error message. The other treatments are
-.I weak
-or
-.I non-weak,
-which makes mismatched undefined symbol references either weak or non-weak
-in the output, respectively. Care must be taken when using the treatment
-.I weak
-as the use of the non-weak symbol references in an object file may cause the
-program to crash when the symbol is not present at execution time.
-.TP
-.B \-prebind (32-bit only)
-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.
-If the environment variable
-.SM LD_FORCE_NO_PREBIND
-is set both the option
-.B \-prebind
-.SM LD_PREBIND
-environment variable are ignore and the output is not prebound.
-Or if the environment variable
-.B 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.
-.TP
-.B \-noprebind (32-bit only)
-Do not have the static linker,
-.IR ld (1),
-prebind the output. If this is specified the environment variable
-.SM LD_PREBIND
-is ignored.
-.TP
-.B \-prebind_allow_overlap (32-bit only)
-Have the static linker,
-.IR ld (1),
-prebind the output even if the addresses of the dynamic libraries it uses
-overlap. The resulting output can then have
-.IR 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
-environment variable
-.SM LD_PREBIND_ALLOW_OVERLAP.
-.TP
-.B \-prebind_all_twolevel_modules (32-bit only)
-Have the static linker,
-.IR 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
-.SM LD_PREBIND_ALL_TWOLEVEL_MODULES.
-.TP
-.B \-noprebind_all_twolevel_modules (32-bit only)
-Don't have the static linker,
-.IR ld (1),
-mark all modules from prebound two-level namespace dynamic libraries as used
-by the program. This flag overrides the setting of the
-environment variable
-.SM LD_PREBIND_ALL_TWOLEVEL_MODULES.
-.TP
-.B \-nofixprebinding (32-bit only)
-Have the static linker,
-.IR 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.
-.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 any directories specified in the colon separated set of paths
-in the environment variable LD_LIBRARY_PATH, then 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 \-weak-l x
-This is the same as the
-.BI \-l x
-but 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.
-.TP
-.BI \-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.
-.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 "\-syslibroot " rootdir " (32-bit only)"
-Prepend
-.I rootdir
-to the standard directories when searching for libraries or frameworks.
-.TP
-.B \-search_paths_first
-By default when the
-.B \-dynamic
-flag is in effect, the
-.BI \-l x
-and
-.BI \-weak-l x
-options first search for a file of the form
-.RI `lib x .dylib'
-in each directory in the library search path, then a file of the form
-.RI `lib x .a'
-is searched for in the library search paths.
-This option changes it so that in each path
-.RI `lib x .dylib'
-is searched for then
-.RI `lib x .a'
-before the next path in the library search path is searched.
-.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 "\-weak_framework " name[,suffix]
-This is the same as the
-.BI "\-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.
-.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
+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 be laid out at after
+sections from .o files. The use of the -order_file option will alter the layout
+rules above, and move the symbols specified to start of their section.
+.Ss Libraries
+A static library (aka static archive) is a collection of .o files with a table of contents
+that lists the global symbols in the .o files.
+.Nm ld
+will only pull .o files out of a static library if needed to resolve some symbol reference.
+Unlike traditional linkers,
+.Nm ld
+will continually search a static library while linking. There is no need to specify a static
+library multiple times on the command line.
+.Pp
+A dynamic library (aka dylib or framework) is a final linked image. Putting a dynamic
+library on the command line causes two things: 1) The generated final linked image
+will have encoded that it depends on that dynamic library. 2) Exported symbols from the
+dynamic library are used to resolve references.
+.Pp
+Both dynamic and static libraries are searched as they appear on the command line.
+.Ss Search paths
+.Nm ld
+maintains a list of directories to search for a library or framework to use. The default
+library search path is /usr/lib then /usr/local/lib. The -L option will add a new library search
+path. The default framework search path is /Library/Frameworks then /System/Library/Frameworks.
+The -F option will a new framework search path. The -Z option will remove
+the standard search paths. The -syslibroot option will prepend a prefix to all search
+paths.
+.Ss Two-level namespace
+By default all references resolved to a dynamic library record the library to which
+they were resolved. At runtime, dyld uses that information to directly resolve
+symobls. The alternative is to use the -flat_namespace option. With flat namespace,
+the library is not recorded. At runtime, dyld will search each dynamic library in load
+order when resolving symbols. This is slower, but more like how other operating systems
+resolve symbols.
+.Ss Indirect dynamic libraries
+If the command line specifies to link against dylib A, and when dylib A was built it linked
+against dylib B, then B is considered an indirect dylib.
+When linking for two-level namespace, ld does not look at indirect dylibs, except when
+re-exported by a direct dylibs. On the other hand when linking for flat namespace,
+ld does load all indirect dylibs and uses them to resolve references.
+Even though indirect dylibs are specified via a full path,
+.Nm ld
+first uses the specified search paths to locate each indirect dylib. If one cannot
+be found using the search paths, the full path is used.
+.Ss Dynamic libraries undefines
+When linking for two-level namespace,
+.Nm ld
+does not verify that undefines in dylibs actually
+exist. But when linking for flat namespace,
+.Nm ld
+does check that all undefines from all loaded dylibs have a matching definition.
+This is sometimes used to force selected functions to be loaded from a static library.
+.Sh OPTIONS
+.Ss Options that control the kind of output
+.Bl -tag
+.It Fl execute
+The default. Produce a mach-o main executable that has file type MH_EXECUTE.
+.It Fl dylib
+Produce a mach-o shared library that has file type MH_DYLIB.
+.It Fl bundle
+Produce a mach-o bundle that has file type MH_BUNDLE.
+.It Fl r
+Merges object files to produce another mach-o object file with file type MH_OBJECT.
+.It Fl dylinker
+Produce a mach-o dylinker that has file type MH_DYLINKER. Only used when building dyld.
+.It Fl dynamic
+The default. Implied by -dynamiclib, -bundle, or -execute
+.It Fl static
+Produces a mach-o file that does not use the dyld. Only used building the kernel.
+.It Fl arch Ar arch_name
+Specifies which architecture (e.g. ppc, ppc64, i386, x86_64) the output file should be.
+.It Fl o Ar path
+Specifies the name and location of the output file. If not specified, `a.out' is used.
+.El
+.Ss Options that control libraries
+.Bl -tag
+.It Fl l Ns x
+This option tells the linker to search for libx.dylib or libx.a in the library search path.
+If string x is of the form y.o, then that file is searched for in the same places, but without
+prepending `lib' or appending `.a' or `.dylib' to the filename.
+.It Fl weak-l Ns Ar x
+This is the same as the -lx but forces the library and all references to it to be marked as weak imports.
+That is, the library is allowed to be missing at runtime.
+.It Fl weak_library Ar 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.
+.It Fl reexport-l Ns Ar x
+This is the same as the -lx but specifies that the all symbols in library x should be available to
+clients linking to the library being created. This was previously done with a separate -sub_library option.
+.It Fl reexport_library Ar path_to_library
+This is the same as listing a file name path to a library on the link line and it specifies that the
+all symbols in library path should be available to clients linking to the library being created.
+This was previously done with a separate -sub_library option.
+.It Fl L Ns dir
+Add
+.Ar dir
+to the list of directories in which to search for libraries.
+Directories specified with -L are searched in the order they appear on the command line
+and before the default search path.
+.It Fl Z
+Do not search the standard directories when searching for libraries and frameworks.
+.It Fl syslibroot Ar rootdir
+Prepend
+.Ar rootdir
+to all search paths when searching for libraries or frameworks.
+.It Fl search_paths_first
+By default 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.
+.It Fl framework Ar name[,suffix]
+This option tells the linker to search for `name.framework/name' the framework search path.
+If the optional suffix is specified the framework is first searched for the name with the suffix and then without
+(e.g. look for `name.framework/name_suffix' first).
+.It Fl weak_framework Ar 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.
+.It Fl reexport_framework Ar name[,suffix]
+This is the same as the -framework name[,suffix] but also specifies that the
+all symbols in that framework should be available to clients linking to the library being created.
+This was previously done with a separate -sub_umbrella option.
+.It Fl F Ns dir
+Add
+.Ar dir
+to the list of directories in which to search for frameworks.
+Directories specified with -F are searched in the order they appear on the command line
+and before the default search path.
+.It Fl 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" (32-bit only)
-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.
-.TP
-.BI \-executable_path " path_name" (32-bit only)
-Specifies that
-.I path_name
-is used to replace
-.I @executable_path
-for dependent libraries.
-
-.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 (32-bit only)
-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 used with the dynamic
-linker.
-.TP
-.B \-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
-.SM MH_PRELOAD.
-This option was previously
-.BR "\-p" ,
-which will continue to be recognized.
-.TP
-.B "\-dylib"
-Produce a Mach-O dynamically 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 (32-bit only)
-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 (32-bit only)
-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" " (32-bit only)"
-Specifies the segment alignment.
-.I 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).
-.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" " (32-bit only)"
-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" " (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.
-.I addr
-is a hexadecimal number and must be a multiple of the segment alignment.
-.TP
-.BI "\-segs_read_write_addr" " addr" " (32-bit only)"
-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" " (32-bit only)"
-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 "\-seg_addr_table_filename" " pathname" " (32-bit only)"
-Use
-.B pathname
-instead of the install name of the library for matching an entry in the segment
-address table.
-.TP
-.BI "\-segprot" " name max init" " (32-bit only)"
-Specifies the maximum and initial virtual memory protection of the named
-segment,
-.I name,
-to be
-.I max
-and
-.I init
-,respectively. 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 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
-.SM "``_\|_TEXT''"
-segment is `rx' (not writable).
-.TP
-.B \-seglinkedit (32-bit only)
-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 (32-bit only)
-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, 1000 hexadecimal for the PowerPC
-and for i386).
-.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, 1000
-hexadecimal for the PowerPC and for i386).
-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, 1000
-hexadecimal for the PowerPC and for i386).
-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 .
-.TP
-.B \-allow_stack_execute
-Marks executable so that all stacks in the task will be given stack execution
-privilege. This includes pthread stacks.
-
-.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" (32-bit only)
-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 (':').
-Lines that start with # are ignored and treated as comments.
-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 (32-bit only)
-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" " (32-bit only)"
-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 be 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 name spaces:
-.TP
-.B \-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
-.SM LD_TWOLEVEL_NAMESPACE.
-This is the default.
-.TP
-.B \-flat_namespace
-Specifies the output to be built as a flat namespace image.
-This is not the default (but was the default in MacOS X 10.0).
-.TP
-.B \-force_flat_namespace
-Specifies the executable output to be built and executed treating all its
-dynamic libraries as flat namespace images. This marks the executable so that
-the dynamic link editor treats all dynamic libraries as flat namespace
-images when the program is executed.
-.TP
-.BI \-bundle_loader " executable" " (32-bit only)"
-This specifies the
-.I executable
-that will be loading the bundle output file being linked. Undefined symbols
-from the bundle are checked against the specified executable like it was one of
-the dynamic libraries the bundle was linked with. If the bundle being created
-with
-.B \-twolevel_namespace
-in effect then the searching of the executable for
-symbols is based on the placement of the
-.B \-bundle_loader
-flag relative to the dynamic libraries. If the the bundle being created with
-.B \-flat_namespace
-then the searching of the executable is done before all dynamic libraries.
-.TP
-.B \-private_bundle (32-bit only)
-This allows symbols defined in the output to also be defined in executable in
-the
-.B \-bundle_loader
-argument
-when
-.B \-flat_namespace
-is in effect.
-This implies that the bundle output file being created is going to be loaded by
-the executable with the
-.B NSLINKMODULE_OPTION_PRIVATE
-option to
-.IR NSLinkModule (3).
-.TP
-.B \-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
-.B \-bundle
-flag is specified. If this is used when the
-.B \-bundle
-flag is specified the bundle will fail to load on a MacOS X 10.0 system with a
-malformed object error.
-.TP
-.BI \-multiply_defined " treatment" " (32-bit only)"
-Specifies how multiply defined symbols in dynamic libraries when
-.B \-twolevel_namespace
-is in effect are to be treated.
-.I treatment
-can be:
-.I error,
-.I warning,
-or
-.I 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
-.B \-twolevel_namespace
-is in effect.
-The default is to treat multiply defined symbols in dynamic libraries as
-warnings when
-.B \-twolevel_namespace
-is in effect.
-.TP
-.BI \-multiply_defined_unused " treatment" " (32-bit only)"
-Specifies how unused multiply defined symbols in dynamic libraries when
-.B \-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
-output.
-.I treatment
-can be:
-.I error,
-.I warning,
-or
-.I suppress.
-The default for unused multiply defined symbols is to suppress these messages.
-.TP
-.B -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
-.BI \-multiply_defined " error".
-
-.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 " (32-bit only)"
-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" " (32-bit only)"
-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 (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
-symbols 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!
-.TP
-.B \-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
-.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 " (32-bit only)"
-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.
-When the environment variable
-.B MACOSX_DEPLOYMENT_TARGET
-is set to
-.B 10.3
-or higher then
-.BI \-undefined " dynamic_lookup"
-can also be used to allow any undefined symbols to be looked up dynamically at
-runtime. Use of a binary built with this flag requires a system with a dynamic
-linker from Mac OS X 10.3 or later.
-The flag
-.BI \-undefined " define_a_way"
-can also be used to cause the static linker to create a private definition for
-all undefined symbols. This flag should only be used if it is known that the
-undefined symbols are not referenced as any use of them may cause a crash.
-.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.
-.TP
-.BI \-commons " treatment" " (64-bit only)"
-Specifies how common symbols (tentative defintions) from object files interact with dynamic libraries.
-.I treatment
-can be:
-.I ignore_dylibs,
-.I use_dylibs,
-or
-.I 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 tentative definition (e.g. change
-.I int foo;
-to
-.I 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.
-.TP
-.B \-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.
-
-.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 (32-bit only)
-Completely strip the output; that is, remove the symbol table
-and relocation information.
-.TP
-.B \-x (32-bit only)
-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 (32-bit only)
-Strip debugging symbols; only save local and global symbols.
-.TP
-.B \-X (32-bit only)
-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 \-Sp
-Strip, edit and add debugging symbols so the debugger can used most of the
-debugging symbols from the object files.
-.TP
-.B \-Si (32-bit only)
-Strip duplicate debugging symbols from include files. This is
-the default.
-.TP
-.B \-b (32-bit only)
-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 (32-bit only)
-Don't strip any symbols.
-.TP
-.BI \-exported_symbols_list " filename"
-The specified
-.I 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
-.I __private_extern__
-and will not be global in the output file. The symbol names listed in
-.I 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.
-.TP
-.BI \-unexported_symbols_list " filename"
-The specified
-.I 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
-.I __private_extern__
-and will not be global in the output file. The symbol names listed in
-.I 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.
-.TP
-.BI \-no_uuid
-Do not emit an LC_UUID load command in the linked output file.
-
-.TP
-.B -dead_strip (32-bit only)
-Remove blocks of code and data that are unreachable by the entry point or
-exported symbols.
-.TP
-.B -no_dead_strip_inits_and_terms (32-bit only)
-When specified along with
-.B -dead_strip
-cause all constructors and destructors to never be dead stripped.
-
-.PP
-The remaining options are infrequently used:
-.TP
-.B \-v
-Print the version of the linker.
-.TP
-.B \-w (32-bit only)
-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 (32-bit only)
-Cause the errors having to do with files that have the wrong architecture to be
-fatal and stop the link editor.
-.TP
-.B \-M (32-bit only)
-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 (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).
-.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
+.It Fl ObjC
+Loads all members of static archive libraries that implement an Objective-C class or category.
+.El
+.Ss Options that control additional content
+.Bl -tag
+.It Fl sectcreate Ar segname sectname file
+The section
+.Ar sectname
+in the segment
+.Ar segname
+is created from the contents of file
+.Ar file.
+The combination of segname and sectname must be unique Ð there cannot already be a section (segname,sectname)
+from any other input.
+.It Fl filelist Ar file[,dirname]
+Specifies that the linker should link the files listed in
+.Ar file .
+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,
+.Ar 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 and all output file types with the dynamic linker.
-.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 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
-.B \-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.)
-.TP
-.B \-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.
-.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" " (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
-.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 statically 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 additional 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" " (32-bit only)"
-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" " (32-bit only)"
-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 one of the
-subframeworks with respect to twolevel namespace.
-.TP
-.BI \-sub_library " library_name"
-Specifies that the
-.I 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
-.I library_name
-for
-.I /usr/lib/libobjc_profile.A.dylib
-would be
-.I libobjc.
-.TP
-.BI \-init " sym"
+.It Fl dtrace Ar file
+Enables dtrace static probes when producing a final linked image. The file
+.Ar file
+must be a DTrace script which declares the static probes.
+.El
+.Ss Options that control optimizations
+.Bl -tag
+.It Fl dead_strip
+Remove functions and data that are unreachable by the entry point or exported symbols.
+.It Fl dead_strip_dylibs
+Remove dylibs that are unreachable by the entry point or exported symbols. That is,
+suppresses the generation of load command commands for dylibs which supplied no
+symbols during the link. This option should not be used when linking against a dylib which
+is required at runtime for some indirect reason such as the dylib has an important initializer.
+.It Fl order_file Ar file
+Alters the order in which functions and data are laid out. For each section in the output file,
+any symbol in that section that are specified in the order file
+.Ar file
+is moved to the start of its section and laid out in the same order as in the order file
+.Ar file .
+Order files are text files with one symbol name per line. Lines starting with a # are comments.
+A symbol name may be optionally preceded with its object file leafname and a colon (e.g. foo.o:_foo).
+This is useful for static functions/data that occur in multiple files.
+A symbol name may also be optionally preceded with the architecture (e.g. ppc:_foo or ppc:foo.o:_foo).
+This enables you to have one order file that works for multiple architectures.
+Literal c-strings may be ordered by by quoting the string (e.g. "Hello, world\\n") in the order file.
+.It Fl macosx_version_min Ar version
+This is set to indicate the oldest Mac OS X version that that the output is to be used on. Specifying
+a later version enables the linker to assumes features of that OS in the output file. The format of
+.Ar version
+is a Mac OS X version number such as 10.4 or 10.5
+.It Fl image_base Ar address
+Specifies the perferred load address for a dylib or bundle. The argument
+.Ar address
+is a hexadecimal number with an optional leading 0x. By choosing non-overlapping address for all
+dylibs and bundles that a program loads, launch time can be improved because dyld will not need to
+"rebase" the image (that is, adjust pointers within the image to work at the loaded address).
+It is often easier to not use this option, but instead use the rebase(1) tool, and give it a list of dylibs.
+It will then choose non-overlapping addresses for the list and rebase them all.
+This option is also called -seg1addr for compatibility.
+.El
+.Ss Options when creating a dynamic library (dylib)
+.Bl -tag
+.It Fl install_name Ar name
+Sets an internal "install path" (LC_ID_DYLIB) in a dynamic library. Any clients linked against the library
+will record that path as the way dyld should locate this library. If this option is not specified, then
+the -o path will be used. This option is also called -dylib_install_name for compatibility.
+.It Fl compatibility_version Ar number
+Specifies the compatibility version number of the library. When a library is loaded by dyld, 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
+.Ar 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 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 also called -dylib_compatibility_version for compatibility.
+.It Fl current_version Ar number
+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
+.Ar 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 also called -dylib_current_version for compatibility.
+.El
+.Ss Options when creating a main executable
+.Bl -tag
+.It Fl pie
+This makes a special kind of main executable that is position independent (PIE). On Mac OS X 10.5, the OS
+will load a PIE at a random address each time it is executed. You cannot create a PIE from .o files compiled
+with -mdynamic-no-pic. That means the codegen is less optimal, but the address randomization adds some
+security.
+.It Fl pagezero_size Ar size
+By default the linker creates an unreadable segment starting at address zero named __PAGEZERO. Its existence
+will cause a bus error if a NULL pointer is dereferenced. The argument
+.Ar size
+is a hexadecimal number with an optional leading 0x. If
+.Ar size
+is zero, the linker will not generate a page zero segment. By default on 32-bit architectures the page zero size
+is 4KB. On 64-bit architectures, the default size if 4GB. The ppc64 architecture has some special cases. Since Mac
+OS X 10.4 did not support 4GB page zero programs, the default page zero size for ppc64 will be 4KB unless
+-macosx_version_min is 10.5 or later. Also, the -mdynamic-no-pic codegen model for ppc64 will only work if the
+code is placed in the lower 2GB of the address space, so the if the linker detects any such code, the page zero
+size is set to 4KB and then a new unredable trailing segment is created after the code, filling up the lower 4GB.
+.It Fl stack_size Ar size
+Specifies the maximum stack size for the main thread in a program. Without this option a program has a 8MB stack.
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_LOAD routines).
-.TP
-.B \-run_init_lazily (32-bit only)
+.Ar size
+is a hexadecimal number with an optional leading 0x. The
+.Ar size
+should be an even multiple of 4KB, that is the last three hexadecimal digits should be zero.
+.It Fl allow_stack_execute
+Marks executable so that all stacks in the task will be given stack execution privilege. This includes pthread stacks.
+.El
+.Ss Options when creating a bundle
+.Bl -tag
+.It Fl bundle_loader Ar executable
+This specifies the
+.Ar executable
+that will be loading the bundle output file being linked.
+Undefined symbols from the bundle are checked against the specified
+.Ar executable
+like it was one of the
+dynamic libraries the bundle was linked with.
+.El
+.Ss Options when creating an object file
+.Bl -tag
+.It Fl keep_private_externs
+Don't turn private external (aka visibility=hidden) symbols into static symbols,
+but rather leave them as private external in the resulting object file.
+.It Fl d
+Force definition of common symbols. That is, transform tentative defintions into real definitions.
+.El
+.Ss Options that control symbol resolution
+.Bl -tag
+.It Fl exported_symbols_list Ar filename
+The specified
+.Ar filename
+contains a list 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__ (aka visibility=hidden)
+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.
+Some wildcards (similar to shell file matching) are supported. The * matches zero or more characters.
+The ? matches one character. [abc] matches one character which must be an 'a', 'b', or 'c'. [a-z] matches
+any single lower case letter from 'a' to 'z'.
+.It Fl exported_symbol Ar symbol
+The specified
+.Ar symbol
+is added to the list of global symbols names that will remain as global symbols in the output file. This
+option can be used multiple times. For short lists, this can be more convenient than creating a file and using
+-exported_symbols_list.
+.It Fl unexported_symbols_list Ar file
+The specified
+.Ar filename
+contains a list 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 __private_extern__ (aka visibility=hidden) 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.
+Some wildcards (similar to shell file matching) are supported. The * matches zero or more characters.
+The ? matches one character. [abc] matches one character which must be an 'a', 'b', or 'c'. [a-z] matches
+any single lower case letter from 'a' to 'z'.
+.It Fl unexported_symbol Ar symbol
+The specified
+.Ar symbol
+is added to the list of global symbols names that will not remain as global symbols in the output file. This
+option can be used multiple times. For short lists, this can be more convenient than creating a file and using
+-unexported_symbols_list.
+.It Fl alias Ar symbol_name Ar alternate_symbol_name
+Create an alias named
+.Ar alternate_symbol_name
+for the symbol
+.Ar symbol_name .
+By default the alias symbol has global visibility. This option was previous the -idef:indir option.
+.It Fl alias_list Ar filename
+The specified
+.Ar filename
+contains a list of aliases. The symbol name and its alias are on one line, separated by whitespace.
+Lines starting with # are ignored.
+.It Fl flat_namespace
+Alters how symbols are resolved at build time and runtime. With -two_levelnamespace (the default), the linker
+only searches dylibs on the command line for symbols, and records in which dylib they were found. With -flat_namespace,
+the linker searches all dylibs on the command line and all dylibs those original dylibs depend on. The linker
+does not record which dylib an external symbol came from, so at runtime dyld again searches all images and uses
+the first definition it finds. In addition, any undefines in loaded flat_namespace dylibs must be resolvable
+at build time.
+.It Fl u Ar symbol_name
+Specified that symbol
+.Ar symbol_name
+must be defined for the link to succeed. This is useful to force selected functions to be loaded
+from a static library.
+.It Fl U Ar symbol_name
+Specified that it is ok for
+.Ar symbol_name
+to have no definition. With -two_levelnamespace, the resulting symbol will be marked dynamic_lookup which
+means dyld will search all loaded images.
+.It Fl undefined Ar treatment
+Specifies how undefined symbols are to be treated. Options are: error, warning, suppress, or dynamic_lookup. The
+default is error.
+.It Fl rpath Ar path
+Add
+.Ar path
+to the runpath search path list for image being created. At runtime, dyld uses the runpath when searching
+for dylibs whose load path begins with @rpath/.
+.El
+.Ss Options for introspecting the linker
+.Bl -tag
+.It Fl why_load
+Log why each object file in a static library is loaded. That is, what symbol was needed. Also called -whyload
+for compatibility.
+.It Fl why_live Ar symbol_name
+Logs a chain of references to
+.Ar symbol_name .
+Only applicable with -dead_strip .
+It can help debug why something that you think should be dead strip removed is not removed.
+.It Fl print_statistics
+Logs information about the amount of memory and time the linker used.
+.It Fl t
+Logs each file (object, archive, or dylib) the linker loads. Useful for debugging problems with search paths where the wrong library is loaded.
+.It Fl whatsloaded
+Logs just object files the linker loads.
+.It Fl order_file_statistics
+Logs information about the processing of a -order_file.
+.It Fl map Ar map_file_path
+Writes a map file to the specified path which details all symbols and their addresses in the output image.
+.El
+.Ss Options for controling symbol table optimizations
+.Bl -tag
+.It Fl S
+Do not put debug information (STABS or DWARF) in the output file.
+.It Fl x
+Do not put non-global symbols in the output file's symbol table. Non-global symbols are useful when debugging and
+getting symbol names in back traces, but are not used at runtime.
+.It Fl non_global_symbols_strip_list Ar filename
+The specified
+.Ar filename
+contains a list of non-global symbol names that should be removed from the output file's symbol table. All other
+non-global symbol names will remain in the output files symbol table. See -exported_symbols_list for syntax and use
+of wildcards.
+.It Fl non_global_symbols_no_strip_list Ar filename
+The specified
+.Ar filename
+contains a list of non-global symbol names that should be remain in the output file's symbol table. All other
+symbol names will be removed from the output file's symbol table. See -exported_symbols_list for syntax and use
+of wildcards.
+.El
+.Ss Rarely used Options
+.Bl -tag
+.It Fl v
+Prints the version of the linker.
+.It Fl no_uuid
+Do not generate an LC_UUID load command in the output file.
+.It Fl root_safe
+Sets the MH_ROOT_SAFE bit in the mach header of the output file.
+.It Fl setuid_safe
+Sets the MH_SETUID_SAFE bit in the mach header of the output file.
+.It Fl interposable
+Indirects access to all to exported symbols when creating a dynamic library.
+.It Fl init Ar symbol_name
+The specified symbol_name will be run as the first initializer. Only used when creating a dynamic library.
+.It Fl sub_library Ar library_name
+The specified dylib will be re-exported. For example the library_name for /usr/lib/libobjc_profile.A.dylib would be libobjc.
+Only used when creating a dynamic library.
+.It Fl sub_umbrella Ar framework_name
+The specified framework will be re-exported. Only used when creating a dynamic library.
+.It Fl allowable_client Ar name
+Restricts what can link against the dynamic library being created.
+.It Fl client_name Ar name
+Enables a bundle to link against a dylib that was built with -allowable_client.
+The name specified must match one of the -allowable_client names specified when the dylib was created.
+.It Fl umbrella Ar framework_name
+Specifies that the dylib being linked is re-exported through an umbrella framework of the specified name.
+.It Fl headerpad Ar size
+Specifies the minimum space for future expansion of the load commands. Only useful if intend to run
+install_name_tool to alter the load commands later. Size is a hexadecimal number.
+.It Fl headerpad_max_install_names
+Automatically adds space for future expansion of load commands such that all paths could expand to MAXPATHLEN.
+Only useful if intend to run install_name_tool to alter the load commands later. Size is a hexadecimal number.
+.It Fl bind_at_load
+Sets a bit in the mach header of the resulting binary which tells dyld to bind all symbols when the binary is loaded, rather than lazily.
+.It Fl force_flat_namespace
+Sets a bit in the mach header of the resulting binary which tells dyld to not only use flat namespace for the binary,
+but force flat namespace binding on all dylibs and bundles loaded in the process. Can only be used when linking main executables.
+.It Fl sectalign Ar segname Ar sectname Ar 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.
+.It Fl stack_addr Ar address
+Specifies the initial address of the stack pointer value, where value is a hexadecimal number rounded to a page boundary.
+.It Fl segprot Ar segname Ar max_prot Ar init_prot
+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).
+.It Fl seg_addr_table Ar filename
+Specifies a file containing base addresses for dynamic libraries. Each line of the file is a hexadecimal base address
+followed by whitespace then the install name of the corresponding dylib. The # character denotes a comment.
+.It Fl segs_read_write_addr Ar address
+Allows a dynamic library to be built where the read-only and read-write segments are not contiguous. The address
+specified is a hexadecimal number that indicates the base address for the read-write segments.
+.It Fl segs_read_only_addr Ar address
+Allows a dynamic library to be built where the read-only and read-write segments are not contiguous. The address
+specified is a hexadecimal number that indicates the base address for the read-only segments.
+.It Fl segaddr Ar name Ar address
+Specifies the starting address of the segment named name to be address. The address must be a hexadecimal number
+that is a multiple of 4K page size.
+.It Fl dylib_file Ar 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. install_name specifies the path where the library normally 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.
+.It Fl prebind
+The created output file will be in the prebound format. This was used in Mac OS X 10.3 and earlier to improve launch performance.
+.It Fl weak_reference_mismatches Ar treatment
+Specifies what to do if a symbol is weak-imported in one object file but not weak-imported in another. The valid
+treatments are: error, weak, or non-weak. The default is non-weak.
+.It Fl read_only_relocs Ar treatment
+Enables the use of relocations which will cause dyld to modify (copy-on-write) read-only pages. The compiler will
+normally never generate such code.
+.It Fl force_cpusubtype_ALL
+The is only applicable with -arch ppc. It tells the linker to ignore the PowerPC cpu requirements (e.g. G3, G4 or G5) encoded
+in the object files and mark the resulting binary as runnable on any PowerPC cpu.
+.It Fl dylinker_install_name Ar path
+Only used when building dyld.
+.It Fl no_arch_warnings
+Suppresses warning messages about files that have the wrong architecture for the -arch flag
+.It Fl arch_errors_fatal
+Turns into errors, warnings about files that have the wrong architecture for the -arch flag.
+.It Fl e Ar symbol_name
+Specifies the entry point of a main executable. By default the entry name is "start" which is found in crt1.o which contains
+the glue code need to set up and call main().
+.It Fl w
+Suppress all warning messages
+.It Fl final_output Ar name
+Specifies the install name of a dylib if -install_name is not used. This option is used by gcc driver when it is invoked
+with multiple -arch arguments.
+.It Fl arch_multiple
+Specifes that the linker should augment error and warning messages with the architecture name. This option is used by gcc
+driver when it is invoked with multiple -arch arguments.
+.It Fl twolevel_namespace_hints
+Specifies that hints should be added to the resulting binary that can help speed up runtime binding by dyld as long as the
+libraries being linked against have not changed.
+.It Fl dot Ar path
+Create a file a file at the specified path containing a graph of symbol dependencies. The .dot file can be viewed in GraphViz.
+.It Fl keep_relocs
+Add section based relocation records to a final linked image. These relocations are ignored at runtime by dyld.
+.It Fl warn_stabs
+Print a warning when the linker cannot do a BINCL/EINCL optimzation because the compiler put a bad stab symbol inside
+a BINCL/EINCL range.
+.El
+.Ss Obsolete Options
+.Bl -tag
+.It Fl segalign Ar value
+All segments must be page aligned. This option is obsolete.
+.It Fl seglinkedit
+Object files (MH_OBJECT) with a LINKEDIT segment are no longer supported. This option is obsolete.
+.It Fl noseglinkedit
+This is the default. This option is obsolete.
+.It Fl fvmlib
+Fixed VM shared libraries (MH_FVMLIB) are no longer supported. This option is obsolete.
+.It Fl preload
+Preload executables (MH_PRELOAD) are no longer supported. This option is obsolete.
+.It Fl sectobjectsymbols Ar segname Ar sectname
+Adding a local label at a section start is no longer supported. This option is obsolete.
+.It Fl nofixprebinding
+The MH_NOFIXPREBINDING bit of mach_headers has been ignored since Mac OS X 10.3.9. This option is obsolete.
+.It Fl noprebind_all_twolevel_modules
+Multi-modules in dynamic libraries have been ignored at runtime since Mac OS X 10.4.0. This option is obsolete.
+.It Fl prebind_all_twolevel_modules
+Multi-modules in dynamic libraries have been ignored at runtime since Mac OS X 10.4.0. This option is obsolete.
+.It Fl prebind_allow_overlap
+When using -prebind, the linker allows overlapping by default, so this option is obsolete.
+.It Fl noprebind
+LD_PREBIND is no longer supported as a way to force on prebinding, so there no longer needs to
+be a command line way to override LD_PREBIND. This option is obsolete.
+.It Fl sect_diff_relocs Ar treatment
+This option was an attempt to warn about linking .o files compiled without -mdynamic-no-pic into
+a main executable, but the false positive rate generated too much noise to make the option useful.
This option is obsolete.
-.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 non-negative 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 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
-.IR libtool (1)
-.BI \-current_version " number"
-option when its
-.B \-dynamic
-option is set.
-.TP
-.BI \-single_module
-When building a dynamic library build the library so that it contains only
-one module.
-.TP
-.BI \-multi_module (32-bit only)
-When building a dynamic library build the library so that it contains one
-module for each object file linked in. This is the default.
-.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.
-.TP
-.BI \-macosx_version_min " version"
-This overrides the
-.B MACOSX_DEPLOYMENT_TARGET
-environment variable (see below). Unlike other linker options, this one may
-be specified multiple times; only the last occurrence is effective.
-.PP
-The following environment variable is used to control the use of incompatible
-features in the output with respect to Mac OS X releases.
-.TP
-.B 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
-.B 10.1,
-.B 10.2
-.B 10.3,
-and
-.B 10.4
-with the default being
-.B 10.4
-for the i386 architecture and
-.B 10.1
-for all other architectures.
-.PP
-The following environment variables are used by Apple's Build and Integration
-team:
-.TP
-.B LD_TRACE_ARCHIVES
-When this is set it causes a message of the form ``[Logging for XBS]
-Used static archive:
-.I filename''
-for each static archive that has members linked into the output.
-.TP
-.B LD_TRACE_DYLIBS
-When this is set it causes a message of the form ``[Logging for XBS]
-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 XBS
-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.
-.TP
-.B LD_TRACE_FILE
-When this is set, messages displayed due to the
-.B LD_TRACE_ARCHIVES
-,
-.B LD_TRACE_DYLIBS
-, and
-.B LD_TRACE_PREBINDING_DISABLED
-environment variables are printed to the file whose path is specified
-by this variable instead of stdout.
-.TP
-.B LD_SPLITSEGS_NEW_LIBRARIES
-When set and
-.B 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
-.B 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.
-
-.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), nm(1), otool(1) lipo(1),
-arch(3), dyld(3), Mach-O(5), strip(1), redo_prebinding(1)
+.It Fl run_init_lazily
+This option was removed in Mac OS X 10.2.
+.It Fl single_module
+This is now the default so does not need to be specified.
+.It Fl multi_module
+Multi-modules in dynamic libraries have been ignored at runtime since Mac OS X 10.4.0. This option is obsolete.
+.It Fl no_dead_strip_inits_and_terms
+The linker never dead strips initialzation and termination routines. They are considered "roots" of the dead strip graph.
+.It Fl A Ar basefile
+Obsolete incremental load format. This option is obsolete.
+.It Fl b
+Used with -A option to strip base file's symbols. This option is obsolete.
+..It Fl M
+Obsolete option to produce a load map. Use -map option instead.
+.It Fl Sn
+Don't strip any symbols. This is the default. This option is obsolete.
+.It Fl Si
+Optimize stabs debug symbols to remove duplicates. This is the default. This option is obsolete.
+.It Fl Sp
+Write minimal stabs which causes the debugger to open and read the original .o file for full stabs.
+This style of debugging is obsolete in Mac OS X 10.5. This option is obsolete.
+.It Fl X
+Strip local symbols that being the 'L'. This is the default. This option is obsolete.
+.It Fl s
+Completely strip the output, including removing the symbol table. This file format variant is no longer supported.
+This option is obsolete.
+.It Fl m
+Don't treat multiple definitions as an error. This is no longer supported. This option is obsolete.
+.It Fl y Ns symbol
+Display each file in which
+.Ar symbol
+is used. This was previously used to debug where an undefined symbol was used, but the linker now
+automatically prints out all usages. The -why_live option can also be used to display what kept
+a symbol from being dead striped. This option is obsolete.
+.It Fl Y Ar number
+Used to control how many occurances of each symbol specifed with -y would be shown. This option is obsolete.
+.It Fl nomultidefs
+Only used when linking an umbrella framework. Sets the MH_NOMULTIDEFS bit in the mach_header. The MH_NOMULTIDEFS
+bit has been obsolete since Mac OS X 10.4. This option is obsolete.
+.It Fl multiply_defined_unused Ar treatment
+Previously provided a way to warn or error if any of the symbol definitions in the output file matched any
+definitions in dynamic library being linked. This option is obsolete.
+.It Fl multiply_defined Ar treatment
+Previously provided a way to warn or error if any of the symbols used from a dynamic library were also
+available in another linked dynamic library. This option is obsolete.
+.It Fl private_bundle
+Previously prevented errors when -flat_namespace, -bundle, and -bundle_loader were used and the bundle
+contained a definition that conflicted with a symbol in the main executable. The linker no longer
+errors on such conflicts. This option is obsolete.
+.It Fl noall_load
+This is the default. This option is obsolete.
+.It Fl seg_addr_table_filename Ar path
+Use
+.Ar path
+instead of the install name of the library for matching an entry in the seg_addr_table. This option is obsolete.
+.It Fl sectorder Ar segname sectname orderfile
+Replaced by more general -order_file option.
+.It Fl sectorder_detail
+Produced extra logging about which entries from a sectorder entries were used. Replaced by -order_file_statistics.
+This option is obsolete.
+.El
+.Sh SEE ALSO
+as(1), ar(1), cc(1), nm(1), otool(1) lipo(1),
+arch(3), dyld(3), Mach-O(5), strip(1), rebase(1)
projects / apple / ld64.git / blobdiff