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