1ld(1) User Commands ld(1)
2
6 ld - link-editor for object files
7
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 ]
18 [-z altexec64] [-z combreloc | nocombreloc ] [-z defs | nodefs]
19 [-z direct | nodirect] [-z endfiltee] [-z finiarray=function]
20 [-z globalaudit] [-z groupperm | nogroupperm] [-z help ]
21 [-z ignore | record] [-z initarray=function] [-z initfirst]
22 [-z interpose] [-z lazyload | nolazyload]
23 [-z ld32=arg1,arg2,...] [-z ld64=arg1,arg2,...]
24 [-z loadfltr] [-z muldefs] [-z nocompstrtab] [-z nodefaultlib]
25 [-z nodelete] [-z nodlopen] [-z nodump] [-z noldynsym]
26 [-z nopartial] [-z noversion] [-z now] [-z origin]
27 [-z preinitarray=function] [-z redlocsym] [-z relaxreloc]
28 [-z rescan-now] [-z recan] [-z rescan-start ... -z rescan-end]]
29 [-z target=sparc|x86] [-z text | textwarn | textoff]
30 [-z verbose] [-z wrap=symbol] filename...
31
34 The link-editor, ld, combines relocatable object files by resolving
35 symbol references to symbol definitions, together with performing relo‐
36 cations. ld operates in two modes, static or dynamic, as governed by
37 the -d option. In all cases, the output of ld is left in the file a.out
38 by default. See NOTES.
39 In dynamic mode, -dy, the default, relocatable object files that are
42 provided as arguments are combined to produce an executable object
43 file. This file is linked at execution with any shared object files
44 that are provided as arguments. If the -G option is specified, relocat‐
45 able object files are combined to produce a shared object. Without the
46 -G option, a dynamic executable is created.
47 In static mode, -dn, relocatable object files that are provided as
50 arguments are combined to produce a static executable file. If the -r
51 option is specified, relocatable object files are combined to produce
52 one relocatable object file. See Static Executables.
53 Dynamic linking is the most common model for combining relocatable
56 objects, and the eventual creation of processes within Solaris. This
57 environment tightly couples the work of the link-editor and the runtime
58 linker, ld.so.1(1). Both of these utilities, together with their
59 related technologies and utilities, are extensively documented in the
60 Linker and Libraries Guide.
61 If any argument is a library, ld by default searches the library
64 exactly once at the point the library is encountered on the argument
65 list. The library can be either a shared object or relocatable archive.
66 See ar.h(3HEAD)).
67 A shared object consists of an indivisible, whole unit that has been
70 generated by a previous link-edit of one or more input files. When the
71 link-editor processes a shared object, the entire contents of the
72 shared object become a logical part of the resulting output file image.
73 The shared object is not physically copied during the link-edit as its
74 actual inclusion is deferred until process execution. This logical
75 inclusion means that all symbol entries defined in the shared object
76 are made available to the link-editing process. See Chapter 4, Shared
77 Objects, in Linker and Libraries Guide
78 For an archive library, ld loads only those routines that define an
81 unresolved external reference. ld searches the symbol table of the ar‐
82 chive library sequentially to resolve external references that can be
83 satisfied by library members. This search is repeated until no external
84 references can be resolved by the archive. Thus, the order of members
85 in the library is functionally unimportant, unless multiple library
86 members exist that define the same external symbol. Archive libraries
87 that have interdependencies can require multiple command line defini‐
88 tions, or the use of one of the -z rescan options. See Archive Process‐
89 ing in Linker and Libraries Guide.
90 ld is a cross link-editor, able to link 32-bit objects or 64-bit
93 objects, for Sparc or x86 targets. ld uses the ELF class and machine
94 type of the first relocatable object on the command line to govern the
95 mode in which to operate. The mixing of 32-bit objects and 64-bit
96 objects is not permitted. Similarly, only objects of a single machine
97 type are allowed. See the -32, -64 and -z target options, and the
98 LD_NOEXEC_64 environment variable.
99 Static Executables
101 The creation of static executables has been discouraged for many
102 releases. In fact, 64-bit system archive libraries have never been pro‐
103 vided. Because a static executable is built against system archive
104 libraries, the executable contains system implementation details. This
105 self-containment has a number of drawbacks.
106 o The executable is immune to the benefits of system patches
108 delivered as shared objects. The executable therefore, must
109 be rebuilt to take advantage of many system improvements.
110 o The ability of the executable to run on future releases can
112 be compromised.
113 o The duplication of system implementation details negatively
115 affects system performance.
116 With Solaris 10, 32-bit system archive libraries are no longer pro‐
119 vided. Without these libraries, specifically libc.a, the creation of
120 static executables is no longer achievable without specialized system
121 knowledge. However, the capability of ld to process static linking
122 options, and the processing of archive libraries, remains unchanged.
123
125 The following options are supported.
126 -32 | -64
128 Creates a 32-bit, or 64-bit object.
130 By default, the class of the object being generated is determined
132 from the first ELF object processed from the command line. If no
133 objects are specified, the class is determined by the first object
134 encountered within the first archive processed from the command
135 line. If there are no objects or archives, the link-editor creates
136 a 32-bit object.
137 The -64 option is required to create a 64-bit object solely from a
139 mapfile.
140 This -32 or -64 options can also be used in the rare case of link‐
142 ing entirely from an archive that contains a mixture of 32 and
143 64-bit objects. If the first object in the archive is not the class
144 of the object that is required to be created, then the -32 or -64
145 option can be used to direct the link-editor. See The 32-bit link-
146 editor and 64-bit link-editor in Linker and Libraries Guide.
147 -a
150 In static mode only, produces an executable object file. Undefined
152 references are not permitted. This option is the default behavior
153 for static mode. The -a option can not be used with the -r option.
154 See Static Executables under DESCRIPTION.
155 -b
158 In dynamic mode only, provides no special processing for dynamic
160 executable relocations that reference symbols in shared objects.
161 Without the -b option, the link-editor applies techniques within a
162 dynamic executable so that the text segment can remain read-only.
163 One technique is the creation of special position-independent relo‐
164 cations for references to functions that are defined in shared
165 objects. Another technique arranges for data objects that are
166 defined in shared objects to be copied into the memory image of an
167 executable at runtime.
168 The -b option is intended for specialized dynamic objects and is
170 not recommended for general use. Its use suppresses all specialized
171 processing required to ensure an object's shareability, and can
172 even prevent the relocation of 64-bit executables.
173 -B direct | nodirect
176 These options govern direct binding. -B direct establishes direct
178 binding information by recording the relationship between each sym‐
179 bol reference together with the dependency that provides the defi‐
180 nition. 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 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 bind‐
189 ing environment should identify themselves as interposers with the
190 -z interpose option. The use of -B direct enables -z lazyload for
191 all dependencies.
192 The -B nodirect option prevents any direct binding to the inter‐
194 faces offered by the object being created. The object being created
195 can continue to directly bind to external interfaces by specifying
196 the -z direct option. See Appendix D, Direct Bindings, in Linker
197 and Libraries Guide.
198 -B dynamic | static
201 Options governing library inclusion. -B dynamic is valid in dynamic
203 mode only. These options can be specified any number of times on
204 the command line as toggles: if the -B static option is given, no
205 shared objects are accepted until -B dynamic is seen. See the -l
206 option.
207 -B eliminate
210 Causes any global symbols, not assigned to a version definition, to
212 be eliminated from the symbol table. Version definitions can be
213 supplied by means of a mapfile to indicate the global symbols that
214 should remain visible in the generated object. This option achieves
215 the same symbol elimination as the auto-elimination directive that
216 is available as part of a mapfile version definition. This option
217 can be useful when combining versioned and non-versioned relocat‐
218 able objects. See also the -B local option and the -B reduce
219 option. See Defining Additional Symbols with a mapfile in Linker
220 and Libraries Guide.
221 -B group
224 Establishes a shared object and its dependencies as a group.
226 Objects within the group are bound to other members of the group at
227 runtime. This mode is similar to adding the object to the process
228 by using dlopen(3C) with the RTLD_GROUP mode. An object that has an
229 explicit dependency on a object identified as a group, becomes a
230 member of the group.
231 As the group must be self contained, use of the -B group option
233 also asserts the -z defs option.
234 -B local
237 Causes any global symbols, not assigned to a version definition, to
239 be reduced to local. Version definitions can be supplied by means
240 of a mapfile to indicate the global symbols that should remain vis‐
241 ible in the generated object. This option achieves the same symbol
242 reduction as the auto-reduction directive that is available as part
243 of a mapfile version definition. This option can be useful when
244 combining versioned and non-versioned relocatable objects. See also
245 the -B eliminate option and the -B reduce option. See Defining
246 Additional Symbols with a mapfile in Linker and Libraries Guide.
247 -B reduce
250 When generating a relocatable object, causes the reduction of sym‐
252 bolic information defined by any version definitions. Version defi‐
253 nitions can be supplied by means of a mapfile to indicate the
254 global symbols that should remain visible in the generated object.
255 By default, when a relocatable object is generated, version defini‐
256 tions are only recorded in the output image. The actual reduction
257 of symbolic information is carried out when the object is used in
258 the construction of a dynamic executable or shared object. The -B
259 reduce option is applied automatically when a dynamic executable or
260 shared object is created.
261 -B symbolic
264 In dynamic mode only. When building a shared object, binds refer‐
266 ences to global symbols to their definitions, if available, within
267 the object. Normally, references to global symbols within shared
268 objects are not bound until runtime, even if definitions are avail‐
269 able. This model allows definitions of the same symbol in an exe‐
270 cutable or other shared object to override the object's own defini‐
271 tion. ld issues warnings for undefined symbols unless -z defs over‐
272 rides.
273 The -B symbolic option is intended for specialized dynamic objects
275 and is not recommended for general use. To reduce the runtime relo‐
276 cation processing that is required an object, the creation of a
277 version definition is recommended.
278 -c name
281 Records the configuration file name for use at runtime. Configura‐
283 tion files can be employed to alter default search paths, provide a
284 directory cache, together with providing alternative object depen‐
285 dencies. See crle(1).
286 -C
289 Demangles C++ symbol names displayed in diagnostic messages.
291 -d y | n
294 When -d y, the default, is specified, ld uses dynamic linking. When
296 -d n is specified, ld uses static linking. See Static Executables
297 under DESCRIPTION, and -B dynamic|static.
298 -D token,...
301 Prints debugging information as specified by each token, to the
303 standard error. The special token help indicates the full list of
304 tokens available. See Debugging Aids in Linker and Libraries Guide.
305 -e epsym
308 --entry epsym
309 Sets the entry point address for the output file to be the symbol
311 epsym.
312 -f name
315 --auxiliary name
316 Useful only when building a shared object. Specifies that the sym‐
318 bol table of the shared object is used as an auxiliary filter on
319 the symbol table of the shared object specified by name. Multiple
320 instances of this option are allowed. This option can not be com‐
321 bined with the -F option. See Generating Auxiliary Filters in
322 Linker and Libraries Guide.
323 -F name
326 --filter name
327 Useful only when building a shared object. Specifies that the sym‐
329 bol table of the shared object is used as a filter on the symbol
330 table of the shared object specified by name. Multiple instances of
331 this option are allowed. This option can not be combined with the
332 -f option. See Generating Standard Filters in Linker and Libraries
333 Guide.
334 -G
337 -shared
338 In dynamic mode only, produces a shared object. Undefined symbols
340 are allowed. See Chapter 4, Shared Objects, in Linker and Libraries
341 Guide.
342 -h name
345 --soname name
346 In dynamic mode only, when building a shared object, records name
348 in the object's dynamic section. name is recorded in any dynamic
349 objects that are linked with this object rather than the object's
350 file system name. Accordingly, name is used by the runtime linker
351 as the name of the shared object to search for at runtime. See
352 Recording a Shared Object Name in Linker and Libraries Guide.
353 -i
356 Ignores LD_LIBRARY_PATH. This option is useful when an
358 LD_LIBRARY_PATH setting is in effect to influence the runtime
359 library search, which would interfere with the link-editing being
360 performed.
361 -I name
364 --dynamic-linker name
365 When building an executable, uses name as the path name of the
367 interpreter to be written into the program header. The default in
368 static mode is no interpreter. In dynamic mode, the default is the
369 name of the runtime linker, ld.so.1(1). Either case can be overrid‐
370 den by -I name. exec(2) loads this interpreter when the a.out is
371 loaded, and passes control to the interpreter rather than to the
372 a.out directly.
373 -l x
376 --library x
377 Searches a library libx.so or libx.a, the conventional names for
379 shared object and archive libraries, respectively. In dynamic mode,
380 unless the -B static option is in effect, ld searches each direc‐
381 tory specified in the library search path for a libx.so or libx.a
382 file. The directory search stops at the first directory containing
383 either. ld chooses the file ending in .so if -lx expands to two
384 files with names of the form libx.so and libx.a. If no libx.so is
385 found, then ld accepts libx.a. In static mode, or when the -B
386 static option is in effect, ld selects only the file ending in .a.
387 ld searches a library when the library is encountered, so the
388 placement of -l is significant. See Linking With Additional
389 Libraries in Linker and Libraries Guide.
390 -L path
393 --library-path path
394 Adds path to the library search directories. ld searches for
396 libraries first in any directories specified by the -L options and
397 then in the standard directories. This option is useful only if the
398 option precedes the -l options to which the -L option applies. See
399 Directories Searched by the Link-Editor in Linker and Libraries
400 Guide.
401 The environment variable LD_LIBRARY_PATH can be used to supplement
403 the library search path, however the -L option is recommended, as
404 the environment variable is also interpreted by the runtime envi‐
405 ronment. See LD_LIBRARY_PATH under ENVIRONMENT VARIABLES.
406 -m
409 Produces a memory map or listing of the input/output sections,
411 together with any non-fatal multiply-defined symbols, on the stan‐
412 dard output.
413 -M mapfile
416 Reads mapfile as a text file of directives to ld. This option can
418 be specified multiple times. If mapfile is a directory, then all
419 regular files, as defined by stat(2), within the directory are pro‐
420 cessed. See Chapter 9, Mapfile Option, in Linker and Libraries
421 Guide. Example mapfiles are provided in /usr/lib/ld. See FILES.
422 -N string
425 This option causes a DT_NEEDED entry to be added to the .dynamic
427 section of the object being built. The value of the DT_NEEDED
428 string is the string that is specified on the command line. This
429 option is position dependent, and the DT_NEEDED .dynamic entry is
430 relative to the other dynamic dependencies discovered on the link-
431 edit line. This option is useful for specifying dependencies within
432 device driver relocatable objects when combined with the -dy and -r
433 options.
434 -o outfile
437 --output outfile
438 Produces an output object file that is named outfile. The name of
440 the default object file is a.out.
441 -p auditlib
444 Identifies an audit library, auditlib. This audit library is used
446 to audit the object being created at runtime. A shared object iden‐
447 tified as requiring auditing with the -p option, has this require‐
448 ment inherited by any object that specifies the shared object as a
449 dependency. See the -P option. See Runtime Linker Auditing Inter‐
450 face in Linker and Libraries Guide.
451 -P auditlib
454 Identifies an audit library, auditlib. This audit library is used
456 to audit the dependencies of the object being created at runtime.
457 Dependency auditing can also be inherited from dependencies that
458 are identified as requiring auditing. See the -p option, and the -z
459 globalaudit option. See Runtime Linker Auditing Interface in Linker
460 and Libraries Guide.
461 -Q y | n
464 Under -Q y, an ident string is added to the .comment section of the
466 output file. This string identifies the version of the ld used to
467 create the file. This results in multiple ld idents when there have
468 been multiple linking steps, such as when using ld -r. This identi‐
469 fication is identical with the default action of the cc command. -Q
470 n suppresses version identification. .comment sections can be
471 manipulated by the mcs(1) utility.
472 -r
475 --relocatable
476 Combines relocatable object files to produce one relocatable object
478 file. ld does not complain about unresolved references. This option
479 cannot be used with the -a option.
480 -R path
483 -rpath path
484 A colon-separated list of directories used to specify library
486 search directories to the runtime linker. If present and not NULL,
487 the path is recorded in the output object file and passed to the
488 runtime linker. Multiple instances of this option are concatenated
489 together with each path separated by a colon. See Directories
490 Searched by the Runtime Linker in Linker and Libraries Guide.
491 The use of a runpath within an associated object is preferable to
493 setting global search paths such as through the LD_LIBRARY_PATH
494 environment variable. Only the runpaths that are necessary to find
495 the objects dependencies should be recorded. ldd(1) can also be
496 used to discover unused runpaths in dynamic objects, when used with
497 the -U option.
498 Various tokens can also be supplied with a runpath that provide a
500 flexible means of identifying system capabilities or an objects
501 location. See Appendix C, Establishing Dependencies with Dynamic
502 String Tokens, in Linker and Libraries Guide. The $ORIGIN token is
503 especially useful in allowing dynamic objects to be relocated to
504 different locations in the file system.
505 -s
508 --strip-all
509 Strips symbolic information from the output file. Any debugging
511 information, that is, .line, .debug*, and .stab* sections, and
512 their associated relocation entries are removed. Except for relo‐
513 catable files, a symbol table SHT_SYMTAB and its associated string
514 table section are not created in the output object file. The elimi‐
515 nation of a SHT_SYMTAB symbol table can reduce the .stab* debugging
516 information that is generated using the compiler drivers -g option.
517 See the -z redlocsym and -z noldynsym options.
518 -S supportlib
521 The shared object supportlib is loaded with ld and given informa‐
523 tion regarding the linking process. Shared objects that are defined
524 by using the -S option can also be supplied using the SGS_SUPPORT
525 environment variable. See Link-Editor Support Interface in Linker
526 and Libraries Guide.
527 -t
530 Turns off the warning for multiply-defined symbols that have dif‐
532 ferent sizes or different alignments.
533 -u symname
536 --undefined symname
537 Enters symname as an undefined symbol in the symbol table. This
539 option is useful for loading entirely from an archive library. In
540 this instance, an unresolved reference is needed to force the load‐
541 ing of the first routine. The placement of this option on the com‐
542 mand line is significant. This option must be placed before the
543 library that defines the symbol. See Defining Additional Symbols
544 with the u option in Linker and Libraries Guide.
545 -V
548 --version
549 Outputs a message giving information about the version of ld being
551 used.
552 -Y P,dirlist
555 Changes the default directories used for finding libraries. dirlist
557 is a colon-separated path list.
558 -z absexec
561 Useful only when building a dynamic executable. Specifies that ref‐
563 erences to external absolute symbols should be resolved immediately
564 instead of being left for resolution at runtime. In very special‐
565 ized circumstances, this option removes text relocations that can
566 result in excessive swap space demands by an executable.
567 -z allextract | defaultextract | weakextract
570 --whole-archive | --no-whole-archive
571 Alters the extraction criteria of objects from any archives that
573 follow. By default, archive members are extracted to satisfy unde‐
574 fined references and to promote tentative definitions with data
575 definitions. Weak symbol references do not trigger extraction.
576 Under the -z allextract or --whole-archive options, all archive
577 members are extracted from the archive. Under -z weakextract, weak
578 references trigger archive extraction. The -z defaultextract or
579 --no-whole-archive options provide a means of returning to the
580 default following use of the former extract options. See Archive
581 Processing in Linker and Libraries Guide.
582 -z altexec64
585 Execute the 64-bit ld. The creation of very large 32-bit objects
587 can exhaust the virtual memory that is available to the 32-bit ld.
588 The -z altexec64 option can be used to force the use of the associ‐
589 ated 64-bit ld. The 64-bit ld provides a larger virtual address
590 space for building 32-bit objects. See The 32-bit link-editor and
591 64-bit link-editor in Linker and Libraries Guide.
592 -z combreloc | nocombreloc
595 By default, ld combines multiple relocation sections when building
597 executables or shared objects. This section combination differs
598 from relocatable objects, in which relocation sections are main‐
599 tained in a one-to-one relationship with the sections to which the
600 relocations must be applied. The -z nocombreloc option disables
601 this merging of relocation sections, and preserves the one-to-one
602 relationship found in the original relocatable objects.
603 ld sorts the entries of data relocation sections by their symbol
605 reference. This sorting reduces runtime symbol lookup. When multi‐
606 ple relocation sections are combined, this sorting produces the
607 least possible relocation overhead when objects are loaded into
608 memory, and speeds the runtime loading of dynamic objects.
609 Historically, the individual relocation sections were carried over
611 to any executable or shared object, and the -z combreloc option was
612 required to enable the relocation section merging previously
613 described. Relocation section merging is now the default. The -z
614 combreloc option is still accepted for the benefit of old build
615 environments, but the option is unnecessary, and has no effect.
616 -z defs | nodefs
619 --no-undefined
620 The -z defs option and the --no-undefined option force a fatal
622 error if any undefined symbols remain at the end of the link. This
623 mode is the default when an executable is built. For historic rea‐
624 sons, this mode is not the default when building a shared object.
625 Use of the -z defs option is recommended, as this mode assures the
626 object being built is self-contained. A self-contained object has
627 all symbolic references resolved internally, or to the object's
628 immediate dependencies.
629 The -z nodefs option allows undefined symbols. For historic rea‐
631 sons, this mode is the default when a shared object is built. When
632 used with executables, the behavior of references to such undefined
633 symbols is unspecified. Use of the -z nodefs option is not recom‐
634 mended.
635 -z direct | nodirect
638 Enables or disables direct binding to any dependencies that follow
640 on the command line. These options allow finer control over direct
641 binding than the global counterpart -B direct. The -z direct option
642 also differs from the -B direct option in the following areas.
643 Direct binding information is not established between a symbol ref‐
644 erence and an associated definition within the object being cre‐
645 ated. Lazy loading is not enabled.
646 -z endfiltee
649 Marks a filtee so that when processed by a filter, the filtee ter‐
651 minates any further filtee searches by the filter. See Reducing
652 Filtee Searches in Linker and Libraries Guide.
653 -z finiarray=function
656 Appends an entry to the .finiarray section of the object being
658 built. If no .finiarray section is present, a section is created.
659 The new entry is initialized to point to function. See Initializa‐
660 tion and Termination Sections in Linker and Libraries Guide.
661 -z globalaudit
664 This option supplements an audit library definition that has been
666 recorded with the -P option. This option is only meaningful when
667 building a dynamic executable. Audit libraries that are defined
668 within an object with the -P option typically allow for the audit‐
669 ing of the immediate dependencies of the object. The -z globalaudit
670 promotes the auditor to a global auditor, thus allowing the audit‐
671 ing of all dependencies. See Invoking the Auditing Interface in
672 Linker and Libraries Guide.
673 An auditor established with the -P option and the -z globalaudit
675 option, is equivalent to the auditor being established with the
676 LD_AUDIT environment variable. See ld.so.1(1).
677 -z groupperm | nogroupperm
680 Assigns, or deassigns each dependency that follows to a unique
682 group. The assignment of a dependency to a group has the same
683 effect as if the dependency had been built using the -B group
684 option.
685 -z help
688 --help
689 Print a summary of the command line options on the standard output
691 and exit.
692 -z ignore | record
695 Ignores, or records, dynamic dependencies that are not referenced
697 as part of the link-edit. Ignores, or records, unreferenced ELF
698 sections from the relocatable objects that are read as part of the
699 link-edit. By default, -z record is in effect.
700 If an ELF section is ignored, the section is eliminated from the
702 output file being generated. A section is ignored when three condi‐
703 tions are true. The eliminated section must contribute to an allo‐
704 catable segment. The eliminated section must provide no global sym‐
705 bols. No other section from any object that contributes to the
706 link-edit, must reference an eliminated section.
707 -z initarray=function
710 Appends an entry to the .initarray section of the object being
712 built. If no .initarray section is present, a section is created.
713 The new entry is initialized to point to function. See Initializa‐
714 tion and Termination Sections in Linker and Libraries Guide.
715 -z initfirst
718 Marks the object so that its runtime initialization occurs before
720 the runtime initialization of any other objects brought into the
721 process at the same time. In addition, the object runtime finaliza‐
722 tion occurs after the runtime finalization of any other objects
723 removed from the process at the same time. This option is only
724 meaningful when building a shared object.
725 -z interpose
728 Marks the object as an interposer. At runtime, an object is identi‐
730 fied as an explicit interposer if the object has been tagged using
731 the -z interpose option. An explicit interposer is also established
732 when an object is loaded using the LD_PRELOAD environment variable.
733 Implicit interposition can occur because of the load order of
734 objects, however, this implicit interposition is unknown to the
735 runtime linker. Explicit interposition can ensure that interposi‐
736 tion takes place regardless of the order in which objects are
737 loaded. Explicit interposition also ensures that the runtime linker
738 searches for symbols in any explicit interposers when direct bind‐
739 ings are in effect.
740 -z lazyload | nolazyload
743 Enables or disables the marking of dynamic dependencies to be
745 lazily loaded. Dynamic dependencies which are marked lazyload are
746 not loaded at initial process start-up. These dependencies are
747 delayed until the first binding to the object is made. Note: Lazy
748 loading requires the correct declaration of dependencies, together
749 with associated runpaths for each dynamic object used within a
750 process. See Lazy Loading of Dynamic Dependencies in Linker and
751 Libraries Guide.
752 -z ld32=arg1,arg2,...
755 -z ld64=arg1,arg2,...
756 The class of the link-editor is affected by the class of the output
758 file being created and by the capabilities of the underlying oper‐
759 ating system. The -z ld[32|64] options provide a means of defining
760 any link-editor argument. The defined argument is only interpreted,
761 respectively, by the 32-bit class or 64-bit class of the link-edi‐
762 tor.
763 For example, support libraries are class specific, so the correct
765 class of support library can be ensured using:
766 ld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...
768 The class of link-editor that is invoked is determined from the ELF
771 class of the first relocatable file that is seen on the command
772 line. This determination is carried out prior to any -z ld[32|64]
773 processing.
774 -z loadfltr
777 Marks a filter to indicate that filtees must be processed immedi‐
779 ately at runtime. Normally, filter processing is delayed until a
780 symbol reference is bound to the filter. The runtime processing of
781 an object that contains this flag mimics that which occurs if the
782 LD_LOADFLTR environment variable is in effect. See the ld.so.1(1).
783 -z muldefs
786 --allow-multiple-definition
787 Allows multiple symbol definitions. By default, multiple symbol
789 definitions that occur between relocatable objects result in a
790 fatal error condition. This option, suppresses the error condition,
791 allowing the first symbol definition to be taken.
792 -z nocompstrtab
795 Disables the compression of ELF string tables. By default, string
797 compression is applied to SHT_STRTAB sections, and to SHT_PROGBITS
798 sections that have their SHF_MERGE and SHF_STRINGS section flags
799 set.
800 -z nodefaultlib
803 Marks the object so that the runtime default library search path,
805 used after any LD_LIBRARY_PATH or runpaths, is ignored. This option
806 implies that all dependencies of the object can be satisfied from
807 its runpath.
808 -z nodelete
811 Marks the object as non-deletable at runtime. This mode is similar
813 to adding the object to the process by using dlopen(3C) with the
814 RTLD_NODELETE mode.
815 -z nodlopen
818 Marks the object as not available to dlopen(3C), either as the
820 object specified by the dlopen(), or as any form of dependency
821 required by the object specified by the dlopen(). This option is
822 only meaningful when building a shared object.
823 -z nodump
826 Marks the object as not available to dldump(3C).
828 -z noldynsym
831 Prevents the inclusion of a .SUNW_ldynsym section in dynamic exe‐
833 cutables or sharable libraries. The .SUNW_ldynsym section augments
834 the .dynsym section by providing symbols for local functions. Local
835 function symbols allow debuggers to display local function names in
836 stack traces from stripped programs. Similarly, dladdr(3C) is able
837 to supply more accurate results.
838 The -z noldynsym option also prevents the inclusion of the two sym‐
840 bol sort sections that are related to the .SUNW_ldynsym section.
841 The .SUNW_dynsymsort section provides sorted access to regular
842 function and variable symbols. The .SUNW_dyntlssort section pro‐
843 vides sorted access to thread local storage (TLS) variable symbols.
844 The .SUNW_ldynsym, .SUNW_dynsymsort, and .SUNW_dyntlssort sections,
846 which becomes part of the allocable text segment of the resulting
847 file, cannot be removed by strip(1). Therefore, the -z noldynsym
848 option is the only way to prevent their inclusion. See the -s and
849 -z redlocsym options.
850 -z nopartial
853 Partially initialized symbols, that are defined within relocatable
855 object files, are expanded in the output file being generated.
856 -z noversion
859 Does not record any versioning sections. Any version sections or
861 associated .dynamic section entries are not generated in the output
862 image.
863 -z now
866 Marks the object as requiring non-lazy runtime binding. This mode
868 is similar to adding the object to the process by using dlopen(3C)
869 with the RTLD_NOW mode. This mode is also similar to having the
870 LD_BIND_NOW environment variable in effect. See ld.so.1(1).
871 -z origin
874 Marks the object as requiring immediate $ORIGIN processing at run‐
876 time. This option is only maintained for historic compatibility, as
877 the runtime analysis of objects to provide for $ORIGIN processing
878 is now default.
879 -z preinitarray=function
882 Appends an entry to the .preinitarray section of the object being
884 built. If no .preinitarray section is present, a section is cre‐
885 ated. The new entry is initialized to point to function. See Ini‐
886 tialization and Termination Sections in Linker and Libraries Guide.
887 -z redlocsym
890 Eliminates all local symbols except for the SECT symbols from the
892 symbol table SHT_SYMTAB. All relocations that refer to local sym‐
893 bols are updated to refer to the corresponding SECT symbol. This
894 option allows specialized objects to greatly reduce their symbol
895 table sizes. Eliminated local symbols can reduce the .stab* debug‐
896 ging information that is generated using the compiler drivers -g
897 option. See the -s and -z noldynsym options.
898 -z relaxreloc
901 ld normally issues a fatal error upon encountering a relocation
903 using a symbol that references an eliminated COMDAT section. If -z
904 relaxreloc is enabled, ld instead redirects such relocations to the
905 equivalent symbol in the COMDAT section that was kept. -z relaxre‐
906 loc is a specialized option, mainly of interest to compiler
907 authors, and is not intended for general use.
908 -z rescan-now
911 -z rescan
912 These options rescan the archive files that are provided to the
914 link-edit. By default, archives are processed once as the archives
915 appear on the command line. Archives are traditionally specified at
916 the end of the command line so that their symbol definitions
917 resolve any preceding references. However, specifying archives mul‐
918 tiple times to satisfy their own interdependencies can be neces‐
919 sary.
920 -z rescan-now is a positional option, and is processed by the link-
922 editor immediately when encountered on the command line. All ar‐
923 chives seen on the command line up to that point are immediately
924 reprocessed in an attempt to locate additional archive members that
925 resolve symbol references. This archive rescanning is repeated
926 until a pass over the archives occurs in which no new members are
927 extracted.
928 -z rescan is a position independent option. The link-editor defers
930 the rescan operation until after it has processed the entire com‐
931 mand line, and then initiates a final rescan operation over all ar‐
932 chives seen on the command line. The -z rescan operation can inter‐
933 act incorrectly with objects that contain initialization
934 (.init) or finalization (.fini) sections, preventing the code in
935 those sections from running. For this reason, -z rescan is depre‐
936 cated, and use of -z rescan-now is advised.
937 -z rescan-start ... -z rescan-end
940 --start-group ... --end-group
941 -( ... -)
942 Defines an archive rescan group. This is a positional construct,
944 and is processed by the link-editor immediately upon encountering
945 the closing delimiter option. Archives found within the group
946 delimiter options are reprocessed as a group in an attempt to
947 locate additional archive members that resolve symbol references.
948 This archive rescanning is repeated until a pass over the ar‐
949 chives On the occurs in which no new members are extracted. Ar‐
950 chive rescan groups cannot be nested.
951 -z target=sparc|x86
954 Specifies the machine type for the output object. Supported targets
956 are Sparc and x86. The 32-bit machine type for the specified target
957 is used unless the -64 option is also present, in which case the
958 corresponding 64-bit machine type is used. By default, the machine
959 type of the object being generated is determined from the first ELF
960 object processed from the command line. If no objects are speci‐
961 fied, the machine type is determined by the first object encoun‐
962 tered within the first archive processed from the command line. If
963 there are no objects or archives, the link-editor assumes the
964 native machine. This option is useful when creating an object
965 directly with ld whose input is solely from a mapfile. See the -M
966 option. It can also be useful in the rare case of linking entirely
967 from an archive that contains objects of different machine types
968 for which the first object is not of the desired machine type. See
969 The 32-bit link-editor and 64-bit link-editor in Linker and
970 Libraries Guide.
971 -z text
974 In dynamic mode only, forces a fatal error if any relocations
976 against non-writable, allocatable sections remain. For historic
977 reasons, this mode is not the default when building an executable
978 or shared object. However, its use is recommended to ensure that
979 the text segment of the dynamic object being built is shareable
980 between multiple running processes. A shared text segment incurs
981 the least relocation overhead when loaded into memory. See Posi‐
982 tion-Independent Code in Linker and Libraries Guide.
983 -z textoff
986 In dynamic mode only, allows relocations against all allocatable
988 sections, including non-writable ones. This mode is the default
989 when building a shared object.
990 -z textwarn
993 In dynamic mode only, lists a warning if any relocations against
995 non-writable, allocatable sections remain. This mode is the default
996 when building an executable.
997 -z verbose
1000 This option provides additional warning diagnostics during a link-
1002 edit. Presently, this option conveys suspicious use of displacement
1003 relocations. This option also conveys the restricted use of static
1004 TLS relocations when building shared objects. In future, this
1005 option might be enhanced to provide additional diagnostics that are
1006 deemed too noisy to be generated by default.
1007 -zwrap=symbol
1010 -wrap= symbol
1011 --wrap= symbol
1012 Rename undefined references to symbol in order to allow wrapper
1014 code to be linked into the output object without having to modify
1015 source code. When -z wrap is specified, all undefined references to
1016 symbol are modified to reference __wrap_symbol, and all references
1017 to __real_symbol are modified to reference symbol. The user is
1018 expected to provide an object containing the __wrap_symbol func‐
1019 tion. This wrapper function can call __real_symbol in order to ref‐
1020 erence the actual function being wrapped.
1021 The following is an example of a wrapper for the malloc(3C) func‐
1023 tion:
1024 void *
1026 __wrap_malloc(size_t c)
1027 {
1028 (void) printf("malloc called with %zu0, c);
1029 return (__real_malloc(c));
1030 }
1031 If you link other code with this file using -z wrap=malloc to com‐
1033 pile all the objects, then all calls to malloc will call the func‐
1034 tion __wrap_malloc instead. The call to __real_malloc will call the
1035 real malloc function.
1036 The real and wrapped functions should be maintained in separate
1038 source files. Otherwise, the compiler or assembler may resolve the
1039 call instead of leaving that operation for the link-editor to carry
1040 out, and prevent the wrap from occurring.
1041
1044 LD_ALTEXEC
1045 An alternative link-editor path name. ld executes, and passes con‐
1047 trol to this alternative link-editor. This environment variable
1048 provides a generic means of overriding the default link-editor that
1049 is called from the various compiler drivers. See the -z altexec64
1050 option.
1051 LD_LIBRARY_PATH
1054 A list of directories in which to search for the libraries speci‐
1056 fied using the -l option. Multiple directories are separated by a
1057 colon. In the most general case, this environment variable contains
1058 two directory lists separated by a semicolon:
1059 dirlist1;dirlist2
1061 If ld is called with any number of occurrences of -L, as in:
1064 ld ... -Lpath1 ... -Lpathn ...
1066 then the search path ordering is:
1069 dirlist1 path1 ... pathn dirlist2 LIBPATH
1071 When the list of directories does not contain a semicolon, the list
1074 is interpreted as dirlist2.
1075 The LD_LIBRARY_PATH environment variable also affects the runtime
1077 linkers search for dynamic dependencies.
1078 This environment variable can be specified with a _32 or _64 suf‐
1080 fix. This makes the environment variable specific, respectively, to
1081 32-bit or 64-bit processes and overrides any non-suffixed version
1082 of the environment variable that is in effect.
1083 LD_NOEXEC_64
1086 Suppresses the automatic execution of the 64-bit link-editor. By
1088 default, the link-editor executes the 64-bit version when the ELF
1089 class of the first relocatable file identifies a 64-bit object. The
1090 64-bit image that a 32-bit link-editor can create, has some limita‐
1091 tions. However, some link-edits might find the use of the 32-bit
1092 link-editor faster.
1093 LD_OPTIONS
1096 A default set of options to ld. LD_OPTIONS is interpreted by ld
1098 just as though its value had been placed on the command line, imme‐
1099 diately following the name used to invoke ld, as in:
1100 ld $LD_OPTIONS ... other-arguments ...
1102 LD_RUN_PATH
1107 An alternative mechanism for specifying a runpath to the link-edi‐
1109 tor. See the -R option. If both LD_RUN_PATH and the -R option are
1110 specified, -R supersedes.
1111 SGS_SUPPORT
1114 Provides a colon-separated list of shared objects that are loaded
1116 with the link-editor and given information regarding the linking
1117 process. This environment variable can be specified with a _32 or
1118 _64 suffix. This makes the environment variable specific, respec‐
1119 tively, to the 32-bit or 64-bit class of ld and overrides any non-
1120 suffixed version of the environment variable that is in effect. See
1121 the -S option.
1122 Notice that environment variable-names that begin with the characters
1126 'LD_' are reserved for possible future enhancements to ld and
1127 ld.so.1(1).
1128
1130 libx.so shared object libraries.
1131 libx.a archive libraries.
1134 a.out default output file.
1137 LIBPATH For 32-bit libraries, the default search path is
1140 /usr/ccs/lib, followed by /lib, and finally /usr/lib.
1141 For 64-bit libraries, the default search path is
1142 /lib/64, followed by /usr/lib/64.
1143 /usr/lib/ld A directory containing several mapfiles that can be used
1146 during link-editing. These mapfiles provide various
1147 capabilities, such as defining memory layouts, aligning
1148 bss, and defining non-executable stacks.
1149
1152 See attributes(5) for descriptions of the following attributes:
1153 ┌─────────────────────────────┬─────────────────────────────┐
1158 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
1159 ├─────────────────────────────┼─────────────────────────────┤
1160 │Availability │SUNWtoo │
1161 ├─────────────────────────────┼─────────────────────────────┤
1162 │Interface Stability │Committed │
1163 └─────────────────────────────┴─────────────────────────────┘
1164
1166 as(1), crle(1), gprof(1), ld.so.1(1), ldd(1), mcs(1), pvs(1), exec(2),
1167 stat(2), dlopen(3C), dldump(3C), elf(3ELF), ar.h(3HEAD), a.out(4),
1168 attributes(5)
1169 Linker and Libraries Guide
1172
1174 Default options applied by ld are maintained for historic reasons. In
1175 today's programming environment, where dynamic objects dominate, alter‐
1176 native defaults would often make more sense. However, historic defaults
1177 must be maintained to ensure compatibility with existing program devel‐
1178 opment environments. Historic defaults are called out wherever possible
1179 in this manual. For a description of the current recommended options,
1180 see Appendix A, Link-Editor Quick Reference, in Linker and Libraries
1181 Guide.
1182 If the file being created by ld already exists, the file is unlinked
1185 after all input files have been processed. A new file with the speci‐
1186 fied name is then created. This allows ld to create a new version of
1187 the file, while simultaneously allowing existing processes that are
1188 accessing the old file contents to continue running. If the old file
1189 has no other links, the disk space of the removed file is freed when
1190 the last process referencing the file terminates.
1191 The behavior of ld when the file being created already exists was
1194 changed with SXCE build 43. In older versions, the existing file was
1195 rewritten in place, an approach with the potential to corrupt any run‐
1196 ning processes that is using the file. This change has an implication
1197 for output files that have multiple hard links in the file system. Pre‐
1198 viously, all links would remain intact, with all links accessing the
1199 new file contents. The new ld behavior breaks such links, with the
1200 result that only the specified output file name references the new
1201 file. All the other links continue to reference the old file. To ensure
1202 consistent behavior, applications that rely on multiple hard links to
1203 linker output files should explicitly remove and relink the other file
1204 names.
1205SunOS 5.11 18 Sep 2009 ld(1)