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
-a Produce an object file for execution. This option is in effect
by default unless -r is specified. The -a option removes
relocation entries from the object module and allocates a .bss
section for global symbols. If you specify both -a and -r, the
link editor preserves relocation entries and also allocates a
.bss section.
-d Same as -a.
-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 /lib and /usr/lib. If the SYSTYPE environment
variable is set to bsd4.3, ld will also search for libraries in
/usr/local/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 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
relocation entries and allocates a .bss section. To preserve
relocation 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. 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: If you use the -s option, you cannot debug the resulting
program with a source level debugger (dbx or dde).
-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.
-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 useful if you have different
versions of a library and you want to specify which one ld
should use. 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.
-Tsystype Define the target system type (systype) for the compiled
object. Same as -A sys[type],sys.
-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 /lib as the first default directory with
dir. If you specify U, and ld was built with a second default
directory, /usr/lib, 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. Instead, -A identifies Domain/OS-specific options.
The following ld options are not supported in Domain/OS: -D, -n, -N, -S,
-X, and -z.
DOMAIN/OS EXTENSIONS
The Domain/OS 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.
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
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 -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.
NOTE: If you specify -A systype,any, calls that have different
semantics in each UNIX environment may not work as expected.
To insure proper behavior, specify a run-time environment with
the -A runtype option.
-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 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.
-A ansi Observe certain ANSI rules concerning global data.
Specifically, there can be only one definition of a global,
whether it is initialized or not. (Without -A ansi, multiple
uninitialized 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
section 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]
Do not make system globals visible 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;
hexnum is a one-digit to eight-digit hexadecimal number,
optionally preceded by 0x or 0X.
-A standard,num
Set a bit in the .sri record of the object file so that the
loader will enforce the appropriate C standard(s). Use this
option only if you receive an "Unrecognized pragma" warning
from Domain/C Version 6.8 concerning the HP_STANDARD pragma.
For the num argument, specify the numeric argument to the
HP_STANDARD pragma that appears in the warning message.
BUGS
Through its options and input directives, the common link editor gives
users great flexibility; however, you must assume some added
responsibilities. Input directives and options should ensure the
following properties for programs:
o 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.
o 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
profiling options, the filename is mcrt0.o or gcrt0.o). If you call
ld directly, you must link in this routine yourself. For more
information, see the SR10.3 Software Release Document.
The symbols etext, edata, and end (see end(3C)) are reserved and are
defined by ld. Your program may not 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
/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(1)