NAME
ld - link editor

SYNOPSIS
ld [ option ] ... file ...

DESCRIPTION
Ld combines several object programs into one, resolves external
references, and searches libraries. In the simplest case several
object files are given, and ld combines them, producing an object
module which can be either executed or become the input for a
further ld run. (In the latter case, the -r option must be given
to preserve the relocation bits.) The output of ld is left on
a.out. This file is made executable only if no errors occurred
during the load.

The argument routines are concatenated in the order specified. The
entry point of the output is the beginning of the first routine
(unless the -e option is specified).

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 ranlib(1), the referenced routine
must appear after the referencing routine in the library. Thus the
order of programs within libraries may be important. The first
member of a library should be a file named ‘__.SYMDEF’, which is
understood to be a dictionary for the library as produced by
ranlib(1); the dictionary is searched iteratively to satisfy as
many references as possible.

The MachTen version of ld assumes the target is intended to be a
MachTen executable, except when the -cross flag is set. When
creating a MachTen executable, the symbol table and relocation
information must remain. Unless -cross is set, the flags -Sand-s
are ignored and is always set. The symbols _etext, _edata, _end,
and STACKSIZE are reserved and always included in the resulting
output file.

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.

Ld understands several options. Except for -l, they should appear
before the file names.

-A This option specifies incremental loading, i.e. linking is to
be done in a manner so that the resulting object may be read
into an already executing program. The next argument is the
name of a file whose symbol table will be taken as a basis on
which to define additional symbols. Only newly linked
material will be entered into the text and data portions of
a.out, but the new symbol table will reflect every symbol
defined before and after the incremental load. This argument
must appear before any other object file in the argument list.
The -T option may be used as well, and will be taken to mean
that the newly linked segment will commence at the
corresponding address (which must be a multiple of 1024). The
default value is the old value of _end.

-c MachTen only. Ignored if -cross is set. Allow the output
program to make Macintosh ROM TRAP calls, without requiring a
complete MachTen Macintosh program context.

-cross
MachTen only. Avoid the MachTen postprocessing of the symbol
table, and allow a non-relocatable a.out to be created.

-D Take the next argument as a hexadecimal number and pad the
data segment with zero bytes to the indicated length.

-d Force definition of common storage even if the -r flag is
present.

-e The following argument is taken to be the name of the entry
point of the loaded program; location 0 is the default.

-Ldir
Add dir to the list of directories in which libraries are
searched for. Directories specified with -L are searched
before the standard directories.

-lx This option is an abbreviation for the library name ‘libx.a’,
where x is a string. Ld searches for libraries first in any
directories specified with -L options, then in the standard
directories ‘/lib’, ‘/usr/lib’, and ‘/usr/local/lib’. A
library is searched when its name is encountered, so the
placement of a -l is significant.

-M produce a primitive load map, listing the names of the files
which will be loaded.

-N Do not make the text portion read only or sharable. (Use
"magic number" 0407.)

-n Arrange (by giving the output file a 0410 "magic number") 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 1024
byte boundary following the end of the text.

-o The name argument after -o is used as the name of the ld
output file, instead of a.out.

-r Generate relocation bits in the output file so that it can be
the subject of another ld run. This flag also prevents final
definitions from being given to common symbols, and suppresses
the ‘undefined symbol’ diagnostics.

-S ‘Strip’ the output by removing all symbols except locals and
globals. Disallowed unless combined with the -cross flag.

-s ‘Strip’ the output, that is, remove the symbol table and
relocation bits to save space (but impair the usefulness of
the debuggers). This information can also be removed by
strip(1). Disallowed unless combined with the -cross flag.

-stack <size>
MachTen only. Ignored if -cross is set. Suggest that MachTen
create a stack of the specified size when the a.out is
executed. MachTen will impose a minimum stacksize.

-T The next argument is a hexadecimal number which sets the text
segment origin. The default origin is 0.

-t ("trace") Print the name of each file as it is processed.

-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.

-X Save local symbols except for those whose names begin with
‘L’. This option is used by cc(1) to discard internally-
generated labels while retaining symbols local to routines.

-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.

-ysym
Indicate each file in which sym appears, its type and whether
the file defines or references it. Many such options may be
given to trace many symbols. (It is usually necessary to
begin sym with an ‘_’, as external C, FORTRAN and Pascal
variables begin with underscores.)

-z Arrange for the process to be loaded on demand from the
resulting executable file (413 format) rather than preloaded.
This is the default. Results in a 1024 byte header on the
output file followed by a text and data segment each of which
have size a multiple of 1024 bytes (being padded out with
nulls in the file if necessary). With this format the first
few BSS segment symbols may actually appear (from the output
of size(1)) to live in the data segment; this to avoid wasting
the space resulting from data segment size roundup.

FILES
/usr/lib/lib*.a libraries
/usr/local/lib/lib*.a more libraries
a.out output file