LD(1) SysV LD(1)
NAME
ld - link editor for common object files
SYNOPSIS
ld [options] [-A option[,argument]... ] filename ...
DESCRIPTION
ld combines several object files into one, performs relocation, resolves
external symbols, and supports symbol table information for symbolic
debugging. In the simplest case, you specify the names of several object
programs, and ld combines the objects, producing an object module that
can either be executed or, if you specify the -r option, used as input
for a subsequent ld run. The output of ld is left in a.out. By default
this file is executable if no errors occurred during the load. If any
input file (filename) is not an object file, ld assumes it is either an
archive library or a text file containing link editor directives.
If any argument is a library, it is searched exactly once, at the point
it is encountered in the argument list. ld loads only routines that
define an unresolved external reference. It searches the library
(archive) symbol table sequentially with as many passes as are necessary
to resolve external references that library members can satisfy (see
ar(4)). Thus, the ordering of library members is functionally unimpor-
tant, unless multiple library members define the same external symbol.
OPTIONS
-a Produce an object file for execution. This option is in effect
by default unless -r is specified. The -a option removes relo-
cation entries from the object module and allocates a .bss sec-
tion for global symbols. If you specify both -a and -r, the
link editor preserves relocation entries and also allocates a
.bss section.
-e epsym Set the default entry point address for the output file to be
that of the symbol epsym.
-f fill Set the default fill pattern for "holes" within an output sec-
tion as well as initialized bss sections. The argument fill is
a two-byte constant.
-lx Search the library libx.a, where x may contain up to nine char-
acters. 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. If the SYSTYPE environment
variable is set to bsd4.3, ld will also search for libraries in
/usr/local/lib.
-Ldir Change the algorithm of searching for libx.a to look in dir
before looking in /lib and /usr/lib (and /usr/local/lib for
SYSTYPE = bsd4.3). This option is effective only if it pre-
cedes the -l option on the command line.
-m Produce a map or listing of the input/output sections on the
standard output.
-M Outputs a message for each multiply-defined external defini-
tion.
-o outfile
Produce an output object file with the name outfile. The name
of the default object file is a.out.
-r Preserve relocation entries in the output object module and
suppress the allocation of a .bss section. The output file is
not executable unless -a is also specified. Relocation entries
must be preserved if the object file will be specified in a
future ld command. If you do not specify -r, ld removes relo-
cation entries and allocates a .bss section. To preserve relo-
cation entries and also allocate a .bss section, specify both
-r and -a.
-s Strip line number entries and symbol table information from the
output object file. This option is equivalent to using the
strip(1) utility and is useful if you want to reduce the size
of the object module.
NOTE: If you use the -s option, you cannot debug the resulting
program with a source level debugger (dbx or dde).
-t Turns off the warning about multiply-defined symbols that are
not the same size.
-Tsystype Define the target system type (systype) for the compiled
object. Same as -A sys[type],sys.
-u symname
Enter symname as an undefined symbol in the symbol table. This
is useful for loading entirely from a library, since initially
the symbol table is empty and an unresolved reference is needed
to force the loading of the first routine. The placement of
this option on the ld line is significant; it must be placed
before the library which will define the symbol.
-V Output a message giving information about the version of ld
being used.
-VS num Use num as a decimal version stamp identifying the a.out file
that is produced. The version stamp is stored in the optional
header.
-x Do not preserve local symbols in the output symbol table; enter
external and static symbols only. This option may save some
space in the output file, but it has no effect on objects com-
piled on Domain/OS systems, since Domain/OS compilers do not
generate local symbol information.
-Y[LU],dir
Change the default directory used for finding libraries. If L
is specified, the first default directory ld searches, /lib, is
replaced by dir. If U is specified, and ld has been built with
a second default directory, /usr/lib, then that directory is
replaced by dir. If ld was built with only one default direc-
tory and U is specified, a warning is printed and the option is
ignored.
DOMAIN/OS EXTENSIONS
The Domain/OS version of ld, includes support for features which are not
available on System V. Domain/OS ld supports the following extensions:
Static Resource Information records (.sri), Module Information records
(.mir), and control of global variable visibility.
When you specify arguments to the following options, there must be no
space before or after the comma.
-A sys[type],sys
Set the environment variable SYSTYPE to sys while ld is run-
ning. If sys is any, SYSTYPE is not reset. A static resource
information (SRI) record for SYSTYPE is produced. This option
is useful to set the resolution of systype-dependent links at
run time. For example, if your systype is bsd4.3, and you
specify -A systype,sys5.3, the file /usr/lib/libm.a resolves to
/sys5.3/usr/lib/libm.a, instead of /bsd4.3/usr/lib/libm.a.
-A run[type],sys
Determine the system-call semantics of the object module. For
example, if you specify -A systype,any, and specify -A
runtype,bsd4.3, the executable resolves pathnames according to
your current SYSTYPE value, but always uses bsd4.3 system-call
semantics.
-A allres[olved]
Exit with an error status if unresolved references exist. This
is the default.
-A noallres[olved]
Terminate successfully even if unresolved references exist (if
there are no other errors during linking). This option is use-
ful when you run ld from shell scripts or other drivers, such
as /bin/cc or /bin/make.
-A ansi Observe certain ANSI rules concerning global data. Specifi-
cally, there can be only one definition of a global, whether it
is initialized or not. (Without -A ansi, multiple uninitial-
ized definitions are tolerated and share the same memory.)
-A cpu,id Specify the target machine type on which the program will run.
The id must be either m68k or a88k. Use this option if you are
linking on one target machine type but your executable file
will run on the other.
-A exp[unge],sym1,sym2,...
Remove the defined global symbol from the symbol table. No
subsequent link runs (using ld or bind) can resolve to this
symbol. The symbol is not entered into the KGT (Known Global
Table) if this object is installed, nor is it visible if this
object is part of an archive.
-A allexp[unge] [-A keep[sym],sym1,sym2,...]
Expunge all defined symbols except those specified by the -A
keepsym option. If this option appears multiple times, all
symbols specified are kept in the symbol table.
-A inlib,pathname1,pathname2,...
Specify the pathnames of the libraries to be installed at load
time.
-A noinlib,pathname1,pathname2,...
Delete the named libraries from the list of libraries to be
installed at load time.
-A loadhigh
Create an SRI record to instruct the loader to load the object
at the "high" end of memory (for position independent code).
-A looks[ection],sec1,sec2,...
Make the named section available for sharing with a public sec-
tion in an installed library.
-A alllooks[ection]
Make all sections available for sharing with their counterpart
public sections in an installed library.
-A nolooks[ection],sec1,sec2,...
Make the named sections (sec1, sec2,...) unavailable for
sharing.
-A allnolooks[ection]
Make all data named sections unavailable for sharing.
-A marks[ection],sec1,sec2,...
Make the specified section names (sec1, sec2,...) public.
Affects only those object files that are destined to be
installed as an installed library.
-A allmarks[ection]
Make all sections public. Affects only those object files that
are destined to be installed as an installed library.
-A nomarks[ection],sec1,sec2,...
Make the named sections private.
-A allnomarks[ection]
Make all sections private.
-A module,name
Specify the object module name of the output binary file. This
name will be stored in an object file Module Information Record
(MIR). The default name of the object module is the name of
the first object module read.
-A nosys[tem]
Make system globals invisible to ld. Turn off the check in the
KGT (Known Global Table) and installed libraries.
-A segsize,num
Set the segment size to num, which may be either 32 or 256.
The default is 256. Use -A segsize,32 if you want your program
to run on SR10.1.
-A sparse_vm
Allocate virtual memory disk space dynamically rather than at
process creation.
-A stacksize,hexnum
Produce a stacksize record (SRI) with the specified value; hex-
num is a one-digit to eight-digit hexadecimal number, option-
ally preceded by 0x or 0X.
BUGS
Through its options and input directives, the common link editor gives
users great flexibility; however, you must assume some added responsibil-
ities. Input directives and options should ensure the following proper-
ties for programs:
⊕ C defines a zero pointer as null. A pointer to which zero has been
assigned must not point to any object. To satisfy this, do not place
any object at virtual address zero in the program's address space.
⊕ When you call ld through cc(1), a startup routine is linked with your
program. The pathname of the routine is /usr/apollo/lib/crt0.o if you
compile with the default -A xansi or with -A ansi, or /usr/lib/crt0.o
if you compile with -A nansi. (If you compile with one of the profil-
ing options, the filename is mcrt0.o or gcrt0.o). If you call ld
directly, you must link in this routine yourself.
The symbols etext, edata, and end (see end(3C)) are reserved and are
defined by the link editor. Your program may not redefine them.
If the link editor does not recognize an input file as an object file or
an archive file, it assumes that it contains link editor directives and
attempts to parse it. This occasionally produces an error message com-
plaining about syntax errors.
Arithmetic expressions can only have one forward-referenced symbol per
expression.
FILES
/lib/libx.a Libraries
/usr/lib/libx.a Libraries
/usr/local/lib/libx.a Libraries (bsd4.3 only)
a.out Output file
SEE ALSO
ar(1), cc(1), end(3), ar(5), a.out(5), systype(1M)