LD(1) BSD LD(1)
NAME
ld - link editor for common object files
SYNOPSIS
ld [options] [ -A option,[argument] ... ] file ...
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 be either 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 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 it needs to
resolve external references that library members can satisfy (see ar(5)).
Thus, the ordering of library members is functionally unimportant, unless
multiple library members define the same external symbol.
OPTIONS
-d Force definition of common storage even if the -r flag is
present.
-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
section as well as initialized bss sections. The argument fill
is a two-byte constant.
-lx Search the library named libx.a. ld searches a library when it
encounters the library name, so the placement of a -l is
significant. By default, ld searches for libraries in the
directories specified by the environment variables LIBDIR or
LLIBDIR (these generally resolve to /lib and /usr/lib). You
can specify additional library directories with the -L option.
-m Produce a map or listing of the input/output sections on the
standard output.
-o outfile
Name the final output file outfile. By default, outfile is
a.out. If you specify a different name, the system leaves any
existing a.out files undisturbed.
-r Retain relocation entries in the output object file.
Relocation entries must be saved if the output file is to
become an input file in a subsequent ld run. The link editor
will not complain about unresolved references, and the output
file will not be executable unless -a is also specified.
-a Create an absolute file. This is the default if you do not
specify -r. Used with the -r option, -a allocates memory for
common symbols.
-s Strip line-number entries and symbol-table information from the
output object file. Specifying 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, however, that removing
this information from a program makes it impossible to debug it
with a source-level debugger (dbx or dde).
-T systype
Define the target system type (systype) for the compiled
object.
-t Trace; print the name of each file as it is processed.
-u sym Enter sym as an undefined symbol in the symbol table. This is
useful for loading entirely from a library, since the symbol
table is initially empty and needs an unresolved reference to
force ld to load the first routine. The placement of this
option on the ld line is significant; you must put it before
the library that will define the symbol.
-x Do not preserve local symbols in the output symbol table; enter
external and static symbols only. This option saves some space
in the output file. This option has no effect on objects
compiled on Domain/OS systems, since Domain/OS compilers do not
generate local symbol information.
-L dir Change the search path for libx.a libraries. By default, the
compiler looks for libx.a in the directories specified by
before looking in LIBDIR and LLIBDIR. This option is useful if
you have different versions of a library and you want to
specify which one ld should use. Note that this option is
effective only if it precedes a -l option on the command line.
-M Produce a primitive load map, listing the names of the files
that will be loaded.
-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.
-Y [LU],dir
Change the default directory used for finding libraries. If you
specify L, ld replaces LIBDIR as the first default directory
with dir. If you specify U, and ld was built with a second
default directory, LLIBDIR, ld replaces that directory with
dir. If you specify U, and ld was built with only one default
directory, ld prints a warning and ignores the option.
-ysym Indicate each file in which sym appears, its type, and whether
the file defines or references it. You can specify many such
options to trace many symbols. The placement of -ysym is
significant; symbol tracing is not done on files that precede
the -y option.
-A The 4.3BSD version of this option is not supported in Domain/OS
BSD. Instead, -A identifies Domain/OS BSD-specific options.
The following ld options are not supported in Domain/OS BSD: -D, -n, -N,
-S, -X, and -z.
Domain/OS BSD EXTENSIONS
The Domain/OS BSD version of ld includes support for features that are
not available on 4.3BSD. Domain/OS ld supports the following extensions:
static resource information records (.sri), module information records
(.mir), and control of global variable visibility.
You must precede each of the following arguments with the -A option.
-A sys[type],sys
Sets the environment variable SYSTYPE to sys while ld is
running. 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 the following: -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
This option determines 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 stacksize,hexnum
Produces a stacksize (SRI) with the specified value; hexnum is
a one-digit to eight-digit hexadecimal number, optionally
preceded by 0x or 0X.
-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 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. If this
option appears multiple times, all symbols specified are kept
in the symbol table.
-A looks[ection],sec1,sec2,...
Makes the named section available for sharing with a public
section in an installed library.
-A alllooks[ection]
Makes all sections available for sharing with their counterpart
public sections in an installed library.
-A marks[ection],sec1,sec2,...
Makes 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]
Makes all sections public. Affects only those object files
that are destined to be installed as an installed library.
-A nolooks[ection],sec1,sec2,...
Makes the named sections (sec1,sec2,...) unavailable for
sharing.
-A allnolooks[ection]
Makes all data named sections unavailable for sharing.
-A nomarks[ection],sec1,sec2,...
Makes the named sections private.
-A allnomarks[ection]
Makes all sections private.
-A inlib,pathname1,pathname2,...
Specifies the pathnames of the libraries to be installed at
load time.
-A noinlib,pathname1,pathname2,...
Deletes the named libraries from the list of libraries to be
installed at load time.
-A loadhigh
Creates an SRI record to instruct the loader to load the object
at the "high" end of memory (for position independent code).
-A module,name
Specifies 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]
Do not make system globals visible to ld. Turn off the check in
KGT (Known Global Table) and installed libraries.
-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
useful when you run ld from shell scripts or other drivers,
such as /bin/cc, or /bin/make.
BUGS
Through its options and input directives, the common link editor gives
users great flexibility; however, those who use the input directives must
assume some added responsibilities. Input directives and options should
ensure the following properties for programs:
⊕ C defines a zero pointer as null. A pointer to which zero is 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. This routine calls after execution of the main program. If
you call ld directly, you must ensure that the program always calls
exit(2) rather than falling through the end of the entry routine.
The symbols etext, edata, and end (see end(3C)) are reserved and are
defined by ld. It is incorrect for a user program to redefine them.
If ld does not recognize an input file as an object file or an archive
file, it assumes that it contains ld directives and attempts to parse it.
This occasionally produces an error message complaining about syntax
errors.
Arithmetic expressions can have only one forward-referenced symbol per
expression.
FILES
LIBDIR/libx.a Libraries
LLIBDIR/libx.a Libraries
a.out Output file
LIBDIR Usually /usr/lib
LLIBDIR Usually /usr/lib
SEE ALSO
ar(1), cc(1), end(3), ar(5), a.out(5), systype(1)