LD(1) HP-UX 5.0 LD(1) NAME ld - link editor SYNOPSIS ld [ [option] ... [file] ... ] ... HP-UX COMPATIBILITY Level: HP-UX/NUCLEUS Origin: HP 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 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 options may occur anywhere on the command line following the command name itself. Some options require a modifier following the option letter (e.g. ... -o outputname). Ld recognizes modifiers either as part of the word containing the option letter, or as a separate word following the option letter. This is the same convention as used by getopt(3). Ld recognizes the following options. In the descriptions below, a colon following an option letter indicates that it takes an additional modifier. The colon itself is not literal, and must not appear on the command line. -N generate an (executable) output file that is not shareable. -Q ensure that the output file is not marked as demand- loadable. (This is the complement of the -q option.) -V : specifies a version stamp (in decimal) to identify the output file. This is not the same as the version information reported by the SCCS what(1) command. -X : indicates 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). Note: the linker expands its data structures as necessary no matter what their starting size. provides the user with a means of controlling the size of the linker's symbol table. It is useful for dealing with very large applications that contain a great many externally visible symbols. -d forces definition of "common" storage (i.e. assign addresses and sizes), even for -r output. -e : names an alternate entry point for the output file. The loader will then call the alternate entry point to initiate the program. (Thus this option only applies to executable files.) -h : 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.) -l : abbreviation for a library name. Ld searches for a library called libx.a, where x is a string of up to nine ASCII characters specified as the modifier to the -l option. A null string for x is the same as specifying -lc. In this case, the linker searches specific directories for libraries. By default, it first looks in /lib, and then in /usr/lib. Since ld searches files (including libraries) in the same order that they are named on the command line, the placement of -l options is important. -n generate an (executable) output file with code to be shared by all users. Compare with -N. -o : specifies a name for the output file that the linker generates. (The default name is a.out.) -q generate an (executable) output file that is demand- loadable. Compare with -Q. -r retains 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. The file names appear once for each pass over the input (usually two). -u : indicates a name to enter as an undefined symbol in the linker's symbol table. The resulting unresolved reference is useful for linking a program entirely from object files in a library. 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 -V2 -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. ld -e start /lib/frt0.o ftn.o -lI77 -lF77 -lm -lc /usr/lib/end.o Finally, this command will link a PASCAL program. ld -e start /lib/prt0.o main.o -lpccat -lpc -lm -lc HARDWARE DEPENDENCIES Series 200: 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 - 32,767. These options are specific to the Series 200 linker: -R : specifies an alternate origin (in hexadecimal) for the text (i.e. code) segment. -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. 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 edata are 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 -t option displays file names twice, once for each pass over the input. These options are specific to the Series 500 linker: -A forces the linker to put D-data and I-data in separate segments. -M : enables merging of 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 forces the linker to put D-data and I-data into the same segment. -v display verbose messages. This option may have little or no effect. It is useful for obtaining more information about an error that occurs while linking. 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. 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 SEE ALSO ar(1), cc(1), cdb(1), fc(1), nm(1), pc(1), strip(1), exec(2), end(3), a.out(5), ar(5). 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 (end, edata, and etext in C) are reserved. (See end(3) 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 insure 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 the user calls ld directly, then he or she must insure 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 and furthermore that main is the initial entry point for executing the program. (Thus the -e option is compatible with debugging.) 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.