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