.\" This source code is a product of Sun Microsystems, Inc. and is provided .\" for unrestricted use provided that this legend is included on all tape .\" media and as a part of the software program in whole or part. Users .\" may copy or modify this source code without charge, but are not authorized .\" to license or distribute it to anyone else except as part of a product or .\" program developed by the user. .\" .\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC. .\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY .\" OF SUCH SOURCE CODE FOR ANY PURPOSE. IT IS PROVIDED "AS IS" WITHOUT .\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND. SUN MICROSYSTEMS, INC. DISCLAIMS .\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN .\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT, .\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING .\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY. .\" .\" This source code is provided with no support and without any obligation on .\" the part of Sun Microsystems, Inc. to assist in its use, correction, .\" modification or enhancement. .\" .\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE .\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS .\" SOURCE CODE OR ANY PART THEREOF. .\" .\" Sun Microsystems, Inc. .\" 2550 Garcia Avenue .\" Mountain View, California 94043 .\" .\" Copyright (c) 1991 Sun Microsystems, Inc. .\" .\" @(#)ld.1 1.48 90/02/02 SMI; .TH LD 1 "21 January 1990" .SH NAME ld, ld.so \- link editor, dynamic link editor .SH SYNOPSIS .B ld [ .BI \-align " datum" ] [ .BI \-assert " assertion-keyword" ] .if n .ti +0.5i [ .BI \-A " name" ] [ .BI \-B "binding-keyword" ] [ .B \-d ] .if t .ti +0.5i [ .B \-dc ] .if n .ti +0.5i [ .B \-dp ] [ .BI \-D " hex" ] [ .BI \-e " entry" ] [ .BI \-l x ] [ .BI \-L dir ] .if n .ti +0.5i [ .B \-M ] [ .B \-n ] [ .B \-N ] [ .BI \-o " name" ] [ .B \-p ] .if t .ti +0.5i [ .B \-r ] [ .B \-s ] [ .B \-S ] .if n .ti +0.5i [ .B \-t ] [ .BR \-T \|[\| text \|] .I hex ] [ .BI \-Tdata " hex" ] [ .BI \-u " name" ] .if n .ti +0.5i [ .B \-x ] [ .B \-X ] [ .BI \-y sym ] .if t .ti +0.5i [ .B \-z ] .I filename \&.\|.\|. .SH DESCRIPTION .IX "ld command" "" "\fLld\fP \(em link editor" .IX "programming tools" "ld command" "" "\fLld\fP \(em link editor" .IX "link editor" "" "link editor \(em \fLld\fP" .LP .B ld combines object programs to create an .I executable file or another object program suitable for further .B ld processing (with the .B \-r option). The object modules on which .B ld operates are specified on the command line, and can be: .RS .TP 3 \(bu simple object files, which typically end in the .BR .o suffix, and are referred to as \*(lqdot-oh\*(rq files .TP 3 \(bu .BR ar (1V) library archives .RB ( .a ), or \*(lqlibraries\*(rq .TP 3 \(bu dynamically-bound, sharable object files .RB ( .so ), are also referred to as \*(lqshared libraries,\*(rq which are created from previous .B ld executions. .RE .LP Unless an output file is specified, .B ld produces a file named .BR a.out . This file contains the object files given as input, appropriately combined to form an executable file. .SH OPTIONS When linking debugging or profiling objects, include the .B \-g or .B \-pg option (see .BR cc (1V)), as appropriate, in the .B ld command. .LP Options should appear before filenames, except for abbreviated library names specified with .B \-l options, and some binding control options specified by .BR \-B (which can appear anywhere in the line). .TP .BI \-align " datum" Force the global uninitialized data symbol .I datum (usually a .SM FORTRAN common block) to be page-aligned. Increase its size to a whole number of pages, and place its first byte at the start of a page. .TP .BI \-assert " assertion-keyword" Check an assertion about the link editing being performed. The assertion desired is specified by the .I assertion-keyword string. .B ld is silent if the assertion holds, else it yields a diagnostic and aborts. Valid .IR assertion-keyword 's and their interpretations are: .RS .RS .TP 15 .B definitions If the resulting program were run now, there would be no run-time undefined symbol diagnostics. This assertion is set by default. .TP .B nodefinitions Permit the successful linking of a program with unresolved references. .TP .B nosymbolic There are no symbolic relocation items remaining to be resolved. .TP .B pure-text The resulting load has no relocation items remaining in its text. .RE .RE .TP .BI \-A " name" Incremental loading: linking is to be done in a manner so that the resulting object may be read into an already executing program. .I name is the name of a file whose symbol table is taken as a basis on which to define additional symbols. Only newly linked material is entered into the text and data portions of .BR a.out , but the new symbol table will reflect all symbols defined before and after the incremental load. This argument must appear before any other object file in the argument list. One or both of the .B \-T options may be used as well, and will be taken to mean that the newly linked segment will commence at the corresponding addresses (which must be a multiple of the page size). The default value is the old value of .BR _end . .br .ne 10 .TP .BI \-B binding-keyword Specify allowed binding times for the items which follow. Allowed values of .I binding-keyword are: .RS .TP 15 .B dynamic Allow dynamic binding: do not resolve symbolic references, allow creation of run-time symbol and relocation environment. .B -Bdynamic is the default. When .B \-Bdynamic is in effect, all sharable objects encountered until a succeeding .B \-Bstatic may be added dynamically to the object being linked. Non-sharable objects are bound statically. .TP .B nosymbolic Do not perform symbolic relocation, even if other options imply it. .TP .B static Bind statically. Opposite of .BR \-Bdynamic . Implied when either .B \-n or .B \-N is specified. Influences handling of all objects following its specification on a command line until the next .BR \-Bdynamic . .TP .B symbolic Force symbolic relocation. Normally implied if an entry point has been specified with .BR \-e , or if dynamic loading is in effect. .RE .TP .B \-d Force common storage for uninitialized variables and other common symbols to be allocated in the current .B ld run, even when the .B \-r flag is present (which would otherwise postpone this binding until the final linking phase). .TP .B \-dc Do .BR \-d , but also copy initialized data referenced by this program from shared objects. .TP .B \-dp Force an alias definition of undefined procedure entry points. Used with dynamic binding to improve sharing and the locality of run-time relocations. .TP .BI \-D " hex" Pad the data segment with zero-valued bytes to make it .I hex bytes long. .TP .BI \-e " entry" Define the entry point: the .I entry argument is made the name of the entry point of the loaded program. Implies .BR \-Bsymbolic . .TP .BI \-l x\|\fR[ . v\|\fR] This option is an abbreviation for the library name .BI lib x .a\fR, where .I x is a string. .B ld searches for libraries first in any directories specified with .B \-L options, then in the standard directories .BR /lib , .BR /usr/lib , and .BR /usr/local/lib . A library is searched when its name is encountered, so the placement of a .B \-l is significant. If a dynamically loadable object is found, and .B \-Bdynamic is in effect at that point on the command line, then .B ld prepares to access the object for relocation at run-time. In such a case, the optional .BI . v suffix can be used to indicate a specific library version. .br .ne 5 .TP .BI \-L dir Add .I dir to the list of directories in which to search for libraries. Directories specified with .B \-L are searched before the standard directories, .BR /lib , .BR /usr/lib , and .BR /usr/local/lib . When building a program in which one or more objects are loaded when .B -Bdynamic is in effect, those directories specified by .B \-L options will be \*(lqremembered\*(rq for use at execution time. This permits the construction of software that uses shared objects as libraries not residing in the standard locations and avoids requiring the specification of the .SB LD_LIBRARY_PATH environment variable in order to execute such software. Note that such directories are retained in .I exactly the form specified in the option, which means that relative directory specifications (i.e., not beginning with \*(lq/\*(rq) will be evaluated relative to the current directory when the program is .IR run , not just during the operation of .BR ld . .TP .B \-M Produce a primitive load map, listing the names of the files which will be loaded. .TP .B \-n Arrange (by giving the output file a 0410 \*(lqmagic number\*(rq) that when the output file is executed, the text portion will be read-only with the data areas placed at the beginning of the next address boundary following the end of the text. Implies .BR \-Bstatic . .TP .B \-N Do not make the text portion read-only. (Use \*(lqmagic number\*(rq 0407.) Implies .BR \-Bstatic . .TP .BI \-o " name" .I name is made the name of the .B ld output file, instead of .BR a.out . .br .ne 3 .TP .B \-p Arrange for the data segment to begin on a page boundary, even if the text is not shared (with the .B \-N option). .TP .B \-r Generate relocation bits in the output file so that it can be the subject of another .B ld run. This flag also prevents final definitions from being given to common symbols, and suppresses the \*(lqundefined symbol\*(rq diagnostics. .TP .B \-s Strip the output, that is, remove the symbol table and relocation bits to save space (but impair the usefulness of the debuggers). This information can also be removed by .BR strip (1). .TP .B \-S Strip the output by removing all symbols except locals and globals. .TP .B \-t Trace: display the name of each file as it is processed. .br .ne 5 .TP .BR \-T \|[\| text \|]\| \fIhex\fR Start the text segment at location .IR hex . Specifying .B \-T is the same as using the .B \-Ttext option. .TP .BI \-Tdata " hex" Start the data segment at location .IR hex . This option is only of use to programmers wishing to write code for .SM PROM\s0s, since the resulting code cannot be executed by the system. .TP .BI \-u " name" Enter .I name as an undefined symbol. This is useful for loading wholly from a library, since initially the symbol table is empty and an unresolved reference is needed to force the loading of the first routine. .TP .B \-x Preserve only global (non-\fB.globl\fP) symbols in the output symbol table; only enter external symbols. This option saves some space in the output file. .TP .B \-X Record local symbols, except for those whose names begin with .BR L . This option is used by .B cc to discard internally generated labels while retaining symbols local to routines. .TP .BI \-y sym Display each file in which .I sym appears, its type and whether the file defines or references it. Many such options may be given to trace many symbols. It is usually necessary to begin .I sym with an .RB ` _ ', as external C, .SM FORTRAN and Pascal variables begin with underscores. .TP .B \-z Arrange for the process demand paged from the resulting executable file (0413 \*(lqmagic number\*(rq). This is the default. Results in a (32-byte) header on the output file followed by text and data segments, each of which has a multiple of page-size bytes (being padded out with null characters in the file if necessary). With this format the first few .SM BSS segment symbols may actually end up in the data segment; this is to avoid wasting the space resulting from rounding the data segment size. Implies .BR \-Bdynamic . .SH USAGE .SS Command Line Processing .LP In general, options should appear ahead of the list of files to process. Unless otherwise specified, the effect of an option covers all of .B ld operations, independent of that option's placement on the command line. Exceptions to this rule include some of the binding control options specified by .RB ` \-B ' and the abbreviated library-names specified by .RB ` \-l '. These may appear anywhere, and their influence is dependent upon their location. Some options may be obtained from environment variables, such options are interpreted before any on the command line (see .SM ENVIRONMENT\s0, below). .SS Object File Processing .LP The files specified on the command line are processed in the order listed. Information is extracted from each file, and concatenated to form the output. The specific processing performed on a given file depends upon whether it is a simple object file, a library archive, or a shared library. .LP Simple object .RB ( .o ) files are concatenated to the output as they are encountered. .LP Library archive .RB ( .a ) files are searched exactly once each, as each is encountered; only those archive entries matching an unresolved external reference are extracted and concatenated to the output. If a member of an archive references a symbol defined by another member of that same archive, the member making the reference must appear before the member containing the definition. .LP On Sun386i, a library contains a dictionary of symbols, On other Sun systems, processing library archives through .BR ranlib (1) provides this dictionary. In addition, you can use .BR lorder (1), in combination with .BR tsort (1) to place library members in calling order (see .BR lorder (1) for details), or both (for fastest symbol lookup). The first member of an archived processed by .B ranlib has the reserved name of .BR _\^_.\s-1SYMDEF\s0 , which .B ld takes to be the dictionary of all symbols defined by members of the archive. .LP Sharable objects .RB ( .so ) are scanned for symbol definitions and references, but are not normally included in the output from .BR ld , except in cases where a shared library exports initialized data structures and the .B \-dc option is in effect. However, the occurrence of each sharable object file in the .BR ld command line is noted in the resulting executable file; this notation is utilized by an execution-time variant of .BR ld , .BR ld.so , for .I deferred and .I dynamic loading and binding during execution. See .BR "Execution-Time Loading" , below, for details. .LP The .B \-l option specifies a short name for an object file or archive used as a library. The full name of the object file is derived by adding the prefix .B lib and a suffix of either .B .a or .BR .so [ .\c .IR v ] to indicate an .BR ar (1V) archive or a shared library, respectively. The specific suffix used is determined through rules discussed in .BR "Binding and Relocation Semantics" , below. .LP .B ld searches for the desired object file through a list of directories specified by .B \-L options, the environment variable .BR \s-1LD_LIBRARY_PATH\s0 , and finally, the built-in list of standard library directories: .BR /lib , .BR /usr/lib , and .BR /usr/local/lib . . .SS Binding and Relocation Semantics .LP The manner in which .B ld processes a given object file is dependent in part upon the \*(lqbinding mode\*(rq in which it is operating at the time the file is encountered. This binding mode is specified by the .B \-B flag, which takes the keyword arguments: .RS .TP 10 .B dynamic Allow dynamic binding, do not resolve symbolic references, and allow creation of execution-time symbol and relocation information. This is the default setting. .TP .B static Force static binding, implied by options that generate non-sharable executable formats. .RE .LP .B \-Bdynamic and .B \-Bstatic may be specified several times, and may be used to toggle each other on and off. Like .BR \-l , the influence of each depends upon its location within the command line. When .B \-Bdynamic is in effect, .B \-l searches may be satisfied by the first occurrence of either form of library .RB ( .so or .BR .a ), but if both are encountered, the .B .so form is preferred. When .B \-Bstatic is in effect, .B ld refuses to use any .B .so libraries it encounters; it continue searching for the .B .a form. Furthermore, an explicit request to load a .B .so file is treated as an error. .LP After .B ld has processed all input files and command line options, the form of the output it produces is based on the information provided in both. .B ld first tries to reduce all symbolic references to relative numerical offsets within the executable it is building. To perform this \*(lqsymbolic reduction,\*(rq .B ld must be able to determine that: .RS .TP 3 \(bu all information relating to the program has been provided, in particular, no .B .so is to be added at execution time; and/or .TP \(bu the program has an entry point, and symbolic reduction can be performed for all symbols having definitions existing in the material provided. .RE .LP It should be noted that uninitialized \*(lqcommon\*(rq areas (for example, uninitialized C globals) are allocated by the link editor .I after it has collected all references. In particular, this allocation can not occur in a program that still requires the addition of information contained in a .B \&.so file, as the missing information may affect the allocation process. Initialized \*(lqcommons\*(rq however, are allocated within the executable in which their definition appears. .LP After .B ld has performed all the symbolic reductions it can, it attempts to transform all relative references to absolute addresses. .B ld is able to perform this \*(lqrelative reduction\*(rq only if it has been provided .I some absolute address, either implicitly through the specification of an entry point, or explicitly through .B ld command-line options. If, after performing all the reductions it can, there are no further relocations or definitions to perform, then .B ld has produced a completely linked executable. .SS Execution-Time Loading .LP In the event that one or more reductions can not be completed, the executable will require further link editing at execution time in order to be usable. Such executables contain an data structure identified with the symbol .BR _\^_\s-1DYNAMIC\s0 . An incompletely linked \*(lqmain\*(rq program should be linked with a \*(lqbootstrap\*(rq routine that invokes .BR ld.so , which uses the information contained in the main program's .SB _\^_DYNAMIC to assemble the rest of the executables constituting the entire program. A standard Sun compilation driver (such as .BR cc (1V)) automatically includes such a module in each \*(lqmain\*(rq executable. .LP When .B ld.so is given control on program startup, it finds all .B .so files specified when the program was constructed (and all .BR .so 's on which they depend), and loads them into the address space. The algorithm by which such files are found mimics that used when .B ld is run, and like .BR ld , can be influenced by the setting of .SB LD_LIBRARY_PATH and any .B \-L options specified to .B ld when the program was built. .B ld.so then completes all remaining relocations, with the exception of procedure call relocations; failure to resolve a given non-procedural relocation results in termination of the program with an appropriate diagnostic. .LP Procedure relocations are resolved when the referencing instruction is first executed. It should be noted that it is possible for \*(lqundefined symbol\*(rq diagnostics to be produced during program execution if a given target is not defined when referenced. .LP Although it is possible for binding errors to occur at execution-time, such an occurrence generally indicates something wrong in the maintenance of shared objects. .BR ld 's .B "\-assert nodefinitions" function (on by default) checks at .BR ld -time whether or not an execution-time binding error would occur. .SS Version Handling for Shared Libraries .LP To allow the independent evolution of .BR .so 's used as libraries and the programs which use them, .BR ld 's handling of .B .so files found through .B \-l options involves the retention and management of version control information. The .B .so files used as such \*(lqshared libraries\*(rq are post-fixed with a Dewey-decimal format string describing the version of the \*(lqlibrary\*(rq contained in the file. .LP The first decimal component is called the library's \*(lqmajor version\*(rq number, and the second component its \*(lqminor version\*(rq number. When .B ld records a .B .so used as a library, it also records these two numbers in the database used by .B ld.so at execution time. In turn, .B ld.so uses these numbers to decide which of multiple versions of a given library is \*(lqbest\*(rq or whether .I any of the available versions are acceptable. The rules are: .RS .TP 3 \(bu Major Versions Identical: the major version used at execution time must exactly match the version found at .BR ld -time. Failure to find an instance of the library with a matching major version causes a diagnostic to be issued and the program's execution to be terminated. .TP \(bu Highest Minor Version: in the presence of multiple instances of libraries that match the desired major version, .B ld.so uses the highest minor version it finds. However, if the highest minor version found at execution time is less than the version found at .BR ld -time, a warning diagnostic is issued; program execution continues. .RE .LP The semantics of version numbers are such that major version numbers should be changed whenever interfaces are changed. Minor versions should be changed to reflect compatible updates to libraries, and programs will silently favor the highest compatible version they can obtain. .SS Special Symbols .LP A number of symbols have special meanings to .B ld and programs should not define these symbols. The symbols described below are those actually seen by .BR ld . Note: C and several other languages prepend symbols they use with .RB ` _ '. .TP .BR _etext The first location after the text of the program. .TP .BR _edata The first location after initialized data. .TP .B _end The first location after all data. .br .ne 5 .TP .SB _\^_DYNAMIC Identifies an .BR ld -produced data structure. It is defined with a non-zero value in executables which require execution-time link editing. By convention, if defined, it is the first symbol in the symbol table associated with an .B a.out file. .br .ne 8 .TP .SB _\^_GLOBAL_OFFSET_TABLE_ A position-independent reference to an .BR ld -constructed table of addresses. This table is constructed from \*(lqposition-independent\*(rq data references occurring in objects that have been assembled with the assembler's .B \-k flag (invoked on behalf of C compilations performed with the .B \-pic flag). A related table (for which no symbol is currently defined) contains a series of transfer instructions and is created from \*(lqposition-independent\*(rq procedure calls or, if .B \-dp is specified to .BR ld , a list of undefined symbols. .LP Symbols in object files beginning with the letter .B L are taken to be local symbols and unless otherwise specified are purged from .B ld output files. .br .ne 6 .SH ENVIRONMENT .TP .SB LD_LIBRARY_PATH A colon-separated list of directories in which to search for libraries specified with the .B \-l option. Similar to the .SB PATH environment variable. .SB LD_LIBRARY_PATH also affects library searching during execution-time loading, causing the search to use first those directories found in the environment variable, then any directories specified by .B \-L options, and finally the standard directories .B /usr/lib and .BR /usr/local/lib . .SB NOTE: when running a set-user- or set-group-ID program, .BR ld.so will only search for libraries in directories it \*(lqtrusts\*(rq, which are .BR /usr/lib , .BR /usr/5lib , .BR /usr/local/lib , and any directories specified within the executable as a result of .B \-L options given when the executable was constructed. .br .ne 5 .TP .SB LD_OPTIONS A default set of options to .BR ld . .SB LD_OPTIONS is interpreted by .B ld just as though its value had been placed on the command line, immediately following the name used to invoke .BR ld , as in: .IP .ft B example% ld $LD_OPTIONS \fR.\|.\|. \fIother-arguments \fR.\|.\|. .LP Note: Environment variable-names beginning with the characters .RB ` LD_ ' are reserved for possible future enhancements to .BR ld . .SH FILES .PD 0 .TP 20 .B /usr/lib/lib*.a libraries .TP .B lib*.so.v shared libraries .TP .B lib*.sa.v exported, initialized shared library data .TP .B /usr/lib/ld.so execution-time .B ld .TP .B /usr/lib/*crt*.o default program bootstraps .TP .B a.out output file .TP .B /usr/local/lib .PD .SH SEE ALSO .BR ar (1V), .BR as (1), .BR cc (1V), .BR lorder (1), .BR ranlib (1), .BR strip (1), .BR tsort (1), .BR ldconfig (8) .br .ne 8 .SH BUGS .LP Options are being overloaded and are an inappropriate vehicle for describing to .B ld the wide variety of things it can do. There needs to be a link-editing language which can be used in the more complex situations. .LP The .B \-r option does not properly handle programs assembled with the .B \-k (position-independent) flag, invoked from .B cc with .B \-pic or .BR \-\s-1PIC\s0 .