NAME

ld − link editor

SYNOPSIS

ld [-bdmnqrstvxzENQZ] [+b path_list] [+e symbol] ... [+s] [+I symbol] [-a search] [-c filename] [-e epsym] [-h symbol] ... [-o outfile] [-u symbol] ... [-y symbol] ... [-A name] [-B bind] [-D offset] [-L dir] ... [-R offset] [-V num] [-X num] [-l x | 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() (see 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. 

The LPATH environment variable can be used to specify default directories to search for library files. See the -l option. 

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 arguments 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 (see +s and +b options). 

-m Produce a load map on the standard output. 

-n Generate an (executable) output file with file type SHARE_MAGIC.  This option is incompatible with -N and -q. 

-o outfile Produce an output object file named outfile (a.out if outfile is not specified). 

-q Generate an (executable) output file with file type DEMAND_MAGIC.  This option is incompatible with -n, -N, and -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. 

-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. 

-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.  See the Programming on HP-UX manual for a description of this option. 

-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. 

-D offset Set the origin (in hexadecimal) for the data segment. 

-E Mark all symbols defined by a program for export to shared libraries.  By default, ld marks only those symbols that are actually referenced by a shared library seen at link time. 

-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 with file type EXEC_MAGIC.  This option is incompatible with -n and -q.  This option causes the data to be placed immediately following the text, and makes the text writable.  Files of this type cannot be shared. 

-Q Generate an (executable) output file with file type EXEC_MAGIC or SHARE_MAGIC, depending on whether -N or -n is specified.  This option is incompatible with -q. 

-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 command (see what(1)), 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.) 

+b path_list Specify a colon-separated list of directories to be searched at program run-time to locate shared libraries needed by the executable output file that were specified with either the -l or -l: (Series 700/800) option.  An argument consisting of a single colon (:) indicates that ld should build the list using all the directories specified by the -L option and the LPATH environment variable (see +s 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. 

+s Indicates that the shared library loader can use the environment variable SHLIB_PATH to locate shared libraries needed by the executable output file that were specified with either the -l or -l: (Series 700/800) option. The SHLIB_PATH environment variable should be set to a colon-separated list of directories. If both +s and +b are used, their relative order on the command line indicates which path list will be searched first (see the +b option). 

+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. 

The default value of the -Z/-z option is -Z. 

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

Link part of a C program for later processing by ld.  Specify 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

Link a simple FORTRAN program for use with the xdb symbolic debugger (see xdb(1)). Output file name is a.out since there is no -o option in the command line.  Options shown are for a Series 300/400 system:

ld /lib/frt0.o ftn.o -lquad -lIO77 -lF77 -lm -lc /usr/lib/end.o

Create 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 modifier:

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 xdb, 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. 

By default, the data segment begins on the next page following the text segment. 

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 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). 

The default file type is DEMAND_MAGIC if the total size of text and data is greater than the constant DEMAND_THRESHOLD; otherwise the file type defaults to SHARE_MAGIC.  DEMAND_THRESHOLD is defined in /usr/include/a.out.h, and this value may vary from release to release.  See the manual How HP-UX Works: Concepts for the System Administrator for a discussion of the various file types. 

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. 

By default, the data segment begins at offset 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 segment is set to be within the range 0x40000000 through 0x40001000. 

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. For these files, the data segment begins on the next page following the text segment. 

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. 

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). 

The default file type is SHARE_MAGIC.  See the manual How HP-UX Works: Concepts for the System Administrator for a discussion of the various file types. 

The Series 700/800 linker works in conjunction with the compilers to support profile-based optimization: transformations that use profile data gathered from previous runs of a program to improve run-time performance.  Profile data collection and profile-based optimizations can be performed within the bodies of procedures compiled with the +I option to cc or f77 (see cc(1) and f77(1)). For example, code can be repositioned within procedures so that fewer branches are executed and better code locality is achieved. The linker can also instrument calls between procedures, even if they were not compiled with the +I option.  After profile data is collected, the program can be relinked and the linker will reposition the procedures to further improve code locality.  See the -I, -P, +df, and +pgm options below.  Also see the discussion of profile-based optimization in the Programming on HP-UX manual. 

Object files that are compiled with the +I or +P option (see cc(1) and f77(1)) contain a compiler intermediate representation instead of PA-RISC object code.  The linker then invokes a PA-RISC code generator on these files before linking them into the executable file.  Because of this, linking object files compiled with +I or +P may take significantly more time than linking ordinary object files.  The object files that are generated by compiling the intermediate code are written to the directory specified by the TMPDIR environment variable, or /tmp if TMPDIR is not specified.  The object files are deleted before the linker exits. 

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

FLOW_DATA Used by the profile-based optimization feature of the linker.  An instrumented executable (see -I option) writes out the profile data to a database file named flow.data in the current directory.  The name and location of this file can be specified by setting FLOW_DATA to the desired path name.  The profile data is stored in the database file under a look-up name that is the same as the basename of the executable file specified at run-time.  A single flow.data file can hold profile data for multiple program files. 

FLOW_DATA_DIR Obsolete environment variable.  Do not use. 

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

-a search The Series 700/800 linker supports two additional values for the search flag. The value archive_shared indicates that within each directory searched to find the library specified with -l, the archive form is preferred, but the shared form is allowed. The value shared_archive states that the shared form is preferred but the archive form is allowed. 

-l: library Search the library specified. Similar to the -l option except the current state of the -a option is not important. The library name must contain the prefix lib and end with a suffix of .a or .sl. 

-B bind Along with the major binding modes of immediate and deferred, the bind modifier restricted can be specified to indicate that the symbols visible to the shared libraries needed by the executable output file should be limited to the symbols available at program start-up.  See the Programming on HP-UX manual for common uses of binding modes. 

-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.

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

-I Instrument the code to collect profile information upon execution.  The profile data gathered during program execution can be used in conjunction with the -P option.  Programs linked with this option should use the startup file /lib/icrt0.o instead of /lib/crt0.o.  This option should not be used together with the -b, -s, -G, -A, or -N options. 

-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 by an instrumented program (see the -I option) to perform profile based optimizations on the code.  This option should not be used together with the -A, or -N options. 

-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. 

+df file Used together with the -P option, this option specifies that file should be used as the profile database file.  The default value is flow.data.  See the discussion of the FLOW_DATA environment variable above. 

+pgm name Used together with the -P option, this option specifies that name should be used as the look-up name in the profile database file.  The default is the basename of the output file (specified by the -o option.) 

+FP flags Specify how the environment for floating-point operations should be initialized at program start-up.  By default, all behaviors are disabled.  The following flags are supported (uppercase flag enables; lowercase flag disables):

V (v) Trap on invalid floating-point operations

Z (z) Trap on divide by zero

O (o) Trap on floating-point overflow

U (u) Trap on floating-point underflow

I (i) Trap on floating-point operations that produce inexact results. 

D (d) Enable sudden underflow (flush to zero) of denormalized values. 

Note: Enabling sudden underflow is an undefined operation on PA-RISC 1.0-based systems, but it is defined on all subsequent versions of PA-RISC.  Selecting this flag enables sudden underflow only if it is available on the processor being used at run-time. 

To dynamically change these settings at run-time, see fpgetround(3M).

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

/usr/lib/end.o for use with xdb debugger

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, or pdb debugger

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/icrt0.o run-time start-up with profiling (see discussion of profile based optimization above.) 

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

/tmp/ld* temporary files

flow.data file containing profile data generated by running an instrumented executable

/bin/fdp program for creating the procedure link order from a profile database file created by an instrumented executable; forked by the -P option

/usr/lib/uccom PA-RISC code generator for the C language

/usr/lib/uf77pass1 PA-RISC code generator for the FORTRAN language

/usr/lib/ucomp Default PA-RISC code generator

SEE ALSO

ar(1), cc(1), cdb(1), chatr(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.

How HP-UX Works: Concepts for the System Administrator.

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

STANDARDS CONFORMANCE

ld: SVID2, XPG2

Hewlett-Packard Company  —  HP-UX Release 9.03: April 1994