1 '\" te
2 .\" Copyright 1989 AT&T
3 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
4 .\" Copyright (c) 2012, Joyent, Inc. All Rights Reserved
5 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License. You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.
6 .\" See the License for the specific language governing permissions and limitations under the License. When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with
7 .\" the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
8 .TH LD 1 "May 13, 2017"
9 .SH NAME
10 ld \- link-editor for object files
11 .SH SYNOPSIS
12 .LP
13 .nf
14 \fBld\fR [\fB-32\fR | \fB-64\fR] [\fB-a\fR | \fB-r\fR] [\fB-b\fR] [\fB-B\fRdirect | nodirect]
15 [\fB-B\fR dynamic | static] [\fB-B\fR eliminate] [\fB-B\fR group] [\fB-B\fR local]
16 [\fB-B\fR reduce] [\fB-B\fR symbolic] [\fB-c\fR \fIname\fR] [\fB-C\fR] [\fB-d\fR y | n]
17 [\fB-D\fR \fItoken\fR,...] [\fB-e\fR \fIepsym\fR] [\fB-f\fR \fIname\fR | \fB-F\fR \fIname\fR] [\fB-G\fR] [\fB-h\fR \fIname\fR]
18 [\fB-i\fR] [\fB-I\fR \fIname\fR] [\fB-l\fR \fIx\fR] [\fB-L\fR \fIpath\fR] [\fB-m\fR] [\fB-M\fR \fImapfile\fR]
19 [\fB-N\fR \fIstring\fR] [\fB-o\fR \fIoutfile\fR] [\fB-p\fR \fIauditlib\fR] [\fB-P\fR \fIauditlib\fR]
20 [\fB-Q\fR y | n] [\fB-R\fR \fIpath\fR] [\fB-s\fR] [\fB-S\fR \fIsupportlib\fR] [\fB-t\fR]
21 [\fB-u\fR \fIsymname\fR] [\fB-V\fR] [\fB-Y P\fR\fI,dirlist\fR] [\fB-z\fR absexec]
22 [\fB-z\fR allextract | defaultextract | weakextract ] [\fB-z\fR altexec64]
23 [\fB-z\fR aslr[=\fIstate\fR]] [\fB-z\fR assert-deflib] [ \fB-z\fR assert-deflib=\fIlibname\fR]
24 [\fB-z\fR combreloc | nocombreloc ] [\fB-z\fR defs | nodefs]
25 [\fB-z\fR direct | nodirect] [\fB-z\fR endfiltee]
26 [\fB-z\fR fatal-warnings | nofatal-warnings ] [\fB-z\fR finiarray=\fIfunction\fR]
27 [\fB-z\fR globalaudit] [\fB-z\fR groupperm | nogroupperm]
28 [\fB-z\fR guidance[=\fIid1\fR,\fIid2\fR...] [\fB-z\fR help ]
29 [\fB-z\fR ignore | record] [\fB-z\fR initarray=\fIfunction\fR] [\fB-z\fR initfirst]
30 [\fB-z\fR interpose] [\fB-z\fR lazyload | nolazyload]
31 [\fB-z\fR ld32=\fIarg1\fR,\fIarg2\fR,...] [\fB-z\fR ld64=\fIarg1\fR,\fIarg2\fR,...]
32 [\fB-z\fR loadfltr] [\fB-z\fR muldefs] [\fB-z\fR nocompstrtab] [\fB-z\fR nodefaultlib]
33 [\fB-z\fR nodelete] [\fB-z\fR nodlopen] [\fB-z\fR nodump] [\fB-z\fR noldynsym]
34 [\fB-z\fR nopartial] [\fB-z\fR noversion] [\fB-z\fR now] [\fB-z\fR origin]
35 [\fB-z\fR preinitarray=\fIfunction\fR] [\fB-z\fR redlocsym] [\fB-z\fR relaxreloc]
36 [\fB-z\fR rescan-now] [\fB-z\fR recan] [\fB-z\fR rescan-start \fI\&...\fR \fB-z\fR rescan-end]]
37 [\fB-z\fR target=sparc|x86] [\fB-z\fR text | textwarn | textoff]
38 [\fB-z\fR type=\fIexec\fR|\fIkmod\fR|\fIreloc\fR|\fIshared\fR]
39 [\fB-z\fR verbose] [\fB-z\fR wrap=\fIsymbol\fR] \fIfilename\fR...
40 .fi
41
42 .SH DESCRIPTION
43 .LP
44 The link-editor, \fBld\fR, combines relocatable object files by resolving
45 symbol references to symbol definitions, together with performing relocations.
46 \fBld\fR operates in two modes, static or dynamic, as governed by the \fB-d\fR
47 option. In all cases, the output of \fBld\fR is left in the file \fBa.out\fR by
48 default. See NOTES.
49 .sp
50 .LP
51 In dynamic mode, \fB-dy\fR, the default, relocatable object files that are
52 provided as arguments are combined to produce an executable object file. This
53 file is linked at execution with any shared object files that are provided as
54 arguments. If the \fB-G\fR option is specified, relocatable object files are
55 combined to produce a shared object. Without the \fB-G\fR option, a dynamic
56 executable is created.
57 .sp
58 .LP
59 In static mode, \fB-dn\fR, relocatable object files that are provided as
60 arguments are combined to produce a static executable file. If the \fB-r\fR
61 option is specified, relocatable object files are combined to produce one
62 relocatable object file. See \fBStatic Executables\fR.
63 .sp
64 .LP
65 Dynamic linking is the most common model for combining relocatable objects, and
66 the eventual creation of processes within Solaris. This environment tightly
67 couples the work of the link-editor and the runtime linker, \fBld.so.1\fR(1).
68 Both of these utilities, together with their related technologies and
69 utilities, are extensively documented in the \fILinker and Libraries Guide\fR.
70 .sp
71 .LP
72 If any argument is a library, \fBld\fR by default searches the library exactly
73 once at the point the library is encountered on the argument list. The library
74 can be either a shared object or relocatable archive. See \fBar.h\fR(3HEAD)).
75 .sp
76 .LP
77 A shared object consists of an indivisible, whole unit that has been generated
78 by a previous link-edit of one or more input files. When the link-editor
79 processes a shared object, the entire contents of the shared object become a
80 logical part of the resulting output file image. The shared object is not
81 physically copied during the link-edit as its actual inclusion is deferred
82 until process execution. This logical inclusion means that all symbol entries
83 defined in the shared object are made available to the link-editing process.
84 See Chapter 4, \fIShared Objects,\fR in \fILinker and Libraries Guide\fR
85 .sp
86 .LP
87 For an archive library, \fBld\fR loads only those routines that define an
88 unresolved external reference. \fBld\fR searches the symbol table of the
89 archive library sequentially to resolve external references that can be
90 satisfied by library members. This search is repeated until no external
91 references can be resolved by the archive. Thus, the order of members in the
92 library is functionally unimportant, unless multiple library members exist that
93 define the same external symbol. Archive libraries that have interdependencies
94 can require multiple command line definitions, or the use of one of the
95 \fB-z\fR \fBrescan\fR options. See \fIArchive Processing\fR in \fILinker and
96 Libraries Guide\fR.
97 .sp
98 .LP
99 \fBld\fR is a cross link-editor, able to link 32-bit objects or 64-bit objects,
100 for Sparc or x86 targets. \fBld\fR uses the \fBELF\fR class and machine type of
101 the first relocatable object on the command line to govern the mode in which to
102 operate. The mixing of 32-bit objects and 64-bit objects is not permitted.
103 Similarly, only objects of a single machine type are allowed. See the
104 \fB-32\fR, \fB-64\fR and \fB-z target\fR options, and the \fBLD_NOEXEC_64\fR
105 environment variable.
106 .SS "Static Executables"
107 .LP
108 The creation of static executables has been discouraged for many releases. In
109 fact, 64-bit system archive libraries have never been provided. Because a
110 static executable is built against system archive libraries, the executable
111 contains system implementation details. This self-containment has a number of
112 drawbacks.
113 .RS +4
114 .TP
115 .ie t \(bu
116 .el o
117 The executable is immune to the benefits of system updates delivered as shared
118 objects. The executable therefore, must be rebuilt to take advantage of many
119 system improvements.
120 .RE
121 .RS +4
122 .TP
123 .ie t \(bu
124 .el o
125 The ability of the executable to run on future releases can be compromised.
126 .RE
127 .RS +4
128 .TP
129 .ie t \(bu
130 .el o
131 The duplication of system implementation details negatively affects system
132 performance.
133 .RE
134 .sp
135 .LP
136 With Solaris 10, 32-bit system archive libraries are no longer provided.
137 Without these libraries, specifically \fBlibc.a\fR, the creation of static
138 executables is no longer achievable without specialized system knowledge.
139 However, the capability of \fBld\fR to process static linking options, and the
140 processing of archive libraries, remains unchanged.
141 .SH OPTIONS
142 .LP
143 The following options are supported.
144 .sp
145 .ne 2
146 .na
147 \fB\fB-32\fR | \fB-64\fR\fR
148 .ad
149 .sp .6
150 .RS 4n
151 Creates a 32-bit, or 64-bit object.
152 .sp
153 By default, the class of the object being generated is determined from the
154 first \fBELF\fR object processed from the command line. If no objects are
155 specified, the class is determined by the first object encountered within the
156 first archive processed from the command line. If there are no objects or
157 archives, the link-editor creates a 32-bit object.
158 .sp
159 The \fB-64\fR option is required to create a 64-bit object solely from a
160 mapfile.
161 .sp
162 This \fB-32\fR or \fB-64\fR options can also be used in the rare case of
163 linking entirely from an archive that contains a mixture of 32 and 64-bit
164 objects. If the first object in the archive is not the class of the object that
165 is required to be created, then the \fB-32\fR or \fB-64\fR option can be used
166 to direct the link-editor. See \fIThe 32-bit link-editor and 64-bit
167 link-editor\fR in \fILinker and Libraries Guide\fR.
168 .RE
169
170 .sp
171 .ne 2
172 .na
173 \fB\fB-a\fR\fR
174 .ad
175 .sp .6
176 .RS 4n
177 In static mode only, produces an executable object file. Undefined references
178 are not permitted. This option is the default behavior for static mode. The
179 \fB-a\fR option can not be used with the \fB-r\fR option. See \fBStatic
180 Executables\fR under DESCRIPTION.
181 .RE
182
183 .sp
184 .ne 2
185 .na
186 \fB\fB-b\fR\fR
187 .ad
188 .sp .6
189 .RS 4n
190 In dynamic mode only, provides no special processing for dynamic executable
191 relocations that reference symbols in shared objects. Without the \fB-b\fR
192 option, the link-editor applies techniques within a dynamic executable so that
193 the text segment can remain read-only. One technique is the creation of special
194 position-independent relocations for references to functions that are defined
195 in shared objects. Another technique arranges for data objects that are defined
196 in shared objects to be copied into the memory image of an executable at
197 runtime.
198 .sp
199 The \fB-b\fR option is intended for specialized dynamic objects and is not
200 recommended for general use. Its use suppresses all specialized processing
201 required to ensure an object's shareability, and can even prevent the
202 relocation of 64-bit executables.
203 .RE
204
205 .sp
206 .ne 2
207 .na
208 \fB\fB-B\fR \fBdirect\fR | \fBnodirect\fR\fR
209 .ad
210 .sp .6
211 .RS 4n
212 These options govern direct binding. \fB-B\fR \fBdirect\fR establishes direct
213 binding information by recording the relationship between each symbol reference
214 together with the dependency that provides the definition. In addition, direct
215 binding information is established between each symbol reference and an
216 associated definition within the object being created. The runtime linker uses
217 this information to search directly for a symbol in the associated object
218 rather than to carry out a default symbol search.
219 .sp
220 Direct binding information can only be established to dependencies specified
221 with the link-edit. Thus, you should use the \fB-z\fR \fBdefs\fR option.
222 Objects that wish to interpose on symbols in a direct binding environment
223 should identify themselves as interposers with the \fB-z\fR \fBinterpose\fR
224 option. The use of \fB-B\fR \fBdirect\fR enables \fB-z\fR \fBlazyload\fR for
225 all dependencies.
226 .sp
227 The \fB-B\fR \fBnodirect\fR option prevents any direct binding to the
228 interfaces offered by the object being created. The object being created can
229 continue to directly bind to external interfaces by specifying the \fB-z\fR
230 \fBdirect\fR option. See Appendix D, \fIDirect Bindings,\fR in \fILinker and
231 Libraries Guide\fR.
232 .RE
233
234 .sp
235 .ne 2
236 .na
237 \fB\fB-B\fR \fBdynamic\fR | \fBstatic\fR\fR
238 .ad
239 .sp .6
240 .RS 4n
241 Options governing library inclusion. \fB-B\fR \fBdynamic\fR is valid in dynamic
242 mode only. These options can be specified any number of times on the command
243 line as toggles: if the \fB-B\fR \fBstatic\fR option is given, no shared
244 objects are accepted until \fB-B\fR \fBdynamic\fR is seen. See the \fB-l\fR
245 option.
246 .RE
247
248 .sp
249 .ne 2
250 .na
251 \fB\fB-B\fR \fBeliminate\fR\fR
252 .ad
253 .sp .6
254 .RS 4n
255 Causes any global symbols, not assigned to a version definition, to be
256 eliminated from the symbol table. Version definitions can be supplied by means
257 of a \fBmapfile\fR to indicate the global symbols that should remain visible in
258 the generated object. This option achieves the same symbol elimination as the
259 \fIauto-elimination\fR directive that is available as part of a \fBmapfile\fR
260 version definition. This option can be useful when combining versioned and
261 non-versioned relocatable objects. See also the \fB-B\fR \fBlocal\fR option and
262 the \fB-B\fR \fBreduce\fR option. See \fIDefining Additional Symbols with a
263 mapfile\fR in \fILinker and Libraries Guide\fR.
264 .RE
265
266 .sp
267 .ne 2
268 .na
269 \fB\fB-B\fR \fBgroup\fR\fR
270 .ad
271 .sp .6
272 .RS 4n
273 Establishes a shared object and its dependencies as a group. Objects within the
274 group are bound to other members of the group at runtime. This mode is similar
275 to adding the object to the process by using \fBdlopen\fR(3C) with the
276 \fBRTLD_GROUP\fR mode. An object that has an explicit dependency on a object
277 identified as a group, becomes a member of the group.
278 .sp
279 As the group must be self contained, use of the \fB-B\fR \fBgroup\fR option
280 also asserts the \fB-z\fR \fBdefs\fR option.
281 .RE
282
283 .sp
284 .ne 2
285 .na
286 \fB\fB-B\fR \fBlocal\fR\fR
287 .ad
288 .sp .6
289 .RS 4n
290 Causes any global symbols, not assigned to a version definition, to be reduced
291 to local. Version definitions can be supplied by means of a \fBmapfile\fR to
292 indicate the global symbols that should remain visible in the generated object.
293 This option achieves the same symbol reduction as the \fIauto-reduction\fR
294 directive that is available as part of a \fBmapfile\fR version definition. This
295 option can be useful when combining versioned and non-versioned relocatable
296 objects. See also the \fB-B\fR \fBeliminate\fR option and the \fB-B\fR
297 \fBreduce\fR option. See \fIDefining Additional Symbols with a mapfile\fR in
298 \fILinker and Libraries Guide\fR.
299 .RE
300
301 .sp
302 .ne 2
303 .na
304 \fB\fB-B\fR \fBreduce\fR\fR
305 .ad
306 .sp .6
307 .RS 4n
308 When generating a relocatable object, causes the reduction of symbolic
309 information defined by any version definitions. Version definitions can be
310 supplied by means of a \fBmapfile\fR to indicate the global symbols that should
311 remain visible in the generated object. By default, when a relocatable object
312 is generated, version definitions are only recorded in the output image. The
313 actual reduction of symbolic information is carried out when the object is used
314 in the construction of a dynamic executable or shared object. The \fB-B\fR
315 \fBreduce\fR option is applied automatically when a dynamic executable or
316 shared object is created.
317 .RE
318
319 .sp
320 .ne 2
321 .na
322 \fB\fB-B\fR \fBsymbolic\fR\fR
323 .ad
324 .sp .6
325 .RS 4n
326 In dynamic mode only. When building a shared object, binds references to global
327 symbols to their definitions, if available, within the object. Normally,
328 references to global symbols within shared objects are not bound until runtime,
329 even if definitions are available. This model allows definitions of the same
330 symbol in an executable or other shared object to override the object's own
331 definition. \fBld\fR issues warnings for undefined symbols unless \fB-z\fR
332 \fBdefs\fR overrides.
333 .sp
334 The \fB-B\fR \fBsymbolic\fR option is intended for specialized dynamic objects
335 and is not recommended for general use. To reduce the runtime relocation
336 processing that is required an object, the creation of a version definition is
337 recommended.
338 .RE
339
340 .sp
341 .ne 2
342 .na
343 \fB\fB-c\fR \fIname\fR\fR
344 .ad
345 .sp .6
346 .RS 4n
347 Records the configuration file \fIname\fR for use at runtime. Configuration
348 files can be employed to alter default search paths, provide a directory cache,
349 together with providing alternative object dependencies. See \fBcrle\fR(1).
350 .RE
351
352 .sp
353 .ne 2
354 .na
355 \fB\fB-C\fR\fR
356 .ad
357 .sp .6
358 .RS 4n
359 Demangles C++ symbol names displayed in diagnostic messages.
360 .RE
361
362 .sp
363 .ne 2
364 .na
365 \fB\fB-d\fR \fBy\fR | \fBn\fR\fR
366 .ad
367 .sp .6
368 .RS 4n
369 When \fB-d\fR \fBy\fR, the default, is specified, \fBld\fR uses dynamic
370 linking. When \fB-d\fR \fBn\fR is specified, \fBld\fR uses static linking. See
371 \fBStatic Executables\fR under DESCRIPTION, and \fB-B\fR
372 \fBdynamic\fR|\fBstatic\fR.
373 .RE
374
375 .sp
376 .ne 2
377 .na
378 \fB\fB-D\fR \fItoken\fR,...\fR
379 .ad
380 .sp .6
381 .RS 4n
382 Prints debugging information as specified by each \fItoken\fR, to the standard
383 error. The special token \fBhelp\fR indicates the full list of tokens
384 available. See \fIDebugging Aids\fR in \fILinker and Libraries Guide\fR.
385 .RE
386
387 .sp
388 .ne 2
389 .na
390 \fB\fB-e\fR \fIepsym\fR\fR
391 .ad
392 .br
393 .na
394 \fB\fB--entry\fR \fIepsym\fR\fR
395 .ad
396 .sp .6
397 .RS 4n
398 Sets the entry point address for the output file to be the symbol \fIepsym\fR.
399 .RE
400
401 .sp
402 .ne 2
403 .na
404 \fB\fB-f\fR \fIname\fR\fR
405 .ad
406 .br
407 .na
408 \fB\fB--auxiliary\fR \fIname\fR\fR
409 .ad
410 .sp .6
411 .RS 4n
412 Useful only when building a shared object. Specifies that the symbol table of
413 the shared object is used as an auxiliary filter on the symbol table of the
414 shared object specified by \fIname\fR. Multiple instances of this option are
415 allowed. This option can not be combined with the \fB-F\fR option. See
416 \fIGenerating Auxiliary Filters\fR in \fILinker and Libraries Guide\fR.
417 .RE
418
419 .sp
420 .ne 2
421 .na
422 \fB\fB-F\fR \fIname\fR\fR
423 .ad
424 .br
425 .na
426 \fB\fB--filter\fR \fIname\fR\fR
427 .ad
428 .sp .6
429 .RS 4n
430 Useful only when building a shared object. Specifies that the symbol table of
431 the shared object is used as a filter on the symbol table of the shared object
432 specified by \fIname\fR. Multiple instances of this option are allowed. This
433 option can not be combined with the \fB-f\fR option. See \fIGenerating Standard
434 Filters\fR in \fILinker and Libraries Guide\fR.
435 .RE
436
437 .sp
438 .ne 2
439 .na
440 \fB\fB-G\fR\fR
441 .ad
442 .br
443 .na
444 \fB\fB-shared\fR\fR
445 .ad
446 .sp .6
447 .RS 4n
448 In dynamic mode only, produces a shared object. Undefined symbols are allowed.
449 See Chapter 4, \fIShared Objects,\fR in \fILinker and Libraries Guide\fR.
450 .RE
451
452 .sp
453 .ne 2
454 .na
455 \fB\fB-h\fR \fIname\fR\fR
456 .ad
457 .br
458 .na
459 \fB\fB--soname\fR \fIname\fR\fR
460 .ad
461 .sp .6
462 .RS 4n
463 In dynamic mode only, when building a shared object, records \fIname\fR in the
464 object's dynamic section. \fIname\fR is recorded in any dynamic objects that
465 are linked with this object rather than the object's file system name.
466 Accordingly, \fIname\fR is used by the runtime linker as the name of the shared
467 object to search for at runtime. See \fIRecording a Shared Object Name\fR in
468 \fILinker and Libraries Guide\fR.
469 .RE
470
471 .sp
472 .ne 2
473 .na
474 \fB\fB-i\fR\fR
475 .ad
476 .sp .6
477 .RS 4n
478 Ignores \fBLD_LIBRARY_PATH\fR. This option is useful when an
479 \fBLD_LIBRARY_PATH\fR setting is in effect to influence the runtime library
480 search, which would interfere with the link-editing being performed.
481 .RE
482
483 .sp
484 .ne 2
485 .na
486 \fB\fB-I\fR \fIname\fR\fR
487 .ad
488 .br
489 .na
490 \fB\fB--dynamic-linker\fR \fIname\fR\fR
491 .ad
492 .sp .6
493 .RS 4n
494 When building an executable, uses \fIname\fR as the path name of the
495 interpreter to be written into the program header. The default in static mode
496 is no interpreter. In dynamic mode, the default is the name of the runtime
497 linker, \fBld.so.1\fR(1). Either case can be overridden by \fB-I\fR \fIname\fR.
498 \fBexec\fR(2) loads this interpreter when the \fBa.out\fR is loaded, and passes
499 control to the interpreter rather than to the \fBa.out\fR directly.
500 .RE
501
502 .sp
503 .ne 2
504 .na
505 \fB\fB-l\fR \fIx\fR\fR
506 .ad
507 .br
508 .na
509 \fB\fB--library\fR \fIx\fR\fR
510 .ad
511 .sp .6
512 .RS 4n
513 Searches a library \fBlib\fR\fIx\fR\fB\&.so\fR or \fBlib\fR\fIx\fR\fB\&.a\fR,
514 the conventional names for shared object and archive libraries, respectively.
515 In dynamic mode, unless the \fB-B\fR \fBstatic\fR option is in effect, \fBld\fR
516 searches each directory specified in the library search path for a
517 \fBlib\fR\fIx\fR\fB\&.so\fR or \fBlib\fR\fIx\fR\fB\&.a\fR file. The directory
518 search stops at the first directory containing either. \fBld\fR chooses the
519 file ending in \fB\&.so\fR if \fB-l\fR\fIx\fR expands to two files with names
520 of the form \fBlib\fR\fIx\fR\fB\&.so\fR and \fBlib\fR\fIx\fR\fB\&.a\fR. If no
521 \fBlib\fR\fIx\fR\fB\&.so\fR is found, then \fBld\fR accepts
522 \fBlib\fR\fIx\fR\fB\&.a\fR. In static mode, or when the \fB-B\fR \fBstatic\fR
523 option is in effect, \fBld\fR selects only the file ending in \fB\&.a\fR.
524 \fBld\fR searches a library when the library is encountered, so the placement
525 of \fB-l\fR is significant. See \fILinking With Additional Libraries\fR in
526 \fILinker and Libraries Guide\fR.
527 .RE
528
529 .sp
530 .ne 2
531 .na
532 \fB\fB-L\fR \fIpath\fR\fR
533 .ad
534 .br
535 .na
536 \fB\fB--library-path\fR \fIpath\fR\fR
537 .ad
538 .sp .6
539 .RS 4n
540 Adds \fIpath\fR to the library search directories. \fBld\fR searches for
541 libraries first in any directories specified by the \fB-L\fR options and then
542 in the standard directories. This option is useful only if the option precedes
543 the \fB-l\fR options to which the \fB-L\fR option applies. See \fIDirectories
544 Searched by the Link-Editor\fR in \fILinker and Libraries Guide\fR.
545 .sp
546 The environment variable \fBLD_LIBRARY_PATH\fR can be used to supplement the
547 library search path, however the \fB-L\fR option is recommended, as the
548 environment variable is also interpreted by the runtime environment. See
549 \fBLD_LIBRARY_PATH\fR under ENVIRONMENT VARIABLES.
550 .RE
551
552 .sp
553 .ne 2
554 .na
555 \fB\fB-m\fR\fR
556 .ad
557 .sp .6
558 .RS 4n
559 Produces a memory map or listing of the input/output sections, together with
560 any non-fatal multiply-defined symbols, on the standard output.
561 .RE
562
563 .sp
564 .ne 2
565 .na
566 \fB\fB-M\fR \fImapfile\fR\fR
567 .ad
568 .sp .6
569 .RS 4n
570 Reads \fImapfile\fR as a text file of directives to \fBld\fR. This option can
571 be specified multiple times. If \fImapfile\fR is a directory, then all regular
572 files, as defined by \fBstat\fR(2), within the directory are processed. See
573 Chapter 9, \fIMapfile Option,\fR in \fILinker and Libraries Guide\fR. Example
574 mapfiles are provided in \fB/usr/lib/ld\fR. See FILES.
575 .RE
576
577 .sp
578 .ne 2
579 .na
580 \fB\fB-N\fR \fIstring\fR\fR
581 .ad
582 .sp .6
583 .RS 4n
584 This option causes a \fBDT_NEEDED\fR entry to be added to the \fB\&.dynamic\fR
585 section of the object being built. The value of the \fBDT_NEEDED\fR string is
586 the \fIstring\fR that is specified on the command line. This option is position
587 dependent, and the \fBDT_NEEDED\fR \fB\&.dynamic\fR entry is relative to the
588 other dynamic dependencies discovered on the link-edit line. This option is
589 useful for specifying dependencies within device driver relocatable objects
590 when combined with the \fB-dy\fR and \fB-r\fR options.
591 .RE
592
593 .sp
594 .ne 2
595 .na
596 \fB\fB-o\fR \fIoutfile\fR\fR
597 .ad
598 .br
599 .na
600 \fB\fB--output\fR \fIoutfile\fR\fR
601 .ad
602 .sp .6
603 .RS 4n
604 Produces an output object file that is named \fIoutfile\fR. The name of the
605 default object file is \fBa.out\fR.
606 .RE
607
608 .sp
609 .ne 2
610 .na
611 \fB\fB-p\fR \fIauditlib\fR\fR
612 .ad
613 .sp .6
614 .RS 4n
615 Identifies an audit library, \fIauditlib\fR. This audit library is used to
616 audit the object being created at runtime. A shared object identified as
617 requiring auditing with the \fB-p\fR option, has this requirement inherited by
618 any object that specifies the shared object as a dependency. See the \fB-P\fR
619 option. See \fIRuntime Linker Auditing Interface\fR in \fILinker and Libraries
620 Guide\fR.
621 .RE
622
623 .sp
624 .ne 2
625 .na
626 \fB\fB-P\fR \fIauditlib\fR\fR
627 .ad
628 .sp .6
629 .RS 4n
630 Identifies an audit library, \fIauditlib\fR. This audit library is used to
631 audit the dependencies of the object being created at runtime. Dependency
632 auditing can also be inherited from dependencies that are identified as
633 requiring auditing. See the \fB-p\fR option, and the \fB-z\fR \fBglobalaudit\fR
634 option. See \fIRuntime Linker Auditing Interface\fR in \fILinker and Libraries
635 Guide\fR.
636 .RE
637
638 .sp
639 .ne 2
640 .na
641 \fB\fB-Q\fR \fBy\fR | \fBn\fR\fR
642 .ad
643 .sp .6
644 .RS 4n
645 Under \fB-Q\fR \fBy\fR, an \fBident\fR string is added to the \fB\&.comment\fR
646 section of the output file. This string identifies the version of the \fBld\fR
647 used to create the file. This results in multiple \fBld\fR \fBidents\fR when
648 there have been multiple linking steps, such as when using \fBld\fR \fB-r\fR.
649 This identification is identical with the default action of the \fBcc\fR
650 command. \fB-Q\fR \fBn\fR suppresses version identification. \fB\&.comment\fR
651 sections can be manipulated by the \fBmcs\fR(1) utility.
652 .RE
653
654 .sp
655 .ne 2
656 .na
657 \fB\fB-r\fR\fR
658 .ad
659 .br
660 .na
661 \fB\fB--relocatable\fR\fR
662 .ad
663 .sp .6
664 .RS 4n
665 Combines relocatable object files to produce one relocatable object file.
666 \fBld\fR does not complain about unresolved references. This option cannot be
667 used with the \fB-a\fR option.
668 .RE
669
670 .sp
671 .ne 2
672 .na
673 \fB\fB-R\fR \fIpath\fR\fR
674 .ad
675 .br
676 .na
677 \fB\fB-rpath\fR \fIpath\fR\fR
678 .ad
679 .sp .6
680 .RS 4n
681 A colon-separated list of directories used to specify library search
682 directories to the runtime linker. If present and not NULL, the path is
683 recorded in the output object file and passed to the runtime linker. Multiple
684 instances of this option are concatenated together with each \fIpath\fR
685 separated by a colon. See \fIDirectories Searched by the Runtime Linker\fR in
686 \fILinker and Libraries Guide\fR.
687 .sp
688 The use of a runpath within an associated object is preferable to setting
689 global search paths such as through the \fBLD_LIBRARY_PATH\fR environment
690 variable. Only the runpaths that are necessary to find the objects dependencies
691 should be recorded. \fBldd\fR(1) can also be used to discover unused runpaths
692 in dynamic objects, when used with the \fB-U\fR option.
693 .sp
694 Various tokens can also be supplied with a runpath that provide a flexible
695 means of identifying system capabilities or an objects location. See Appendix
696 C, \fIEstablishing Dependencies with Dynamic String Tokens,\fR in \fILinker and
697 Libraries Guide\fR. The \fB$ORIGIN\fR token is especially useful in allowing
698 dynamic objects to be relocated to different locations in the file system.
699 .RE
700
701 .sp
702 .ne 2
703 .na
704 \fB\fB-s\fR\fR
705 .ad
706 .br
707 .na
708 \fB\fB--strip-all\fR\fR
709 .ad
710 .sp .6
711 .RS 4n
712 Strips symbolic information from the output file. Any debugging information,
713 that is, \fB\&.line\fR, \fB\&.debug*\fR, and \fB\&.stab*\fR sections, and their
714 associated relocation entries are removed. Except for relocatable files, a
715 symbol table \fBSHT_SYMTAB\fR and its associated string table section are not
716 created in the output object file. The elimination of a \fBSHT_SYMTAB\fR symbol
717 table can reduce the \fB\&.stab*\fR debugging information that is generated
718 using the compiler drivers \fB-g\fR option. See the \fB-z\fR \fBredlocsym\fR
719 and \fB-z\fR \fBnoldynsym\fR options.
720 .RE
721
722 .sp
723 .ne 2
724 .na
725 \fB\fB-S\fR \fIsupportlib\fR\fR
726 .ad
727 .sp .6
728 .RS 4n
729 The shared object \fIsupportlib\fR is loaded with \fBld\fR and given
730 information regarding the linking process. Shared objects that are defined by
731 using the \fB-S\fR option can also be supplied using the \fBSGS_SUPPORT\fR
732 environment variable. See \fILink-Editor Support Interface\fR in \fILinker and
733 Libraries Guide\fR.
734 .RE
735
736 .sp
737 .ne 2
738 .na
739 \fB\fB-t\fR\fR
740 .ad
741 .sp .6
742 .RS 4n
743 Turns off the warning for multiply-defined symbols that have different sizes or
744 different alignments.
745 .RE
746
747 .sp
748 .ne 2
749 .na
750 \fB\fB-u\fR \fIsymname\fR\fR
751 .ad
752 .br
753 .na
754 \fB\fB--undefined\fR \fIsymname\fR\fR
755 .ad
756 .sp .6
757 .RS 4n
758 Enters \fIsymname\fR as an undefined symbol in the symbol table. This option is
759 useful for loading entirely from an archive library. In this instance, an
760 unresolved reference is needed to force the loading of the first routine. The
761 placement of this option on the command line is significant. This option must
762 be placed before the library that defines the symbol. See \fIDefining
763 Additional Symbols with the u option\fR in \fILinker and Libraries Guide\fR.
764 .RE
765
766 .sp
767 .ne 2
768 .na
769 \fB\fB-V\fR\fR
770 .ad
771 .br
772 .na
773 \fB\fB--version\fR\fR
774 .ad
775 .sp .6
776 .RS 4n
777 Outputs a message giving information about the version of \fBld\fR being used.
778 .RE
779
780 .sp
781 .ne 2
782 .na
783 \fB\fB-Y\fR \fBP,\fR\fIdirlist\fR\fR
784 .ad
785 .sp .6
786 .RS 4n
787 Changes the default directories used for finding libraries. \fIdirlist\fR is a
788 colon-separated path list.
789 .RE
790
791 .sp
792 .ne 2
793 .na
794 \fB\fB-z\fR \fBabsexec\fR\fR
795 .ad
796 .sp .6
797 .RS 4n
798 Useful only when building a dynamic executable. Specifies that references to
799 external absolute symbols should be resolved immediately instead of being left
800 for resolution at runtime. In very specialized circumstances, this option
801 removes text relocations that can result in excessive swap space demands by an
802 executable.
803 .RE
804
805 .sp
806 .ne 2
807 .na
808 \fB\fB-z\fR \fBallextract\fR | \fBdefaultextract\fR | \fBweakextract\fR\fR
809 .ad
810 .br
811 .na
812 \fB\fB--whole-archive\fR | \fB--no-whole-archive\fR\fR
813 .ad
814 .sp .6
815 .RS 4n
816 Alters the extraction criteria of objects from any archives that follow. By
817 default, archive members are extracted to satisfy undefined references and to
818 promote tentative definitions with data definitions. Weak symbol references do
819 not trigger extraction. Under the \fB-z\fR \fBallextract\fR or
820 \fB--whole-archive\fR options, all archive members are extracted from the
821 archive. Under \fB-z\fR \fBweakextract\fR, weak references trigger archive
822 extraction. The \fB-z\fR \fBdefaultextract\fR or \fB--no-whole-archive\fR
823 options provide a means of returning to the default following use of the former
824 extract options. See \fIArchive Processing\fR in \fILinker and Libraries
825 Guide\fR.
826 .RE
827
828 .sp
829 .ne 2
830 .na
831 \fB\fB-z\fR \fBaltexec64\fR\fR
832 .ad
833 .sp .6
834 .RS 4n
835 Execute the 64-bit \fBld\fR. The creation of very large 32-bit objects can
836 exhaust the virtual memory that is available to the 32-bit \fBld\fR. The
837 \fB-z\fR \fBaltexec64\fR option can be used to force the use of the associated
838 64-bit \fBld\fR. The 64-bit \fBld\fR provides a larger virtual address space
839 for building 32-bit objects. See \fIThe 32-bit link-editor and 64-bit
840 link-editor\fR in \fILinker and Libraries Guide\fR.
841 .RE
842
843 .sp
844 .ne 2
845 .na
846 \fB-z\fR \fBaslr[=\fIstate\fR]\fR
847 .ad
848 .sp .6
849 .RS 4n
850 Specify whether the executable's address space should be randomized on
851 execution. If \fIstate\fR is "enabled" randomization will always occur when
852 this executable is run (regardless of inherited settings). If \fIstate\fR is
853 "disabled" randomization will never occur when this executable is run. If
854 \fIstate\fR is omitted, ASLR is enabled.
855
856 An executable that should simply use the settings inherited from its
857 environment should not use this flag at all.
858 .RE
859
860 .sp
861 .ne 2
862 .na
863 \fB\fB-z\fR \fBcombreloc\fR | \fBnocombreloc\fR\fR
864 .ad
865 .sp .6
866 .RS 4n
867 By default, \fBld\fR combines multiple relocation sections when building
868 executables or shared objects. This section combination differs from
869 relocatable objects, in which relocation sections are maintained in a
870 one-to-one relationship with the sections to which the relocations must be
871 applied. The \fB-z\fR \fBnocombreloc\fR option disables this merging of
872 relocation sections, and preserves the one-to-one relationship found in the
873 original relocatable objects.
874 .sp
875 \fBld\fR sorts the entries of data relocation sections by their symbol
876 reference. This sorting reduces runtime symbol lookup. When multiple relocation
877 sections are combined, this sorting produces the least possible relocation
878 overhead when objects are loaded into memory, and speeds the runtime loading of
879 dynamic objects.
880 .sp
881 Historically, the individual relocation sections were carried over to any
882 executable or shared object, and the \fB-z\fR \fBcombreloc\fR option was
883 required to enable the relocation section merging previously described.
884 Relocation section merging is now the default. The \fB-z\fR \fBcombreloc\fR
885 option is still accepted for the benefit of old build environments, but the
886 option is unnecessary, and has no effect.
887 .RE
888
889 .sp
890 .ne 2
891 .na
892 \fB\fB-z\fR \fBassert-deflib\fR\fR
893 .ad
894 .br
895 .na
896 \fB\fB-z\fR \fBassert-deflib=\fR\fIlibname\fR\fR
897 .ad
898 .sp .6
899 .RS 4n
900 Enables warnings that check the location of where libraries passed in with
901 \fB-l\fR are found. If the link-editor finds a library on its default search
902 path it will emit a warning. This warning can be made fatal in conjunction with
903 the option \fB-z fatal-warnings\fR. Passing \fIlibname\fR white lists a library
904 from this check. The library must be the full name of the library, e.g.
905 \fIlibc.so\fR. To white list multiple libraries, the \fB-z
906 assert-deflib=\fR\fIlibname\fR option can be repeated multiple times. This
907 option is useful when trying to build self-contained objects where a referenced
908 library might exist in the default system library path and in alternate paths
909 specified by \fB-L\fR, but you only want the alternate paths to be used.
910 .RE
911
912 .sp
913 .ne 2
914 .na
915 \fB\fB-z\fR \fBdefs\fR | \fBnodefs\fR\fR
916 .ad
917 .br
918 .na
919 \fB\fB--no-undefined\fR\fR
920 .ad
921 .sp .6
922 .RS 4n
923 The \fB-z\fR \fBdefs\fR option and the \fB--no-undefined\fR option force a
924 fatal error if any undefined symbols remain at the end of the link. This mode
925 is the default when an executable is built. For historic reasons, this mode is
926 \fBnot\fR the default when building a shared object. Use of the \fB-z\fR
927 \fBdefs\fR option is recommended, as this mode assures the object being built
928 is self-contained. A self-contained object has all symbolic references resolved
929 internally, or to the object's immediate dependencies.
930 .sp
931 The \fB-z\fR \fBnodefs\fR option allows undefined symbols. For historic
932 reasons, this mode is the default when a shared object is built. When used with
933 executables, the behavior of references to such undefined symbols is
934 unspecified. Use of the \fB-z\fR \fBnodefs\fR option is not recommended.
935 .RE
936
937 .sp
938 .ne 2
939 .na
940 \fB\fB-z\fR \fBdirect\fR | \fBnodirect\fR\fR
941 .ad
942 .sp .6
943 .RS 4n
944 Enables or disables direct binding to any dependencies that follow on the
945 command line. These options allow finer control over direct binding than the
946 global counterpart \fB-B\fR \fBdirect\fR. The \fB-z\fR \fBdirect\fR option also
947 differs from the \fB-B\fR \fBdirect\fR option in the following areas. Direct
948 binding information is not established between a symbol reference and an
949 associated definition within the object being created. Lazy loading is not
950 enabled.
951 .RE
952
953 .sp
954 .ne 2
955 .na
956 \fB\fB-z\fR \fBendfiltee\fR\fR
957 .ad
958 .sp .6
959 .RS 4n
960 Marks a filtee so that when processed by a filter, the filtee terminates any
961 further filtee searches by the filter. See \fIReducing Filtee Searches\fR in
962 \fILinker and Libraries Guide\fR.
963 .RE
964
965 .sp
966 .ne 2
967 .na
968 \fB\fB-z\fR \fBfatal-warnings\fR | \fBnofatal-warnings\fR\fR
969 .ad
970 .br
971 .na
972 \fB\fB--fatal-warnings\fR | \fB--no-fatal-warnings\fR
973 .ad
974 .sp .6
975 .RS 4n
976 Controls the behavior of warnings emitted from the link-editor. Setting \fB-z
977 fatal-warnings\fR promotes warnings emitted by the link-editor to fatal errors
978 that will cause the link-editor to fail before linking. \fB-z
979 nofatal-warnings\fR instead demotes these warnings such that they will not cause
980 the link-editor to exit prematurely.
981 .RE
982
983
984 .sp
985 .ne 2
986 .na
987 \fB\fB-z\fR \fBfiniarray=\fR\fIfunction\fR\fR
988 .ad
989 .sp .6
990 .RS 4n
991 Appends an entry to the \fB\&.fini_array\fR section of the object being built.
992 If no \fB\&.fini_array\fR section is present, a section is created. The new
993 entry is initialized to point to \fIfunction\fR. See \fIInitialization and
994 Termination Sections\fR in \fILinker and Libraries Guide\fR.
995 .RE
996
997 .sp
998 .ne 2
999 .na
1000 \fB\fB-z\fR \fBglobalaudit\fR\fR
1001 .ad
1002 .sp .6
1003 .RS 4n
1004 This option supplements an audit library definition that has been recorded with
1005 the \fB-P\fR option. This option is only meaningful when building a dynamic
1006 executable. Audit libraries that are defined within an object with the \fB-P\fR
1007 option typically allow for the auditing of the immediate dependencies of the
1008 object. The \fB-z\fR \fBglobalaudit\fR promotes the auditor to a global
1009 auditor, thus allowing the auditing of all dependencies. See \fIInvoking the
1010 Auditing Interface\fR in \fILinker and Libraries Guide\fR.
1011 .sp
1012 An auditor established with the \fB-P\fR option and the \fB-z\fR
1013 \fBglobalaudit\fR option, is equivalent to the auditor being established with
1014 the \fBLD_AUDIT\fR environment variable. See \fBld.so.1\fR(1).
1015 .RE
1016
1017 .sp
1018 .ne 2
1019 .na
1020 \fB\fB-z\fR \fBgroupperm\fR | \fBnogroupperm\fR\fR
1021 .ad
1022 .sp .6
1023 .RS 4n
1024 Assigns, or deassigns each dependency that follows to a unique group. The
1025 assignment of a dependency to a group has the same effect as if the dependency
1026 had been built using the \fB-B\fR \fBgroup\fR option.
1027 .RE
1028
1029 .sp
1030 .ne 2
1031 .na
1032 \fB-z\fR \fBguidance\fR[=\fIid1\fR,\fIid2\fR...]
1033 .ad
1034 .sp .6
1035 .RS 4n
1036 Give messages suggesting link-editor features that could improve the resulting
1037 dynamic object.
1038 .LP
1039 Specific classes of suggestion can be silenced by specifying an optional comma separated
1040 list of guidance identifiers.
1041 .LP
1042 The current classes of suggestion provided are:
1043
1044 .sp
1045 .ne 2
1046 .na
1047 Enable use of direct binding
1048 .ad
1049 .sp .6
1050 .RS 4n
1051 Suggests that \fB-z direct\fR or \fB-B direct\fR be present prior to any
1052 specified dependency. This allows predictable symbol binding at runtime.
1053
1054 Can be disabled with \fB-z guidance=nodirect\fR
1055 .RE
1056
1057 .sp
1058 .ne 2
1059 .na
1060 Enable lazy dependency loading
1061 .ad
1062 .sp .6
1063 .RS 4n
1064 Suggests that \fB-z lazyload\fR be present prior to any specified dependency.
1065 This allows the dynamic object to be loaded more quickly.
1066
1067 Can be disabled with \fB-z guidance=nolazyload\fR.
1068 .RE
1069
1070 .sp
1071 .ne 2
1072 .na
1073 Shared objects should define all their dependencies.
1074 .ad
1075 .sp .6
1076 .RS 4n
1077 Suggests that \fB-z defs\fR be specified on the link-editor command line.
1078 Shared objects that explicitly state all their dependencies behave more
1079 predictably when used.
1080
1081 Can be be disabled with \fB-z guidance=nodefs\fR
1082 .RE
1083
1084 .sp
1085 .ne 2
1086 .na
1087 Version 2 mapfile syntax
1088 .ad
1089 .sp .6
1090 .RS 4n
1091 Suggests that any specified mapfiles use the more readable version 2 syntax.
1092
1093 Can be disabled with \fB-z guidance=nomapfile\fR.
1094 .RE
1095
1096 .sp
1097 .ne 2
1098 .na
1099 Read-only text segment
1100 .ad
1101 .sp .6
1102 .RS 4n
1103 Should any runtime relocations within the text segment exist, suggests that
1104 the object be compiled with position independent code (PIC). Keeping large
1105 allocatable sections read-only allows them to be shared between processes
1106 using a given shared object.
1107
1108 Can be disabled with \fB-z guidance=notext\fR
1109 .RE
1110
1111 .sp
1112 .ne 2
1113 .na
1114 No unused dependencies
1115 .ad
1116 .sp .6
1117 .RS 4n
1118 Suggests that any dependency not referenced by the resulting dynamic object be
1119 removed from the link-editor command line.
1120
1121 Can be disabled with \fB-z guidance=nounused\fR.
1122 .RE
1123 .RE
1124
1125 .sp
1126 .ne 2
1127 .na
1128 \fB\fB-z\fR \fBhelp\fR\fR
1129 .ad
1130 .br
1131 .na
1132 \fB\fB--help\fR\fR
1133 .ad
1134 .sp .6
1135 .RS 4n
1136 Print a summary of the command line options on the standard output and exit.
1137 .RE
1138
1139 .sp
1140 .ne 2
1141 .na
1142 \fB\fB-z\fR \fBignore\fR | \fBrecord\fR\fR
1143 .ad
1144 .sp .6
1145 .RS 4n
1146 Ignores, or records, dynamic dependencies that are not referenced as part of
1147 the link-edit. Ignores, or records, unreferenced \fBELF\fR sections from the
1148 relocatable objects that are read as part of the link-edit. By default,
1149 \fB-z\fR \fBrecord\fR is in effect.
1150 .sp
1151 If an \fBELF\fR section is ignored, the section is eliminated from the output
1152 file being generated. A section is ignored when three conditions are true. The
1153 eliminated section must contribute to an allocatable segment. The eliminated
1154 section must provide no global symbols. No other section from any object that
1155 contributes to the link-edit, must reference an eliminated section.
1156 .RE
1157
1158 .sp
1159 .ne 2
1160 .na
1161 \fB\fB-z\fR \fBinitarray=\fR\fIfunction\fR\fR
1162 .ad
1163 .sp .6
1164 .RS 4n
1165 Appends an entry to the \fB\&.init_array\fR section of the object being built.
1166 If no \fB\&.init_array\fR section is present, a section is created. The new
1167 entry is initialized to point to \fIfunction\fR. See \fIInitialization and
1168 Termination Sections\fR in \fILinker and Libraries Guide\fR.
1169 .RE
1170
1171 .sp
1172 .ne 2
1173 .na
1174 \fB\fB-z\fR \fBinitfirst\fR\fR
1175 .ad
1176 .sp .6
1177 .RS 4n
1178 Marks the object so that its runtime initialization occurs before the runtime
1179 initialization of any other objects brought into the process at the same time.
1180 In addition, the object runtime finalization occurs after the runtime
1181 finalization of any other objects removed from the process at the same time.
1182 This option is only meaningful when building a shared object.
1183 .RE
1184
1185 .sp
1186 .ne 2
1187 .na
1188 \fB\fB-z\fR \fBinterpose\fR\fR
1189 .ad
1190 .sp .6
1191 .RS 4n
1192 Marks the object as an interposer. At runtime, an object is identified as an
1193 explicit interposer if the object has been tagged using the \fB-z interpose\fR
1194 option. An explicit interposer is also established when an object is loaded
1195 using the \fBLD_PRELOAD\fR environment variable. Implicit interposition can
1196 occur because of the load order of objects, however, this implicit
1197 interposition is unknown to the runtime linker. Explicit interposition can
1198 ensure that interposition takes place regardless of the order in which objects
1199 are loaded. Explicit interposition also ensures that the runtime linker
1200 searches for symbols in any explicit interposers when direct bindings are in
1201 effect.
1202 .RE
1203
1204 .sp
1205 .ne 2
1206 .na
1207 \fB\fB-z\fR \fBlazyload\fR | \fBnolazyload\fR\fR
1208 .ad
1209 .sp .6
1210 .RS 4n
1211 Enables or disables the marking of dynamic dependencies to be lazily loaded.
1212 Dynamic dependencies which are marked \fBlazyload\fR are not loaded at initial
1213 process start-up. These dependencies are delayed until the first binding to the
1214 object is made. \fBNote:\fR Lazy loading requires the correct declaration of
1215 dependencies, together with associated runpaths for each dynamic object used
1216 within a process. See \fILazy Loading of Dynamic Dependencies\fR in \fILinker
1217 and Libraries Guide\fR.
1218 .RE
1219
1220 .sp
1221 .ne 2
1222 .na
1223 \fB\fB-z\fR \fBld32\fR=\fIarg1\fR,\fIarg2\fR,...\fR
1224 .ad
1225 .br
1226 .na
1227 \fB\fB-z\fR \fBld64\fR=\fIarg1\fR,\fIarg2\fR,...\fR
1228 .ad
1229 .sp .6
1230 .RS 4n
1231 The class of the link-editor is affected by the class of the output file being
1232 created and by the capabilities of the underlying operating system. The
1233 \fB-z\fR \fBld\fR[\fB32\fR|\fB64\fR] options provide a means of defining any
1234 link-editor argument. The defined argument is only interpreted, respectively,
1235 by the 32-bit class or 64-bit class of the link-editor.
1236 .sp
1237 For example, support libraries are class specific, so the correct class of
1238 support library can be ensured using:
1239 .sp
1240 .in +2
1241 .nf
1242 \fBld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...\fR
1243 .fi
1244 .in -2
1245 .sp
1246
1247 The class of link-editor that is invoked is determined from the \fBELF\fR class
1248 of the first relocatable file that is seen on the command line. This
1249 determination is carried out \fBprior\fR to any \fB-z\fR
1250 \fBld\fR[\fB32\fR|\fB64\fR] processing.
1251 .RE
1252
1253 .sp
1254 .ne 2
1255 .na
1256 \fB\fB-z\fR \fBloadfltr\fR\fR
1257 .ad
1258 .sp .6
1259 .RS 4n
1260 Marks a filter to indicate that filtees must be processed immediately at
1261 runtime. Normally, filter processing is delayed until a symbol reference is
1262 bound to the filter. The runtime processing of an object that contains this
1263 flag mimics that which occurs if the \fBLD_LOADFLTR\fR environment variable is
1264 in effect. See the \fBld.so.1\fR(1).
1265 .RE
1266
1267 .sp
1268 .ne 2
1269 .na
1270 \fB\fB-z\fR \fBmuldefs\fR\fR
1271 .ad
1272 .br
1273 .na
1274 \fB\fB--allow-multiple-definition\fR\fR
1275 .ad
1276 .sp .6
1277 .RS 4n
1278 Allows multiple symbol definitions. By default, multiple symbol definitions
1279 that occur between relocatable objects result in a fatal error condition. This
1280 option, suppresses the error condition, allowing the first symbol definition to
1281 be taken.
1282 .RE
1283
1284 .sp
1285 .ne 2
1286 .na
1287 \fB\fB-z\fR \fBnocompstrtab\fR\fR
1288 .ad
1289 .sp .6
1290 .RS 4n
1291 Disables the compression of \fBELF\fR string tables. By default, string
1292 compression is applied to \fBSHT_STRTAB\fR sections, and to \fBSHT_PROGBITS\fR
1293 sections that have their \fBSHF_MERGE\fR and \fBSHF_STRINGS\fR section flags
1294 set.
1295 .RE
1296
1297 .sp
1298 .ne 2
1299 .na
1300 \fB\fB-z\fR \fBnodefaultlib\fR\fR
1301 .ad
1302 .sp .6
1303 .RS 4n
1304 Marks the object so that the runtime default library search path, used after
1305 any \fBLD_LIBRARY_PATH\fR or runpaths, is ignored. This option implies that all
1306 dependencies of the object can be satisfied from its runpath.
1307 .RE
1308
1309 .sp
1310 .ne 2
1311 .na
1312 \fB\fB-z\fR \fBnodelete\fR\fR
1313 .ad
1314 .sp .6
1315 .RS 4n
1316 Marks the object as non-deletable at runtime. This mode is similar to adding
1317 the object to the process by using \fBdlopen\fR(3C) with the
1318 \fBRTLD_NODELETE\fR mode.
1319 .RE
1320
1321 .sp
1322 .ne 2
1323 .na
1324 \fB\fB-z\fR \fBnodlopen\fR\fR
1325 .ad
1326 .sp .6
1327 .RS 4n
1328 Marks the object as not available to \fBdlopen\fR(3C), either as the object
1329 specified by the \fBdlopen()\fR, or as any form of dependency required by the
1330 object specified by the \fBdlopen()\fR. This option is only meaningful when
1331 building a shared object.
1332 .RE
1333
1334 .sp
1335 .ne 2
1336 .na
1337 \fB\fB-z\fR \fBnodump\fR\fR
1338 .ad
1339 .sp .6
1340 .RS 4n
1341 Marks the object as not available to \fBdldump\fR(3C).
1342 .RE
1343
1344 .sp
1345 .ne 2
1346 .na
1347 \fB\fB-z\fR \fBnoldynsym\fR\fR
1348 .ad
1349 .sp .6
1350 .RS 4n
1351 Prevents the inclusion of a \fB\&.SUNW_ldynsym\fR section in dynamic
1352 executables or sharable libraries. The \fB\&.SUNW_ldynsym\fR section augments
1353 the \fB\&.dynsym\fR section by providing symbols for local functions. Local
1354 function symbols allow debuggers to display local function names in stack
1355 traces from stripped programs. Similarly, \fBdladdr\fR(3C) is able to supply
1356 more accurate results.
1357 .sp
1358 The \fB-z\fR \fBnoldynsym\fR option also prevents the inclusion of the two
1359 symbol sort sections that are related to the \fB\&.SUNW_ldynsym\fR section. The
1360 \fB\&.SUNW_dynsymsort\fR section provides sorted access to regular function and
1361 variable symbols. The \fB\&.SUNW_dyntlssort\fR section provides sorted access
1362 to thread local storage (\fBTLS\fR) variable symbols.
1363 .sp
1364 The \fB\&.SUNW_ldynsym\fR, \fB\&.SUNW_dynsymsort\fR, and
1365 \fB\&.SUNW_dyntlssort\fR sections, which becomes part of the allocable text
1366 segment of the resulting file, cannot be removed by \fBstrip\fR(1). Therefore,
1367 the \fB-z\fR \fBnoldynsym\fR option is the only way to prevent their inclusion.
1368 See the \fB-s\fR and \fB-z\fR \fBredlocsym\fR options.
1369 .RE
1370
1371 .sp
1372 .ne 2
1373 .na
1374 \fB\fB-z\fR \fBnopartial\fR\fR
1375 .ad
1376 .sp .6
1377 .RS 4n
1378 Partially initialized symbols, that are defined within relocatable object
1379 files, are expanded in the output file being generated.
1380 .RE
1381
1382 .sp
1383 .ne 2
1384 .na
1385 \fB\fB-z\fR \fBnoversion\fR\fR
1386 .ad
1387 .sp .6
1388 .RS 4n
1389 Does not record any versioning sections. Any version sections or associated
1390 \fB\&.dynamic\fR section entries are not generated in the output image.
1391 .RE
1392
1393 .sp
1394 .ne 2
1395 .na
1396 \fB\fB-z\fR \fBnow\fR\fR
1397 .ad
1398 .sp .6
1399 .RS 4n
1400 Marks the object as requiring non-lazy runtime binding. This mode is similar to
1401 adding the object to the process by using \fBdlopen\fR(3C) with the
1402 \fBRTLD_NOW\fR mode. This mode is also similar to having the \fBLD_BIND_NOW\fR
1403 environment variable in effect. See \fBld.so.1\fR(1).
1404 .RE
1405
1406 .sp
1407 .ne 2
1408 .na
1409 \fB\fB-z\fR \fBorigin\fR\fR
1410 .ad
1411 .sp .6
1412 .RS 4n
1413 Marks the object as requiring immediate \fB$ORIGIN\fR processing at runtime.
1414 This option is only maintained for historic compatibility, as the runtime
1415 analysis of objects to provide for \fB$ORIGIN\fR processing is now default.
1416 .RE
1417
1418 .sp
1419 .ne 2
1420 .na
1421 \fB\fB-z\fR \fBpreinitarray=\fR\fIfunction\fR\fR
1422 .ad
1423 .sp .6
1424 .RS 4n
1425 Appends an entry to the \fB\&.preinitarray\fR section of the object being
1426 built. If no \fB\&.preinitarray\fR section is present, a section is created.
1427 The new entry is initialized to point to \fIfunction\fR. See \fIInitialization
1428 and Termination Sections\fR in \fILinker and Libraries Guide\fR.
1429 .RE
1430
1431 .sp
1432 .ne 2
1433 .na
1434 \fB\fB-z\fR \fBredlocsym\fR\fR
1435 .ad
1436 .sp .6
1437 .RS 4n
1438 Eliminates all local symbols except for the \fISECT\fR symbols from the symbol
1439 table \fBSHT_SYMTAB\fR. All relocations that refer to local symbols are updated
1440 to refer to the corresponding \fISECT\fR symbol. This option allows specialized
1441 objects to greatly reduce their symbol table sizes. Eliminated local symbols
1442 can reduce the \fB\&.stab*\fR debugging information that is generated using the
1443 compiler drivers \fB-g\fR option. See the \fB-s\fR and \fB-z\fR \fBnoldynsym\fR
1444 options.
1445 .RE
1446
1447 .sp
1448 .ne 2
1449 .na
1450 \fB\fB-z\fR \fBrelaxreloc\fR\fR
1451 .ad
1452 .sp .6
1453 .RS 4n
1454 \fBld\fR normally issues a fatal error upon encountering a relocation using a
1455 symbol that references an eliminated COMDAT section. If \fB-z\fR
1456 \fBrelaxreloc\fR is enabled, \fBld\fR instead redirects such relocations to the
1457 equivalent symbol in the COMDAT section that was kept. \fB-z\fR
1458 \fBrelaxreloc\fR is a specialized option, mainly of interest to compiler
1459 authors, and is not intended for general use.
1460 .RE
1461
1462 .sp
1463 .ne 2
1464 .na
1465 \fB\fB-z\fR \fBrescan-now\fR\fR
1466 .ad
1467 .br
1468 .na
1469 \fB\fB-z\fR \fBrescan\fR\fR
1470 .ad
1471 .sp .6
1472 .RS 4n
1473 These options rescan the archive files that are provided to the link-edit. By
1474 default, archives are processed once as the archives appear on the command
1475 line. Archives are traditionally specified at the end of the command line so
1476 that their symbol definitions resolve any preceding references. However,
1477 specifying archives multiple times to satisfy their own interdependencies can
1478 be necessary.
1479 .sp
1480 \fB-z\fR \fBrescan-now\fR is a positional option, and is processed by the
1481 link-editor immediately when encountered on the command line. All archives seen
1482 on the command line up to that point are immediately reprocessed in an attempt
1483 to locate additional archive members that resolve symbol references. This
1484 archive rescanning is repeated until a pass over the archives occurs in which
1485 no new members are extracted.
1486 .sp
1487 \fB-z\fR \fBrescan\fR is a position independent option. The link-editor defers
1488 the rescan operation until after it has processed the entire command line, and
1489 then initiates a final rescan operation over all archives seen on the command
1490 line. The \fB-z\fR \fBrescan\fR operation can interact incorrectly
1491 with objects that contain initialization (.init) or finalization (.fini)
1492 sections, preventing the code in those sections from running. For this reason,
1493 \fB-z\fR \fBrescan\fR is deprecated, and use of \fB-z\fR \fBrescan-now\fR is
1494 advised.
1495 .RE
1496
1497 .sp
1498 .ne 2
1499 .na
1500 \fB\fB-z\fR \fBrescan-start\fR ... \fB-z\fR \fBrescan-end\fR\fR
1501 .ad
1502 .br
1503 .na
1504 \fB\fB--start-group\fR ... \fB--end-group\fR\fR
1505 .ad
1506 .br
1507 .na
1508 \fB\fB-(\fR ... \fB-)\fR\fR
1509 .ad
1510 .sp .6
1511 .RS 4n
1512 Defines an archive rescan group. This is a positional construct, and is
1513 processed by the link-editor immediately upon encountering the closing
1514 delimiter option. Archives found within the group delimiter options are
1515 reprocessed as a group in an attempt to locate additional archive members that
1516 resolve symbol references. This archive rescanning is repeated until a pass
1517 over the archives occurs in which no new members are extracted.
1518 Archive rescan groups cannot be nested.
1519 .RE
1520
1521 .sp
1522 .ne 2
1523 .na
1524 \fB\fB-z\fR \fBtarget=sparc|x86\fR \fI\fR\fR
1525 .ad
1526 .sp .6
1527 .RS 4n
1528 Specifies the machine type for the output object. Supported targets are Sparc
1529 and x86. The 32-bit machine type for the specified target is used unless the
1530 \fB-64\fR option is also present, in which case the corresponding 64-bit
1531 machine type is used. By default, the machine type of the object being
1532 generated is determined from the first \fBELF\fR object processed from the
1533 command line. If no objects are specified, the machine type is determined by
1534 the first object encountered within the first archive processed from the
1535 command line. If there are no objects or archives, the link-editor assumes the
1536 native machine. This option is useful when creating an object directly with
1537 \fBld\fR whose input is solely from a \fBmapfile\fR. See the \fB-M\fR option.
1538 It can also be useful in the rare case of linking entirely from an archive that
1539 contains objects of different machine types for which the first object is not
1540 of the desired machine type. See \fIThe 32-bit link-editor and 64-bit
1541 link-editor\fR in \fILinker and Libraries Guide\fR.
1542 .RE
1543
1544 .sp
1545 .ne 2
1546 .na
1547 \fB\fB-z\fR \fBtext\fR\fR
1548 .ad
1549 .sp .6
1550 .RS 4n
1551 In dynamic mode only, forces a fatal error if any relocations against
1552 non-writable, allocatable sections remain. For historic reasons, this mode is
1553 not the default when building an executable or shared object. However, its use
1554 is recommended to ensure that the text segment of the dynamic object being
1555 built is shareable between multiple running processes. A shared text segment
1556 incurs the least relocation overhead when loaded into memory. See
1557 \fIPosition-Independent Code\fR in \fILinker and Libraries Guide\fR.
1558 .RE
1559
1560 .sp
1561 .ne 2
1562 .na
1563 \fB\fB-z\fR \fBtextoff\fR\fR
1564 .ad
1565 .sp .6
1566 .RS 4n
1567 In dynamic mode only, allows relocations against all allocatable sections,
1568 including non-writable ones. This mode is the default when building a shared
1569 object.
1570 .RE
1571
1572 .sp
1573 .ne 2
1574 .na
1575 \fB\fB-z\fR \fBtextwarn\fR\fR
1576 .ad
1577 .sp .6
1578 .RS 4n
1579 In dynamic mode only, lists a warning if any relocations against non-writable,
1580 allocatable sections remain. This mode is the default when building an
1581 executable.
1582 .RE
1583
1584 .sp
1585 .ne 2
1586 .na
1587 \fB-z\fR \fBtype=exec|kmod|reloc|shared\fR
1588 .ad
1589 .sp .6
1590 .RS 4n
1591 Specifies the type of object to create.
1592
1593 .sp
1594 .ne 2
1595 .na
1596 exec
1597 .ad
1598 .sp .6
1599 .RS 4n
1600 Dynamic executable
1601 .RE
1602
1603 .sp
1604 .ne 2
1605 .na
1606 reloc
1607 .ad
1608 .sp .6
1609 .RS 4n
1610 Relocatable object
1611 .RE
1612
1613 .sp
1614 .ne 2
1615 .na
1616 shared
1617 .ad
1618 .sp .6
1619 .RS 4n
1620 Dynamic shared object
1621 .RE
1622
1623 .sp
1624 .ne 2
1625 .na
1626 kmod
1627 .ad
1628 .sp .6
1629 .RS 4n
1630 illumos kernel module
1631 .RE
1632 .RE
1633
1634 .sp
1635 .ne 2
1636 .na
1637 \fB\fB-z\fR \fBverbose\fR\fR
1638 .ad
1639 .sp .6
1640 .RS 4n
1641 This option provides additional warning diagnostics during a link-edit.
1642 Presently, this option conveys suspicious use of displacement relocations. This
1643 option also conveys the restricted use of static \fBTLS\fR relocations when
1644 building shared objects. In future, this option might be enhanced to provide
1645 additional diagnostics that are deemed too noisy to be generated by default.
1646 .RE
1647
1648 .sp
1649 .ne 2
1650 .na
1651 \fB\fB-z\fR\fBwrap=\fR\fIsymbol\fR\fR
1652 .ad
1653 .br
1654 .na
1655 \fB\fB-wrap=\fR \fIsymbol\fR\fR
1656 .ad
1657 .br
1658 .na
1659 \fB\fB--wrap=\fR \fIsymbol\fR\fR
1660 .ad
1661 .sp .6
1662 .RS 4n
1663 Rename undefined references to \fIsymbol\fR in order to allow wrapper code to
1664 be linked into the output object without having to modify source code. When
1665 \fB-z wrap\fR is specified, all undefined references to \fIsymbol\fR are
1666 modified to reference \fB__wrap_\fR\fIsymbol\fR, and all references to
1667 \fB__real_\fR\fIsymbol\fR are modified to reference \fIsymbol\fR. The user is
1668 expected to provide an object containing the \fB__wrap_\fR\fIsymbol\fR
1669 function. This wrapper function can call \fB__real_\fR\fIsymbol\fR in order to
1670 reference the actual function being wrapped.
1671 .sp
1672 The following is an example of a wrapper for the \fBmalloc\fR(3C) function:
1673 .sp
1674 .in +2
1675 .nf
1676 void *
1677 __wrap_malloc(size_t c)
1678 {
1679 (void) printf("malloc called with %zu\en", c);
1680 return (__real_malloc(c));
1681 }
1682 .fi
1683 .in -2
1684
1685 If you link other code with this file using \fB-z\fR \fBwrap=malloc\fR to
1686 compile all the objects, then all calls to \fBmalloc\fR will call the function
1687 \fB__wrap_malloc\fR instead. The call to \fB__real_malloc\fR will call the real
1688 \fBmalloc\fR function.
1689 .sp
1690 The real and wrapped functions should be maintained in separate source files.
1691 Otherwise, the compiler or assembler may resolve the call instead of leaving
1692 that operation for the link-editor to carry out, and prevent the wrap from
1693 occurring.
1694 .RE
1695
1696 .SH ENVIRONMENT VARIABLES
1697 .ne 2
1698 .na
1699 \fB\fBLD_ALTEXEC\fR\fR
1700 .ad
1701 .sp .6
1702 .RS 4n
1703 An alternative link-editor path name. \fBld\fR executes, and passes control to
1704 this alternative link-editor. This environment variable provides a generic
1705 means of overriding the default link-editor that is called from the various
1706 compiler drivers. See the \fB-z altexec64\fR option.
1707 .RE
1708
1709 .sp
1710 .ne 2
1711 .na
1712 \fB\fBLD_LIBRARY_PATH\fR\fR
1713 .ad
1714 .sp .6
1715 .RS 4n
1716 A list of directories in which to search for the libraries specified using the
1717 \fB-l\fR option. Multiple directories are separated by a colon. In the most
1718 general case, this environment variable contains two directory lists separated
1719 by a semicolon:
1720 .sp
1721 .in +2
1722 .nf
1723 \fIdirlist1\fR\fB;\fR\fIdirlist2\fR
1724 .fi
1725 .in -2
1726 .sp
1727
1728 If \fBld\fR is called with any number of occurrences of \fB-L\fR, as in:
1729 .sp
1730 .in +2
1731 .nf
1732 \fBld ... -L\fIpath1\fR ... -L\fIpathn\fR ...\fR
1733 .fi
1734 .in -2
1735 .sp
1736
1737 then the search path ordering is:
1738 .sp
1739 .in +2
1740 .nf
1741 \fB\fIdirlist1 path1\fR ... \fIpathn dirlist2\fR LIBPATH\fR
1742 .fi
1743 .in -2
1744 .sp
1745
1746 When the list of directories does not contain a semicolon, the list is
1747 interpreted as \fIdirlist2\fR.
1748 .sp
1749 The \fBLD_LIBRARY_PATH\fR environment variable also affects the runtime linkers
1750 search for dynamic dependencies.
1751 .sp
1752 This environment variable can be specified with a _32 or _64 suffix. This makes
1753 the environment variable specific, respectively, to 32-bit or 64-bit processes
1754 and overrides any non-suffixed version of the environment variable that is in
1755 effect.
1756 .RE
1757
1758 .sp
1759 .ne 2
1760 .na
1761 \fB\fBLD_NOEXEC_64\fR\fR
1762 .ad
1763 .sp .6
1764 .RS 4n
1765 Suppresses the automatic execution of the 64-bit link-editor. By default, the
1766 link-editor executes the 64-bit version when the \fBELF\fR class of the first
1767 relocatable file identifies a 64-bit object. The 64-bit image that a 32-bit
1768 link-editor can create, has some limitations. However, some link-edits might
1769 find the use of the 32-bit link-editor faster.
1770 .RE
1771
1772 .sp
1773 .ne 2
1774 .na
1775 \fB\fBLD_OPTIONS\fR\fR
1776 .ad
1777 .sp .6
1778 .RS 4n
1779 A default set of options to \fBld\fR. \fBLD_OPTIONS\fR is interpreted by
1780 \fBld\fR just as though its value had been placed on the command line,
1781 immediately following the name used to invoke \fBld\fR, as in:
1782 .sp
1783 .in +2
1784 .nf
1785 \fBld $LD_OPTIONS ... \fIother-arguments\fR ...\fR
1786 .fi
1787 .in -2
1788 .sp
1789
1790 .RE
1791
1792 .sp
1793 .ne 2
1794 .na
1795 \fB\fBLD_RUN_PATH\fR\fR
1796 .ad
1797 .sp .6
1798 .RS 4n
1799 An alternative mechanism for specifying a runpath to the link-editor. See the
1800 \fB-R\fR option. If both \fBLD_RUN_PATH\fR and the \fB-R\fR option are
1801 specified, \fB-R\fR supersedes.
1802 .RE
1803
1804 .sp
1805 .ne 2
1806 .na
1807 \fB\fBSGS_SUPPORT\fR\fR
1808 .ad
1809 .sp .6
1810 .RS 4n
1811 Provides a colon-separated list of shared objects that are loaded with the
1812 link-editor and given information regarding the linking process. This
1813 environment variable can be specified with a _32 or _64 suffix. This makes the
1814 environment variable specific, respectively, to the 32-bit or 64-bit class of
1815 \fBld\fR and overrides any non-suffixed version of the environment variable
1816 that is in effect. See the \fB-S\fR option.
1817 .RE
1818
1819 .sp
1820 .LP
1821 Notice that environment variable-names that begin with the
1822 characters '\fBLD_\fR' are reserved for possible future enhancements to \fBld\fR and
1823 \fBld.so.1\fR(1).
1824 .SH FILES
1825 .ne 2
1826 .na
1827 \fB\fBlib\fIx\fR.so\fR\fR
1828 .ad
1829 .RS 15n
1830 shared object libraries.
1831 .RE
1832
1833 .sp
1834 .ne 2
1835 .na
1836 \fB\fBlib\fIx\fR.a\fR\fR
1837 .ad
1838 .RS 15n
1839 archive libraries.
1840 .RE
1841
1842 .sp
1843 .ne 2
1844 .na
1845 \fB\fBa.out\fR\fR
1846 .ad
1847 .RS 15n
1848 default output file.
1849 .RE
1850
1851 .sp
1852 .ne 2
1853 .na
1854 \fB\fILIBPATH\fR\fR
1855 .ad
1856 .RS 15n
1857 For 32-bit libraries, the default search path is \fB/usr/ccs/lib\fR, followed
1858 by \fB/lib\fR, and finally \fB/usr/lib\fR. For 64-bit libraries, the default
1859 search path is \fB/lib/64\fR, followed by \fB/usr/lib/64\fR.
1860 .RE
1861
1862 .sp
1863 .ne 2
1864 .na
1865 \fB\fB/usr/lib/ld\fR\fR
1866 .ad
1867 .RS 15n
1868 A directory containing several \fBmapfiles\fR that can be used during
1869 link-editing. These \fBmapfiles\fR provide various capabilities, such as
1870 defining memory layouts, aligning bss, and defining non-executable stacks.
1871 .RE
1872
1873 .SH ATTRIBUTES
1874 .LP
1875 See \fBattributes\fR(5) for descriptions of the following attributes:
1876 .sp
1877
1878 .sp
1879 .TS
1880 box;
1881 c | c
1882 l | l .
1883 ATTRIBUTE TYPE ATTRIBUTE VALUE
1884 _
1885 Interface Stability Committed
1886 .TE
1887
1888 .SH SEE ALSO
1889 .LP
1890 \fBas\fR(1), \fBcrle\fR(1), \fBgprof\fR(1), \fBld.so.1\fR(1), \fBldd\fR(1),
1891 \fBmcs\fR(1), \fBpvs\fR(1), \fBexec\fR(2), \fBstat\fR(2), \fBdlopen\fR(3C),
1892 \fBdldump\fR(3C), \fBelf\fR(3ELF), \fBar.h\fR(3HEAD), \fBa.out\fR(4),
1893 \fBattributes\fR(5)
1894 .sp
1895 .LP
1896 \fILinker and Libraries Guide\fR
1897 .SH NOTES
1898 .LP
1899 Default options applied by \fBld\fR are maintained for historic reasons. In
1900 today's programming environment, where dynamic objects dominate, alternative
1901 defaults would often make more sense. However, historic defaults must be
1902 maintained to ensure compatibility with existing program development
1903 environments. Historic defaults are called out wherever possible in this
1904 manual. For a description of the current recommended options, see Appendix A,
1905 \fILink-Editor Quick Reference,\fR in \fILinker and Libraries Guide\fR.
1906 .sp
1907 .LP
1908 If the file being created by \fBld\fR already exists, the file is unlinked
1909 after all input files have been processed. A new file with the specified name
1910 is then created. This allows \fBld\fR to create a new version of the file,
1911 while simultaneously allowing existing processes that are accessing the old
1912 file contents to continue running. If the old file has no other links, the disk
1913 space of the removed file is freed when the last process referencing the file
1914 terminates.
1915 .sp
1916 .LP
1917 The behavior of \fBld\fR when the file being created already exists was changed
1918 with \fBSXCE\fR build \fB43\fR. In older versions, the existing file was
1919 rewritten in place, an approach with the potential to corrupt any running
1920 processes that is using the file. This change has an implication for output
1921 files that have multiple hard links in the file system. Previously, all links
1922 would remain intact, with all links accessing the new file contents. The new
1923 \fBld\fR behavior \fBbreaks\fR such links, with the result that only the
1924 specified output file name references the new file. All the other links
1925 continue to reference the old file. To ensure consistent behavior, applications
1926 that rely on multiple hard links to linker output files should explicitly
1927 remove and relink the other file names.