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