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