manpagez: man pages & more
man ld(1)
Home | html | info | man
ld(1)                     BSD General Commands Manual                    ld(1)


NAME

     ld -- linker


SYNOPSIS

     ld files...  [options] [-o outputfile]


DESCRIPTION

     The ld command combines several object files and libraries, resolves ref-
     erences, and produces an ouput file.  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".

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

     Usually, ld is not used directly.  Instead the gcc(1) compiler driver
     invokes ld. The compiler driver can be passed multiple -arch options and
     it will create a universal final linked image by invoking ld multiple
     times and then running lipo(1) merge the outputs into a universal file.

   Layout
     The object files are loaded in the order in which they are specified on
     the command line.  The segments and the sections in those segments will
     appear in the output file in the order they are encountered in the object
     files being linked.  All zero fill sections will appear after all non-
     zero fill sections in their segments.  Sections created from files with
     the -sectcreate option will 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.

   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.  ld will
     only pull .o files out of a static library if needed to resolve some sym-
     bol reference.  Unlike traditional linkers, ld will continually search a
     static library while linking. There is no need to specify a static
     library multiple times on the command line.

     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.

     Both dynamic and static libraries are searched as they appear on the com-
     mand line.

   Search paths
     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.
     (Note: previously, /Network/Library/Frameworks was at the end of the
     default path.  If you need that functionality, you need to explicitly add
     -F/Network/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.

   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 informa-
     tion to directly resolve symbols.  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.

   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 indi-
     rect 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, 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.

   Dynamic libraries undefines
     When linking for two-level namespace, ld does not verify that undefines
     in dylibs actually exist.  But when linking for flat namespace, ld does
     check that all undefines from all loaded dylibs have a matching defini-
     tion.  This is sometimes used to force selected functions to be loaded
     from a static library.


OPTIONS

   Options that control the kind of output
     -execute    The default.  Produce a mach-o main executable that has file
                 type MH_EXECUTE.

     -dylib      Produce a mach-o shared library that has file type MH_DYLIB.

     -bundle     Produce a mach-o bundle that has file type MH_BUNDLE.

     -r          Merges object files to produce another mach-o object file
                 with file type MH_OBJECT.

     -dylinker   Produce a mach-o dylinker that has file type MH_DYLINKER.
                 Only used when building dyld.

     -dynamic    The default.  Implied by -dylib, -bundle, or -execute

     -static     Produces a mach-o file that does not use the dyld.  Only used
                 building the kernel.

     -arch arch_name
                 Specifies which architecture (e.g. ppc, ppc64, i386, x86_64)
                 the output file should be.

     -o path     Specifies the name and location of the output file.  If not
                 specified, `a.out' is used.

   Options that control libraries
     -lx         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.

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

     -weak_library 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 ref-
                 erences to it to be marked as weak imports.

     -reexport-lx
                 This is the same as the -lx but specifies that the all sym-
                 bols in library x should be available to clients linking to
                 the library being created.  This was previously done with a
                 separate -sub_library option.

     -reexport_library 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 sepa-
                 rate -sub_library option.

     -lazy-lx    This is the same as the -lx but it is only for shared
                 libraries and the linker will construct glue code so that the
                 shared library is not loaded until the first function in it
                 is called.

     -lazy_library path_to_library
                 This is the same as listing a file name path to a shared
                 library on the link line except that the linker will con-
                 struct glue code so that the shared library is not loaded
                 until the first function in it is called.

     -upward-lx  This is the same as the -lx but specifies that the dylib is
                 an upward dependency.

     -upward_library path_to_library
                 This is the same as listing a file name path to a library on
                 the link line but also marks the dylib as an upward depen-
                 dency.

     -Ldir       Add 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. In Xcode4 and later, there can be a space
                 between the -L and directory.

     -Z          Do not search the standard directories when searching for
                 libraries and frameworks.

     -syslibroot rootdir
                 Prepend rootdir to all search paths when searching for
                 libraries or frameworks.

     -search_paths_first
                 This is now the default (in Xcode4 tools).  When processing
                 -lx the linker now searches each directory in its library
                 search paths for `libx.dylib' then `libx.a' before the moving
                 on to the next path in the library search path.

     -search_dylibs_first
                 Changes the searching behavior for libraries.  The default is
                 that when processing -lx the linker searches each directory
                 in its library search paths for `libx.dylib' then `libx.a'.
                 This option changes the behavior to 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 restores the search
                 behavior of the linker prior to Xcode4.

     -framework name[,suffix]
                 This option tells the linker to search for `name.frame-
                 work/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.frame-
                 work/name_suffix' first, if not there try `name.frame-
                 work/name').

     -weak_framework name[,suffix]
                 This is the same as the -framework name[,suffix] but forces
                 the framework and all references to it to be marked as weak
                 imports.

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

     -lazy_framework name[,suffix]
                 This is the same as the -framework name[,suffix] except that
                 the linker will construct glue code so that the framework is
                 not loaded until the first function in it is called.  You
                 cannot directly access data or Objective-C classes in a
                 framework linked this way.

     -upward_framework name[,suffix]
                 This is the same as the -framework name[,suffix] but also
                 specifies that the framework is an upward dependency.

     -Fdir       Add 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. In Xcode4 and later, there can be a
                 space between the -F and directory.

     -all_load   Loads all members of static archive libraries.

     -ObjC       Loads all members of static archive libraries that implement
                 an Objective-C class or category.

     -force_load path_to_archive
                 Loads all members of the specified static archive library.
                 Note: -all_load forces all members of all archives to be
                 loaded.  This option allows you to target a specific archive.

   Options that control additional content
     -sectcreate segname sectname file
                 The section sectname in the segment segname is created from
                 the contents of file file. The combination of segname and
                 sectname must be unique D there cannot already be a section
                 (segname,sectname) from any other input.

     -filelist file[,dirname]
                 Specifies that the linker should link the files listed in
                 file.  This is an alternative to listing the files on the
                 command line.  The file names are listed one per line sepa-
                 rated only by newlines. (Spaces and tabs are assumed to be
                 part of the file name.)  If the optional directory name,
                 dirname is specified, it is prepended to each name in the
                 list file.

     -dtrace file
                 Enables dtrace static probes when producing a final linked
                 image.  The file file must be a DTrace script which declares
                 the static probes.

   Options that control optimizations
     -dead_strip
                 Remove functions and data that are unreachable by the entry
                 point or exported symbols.

     -order_file file
                 Alters the order in which functions and data are laid out.
                 For each section in the output file, any symbol in that sec-
                 tion that are specified in the order file file is moved to
                 the start of its section and laid out in the same order as in
                 the order file 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
                 leaf name 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.  Lit-
                 eral c-strings may be ordered by by quoting the string (e.g.
                 "Hello, world\n") in the order file.

     -no_order_inits
                 When the -order_file option is not used, the linker lays out
                 functions in object file order and it moves all initializer
                 routines to the start of the __text section and terminator
                 routines to the end. Use this option to disable the automatic
                 rearrangement of initializers and terminators.

     -no_order_data
                 By default the linker reorders global data in the __DATA seg-
                 ment so that all global variables that dyld will need to
                 adjust at launch time will early in the __DATA segment.  This
                 reduces the number of dirty pages at launch time.  This
                 option disables that optimization.

     -macosx_version_min 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 out-
                 put file.  The format of version is a Mac OS X version number
                 such as 10.4 or 10.5

     -ios_version_min version
                 This is set to indicate the oldest iOS 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 version is an iOS version number such as 3.1 or
                 4.0

     -image_base address
                 Specifies the perferred load address for a dylib or bundle.
                 The argument 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.

     -no_implicit_dylibs
                 When creating a two-level namespace final linked image, nor-
                 mally the linker will hoist up public dylibs that are implic-
                 itly linked to make the two-level namespace encoding more
                 efficient for dyld.  For example, Cocoa re-exports AppKit and
                 AppKit re-exports Foundation.  If you link with -framework
                 Cocoa and use a symbol from Foundation, the linker will
                 implicitly add a load command to load Foundation and encode
                 the symbol as coming from Foundation.  If you use this
                 option, the linker will not add a load command for Foundation
                 and encode the symbol as coming from Cocoa.  Then at runtime
                 dyld will have to search Cocoa and AppKit before finding the
                 symbol in Foundation.

     -exported_symbols_order file
                 When targeting Mac OS X 10.6 or later, the format of the
                 exported symbol information can be optimized to make lookups
                 of popular symbols faster.  This option is used to pass a
                 file containing a list of the symbols most frequently used by
                 clients of the dynamic library being built. Not all exported
                 symbols need to be listed.

     -no_zero_fill_sections
                 By default the linker moves all zero fill sections to the end
                 of the __DATA segment and configures them to use no space on
                 disk.  This option suppresses that optimization, so zero-
                 filled data occupies space on disk in a final linked image.

     -merge_zero_fill_sections
                 Causes all zero-fill sections in the __DATA segment to be
                 merged into one __zerofill section.

   Options when creating a dynamic library (dylib)
     -install_name 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 compati-
                 bility.

     -mark_dead_strippable_dylib
                 Specifies that the dylib being built can be dead strip by any
                 client.  That is, the dylib has no initialization side
                 effects.  So if a client links against the dylib, but never
                 uses any symbol from it, the linker can optimize away the use
                 of the dylib.

     -compatibility_version 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 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_compatibil-
                 ity_version for compatibility.

     -current_version number
                 Specifies the current version number of the library. The cur-
                 rent 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 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.

   Options when creating a main executable
     -pie        This makes a special kind of main executable that is position
                 independent (PIE).  On Mac OS X 10.5 and later, the OS 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 -mdy-
                 namic-no-pic.  That means the codegen is less optimal, but
                 the address randomization adds some security. When targeting
                 Mac OS X 10.7 or later PIE is the default for main executa-
                 bles.

     -no_pie     Do not make a position independent executable (PIE).  This is
                 the default, when targeting 10.6 and earlier.

     -pagezero_size 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
                 size is a hexadecimal number with an optional leading 0x.  If
                 size is zero, the linker will not generate a page zero seg-
                 ment.  By default on 32-bit architectures the page zero size
                 is 4KB.  On 64-bit architectures, the default size is 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 unread-
                 able trailing segment is created after the code, filling up
                 the lower 4GB.

     -stack_size size
                 Specifies the maximum stack size for the main thread in a
                 program.  Without this option a program has a 8MB stack.  The
                 argument size is a hexadecimal number with an optional lead-
                 ing 0x. The size should be an even multiple of 4KB, that is
                 the last three hexadecimal digits should be zero.

     -allow_stack_execute
                 Marks executable so that all stacks in the task will be given
                 stack execution privilege. This includes pthread stacks.

   Options when creating a bundle
     -bundle_loader executable
                 This specifies the 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.

   Options when creating an object file
     -keep_private_externs
                 Don't turn private external (aka visibility=hidden) symbols
                 into static symbols, but rather leave them as private exter-
                 nal in the resulting object file.

     -d          Force definition of common symbols.  That is, transform ten-
                 tative definitions into real definitions.

   Options that control symbol resolution
     -exported_symbols_list filename
                 The specified 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 file-
                 name 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 charac-
                 ter.  [abc] matches one character which must be an 'a', 'b',
                 or 'c'.  [a-z] matches any single lower case letter from 'a'
                 to 'z'.

     -exported_symbol symbol
                 The specified 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.

     -unexported_symbols_list file
                 The specified 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 __pri-
                 vate_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'.

     -unexported_symbol symbol
                 The specified 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.

     -reexported_symbols_list file
                 The specified filename contains a list of symbol names that
                 are implemented in a dependent dylib and should be re-
                 exported through the dylib being created.

     -alias symbol_name alternate_symbol_name
                 Create an alias named alternate_symbol_name for the symbol
                 symbol_name.  By default the alias symbol has global visibil-
                 ity.  This option was previous the -idef:indir option.

     -alias_list filename
                 The specified filename contains a list of aliases. The symbol
                 name and its alias are on one line, separated by whitespace.
                 Lines starting with # are ignored.

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

     -u symbol_name
                 Specified that symbol symbol_name must be defined for the
                 link to succeed.  This is useful to force selected functions
                 to be loaded from a static library.

     -U symbol_name
                 Specified that it is ok for symbol_name to have no defini-
                 tion.  With -two_levelnamespace, the resulting symbol will be
                 marked dynamic_lookup which means dyld will search all loaded
                 images.

     -undefined treatment
                 Specifies how undefined symbols are to be treated. Options
                 are: error, warning, suppress, or dynamic_lookup.  The
                 default is error.

     -rpath path
                 Add path to the runpath search path list for image being cre-
                 ated.  At runtime, dyld uses the runpath when searching for
                 dylibs whose load path begins with @rpath/.

     -commons treatment
                 Specifies how commons (aka tentative definitions) are
                 resolved with respect to dylibs.  Options are: ignore_dylibs,
                 use_dylibs, error.  The default is ignore_dylibs which means
                 the linker will turn a tentative definition in an object file
                 into a real definition and not even check dylibs for con-
                 flicts.  The dylibs option means the linker should check
                 linked dylibs for definitions and use them to replace tenta-
                 tive definitions from object files.  The error option means
                 the linker should issue an error whenever a tentative defini-
                 tion in an object file conflicts with an external symbol in a
                 linked dylib.  See also -warn_commons.

   Options for introspecting the linker
     -why_load   Log why each object file in a static library is loaded. That
                 is, what symbol was needed.  Also called -whyload for compat-
                 ibility.

     -why_live symbol_name
                 Logs a chain of references to symbol_name.  Only applicable
                 with -dead_strip .  It can help debug why something that you
                 think should be dead strip removed is not removed.

     -print_statistics
                 Logs information about the amount of memory and time the
                 linker used.

     -t          Logs each file (object, archive, or dylib) the linker loads.
                 Useful for debugging problems with search paths where the
                 wrong library is loaded.

     -whatsloaded
                 Logs just object files the linker loads.

     -order_file_statistics
                 Logs information about the processing of a -order_file.

     -map map_file_path
                 Writes a map file to the specified path which details all
                 symbols and their addresses in the output image.

   Options for controling symbol table optimizations
     -S          Do not put debug information (STABS or DWARF) in the output
                 file.

     -x          Do not put non-global symbols in the output file's symbol ta-
                 ble. Non-global symbols are useful when debugging and getting
                 symbol names in back traces, but are not used at runtime. If
                 -x is used with -r non-global symbol names are not removed,
                 but instead replaced with a unique, dummy name that will be
                 automatically removed when linked into a final linked image.
                 This allows dead code stripping, which uses symbols to break
                 up code and data, to work properly and provides the security
                 of having source symbol names removed.

     -non_global_symbols_strip_list filename
                 The specified 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.

     -non_global_symbols_no_strip_list filename
                 The specified filename contains a list of non-global symbol
                 names that should be remain in the output file's symbol ta-
                 ble.  All other symbol names will be removed from the output
                 file's symbol table. See -exported_symbols_list for syntax
                 and use of wildcards.

   Rarely used Options
     -v          Prints the version of the linker.

     -allow_heap_execute
                 Normally i386 main executables will be marked so that the Mac
                 OS X 10.7 and later kernel will only allow pages with the x-
                 bit to execute instructions. This option overrides that
                 behavior and allows instructions on any page to be executed.

     -fatal_warnings
                 Causes the linker to exit with a non-zero value if any warn-
                 ings were emitted.

     -no_eh_labels
                 Normally in -r mode, the linker produces .eh labels on all
                 FDEs in the __eh_frame section.  This option suppresses those
                 labels.  Those labels are not needed by the Mac OS X 10.6
                 linker but are needed by earlier linker tools.

     -warn_compact_unwind
                 When producing a final linked image, the linker processes the
                 __eh_frame section and produces an __unwind_info section.
                 Most FDE entries in the __eh_frame can be represented by a
                 32-bit value in the __unwind_info section.  The option issues
                 a warning for any function whose FDE cannot be expressed in
                 the compact unwind format.

     -warn_weak_exports
                 Issue a warning if the resulting final linked image contains
                 weak external symbols. Such symbols require dyld to do extra
                 work at launch time to coalesce those symbols.

     -objc_gc_compaction
                 Marks the Objective-C image info in the final linked image
                 with the bit that says that the code was built to work the
                 compacting garbage collection.

     -objc_gc    Verifies all code was compiled with -fobjc-gc or -fobjc-gc-
                 only.

     -objc_gc_only
                 Verifies all code was compiled with -fobjc-gc-only.

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

     -allow_sub_type_mismatches
                 Normally the linker considers different cpu-subtype for ARM
                 (e.g. armv4t and armv6) to be different different architec-
                 tures that cannot be mixed at build time.  This option
                 relaxes that requirement, allowing you to mix object files
                 compiled for different ARM subtypes.

     -no_uuid    Do not generate an LC_UUID load command in the output file.

     -root_safe  Sets the MH_ROOT_SAFE bit in the mach header of the output
                 file.

     -setuid_safe
                 Sets the MH_SETUID_SAFE bit in the mach header of the output
                 file.

     -interposable
                 Indirects access to all to exported symbols when creating a
                 dynamic library.

     -init symbol_name
                 The specified symbol_name will be run as the first initial-
                 izer.   Only used when creating a dynamic library.

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

     -sub_umbrella framework_name
                 The specified framework will be re-exported.  Only used when
                 creating a dynamic library.

     -allowable_client name
                 Restricts what can link against the dynamic library being
                 created.  By default any code can link against any dylib. But
                 if a dylib is supposed to be private to a small set of
                 clients, you can formalize that by adding a -allowable_client
                 for each client.  If a client is libfoo.1.dylib its -allow-
                 able_client name would be "foo".  If a client is Foo.frame-
                 work its -allowable_client name would be "Foo".  For the
                 degenerate case where you want no one to ever link against a
                 dylib, you can set the -allowable_client to "!".

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

     -umbrella framework_name
                 Specifies that the dylib being linked is re-exported through
                 an umbrella framework of the specified name.

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

     -headerpad_max_install_names
                 Automatically adds space for future expansion of load com-
                 mands such that all paths could expand to MAXPATHLEN.  Only
                 useful if intend to run install_name_tool to alter the load
                 commands later.

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

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

     -sectalign segname sectname value
                 The section named sectname in the segment segname will have
                 its alignment set to value, where value is a hexadecimal num-
                 ber that must be an integral power of 2.

     -stack_addr address
                 Specifies the initial address of the stack pointer value,
                 where value is a hexadecimal number rounded to a page bound-
                 ary.

     -segprot segname max_prot 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 char-
                 acters `r' (for read), `w' (for write), `x' (for execute) and
                 `-' (no access).

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

     -segs_read_write_addr address
                 Allows a dynamic library to be built where the read-only and
                 read-write segments are not contiguous.  The address speci-
                 fied is a hexadecimal number that indicates the base address
                 for the read-write segments.

     -segs_read_only_addr address
                 Allows a dynamic library to be built where the read-only and
                 read-write segments are not contiguous.  The address speci-
                 fied is a hexadecimal number that indicates the base address
                 for the read-only segments.

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

     -seg_page_size name size
                 Specifies the page size used by the specified segment.  By
                 default the page size is 4096 for all segments.  The linker
                 will lay out segments such that size of a segment is always
                 an even multiple of its page size.

     -dylib_file install_name:file_name
                 Specifies that a dynamic shared library is in a different
                 location than its standard location. Use this option when you
                 link with a library that is dependent on a dynamic library,
                 and the dynamic library is in a location other than its
                 default location. 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/lib-
                 sys_s.A.dylib:/me/lib/libsys_s.A.dylib.

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

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

     -read_only_relocs treatment
                 Enables the use of relocations which will cause dyld to mod-
                 ify (copy-on-write) read-only pages.  The compiler will nor-
                 mally never generate such code.

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

     -dylinker_install_name path
                 Only used when building dyld.

     -no_arch_warnings
                 Suppresses warning messages about files that have the wrong
                 architecture for the -arch flag

     -arch_errors_fatal
                 Turns into errors, warnings about files that have the wrong
                 architecture for the -arch flag.

     -e symbol_name
                 Specifies the entry point of a main executable.  By default
                 the entry name is "start" which is found in crt1.o which con-
                 tains the glue code need to set up and call main().

     -w          Suppress all warning messages

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

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

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

     -dot path   Create a file at the specified path containing a graph of
                 symbol dependencies.  The .dot file can be viewed in
                 GraphViz.

     -keep_relocs
                 Add section based relocation records to a final linked image.
                 These relocations are ignored at runtime by dyld.

     -warn_stabs
                 Print a warning when the linker cannot do a BINCL/EINCL opti-
                 mization because the compiler put a bad stab symbol inside a
                 BINCL/EINCL range.

     -warn_commons
                 Print a warning whenever the a tentative definition in an
                 object file is found and a external symbol by the same name
                 is also found in a linked dylib.  This often means that the
                 extern keyword is missing from a variable declaration in a
                 header file.

     -read_only_stubs
                 [i386 only] Makes the __IMPORT segment of a final linked
                 images read-only.  This option makes a program slightly more
                 secure in that the JMP instructions in the i386 fast stubs
                 cannot be easily overwritten by malicious code.  The downside
                 is the dyld must use mprotect() to temporarily make the seg-
                 ment writable while it is binding the stubs.

     -slow_stubs
                 [i386 only]  Instead of using single JMP instruction stubs,
                 the linker creates code in the __TEXT segment which calls
                 through a lazy pointer in the __DATA segment.

     -interposable_list filename
                 The specified filename contains a list of global symbol names
                 that should always be accessed indirectly.  For instance, if
                 libSystem.dylib is linked such that _malloc is interposable,
                 then calls to malloc() from within libSystem will go through
                 a dyld stub and could potentially indirected to an alternate
                 malloc.  If libSystem.dylib were built without making _malloc
                 interposable then if _malloc was interposed at runtime, calls
                 to malloc from with libSystem would be missed (not inter-
                 posed) because they would be direct calls.

     -no_function_starts
                 By default the linker creates a compress table of function
                 start addresses in the LINKEDIT of final linked image.  This
                 option disables that behavior.

     -no_version_load_command
                 By default the linker creates a load command in final linked
                 images that contains the -macosx_version_min.  This option
                 disables that behavior.

     -no_objc_category_merging
                 By default when producing final linked image, the linker will
                 optimize Objective-C classes by merging any categories on a
                 class into the class.  Both the class and its categories must
                 be defined in the image being linked for the optimization to
                 occur.  Using this option disables that behavior.

     -object_path_lto filename
                 When performing Link Time Optimization (LTO) and a temporary
                 mach-o object file is needed, if this option is used, the
                 temporary file will be stored at the specified path and
                 remain after the link is complete.  Without the option, the
                 linker picks a path and deletes the object file before the
                 linker tool completes, thus tools such as the debugger or
                 dsymutil will not be able to access the DWARF debug info in
                 the temporary object file.

     -page_align_data_atoms
                 During development, this option can be used to space out all
                 global variables so each is on a separate page.  This is use-
                 ful when analyzing dirty and resident pages.  The information
                 can then be used to create an order file  to cluster commonly
                 used/dirty globals onto the same page(s).

   Obsolete Options
     -segalign value
                 All segments must be page aligned.  This option is obsolete.

     -seglinkedit
                 Object files (MH_OBJECT) with a LINKEDIT segment are no
                 longer supported. This option is obsolete.

     -noseglinkedit
                 This is the default.  This option is obsolete.

     -fvmlib     Fixed VM shared libraries (MH_FVMLIB) are no longer sup-
                 ported. This option is obsolete.

     -preload    Preload executables (MH_PRELOAD) are no longer supported.
                 This option is obsolete.

     -sectobjectsymbols segname sectname
                 Adding a local label at a section start is no longer sup-
                 ported.  This option is obsolete.

     -nofixprebinding
                 The MH_NOFIXPREBINDING bit of mach_headers has been ignored
                 since Mac OS X 10.3.9.  This option is obsolete.

     -noprebind_all_twolevel_modules
                 Multi-modules in dynamic libraries have been ignored at run-
                 time since Mac OS X 10.4.0.  This option is obsolete.

     -prebind_all_twolevel_modules
                 Multi-modules in dynamic libraries have been ignored at run-
                 time since Mac OS X 10.4.0.  This option is obsolete.

     -prebind_allow_overlap
                 When using -prebind, the linker allows overlapping by
                 default, so this option is obsolete.

     -noprebind  LD_PREBIND is no longer supported as a way to force on pre-
                 binding, so there no longer needs to be a command line way to
                 override LD_PREBIND.  This option is obsolete.

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

     -run_init_lazily
                 This option was removed in Mac OS X 10.2.

     -single_module
                 This is now the default so does not need to be specified.

     -multi_module
                 Multi-modules in dynamic libraries have been ignored at run-
                 time since Mac OS X 10.4.0.  This option is obsolete.

     -no_dead_strip_inits_and_terms
                 The linker never dead strips initialization and termination
                 routines.  They are considered "roots" of the dead strip
                 graph.

     -A basefile
                 Obsolete incremental load format.  This option is obsolete.

     -b          Used with -A option to strip base file's symbols.  This
                 option is obsolete.  Obsolete option to produce a load map.
                 Use -map option instead.

     -Sn         Don't strip any symbols.  This is the default.  This option
                 is obsolete.

     -Si         Optimize stabs debug symbols to remove duplicates.  This is
                 the default.  This option is obsolete.

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

     -X          Strip local symbols that begin with 'L'.  This is the
                 default.  This option is obsolete.

     -s          Completely strip the output, including removing the symbol
                 table.  This file format variant is no longer supported.
                 This option is obsolete.

     -m          Don't treat multiple definitions as an error.  This is no
                 longer supported. This option is obsolete.

     -ysymbol    Display each file in which symbol is used.  This was previ-
                 ously 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 sym-
                 bol from being dead striped.  This option is obsolete.

     -Y number   Used to control how many occurrences of each symbol specified
                 with -y would be shown.  This option is obsolete.

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

     -multiply_defined_unused treatment
                 Previously provided a way to warn or error if any of the sym-
                 bol definitions in the output file matched any definitions in
                 dynamic library being linked.  This option is obsolete.

     -multiply_defined treatment
                 Previously provided a way to warn or error if any of the sym-
                 bols used from a dynamic library were also available in
                 another linked dynamic library.  This option is obsolete.

     -private_bundle
                 Previously prevented errors when -flat_namespace, -bundle,
                 and -bundle_loader were used and the bundle contained a defi-
                 nition that conflicted with a symbol in the main executable.
                 The linker no longer errors on such conflicts.  This option
                 is obsolete.

     -noall_load
                 This is the default.  This option is obsolete.

     -seg_addr_table_filename path
                 Use path instead of the install name of the library for
                 matching an entry in the seg_addr_table.  This option is
                 obsolete.

     -sectorder segname sectname orderfile
                 Replaced by more general -order_file option.

     -sectorder_detail
                 Produced extra logging about which entries from a sectorder
                 entries were used.  Replaced by -order_file_statistics.  This
                 option is obsolete.


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)

Darwin                           March 7, 2011                          Darwin

Mac OS X 10.8 - Generated Mon Aug 20 07:23:16 CDT 2012
© manpagez.com 2000-2024
Individual documents may contain additional copyright information.