]> git.saurik.com Git - apple/ld64.git/blob - doc/man/man1/ld.1
03f257ad95a8750fe0f2f17845d2b50c3d3efbba
[apple/ld64.git] / doc / man / man1 / ld.1
1 .Dd March 7, 2011
2 .Dt ld 1
3 .Os Darwin
4 .Sh NAME
5 .Nm ld
6 .Nd "linker"
7 .Sh SYNOPSIS
8 .Nm
9 files...
10 .Op options
11 .Op Fl o Ar outputfile
12 .Sh DESCRIPTION
13 The
14 .Nm ld
15 command combines several object files and libraries, resolves references, and
16 produces an ouput file.
17 .Nm ld
18 can produce a final linked image (executable, dylib, or bundle), or with the -r
19 option, produce another object file. If the -o option is not used, the output
20 file produced is named "a.out".
21 .Ss Universal
22 The linker accepts universal (multiple-architecture) input files, but
23 always creates a "thin" (single-architecture), standard Mach-O output file.
24 The architecture for the output file is specified using the -arch option.
25 If this option is not used,
26 .Nm ld
27 attempts to determine the output architecture by examining the object
28 files in command line order. The first "thin"
29 architecture determines that of the output file. If no input
30 object file is a "thin" file, the native 32-bit architecture for the host is used.
31 .Pp
32 Usually,
33 .Nm ld
34 is not used directly. Instead the
35 .Xr gcc(1)
36 compiler driver invokes
37 .Nm ld.
38 The compiler driver can be passed multiple -arch options and it will create a
39 universal final linked image by invoking
40 .Nm ld
41 multiple times and then running
42 .Xr lipo(1)
43 merge the outputs into a universal file.
44 .Ss Layout
45 The object files are loaded in the order in which they are specified on the
46 command line. The segments and the sections in those segments will appear in
47 the output file in the order they are encountered in the object files being linked.
48 All zero fill sections will appear after all non-zero fill sections in their segments.
49 Sections created from files with the -sectcreate option will be laid out at after
50 sections from .o files. The use of the -order_file option will alter the layout
51 rules above, and move the symbols specified to start of their section.
52 .Ss Libraries
53 A static library (aka static archive) is a collection of .o files with a table of contents
54 that lists the global symbols in the .o files.
55 .Nm ld
56 will only pull .o files out of a static library if needed to resolve some symbol reference.
57 Unlike traditional linkers,
58 .Nm ld
59 will continually search a static library while linking. There is no need to specify a static
60 library multiple times on the command line.
61 .Pp
62 A dynamic library (aka dylib or framework) is a final linked image. Putting a dynamic
63 library on the command line causes two things: 1) The generated final linked image
64 will have encoded that it depends on that dynamic library. 2) Exported symbols from the
65 dynamic library are used to resolve references.
66 .Pp
67 Both dynamic and static libraries are searched as they appear on the command line.
68 .Ss Search paths
69 .Nm ld
70 maintains a list of directories to search for a library or framework to use. The default
71 library search path is /usr/lib then /usr/local/lib. The -L option will add a new library search
72 path. The default framework search path is /Library/Frameworks then /System/Library/Frameworks.
73 (Note: previously, /Network/Library/Frameworks was at the end of the default path. If you need
74 that functionality, you need to explicitly add -F/Network/Library/Frameworks).
75 The -F option will a new framework search path. The -Z option will remove
76 the standard search paths. The -syslibroot option will prepend a prefix to all search
77 paths.
78 .Ss Two-level namespace
79 By default all references resolved to a dynamic library record the library to which
80 they were resolved. At runtime, dyld uses that information to directly resolve
81 symbols. The alternative is to use the -flat_namespace option. With flat namespace,
82 the library is not recorded. At runtime, dyld will search each dynamic library in load
83 order when resolving symbols. This is slower, but more like how other operating systems
84 resolve symbols.
85 .Ss Indirect dynamic libraries
86 If the command line specifies to link against dylib A, and when dylib A was built it linked
87 against dylib B, then B is considered an indirect dylib.
88 When linking for two-level namespace, ld does not look at indirect dylibs, except when
89 re-exported by a direct dylibs. On the other hand when linking for flat namespace,
90 ld does load all indirect dylibs and uses them to resolve references.
91 Even though indirect dylibs are specified via a full path,
92 .Nm ld
93 first uses the specified search paths to locate each indirect dylib. If one cannot
94 be found using the search paths, the full path is used.
95 .Ss Dynamic libraries undefines
96 When linking for two-level namespace,
97 .Nm ld
98 does not verify that undefines in dylibs actually
99 exist. But when linking for flat namespace,
100 .Nm ld
101 does check that all undefines from all loaded dylibs have a matching definition.
102 This is sometimes used to force selected functions to be loaded from a static library.
103 .Sh OPTIONS
104 .Ss Options that control the kind of output
105 .Bl -tag
106 .It Fl execute
107 The default. Produce a mach-o main executable that has file type MH_EXECUTE.
108 .It Fl dylib
109 Produce a mach-o shared library that has file type MH_DYLIB.
110 .It Fl bundle
111 Produce a mach-o bundle that has file type MH_BUNDLE.
112 .It Fl r
113 Merges object files to produce another mach-o object file with file type MH_OBJECT.
114 .It Fl dylinker
115 Produce a mach-o dylinker that has file type MH_DYLINKER. Only used when building dyld.
116 .It Fl dynamic
117 The default. Implied by -dylib, -bundle, or -execute
118 .It Fl static
119 Produces a mach-o file that does not use the dyld. Only used building the kernel.
120 .It Fl arch Ar arch_name
121 Specifies which architecture (e.g. ppc, ppc64, i386, x86_64) the output file should be.
122 .It Fl o Ar path
123 Specifies the name and location of the output file. If not specified, `a.out' is used.
124 .El
125 .Ss Options that control libraries
126 .Bl -tag
127 .It Fl l Ns x
128 This option tells the linker to search for libx.dylib or libx.a in the library search path.
129 If string x is of the form y.o, then that file is searched for in the same places, but without
130 prepending `lib' or appending `.a' or `.dylib' to the filename.
131 .It Fl weak-l Ns Ar x
132 This is the same as the -lx but forces the library and all references to it to be marked as weak imports.
133 That is, the library is allowed to be missing at runtime.
134 .It Fl weak_library Ar path_to_library
135 This is the same as listing a file name path to a library on the link line except that it forces the
136 library and all references to it to be marked as weak imports.
137 .It Fl reexport-l Ns Ar x
138 This is the same as the -lx but specifies that the all symbols in library x should be available to
139 clients linking to the library being created. This was previously done with a separate -sub_library option.
140 .It Fl reexport_library Ar path_to_library
141 This is the same as listing a file name path to a library on the link line and it specifies that the
142 all symbols in library path should be available to clients linking to the library being created.
143 This was previously done with a separate -sub_library option.
144 .It Fl lazy-l Ns Ar x
145 This is the same as the -lx but it is only for shared libraries and the linker
146 will construct glue code so that the shared library is not loaded until
147 the first function in it is called.
148 .It Fl lazy_library Ar path_to_library
149 This is the same as listing a file name path to a shared library on the link line
150 except that the linker will construct glue code so that the shared library is not
151 loaded until the first function in it is called.
152 .It Fl upward-l Ns Ar x
153 This is the same as the -lx but specifies that the dylib is an upward dependency.
154 .It Fl upward_library Ar path_to_library
155 This is the same as listing a file name path to a library on the link line but also marks
156 the dylib as an upward dependency.
157 .It Fl L Ns dir
158 Add
159 .Ar dir
160 to the list of directories in which to search for libraries.
161 Directories specified with -L are searched in the order they appear on the command line
162 and before the default search path. In Xcode4 and later, there can be a space between
163 the -L and directory.
164 .It Fl Z
165 Do not search the standard directories when searching for libraries and frameworks.
166 .It Fl syslibroot Ar rootdir
167 Prepend
168 .Ar rootdir
169 to all search paths when searching for libraries or frameworks.
170 .It Fl search_paths_first
171 This is now the default (in Xcode4 tools). When processing -lx the linker now searches each directory
172 in its library search paths for `libx.dylib' then `libx.a' before the moving on to the next path
173 in the library search path.
174 .It Fl search_dylibs_first
175 Changes the searching behavior for libraries. The default is that when processing -lx the linker
176 searches each directory in its library search paths for `libx.dylib' then `libx.a'.
177 This option changes the behavior to first search for a file of the form `libx.dylib' in each directory
178 in the library search path, then a file of the form `libx.a' is searched for in the library search paths.
179 This option restores the search behavior of the linker prior to Xcode4.
180 .It Fl framework Ar name[,suffix]
181 This option tells the linker to search for `name.framework/name' the framework search path.
182 If the optional suffix is specified the framework is first searched for the name with the suffix and then without
183 (e.g. look for `name.framework/name_suffix' first, if not there try `name.framework/name').
184 .It Fl weak_framework Ar name[,suffix]
185 This is the same as the -framework name[,suffix] but forces the framework and all
186 references to it to be marked as weak imports.
187 .It Fl reexport_framework Ar name[,suffix]
188 This is the same as the -framework name[,suffix] but also specifies that the
189 all symbols in that framework should be available to clients linking to the library being created.
190 This was previously done with a separate -sub_umbrella option.
191 .It Fl lazy_framework Ar name[,suffix]
192 This is the same as the -framework name[,suffix] except that the linker will
193 construct glue code so that the framework is not
194 loaded until the first function in it is called. You cannot directly access
195 data or Objective-C classes in a framework linked this way.
196 .It Fl upward_framework Ar name[,suffix]
197 This is the same as the -framework name[,suffix] but also specifies that the
198 framework is an upward dependency.
199 .It Fl F Ns dir
200 Add
201 .Ar dir
202 to the list of directories in which to search for frameworks.
203 Directories specified with -F are searched in the order they appear on the command line
204 and before the default search path. In Xcode4 and later, there can be a space between
205 the -F and directory.
206 .It Fl all_load
207 Loads all members of static archive libraries.
208 .It Fl ObjC
209 Loads all members of static archive libraries that implement an Objective-C class or category.
210 .It Fl force_load Ar path_to_archive
211 Loads all members of the specified static archive library. Note: -all_load forces all members of all
212 archives to be loaded. This option allows you to target a specific archive.
213 .El
214 .Ss Options that control additional content
215 .Bl -tag
216 .It Fl sectcreate Ar segname sectname file
217 The section
218 .Ar sectname
219 in the segment
220 .Ar segname
221 is created from the contents of file
222 .Ar file.
223 The combination of segname and sectname must be unique Ð there cannot already be a section (segname,sectname)
224 from any other input.
225 .It Fl filelist Ar file[,dirname]
226 Specifies that the linker should link the files listed in
227 .Ar file .
228 This is an alternative to listing the files on the command line.
229 The file names are listed one per line separated only by newlines. (Spaces and tabs are assumed to be part of the file name.)
230 If the optional directory name,
231 .Ar dirname
232 is specified, it is prepended to each name in the list file.
233 .It Fl dtrace Ar file
234 Enables dtrace static probes when producing a final linked image. The file
235 .Ar file
236 must be a DTrace script which declares the static probes.
237 .El
238 .Ss Options that control optimizations
239 .Bl -tag
240 .It Fl dead_strip
241 Remove functions and data that are unreachable by the entry point or exported symbols.
242 .It Fl order_file Ar file
243 Alters the order in which functions and data are laid out. For each section in the output file,
244 any symbol in that section that are specified in the order file
245 .Ar file
246 is moved to the start of its section and laid out in the same order as in the order file
247 .Ar file .
248 Order files are text files with one symbol name per line. Lines starting with a # are comments.
249 A symbol name may be optionally preceded with its object file leaf name and a colon (e.g. foo.o:_foo).
250 This is useful for static functions/data that occur in multiple files.
251 A symbol name may also be optionally preceded with the architecture (e.g. ppc:_foo or ppc:foo.o:_foo).
252 This enables you to have one order file that works for multiple architectures.
253 Literal c-strings may be ordered by by quoting the string (e.g. "Hello, world\\n") in the order file.
254 .It Fl no_order_inits
255 When the -order_file option is not used, the linker lays out functions in object file order and
256 it moves all initializer routines to the start of the __text section and terminator routines
257 to the end. Use this option to disable the automatic rearrangement of initializers and terminators.
258 .It Fl no_order_data
259 By default the linker reorders global data in the __DATA segment so that all global variables that
260 dyld will need to adjust at launch time will early in the __DATA segment. This reduces the number
261 of dirty pages at launch time. This option disables that optimization.
262 .It Fl macosx_version_min Ar version
263 This is set to indicate the oldest Mac OS X version that that the output is to be used on. Specifying
264 a later version enables the linker to assumes features of that OS in the output file. The format of
265 .Ar version
266 is a Mac OS X version number such as 10.4 or 10.5
267 .It Fl ios_version_min Ar version
268 This is set to indicate the oldest iOS version that that the output is to be used on. Specifying
269 a later version enables the linker to assumes features of that OS in the output file. The format of
270 .Ar version
271 is an iOS version number such as 3.1 or 4.0
272 .It Fl image_base Ar address
273 Specifies the perferred load address for a dylib or bundle. The argument
274 .Ar address
275 is a hexadecimal number with an optional leading 0x. By choosing non-overlapping address for all
276 dylibs and bundles that a program loads, launch time can be improved because dyld will not need to
277 "rebase" the image (that is, adjust pointers within the image to work at the loaded address).
278 It is often easier to not use this option, but instead use the rebase(1) tool, and give it a list of dylibs.
279 It will then choose non-overlapping addresses for the list and rebase them all.
280 This option is also called -seg1addr for compatibility.
281 .It Fl no_implicit_dylibs
282 When creating a two-level namespace final linked image, normally the linker will hoist up public dylibs
283 that are implicitly linked to make the two-level namespace
284 encoding more efficient for dyld. For example, Cocoa re-exports AppKit and AppKit re-exports Foundation.
285 If you link with -framework Cocoa and use a symbol from Foundation, the linker will implicitly add a load
286 command to load Foundation and encode the symbol as coming from Foundation. If you use this option,
287 the linker will not add a load command for Foundation and encode the symbol as coming from Cocoa. Then
288 at runtime dyld will have to search Cocoa and AppKit before finding the symbol in Foundation.
289 .It Fl exported_symbols_order Ar file
290 When targeting Mac OS X 10.6 or later, the format of the exported symbol information can be optimized to
291 make lookups of popular symbols faster. This option is used to pass a file containing a list of
292 the symbols most frequently used by clients of the dynamic library being built. Not all exported symbols
293 need to be listed.
294 .It Fl no_zero_fill_sections
295 By default the linker moves all zero fill sections to the end of the __DATA segment and configures
296 them to use no space on disk. This option suppresses that optimization, so zero-filled data occupies
297 space on disk in a final linked image.
298 .It Fl merge_zero_fill_sections
299 Causes all zero-fill sections in the __DATA segment to be merged into one __zerofill section.
300 .El
301 .Ss Options when creating a dynamic library (dylib)
302 .Bl -tag
303 .It Fl install_name Ar name
304 Sets an internal "install path" (LC_ID_DYLIB) in a dynamic library. Any clients linked against the library
305 will record that path as the way dyld should locate this library. If this option is not specified, then
306 the -o path will be used. This option is also called -dylib_install_name for compatibility.
307 .It Fl mark_dead_strippable_dylib
308 Specifies that the dylib being built can be dead strip by any client. That is, the dylib has
309 no initialization side effects. So if a client links against the dylib, but never uses
310 any symbol from it, the linker can optimize away the use of the dylib.
311 .It Fl compatibility_version Ar number
312 Specifies the compatibility version number of the library. When a library is loaded by dyld, the
313 compatibility version is checked and if the program's version is greater that the library's version, it is an error.
314 The format of
315 .Ar number
316 is X[.Y[.Z]] where X must be a positive non-zero number less than or equal to 65535,
317 and .Y and .Z are optional and if present must be non-negative numbers less than or equal to 255.
318 If the compatibility version number is not specified, it has a value of 0 and no checking is done when the library is used.
319 This option is also called -dylib_compatibility_version for compatibility.
320 .It Fl current_version Ar number
321 Specifies the current version number of the library. The current version of the library can be obtained
322 programmatically by the user of the library so it can determine exactly which version of the library it is using.
323 The format of
324 .Ar number
325 is X[.Y[.Z]] where X must be a positive non-zero number less than or equal to 65535,
326 and .Y and .Z are optional and if present must be non-negative numbers less than or equal to 255.
327 If the version number is not specified, it has a value of 0.
328 This option is also called -dylib_current_version for compatibility.
329 .El
330 .Ss Options when creating a main executable
331 .Bl -tag
332 .It Fl pie
333 This makes a special kind of main executable that is position independent (PIE). On Mac OS X 10.5 and later, the OS
334 the OS will load a PIE at a random address each time it is executed. You cannot create a PIE from .o files compiled
335 with -mdynamic-no-pic. That means the codegen is less optimal, but the address randomization adds some
336 security. When targeting Mac OS X 10.7 or later PIE is the default for main executables.
337 .It Fl no_pie
338 Do not make a position independent executable (PIE). This is the default, when targeting 10.6 and earlier.
339 .It Fl pagezero_size Ar size
340 By default the linker creates an unreadable segment starting at address zero named __PAGEZERO. Its existence
341 will cause a bus error if a NULL pointer is dereferenced. The argument
342 .Ar size
343 is a hexadecimal number with an optional leading 0x. If
344 .Ar size
345 is zero, the linker will not generate a page zero segment. By default on 32-bit architectures the page zero size
346 is 4KB. On 64-bit architectures, the default size is 4GB. The ppc64 architecture has some special cases. Since Mac
347 OS X 10.4 did not support 4GB page zero programs, the default page zero size for ppc64 will be 4KB unless
348 -macosx_version_min is 10.5 or later. Also, the -mdynamic-no-pic codegen model for ppc64 will only work if the
349 code is placed in the lower 2GB of the address space, so the if the linker detects any such code, the page zero
350 size is set to 4KB and then a new unreadable trailing segment is created after the code, filling up the lower 4GB.
351 .It Fl stack_size Ar size
352 Specifies the maximum stack size for the main thread in a program. Without this option a program has a 8MB stack.
353 The argument
354 .Ar size
355 is a hexadecimal number with an optional leading 0x. The
356 .Ar size
357 should be an even multiple of 4KB, that is the last three hexadecimal digits should be zero.
358 .It Fl allow_stack_execute
359 Marks executable so that all stacks in the task will be given stack execution privilege. This includes pthread stacks.
360 .El
361 .Ss Options when creating a bundle
362 .Bl -tag
363 .It Fl bundle_loader Ar executable
364 This specifies the
365 .Ar executable
366 that will be loading the bundle output file being linked.
367 Undefined symbols from the bundle are checked against the specified
368 .Ar executable
369 like it was one of the
370 dynamic libraries the bundle was linked with.
371 .El
372 .Ss Options when creating an object file
373 .Bl -tag
374 .It Fl keep_private_externs
375 Don't turn private external (aka visibility=hidden) symbols into static symbols,
376 but rather leave them as private external in the resulting object file.
377 .It Fl d
378 Force definition of common symbols. That is, transform tentative definitions into real definitions.
379 .El
380 .Ss Options that control symbol resolution
381 .Bl -tag
382 .It Fl exported_symbols_list Ar filename
383 The specified
384 .Ar filename
385 contains a list of global symbol names that will remain as global symbols in the output file.
386 All other global symbols will be treated as if they were marked as __private_extern__ (aka visibility=hidden)
387 and will not be global in the output file. The symbol names listed in filename must be one per line.
388 Leading and trailing white space are not part of the symbol name.
389 Lines starting with # are ignored, as are lines with only white space.
390 Some wildcards (similar to shell file matching) are supported. The * matches zero or more characters.
391 The ? matches one character. [abc] matches one character which must be an 'a', 'b', or 'c'. [a-z] matches
392 any single lower case letter from 'a' to 'z'.
393 .It Fl exported_symbol Ar symbol
394 The specified
395 .Ar symbol
396 is added to the list of global symbols names that will remain as global symbols in the output file. This
397 option can be used multiple times. For short lists, this can be more convenient than creating a file and using
398 -exported_symbols_list.
399 .It Fl unexported_symbols_list Ar file
400 The specified
401 .Ar filename
402 contains a list of global symbol names that will not remain as global symbols in the output file.
403 The symbols will be treated as if they were marked as __private_extern__ (aka visibility=hidden) and will not be global
404 in the output file. The symbol names listed in filename must be one per line.
405 Leading and trailing white space are not part of the symbol name.
406 Lines starting with # are ignored, as are lines with only white space.
407 Some wildcards (similar to shell file matching) are supported. The * matches zero or more characters.
408 The ? matches one character. [abc] matches one character which must be an 'a', 'b', or 'c'. [a-z] matches
409 any single lower case letter from 'a' to 'z'.
410 .It Fl unexported_symbol Ar symbol
411 The specified
412 .Ar symbol
413 is added to the list of global symbols names that will not remain as global symbols in the output file. This
414 option can be used multiple times. For short lists, this can be more convenient than creating a file and using
415 -unexported_symbols_list.
416 .It Fl reexported_symbols_list Ar file
417 The specified
418 .Ar filename
419 contains a list of symbol names that are implemented in a dependent dylib and should be re-exported
420 through the dylib being created.
421 .It Fl alias Ar symbol_name Ar alternate_symbol_name
422 Create an alias named
423 .Ar alternate_symbol_name
424 for the symbol
425 .Ar symbol_name .
426 By default the alias symbol has global visibility. This option was previous the -idef:indir option.
427 .It Fl alias_list Ar filename
428 The specified
429 .Ar filename
430 contains a list of aliases. The symbol name and its alias are on one line, separated by whitespace.
431 Lines starting with # are ignored.
432 .It Fl flat_namespace
433 Alters how symbols are resolved at build time and runtime. With -two_levelnamespace (the default), the linker
434 only searches dylibs on the command line for symbols, and records in which dylib they were found. With -flat_namespace,
435 the linker searches all dylibs on the command line and all dylibs those original dylibs depend on. The linker
436 does not record which dylib an external symbol came from, so at runtime dyld again searches all images and uses
437 the first definition it finds. In addition, any undefines in loaded flat_namespace dylibs must be resolvable
438 at build time.
439 .It Fl u Ar symbol_name
440 Specified that symbol
441 .Ar symbol_name
442 must be defined for the link to succeed. This is useful to force selected functions to be loaded
443 from a static library.
444 .It Fl U Ar symbol_name
445 Specified that it is ok for
446 .Ar symbol_name
447 to have no definition. With -two_levelnamespace, the resulting symbol will be marked dynamic_lookup which
448 means dyld will search all loaded images.
449 .It Fl undefined Ar treatment
450 Specifies how undefined symbols are to be treated. Options are: error, warning, suppress, or dynamic_lookup. The
451 default is error.
452 .It Fl rpath Ar path
453 Add
454 .Ar path
455 to the runpath search path list for image being created. At runtime, dyld uses the runpath when searching
456 for dylibs whose load path begins with @rpath/.
457 .It Fl commons Ar treatment
458 Specifies how commons (aka tentative definitions) are resolved with respect to dylibs. Options are:
459 ignore_dylibs, use_dylibs, error. The default is ignore_dylibs which means the linker will turn a tentative
460 definition in an object file into a real definition and not even check dylibs for conflicts. The dylibs
461 option means the linker should check linked dylibs for definitions and use them to replace tentative definitions
462 from object files. The error option means the linker should issue an error whenever a tentative definition in an
463 object file conflicts with an external symbol in a linked dylib. See also -warn_commons.
464 .El
465 .Ss Options for introspecting the linker
466 .Bl -tag
467 .It Fl why_load
468 Log why each object file in a static library is loaded. That is, what symbol was needed. Also called -whyload
469 for compatibility.
470 .It Fl why_live Ar symbol_name
471 Logs a chain of references to
472 .Ar symbol_name .
473 Only applicable with -dead_strip .
474 It can help debug why something that you think should be dead strip removed is not removed.
475 .It Fl print_statistics
476 Logs information about the amount of memory and time the linker used.
477 .It Fl t
478 Logs each file (object, archive, or dylib) the linker loads. Useful for debugging problems with search paths where the wrong library is loaded.
479 .It Fl whatsloaded
480 Logs just object files the linker loads.
481 .It Fl order_file_statistics
482 Logs information about the processing of a -order_file.
483 .It Fl map Ar map_file_path
484 Writes a map file to the specified path which details all symbols and their addresses in the output image.
485 .El
486 .Ss Options for controling symbol table optimizations
487 .Bl -tag
488 .It Fl S
489 Do not put debug information (STABS or DWARF) in the output file.
490 .It Fl x
491 Do not put non-global symbols in the output file's symbol table. Non-global symbols are useful when debugging and
492 getting symbol names in back traces, but are not used at runtime. If -x is used with -r
493 non-global symbol names are not removed, but instead replaced with a unique, dummy name
494 that will be automatically removed when linked into a final linked image. This
495 allows dead code stripping, which uses symbols to break up code and data, to
496 work properly and provides the security of having source symbol names removed.
497 .It Fl non_global_symbols_strip_list Ar filename
498 The specified
499 .Ar filename
500 contains a list of non-global symbol names that should be removed from the output file's symbol table. All other
501 non-global symbol names will remain in the output files symbol table. See -exported_symbols_list for syntax and use
502 of wildcards.
503 .It Fl non_global_symbols_no_strip_list Ar filename
504 The specified
505 .Ar filename
506 contains a list of non-global symbol names that should be remain in the output file's symbol table. All other
507 symbol names will be removed from the output file's symbol table. See -exported_symbols_list for syntax and use
508 of wildcards.
509 .El
510 .Ss Rarely used Options
511 .Bl -tag
512 .It Fl v
513 Prints the version of the linker.
514 .It Fl allow_heap_execute
515 Normally i386 main executables will be marked so that the Mac OS X 10.7 and later kernel
516 will only allow pages with the x-bit to execute instructions. This option overrides that
517 behavior and allows instructions on any page to be executed.
518 .It Fl no_eh_labels
519 Normally in -r mode, the linker produces .eh labels on all FDEs in the __eh_frame section.
520 This option suppresses those labels. Those labels are not needed by the Mac OS X 10.6
521 linker but are needed by earlier linker tools.
522 .It Fl warn_compact_unwind
523 When producing a final linked image, the linker processes the __eh_frame section and
524 produces an __unwind_info section. Most FDE entries in the __eh_frame can be represented
525 by a 32-bit value in the __unwind_info section. The option issues a warning for
526 any function whose FDE cannot be expressed in the compact unwind format.
527 .It Fl warn_weak_exports
528 Issue a warning if the resulting final linked image contains weak external symbols. Such
529 symbols require dyld to do extra work at launch time to coalesce those symbols.
530 .It Fl objc_gc_compaction
531 Marks the Objective-C image info in the final linked image with the bit that says that the
532 code was built to work the compacting garbage collection.
533 .It Fl objc_gc
534 Verifies all code was compiled with -fobjc-gc or -fobjc-gc-only.
535 .It Fl objc_gc_only
536 Verifies all code was compiled with -fobjc-gc-only.
537 .It Fl dead_strip_dylibs
538 Remove dylibs that are unreachable by the entry point or exported symbols. That is,
539 suppresses the generation of load command commands for dylibs which supplied no
540 symbols during the link. This option should not be used when linking against a dylib which
541 is required at runtime for some indirect reason such as the dylib has an important initializer.
542 .It Fl allow_sub_type_mismatches
543 Normally the linker considers different cpu-subtype for ARM (e.g. armv4t and armv6) to be different
544 different architectures that cannot be mixed at build time. This option relaxes that requirement,
545 allowing you to mix object files compiled for different ARM subtypes.
546 .It Fl no_uuid
547 Do not generate an LC_UUID load command in the output file.
548 .It Fl root_safe
549 Sets the MH_ROOT_SAFE bit in the mach header of the output file.
550 .It Fl setuid_safe
551 Sets the MH_SETUID_SAFE bit in the mach header of the output file.
552 .It Fl interposable
553 Indirects access to all to exported symbols when creating a dynamic library.
554 .It Fl init Ar symbol_name
555 The specified symbol_name will be run as the first initializer. Only used when creating a dynamic library.
556 .It Fl sub_library Ar library_name
557 The specified dylib will be re-exported. For example the library_name for /usr/lib/libobjc_profile.A.dylib would be libobjc.
558 Only used when creating a dynamic library.
559 .It Fl sub_umbrella Ar framework_name
560 The specified framework will be re-exported. Only used when creating a dynamic library.
561 .It Fl allowable_client Ar name
562 Restricts what can link against the dynamic library being created. By default any code
563 can link against any dylib. But if a dylib is supposed to be private to a small
564 set of clients, you can formalize that by adding a -allowable_client for each client.
565 If a client is libfoo.1.dylib its -allowable_client name would be "foo". If a
566 client is Foo.framework its -allowable_client name would be "Foo". For the degenerate
567 case where you want no one to ever link against a dylib, you can set the
568 -allowable_client to "!".
569 .It Fl client_name Ar name
570 Enables a bundle to link against a dylib that was built with -allowable_client.
571 The name specified must match one of the -allowable_client names specified when the dylib was created.
572 .It Fl umbrella Ar framework_name
573 Specifies that the dylib being linked is re-exported through an umbrella framework of the specified name.
574 .It Fl headerpad Ar size
575 Specifies the minimum space for future expansion of the load commands. Only useful if intend to run
576 install_name_tool to alter the load commands later. Size is a hexadecimal number.
577 .It Fl headerpad_max_install_names
578 Automatically adds space for future expansion of load commands such that all paths could expand to MAXPATHLEN.
579 Only useful if intend to run install_name_tool to alter the load commands later. Size is a hexadecimal number.
580 .It Fl bind_at_load
581 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.
582 .It Fl force_flat_namespace
583 Sets a bit in the mach header of the resulting binary which tells dyld to not only use flat namespace for the binary,
584 but force flat namespace binding on all dylibs and bundles loaded in the process. Can only be used when linking main executables.
585 .It Fl sectalign Ar segname Ar sectname Ar value
586 The section named sectname in the segment segname will have its alignment set to value, where value is a hexadecimal
587 number that must be an integral power of 2.
588 .It Fl stack_addr Ar address
589 Specifies the initial address of the stack pointer value, where value is a hexadecimal number rounded to a page boundary.
590 .It Fl segprot Ar segname Ar max_prot Ar init_prot
591 Specifies the maximum and initial virtual memory protection of the named segment, name, to be max and init ,respectively.
592 The values for max and init are any combination of the characters `r' (for read), `w' (for write), `x' (for execute) and `-' (no access).
593 .It Fl seg_addr_table Ar filename
594 Specifies a file containing base addresses for dynamic libraries. Each line of the file is a hexadecimal base address
595 followed by whitespace then the install name of the corresponding dylib. The # character denotes a comment.
596 .It Fl segs_read_write_addr Ar address
597 Allows a dynamic library to be built where the read-only and read-write segments are not contiguous. The address
598 specified is a hexadecimal number that indicates the base address for the read-write segments.
599 .It Fl segs_read_only_addr Ar address
600 Allows a dynamic library to be built where the read-only and read-write segments are not contiguous. The address
601 specified is a hexadecimal number that indicates the base address for the read-only segments.
602 .It Fl segaddr Ar name Ar address
603 Specifies the starting address of the segment named name to be address. The address must be a hexadecimal number
604 that is a multiple of 4K page size.
605 .It Fl seg_page_size Ar name Ar size
606 Specifies the page size used by the specified segment. By default the page size is 4096 for all segments.
607 The linker will lay out segments such that size of a segment is always an even multiple of its page size.
608 .It Fl dylib_file Ar install_name:file_name
609 Specifies that a dynamic shared library is in a different location than its standard location. Use this option
610 when you link with a library that is dependent on a dynamic library, and the dynamic library is in a location other
611 than its default location. install_name specifies the path where the library normally resides. file_name specifies
612 the path of the library you want to use instead. For example, if you link to a library that depends upon the dynamic
613 library libsys and you have libsys installed in a nondefault location, you would use this option:
614 -dylib_file /lib/libsys_s.A.dylib:/me/lib/libsys_s.A.dylib.
615 .It Fl prebind
616 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.
617 .It Fl weak_reference_mismatches Ar treatment
618 Specifies what to do if a symbol is weak-imported in one object file but not weak-imported in another. The valid
619 treatments are: error, weak, or non-weak. The default is non-weak.
620 .It Fl read_only_relocs Ar treatment
621 Enables the use of relocations which will cause dyld to modify (copy-on-write) read-only pages. The compiler will
622 normally never generate such code.
623 .It Fl force_cpusubtype_ALL
624 The is only applicable with -arch ppc. It tells the linker to ignore the PowerPC cpu requirements (e.g. G3, G4 or G5) encoded
625 in the object files and mark the resulting binary as runnable on any PowerPC cpu.
626 .It Fl dylinker_install_name Ar path
627 Only used when building dyld.
628 .It Fl no_arch_warnings
629 Suppresses warning messages about files that have the wrong architecture for the -arch flag
630 .It Fl arch_errors_fatal
631 Turns into errors, warnings about files that have the wrong architecture for the -arch flag.
632 .It Fl e Ar symbol_name
633 Specifies the entry point of a main executable. By default the entry name is "start" which is found in crt1.o which contains
634 the glue code need to set up and call main().
635 .It Fl w
636 Suppress all warning messages
637 .It Fl final_output Ar name
638 Specifies the install name of a dylib if -install_name is not used. This option is used by gcc driver when it is invoked
639 with multiple -arch arguments.
640 .It Fl arch_multiple
641 Specifes that the linker should augment error and warning messages with the architecture name. This option is used by gcc
642 driver when it is invoked with multiple -arch arguments.
643 .It Fl twolevel_namespace_hints
644 Specifies that hints should be added to the resulting binary that can help speed up runtime binding by dyld as long as the
645 libraries being linked against have not changed.
646 .It Fl dot Ar path
647 Create a file at the specified path containing a graph of symbol dependencies. The .dot file can be viewed in GraphViz.
648 .It Fl keep_relocs
649 Add section based relocation records to a final linked image. These relocations are ignored at runtime by dyld.
650 .It Fl warn_stabs
651 Print a warning when the linker cannot do a BINCL/EINCL optimization because the compiler put a bad stab symbol inside
652 a BINCL/EINCL range.
653 .It Fl warn_commons
654 Print a warning whenever the a tentative definition in an object file is found and a external symbol by the same name
655 is also found in a linked dylib. This often means that the extern keyword is missing from a variable declaration
656 in a header file.
657 .It Fl read_only_stubs
658 [i386 only] Makes the __IMPORT segment of a final linked images read-only. This option makes a program slightly more
659 secure in that the JMP instructions in the i386 fast stubs cannot be easily overwritten by malicious code. The downside
660 is the dyld must use mprotect() to temporarily make the segment writable while it is binding the stubs.
661 .It Fl slow_stubs
662 [i386 only] Instead of using single JMP instruction stubs, the linker creates code in the __TEXT segment which
663 calls through a lazy pointer in the __DATA segment.
664 .It Fl interposable_list Ar filename
665 The specified
666 .Ar filename
667 contains a list of global symbol names that should always be accessed indirectly. For instance, if libSystem.dylib
668 is linked such that _malloc is interposable, then calls to malloc() from within libSystem will go through a dyld
669 stub and could potentially indirected to an alternate malloc. If libSystem.dylib were built without making _malloc
670 interposable then if _malloc was interposed at runtime, calls to malloc from with libSystem would be missed
671 (not interposed) because they would be direct calls.
672 .It Fl no_function_starts
673 By default the linker creates a compress table of function start addresses in the LINKEDIT of
674 final linked image. This option disables that behavior.
675 .It Fl no_version_load_command
676 By default the linker creates a load command in final linked images that contains the -macosx_version_min.
677 This option disables that behavior.
678 .It Fl no_objc_category_merging
679 By default when producing final linked image, the linker will optimize Objective-C classes by merging
680 any categories on a class into the class. Both the class and its categories must be defined in the image
681 being linked for the optimization to occur. Using this option disables that behavior.
682 .It Fl object_path_lto Ar filename
683 When performing Link Time Optimization (LTO) and a temporary mach-o object file is needed, if this
684 option is used, the temporary file will be stored at the specified path and remain after the link
685 is complete. Without the option, the linker picks a path and deletes the object file before the linker
686 tool completes, thus tools such as the debugger or dsymutil will not be able to access the DWARF debug
687 info in the temporary object file.
688 .It Fl page_align_data_atoms
689 During development, this option can be used to space out all global variables so each is on a separate page.
690 This is useful when analyzing dirty and resident pages. The information can then be used to create an
691 order file to cluster commonly used/dirty globals onto the same page(s).
692 .El
693 .Ss Obsolete Options
694 .Bl -tag
695 .It Fl segalign Ar value
696 All segments must be page aligned. This option is obsolete.
697 .It Fl seglinkedit
698 Object files (MH_OBJECT) with a LINKEDIT segment are no longer supported. This option is obsolete.
699 .It Fl noseglinkedit
700 This is the default. This option is obsolete.
701 .It Fl fvmlib
702 Fixed VM shared libraries (MH_FVMLIB) are no longer supported. This option is obsolete.
703 .It Fl preload
704 Preload executables (MH_PRELOAD) are no longer supported. This option is obsolete.
705 .It Fl sectobjectsymbols Ar segname Ar sectname
706 Adding a local label at a section start is no longer supported. This option is obsolete.
707 .It Fl nofixprebinding
708 The MH_NOFIXPREBINDING bit of mach_headers has been ignored since Mac OS X 10.3.9. This option is obsolete.
709 .It Fl noprebind_all_twolevel_modules
710 Multi-modules in dynamic libraries have been ignored at runtime since Mac OS X 10.4.0. This option is obsolete.
711 .It Fl prebind_all_twolevel_modules
712 Multi-modules in dynamic libraries have been ignored at runtime since Mac OS X 10.4.0. This option is obsolete.
713 .It Fl prebind_allow_overlap
714 When using -prebind, the linker allows overlapping by default, so this option is obsolete.
715 .It Fl noprebind
716 LD_PREBIND is no longer supported as a way to force on prebinding, so there no longer needs to
717 be a command line way to override LD_PREBIND. This option is obsolete.
718 .It Fl sect_diff_relocs Ar treatment
719 This option was an attempt to warn about linking .o files compiled without -mdynamic-no-pic into
720 a main executable, but the false positive rate generated too much noise to make the option useful.
721 This option is obsolete.
722 .It Fl run_init_lazily
723 This option was removed in Mac OS X 10.2.
724 .It Fl single_module
725 This is now the default so does not need to be specified.
726 .It Fl multi_module
727 Multi-modules in dynamic libraries have been ignored at runtime since Mac OS X 10.4.0. This option is obsolete.
728 .It Fl no_dead_strip_inits_and_terms
729 The linker never dead strips initialization and termination routines. They are considered "roots" of the dead strip graph.
730 .It Fl A Ar basefile
731 Obsolete incremental load format. This option is obsolete.
732 .It Fl b
733 Used with -A option to strip base file's symbols. This option is obsolete.
734 ..It Fl M
735 Obsolete option to produce a load map. Use -map option instead.
736 .It Fl Sn
737 Don't strip any symbols. This is the default. This option is obsolete.
738 .It Fl Si
739 Optimize stabs debug symbols to remove duplicates. This is the default. This option is obsolete.
740 .It Fl Sp
741 Write minimal stabs which causes the debugger to open and read the original .o file for full stabs.
742 This style of debugging is obsolete in Mac OS X 10.5. This option is obsolete.
743 .It Fl X
744 Strip local symbols that being the 'L'. This is the default. This option is obsolete.
745 .It Fl s
746 Completely strip the output, including removing the symbol table. This file format variant is no longer supported.
747 This option is obsolete.
748 .It Fl m
749 Don't treat multiple definitions as an error. This is no longer supported. This option is obsolete.
750 .It Fl y Ns symbol
751 Display each file in which
752 .Ar symbol
753 is used. This was previously used to debug where an undefined symbol was used, but the linker now
754 automatically prints out all usages. The -why_live option can also be used to display what kept
755 a symbol from being dead striped. This option is obsolete.
756 .It Fl Y Ar number
757 Used to control how many occurrences of each symbol specified with -y would be shown. This option is obsolete.
758 .It Fl nomultidefs
759 Only used when linking an umbrella framework. Sets the MH_NOMULTIDEFS bit in the mach_header. The MH_NOMULTIDEFS
760 bit has been obsolete since Mac OS X 10.4. This option is obsolete.
761 .It Fl multiply_defined_unused Ar treatment
762 Previously provided a way to warn or error if any of the symbol definitions in the output file matched any
763 definitions in dynamic library being linked. This option is obsolete.
764 .It Fl multiply_defined Ar treatment
765 Previously provided a way to warn or error if any of the symbols used from a dynamic library were also
766 available in another linked dynamic library. This option is obsolete.
767 .It Fl private_bundle
768 Previously prevented errors when -flat_namespace, -bundle, and -bundle_loader were used and the bundle
769 contained a definition that conflicted with a symbol in the main executable. The linker no longer
770 errors on such conflicts. This option is obsolete.
771 .It Fl noall_load
772 This is the default. This option is obsolete.
773 .It Fl seg_addr_table_filename Ar path
774 Use
775 .Ar path
776 instead of the install name of the library for matching an entry in the seg_addr_table. This option is obsolete.
777 .It Fl sectorder Ar segname sectname orderfile
778 Replaced by more general -order_file option.
779 .It Fl sectorder_detail
780 Produced extra logging about which entries from a sectorder entries were used. Replaced by -order_file_statistics.
781 This option is obsolete.
782 .El
783 .Sh SEE ALSO
784 as(1), ar(1), cc(1), nm(1), otool(1) lipo(1),
785 arch(3), dyld(3), Mach-O(5), strip(1), rebase(1)