ld(CP) 6 January 1993 ld(CP) Name ld - invokes the link editor Syntax ld [options] filename [[options] filename] Description The ld command combines several object files into one, performs reloca- tion, resolves external symbols, and supports symbol table information for symbolic debugging. It creates an executable program by combining one or more object files and copying the executable result to the file a.out. The filename must name an object or library file. By convention these names have the .o (for object) or .a (for archive library) exten- sions. If more than one name is given, the names must be separated by one or more spaces. If any input file, filename, is not an object file, ld assumes it is either an archive library or a text file containing link editor directives. By default, the file a.out is executable if no errors occurred during the load. If errors occur while linking, ld displays an error message; the resulting a.out file is unexecutable. ld concatenates the contents of the given object files in the order given in the command line. Library files in the command line are examined only if there are unresolved external references encountered from previous object files. The library is searched iteratively to satisfy as many references as pos- sible and only those routines that define unresolved external references are concatenated. The library (archive) symbol table (see ar(FP)) is searched sequentially with as many passes as are necessary to resolve external references which can be satisfied by library members. Thus, the ordering of library members is functionally unimportant, unless there are multiple library members defining the same external symbol. The library may be either a relocatable archive library or a shared library. Object and library files are processed at the point they are encountered in the argument list, so the order of files in the command line is important. In general, all object files should be given before library files. ld sets the entry point of the resulting program to the beginning of the first routine. ld should be invoked using the cc(CP) command instead of directly. cc invokes ld as the last step of compilation, providing all the necessary C language support routines. Invoking ld directly is not recommended since failure to give command line arguments in the correct order can result in errors. Generating COFF vs. x.out binaries When ld is called, it scans all the object files that are to be linked. It determines whether an object file is in x.out or COFF format and exe- cutes the appropriate binaries in each case. Since this utility relies on the files in /lib/coff and /lib/xout), changing or moving any of those files results in an error. If all the object files are COFF objects, then the resulting binary will be in COFF format. If any of the object files to be linked are in x.out format, any COFF modules in the group will be converted to x.out and the resulting binary will be in x.out for- mat. Common options The following options are recognized by ld, and are common to producing both COFF and x.out binaries. Refer to the sections ``Linking COFF Binaries'' and ``Linking x.out Binaries'' for format-specific options. -m mapfile Produce a map of the input/output sections and store it in mapfile. If no mapfile is specified, the map is sent to standard output. -o name Sets the executable program filename to name instead of a.out. -r XENIX Version: Invokes the incremental linker, /lib/ldr, with the arguments passed to ld to produce a relocatable output file. -r AT&T Version: retains relocation entries in the output object file. Relocation entries must be saved if the output file is to become an input file in a subsequent ld run. The link editor will not complain about unresolved references, and the output file will not be execut- able. -s Strips line number entries and symbol table information from the out- put object file. -u symbol Designates the specified symbol as undefined. This is useful for loading entirely from a library, since initially the symbol table is empty and an unresolved reference is needed to force the loading of the first routine. The placement of this option on the ld line is significant; it must be placed before the library which defines the symbol. -V Outputs a message giving information about the version of ld being used. Linking COFF binaries The following options are used for linking COFF binaries: -a Create an absolute (executable) file. This is the default except when the -r option is also used. If -r is used, then -a allocates memory for common symbols. -e epsym Set the default entry point address for the output file to be that of the symbol epsym. -f fill Set the default fill pattern for ``holes'' within an output section as well as initialized .bss sections. The argument fill is a two- byte constant. -lx Search a library libx.a, where x is up to nine characters. A library is searched when its name is encountered, so the placement of a -l is significant. By default, libraries are located in LIBDIR or LLIBDIR. -L dir Change the algorithm of searching for libx.a to look in dir before looking in LIBDIR and LLIBDIR. This option is effective only if it precedes the -l option on the command line. -M Output a message for each multiply-defined external definition. -N Put the text section at the beginning of the text segment rather than after all header information, and put the data section immediately following text in the core image. -strict Suppress the generation of the symbols edata, etext and end which are aliases, used for compatibility with previous releases, to the sym- bols edata, etext and end. This prevents name space pollution when compiling in any of ANSI, POSIX, or XOPEN modes (see -ansi, - posix and -xpg3 options to the cc(CP)command. -t Turn off the warning about multiply-defined symbols that are not the same size. -VS num Use num as a decimal version stamp identifying the a.out file that is produced. The version stamp is stored in the optional header. -x Do not preserve local symbols in the output symbol table; enter external and static symbols only. This option saves some space in the output file. -Y[LU],dir Change the default directory used for finding libraries. If L is specified, the first default directory which ld searches, LIBDIR, is replaced by dir. If U is specified and ld has been built with a second default directory, LLIBDIR, then that directory is replaced by dir. If ld was built with only one default directory and U is speci- fied a warning is printed and the option is ignored. -z Do not bind anything to address zero. This option will allow runtime detection of null pointers. Linking x.out binaries The user must make sure that the most recent library versions have been processed with ranlib(XNX) before linking. Library files for x.out format binaries must be in ranlib(XNX) format, that is, the first member must be named __.SYMDEF, which is a dictionary for the library. ld compares the modification dates of the library and the __.SYMDEF entry, so if object files have been added to the library since __.SYMDEF was created, the link may result in an ``invalid object module'' that cannot run. The following options are recognized by ld for linking x.out binaries: -A hex-num Creates a standalone program whose expected load address (in hexade- cimal) is hex-num. This option sets the absolute flag in the header of the a.out file. Such program files can only be executed as stan- dalone programs. Options -A and -F are mutually exclusive. -B hex-num Sets the text selector bias to the specified hexadecimal number. -c num Alters the default target CPU in the x.out header. num can be 0, 1, 2, or 3 indicating 8086, 80186, 80286, or 80386 processors, respec- tively. The default value is 3. Note that this option only alters the default; if object modules containing code for a higher numbered processor are linked, then that will take precedence over the default. -C Causes the link editor to ignore the case of symbols. -D hex-num Sets the data selector bias to the specified hexadecimal number. -F hex-num Sets the size of the program stack to hex-num bytes where hex-num is a hexadecimal number. This option is ignored for 80386 programs, which have a variable-sized stack. By default 8086 programs have a variable stack located at the top of the first data segment, and 80286 programs have a fixed size 4096 byte stack. The -F option is incompatible with the -A option. -g Includes symbolic information for Codeview. -i Creates separate instruction and data spaces for small model pro- grams. When the output file is executed, the program text and data areas are allocated separate physical segments. The text portion will be read-only and shared by all users executing the file. -La Sets advisory file locking. Advisory locking is used on files with access modes that do not require mandatory locking. -Lm Sets mandatory file locking. Mandatory file locking is used on files that cannot be opened by more than one process at a time. -Mx Specifies the memory model. x can have the following values: s small m medium l large h huge e mixed -n num Truncates symbols to the length specified by num. -N hex-num Sets the pagesize to hex-num (which should be a multiple of 200 hex- adecimal or 512 decimal). The default is 400 hexadecimal (1024 decimal) for 80386 programs. 8086/80186/80286 programs do not nor- mally have page-aligned x.out files and the default for these is 0. -P Disables packing of segments -R Ensures that the relocation table is of non-zero size. Important for 8086 compatibility. -Rd hex-num Specify the data segment relocation offset (80386 only). -Rt hex-num Specify the text segment relocation offset (80386 only). -S num Sets the maximum number of segments to num. If no argument is given, the default is 128. Files /bin/ld LIBDIR/libx.a libraries LLIBDIR/libx.a libraries a.out output file LIBDIR usually /lib LLIBDIR usually /usr/lib Notes Through its options and input directives, the common link editor gives users great flexibility; however, those who use the input directives must assume some added responsibilities. Input directives and options should insure the following properties for programs: - C defines a zero pointer as null. A pointer to which zero has been assigned must not point to any object. To satisfy this, users must not place any object at virtual address zero in the program's address space. - When the link editor is called through cc(CP), a startup routine is linked with the user's program. This routine calls exit( ) (see exit(S)) after execution of the main program. If the user calls the link editor directly, then the user must insure that the program always calls exit( ) rather than falling through the end of the entry routine. The symbols etext, edata, and end (see end(S)) are reserved and are defined by the link editor. It is incorrect for a user program to rede- fine them. The following only applies to the linking of COFF binaries. The ``_'' forms are always defined, the non ``_'' forms are also defined in non-strict modes. If the link editor does not recognize an input file as an object file or an archive file, it will assume that it contains link editor directives and will attempt to parse it. This will occasionally produce an error message complaining about ``syntax errors''. Arithmetic expressions may only have one forward referenced symbol per expression. If you are using XENIX binaries, please refer to the ld(XNX) manual page for information on the appropriate usage with XENIX binaries. See also a.out(FP), ar(FP), as(CP), cc(CP), end(S), exit(S), masm(CP), mkshlib(CP), ranlib(XNX) Standards conformance ld is conformant with: AT&T SVID Issue 2; and X/Open Portability Guide, Issue 3, 1989.