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