1 LD(1) User Commands LD(1)
2
3
4
5 NAME
6 ld - link-editor for object files
7
8 SYNOPSIS
9 ld [-32 | -64] [-a | -r] [-b] [-Bdirect | nodirect]
10 [-B dynamic | static] [-B eliminate] [-B group] [-B local]
11 [-B reduce] [-B symbolic] [-c name] [-C] [-d y | n]
12 [-D token,...] [-e epsym] [-f name | -F name] [-G] [-h name]
13 [-i] [-I name] [-l x] [-L path] [-m] [-M mapfile]
14 [-N string] [-o outfile] [-p auditlib] [-P auditlib]
15 [-Q y | n] [-R path] [-s] [-S supportlib] [-t]
16 [-u symname] [-V] [-Y P,dirlist] [-z absexec]
17 [-z allextract | defaultextract | weakextract ] [-z altexec64]
18 [-z aslr[=state]] [-z assert-deflib] [ -z assert-deflib=libname]
19 [-z combreloc | nocombreloc ] [-z defs | nodefs]
20 [-z direct | nodirect] [-z endfiltee]
21 [-z fatal-warnings | nofatal-warnings ] [-z finiarray=function]
22 [-z globalaudit] [-z groupperm | nogroupperm]
23 [-z guidance[=id1,id2...] [-z help ]
24 [-z ignore | record] [-z initarray=function] [-z initfirst]
25 [-z interpose] [-z lazyload | nolazyload]
26 [-z ld32=arg1,arg2,...] [-z ld64=arg1,arg2,...]
27 [-z loadfltr] [-z muldefs] [-z nocompstrtab] [-z nodefaultlib]
28 [-z nodelete] [-z nodlopen] [-z nodump] [-z noldynsym]
29 [-z nopartial] [-z noversion] [-z now] [-z origin]
30 [-z preinitarray=function] [-z redlocsym] [-z relaxreloc]
31 [-z rescan-now] [-z recan] [-z rescan-start ... -z rescan-end]]
32 [-z target=sparc|x86] [-z text | textwarn | textoff]
33 [-z verbose] [-z wrap=symbol] filename...
34
35
36 DESCRIPTION
37 The link-editor, ld, combines relocatable object files by resolving
38 symbol references to symbol definitions, together with performing
39 relocations. ld operates in two modes, static or dynamic, as governed
40 by the -d option. In all cases, the output of ld is left in the file
41 a.out by default. See NOTES.
42
43
44 In dynamic mode, -dy, the default, relocatable object files that are
45 provided as arguments are combined to produce an executable object
46 file. This file is linked at execution with any shared object files
47 that are provided as arguments. If the -G option is specified,
48 relocatable object files are combined to produce a shared object.
49 Without the -G option, a dynamic executable is created.
50
51
52 In static mode, -dn, relocatable object files that are provided as
53 arguments are combined to produce a static executable file. If the -r
54 option is specified, relocatable object files are combined to produce
55 one relocatable object file. See Static Executables.
56
57
58 Dynamic linking is the most common model for combining relocatable
59 objects, and the eventual creation of processes within Solaris. This
60 environment tightly couples the work of the link-editor and the runtime
61 linker, ld.so.1(1). Both of these utilities, together with their
62 related technologies and utilities, are extensively documented in the
63 Linker and Libraries Guide.
64
65
66 If any argument is a library, ld by default searches the library
67 exactly once at the point the library is encountered on the argument
68 list. The library can be either a shared object or relocatable archive.
69 See ar.h(3HEAD)).
70
71
72 A shared object consists of an indivisible, whole unit that has been
73 generated by a previous link-edit of one or more input files. When the
74 link-editor processes a shared object, the entire contents of the shared
75 object become a logical part of the resulting output file image. The
76 shared object is not physically copied during the link-edit as its
77 actual inclusion is deferred until process execution. This logical
78 inclusion means that all symbol entries defined in the shared object
79 are made available to the link-editing process. See Chapter 4, Shared
80 Objects, in Linker and Libraries Guide
81
82
83 For an archive library, ld loads only those routines that define an
84 unresolved external reference. ld searches the symbol table of the
85 archive library sequentially to resolve external references that can be
86 satisfied by library members. This search is repeated until no external
87 references can be resolved by the archive. Thus, the order of members
88 in the library is functionally unimportant, unless multiple library
89 members exist that define the same external symbol. Archive libraries
90 that have interdependencies can require multiple command line
91 definitions, or the use of one of the -z rescan options. See Archive
92 Processing in Linker and Libraries Guide.
93
94
95 ld is a cross link-editor, able to link 32-bit objects or 64-bit
96 objects, for Sparc or x86 targets. ld uses the ELF class and machine
97 type of the first relocatable object on the command line to govern the
98 mode in which to operate. The mixing of 32-bit objects and 64-bit
99 objects is not permitted. Similarly, only objects of a single machine
100 type are allowed. See the -32, -64 and -z target options, and the
101 LD_NOEXEC_64 environment variable.
102
103 Static Executables
104 The creation of static executables has been discouraged for many
105 releases. In fact, 64-bit system archive libraries have never been
106 provided. Because a static executable is built against system archive
107 libraries, the executable contains system implementation details. This
108 self-containment has a number of drawbacks.
109
110 o The executable is immune to the benefits of system patches
111 delivered as shared objects. The executable therefore, must
112 be rebuilt to take advantage of many system improvements.
113
114 o The ability of the executable to run on future releases can
115 be compromised.
116
117 o The duplication of system implementation details negatively
118 affects system performance.
119
120
121 With Solaris 10, 32-bit system archive libraries are no longer
122 provided. Without these libraries, specifically libc.a, the creation
123 of static executables is no longer achievable without specialized
124 system knowledge. However, the capability of ld to process static
125 linking options, and the processing of archive libraries, remains
126 unchanged.
127
128 OPTIONS
129 The following options are supported.
130
131 -32 | -64
132 Creates a 32-bit, or 64-bit object.
133
134 By default, the class of the object being generated is determined
135 from the first ELF object processed from the command line. If no
136 objects are specified, the class is determined by the first object
137 encountered within the first archive processed from the command
138 line. If there are no objects or archives, the link-editor creates a
139 32-bit object.
140
141 The -64 option is required to create a 64-bit object solely from a
142 mapfile.
143
144 This -32 or -64 options can also be used in the rare case of
145 linking entirely from an archive that contains a mixture of 32 and
146 64-bit objects. If the first object in the archive is not the class
147 of the object that is required to be created, then the -32 or -64
148 option can be used to direct the link-editor. See The 32-bit link-
149 editor and 64-bit link-editor in Linker and Libraries Guide.
150
151
152 -a
153 In static mode only, produces an executable object file. Undefined
154 references are not permitted. This option is the default behavior
155 for static mode. The -a option can not be used with the -r option.
156 See Static Executables under DESCRIPTION.
157
158
159 -b
160 In dynamic mode only, provides no special processing for dynamic
161 executable relocations that reference symbols in shared objects.
162 Without the -b option, the link-editor applies techniques within a
163 dynamic executable so that the text segment can remain read-only.
164 One technique is the creation of special position-independent
165 relocations for references to functions that are defined in shared
166 objects. Another technique arranges for data objects that are
167 defined in shared objects to be copied into the memory image of an
168 executable at runtime.
169
170 The -b option is intended for specialized dynamic objects and is not
171 recommended for general use. Its use suppresses all specialized
172 processing required to ensure an object's shareability, and can
173 even prevent the relocation of 64-bit executables.
174
175
176 -B direct | nodirect
177 These options govern direct binding. -B direct establishes direct
178 binding information by recording the relationship between each
179 symbol reference together with the dependency that provides the
180 definition. In addition, direct binding information is established
181 between each symbol reference and an associated definition within
182 the object being created. The runtime linker uses this information
183 to search directly for a symbol in the associated object rather
184 than to carry out a default symbol search.
185
186 Direct binding information can only be established to dependencies
187 specified with the link-edit. Thus, you should use the -z defs
188 option. Objects that wish to interpose on symbols in a direct
189 binding environment should identify themselves as interposers with
190 the -z interpose option. The use of -B direct enables -z lazyload for
191 all dependencies.
192
193 The -B nodirect option prevents any direct binding to the interfaces
194 offered by the object being created. The object being created can
195 continue to directly bind to external interfaces by specifying the
196 -z direct option. See Appendix D, Direct Bindings, in Linker and
197 Libraries Guide.
198
199
200 -B dynamic | static
201 Options governing library inclusion. -B dynamic is valid in dynamic
202 mode only. These options can be specified any number of times on
203 the command line as toggles: if the -B static option is given, no
204 shared objects are accepted until -B dynamic is seen. See the -l
205 option.
206
207
208 -B eliminate
209 Causes any global symbols, not assigned to a version definition, to
210 be eliminated from the symbol table. Version definitions can be
211 supplied by means of a mapfile to indicate the global symbols that
212 should remain visible in the generated object. This option achieves
213 the same symbol elimination as the auto-elimination directive that
214 is available as part of a mapfile version definition. This option
215 can be useful when combining versioned and non-versioned relocatable
216 objects. See also the -B local option and the -B reduce option. See
217 Defining Additional Symbols with a mapfile in Linker and Libraries
218 Guide.
219
220
221 -B group
222 Establishes a shared object and its dependencies as a group.
223 Objects within the group are bound to other members of the group at
224 runtime. This mode is similar to adding the object to the process
225 by using dlopen(3C) with the RTLD_GROUP mode. An object that has an
226 explicit dependency on a object identified as a group, becomes a
227 member of the group.
228
229 As the group must be self contained, use of the -B group option also
230 asserts the -z defs option.
231
232
233 -B local
234 Causes any global symbols, not assigned to a version definition, to
235 be reduced to local. Version definitions can be supplied by means
236 of a mapfile to indicate the global symbols that should remain
237 visible in the generated object. This option achieves the same
238 symbol reduction as the auto-reduction directive that is available
239 as part of a mapfile version definition. This option can be useful
240 when combining versioned and non-versioned relocatable objects. See
241 also the -B eliminate option and the -B reduce option. See Defining
242 Additional Symbols with a mapfile in Linker and Libraries Guide.
243
244
245 -B reduce
246 When generating a relocatable object, causes the reduction of
247 symbolic information defined by any version definitions. Version
248 definitions can be supplied by means of a mapfile to indicate the
249 global symbols that should remain visible in the generated object.
250 By default, when a relocatable object is generated, version
251 definitions are only recorded in the output image. The actual
252 reduction of symbolic information is carried out when the object is
253 used in the construction of a dynamic executable or shared object.
254 The -B reduce option is applied automatically when a dynamic
255 executable or shared object is created.
256
257
258 -B symbolic
259 In dynamic mode only. When building a shared object, binds
260 references to global symbols to their definitions, if available,
261 within the object. Normally, references to global symbols within
262 shared objects are not bound until runtime, even if definitions are
263 available. This model allows definitions of the same symbol in an
264 executable or other shared object to override the object's own
265 definition. ld issues warnings for undefined symbols unless -z defs
266 overrides.
267
268 The -B symbolic option is intended for specialized dynamic objects
269 and is not recommended for general use. To reduce the runtime
270 relocation processing that is required an object, the creation of a
271 version definition is recommended.
272
273
274 -c name
275 Records the configuration file name for use at runtime.
276 Configuration files can be employed to alter default search paths,
277 provide a directory cache, together with providing alternative
278 object dependencies. See crle(1).
279
280
281 -C
282 Demangles C++ symbol names displayed in diagnostic messages.
283
284
285 -d y | n
286 When -d y, the default, is specified, ld uses dynamic linking. When
287 -d n is specified, ld uses static linking. See Static Executables
288 under DESCRIPTION, and -B dynamic|static.
289
290
291 -D token,...
292 Prints debugging information as specified by each token, to the
293 standard error. The special token help indicates the full list of
294 tokens available. See Debugging Aids in Linker and Libraries Guide.
295
296
297 -e epsym
298 --entry epsym
299 Sets the entry point address for the output file to be the symbol
300 epsym.
301
302
303 -f name
304 --auxiliary name
305 Useful only when building a shared object. Specifies that the
306 symbol table of the shared object is used as an auxiliary filter on
307 the symbol table of the shared object specified by name. Multiple
308 instances of this option are allowed. This option can not be
309 combined with the -F option. See Generating Auxiliary Filters in
310 Linker and Libraries Guide.
311
312
313 -F name
314 --filter name
315 Useful only when building a shared object. Specifies that the
316 symbol table of the shared object is used as a filter on the symbol
317 table of the shared object specified by name. Multiple instances of
318 this option are allowed. This option can not be combined with the -f
319 option. See Generating Standard Filters in Linker and Libraries
320 Guide.
321
322
323 -G
324 -shared
325 In dynamic mode only, produces a shared object. Undefined symbols
326 are allowed. See Chapter 4, Shared Objects, in Linker and
327 Libraries Guide.
328
329
330 -h name
331 --soname name
332 In dynamic mode only, when building a shared object, records name
333 in the object's dynamic section. name is recorded in any dynamic
334 objects that are linked with this object rather than the object's
335 file system name. Accordingly, name is used by the runtime linker
336 as the name of the shared object to search for at runtime. See
337 Recording a Shared Object Name in Linker and Libraries Guide.
338
339
340 -i
341 Ignores LD_LIBRARY_PATH. This option is useful when an
342 LD_LIBRARY_PATH setting is in effect to influence the runtime
343 library search, which would interfere with the link-editing being
344 performed.
345
346
347 -I name
348 --dynamic-linker name
349 When building an executable, uses name as the path name of the
350 interpreter to be written into the program header. The default in
351 static mode is no interpreter. In dynamic mode, the default is the
352 name of the runtime linker, ld.so.1(1). Either case can be
353 overridden by -I name. exec(2) loads this interpreter when the
354 a.out is loaded, and passes control to the interpreter rather than
355 to the a.out directly.
356
357
358 -l x
359 --library x
360 Searches a library libx.so or libx.a, the conventional names for
361 shared object and archive libraries, respectively. In dynamic
362 mode, unless the -B static option is in effect, ld searches each
363 directory specified in the library search path for a libx.so or
364 libx.a file. The directory search stops at the first directory
365 containing either. ld chooses the file ending in .so if -lx expands
366 to two files with names of the form libx.so and libx.a. If no
367 libx.so is found, then ld accepts libx.a. In static mode, or when
368 the -B static option is in effect, ld selects only the file ending
369 in .a. ld searches a library when the library is encountered, so
370 the placement of -l is significant. See Linking With Additional
371 Libraries in Linker and Libraries Guide.
372
373
374 -L path
375 --library-path path
376 Adds path to the library search directories. ld searches for
377 libraries first in any directories specified by the -L options and
378 then in the standard directories. This option is useful only if the
379 option precedes the -l options to which the -L option applies. See
380 Directories Searched by the Link-Editor in Linker and Libraries
381 Guide.
382
383 The environment variable LD_LIBRARY_PATH can be used to supplement
384 the library search path, however the -L option is recommended, as
385 the environment variable is also interpreted by the runtime
386 environment. See LD_LIBRARY_PATH under ENVIRONMENT VARIABLES.
387
388
389 -m
390 Produces a memory map or listing of the input/output sections,
391 together with any non-fatal multiply-defined symbols, on the standard
392 output.
393
394
395 -M mapfile
396 Reads mapfile as a text file of directives to ld. This option can
397 be specified multiple times. If mapfile is a directory, then all
398 regular files, as defined by stat(2), within the directory are
399 processed. See Chapter 9, Mapfile Option, in Linker and Libraries
400 Guide. Example mapfiles are provided in /usr/lib/ld. See FILES.
401
402
403 -N string
404 This option causes a DT_NEEDED entry to be added to the .dynamic
405 section of the object being built. The value of the DT_NEEDED
406 string is the string that is specified on the command line. This
407 option is position dependent, and the DT_NEEDED .dynamic entry is
408 relative to the other dynamic dependencies discovered on the link-
409 edit line. This option is useful for specifying dependencies within
410 device driver relocatable objects when combined with the -dy and -r
411 options.
412
413
414 -o outfile
415 --output outfile
416 Produces an output object file that is named outfile. The name of
417 the default object file is a.out.
418
419
420 -p auditlib
421 Identifies an audit library, auditlib. This audit library is used
422 to audit the object being created at runtime. A shared object
423 identified as requiring auditing with the -p option, has this
424 requirement inherited by any object that specifies the shared
425 object as a dependency. See the -P option. See Runtime Linker
426 Auditing Interface in Linker and Libraries Guide.
427
428
429 -P auditlib
430 Identifies an audit library, auditlib. This audit library is used
431 to audit the dependencies of the object being created at runtime.
432 Dependency auditing can also be inherited from dependencies that
433 are identified as requiring auditing. See the -p option, and the -z
434 globalaudit option. See Runtime Linker Auditing Interface in Linker
435 and Libraries Guide.
436
437
438 -Q y | n
439 Under -Q y, an ident string is added to the .comment section of the
440 output file. This string identifies the version of the ld used to
441 create the file. This results in multiple ld idents when there have
442 been multiple linking steps, such as when using ld -r. This
443 identification is identical with the default action of the cc
444 command. -Q n suppresses version identification. .comment sections
445 can be manipulated by the mcs(1) utility.
446
447
448 -r
449 --relocatable
450 Combines relocatable object files to produce one relocatable object
451 file. ld does not complain about unresolved references. This
452 option cannot be used with the -a option.
453
454
455 -R path
456 -rpath path
457 A colon-separated list of directories used to specify library search
458 directories to the runtime linker. If present and not NULL, the
459 path is recorded in the output object file and passed to the
460 runtime linker. Multiple instances of this option are concatenated
461 together with each path separated by a colon. See Directories
462 Searched by the Runtime Linker in Linker and Libraries Guide.
463
464 The use of a runpath within an associated object is preferable to
465 setting global search paths such as through the LD_LIBRARY_PATH
466 environment variable. Only the runpaths that are necessary to find
467 the objects dependencies should be recorded. ldd(1) can also be
468 used to discover unused runpaths in dynamic objects, when used with
469 the -U option.
470
471 Various tokens can also be supplied with a runpath that provide a
472 flexible means of identifying system capabilities or an objects
473 location. See Appendix C, Establishing Dependencies with Dynamic
474 String Tokens, in Linker and Libraries Guide. The $ORIGIN token is
475 especially useful in allowing dynamic objects to be relocated to
476 different locations in the file system.
477
478
479 -s
480 --strip-all
481 Strips symbolic information from the output file. Any debugging
482 information, that is, .line, .debug*, and .stab* sections, and
483 their associated relocation entries are removed. Except for
484 relocatable files, a symbol table SHT_SYMTAB and its associated
485 string table section are not created in the output object file. The
486 elimination of a SHT_SYMTAB symbol table can reduce the .stab*
487 debugging information that is generated using the compiler drivers
488 -g option. See the -z redlocsym and -z noldynsym options.
489
490
491 -S supportlib
492 The shared object supportlib is loaded with ld and given
493 information regarding the linking process. Shared objects that are
494 defined by using the -S option can also be supplied using the
495 SGS_SUPPORT environment variable. See Link-Editor Support Interface
496 in Linker and Libraries Guide.
497
498
499 -t
500 Turns off the warning for multiply-defined symbols that have
501 different sizes or different alignments.
502
503
504 -u symname
505 --undefined symname
506 Enters symname as an undefined symbol in the symbol table. This
507 option is useful for loading entirely from an archive library. In
508 this instance, an unresolved reference is needed to force the
509 loading of the first routine. The placement of this option on the
510 command line is significant. This option must be placed before the
511 library that defines the symbol. See Defining Additional Symbols
512 with the u option in Linker and Libraries Guide.
513
514
515 -V
516 --version
517 Outputs a message giving information about the version of ld being
518 used.
519
520
521 -Y P,dirlist
522 Changes the default directories used for finding libraries. dirlist
523 is a colon-separated path list.
524
525
526 -z absexec
527 Useful only when building a dynamic executable. Specifies that
528 references to external absolute symbols should be resolved
529 immediately instead of being left for resolution at runtime. In
530 very specialized circumstances, this option removes text
531 relocations that can result in excessive swap space demands by an
532 executable.
533
534
535 -z allextract | defaultextract | weakextract
536 --whole-archive | --no-whole-archive
537 Alters the extraction criteria of objects from any archives that
538 follow. By default, archive members are extracted to satisfy
539 undefined references and to promote tentative definitions with data
540 definitions. Weak symbol references do not trigger extraction.
541 Under the -z allextract or --whole-archive options, all archive
542 members are extracted from the archive. Under -z weakextract, weak
543 references trigger archive extraction. The -z defaultextract or
544 --no-whole-archive options provide a means of returning to the
545 default following use of the former extract options. See Archive
546 Processing in Linker and Libraries Guide.
547
548
549 -z altexec64
550 Execute the 64-bit ld. The creation of very large 32-bit objects
551 can exhaust the virtual memory that is available to the 32-bit ld.
552 The -z altexec64 option can be used to force the use of the
553 associated 64-bit ld. The 64-bit ld provides a larger virtual
554 address space for building 32-bit objects. See The 32-bit link-
555 editor and 64-bit link-editor in Linker and Libraries Guide.
556
557
558 -z aslr[=state]
559 Specify whether the executable's address space should be randomized
560 on execution. If state is "enabled" randomization will always
561 occur when this executable is run (regardless of inherited
562 settings). If state is "disabled" randomization will never occur
563 when this executable is run. If state is omitted, ASLR is enabled.
564
565 An executable that should simple use the settings inherited from
566 its environment should not use this flag at all.
567
568
569 -z combreloc | nocombreloc
570 By default, ld combines multiple relocation sections when building
571 executables or shared objects. This section combination differs
572 from relocatable objects, in which relocation sections are
573 maintained in a one-to-one relationship with the sections to which
574 the relocations must be applied. The -z nocombreloc option disables
575 this merging of relocation sections, and preserves the one-to-one
576 relationship found in the original relocatable objects.
577
578 ld sorts the entries of data relocation sections by their symbol
579 reference. This sorting reduces runtime symbol lookup. When
580 multiple relocation sections are combined, this sorting produces
581 the least possible relocation overhead when objects are loaded into
582 memory, and speeds the runtime loading of dynamic objects.
583
584 Historically, the individual relocation sections were carried over
585 to any executable or shared object, and the -z combreloc option was
586 required to enable the relocation section merging previously
587 described. Relocation section merging is now the default. The -z
588 combreloc option is still accepted for the benefit of old build
589 environments, but the option is unnecessary, and has no effect.
590
591
592 -z assert-deflib
593 -z assert-deflib=libname
594 Enables warnings that check the location of where libraries passed
595 in with -l are found. If the link-editor finds a library on its
596 default search path it will emit a warning. This warning can be
597 made fatal in conjunction with the option -z fatal-warnings. Passing
598 libname white lists a library from this check. The library must be
599 the full name of the library, e.g. libc.so. To white list multiple
600 libraries, the -z assert-deflib=libname option can be repeated
601 multiple times. This option is useful when trying to build self-
602 contained objects where a referenced library might exist in the
603 default system library path and in alternate paths specified by -L,
604 but you only want the alternate paths to be used.
605
606
607 -z defs | nodefs
608 --no-undefined
609 The -z defs option and the --no-undefined option force a fatal error
610 if any undefined symbols remain at the end of the link. This mode
611 is the default when an executable is built. For historic reasons,
612 this mode is not the default when building a shared object. Use of
613 the -z defs option is recommended, as this mode assures the object
614 being built is self-contained. A self-contained object has all
615 symbolic references resolved internally, or to the object's
616 immediate dependencies.
617
618 The -z nodefs option allows undefined symbols. For historic reasons,
619 this mode is the default when a shared object is built. When used
620 with executables, the behavior of references to such undefined
621 symbols is unspecified. Use of the -z nodefs option is not
622 recommended.
623
624
625 -z direct | nodirect
626 Enables or disables direct binding to any dependencies that follow
627 on the command line. These options allow finer control over direct
628 binding than the global counterpart -B direct. The -z direct option
629 also differs from the -B direct option in the following areas.
630 Direct binding information is not established between a symbol
631 reference and an associated definition within the object being
632 created. Lazy loading is not enabled.
633
634
635 -z endfiltee
636 Marks a filtee so that when processed by a filter, the filtee
637 terminates any further filtee searches by the filter. See Reducing
638 Filtee Searches in Linker and Libraries Guide.
639
640
641 -z fatal-warnings | nofatal-warnings
642 --fatal-warnings | --no-fatal-warnings
643 Controls the behavior of warnings emitted from the link-editor.
644 Setting -z fatal-warnings promotes warnings emitted by the link-editor
645 to fatal errors that will cause the link-editor to fail before
646 linking. -z nofatal-warnings instead demotes these warnings such that
647 they will not cause the link-editor to exit prematurely.
648
649
650
651 -z finiarray=function
652 Appends an entry to the .finiarray section of the object being
653 built. If no .finiarray section is present, a section is created.
654 The new entry is initialized to point to function. See
655 Initialization and Termination Sections in Linker and Libraries
656 Guide.
657
658
659 -z globalaudit
660 This option supplements an audit library definition that has been
661 recorded with the -P option. This option is only meaningful when
662 building a dynamic executable. Audit libraries that are defined
663 within an object with the -P option typically allow for the auditing
664 of the immediate dependencies of the object. The -z globalaudit
665 promotes the auditor to a global auditor, thus allowing the
666 auditing of all dependencies. See Invoking the Auditing Interface
667 in Linker and Libraries Guide.
668
669 An auditor established with the -P option and the -z globalaudit
670 option, is equivalent to the auditor being established with the
671 LD_AUDIT environment variable. See ld.so.1(1).
672
673
674 -z groupperm | nogroupperm
675 Assigns, or deassigns each dependency that follows to a unique
676 group. The assignment of a dependency to a group has the same
677 effect as if the dependency had been built using the -B group
678 option.
679
680
681 -z guidance[=id1,id2...]
682 Give messages suggesting link-editor features that could improve the
683 resulting dynamic object.
684
685 Specific classes of suggestion can be silenced by specifying an
686 optional comma separated list of guidance identifiers.
687
688 The current classes of suggestion provided are:
689
690
691 Enable use of direct binding
692 Suggests that -z direct or -B direct be present prior to any
693 specified dependency. This allows predictable symbol binding
694 at runtime.
695
696 Can be disabled with -z guidance=nodirect
697
698
699 Enable lazy dependency loading
700 Suggests that -z lazyload be present prior to any specified
701 dependency. This allows the dynamic object to be loaded more
702 quickly.
703
704 Can be disabled with -z guidance=nolazyload.
705
706
707 Shared objects should define all their dependencies.
708 Suggests that -z defs be specified on the link-editor command
709 line. Shared objects that explicitly state all their
710 dependencies behave more predictably when used.
711
712 Can be be disabled with -z guidance=nodefs
713
714
715 Version 2 mapfile syntax
716 Suggests that any specified mapfiles use the more readable
717 version 2 syntax.
718
719 Can be disabled with -z guidance=nomapfile.
720
721
722 Read-only text segment
723 Should any runtime relocations within the text segment exist,
724 suggests that the object be compiled with position independent
725 code (PIC). Keeping large allocatable sections read-only allows
726 them to be shared between processes using a given shared
727 object.
728
729 Can be disabled with -z guidance=notext
730
731
732 No unused dependencies
733 Suggests that any dependency not referenced by the resulting
734 dynamic object be removed from the link-editor command line.
735
736 Can be disabled with -z guidance=nounused.
737
738
739 -z help
740 --help
741 Print a summary of the command line options on the standard output
742 and exit.
743
744
745 -z ignore | record
746 Ignores, or records, dynamic dependencies that are not referenced
747 as part of the link-edit. Ignores, or records, unreferenced ELF
748 sections from the relocatable objects that are read as part of the
749 link-edit. By default, -z record is in effect.
750
751 If an ELF section is ignored, the section is eliminated from the
752 output file being generated. A section is ignored when three
753 conditions are true. The eliminated section must contribute to an
754 allocatable segment. The eliminated section must provide no global
755 symbols. No other section from any object that contributes to the
756 link-edit, must reference an eliminated section.
757
758
759 -z initarray=function
760 Appends an entry to the .initarray section of the object being
761 built. If no .initarray section is present, a section is created.
762 The new entry is initialized to point to function. See
763 Initialization and Termination Sections in Linker and Libraries
764 Guide.
765
766
767 -z initfirst
768 Marks the object so that its runtime initialization occurs before
769 the runtime initialization of any other objects brought into the
770 process at the same time. In addition, the object runtime
771 finalization occurs after the runtime finalization of any other
772 objects removed from the process at the same time. This option is
773 only meaningful when building a shared object.
774
775
776 -z interpose
777 Marks the object as an interposer. At runtime, an object is
778 identified as an explicit interposer if the object has been tagged
779 using the -z interpose option. An explicit interposer is also
780 established when an object is loaded using the LD_PRELOAD
781 environment variable. Implicit interposition can occur because of
782 the load order of objects, however, this implicit interposition is
783 unknown to the runtime linker. Explicit interposition can ensure
784 that interposition takes place regardless of the order in which
785 objects are loaded. Explicit interposition also ensures that the
786 runtime linker searches for symbols in any explicit interposers
787 when direct bindings are in effect.
788
789
790 -z lazyload | nolazyload
791 Enables or disables the marking of dynamic dependencies to be
792 lazily loaded. Dynamic dependencies which are marked lazyload are
793 not loaded at initial process start-up. These dependencies are
794 delayed until the first binding to the object is made. Note: Lazy
795 loading requires the correct declaration of dependencies, together
796 with associated runpaths for each dynamic object used within a
797 process. See Lazy Loading of Dynamic Dependencies in Linker and
798 Libraries Guide.
799
800
801 -z ld32=arg1,arg2,...
802 -z ld64=arg1,arg2,...
803 The class of the link-editor is affected by the class of the output
804 file being created and by the capabilities of the underlying
805 operating system. The -z ld[32|64] options provide a means of
806 defining any link-editor argument. The defined argument is only
807 interpreted, respectively, by the 32-bit class or 64-bit class of
808 the link-editor.
809
810 For example, support libraries are class specific, so the correct
811 class of support library can be ensured using:
812
813 ld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...
814
815
816 The class of link-editor that is invoked is determined from the ELF
817 class of the first relocatable file that is seen on the command
818 line. This determination is carried out prior to any -z ld[32|64]
819 processing.
820
821
822 -z loadfltr
823 Marks a filter to indicate that filtees must be processed
824 immediately at runtime. Normally, filter processing is delayed
825 until a symbol reference is bound to the filter. The runtime
826 processing of an object that contains this flag mimics that which
827 occurs if the LD_LOADFLTR environment variable is in effect. See
828 the ld.so.1(1).
829
830
831 -z muldefs
832 --allow-multiple-definition
833 Allows multiple symbol definitions. By default, multiple symbol
834 definitions that occur between relocatable objects result in a
835 fatal error condition. This option, suppresses the error condition,
836 allowing the first symbol definition to be taken.
837
838
839 -z nocompstrtab
840 Disables the compression of ELF string tables. By default, string
841 compression is applied to SHT_STRTAB sections, and to SHT_PROGBITS
842 sections that have their SHF_MERGE and SHF_STRINGS section flags
843 set.
844
845
846 -z nodefaultlib
847 Marks the object so that the runtime default library search path,
848 used after any LD_LIBRARY_PATH or runpaths, is ignored. This option
849 implies that all dependencies of the object can be satisfied from
850 its runpath.
851
852
853 -z nodelete
854 Marks the object as non-deletable at runtime. This mode is similar
855 to adding the object to the process by using dlopen(3C) with the
856 RTLD_NODELETE mode.
857
858
859 -z nodlopen
860 Marks the object as not available to dlopen(3C), either as the
861 object specified by the dlopen(), or as any form of dependency
862 required by the object specified by the dlopen(). This option is
863 only meaningful when building a shared object.
864
865
866 -z nodump
867 Marks the object as not available to dldump(3C).
868
869
870 -z noldynsym
871 Prevents the inclusion of a .SUNW_ldynsym section in dynamic
872 executables or sharable libraries. The .SUNW_ldynsym section
873 augments the .dynsym section by providing symbols for local
874 functions. Local function symbols allow debuggers to display local
875 function names in stack traces from stripped programs. Similarly,
876 dladdr(3C) is able to supply more accurate results.
877
878 The -z noldynsym option also prevents the inclusion of the two
879 symbol sort sections that are related to the .SUNW_ldynsym section.
880 The .SUNW_dynsymsort section provides sorted access to regular
881 function and variable symbols. The .SUNW_dyntlssort section
882 provides sorted access to thread local storage (TLS) variable
883 symbols.
884
885 The .SUNW_ldynsym, .SUNW_dynsymsort, and .SUNW_dyntlssort sections,
886 which becomes part of the allocable text segment of the resulting
887 file, cannot be removed by strip(1). Therefore, the -z noldynsym
888 option is the only way to prevent their inclusion. See the -s and -z
889 redlocsym options.
890
891
892 -z nopartial
893 Partially initialized symbols, that are defined within relocatable
894 object files, are expanded in the output file being generated.
895
896
897 -z noversion
898 Does not record any versioning sections. Any version sections or
899 associated .dynamic section entries are not generated in the output
900 image.
901
902
903 -z now
904 Marks the object as requiring non-lazy runtime binding. This mode is
905 similar to adding the object to the process by using dlopen(3C)
906 with the RTLD_NOW mode. This mode is also similar to having the
907 LD_BIND_NOW environment variable in effect. See ld.so.1(1).
908
909
910 -z origin
911 Marks the object as requiring immediate $ORIGIN processing at
912 runtime. This option is only maintained for historic
913 compatibility, as the runtime analysis of objects to provide for
914 $ORIGIN processing is now default.
915
916
917 -z preinitarray=function
918 Appends an entry to the .preinitarray section of the object being
919 built. If no .preinitarray section is present, a section is
920 created. The new entry is initialized to point to function. See
921 Initialization and Termination Sections in Linker and Libraries
922 Guide.
923
924
925 -z redlocsym
926 Eliminates all local symbols except for the SECT symbols from the
927 symbol table SHT_SYMTAB. All relocations that refer to local
928 symbols are updated to refer to the corresponding SECT symbol. This
929 option allows specialized objects to greatly reduce their symbol
930 table sizes. Eliminated local symbols can reduce the .stab*
931 debugging information that is generated using the compiler drivers
932 -g option. See the -s and -z noldynsym options.
933
934
935 -z relaxreloc
936 ld normally issues a fatal error upon encountering a relocation
937 using a symbol that references an eliminated COMDAT section. If -z
938 relaxreloc is enabled, ld instead redirects such relocations to the
939 equivalent symbol in the COMDAT section that was kept. -z relaxreloc
940 is a specialized option, mainly of interest to compiler authors,
941 and is not intended for general use.
942
943
944 -z rescan-now
945 -z rescan
946 These options rescan the archive files that are provided to the
947 link-edit. By default, archives are processed once as the archives
948 appear on the command line. Archives are traditionally specified at
949 the end of the command line so that their symbol definitions
950 resolve any preceding references. However, specifying archives
951 multiple times to satisfy their own interdependencies can be
952 necessary.
953
954 -z rescan-now is a positional option, and is processed by the link-
955 editor immediately when encountered on the command line. All
956 archives seen on the command line up to that point are immediately
957 reprocessed in an attempt to locate additional archive members that
958 resolve symbol references. This archive rescanning is repeated
959 until a pass over the archives occurs in which no new members are
960 extracted.
961
962 -z rescan is a position independent option. The link-editor defers
963 the rescan operation until after it has processed the entire
964 command line, and then initiates a final rescan operation over all
965 archives seen on the command line. The -z rescan operation can
966 interact incorrectly with objects that contain
967 initialization (.init) or finalization (.fini) sections, preventing
968 the code in those sections from running. For this reason, -z rescan
969 is deprecated, and use of -z rescan-now is advised.
970
971
972 -z rescan-start ... -z rescan-end
973 --start-group ... --end-group
974 -( ... -)
975 Defines an archive rescan group. This is a positional construct,
976 and is processed by the link-editor immediately upon encountering
977 the closing delimiter option. Archives found within the group
978 delimiter options are reprocessed as a group in an attempt to
979 locate additional archive members that resolve symbol references.
980 This archive rescanning is repeated until a pass over the
981 archives On the occurs in which no new members are extracted.
982 Archive rescan groups cannot be nested.
983
984
985 -z target=sparc|x86
986 Specifies the machine type for the output object. Supported targets
987 are Sparc and x86. The 32-bit machine type for the specified target
988 is used unless the -64 option is also present, in which case the
989 corresponding 64-bit machine type is used. By default, the machine
990 type of the object being generated is determined from the first ELF
991 object processed from the command line. If no objects are
992 specified, the machine type is determined by the first object
993 encountered within the first archive processed from the command
994 line. If there are no objects or archives, the link-editor assumes
995 the native machine. This option is useful when creating an object
996 directly with ld whose input is solely from a mapfile. See the -M
997 option. It can also be useful in the rare case of linking entirely
998 from an archive that contains objects of different machine types
999 for which the first object is not of the desired machine type. See
1000 The 32-bit link-editor and 64-bit link-editor in Linker and Libraries
1001 Guide.
1002
1003
1004 -z text
1005 In dynamic mode only, forces a fatal error if any relocations
1006 against non-writable, allocatable sections remain. For historic
1007 reasons, this mode is not the default when building an executable
1008 or shared object. However, its use is recommended to ensure that
1009 the text segment of the dynamic object being built is shareable
1010 between multiple running processes. A shared text segment incurs
1011 the least relocation overhead when loaded into memory. See
1012 Position-Independent Code in Linker and Libraries Guide.
1013
1014
1015 -z textoff
1016 In dynamic mode only, allows relocations against all allocatable
1017 sections, including non-writable ones. This mode is the default when
1018 building a shared object.
1019
1020
1021 -z textwarn
1022 In dynamic mode only, lists a warning if any relocations against
1023 non-writable, allocatable sections remain. This mode is the default
1024 when building an executable.
1025
1026
1027 -z verbose
1028 This option provides additional warning diagnostics during a link-
1029 edit. Presently, this option conveys suspicious use of
1030 displacement relocations. This option also conveys the restricted
1031 use of static TLS relocations when building shared objects. In
1032 future, this option might be enhanced to provide additional
1033 diagnostics that are deemed too noisy to be generated by default.
1034
1035
1036 -zwrap=symbol
1037 -wrap= symbol
1038 --wrap= symbol
1039 Rename undefined references to symbol in order to allow wrapper
1040 code to be linked into the output object without having to modify
1041 source code. When -z wrap is specified, all undefined references to
1042 symbol are modified to reference __wrap_symbol, and all references
1043 to __real_symbol are modified to reference symbol. The user is
1044 expected to provide an object containing the __wrap_symbol
1045 function. This wrapper function can call __real_symbol in order to
1046 reference the actual function being wrapped.
1047
1048 The following is an example of a wrapper for the malloc(3C)
1049 function:
1050
1051 void *
1052 __wrap_malloc(size_t c)
1053 {
1054 (void) printf("malloc called with %zu\n", c);
1055 return (__real_malloc(c));
1056 }
1057
1058 If you link other code with this file using -z wrap=malloc to
1059 compile all the objects, then all calls to malloc will call the
1060 function __wrap_malloc instead. The call to __real_malloc will call
1061 the real malloc function.
1062
1063 The real and wrapped functions should be maintained in separate
1064 source files. Otherwise, the compiler or assembler may resolve the
1065 call instead of leaving that operation for the link-editor to carry
1066 out, and prevent the wrap from occurring.
1067
1068
1069 ENVIRONMENT VARIABLES
1070 LD_ALTEXEC
1071 An alternative link-editor path name. ld executes, and passes
1072 control to this alternative link-editor. This environment variable
1073 provides a generic means of overriding the default link-editor that
1074 is called from the various compiler drivers. See the -z altexec64
1075 option.
1076
1077
1078 LD_LIBRARY_PATH
1079 A list of directories in which to search for the libraries
1080 specified using the -l option. Multiple directories are separated by
1081 a colon. In the most general case, this environment variable
1082 contains two directory lists separated by a semicolon:
1083
1084 dirlist1;dirlist2
1085
1086
1087 If ld is called with any number of occurrences of -L, as in:
1088
1089 ld ... -Lpath1 ... -Lpathn ...
1090
1091
1092 then the search path ordering is:
1093
1094 dirlist1 path1 ... pathn dirlist2 LIBPATH
1095
1096
1097 When the list of directories does not contain a semicolon, the list
1098 is interpreted as dirlist2.
1099
1100 The LD_LIBRARY_PATH environment variable also affects the runtime
1101 linkers search for dynamic dependencies.
1102
1103 This environment variable can be specified with a _32 or _64
1104 suffix. This makes the environment variable specific, respectively,
1105 to 32-bit or 64-bit processes and overrides any non-suffixed version
1106 of the environment variable that is in effect.
1107
1108
1109 LD_NOEXEC_64
1110 Suppresses the automatic execution of the 64-bit link-editor. By
1111 default, the link-editor executes the 64-bit version when the ELF
1112 class of the first relocatable file identifies a 64-bit object. The
1113 64-bit image that a 32-bit link-editor can create, has some
1114 limitations. However, some link-edits might find the use of the
1115 32-bit link-editor faster.
1116
1117
1118 LD_OPTIONS
1119 A default set of options to ld. LD_OPTIONS is interpreted by ld
1120 just as though its value had been placed on the command line,
1121 immediately following the name used to invoke ld, as in:
1122
1123 ld $LD_OPTIONS ... other-arguments ...
1124
1125
1126
1127
1128 LD_RUN_PATH
1129 An alternative mechanism for specifying a runpath to the link-
1130 editor. See the -R option. If both LD_RUN_PATH and the -R option are
1131 specified, -R supersedes.
1132
1133
1134 SGS_SUPPORT
1135 Provides a colon-separated list of shared objects that are loaded
1136 with the link-editor and given information regarding the linking
1137 process. This environment variable can be specified with a _32 or
1138 _64 suffix. This makes the environment variable specific,
1139 respectively, to the 32-bit or 64-bit class of ld and overrides any
1140 non-suffixed version of the environment variable that is in effect.
1141 See the -S option.
1142
1143
1144
1145 Notice that environment variable-names that begin with the characters
1146 'LD_' are reserved for possible future enhancements to ld and
1147 ld.so.1(1).
1148
1149 FILES
1150 libx.so
1151 shared object libraries.
1152
1153
1154 libx.a
1155 archive libraries.
1156
1157
1158 a.out
1159 default output file.
1160
1161
1162 LIBPATH
1163 For 32-bit libraries, the default search path is
1164 /usr/ccs/lib, followed by /lib, and finally /usr/lib.
1165 For 64-bit libraries, the default search path is
1166 /lib/64, followed by /usr/lib/64.
1167
1168
1169 /usr/lib/ld
1170 A directory containing several mapfiles that can be used
1171 during link-editing. These mapfiles provide various
1172 capabilities, such as defining memory layouts, aligning
1173 bss, and defining non-executable stacks.
1174
1175
1176 ATTRIBUTES
1177 See attributes(5) for descriptions of the following attributes:
1178
1179
1180
1181
1182 +--------------------+-----------------+
1183 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
1184 +--------------------+-----------------+
1185 |Interface Stability | Committed |
1186 +--------------------+-----------------+
1187
1188 SEE ALSO
1189 as(1), crle(1), gprof(1), ld.so.1(1), ldd(1), mcs(1), pvs(1), exec(2),
1190 stat(2), dlopen(3C), dldump(3C), elf(3ELF), ar.h(3HEAD), a.out(4),
1191 attributes(5)
1192
1193
1194 Linker and Libraries Guide
1195
1196 NOTES
1197 Default options applied by ld are maintained for historic reasons. In
1198 today's programming environment, where dynamic objects dominate,
1199 alternative defaults would often make more sense. However, historic
1200 defaults must be maintained to ensure compatibility with existing
1201 program development environments. Historic defaults are called out
1202 wherever possible in this manual. For a description of the current
1203 recommended options, see Appendix A, Link-Editor Quick Reference, in
1204 Linker and Libraries Guide.
1205
1206
1207 If the file being created by ld already exists, the file is unlinked
1208 after all input files have been processed. A new file with the
1209 specified name is then created. This allows ld to create a new version
1210 of the file, while simultaneously allowing existing processes that are
1211 accessing the old file contents to continue running. If the old file
1212 has no other links, the disk space of the removed file is freed when
1213 the last process referencing the file terminates.
1214
1215
1216 The behavior of ld when the file being created already exists was
1217 changed with SXCE build 43. In older versions, the existing file was
1218 rewritten in place, an approach with the potential to corrupt any
1219 running processes that is using the file. This change has an
1220 implication for output files that have multiple hard links in the file
1221 system. Previously, all links would remain intact, with all links
1222 accessing the new file contents. The new ld behavior breaks such links,
1223 with the result that only the specified output file name references the
1224 new file. All the other links continue to reference the old file. To
1225 ensure consistent behavior, applications that rely on multiple hard
1226 links to linker output files should explicitly remove and relink the
1227 other file names.
1228
1229
1230
1231 September 10, 2013 LD(1)