1 LD(1)                            User Commands                           LD(1)
   2 
   3 
   4 
   5 NAME
   6        ld - link-editor for object files
   7 
   8 SYNOPSIS
   9        ld [-32 | -64] [-a | -r] [-b] [-Bdirect | nodirect]
  10        [-B dynamic | static] [-B eliminate] [-B group] [-B local]
  11        [-B reduce] [-B symbolic] [-c name] [-C] [-d y | n]
  12        [-D token,...] [-e epsym] [-f name | -F name] [-G] [-h name]
  13        [-i] [-I name] [-l x] [-L path] [-m] [-M mapfile]
  14        [-N string] [-o outfile] [-p auditlib] [-P auditlib]
  15        [-Q y | n] [-R path] [-s] [-S supportlib] [-t]
  16        [-u symname] [-V] [-Y P,dirlist] [-z absexec]
  17        [-z allextract | defaultextract | weakextract ] [-z altexec64]
  18        [-z assert-deflib ] [ -z assert-deflib=libname ]
  19        [-z combreloc | nocombreloc ] [-z defs | nodefs]
  20        [-z direct | nodirect] [-z endfiltee]
  21        [-z fatal-warnings | nofatal-warnings ] [-z finiarray=function]
  22        [-z globalaudit] [-z groupperm | nogroupperm]
  23        [-z guidance[=id1,id2...] [-z help ]
  24        [-z ignore | record] [-z initarray=function] [-z initfirst]
  25        [-z interpose] [-z lazyload | nolazyload]
  26        [-z ld32=arg1,arg2,...] [-z ld64=arg1,arg2,...]
  27        [-z loadfltr] [-z muldefs] [-z nocompstrtab] [-z nodefaultlib]
  28        [-z nodelete] [-z nodlopen] [-z nodump] [-z noldynsym]
  29        [-z nopartial] [-z noversion] [-z now] [-z origin]
  30        [-z preinitarray=function] [-z redlocsym] [-z relaxreloc]
  31        [-z rescan-now] [-z recan] [-z rescan-start ... -z rescan-end]]
  32        [-z target=sparc|x86] [-z text | textwarn | textoff]
  33        [-z verbose] [-z wrap=symbol] filename...
  34 
  35 
  36 DESCRIPTION
  37        The link-editor, ld, combines relocatable object files by resolving
  38        symbol references to symbol definitions, together with performing
  39        relocations.  ld operates in two modes, static or dynamic, as governed
  40        by the -d option. In all cases, the output of ld is left in the file
  41        a.out by default. See NOTES.
  42 
  43 
  44        In dynamic mode, -dy, the default, relocatable object files that are
  45        provided as arguments are combined to produce an executable object
  46        file. This file is linked at execution with any shared object files
  47        that are provided as arguments. If the -G option is specified,
  48        relocatable object files are combined to produce a shared object.
  49        Without the -G option, a dynamic executable is created.
  50 
  51 
  52        In static mode, -dn, relocatable object files that are provided as
  53        arguments are combined to produce a static executable file. If the -r
  54        option is specified, relocatable object files are combined to produce
  55        one relocatable object file. See Static Executables.
  56 
  57 
  58        Dynamic linking is the most common model for combining relocatable
  59        objects, and the eventual creation of processes within Solaris. This
  60        environment tightly couples the work of the link-editor and the runtime
  61        linker, ld.so.1(1).  Both of these utilities, together with their
  62        related technologies and utilities, are extensively documented in the
  63        Linker and Libraries Guide.
  64 
  65 
  66        If any argument is a library, ld by default searches the library
  67        exactly once at the point the library is encountered on the argument
  68        list. The library can be either a shared object or relocatable archive.
  69        See ar.h(3HEAD)).
  70 
  71 
  72        A shared object consists of an indivisible, whole unit that has been
  73        generated by a previous link-edit of one or more input files. When the
  74        link-editor processes a shared object, the entire contents of the
  75        shared object become a logical part of the resulting output file image.
  76        The shared object is not physically copied during the link-edit as its
  77        actual inclusion is deferred until process execution. This logical
  78        inclusion means that all symbol entries defined in the shared object
  79        are made available to the link-editing process.  See Chapter 4, Shared
  80        Objects, in Linker and Libraries Guide
  81 
  82 
  83        For an archive library, ld loads only those routines that define an
  84        unresolved external reference. ld searches the symbol table of the
  85        archive library sequentially to resolve external references that can be
  86        satisfied by library members. This search is repeated until no external
  87        references can be resolved by the archive. Thus, the order of members
  88        in the library is functionally unimportant, unless multiple library
  89        members exist that define the same external symbol. Archive libraries
  90        that have interdependencies can require multiple command line
  91        definitions, or the use of one of the -z rescan options. See Archive
  92        Processing in Linker and Libraries Guide.
  93 
  94 
  95        ld is a cross link-editor, able to link 32-bit objects or 64-bit
  96        objects, for Sparc or x86 targets. ld uses the ELF class and machine
  97        type of the first relocatable object on the command line to govern the
  98        mode in which to operate. The mixing of 32-bit objects and 64-bit
  99        objects is not permitted.  Similarly, only objects of a single machine
 100        type are allowed. See the -32, -64 and -z target options, and the
 101        LD_NOEXEC_64 environment variable.
 102 
 103    Static Executables
 104        The creation of static executables has been discouraged for many
 105        releases. In fact, 64-bit system archive libraries have never been
 106        provided. Because a static executable is built against system archive
 107        libraries, the executable contains system implementation details. This
 108        self-containment has a number of drawbacks.
 109 
 110            o      The executable is immune to the benefits of system patches
 111                   delivered as shared objects. The executable therefore, must
 112                   be rebuilt to take advantage of many system improvements.
 113 
 114            o      The ability of the executable to run on future releases can
 115                   be compromised.
 116 
 117            o      The duplication of system implementation details negatively
 118                   affects system performance.
 119 
 120 
 121        With Solaris 10, 32-bit system archive libraries are no longer
 122        provided.  Without these libraries, specifically libc.a, the creation
 123        of static executables is no longer achievable without specialized
 124        system knowledge.  However, the capability of ld to process static
 125        linking options, and the processing of archive libraries, remains
 126        unchanged.
 127 
 128 OPTIONS
 129        The following options are supported.
 130 
 131        -32 | -64
 132 
 133            Creates a 32-bit, or 64-bit object.
 134 
 135            By default, the class of the object being generated is determined
 136            from the first ELF object processed from the command line. If no
 137            objects are specified, the class is determined by the first object
 138            encountered within the first archive processed from the command
 139            line. If there are no objects or archives, the link-editor creates
 140            a 32-bit object.
 141 
 142            The -64 option is required to create a 64-bit object solely from a
 143            mapfile.
 144 
 145            This -32 or -64 options can also be used in the rare case of
 146            linking entirely from an archive that contains a mixture of 32 and
 147            64-bit objects. If the first object in the archive is not the class
 148            of the object that is required to be created, then the -32 or -64
 149            option can be used to direct the link-editor. See The 32-bit link-
 150            editor and 64-bit link-editor in Linker and Libraries Guide.
 151 
 152 
 153        -a
 154 
 155            In static mode only, produces an executable object file. Undefined
 156            references are not permitted. This option is the default behavior
 157            for static mode. The -a option can not be used with the -r option.
 158            See Static Executables under DESCRIPTION.
 159 
 160 
 161        -b
 162 
 163            In dynamic mode only, provides no special processing for dynamic
 164            executable relocations that reference symbols in shared objects.
 165            Without the -b option, the link-editor applies techniques within a
 166            dynamic executable so that the text segment can remain read-only.
 167            One technique is the creation of special position-independent
 168            relocations for references to functions that are defined in shared
 169            objects. Another technique arranges for data objects that are
 170            defined in shared objects to be copied into the memory image of an
 171            executable at runtime.
 172 
 173            The -b option is intended for specialized dynamic objects and is
 174            not recommended for general use. Its use suppresses all specialized
 175            processing required to ensure an object's shareability, and can
 176            even prevent the relocation of 64-bit executables.
 177 
 178 
 179        -B direct | nodirect
 180 
 181            These options govern direct binding. -B direct establishes direct
 182            binding information by recording the relationship between each
 183            symbol reference together with the dependency that provides the
 184            definition. In addition, direct binding information is established
 185            between each symbol reference and an associated definition within
 186            the object being created. The runtime linker uses this information
 187            to search directly for a symbol in the associated object rather
 188            than to carry out a default symbol search.
 189 
 190            Direct binding information can only be established to dependencies
 191            specified with the link-edit. Thus, you should use the -z defs
 192            option.  Objects that wish to interpose on symbols in a direct
 193            binding environment should identify themselves as interposers with
 194            the -z interpose option. The use of -B direct enables -z lazyload
 195            for all dependencies.
 196 
 197            The -B nodirect option prevents any direct binding to the
 198            interfaces offered by the object being created. The object being
 199            created can continue to directly bind to external interfaces by
 200            specifying the -z direct option. See Appendix D, Direct Bindings,
 201            in Linker and Libraries Guide.
 202 
 203 
 204        -B dynamic | static
 205 
 206            Options governing library inclusion. -B dynamic is valid in dynamic
 207            mode only. These options can be specified any number of times on
 208            the command line as toggles: if the -B static option is given, no
 209            shared objects are accepted until -B dynamic is seen. See the -l
 210            option.
 211 
 212 
 213        -B eliminate
 214 
 215            Causes any global symbols, not assigned to a version definition, to
 216            be eliminated from the symbol table. Version definitions can be
 217            supplied by means of a mapfile to indicate the global symbols that
 218            should remain visible in the generated object. This option achieves
 219            the same symbol elimination as the auto-elimination directive that
 220            is available as part of a mapfile version definition. This option
 221            can be useful when combining versioned and non-versioned
 222            relocatable objects. See also the -B local option and the -B reduce
 223            option. See Defining Additional Symbols with a mapfile in Linker
 224            and Libraries Guide.
 225 
 226 
 227        -B group
 228 
 229            Establishes a shared object and its dependencies as a group.
 230            Objects within the group are bound to other members of the group at
 231            runtime. This mode is similar to adding the object to the process
 232            by using dlopen(3C) with the RTLD_GROUP mode. An object that has an
 233            explicit dependency on a object identified as a group, becomes a
 234            member of the group.
 235 
 236            As the group must be self contained, use of the -B group option
 237            also asserts the -z defs option.
 238 
 239 
 240        -B local
 241 
 242            Causes any global symbols, not assigned to a version definition, to
 243            be reduced to local. Version definitions can be supplied by means
 244            of a mapfile to indicate the global symbols that should remain
 245            visible in the generated object.  This option achieves the same
 246            symbol reduction as the auto-reduction directive that is available
 247            as part of a mapfile version definition. This option can be useful
 248            when combining versioned and non-versioned relocatable objects. See
 249            also the -B eliminate option and the -B reduce option. See Defining
 250            Additional Symbols with a mapfile in Linker and Libraries Guide.
 251 
 252 
 253        -B reduce
 254 
 255            When generating a relocatable object, causes the reduction of
 256            symbolic information defined by any version definitions. Version
 257            definitions can be supplied by means of a mapfile to indicate the
 258            global symbols that should remain visible in the generated object.
 259            By default, when a relocatable object is generated, version
 260            definitions are only recorded in the output image. The actual
 261            reduction of symbolic information is carried out when the object is
 262            used in the construction of a dynamic executable or shared object.
 263            The -B reduce option is applied automatically when a dynamic
 264            executable or shared object is created.
 265 
 266 
 267        -B symbolic
 268 
 269            In dynamic mode only. When building a shared object, binds
 270            references to global symbols to their definitions, if available,
 271            within the object. Normally, references to global symbols within
 272            shared objects are not bound until runtime, even if definitions are
 273            available. This model allows definitions of the same symbol in an
 274            executable or other shared object to override the object's own
 275            definition. ld issues warnings for undefined symbols unless -z defs
 276            overrides.
 277 
 278            The -B symbolic option is intended for specialized dynamic objects
 279            and is not recommended for general use. To reduce the runtime
 280            relocation processing that is required an object, the creation of a
 281            version definition is recommended.
 282 
 283 
 284        -c name
 285 
 286            Records the configuration file name for use at runtime.
 287            Configuration files can be employed to alter default search paths,
 288            provide a directory cache, together with providing alternative
 289            object dependencies. See crle(1).
 290 
 291 
 292        -C
 293 
 294            Demangles C++ symbol names displayed in diagnostic messages.
 295 
 296 
 297        -d y | n
 298 
 299            When -d y, the default, is specified, ld uses dynamic linking. When
 300            -d n is specified, ld uses static linking. See Static Executables
 301            under DESCRIPTION, and -B dynamic|static.
 302 
 303 
 304        -D token,...
 305 
 306            Prints debugging information as specified by each token, to the
 307            standard error. The special token help indicates the full list of
 308            tokens available. See Debugging Aids in Linker and Libraries Guide.
 309 
 310 
 311        -e epsym
 312        --entry epsym
 313 
 314            Sets the entry point address for the output file to be the symbol
 315            epsym.
 316 
 317 
 318        -f name
 319        --auxiliary name
 320 
 321            Useful only when building a shared object. Specifies that the
 322            symbol table of the shared object is used as an auxiliary filter on
 323            the symbol table of the shared object specified by name. Multiple
 324            instances of this option are allowed. This option can not be
 325            combined with the -F option. See Generating Auxiliary Filters in
 326            Linker and Libraries Guide.
 327 
 328 
 329        -F name
 330        --filter name
 331 
 332            Useful only when building a shared object. Specifies that the
 333            symbol table of the shared object is used as a filter on the symbol
 334            table of the shared object specified by name. Multiple instances of
 335            this option are allowed. This option can not be combined with the
 336            -f option. See Generating Standard Filters in Linker and Libraries
 337            Guide.
 338 
 339 
 340        -G
 341        -shared
 342 
 343            In dynamic mode only, produces a shared object. Undefined symbols
 344            are allowed.  See Chapter 4, Shared Objects, in Linker and
 345            Libraries Guide.
 346 
 347 
 348        -h name
 349        --soname name
 350 
 351            In dynamic mode only, when building a shared object, records name
 352            in the object's dynamic section. name is recorded in any dynamic
 353            objects that are linked with this object rather than the object's
 354            file system name.  Accordingly, name is used by the runtime linker
 355            as the name of the shared object to search for at runtime. See
 356            Recording a Shared Object Name in Linker and Libraries Guide.
 357 
 358 
 359        -i
 360 
 361            Ignores LD_LIBRARY_PATH. This option is useful when an
 362            LD_LIBRARY_PATH setting is in effect to influence the runtime
 363            library search, which would interfere with the link-editing being
 364            performed.
 365 
 366 
 367        -I name
 368        --dynamic-linker name
 369 
 370            When building an executable, uses name as the path name of the
 371            interpreter to be written into the program header. The default in
 372            static mode is no interpreter. In dynamic mode, the default is the
 373            name of the runtime linker, ld.so.1(1). Either case can be
 374            overridden by -I name.  exec(2) loads this interpreter when the
 375            a.out is loaded, and passes control to the interpreter rather than
 376            to the a.out directly.
 377 
 378 
 379        -l x
 380        --library x
 381 
 382            Searches a library libx.so or libx.a, the conventional names for
 383            shared object and archive libraries, respectively.  In dynamic
 384            mode, unless the -B static option is in effect, ld searches each
 385            directory specified in the library search path for a libx.so or
 386            libx.a file. The directory search stops at the first directory
 387            containing either. ld chooses the file ending in .so if -lx expands
 388            to two files with names of the form libx.so and libx.a. If no
 389            libx.so is found, then ld accepts libx.a. In static mode, or when
 390            the -B static option is in effect, ld selects only the file ending
 391            in .a.  ld searches a library when the library is encountered, so
 392            the placement of -l is significant. See Linking With Additional
 393            Libraries in Linker and Libraries Guide.
 394 
 395 
 396        -L path
 397        --library-path path
 398 
 399            Adds path to the library search directories. ld searches for
 400            libraries first in any directories specified by the -L options and
 401            then in the standard directories. This option is useful only if the
 402            option precedes the -l options to which the -L option applies. See
 403            Directories Searched by the Link-Editor in Linker and Libraries
 404            Guide.
 405 
 406            The environment variable LD_LIBRARY_PATH can be used to supplement
 407            the library search path, however the -L option is recommended, as
 408            the environment variable is also interpreted by the runtime
 409            environment. See LD_LIBRARY_PATH under ENVIRONMENT VARIABLES.
 410 
 411 
 412        -m
 413 
 414            Produces a memory map or listing of the input/output sections,
 415            together with any non-fatal multiply-defined symbols, on the
 416            standard output.
 417 
 418 
 419        -M mapfile
 420 
 421            Reads mapfile as a text file of directives to ld. This option can
 422            be specified multiple times. If mapfile is a directory, then all
 423            regular files, as defined by stat(2), within the directory are
 424            processed. See Chapter 9, Mapfile Option, in Linker and Libraries
 425            Guide. Example mapfiles are provided in /usr/lib/ld. See FILES.
 426 
 427 
 428        -N string
 429 
 430            This option causes a DT_NEEDED entry to be added to the .dynamic
 431            section of the object being built. The value of the DT_NEEDED
 432            string is the string that is specified on the command line. This
 433            option is position dependent, and the DT_NEEDED .dynamic entry is
 434            relative to the other dynamic dependencies discovered on the link-
 435            edit line. This option is useful for specifying dependencies within
 436            device driver relocatable objects when combined with the -dy and -r
 437            options.
 438 
 439 
 440        -o outfile
 441        --output outfile
 442 
 443            Produces an output object file that is named outfile. The name of
 444            the default object file is a.out.
 445 
 446 
 447        -p auditlib
 448 
 449            Identifies an audit library, auditlib. This audit library is used
 450            to audit the object being created at runtime. A shared object
 451            identified as requiring auditing with the -p option, has this
 452            requirement inherited by any object that specifies the shared
 453            object as a dependency. See the -P option. See Runtime Linker
 454            Auditing Interface in Linker and Libraries Guide.
 455 
 456 
 457        -P auditlib
 458 
 459            Identifies an audit library, auditlib. This audit library is used
 460            to audit the dependencies of the object being created at runtime.
 461            Dependency auditing can also be inherited from dependencies that
 462            are identified as requiring auditing. See the -p option, and the -z
 463            globalaudit option. See Runtime Linker Auditing Interface in Linker
 464            and Libraries Guide.
 465 
 466 
 467        -Q y | n
 468 
 469            Under -Q y, an ident string is added to the .comment section of the
 470            output file. This string identifies the version of the ld used to
 471            create the file. This results in multiple ld idents when there have
 472            been multiple linking steps, such as when using ld -r.  This
 473            identification is identical with the default action of the cc
 474            command. -Q n suppresses version identification. .comment sections
 475            can be manipulated by the mcs(1) utility.
 476 
 477 
 478        -r
 479        --relocatable
 480 
 481            Combines relocatable object files to produce one relocatable object
 482            file.  ld does not complain about unresolved references. This
 483            option cannot be used with the -a option.
 484 
 485 
 486        -R path
 487        -rpath path
 488 
 489            A colon-separated list of directories used to specify library
 490            search directories to the runtime linker. If present and not NULL,
 491            the path is recorded in the output object file and passed to the
 492            runtime linker. Multiple instances of this option are concatenated
 493            together with each path separated by a colon. See Directories
 494            Searched by the Runtime Linker in Linker and Libraries Guide.
 495 
 496            The use of a runpath within an associated object is preferable to
 497            setting global search paths such as through the LD_LIBRARY_PATH
 498            environment variable. Only the runpaths that are necessary to find
 499            the objects dependencies should be recorded. ldd(1) can also be
 500            used to discover unused runpaths in dynamic objects, when used with
 501            the -U option.
 502 
 503            Various tokens can also be supplied with a runpath that provide a
 504            flexible means of identifying system capabilities or an objects
 505            location. See Appendix C, Establishing Dependencies with Dynamic
 506            String Tokens, in Linker and Libraries Guide. The $ORIGIN token is
 507            especially useful in allowing dynamic objects to be relocated to
 508            different locations in the file system.
 509 
 510 
 511        -s
 512        --strip-all
 513 
 514            Strips symbolic information from the output file. Any debugging
 515            information, that is, .line, .debug*, and .stab* sections, and
 516            their associated relocation entries are removed. Except for
 517            relocatable files, a symbol table SHT_SYMTAB and its associated
 518            string table section are not created in the output object file. The
 519            elimination of a SHT_SYMTAB symbol table can reduce the .stab*
 520            debugging information that is generated using the compiler drivers
 521            -g option. See the -z redlocsym and -z noldynsym options.
 522 
 523 
 524        -S supportlib
 525 
 526            The shared object supportlib is loaded with ld and given
 527            information regarding the linking process. Shared objects that are
 528            defined by using the -S option can also be supplied using the
 529            SGS_SUPPORT environment variable. See Link-Editor Support Interface
 530            in Linker and Libraries Guide.
 531 
 532 
 533        -t
 534 
 535            Turns off the warning for multiply-defined symbols that have
 536            different sizes or different alignments.
 537 
 538 
 539        -u symname
 540        --undefined symname
 541 
 542            Enters symname as an undefined symbol in the symbol table. This
 543            option is useful for loading entirely from an archive library. In
 544            this instance, an unresolved reference is needed to force the
 545            loading of the first routine. The placement of this option on the
 546            command line is significant. This option must be placed before the
 547            library that defines the symbol. See Defining Additional Symbols
 548            with the u option in Linker and Libraries Guide.
 549 
 550 
 551        -V
 552        --version
 553 
 554            Outputs a message giving information about the version of ld being
 555            used.
 556 
 557 
 558        -Y P,dirlist
 559 
 560            Changes the default directories used for finding libraries. dirlist
 561            is a colon-separated path list.
 562 
 563 
 564        -z absexec
 565 
 566            Useful only when building a dynamic executable. Specifies that
 567            references to external absolute symbols should be resolved
 568            immediately instead of being left for resolution at runtime. In
 569            very specialized circumstances, this option removes text
 570            relocations that can result in excessive swap space demands by an
 571            executable.
 572 
 573 
 574        -z allextract | defaultextract | weakextract
 575        --whole-archive | --no-whole-archive
 576 
 577            Alters the extraction criteria of objects from any archives that
 578            follow. By default, archive members are extracted to satisfy
 579            undefined references and to promote tentative definitions with data
 580            definitions. Weak symbol references do not trigger extraction.
 581            Under the -z allextract or --whole-archive options, all archive
 582            members are extracted from the archive. Under -z weakextract, weak
 583            references trigger archive extraction. The -z defaultextract or
 584            --no-whole-archive options provide a means of returning to the
 585            default following use of the former extract options. See Archive
 586            Processing in Linker and Libraries Guide.
 587 
 588 
 589        -z altexec64
 590 
 591            Execute the 64-bit ld. The creation of very large 32-bit objects
 592            can exhaust the virtual memory that is available to the 32-bit ld.
 593            The -z altexec64 option can be used to force the use of the
 594            associated 64-bit ld. The 64-bit ld provides a larger virtual
 595            address space for building 32-bit objects. See The 32-bit link-
 596            editor and 64-bit link-editor in Linker and Libraries Guide.
 597 
 598 
 599        -z combreloc | nocombreloc
 600 
 601            By default, ld combines multiple relocation sections when building
 602            executables or shared objects. This section combination differs
 603            from relocatable objects, in which relocation sections are
 604            maintained in a one-to-one relationship with the sections to which
 605            the relocations must be applied. The -z nocombreloc option disables
 606            this merging of relocation sections, and preserves the one-to-one
 607            relationship found in the original relocatable objects.
 608 
 609            ld sorts the entries of data relocation sections by their symbol
 610            reference. This sorting reduces runtime symbol lookup. When
 611            multiple relocation sections are combined, this sorting produces
 612            the least possible relocation overhead when objects are loaded into
 613            memory, and speeds the runtime loading of dynamic objects.
 614 
 615            Historically, the individual relocation sections were carried over
 616            to any executable or shared object, and the -z combreloc option was
 617            required to enable the relocation section merging previously
 618            described.  Relocation section merging is now the default. The -z
 619            combreloc option is still accepted for the benefit of old build
 620            environments, but the option is unnecessary, and has no effect.
 621 
 622 
 623        -z assert-deflib
 624        -z assert-deflib=libname
 625 
 626            Enables warnings that check the location of where libraries passed
 627            in with -l are found. If the link-editor finds a library on its
 628            default search path it will emit a warning. This warning can be
 629            made fatal in conjunction with the option -z fatal-warnings.
 630            Passing libname white lists a library from this check. The library
 631            must be the full name of the library, e.g.  libc.so. To white list
 632            multiple libraries, the -z assert-deflib=libname option can be
 633            repeated multiple times. This option is useful when trying to build
 634            self-contained objects where a referenced library might exist in
 635            the default system library path and in alternate paths specified by
 636            -L, but you only want the alternate paths to be used.
 637 
 638 
 639        -z defs | nodefs
 640        --no-undefined
 641 
 642            The -z defs option and the --no-undefined option force a fatal
 643            error if any undefined symbols remain at the end of the link. This
 644            mode is the default when an executable is built. For historic
 645            reasons, this mode is not the default when building a shared
 646            object. Use of the -z defs option is recommended, as this mode
 647            assures the object being built is self-contained. A self-contained
 648            object has all symbolic references resolved internally, or to the
 649            object's immediate dependencies.
 650 
 651            The -z nodefs option allows undefined symbols. For historic
 652            reasons, this mode is the default when a shared object is built.
 653            When used with executables, the behavior of references to such
 654            undefined symbols is unspecified. Use of the -z nodefs option is
 655            not recommended.
 656 
 657 
 658        -z direct | nodirect
 659 
 660            Enables or disables direct binding to any dependencies that follow
 661            on the command line. These options allow finer control over direct
 662            binding than the global counterpart -B direct. The -z direct option
 663            also differs from the -B direct option in the following areas.
 664            Direct binding information is not established between a symbol
 665            reference and an associated definition within the object being
 666            created. Lazy loading is not enabled.
 667 
 668 
 669        -z endfiltee
 670 
 671            Marks a filtee so that when processed by a filter, the filtee
 672            terminates any further filtee searches by the filter. See Reducing
 673            Filtee Searches in Linker and Libraries Guide.
 674 
 675 
 676        -z fatal-warnings | nofatal-warnings
 677        --fatal-warnings | --no-fatal-warnings
 678 
 679            Controls the behavior of warnings emitted from the link-editor.
 680            Setting -z fatal-warnings promotes warnings emitted by the link-
 681            editor to fatal errors that will cause the link-editor to fail
 682            before linking. -z nofatal-warnings instead demotes these warnings
 683            such that they will not cause the link-editor to exit prematurely.
 684 
 685 
 686 
 687        -z finiarray=function
 688 
 689            Appends an entry to the .fini_array section of the object being
 690            built.  If no .fini_array section is present, a section is created.
 691            The new entry is initialized to point to function. See
 692            Initialization and Termination Sections in Linker and Libraries
 693            Guide.
 694 
 695 
 696        -z globalaudit
 697 
 698            This option supplements an audit library definition that has been
 699            recorded with the -P option. This option is only meaningful when
 700            building a dynamic executable. Audit libraries that are defined
 701            within an object with the -P option typically allow for the
 702            auditing of the immediate dependencies of the object. The -z
 703            globalaudit promotes the auditor to a global auditor, thus allowing
 704            the auditing of all dependencies. See Invoking the Auditing
 705            Interface in Linker and Libraries Guide.
 706 
 707            An auditor established with the -P option and the -z globalaudit
 708            option, is equivalent to the auditor being established with the
 709            LD_AUDIT environment variable. See ld.so.1(1).
 710 
 711 
 712        -z groupperm | nogroupperm
 713 
 714            Assigns, or deassigns each dependency that follows to a unique
 715            group. The assignment of a dependency to a group has the same
 716            effect as if the dependency had been built using the -B group
 717            option.
 718 
 719 
 720        -z guidance[=id1,id2...]
 721 
 722            Give messages suggesting link-editor features that could improve
 723            the resulting dynamic object.
 724 
 725            Specific classes of suggestion can be silenced by specifying an
 726            optional comma separated list of guidance identifiers.
 727 
 728            The current classes of suggestion provided are:
 729 
 730 
 731            Enable use of direct binding
 732 
 733                Suggests that -z direct or -B direct be present prior to any
 734                specified dependency.  This allows predictable symbol binding
 735                at runtime.
 736 
 737                Can be disabled with -z guidance=nodirect
 738 
 739 
 740            Enable lazy dependency loading
 741 
 742                Suggests that -z lazyload be present prior to any specified
 743                dependency.  This allows the dynamic object to be loaded more
 744                quickly.
 745 
 746                Can be disabled with -z guidance=nolazyload.
 747 
 748 
 749            Shared objects should define all their dependencies.
 750 
 751                Suggests that -z defs be specified on the link-editor command
 752                line.  Shared objects that explicitly state all their
 753                dependencies behave more predictably when used.
 754 
 755                Can be be disabled with -z guidance=nodefs
 756 
 757 
 758            Version 2 mapfile syntax
 759 
 760                Suggests that any specified mapfiles use the more readable
 761                version 2 syntax.
 762 
 763                Can be disabled with -z guidance=nomapfile.
 764 
 765 
 766            Read-only text segment
 767 
 768                Should any runtime relocations within the text segment exist,
 769                suggests that the object be compiled with position independent
 770                code (PIC).  Keeping large allocatable sections read-only
 771                allows them to be shared between processes using a given shared
 772                object.
 773 
 774                Can be disabled with -z guidance=notext
 775 
 776 
 777            No unused dependencies
 778 
 779                Suggests that any dependency not referenced by the resulting
 780                dynamic object be removed from the link-editor command line.
 781 
 782                Can be disabled with -z guidance=nounused.
 783 
 784 
 785        -z help
 786        --help
 787 
 788            Print a summary of the command line options on the standard output
 789            and exit.
 790 
 791 
 792        -z ignore | record
 793 
 794            Ignores, or records, dynamic dependencies that are not referenced
 795            as part of the link-edit. Ignores, or records, unreferenced ELF
 796            sections from the relocatable objects that are read as part of the
 797            link-edit. By default, -z record is in effect.
 798 
 799            If an ELF section is ignored, the section is eliminated from the
 800            output file being generated. A section is ignored when three
 801            conditions are true. The eliminated section must contribute to an
 802            allocatable segment. The eliminated section must provide no global
 803            symbols. No other section from any object that contributes to the
 804            link-edit, must reference an eliminated section.
 805 
 806 
 807        -z initarray=function
 808 
 809            Appends an entry to the .init_array section of the object being
 810            built.  If no .init_array section is present, a section is created.
 811            The new entry is initialized to point to function. See
 812            Initialization and Termination Sections in Linker and Libraries
 813            Guide.
 814 
 815 
 816        -z initfirst
 817 
 818            Marks the object so that its runtime initialization occurs before
 819            the runtime initialization of any other objects brought into the
 820            process at the same time.  In addition, the object runtime
 821            finalization occurs after the runtime finalization of any other
 822            objects removed from the process at the same time.  This option is
 823            only meaningful when building a shared object.
 824 
 825 
 826        -z interpose
 827 
 828            Marks the object as an interposer. At runtime, an object is
 829            identified as an explicit interposer if the object has been tagged
 830            using the -z interpose option. An explicit interposer is also
 831            established when an object is loaded using the LD_PRELOAD
 832            environment variable. Implicit interposition can occur because of
 833            the load order of objects, however, this implicit interposition is
 834            unknown to the runtime linker. Explicit interposition can ensure
 835            that interposition takes place regardless of the order in which
 836            objects are loaded. Explicit interposition also ensures that the
 837            runtime linker searches for symbols in any explicit interposers
 838            when direct bindings are in effect.
 839 
 840 
 841        -z lazyload | nolazyload
 842 
 843            Enables or disables the marking of dynamic dependencies to be
 844            lazily loaded.  Dynamic dependencies which are marked lazyload are
 845            not loaded at initial process start-up. These dependencies are
 846            delayed until the first binding to the object is made. Note: Lazy
 847            loading requires the correct declaration of dependencies, together
 848            with associated runpaths for each dynamic object used within a
 849            process. See Lazy Loading of Dynamic Dependencies in Linker and
 850            Libraries Guide.
 851 
 852 
 853        -z ld32=arg1,arg2,...
 854        -z ld64=arg1,arg2,...
 855 
 856            The class of the link-editor is affected by the class of the output
 857            file being created and by the capabilities of the underlying
 858            operating system. The -z ld[32|64] options provide a means of
 859            defining any link-editor argument. The defined argument is only
 860            interpreted, respectively, by the 32-bit class or 64-bit class of
 861            the link-editor.
 862 
 863            For example, support libraries are class specific, so the correct
 864            class of support library can be ensured using:
 865 
 866              ld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...
 867 
 868 
 869            The class of link-editor that is invoked is determined from the ELF
 870            class of the first relocatable file that is seen on the command
 871            line. This determination is carried out prior to any -z ld[32|64]
 872            processing.
 873 
 874 
 875        -z loadfltr
 876 
 877            Marks a filter to indicate that filtees must be processed
 878            immediately at runtime. Normally, filter processing is delayed
 879            until a symbol reference is bound to the filter. The runtime
 880            processing of an object that contains this flag mimics that which
 881            occurs if the LD_LOADFLTR environment variable is in effect. See
 882            the ld.so.1(1).
 883 
 884 
 885        -z muldefs
 886        --allow-multiple-definition
 887 
 888            Allows multiple symbol definitions. By default, multiple symbol
 889            definitions that occur between relocatable objects result in a
 890            fatal error condition. This option, suppresses the error condition,
 891            allowing the first symbol definition to be taken.
 892 
 893 
 894        -z nocompstrtab
 895 
 896            Disables the compression of ELF string tables. By default, string
 897            compression is applied to SHT_STRTAB sections, and to SHT_PROGBITS
 898            sections that have their SHF_MERGE and SHF_STRINGS section flags
 899            set.
 900 
 901 
 902        -z nodefaultlib
 903 
 904            Marks the object so that the runtime default library search path,
 905            used after any LD_LIBRARY_PATH or runpaths, is ignored. This option
 906            implies that all dependencies of the object can be satisfied from
 907            its runpath.
 908 
 909 
 910        -z nodelete
 911 
 912            Marks the object as non-deletable at runtime. This mode is similar
 913            to adding the object to the process by using dlopen(3C) with the
 914            RTLD_NODELETE mode.
 915 
 916 
 917        -z nodlopen
 918 
 919            Marks the object as not available to dlopen(3C), either as the
 920            object specified by the dlopen(), or as any form of dependency
 921            required by the object specified by the dlopen(). This option is
 922            only meaningful when building a shared object.
 923 
 924 
 925        -z nodump
 926 
 927            Marks the object as not available to dldump(3C).
 928 
 929 
 930        -z noldynsym
 931 
 932            Prevents the inclusion of a .SUNW_ldynsym section in dynamic
 933            executables or sharable libraries. The .SUNW_ldynsym section
 934            augments the .dynsym section by providing symbols for local
 935            functions. Local function symbols allow debuggers to display local
 936            function names in stack traces from stripped programs. Similarly,
 937            dladdr(3C) is able to supply more accurate results.
 938 
 939            The -z noldynsym option also prevents the inclusion of the two
 940            symbol sort sections that are related to the .SUNW_ldynsym section.
 941            The .SUNW_dynsymsort section provides sorted access to regular
 942            function and variable symbols. The .SUNW_dyntlssort section
 943            provides sorted access to thread local storage (TLS) variable
 944            symbols.
 945 
 946            The .SUNW_ldynsym, .SUNW_dynsymsort, and .SUNW_dyntlssort sections,
 947            which becomes part of the allocable text segment of the resulting
 948            file, cannot be removed by strip(1). Therefore, the -z noldynsym
 949            option is the only way to prevent their inclusion.  See the -s and
 950            -z redlocsym options.
 951 
 952 
 953        -z nopartial
 954 
 955            Partially initialized symbols, that are defined within relocatable
 956            object files, are expanded in the output file being generated.
 957 
 958 
 959        -z noversion
 960 
 961            Does not record any versioning sections. Any version sections or
 962            associated .dynamic section entries are not generated in the output
 963            image.
 964 
 965 
 966        -z now
 967 
 968            Marks the object as requiring non-lazy runtime binding. This mode
 969            is similar to adding the object to the process by using dlopen(3C)
 970            with the RTLD_NOW mode. This mode is also similar to having the
 971            LD_BIND_NOW environment variable in effect. See ld.so.1(1).
 972 
 973 
 974        -z origin
 975 
 976            Marks the object as requiring immediate $ORIGIN processing at
 977            runtime.  This option is only maintained for historic
 978            compatibility, as the runtime analysis of objects to provide for
 979            $ORIGIN processing is now default.
 980 
 981 
 982        -z preinitarray=function
 983 
 984            Appends an entry to the .preinitarray section of the object being
 985            built. If no .preinitarray section is present, a section is
 986            created.  The new entry is initialized to point to function. See
 987            Initialization and Termination Sections in Linker and Libraries
 988            Guide.
 989 
 990 
 991        -z redlocsym
 992 
 993            Eliminates all local symbols except for the SECT symbols from the
 994            symbol table SHT_SYMTAB. All relocations that refer to local
 995            symbols are updated to refer to the corresponding SECT symbol. This
 996            option allows specialized objects to greatly reduce their symbol
 997            table sizes. Eliminated local symbols can reduce the .stab*
 998            debugging information that is generated using the compiler drivers
 999            -g option. See the -s and -z noldynsym options.
1000 
1001 
1002        -z relaxreloc
1003 
1004            ld normally issues a fatal error upon encountering a relocation
1005            using a symbol that references an eliminated COMDAT section. If -z
1006            relaxreloc is enabled, ld instead redirects such relocations to the
1007            equivalent symbol in the COMDAT section that was kept. -z
1008            relaxreloc is a specialized option, mainly of interest to compiler
1009            authors, and is not intended for general use.
1010 
1011 
1012        -z rescan-now
1013        -z rescan
1014 
1015            These options rescan the archive files that are provided to the
1016            link-edit. By default, archives are processed once as the archives
1017            appear on the command line. Archives are traditionally specified at
1018            the end of the command line so that their symbol definitions
1019            resolve any preceding references. However, specifying archives
1020            multiple times to satisfy their own interdependencies can be
1021            necessary.
1022 
1023            -z rescan-now is a positional option, and is processed by the link-
1024            editor immediately when encountered on the command line. All
1025            archives seen on the command line up to that point are immediately
1026            reprocessed in an attempt to locate additional archive members that
1027            resolve symbol references. This archive rescanning is repeated
1028            until a pass over the archives occurs in which no new members are
1029            extracted.
1030 
1031            -z rescan is a position independent option. The link-editor defers
1032            the rescan operation until after it has processed the entire
1033            command line, and then initiates a final rescan operation over all
1034            archives seen on the command line. The -z rescan operation can
1035            interact          incorrectly with objects that contain
1036            initialization (.init) or finalization (.fini) sections, preventing
1037            the code in those sections from running. For this reason, -z rescan
1038            is deprecated, and use of -z rescan-now is advised.
1039 
1040 
1041        -z rescan-start ... -z rescan-end
1042        --start-group ... --end-group
1043        -( ... -)
1044 
1045            Defines an archive rescan group. This is a positional construct,
1046            and is processed by the link-editor immediately upon encountering
1047            the closing delimiter option.  Archives found within the group
1048            delimiter options are reprocessed as a group in an attempt to
1049            locate  additional archive members that resolve symbol references.
1050            This archive rescanning  is repeated  until a  pass over the
1051            archives On the occurs in  which no  new  members are extracted.
1052            Archive rescan groups cannot be nested.
1053 
1054 
1055        -z target=sparc|x86
1056 
1057            Specifies the machine type for the output object. Supported targets
1058            are Sparc and x86. The 32-bit machine type for the specified target
1059            is used unless the -64 option is also present, in which case the
1060            corresponding 64-bit machine type is used. By default, the machine
1061            type of the object being generated is determined from the first ELF
1062            object processed from the command line. If no objects are
1063            specified, the machine type is determined by the first object
1064            encountered within the first archive processed from the command
1065            line. If there are no objects or archives, the link-editor assumes
1066            the native machine. This option is useful when creating an object
1067            directly with ld whose input is solely from a mapfile. See the -M
1068            option.  It can also be useful in the rare case of linking entirely
1069            from an archive that contains objects of different machine types
1070            for which the first object is not of the desired machine type. See
1071            The 32-bit link-editor and 64-bit link-editor in Linker and
1072            Libraries Guide.
1073 
1074 
1075        -z text
1076 
1077            In dynamic mode only, forces a fatal error if any relocations
1078            against non-writable, allocatable sections remain. For historic
1079            reasons, this mode is not the default when building an executable
1080            or shared object. However, its use is recommended to ensure that
1081            the text segment of the dynamic object being built is shareable
1082            between multiple running processes. A shared text segment incurs
1083            the least relocation overhead when loaded into memory. See
1084            Position-Independent Code in Linker and Libraries Guide.
1085 
1086 
1087        -z textoff
1088 
1089            In dynamic mode only, allows relocations against all allocatable
1090            sections, including non-writable ones. This mode is the default
1091            when building a shared object.
1092 
1093 
1094        -z textwarn
1095 
1096            In dynamic mode only, lists a warning if any relocations against
1097            non-writable, allocatable sections remain. This mode is the default
1098            when building an executable.
1099 
1100 
1101        -z verbose
1102 
1103            This option provides additional warning diagnostics during a link-
1104            edit.  Presently, this option conveys suspicious use of
1105            displacement relocations. This option also conveys the restricted
1106            use of static TLS relocations when building shared objects. In
1107            future, this option might be enhanced to provide additional
1108            diagnostics that are deemed too noisy to be generated by default.
1109 
1110 
1111        -zwrap=symbol
1112        -wrap= symbol
1113        --wrap= symbol
1114 
1115            Rename undefined references to symbol in order to allow wrapper
1116            code to be linked into the output object without having to modify
1117            source code. When -z wrap is specified, all undefined references to
1118            symbol are modified to reference __wrap_symbol, and all references
1119            to __real_symbol are modified to reference symbol. The user is
1120            expected to provide an object containing the __wrap_symbol
1121            function. This wrapper function can call __real_symbol in order to
1122            reference the actual function being wrapped.
1123 
1124            The following is an example of a wrapper for the malloc(3C)
1125            function:
1126 
1127              void *
1128              __wrap_malloc(size_t c)
1129              {
1130                      (void) printf("malloc called with %zu\n", c);
1131                      return (__real_malloc(c));
1132              }
1133 
1134            If you link other code with this file using -z wrap=malloc to
1135            compile all the objects, then all calls to malloc will call the
1136            function __wrap_malloc instead. The call to __real_malloc will call
1137            the real malloc function.
1138 
1139            The real and wrapped functions should be maintained in separate
1140            source files.  Otherwise, the compiler or assembler may resolve the
1141            call instead of leaving that operation for the link-editor to carry
1142            out, and prevent the wrap from occurring.
1143 
1144 
1145 ENVIRONMENT VARIABLES
1146        LD_ALTEXEC
1147 
1148            An alternative link-editor path name. ld executes, and passes
1149            control to this alternative link-editor. This environment variable
1150            provides a generic means of overriding the default link-editor that
1151            is called from the various compiler drivers. See the -z altexec64
1152            option.
1153 
1154 
1155        LD_LIBRARY_PATH
1156 
1157            A list of directories in which to search for the libraries
1158            specified using the -l option. Multiple directories are separated
1159            by a colon. In the most general case, this environment variable
1160            contains two directory lists separated by a semicolon:
1161 
1162              dirlist1;dirlist2
1163 
1164 
1165            If ld is called with any number of occurrences of -L, as in:
1166 
1167              ld ... -Lpath1 ... -Lpathn ...
1168 
1169 
1170            then the search path ordering is:
1171 
1172              dirlist1 path1 ... pathn dirlist2 LIBPATH
1173 
1174 
1175            When the list of directories does not contain a semicolon, the list
1176            is interpreted as dirlist2.
1177 
1178            The LD_LIBRARY_PATH environment variable also affects the runtime
1179            linkers search for dynamic dependencies.
1180 
1181            This environment variable can be specified with a _32 or _64
1182            suffix. This makes the environment variable specific, respectively,
1183            to 32-bit or 64-bit processes and overrides any non-suffixed
1184            version of the environment variable that is in effect.
1185 
1186 
1187        LD_NOEXEC_64
1188 
1189            Suppresses the automatic execution of the 64-bit link-editor. By
1190            default, the link-editor executes the 64-bit version when the ELF
1191            class of the first relocatable file identifies a 64-bit object. The
1192            64-bit image that a 32-bit link-editor can create, has some
1193            limitations. However, some link-edits might find the use of the
1194            32-bit link-editor faster.
1195 
1196 
1197        LD_OPTIONS
1198 
1199            A default set of options to ld. LD_OPTIONS is interpreted by ld
1200            just as though its value had been placed on the command line,
1201            immediately following the name used to invoke ld, as in:
1202 
1203              ld $LD_OPTIONS ... other-arguments ...
1204 
1205 
1206 
1207 
1208        LD_RUN_PATH
1209 
1210            An alternative mechanism for specifying a runpath to the link-
1211            editor. See the -R option. If both LD_RUN_PATH and the -R option
1212            are specified, -R supersedes.
1213 
1214 
1215        SGS_SUPPORT
1216 
1217            Provides a colon-separated list of shared objects that are loaded
1218            with the link-editor and given information regarding the linking
1219            process. This environment variable can be specified with a _32 or
1220            _64 suffix. This makes the environment variable specific,
1221            respectively, to the 32-bit or 64-bit class of ld and overrides any
1222            non-suffixed version of the environment variable that is in effect.
1223            See the -S option.
1224 
1225 
1226 
1227        Notice that environment variable-names that begin with the characters
1228        'LD_' are reserved for possible future enhancements to ld and
1229        ld.so.1(1).
1230 
1231 FILES
1232        libx.so
1233                       shared object libraries.
1234 
1235 
1236        libx.a
1237                       archive libraries.
1238 
1239 
1240        a.out
1241                       default output file.
1242 
1243 
1244        LIBPATH
1245                       For 32-bit libraries, the default search path is
1246                       /usr/ccs/lib, followed by /lib, and finally /usr/lib.
1247                       For 64-bit libraries, the default search path is
1248                       /lib/64, followed by /usr/lib/64.
1249 
1250 
1251        /usr/lib/ld
1252                       A directory containing several mapfiles that can be used
1253                       during link-editing. These mapfiles provide various
1254                       capabilities, such as defining memory layouts, aligning
1255                       bss, and defining non-executable stacks.
1256 
1257 
1258 ATTRIBUTES
1259        See attributes(5) for descriptions of the following attributes:
1260 
1261 
1262 
1263 
1264        +--------------------+-----------------+
1265        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
1266        +--------------------+-----------------+
1267        |Interface Stability | Committed       |
1268        +--------------------+-----------------+
1269 
1270 SEE ALSO
1271        as(1), crle(1), gprof(1), ld.so.1(1), ldd(1), mcs(1), pvs(1), exec(2),
1272        stat(2), dlopen(3C), dldump(3C), elf(3ELF), ar.h(3HEAD), a.out(4),
1273        attributes(5)
1274 
1275 
1276        Linker and Libraries Guide
1277 
1278 NOTES
1279        Default options applied by ld are maintained for historic reasons. In
1280        today's programming environment, where dynamic objects dominate,
1281        alternative defaults would often make more sense. However, historic
1282        defaults must be maintained to ensure compatibility with existing
1283        program development environments. Historic defaults are called out
1284        wherever possible in this manual. For a description of the current
1285        recommended options, see Appendix A, Link-Editor Quick Reference, in
1286        Linker and Libraries Guide.
1287 
1288 
1289        If the file being created by ld already exists, the file is unlinked
1290        after all input files have been processed. A new file with the
1291        specified name is then created. This allows ld to create a new version
1292        of the file, while simultaneously allowing existing processes that are
1293        accessing the old file contents to continue running. If the old file
1294        has no other links, the disk space of the removed file is freed when
1295        the last process referencing the file terminates.
1296 
1297 
1298        The behavior of ld when the file being created already exists was
1299        changed with SXCE build 43. In older versions, the existing file was
1300        rewritten in place, an approach with the potential to corrupt any
1301        running processes that is using the file. This change has an
1302        implication for output files that have multiple hard links in the file
1303        system. Previously, all links would remain intact, with all links
1304        accessing the new file contents. The new ld behavior breaks such links,
1305        with the result that only the specified output file name references the
1306        new file. All the other links continue to reference the old file. To
1307        ensure consistent behavior, applications that rely on multiple hard
1308        links to linker output files should explicitly remove and relink the
1309        other file names.
1310 
1311 
1312 
1313                               September 10, 2013                         LD(1)