NAME

ld − link editor

SYNOPSIS

ld [ −dmnqrstvxzNQZ ] [ −e epsym ] [ −h symbol ] ... [ −o outfile ] [ −u symbol ] ... [ −A name ] [ −L dir ] ... [ −R offset ] [ −V num ] [ −X num ] [ −lx | file ] ... 

DESCRIPTION

Ld takes one or more object files as input and combines them to produce a single (usually executable) file.  In doing so it resolves references to external symbols, assigns final addresses to procedures and variables, revises code and data to reflect new addresses (a process called "relocation"), and updates symbolic debug information (when present in the file).  By default, ld processes one or more object files to produce an executable file that can be run by the HP-UX loader exec(2).  Alternatively, the linker can generate a relocatable file, which is suitable for further processing by ld (see −r below).  Ld will not generate an output file if any errors occur during its operation. 

Ld recognizes two kinds of input files: object files created by the compilers or assembler (also known as ‘.o’ files) and archives of such object files (called libraries).  A library contains an index of all the externally-visible symbols from its component object files.  (The archiver command ar(1) creates and maintains this index.)  Ld uses this table to resolve references to external symbols. 

Ld processes files in the same order as they appear on the command line.  It includes code and data from a library element if and only if that object module provides a definition for a currently unresolved reference within the user’s program.  It is common practice to list libraries following the names of all simple object files on the command line. 

Options

Ld recognizes the following options:

−d Forces definition of “common” storage, i.e., assign addresses and sizes, even for −r output. 

−e epsym Set the default entry point address for the output file to be that of the symbol epsym. (This option only applies to executable files.)

−h symbol Prior to writing the symbol table to the output file, mark this name as “local” so that it is no longer externally visible.  This ensures that this particular entry will not clash with a definition in another file during future processing by ld.  (Of course, this only makes sense with the −r option.)  More than one symbol can be specified, but −h must precede each one. 

−lx Search a library libx.a, where x is one or more characters.  Because a library is searched when its name is encountered, the placement of a −l is significant.  By default, libraries are located in /lib and /usr/lib.  If the environment variable LPATH is present in the user’s environment, it should contain a colon-separated list of directories to search.  These directories are searched instead of the default directories, but −L options can still be used. 

−m Produce a load map on the standard output. 

−n Generate an (executable) output file with code to be shared by all users.  Compare with −N. 

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

−q Generate an (executable) output file that is demand-loadable.  Compare with −Q. 

−r Retain relocation information in the output file for subsequent re-linking.  Ld will not report undefined symbols. 

−s Strip the output file of all symbol table, relocation, and debug support information.  This might impair or prevent the use of a symbolic debugger on the resulting program.  This option is incompatible with −r.  (The strip(1) command also removes this information.) 

−t Print a trace (to standard output) of each input file as ld processes it. 

−u symbol Enter symbol as an undefined symbol in the symbol table.  The resulting unresolved reference is useful for linking a program solely from object files in a library.  More than one symbol can be specified, but each must be preceded by −u. 

−v Display verbose messages during linking.  This option might have little or no effect, but it is useful for obtaining more information about an error that occurs while linking. 

−x Partially strip the output file; that is, leave out local symbols.  The intention is to reduce the size of the output file without impairing the effectiveness of object file utilities.  Note:  use of −x might affect the use of a debugger. 

−z Arrange for run-time dereferencing of null pointers to produce a SIGSEGV signal.  (This is the complement of the −Z option.) 

-A name This option specifies incremental loading, that is, linking to enable the resulting object to be read into an already executing program.  The argument name specifies a file whose symbol table provides the basis for defining additional symbols.  Only newly linked material is entered into the text and data portions of a.out, but the new symbol table reflects all symbols defined before and  after  the incremental  load.  Also, the −R option can be used in conjunction with −A, and allows the newly linked segment to commence at the corresponding address.  The default starting address is the old value of end (_end in some implementations). 

-L dir Change the algorithm of searching for libx.a to look in dir before looking in the default places.  More than one directory can be specified, but each must be preceded by −L.  The −L option is effective only if it precedes the −l option on the command line. 

−N Generate an (executable) output file that cannot be shared.  This option also causes the data to be placed immediately following the text, and the text to be made writable. 

−Q Generate an (executable) output file that is not demand-loadable.  (This is the complement of the −q option.) 

−R offset Set the origin (in hexadecimal) for the text (i.e. code) segment. 

−V num Use num as a decimal version stamp identifying the a.out file that is produced.  (This is not the same as the version information reported by the SCCS what(1) command.) 

−X num Define the initial size for the linker’s global symbol table.  Thus you can reduce link time for very large programs, i.e., those with very many external symbols. 

−Z Arrange for run-time dereferencing of null pointers to be permitted.  (See in cc(1) the discussions of −Z and pointers.) (This is the complement of the −z option.) 

Defaults

Unless otherwise directed, ld names its output a.out.  The −o option overrides this.  Executable output files can be shared. 

DIAGNOSTICS

Ld returns a zero when the link is successful.  A non-zero return code indicates that an error occurred. 

EXAMPLES

The following command line links part of a C program for later processing by ld.  It also specifies a version number of 2 for the output file.  (Note the ‘.o’ suffix for the output object file.  This is an HP-UX convention for indicating a linkable object file.) 
 
ld -V 2 -r file1.o file2.o -o prog.o
 
The next example links a simple FORTRAN program for use with the cdb(1) symbolic debugger.  The output file name will be a.out since there is no −o option in the command line.  (Note:  the particular options shown here are for a Series 300.) 
 
ld -e start /lib/frt0.o ftn.o -lI77 -lF77 -lm -lc /usr/lib/end.o
 
Finally, this command will link a Pascal program on a Series 300.
 
ld -e start /lib/prt0.o main.o -lpccat -lpc -lm -lc

WARNINGS

Ld recognizes several names as having special meanings.  The names end, edata, and etext (preceded by an underscore in some implementations) are reserved.  (See end(3C) for details.)  Users must not write alternative (externally-visible) definitions for these names. 

Through its options, the link editor gives users great flexibility; however, those who invoke the linker directly must assume some added responsibilities.  Input options should ensure the following properties for programs:

•When the link editor is called through cc(1), a start-up routine is linked with the user’s program.  This routine calls exit(2) after execution of the main program.  If users call ld directly, they must ensure that the program always calls exit() rather than falling through the end of the entry routine.

•When linking for use with the symbolic debugger cdb, the user must ensure that the program contains a routine called main.  Also, the user must link in the file /usr/lib/end.o as the last file named on the command line. 

There is no guarantee that the linker will pick up files from libraries and include them in the final program in the same relative order that they occur within the library. 

DEPENDENCIES

Series 300
The default entry point is taken to be text location 0x0 (which is also the default origin of the program text). This corresponds to the first procedure in the first input file that the linker reads. Use the −e option to select a different entry point. 

The version number specified with the −V option must be in the range 0 to 32767. 

The Series 300 linker does not support the following options: −m, −v, −z, and −Z. 

Series 800
The LPATH environment variable is not supported. 

The following options are not supported: −x, −A, and −X. 

The linker searches for the symbol $START$ as the program entry point.  This symbol is defined in the file /lib/crt0.o, which should be the first file loaded for all programs, regardless of source language.  Use the −e option to select a different entry point. 

When invoking ld directly to link a C program whose main procedure is located in a library, the −u main option should be used to force the linker to load main from the library, since this symbol is not actually referenced until the _start routine is loaded from the C library.  If you use cc(1) to link the program, the compiler will automatically pass this option to the linker. Because of this "side effect," you should not use cc to link a program containing a FORTRAN or Pascal main program; use f77 or pc instead. 

Nonsharable, executable files generated with the −N option cannot be executed via exec(2). Typically, −N is used when rebuilding the kernel. 

When the −A option is used to do an incremental link, the linker generates extra code where a procedure call crosses a quadrant boundary.  (A quadrant is one gigabyte, or one fourth of the addressing space.)  On the Series 800, text is normally in the first quadrant and data is in the second quadrant.  When an object file is intended to be read into an already-executing program, both its code and data must be placed in the second quadrant, since the first quadrant is set to read-only.  Procedure calls from one quadrant to the other require the extra code, called inter-space calling stubs.  The linker generates an "export" stub for the entry point designated in the incremental link, and "import" stubs for each procedure in the basis program that is called by the new object file.  The import stubs require the existence of a routine in the basis program called _sr4export, which is supplied in /lib/crt0.o. 

The Series 800 linker does not support the −V option. 

The following options are specific to the Series 800 linker:

-y symbol Indicate each file in which symbol appears.  Many such options can be given to trace many symbols, but −y must precede each one. 

-Cn Set the maximum parameter checking level to n. The default maximum is 3. See the language manuals for the meanings of the parameter checking level.

-D offset Set the origin (in hexadecimal) for the data space.  The default value for offset is 0x40000000. 

-G Strip all unloadable data from the output file.  This option is typically used to strip debug information. 

-S Generate an Initial Program Loader (IPL) auxiliary header for the output file, instead of the default HP-UX auxiliary header. 

-T Save the load data and relocation information in temporary files instead of memory during linking.  This option reduces the virtual memory requirements of the linker. 

AUTHOR

Ld was developed by AT&T and HP. 

FILES

/lib/libx.a libraries

/usr/lib/libx.a libraries

a.out output file

Series 300

/lib/crt0.o run-time start-up for C and Pascal

/lib/mcrt0.o run-time start-up for C and Pascal with profiling (see prof(1)

/lib/gcrt0.o run-time start-up for C and Pascal with profiling (see gprof(1)

/lib/frt0.o run-time start-up for FORTRAN

/lib/mfrt0.o run-time start-up for FORTRAN with profiling (see prof(1)

/lib/gfrt0.o run-time start-up for FORTRAN with profiling (see gprof(1)

/usr/lib/end.o for use with cdb/fdb/pdb(1)

Series 800

/lib/crt0.o run-time start-up

/lib/mcrt0.o run-time start-up with profiling (see prof(1)

/lib/gcrt0.o run-time start-up with profiling (see gprof(1)

/usr/lib/xdbend.o for use with xdb(1)

/usr/lib/nls/$LANG/ld.cat
message catalog

/tmp/ld∗ temporary files

SEE ALSO

ar(1), cc(1), cdb(1), f77(1), gprof(1), nm(1), pc(1), prof(1), strip(1), exec(2), end(3C), a.out(4), ar(4). 

Hewlett-Packard Company  —  May 11, 2021