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