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