.TH LD 1
.UC
.SH NAME
ld \- loader
.SH SYNTAX
.B ld
[ option ] file ...
.SH DESCRIPTION
.I Ld
combines several
object programs into one, resolves external
references, and searches libraries.
In the simplest case several object
.I files
are given, and
.I ld
combines them, producing
an object module which can be either executed or
become the input for a further
.I ld
run.
(In the latter case, the
.B \-r
option must be given
to preserve the relocation bits.)
The output of
.I ld
is left on \fBa.out\fP.
This file is made executable
only if no errors occurred during the load.
Such a module is
in an `executable' format.
.PP
The argument routines are concatenated in the order
specified.  The default entry point is the
beginning of the first routine.
.PP
If any argument is a library, it is searched exactly once
at the point it is encountered in the argument list.
Only those routines defining an unresolved external
reference are loaded.
If a routine from a library
references another routine in the library,
and the library has not been processed by
.IR ranlib (1),
the referenced routine must appear after the
referencing routine in the library.
Thus the order of programs within libraries
may be important.
If the first member of a library is named
`\_\_.SYMDEF',
then it is understood to be a dictionary for the
library
such
as produced by \fIranlib\fP;
the dictionary is searched
iteratively to satisfy as many references as possible.
.PP
The symbols `\_etext', `\_edata' and `\_end'
(`etext', `edata' and `end' in C)
are reserved, and if referred to,
are set to the first location above the program,
the first location above initialized data,
and the first location above all data respectively.
It is erroneous to define these symbols.
.PP
.I Ld
understands several options.
Except for \fB\-l\fP,
they should appear before the file names.
.TP 
.B  \-\^d
Force definition of common storage
even if the
.B \-r
flag is present.
.TP
.B \-\^D
The next argument is a decimal number that sets
the size of the data segment.
.TP
.B \-\^e
The following argument is taken to be the
name of the entry point of the loaded
program; location 0 is the default.
.TP 
.B  \-\^i
When the output file is executed, the program
text and data areas will live in separate address spaces.
The only difference between this option
and
.B \-n
is that here the text and data segments are in separate address spaces
and both start at location 0.
This option creates
a `separate executable' format.
.TP 
.BI \-\^l x
This
option is an abbreviation for the library name
.RI `/lib/lib x .a',
where
.I x
is a string.
If that does not exist,
.I ld
tries
.RI `/usr/lib/lib x .a'.
A library is searched when its name is encountered,
so the placement of a
.B  \-l
is significant.
.TP 
.B  \-\^n
Arrange that
when the output file is executed,
the text portion will be read-only and shared
among all users executing the file.
This involves moving the data areas up to the first
possible 4K word boundary following the
end of the text.
This option creates a `pure executable'
format.
.TP 
.B  \-\^o
The
.I name
argument after
.B \-o
is used as the name of the
.I ld
output file, instead of \fBa.out\fP.
.TP
.B \-\^O
This is a text replacement overlay file; only the text segment
will be replaced by
.IR execve (2).
Shared data must have the same size as
the program overlaid, otherwise the 
.IR execve (2)
will fail.
The entry point to the overlay may be defined with the
.B \-e
option.
This option allows the creation of a `replacement executable'
format.
.TP 
.B  \-\^r
Generate relocation bits in the output file
so that it can be the subject of another
.I ld
run.
This flag also prevents final definitions from being
given to common symbols,
and suppresses the `undefined symbol' diagnostics.
(Note that this option cannot be used with overlays (\fB-Z\fP)
since they cannot be reloaded.)
.TP 
.B  \-\^s
`Strip' the output, that is, remove the symbol table
and relocation bits to save space (but impair the
usefulness of the debugger).
This information can also be removed by
.IR  strip (1).
.TP 
.B \-\^t
Show a trace of the loading of a module.
.TP
.B  \-\^u
Take the following argument as a symbol and enter
it as undefined in the symbol table.
This is useful
for loading wholly from a library, since initially the symbol
table is empty and an unresolved reference is needed
to force the loading of the first routine.
.TP 
.B  \-\^x
Do not preserve local
(non-.globl) symbols in the output symbol table; only enter
external symbols.
This option saves some space in the output file.
It also allows
temporary labels  to be discarded to prevent redefinition in
sucessive \fBld\fP's.
Warning: \fIadb\fP uses these local symbols,
especially when debugging overlaid programs,
so some debugging information is necessarily lost if this option is used.
.TP 
.B  \-\^X
Save local symbols
except for those whose names begin with `L'.
This option is used by
.IR cc (1)
to discard internally generated labels while
retaining symbols local to routines.
.TP
.B \-\^Z
Indicate the creation of an automatic-overlay format. In addition a
.B \-i
or
.B \-n
must be present, for this format is also `separate i/d' or
`pure procedure' only.
Repeated instances bracket the modules that
will be loaded into a given overlay.
Modules before the first
.B \-Z
or after the concluding
.B \-L
will be loaded into the non-overlaid text (base) area.
Note that there may be
a maximum of 7 overlays and that all modules must be
compiled with a special compiler flag (see example).
This option produces
the `overlaid pure executable' and the `overlaid separate executable'
formats.
The loader creates a small entry interface in the base segment
for each subroutine in the overlays.
This interface ("thunk") arranges for the correct overlay
to be present before the actual routine is entered.
.TP
.B \-\^L
Terminate overlaying text.  This will
allow loading the remaining modules or libraries in the non-overlaid
text space.
.SH EXAMPLE
To overlay program text with the loader, use a command of the form:
.IP
.nf
\fBld \-n \-X\fP /lib/crt0.o base.o base2.o
\fB\-Z\fP ov1a.o ov1b.o ...
\fB\-Z\fP ov2a.o ov2b.o ...
...
\fB\-L\fP base3.o ... \-lovc
.fi
.PP
Source code must be compiled using the compiler overlay flags:
.IP
\fIf77 \-c \-V\fP prog.f,
.br
\fIcc \-c \-V\fP prog.c, or
.br
\fIas \-V\fP prog.s
.PP
and the overlay versions of the libraries must be used.
To request the overlaid version of a library, use the prefix "ov".
For example, the f77 library is called
\fBlibovF77.a\fP
and loaded using
\fB\-lovF77\fP.
.PP
When arranging modules into overlays, the following rules
control the maximum sizes for an executable file.
The magic numbers are due to the granularity of PDP-11
segmentation registers (there are 8 registers, each controlling
an 8192-byte segment).
The program is made up of base text, overlay, data + bss, and stack
sections.
The size of the overlay section is controlled by the size of the
largest of the overlays.
Each section starts at an address that is a multiple of 8192,
thus the size of each section is rounded up to a multiple of 8192.
In the case of separate overlaid executable files,
the text and overlays share
one 64K byte address space; the data + bss and stack share the other.
Thus, the total of the base text size (rounded up to an 8K boundary) plus
the maximum overlay size must be less than or equal to 64K
(the number of full or partial text segments plus the number of
overlay segments is <= 8).
As an example, if the base text segment has 36800 bytes and the largest
overlay takes 14144, the base will fit in 5 segments and the overlays
in 2 segments; leaving one to spare.
The data and bss together must fit in 7 segments (56K bytes),
leaving one 8K segment for the stack.
There is also a limit placed on the total size of the program,
including all overlays; that limit is system-dependent.
All of the limits can be checked by using
.IR checkobj (1).
.PP
For pure overlaid programs, the rules are similar except that
all four sections share one 64K-byte address space.
The number of segments required by the text, overlay, data + bss
and stack are calculated in the same way.
The sum of the segments required, including one for the stack,
must be less than or equal to 8.
Example: a program has 8128 bytes of base text, the largest overlay
is 16248 bytes, and the data and bss total 19500.
The text requires 1 8K segment, the overlays 2, and data and bss
use 4, leaving one for the stack.
.SH FILES
.ta 2i
/lib/lib*.a	libraries
.br
/usr/lib/lib*.a	more libraries
.br
/usr/lib/libov*.a	overlaid versions of libraries
.br
a.out	output file
.SH "SEE ALSO"
adb(1), ar(1), as(1), cc(1), checkobj(1), f77(1), file(1), ranlib(1),
size(1), a.out(5)