NAME

ld − link editor

SYNOPSIS

ld [ option ] ... file ... 

DESCRIPTION

Ld combines several object programs into one, resolves external references, and searches libraries.  In the simplest case several object files are given, and ld combines them, producing an object module which can be either executed or become the input for a subsequent ld run.  (In the latter case, the −r option must be given to preserve the relocation bits.)  The output of ld is left in a.out.  This file is made executable only if no errors occurred during the load. 

The argument routines are concatenated in the order specified.  The entry point of the output is the beginning of the first routine (unless the −e option is specified). 

If any argument is a library, it is searched exactly once at the point it is encountered in the argument list.  Only those routines defining unresolved external references are loaded.  If a routine from a library references another routine in the library, and the library has not been processed by ranlib(1), the referenced routine must appear after the referencing routine in the library. Thus the order of programs within libraries may be important. The first member of a library should be a file named ‘__.SYMDEF’, which is understood to be a dictionary for the library as produced by ranlib(1); the dictionary is searched iteratively to satisfy as many references as possible.

The symbols ‘__etext’, ‘__edata’, ‘__end’, ‘__shedata’, ‘__shend’, and ‘__shstart’, (‘_etext’, ‘_edata’, ‘_end’, ‘_shedata’, ‘_shend’, and ‘_shstart’ in C) are reserved. If ‘__etext’, ‘__edata’, or ‘__end’ referred to, they are set to the first byte of the data segment, the first location above initialized data, and the first location above all data, respectively (see the following illustration). It is an error to define these symbols.

Ld understands several options.  Except for −l, they should appear before the file names. 

−A This option specifies incremental loading, i.e.  linking is to be done in a manner so that the resulting object may be read into an already executing program.  The next argument is the name of a file whose symbol table will be taken as a basis on which to define additional symbols.  Only newly linked material will be entered into the text and data portions of a.out, but the new symbol table will reflect every symbol defined before and after the incremental load.  This argument must appear before any other object file in the argument list.  The −T option may be used as well, and will be taken to mean that the newly linked segment will commence at the corresponding address (which must be a multiple of 1024).  The default value is the old value of _end rounded up to a multiple of 1024. 

−D Take the next argument as a hexadecimal number and pad the data segment with zero bytes to the indicated length. 

−d Force definition of common storage even if the −r flag is present. 

−e The following argument is taken to be the name of the entry point of the loaded program; The symbol _start is the default. 

−Fname[,size]
This option places the specified global variable (e.g., ‘_varname’) or named FORTRAN common block (e.g., ‘/COMNAME/’ or ‘_comname_’) in the shared data region. The location of this region is controlled with the -Z option.  The amount of memory allocated to the variable can be changed by specifying a size (hexadecimal, no leading ‘0x’).  The variable must be uninitialized.  The −F option may be repeated for multiple variables.  There is no control over the order in which variables are added to the region.  The value of ‘_end’ (which determines the intial program “break”) is unchanged.  This option can be used to move variables or common blocks to a location where they can be conveniently mapped into shared memory.  Refer to the Guide to Parallel Programming for more information. 

−fpa When interpreting an −lx option, search for a library named ‘libfpax.a’ before searching for ‘libx.a’. This option must be omitted on Balance systems. On Symmetry systems, libraries whose names begin with ‘libfpa’ contain code that use the Weitek 1167 floating point accelerator.

−lx This option is an abbreviation for the library name ‘/lib/libx.a’, where x is a string.  If that does not exist, ld tries ‘/usr/lib/libx.a’ and then ‘/usr/local/lib/libx.a’. If −fpa is specified, ld tries ‘/lib/libfpax.a’, ‘/usr/lib/libfpax.a’, and ‘/usr/local/lib/libfpax.a’ before trying any of the ‘libx.a’ possibilities. A library is searched when its name is encountered, so the placement of a −l is significant. 

−M produce a primitive load map, listing the names of the files that will be loaded. 

−h Arrange (by giving the output file a special "magic number", XMAGIC) that when the output file is executed, an inaccessible page of text will be inserted at zero.  This permits easy detection of programming errors involving null pointers. 

−k Generate a stand alone a.out file (SMAGIC).  The magic number is actually a branch to startup code which transfers control to the entry point specified in the a_entry field of the header.  This format is used for stand alone programs, and is not supported by the DYNIX kernel. 

−p This option is used with -k to produce compact stand alone programs.  The effect is to prevent aligning data and bss to page size. 

−o The name argument after −o is used as the name of the ld output file, instead of a.out. 

−r Generate relocation bits in the output file so that it can be the subject of another ld run.  This flag also prevents final definitions from being given to common symbols, and suppresses the ‘undefined symbol’ diagnostics. 

−S ‘Strip’ the output by removing all symbols except locals and globals. 

−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 strip(1).

−T The next argument is a hexadecimal number which sets the text segment origin.  The default origin is 0. 

−t ("trace") Print the name of each file as it is processed. 

−u Take the following argument as a symbol, and enter it as undefined in the symbol table.  This is useful for loading wholly from a library, since the symbol table is initially empty and an unresolved reference is needed to force the loading of the first routine. 

−X Save local symbols except for those whose names begin with ‘L’.  This option is used by cc(1) to discard internally-generated labels while retaining symbols local to routines.

−x Do not preserve local (non-.globl) symbols in the output symbol table; only enter external symbols.  This option saves some space in the output file. 

−ysym
Indicate each file in which 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 sym with an ‘_’, as external C, FORTRAN, and Pascal variables begin with underscores.) 

−Z[O]n
The -Z option specifies the number of bytes to leave between the end of the bss memory segment and the beginning of the shared data segment.  The -ZO option specifies the base address of the shared data segment.  For either option, n is a hexadecimal number that is always rounded up so that the shared data segment begins on a page boundary.  If both options are omitted, the loader automatically reserves 64 Kbytes between the end of bss and the beginning of the shared data segment, then starts the shared segment at the next page boundary.  If the number specified with -ZO would result in the shared data memory segment overlaying part of the bss segment, an error message is printed and the load step fails. 

−z Arrange for the process to be loaded on demand from the resulting executable file.  This is the default.  The text and data segments are each a multiple of 2048 bytes.  The text segment is located immediately after the header in the file to save file space, but when the program is running, the actual text segment begins at 2048.  With this format the first few BSS segment symbols may actually appear (from the output of size(1)) to live in the data segment; this avoids wasting the space resulting from data segment size roundup.

The −m and −n options, supported in UNIX System V, yield warning messages but are otherwise ignored. 

FILES

/lib/lib∗.alibraries
/usr/lib/lib∗.amore libraries
/usr/local/lib/lib∗.astill more libraries
libfpa∗.alibraries with support for Weitek FPA
a.outoutput file

SEE ALSO

as(1), ar(1), cc(1), ranlib(1), a.out(5)
Guide to Parallel Programming

BUGS

There is no way to force data to be page aligned. 

DYNIX