NAME

ld − link editor for common object files

SYNOPSIS

ld [options] filename

DESCRIPTION

The ld command combines several object files into one, performs relocation, resolves external symbols, and supports symbol table information for symbolic debugging.  In the simplest case, the names of several object programs are given, and ld combines them, producing an object module that can either be executed or used as input for a subsequent ld run.  The output of ld is left in a.out.  By default this file is executable if no errors occurred during the load.  If any input file, file-name, is not an object file, ld assumes it is either an archive library or a text file containing link editor directives.  (See the CX/UX Support Tools Guide for a discussion of input directives.) 

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 an unresolved external reference are loaded.  The library (archive) symbol table (see ar(4)) 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 unimportant. 

The following options are recognized by ld. 

−e epsym
Set the default entry point address for the output file to be that of the symbol epsym. option to be set.

−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 eight characters.  A library is searched when its name is encountered, so the placement of a −l is significant.  By default, libraries are located in /lib and /usr/lib/. 

−m Produce a map or listing of the input/output sections on the standard output. 

−o outfile
Produce an output object file by the name outfile. The name of the default object file is a.out. 

−r Retain 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. 

−s Strip line number entries and symbol table information from the output object file.  Relocation entries will not be saved when this option is used. 

−t Turn off the warning about multiply-defined symbols that are not the same size. 

−u symname
Enter symname as an undefined symbol in the symbol table.  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. 

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

−x1 Produce a pseudo-cross reference listing on the standard output.  Each file and archive is examined, and all external symbols are listed along with the names of the object files which define and/or reference the symbols.  An executable output file is not produced. 

−QBSS
Forces undefined externals with a positive size into the .bss section, even when the −r option is used. 

-Qfile_buffer_limit=number
Sets file_buffer_limit to the amount of buffer space ld will use while linking. Allowing more buffer space will speed linking of large programs (if you have enough memory on the system to avoid thrashing) since the link editor won’t have to read files more than once.   If not set, it defaults to the value in the FILE_BUFFER_LIMIT environment variable.  If that environment variable is not set, it defaults to 2097152 (2 Megabytes). 

−Qnotdesc
Suppresses the production of tdesc information on Series 4000 and Series 5000 systems.

−QOCS
Produces OCS compliant tdesc information on Series 4000 and Series 5000 systems.  Without this option, additional support information is produced.

−Qsave_memory
The link editor will normally allocate enough memory to hold the largest relocation, line number, or symbol table among the object files.  This option directs the link editor not to allocate this memory, but at the expense of increased link time.

−Qstandard_fortran_common
By default, the link editor checks for and properly handles certain nonstandard Fortran common block constructs, but at the expense of increased link time.  Use of this option reduces link time, but it presumes that all Fortran common blocks are strictly standard conforming.  Unexpected results could be obtained if this option is used and nonstandard Fortran common block extensions are present.

−Qwarn_mult_init
Warns if a Fortran common block is multiply initialized.  If a particular byte in the common block is multiply initialized, the last initialized value of the byte is selected.  Without this option, no warning is produced, and all initialization values of the byte are OR’ed together.

−ocs Same as −QOCS.

−L dir
Change the algorithm of searching for libx.a to look in dir before looking in /lib and /usr/lib.  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.  However, if the objects being loaded include debugging information, extraneous output is produced (see the −g option in cc(1)).  Also, output a message for each external entity with different declared sizes and which overlaps another entity. 

−N Put the data section immediately following the text in the output file. 

−O args
Invoke the analyze88(1) tool to perform a static performance analysis, to produce an optimized program, or to produce a profiling program.  If args begins with a hyphen, the system analyze88(1) tool is used, and args is passed to it.  If args does not begin with a hyphen, then the first field is considered to be the name of an alternative analyze88(1) tool, and the remainder of args is passed to it. 

−V Output a message giving information about the version of ld being used. 

−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 look in alternate search paths for libraries.  An error message will be generated if the libraries cannot be located in the specified search path(s). 

FILES

/lib/libx.a libraries

/usr/lib/libx.a libraries

a.out output file

SEE ALSO

as(1), cc(1). 
exit(2), a.out(4), ar(4) in the CX/UX Programmer’s Reference Manual. 

CAVEATS

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 ensure 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 data space. 

−When the link editor is called through cc(1), a startup routine is linked with the user’s program. This routine calls exit( ) (see exit(2)) after execution of the main program. If the user the program always calls exit( ) rather than falling through the calls the link editor directly, then the user must ensure that end of the entry routine. 

On Series 4000 and Series 5000 systems, object files are identified as to whether they exploit features unique to either platform.  The link editor examines the identifiers of all object files which contribute to the program, warning if there is any potential conflict arising from the mixing of features. 

CX/UX User’s Reference Manual