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