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 aslr[=state]] [-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 aslr[=state]
 600 
 601            Specify whether the executable's address space should be randomized
 602            on execution.  If state is "enabled" randomization will always
 603            occur when this executable is run (regardless of inherited
 604            settings).  If state is "disabled" randomization will never occur
 605            when this executable is run.  If state is omitted, ASLR is enabled.
 606 
 607            An executable that should simply use the settings inherited from
 608            its environment should not use this flag at all.
 609 
 610 
 611        -z combreloc | nocombreloc
 612 
 613            By default, ld combines multiple relocation sections when building
 614            executables or shared objects. This section combination differs
 615            from relocatable objects, in which relocation sections are
 616            maintained in a one-to-one relationship with the sections to which
 617            the relocations must be applied. The -z nocombreloc option disables
 618            this merging of relocation sections, and preserves the one-to-one
 619            relationship found in the original relocatable objects.
 620 
 621            ld sorts the entries of data relocation sections by their symbol
 622            reference. This sorting reduces runtime symbol lookup. When
 623            multiple relocation sections are combined, this sorting produces
 624            the least possible relocation overhead when objects are loaded into
 625            memory, and speeds the runtime loading of dynamic objects.
 626 
 627            Historically, the individual relocation sections were carried over
 628            to any executable or shared object, and the -z combreloc option was
 629            required to enable the relocation section merging previously
 630            described.  Relocation section merging is now the default. The -z
 631            combreloc option is still accepted for the benefit of old build
 632            environments, but the option is unnecessary, and has no effect.
 633 
 634 
 635        -z assert-deflib
 636        -z assert-deflib=libname
 637 
 638            Enables warnings that check the location of where libraries passed
 639            in with -l are found. If the link-editor finds a library on its
 640            default search path it will emit a warning. This warning can be
 641            made fatal in conjunction with the option -z fatal-warnings.
 642            Passing libname white lists a library from this check. The library
 643            must be the full name of the library, e.g.  libc.so. To white list
 644            multiple libraries, the -z assert-deflib=libname option can be
 645            repeated multiple times. This option is useful when trying to build
 646            self-contained objects where a referenced library might exist in
 647            the default system library path and in alternate paths specified by
 648            -L, but you only want the alternate paths to be used.
 649 
 650 
 651        -z defs | nodefs
 652        --no-undefined
 653 
 654            The -z defs option and the --no-undefined option force a fatal
 655            error if any undefined symbols remain at the end of the link. This
 656            mode is the default when an executable is built. For historic
 657            reasons, this mode is not the default when building a shared
 658            object. Use of the -z defs option is recommended, as this mode
 659            assures the object being built is self-contained. A self-contained
 660            object has all symbolic references resolved internally, or to the
 661            object's immediate dependencies.
 662 
 663            The -z nodefs option allows undefined symbols. For historic
 664            reasons, this mode is the default when a shared object is built.
 665            When used with executables, the behavior of references to such
 666            undefined symbols is unspecified. Use of the -z nodefs option is
 667            not recommended.
 668 
 669 
 670        -z direct | nodirect
 671 
 672            Enables or disables direct binding to any dependencies that follow
 673            on the command line. These options allow finer control over direct
 674            binding than the global counterpart -B direct. The -z direct option
 675            also differs from the -B direct option in the following areas.
 676            Direct binding information is not established between a symbol
 677            reference and an associated definition within the object being
 678            created. Lazy loading is not enabled.
 679 
 680 
 681        -z endfiltee
 682 
 683            Marks a filtee so that when processed by a filter, the filtee
 684            terminates any further filtee searches by the filter. See Reducing
 685            Filtee Searches in Linker and Libraries Guide.
 686 
 687 
 688        -z fatal-warnings | nofatal-warnings
 689        --fatal-warnings | --no-fatal-warnings
 690 
 691            Controls the behavior of warnings emitted from the link-editor.
 692            Setting -z fatal-warnings promotes warnings emitted by the link-
 693            editor to fatal errors that will cause the link-editor to fail
 694            before linking. -z nofatal-warnings instead demotes these warnings
 695            such that they will not cause the link-editor to exit prematurely.
 696 
 697 
 698 
 699        -z finiarray=function
 700 
 701            Appends an entry to the .fini_array section of the object being
 702            built.  If no .fini_array section is present, a section is created.
 703            The new entry is initialized to point to function. See
 704            Initialization and Termination Sections in Linker and Libraries
 705            Guide.
 706 
 707 
 708        -z globalaudit
 709 
 710            This option supplements an audit library definition that has been
 711            recorded with the -P option. This option is only meaningful when
 712            building a dynamic executable. Audit libraries that are defined
 713            within an object with the -P option typically allow for the
 714            auditing of the immediate dependencies of the object. The -z
 715            globalaudit promotes the auditor to a global auditor, thus allowing
 716            the auditing of all dependencies. See Invoking the Auditing
 717            Interface in Linker and Libraries Guide.
 718 
 719            An auditor established with the -P option and the -z globalaudit
 720            option, is equivalent to the auditor being established with the
 721            LD_AUDIT environment variable. See ld.so.1(1).
 722 
 723 
 724        -z groupperm | nogroupperm
 725 
 726            Assigns, or deassigns each dependency that follows to a unique
 727            group. The assignment of a dependency to a group has the same
 728            effect as if the dependency had been built using the -B group
 729            option.
 730 
 731 
 732        -z guidance[=id1,id2...]
 733 
 734            Give messages suggesting link-editor features that could improve
 735            the resulting dynamic object.
 736 
 737            Specific classes of suggestion can be silenced by specifying an
 738            optional comma separated list of guidance identifiers.
 739 
 740            The current classes of suggestion provided are:
 741 
 742 
 743            Enable use of direct binding
 744 
 745                Suggests that -z direct or -B direct be present prior to any
 746                specified dependency.  This allows predictable symbol binding
 747                at runtime.
 748 
 749                Can be disabled with -z guidance=nodirect
 750 
 751 
 752            Enable lazy dependency loading
 753 
 754                Suggests that -z lazyload be present prior to any specified
 755                dependency.  This allows the dynamic object to be loaded more
 756                quickly.
 757 
 758                Can be disabled with -z guidance=nolazyload.
 759 
 760 
 761            Shared objects should define all their dependencies.
 762 
 763                Suggests that -z defs be specified on the link-editor command
 764                line.  Shared objects that explicitly state all their
 765                dependencies behave more predictably when used.
 766 
 767                Can be be disabled with -z guidance=nodefs
 768 
 769 
 770            Version 2 mapfile syntax
 771 
 772                Suggests that any specified mapfiles use the more readable
 773                version 2 syntax.
 774 
 775                Can be disabled with -z guidance=nomapfile.
 776 
 777 
 778            Read-only text segment
 779 
 780                Should any runtime relocations within the text segment exist,
 781                suggests that the object be compiled with position independent
 782                code (PIC).  Keeping large allocatable sections read-only
 783                allows them to be shared between processes using a given shared
 784                object.
 785 
 786                Can be disabled with -z guidance=notext
 787 
 788 
 789            No unused dependencies
 790 
 791                Suggests that any dependency not referenced by the resulting
 792                dynamic object be removed from the link-editor command line.
 793 
 794                Can be disabled with -z guidance=nounused.
 795 
 796 
 797        -z help
 798        --help
 799 
 800            Print a summary of the command line options on the standard output
 801            and exit.
 802 
 803 
 804        -z ignore | record
 805 
 806            Ignores, or records, dynamic dependencies that are not referenced
 807            as part of the link-edit. Ignores, or records, unreferenced ELF
 808            sections from the relocatable objects that are read as part of the
 809            link-edit. By default, -z record is in effect.
 810 
 811            If an ELF section is ignored, the section is eliminated from the
 812            output file being generated. A section is ignored when three
 813            conditions are true. The eliminated section must contribute to an
 814            allocatable segment. The eliminated section must provide no global
 815            symbols. No other section from any object that contributes to the
 816            link-edit, must reference an eliminated section.
 817 
 818 
 819        -z initarray=function
 820 
 821            Appends an entry to the .init_array section of the object being
 822            built.  If no .init_array section is present, a section is created.
 823            The new entry is initialized to point to function. See
 824            Initialization and Termination Sections in Linker and Libraries
 825            Guide.
 826 
 827 
 828        -z initfirst
 829 
 830            Marks the object so that its runtime initialization occurs before
 831            the runtime initialization of any other objects brought into the
 832            process at the same time.  In addition, the object runtime
 833            finalization occurs after the runtime finalization of any other
 834            objects removed from the process at the same time.  This option is
 835            only meaningful when building a shared object.
 836 
 837 
 838        -z interpose
 839 
 840            Marks the object as an interposer. At runtime, an object is
 841            identified as an explicit interposer if the object has been tagged
 842            using the -z interpose option. An explicit interposer is also
 843            established when an object is loaded using the LD_PRELOAD
 844            environment variable. Implicit interposition can occur because of
 845            the load order of objects, however, this implicit interposition is
 846            unknown to the runtime linker. Explicit interposition can ensure
 847            that interposition takes place regardless of the order in which
 848            objects are loaded. Explicit interposition also ensures that the
 849            runtime linker searches for symbols in any explicit interposers
 850            when direct bindings are in effect.
 851 
 852 
 853        -z lazyload | nolazyload
 854 
 855            Enables or disables the marking of dynamic dependencies to be
 856            lazily loaded.  Dynamic dependencies which are marked lazyload are
 857            not loaded at initial process start-up. These dependencies are
 858            delayed until the first binding to the object is made. Note: Lazy
 859            loading requires the correct declaration of dependencies, together
 860            with associated runpaths for each dynamic object used within a
 861            process. See Lazy Loading of Dynamic Dependencies in Linker and
 862            Libraries Guide.
 863 
 864 
 865        -z ld32=arg1,arg2,...
 866        -z ld64=arg1,arg2,...
 867 
 868            The class of the link-editor is affected by the class of the output
 869            file being created and by the capabilities of the underlying
 870            operating system. The -z ld[32|64] options provide a means of
 871            defining any link-editor argument. The defined argument is only
 872            interpreted, respectively, by the 32-bit class or 64-bit class of
 873            the link-editor.
 874 
 875            For example, support libraries are class specific, so the correct
 876            class of support library can be ensured using:
 877 
 878              ld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...
 879 
 880 
 881            The class of link-editor that is invoked is determined from the ELF
 882            class of the first relocatable file that is seen on the command
 883            line. This determination is carried out prior to any -z ld[32|64]
 884            processing.
 885 
 886 
 887        -z loadfltr
 888 
 889            Marks a filter to indicate that filtees must be processed
 890            immediately at runtime. Normally, filter processing is delayed
 891            until a symbol reference is bound to the filter. The runtime
 892            processing of an object that contains this flag mimics that which
 893            occurs if the LD_LOADFLTR environment variable is in effect. See
 894            the ld.so.1(1).
 895 
 896 
 897        -z muldefs
 898        --allow-multiple-definition
 899 
 900            Allows multiple symbol definitions. By default, multiple symbol
 901            definitions that occur between relocatable objects result in a
 902            fatal error condition. This option, suppresses the error condition,
 903            allowing the first symbol definition to be taken.
 904 
 905 
 906        -z nocompstrtab
 907 
 908            Disables the compression of ELF string tables. By default, string
 909            compression is applied to SHT_STRTAB sections, and to SHT_PROGBITS
 910            sections that have their SHF_MERGE and SHF_STRINGS section flags
 911            set.
 912 
 913 
 914        -z nodefaultlib
 915 
 916            Marks the object so that the runtime default library search path,
 917            used after any LD_LIBRARY_PATH or runpaths, is ignored. This option
 918            implies that all dependencies of the object can be satisfied from
 919            its runpath.
 920 
 921 
 922        -z nodelete
 923 
 924            Marks the object as non-deletable at runtime. This mode is similar
 925            to adding the object to the process by using dlopen(3C) with the
 926            RTLD_NODELETE mode.
 927 
 928 
 929        -z nodlopen
 930 
 931            Marks the object as not available to dlopen(3C), either as the
 932            object specified by the dlopen(), or as any form of dependency
 933            required by the object specified by the dlopen(). This option is
 934            only meaningful when building a shared object.
 935 
 936 
 937        -z nodump
 938 
 939            Marks the object as not available to dldump(3C).
 940 
 941 
 942        -z noldynsym
 943 
 944            Prevents the inclusion of a .SUNW_ldynsym section in dynamic
 945            executables or sharable libraries. The .SUNW_ldynsym section
 946            augments the .dynsym section by providing symbols for local
 947            functions. Local function symbols allow debuggers to display local
 948            function names in stack traces from stripped programs. Similarly,
 949            dladdr(3C) is able to supply more accurate results.
 950 
 951            The -z noldynsym option also prevents the inclusion of the two
 952            symbol sort sections that are related to the .SUNW_ldynsym section.
 953            The .SUNW_dynsymsort section provides sorted access to regular
 954            function and variable symbols. The .SUNW_dyntlssort section
 955            provides sorted access to thread local storage (TLS) variable
 956            symbols.
 957 
 958            The .SUNW_ldynsym, .SUNW_dynsymsort, and .SUNW_dyntlssort sections,
 959            which becomes part of the allocable text segment of the resulting
 960            file, cannot be removed by strip(1). Therefore, the -z noldynsym
 961            option is the only way to prevent their inclusion.  See the -s and
 962            -z redlocsym options.
 963 
 964 
 965        -z nopartial
 966 
 967            Partially initialized symbols, that are defined within relocatable
 968            object files, are expanded in the output file being generated.
 969 
 970 
 971        -z noversion
 972 
 973            Does not record any versioning sections. Any version sections or
 974            associated .dynamic section entries are not generated in the output
 975            image.
 976 
 977 
 978        -z now
 979 
 980            Marks the object as requiring non-lazy runtime binding. This mode
 981            is similar to adding the object to the process by using dlopen(3C)
 982            with the RTLD_NOW mode. This mode is also similar to having the
 983            LD_BIND_NOW environment variable in effect. See ld.so.1(1).
 984 
 985 
 986        -z origin
 987 
 988            Marks the object as requiring immediate $ORIGIN processing at
 989            runtime.  This option is only maintained for historic
 990            compatibility, as the runtime analysis of objects to provide for
 991            $ORIGIN processing is now default.
 992 
 993 
 994        -z preinitarray=function
 995 
 996            Appends an entry to the .preinitarray section of the object being
 997            built. If no .preinitarray section is present, a section is
 998            created.  The new entry is initialized to point to function. See
 999            Initialization and Termination Sections in Linker and Libraries
1000            Guide.
1001 
1002 
1003        -z redlocsym
1004 
1005            Eliminates all local symbols except for the SECT symbols from the
1006            symbol table SHT_SYMTAB. All relocations that refer to local
1007            symbols are updated to refer to the corresponding SECT symbol. This
1008            option allows specialized objects to greatly reduce their symbol
1009            table sizes. Eliminated local symbols can reduce the .stab*
1010            debugging information that is generated using the compiler drivers
1011            -g option. See the -s and -z noldynsym options.
1012 
1013 
1014        -z relaxreloc
1015 
1016            ld normally issues a fatal error upon encountering a relocation
1017            using a symbol that references an eliminated COMDAT section. If -z
1018            relaxreloc is enabled, ld instead redirects such relocations to the
1019            equivalent symbol in the COMDAT section that was kept. -z
1020            relaxreloc is a specialized option, mainly of interest to compiler
1021            authors, and is not intended for general use.
1022 
1023 
1024        -z rescan-now
1025        -z rescan
1026 
1027            These options rescan the archive files that are provided to the
1028            link-edit. By default, archives are processed once as the archives
1029            appear on the command line. Archives are traditionally specified at
1030            the end of the command line so that their symbol definitions
1031            resolve any preceding references. However, specifying archives
1032            multiple times to satisfy their own interdependencies can be
1033            necessary.
1034 
1035            -z rescan-now is a positional option, and is processed by the link-
1036            editor immediately when encountered on the command line. All
1037            archives seen on the command line up to that point are immediately
1038            reprocessed in an attempt to locate additional archive members that
1039            resolve symbol references. This archive rescanning is repeated
1040            until a pass over the archives occurs in which no new members are
1041            extracted.
1042 
1043            -z rescan is a position independent option. The link-editor defers
1044            the rescan operation until after it has processed the entire
1045            command line, and then initiates a final rescan operation over all
1046            archives seen on the command line. The -z rescan operation can
1047            interact          incorrectly with objects that contain
1048            initialization (.init) or finalization (.fini) sections, preventing
1049            the code in those sections from running. For this reason, -z rescan
1050            is deprecated, and use of -z rescan-now is advised.
1051 
1052 
1053        -z rescan-start ... -z rescan-end
1054        --start-group ... --end-group
1055        -( ... -)
1056 
1057            Defines an archive rescan group. This is a positional construct,
1058            and is processed by the link-editor immediately upon encountering
1059            the closing delimiter option.  Archives found within the group
1060            delimiter options are reprocessed as a group in an attempt to
1061            locate  additional archive members that resolve symbol references.
1062            This archive rescanning  is repeated  until a  pass over the
1063            archives On the occurs in  which no  new  members are extracted.
1064            Archive rescan groups cannot be nested.
1065 
1066 
1067        -z target=sparc|x86
1068 
1069            Specifies the machine type for the output object. Supported targets
1070            are Sparc and x86. The 32-bit machine type for the specified target
1071            is used unless the -64 option is also present, in which case the
1072            corresponding 64-bit machine type is used. By default, the machine
1073            type of the object being generated is determined from the first ELF
1074            object processed from the command line. If no objects are
1075            specified, the machine type is determined by the first object
1076            encountered within the first archive processed from the command
1077            line. If there are no objects or archives, the link-editor assumes
1078            the native machine. This option is useful when creating an object
1079            directly with ld whose input is solely from a mapfile. See the -M
1080            option.  It can also be useful in the rare case of linking entirely
1081            from an archive that contains objects of different machine types
1082            for which the first object is not of the desired machine type. See
1083            The 32-bit link-editor and 64-bit link-editor in Linker and
1084            Libraries Guide.
1085 
1086 
1087        -z text
1088 
1089            In dynamic mode only, forces a fatal error if any relocations
1090            against non-writable, allocatable sections remain. For historic
1091            reasons, this mode is not the default when building an executable
1092            or shared object. However, its use is recommended to ensure that
1093            the text segment of the dynamic object being built is shareable
1094            between multiple running processes. A shared text segment incurs
1095            the least relocation overhead when loaded into memory. See
1096            Position-Independent Code in Linker and Libraries Guide.
1097 
1098 
1099        -z textoff
1100 
1101            In dynamic mode only, allows relocations against all allocatable
1102            sections, including non-writable ones. This mode is the default
1103            when building a shared object.
1104 
1105 
1106        -z textwarn
1107 
1108            In dynamic mode only, lists a warning if any relocations against
1109            non-writable, allocatable sections remain. This mode is the default
1110            when building an executable.
1111 
1112 
1113        -z verbose
1114 
1115            This option provides additional warning diagnostics during a link-
1116            edit.  Presently, this option conveys suspicious use of
1117            displacement relocations. This option also conveys the restricted
1118            use of static TLS relocations when building shared objects. In
1119            future, this option might be enhanced to provide additional
1120            diagnostics that are deemed too noisy to be generated by default.
1121 
1122 
1123        -zwrap=symbol
1124        -wrap= symbol
1125        --wrap= symbol
1126 
1127            Rename undefined references to symbol in order to allow wrapper
1128            code to be linked into the output object without having to modify
1129            source code. When -z wrap is specified, all undefined references to
1130            symbol are modified to reference __wrap_symbol, and all references
1131            to __real_symbol are modified to reference symbol. The user is
1132            expected to provide an object containing the __wrap_symbol
1133            function. This wrapper function can call __real_symbol in order to
1134            reference the actual function being wrapped.
1135 
1136            The following is an example of a wrapper for the malloc(3C)
1137            function:
1138 
1139              void *
1140              __wrap_malloc(size_t c)
1141              {
1142                      (void) printf("malloc called with %zu\n", c);
1143                      return (__real_malloc(c));
1144              }
1145 
1146            If you link other code with this file using -z wrap=malloc to
1147            compile all the objects, then all calls to malloc will call the
1148            function __wrap_malloc instead. The call to __real_malloc will call
1149            the real malloc function.
1150 
1151            The real and wrapped functions should be maintained in separate
1152            source files.  Otherwise, the compiler or assembler may resolve the
1153            call instead of leaving that operation for the link-editor to carry
1154            out, and prevent the wrap from occurring.
1155 
1156 
1157 ENVIRONMENT VARIABLES
1158        LD_ALTEXEC
1159 
1160            An alternative link-editor path name. ld executes, and passes
1161            control to this alternative link-editor. This environment variable
1162            provides a generic means of overriding the default link-editor that
1163            is called from the various compiler drivers. See the -z altexec64
1164            option.
1165 
1166 
1167        LD_LIBRARY_PATH
1168 
1169            A list of directories in which to search for the libraries
1170            specified using the -l option. Multiple directories are separated
1171            by a colon. In the most general case, this environment variable
1172            contains two directory lists separated by a semicolon:
1173 
1174              dirlist1;dirlist2
1175 
1176 
1177            If ld is called with any number of occurrences of -L, as in:
1178 
1179              ld ... -Lpath1 ... -Lpathn ...
1180 
1181 
1182            then the search path ordering is:
1183 
1184              dirlist1 path1 ... pathn dirlist2 LIBPATH
1185 
1186 
1187            When the list of directories does not contain a semicolon, the list
1188            is interpreted as dirlist2.
1189 
1190            The LD_LIBRARY_PATH environment variable also affects the runtime
1191            linkers search for dynamic dependencies.
1192 
1193            This environment variable can be specified with a _32 or _64
1194            suffix. This makes the environment variable specific, respectively,
1195            to 32-bit or 64-bit processes and overrides any non-suffixed
1196            version of the environment variable that is in effect.
1197 
1198 
1199        LD_NOEXEC_64
1200 
1201            Suppresses the automatic execution of the 64-bit link-editor. By
1202            default, the link-editor executes the 64-bit version when the ELF
1203            class of the first relocatable file identifies a 64-bit object. The
1204            64-bit image that a 32-bit link-editor can create, has some
1205            limitations. However, some link-edits might find the use of the
1206            32-bit link-editor faster.
1207 
1208 
1209        LD_OPTIONS
1210 
1211            A default set of options to ld. LD_OPTIONS is interpreted by ld
1212            just as though its value had been placed on the command line,
1213            immediately following the name used to invoke ld, as in:
1214 
1215              ld $LD_OPTIONS ... other-arguments ...
1216 
1217 
1218 
1219 
1220        LD_RUN_PATH
1221 
1222            An alternative mechanism for specifying a runpath to the link-
1223            editor. See the -R option. If both LD_RUN_PATH and the -R option
1224            are specified, -R supersedes.
1225 
1226 
1227        SGS_SUPPORT
1228 
1229            Provides a colon-separated list of shared objects that are loaded
1230            with the link-editor and given information regarding the linking
1231            process. This environment variable can be specified with a _32 or
1232            _64 suffix. This makes the environment variable specific,
1233            respectively, to the 32-bit or 64-bit class of ld and overrides any
1234            non-suffixed version of the environment variable that is in effect.
1235            See the -S option.
1236 
1237 
1238 
1239        Notice that environment variable-names that begin with the characters
1240        'LD_' are reserved for possible future enhancements to ld and
1241        ld.so.1(1).
1242 
1243 FILES
1244        libx.so
1245                       shared object libraries.
1246 
1247 
1248        libx.a
1249                       archive libraries.
1250 
1251 
1252        a.out
1253                       default output file.
1254 
1255 
1256        LIBPATH
1257                       For 32-bit libraries, the default search path is
1258                       /usr/ccs/lib, followed by /lib, and finally /usr/lib.
1259                       For 64-bit libraries, the default search path is
1260                       /lib/64, followed by /usr/lib/64.
1261 
1262 
1263        /usr/lib/ld
1264                       A directory containing several mapfiles that can be used
1265                       during link-editing. These mapfiles provide various
1266                       capabilities, such as defining memory layouts, aligning
1267                       bss, and defining non-executable stacks.
1268 
1269 
1270 ATTRIBUTES
1271        See attributes(5) for descriptions of the following attributes:
1272 
1273 
1274 
1275 
1276        +--------------------+-----------------+
1277        |  ATTRIBUTE TYPE    | ATTRIBUTE VALUE |
1278        +--------------------+-----------------+
1279        |Interface Stability | Committed       |
1280        +--------------------+-----------------+
1281 
1282 SEE ALSO
1283        as(1), crle(1), gprof(1), ld.so.1(1), ldd(1), mcs(1), pvs(1), exec(2),
1284        stat(2), dlopen(3C), dldump(3C), elf(3ELF), ar.h(3HEAD), a.out(4),
1285        attributes(5)
1286 
1287 
1288        Linker and Libraries Guide
1289 
1290 NOTES
1291        Default options applied by ld are maintained for historic reasons. In
1292        today's programming environment, where dynamic objects dominate,
1293        alternative defaults would often make more sense. However, historic
1294        defaults must be maintained to ensure compatibility with existing
1295        program development environments. Historic defaults are called out
1296        wherever possible in this manual. For a description of the current
1297        recommended options, see Appendix A, Link-Editor Quick Reference, in
1298        Linker and Libraries Guide.
1299 
1300 
1301        If the file being created by ld already exists, the file is unlinked
1302        after all input files have been processed. A new file with the
1303        specified name is then created. This allows ld to create a new version
1304        of the file, while simultaneously allowing existing processes that are
1305        accessing the old file contents to continue running. If the old file
1306        has no other links, the disk space of the removed file is freed when
1307        the last process referencing the file terminates.
1308 
1309 
1310        The behavior of ld when the file being created already exists was
1311        changed with SXCE build 43. In older versions, the existing file was
1312        rewritten in place, an approach with the potential to corrupt any
1313        running processes that is using the file. This change has an
1314        implication for output files that have multiple hard links in the file
1315        system. Previously, all links would remain intact, with all links
1316        accessing the new file contents. The new ld behavior breaks such links,
1317        with the result that only the specified output file name references the
1318        new file. All the other links continue to reference the old file. To
1319        ensure consistent behavior, applications that rely on multiple hard
1320        links to linker output files should explicitly remove and relink the
1321        other file names.
1322 
1323 
1324 
1325                                  June 6, 2016                            LD(1)