LD(1) — HP-UX

NAME

ld − link editor

SYNOPSIS

ld [ [ option ] ... [ 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 it is 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−one 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.)

−lx Search a library libx.a, where x is up to nine 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 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 so that it does not contain symbol table, relocation, and debug support information. This may 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 symname Enter symname as an undefined symbol in the symbol table. The resulting unresolved reference is useful for linking a program entirely from object files in a library.

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

−x Partially strip the output file, i.e., 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 may impact 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. This option is effective only if it precedes the −l option on the command line.

−N Generate an (executable) output file that is not shareable. 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 are marked as shareable.

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

AUTHOR

Ld was developed by AT&T and HP.

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, −L, and −Z.

Series 500
The linker searches for _main (written as main in C) as the main entry point for a user program. Use the −e option to select a different entry point.

The special names etext and edataare not supported.

The linker marks output files with the following memory management attributes by default: virtual code, virtual data (both D-data and I-data), and paged I-data. Executable output files are not shareable if they contain symbolic debug information.

The −N option does not cause the data to be placed immediately after the text because each is always kept in a separate segment.

The −t option displays file names twice, once for each pass over the input.

These options are specific to the Series 500 linker:

-A Put D-data and I-data in separate segments.

-M maxsize Merge code segments. The integer argument specifies a target upper bound on the size of output code segments. (The actual size may vary from this.)

-T Put D-data and I-data into the same segment.

The Series 500 linker does not support the following options: −m, −x, −L, and −R.

Unless the user specifies a −A or a −T option, the linker puts all data in a single segment (GDS) when the total data size is less than or equal to 16,384 bytes.

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

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

The following options are specific to the Series 800 linker:

-y symname Indicate each file in which symname appears. Many such options may be given to trace many symbols.

-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 in a file instead of memory during linking. This option reduces the virtual memory requirements of the linker.

The Series 800 linker does not support the following options: −x, −A, −V, and −X.

DIAGNOSTICS

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

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.

FILES

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

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

/lib/prt0.o run-time start-up for Pascal

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

/lib/libx.a libraries

/usr/lib/libx.a libraries

a.out output file

Museum

Related Articles