NAME

ld − link editor

SYNOPSIS

ld [−bdmnqrstvxzENQZ] [+e symbol] [+E symbol] [+I symbol] [−a search] [−c filename] [−e epsym] [−h symbol] ... [−o outfile] [−u symbol] ... [−A name] [−B bind] [−L dir] ... [−R offset] [−V num] [−X num] [−lx | file] ...

DESCRIPTION

ld takes one or more object files or libraries 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 produces an executable file that can be run by the HP-UX loader exec(2). Alternatively, the linker can generate a relocatable file that is suitable for further processing by ld (see −r below).  It can also generate a shared library (see −b below).  The linker marks the output file non-executable if any unresolved external references remain.  ld may or may not generate an output file if any other errors occur during its operation; see DEPENDENCIES.  ld recognizes three kinds of input files: object files created by the compilers, assembler, or linker (also known as “.o” files), shared libraries created by the linker, and archives of object files (called archive libraries).  An archive 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 an archive 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. 

Code from shared libraries is never copied into an executable program, and data is copied only if referenced directly by the program.  The dynamic loader /lib/dld.sl is invoked at startup time by /lib/crt0.o if a program uses shared libraries.  The dynamic loader attaches each required library to the process and resolves all symbolic references between the program and its libraries.  The text segment of a shared library is shared among all processes that use the library. 

Environment Variables

Arguments can be passed to the linker through the LDOPTS environment variable as well as on the command line.  The linker picks up the value of LDOPTS and places its contents before any arguments on the command line. 

The LD_PXDB environment variable defines the full execution path for the debug preprocessor pxdb. The default value is /usr/bin/pxdb.  ld invokes pxdb on its output file if that file is executable and contains debug information.  To defer invocation of pxdb until the first debug session, set LD_PXDB to /dev/null. 

Options

ld recognizes the following options:

−a search Specify whether shared or archive libraries are searched with the −l option.  The value of search should be one of archive, shared, or default.  This option can appear more than once, interspersed among −l options, to control the searching for each library.  The default is to use the shared version of a library if one is available, or the archive version if not.  If either archive or shared is active, only the specified library type is accepted. 

−b Create a shared library rather than a normal executable file.  Object files processed with this option should contain position independent code (PIC).  See the discussion of PIC in cc(1), CC(1) [part of optional C++ compiler documentation], f77(1), pc(1), and as(1).

−c filename Read options from an indirect file.  Each line contains zero or more options separated by white space.  A # character implies that the rest of the line is a comment.  To escape a # character, use the sequence ##. 

−d Forces definition of “common” storage; i.e., assign addresses and sizes, 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.

More than one symbol can be specified, but −h must precede each one.  If used when building a shared library or program, this option prevents the named symbol from being visible to the dynamic loader. 

−lx Search a library libx.a or libx.sl, where x is one or more characters.  The current state of the −a option determines whether the archive (.a) or shared (.sl) version of a library is searched. 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.  If a program uses shared libraries, the dynamic loader /lib/dld.sl will attempt to load each library from the same directory in which it was found at link time. 

−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 (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.  The ld command does not report undefined symbols.  The −r option is incompatible with −A and −b. 

−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.  For each library module that is loaded, the linker indicates which symbol caused that module to be loaded. 

−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.  Linking is arranged so that the resulting object can 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, which allows the newly linked segment to commence at the corresponding address.  The default starting address is the old value of _end.  The −A option is incompatible with −r and −b. 

−B bind Select run-time binding behavior of a program using shared libraries.  The most common values for bind are immediate or deferred.  The default is deferred, which tells the dynamic loader /lib/dld.sl to resolve procedure calls on first reference rather than at program start-up time.  A modifier bind value of nonfatal can be used with the immediate major binding mode to allow procedure calls that cannot be resolved at program start-up to be resolved on first reference.  See the example below. 

−E Mark all symbols defined by a program for export to shared libraries.  By default, ld can mark only those symbols that are actually referenced by a shared library. 

−L dir Change the algorithm of searching for libx.a or libx.sl to look in dir before looking in default locations.  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 makes the text 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, nor is it the same as the version information recorded for shared library use. 

−X num Define the initial size for the linker’s global symbol table.  This reduces link time for very large programs, especially those with a large number of external symbols. 

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

+e symbol When building a shared library or program, mark the symbol for export to the dynamic loader.  With the use of this option, only symbols explicitly marked are exported.  When building a shared library, calls to symbols that are not exported are resolved internally. 

+E symbol Specify the name of the elaborator function when building a shared library.  See the Programming on HP-UX manual for a description of the elaborator function. 

+I symbol Specify the name of the initializer function when building a shared library.  See the Programming on HP-UX manual for a description of the initializer function. 

Defaults

Unless otherwise directed, ld names its output a.out.  The −o option overrides this.  Executable output files can be shared.  The default state of −a is to search shared libraries if available, archive libraries otherwise.  The default bind behavior is deferred. 

EXTERNAL INFLUENCES

Environment Variables

LANG determines the language in which messages are displayed (Series 700/800 only). 

If LANG is not specified or is set to the empty string, a default of "C" (see lang(5)) is used instead of LANG. 

If any internationalization variable contains an invalid setting, ld behaves as if all internationalization variables are set to "C".  See environ(5).

DIAGNOSTICS

ld returns 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/400 system.) 

ld −e start /lib/frt0.o ftn.o −lI77 −lF77 −lm −lc /usr/lib/end.o

This example creates a shared library. 

ld −b −o libfunc.sl func1.o func2.o func3.o

Link a program with libfunc.sl but use the archive version of the C library.  Specify the immediate binding mode together with the nonfatal modifer:

ld /lib/crt0.o −B immediate −B nonfatal program.o −L . 
−lfunc −a archive −lc

Link a Pascal program on a Series 300/400 system:

ld /lib/crt0.o main.o −lpc −lm −lc

WARNINGS

ld recognizes several names as having special meanings.  The symbol _end is reserved by the linker to refer to the first address beyond the end of the program’s address space.  Similarly, the symbol _edata refers to the first address beyond the initialized data, and the symbol _etext refers to the first address beyond the program text.  The linker treats a user definition of any of these symbols as an error.  The symbols end, edata, and etext are also defined by the linker, but only if the program contains a reference to these symbols and does not define them (see end(3C) for details).

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 archive libraries and include them in the final program in the same relative order that they occur within the library. 

DEPENDENCIES

Series 300/400
The default entry point is taken to be text location 0x0 (which is also the default origin of the program text) if shared libraries are not used. Otherwise, the entry point is taken to be the first text location after the extension header placed at the beginning of the text segment by ld for use by /lib/dld.sl. This corresponds to the first procedure in the first input file that the linker reads. If the C startup routine /lib/crt0.o is the first object file on the command line, the label start denotes the entry point.  Use the −e option to select a different entry point. 

The version number specified with the −V option must be in the range 0 through 32767.  Use of this option is not recommended because this field is used by several HP-UX commands that expect particular values here.  Consult the C Programmer’s Guide for more details on the version field. 

The placement of −L options relative to −l is not significant. 

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

On Series 300/400 systems, the compilers place an underscore at the beginning of all external names.  Thus, the symbol _end appears to the linker as __end. 

ld does not generate an output file if any other errors occur during its operation (see DESCRIPTION). 

Series 700/800
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.  When using cc(1) to link the program, the compiler automatically passes this option to the linker. Because of this behavior, do 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 or when preparing an image for dynamic loading. 

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 Series 700/800 systems, 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.  If a procedure in the basis program is called indirectly by the new object file, the linker cannot detect the crossing of the quadrant boundary, and therefore will not generate the needed stub.  A special version of $$dyncall placed in /lib/dyncall.o is provided for handling the inter-quadrant branch.  This routine should be linked in when the −A option is in effect. 

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

The following environment variables are specific to the Series 700/800 linker:

The FLOW_DATA_DIR environment variable is used by the procedure repositioning feature of the linker.  An instrumented executable (see −I option) writes out the procedure call profile data to a file named flow.data in the current directory.  The location of this file can be altered by setting the FLOW_DATA_DIR to the desired directory. 

The following options are specific to the Series 700/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 0x40001000. 

Since certain optimizations are now performed in the page previous to 0x40001000, some applications will not function as before if the start of the data space is set to be within the range 0x40000000 through 0x40001000. 

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

−I Instrument the code to collect procedure call counts upon execution.  This option is for use in conjunction with the −P option. 

−O Turn on linker optimizations.  Currently the optimizations include the elimination of unnecessary ADDIL instructions from the code in the executable file.  The linker also rearranges data to further reduce the number of ADDIL instructions in the executable. 

This optimization may reveal some subtle programming errors related to assumptions about data layout. 

−O is passed on to the linker by the compilers when the +O3 compiler option is selected. 

−P Examine the data file produced with the −I option and reposition the procedures according to a “closest is best” strategy. 

−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.  If the TMPDIR environment variable is set, the temporary files are created in the specified directory, rather than in /tmp. 

ld treats both duplicate symbols and unresolved symbols in the same manner:  an output file is generated and marked as non-executable if errors occur during its operation (see DESCRIPTION). 

AUTHOR

ld was developed by AT&T, the University of California, Berkeley, and HP. 

FILES

/lib/libx.a archive libraries

/usr/lib/libx.a archive libraries

/lib/libx.sl shared libraries

/usr/lib/libx.sl shared libraries

a.out output file

/lib/dld.sl dynamic loader

Series 300/400

/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 700/800

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

/lib/dyncall.o used with −A−option links

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

/lib/milli.a millicode library automatically searched by ld

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

/lib/measure.o linked with an executable to instrument it using the −I option

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

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

/tmp/ld∗ temporary files

flow.data file containing procedure calling profile for an instrumented executable. 

/bin/fdp program for creating the procedure link order from flow.data file created by an instrumented executable.  Forked by −P option. 

SEE ALSO

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

Programming on HP-UX manual. 

CC(1) in optional C++ compiler documentation. 

STANDARDS CONFORMANCE

ld: SVID2, XPG2

Hewlett-Packard Company  —  HP-UX Release 8.05: June 1991