V10/630/man/src/u_man/man1/mc68ld.1

.\"	@(#) ld.1:	2.3 11/17/83
.ds ZZ DEVELOPMENT PACKAGE
.TH MC68LD 1 "630 MTG" 
.SH NAME
mc68ld \- link editor for MC68000 object files
.SH SYNOPSIS
\f3mc68ld [\f1 options \f3]\f1 file-names
.SH DESCRIPTION
The
.I mc68ld
command
combines several
object files into one,
performs relocation,
resolves external symbols,
and supports symbol table information
for symbolic debugging.
In the simplest case, the names of several object
programs are given, and
.I mc68ld
combines them, producing
an object module that can either be executed or
used as input for a subsequent
.I mc68ld
run.
The output of
.I mc68ld
is left in
.BR mc68a.out .
This file is executable
if no errors occurred during the load.
If any input file,
.IR file-name ,
is not an object file,
.I mc68ld
assumes it is either a text file containing link editor directives
or an archive library.
(See
the \f2Link Editor\f1 in the \f2UNIX System V Support Tools
Guide\f1 for a discussion of input directives.)
.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.
The order of library members is unimportant because
\fImc68ld\fR passes through each library's (archive) symbol
table as many times as necessary until no new
external symbols are resolved and no new references are generated.
.PP
The following options are recognized by
.IR mc68ld .
.TP \w'\fB\-u\fP\ symname\ \ 'u
.if !'mc68'' \{\
.B \-a
Produces an absolute file; gives warnings for undefined references.
Relocation information is stripped from the output object file
unless the
.B \-r
option is given. The
.B \-r
option is needed only when an absolute file should retain its
relocation information (the normal case for the 630 MTG
downloaded programs).
If neither
.BR \-a " nor " \-r
is given,
.B \-a
is assumed.
\}
.TP
.BR \-e " epsym"
Sets the default entry point address for the output file to be that of
the symbol
.IR epsym .
.if \nF \{\
This option forces the
.B \-X
option to be set. \}
.TP
.BR \-f " fill"
Sets the default fill pattern for ``holes'' within
an output section as well as initialized bss sections.
The argument \fIfill\fP is a two-byte constant.
.if 'mc68'b16' \{\
.TP
.B \-i
This option specifies that separate ``I'' and ``D'' space are to be
generated.
.B \-i
has no effect if
.B \-tv
is given.
This allows 64K of instructions and 64K of data.
'br \}
.if 'mc68'x86' \{\
.TP
.B \-i
This option specifies that separate ``I'' and ``D'' space is to be
generated.
The option
.B \-i
has no effect if
.B \-tv
is given.
This allows up to 1 MB of text and 1 MB of data.
'br \}
.ie \nD \{\
.TP
.BR \-l "x"
Searchs a library
.BI lib x .a,
where \fIx\fR is up to seven characters.
A library is searched when its name is encountered,
so the placement of a \fB\-l\fR
is significant.
By default, libraries are located in
.ie 'mc68''
.BR /lib.
.el $DMD/lib.
'br \}
.el \{\
.TP
.BI \-l x
Searches a library
.BI lib x .a,
where \fIx\fR is up to seven characters.
A library is searched when its name is encountered,
so the placement of a \fB\-l\fR
is significant.
By default, libraries are located in
.ie 'mc68'' /lib and /usr/lib.
.el $DMD/lib .
'br \}
.TP
.B \-m
Produces a map or listing of the input/output sections
on the standard output.
.TP
.BR \-o " outfile"
Produces an output object file by the name 
.IR outfile .
The name of the default object file is
.BR mc68a.out .
.TP
.B \-r
Retains 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
.I mc68ld
run.
.ie 'mc68'' The
.el \{\
Unless
.B \-a
is also given, the
\}
link editor will not complain about
unresolved references.
.TP
.B \-s
Strips line number entries and
symbol table information
from the output object file.
.if \nG \{\
.TP
.B \-t
Turns off the warning about multiply defined symbols that are
not the same size.
'br \}
.if \nC \{\
.TP
.B \-tv
Transfer vector object files are expected.
When libraries are searched with this option,
component object modules with the wrong magic
number are ignored (as are transfer vector modules
when
.B \-tv
is not given).
The default is
.I no
transfer vectors.
'br \}
.TP
.BR \-u " symname"
Enters \fIsymname\fP 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.
.\" .if \nG \{\
.\" .TP
.\" .B \-x
.\" Do not preserve local (non-.globl) symbols in the output symbol
.\" table; enter external and static symbols only.  This option saves
.\" some space in the output file.
.\" 'br \}
.if \nH \{\
.TP
.B \-z
Do not bind anything to address zero.  This option will catch null
pointers.
.TP
.B \-F
Allows the object module to be paged.
'br \}
.TP
.BR \-L " dir"
Changes the algorithm of searching for
.BI lib x .a
to look in
.IR dir
before looking in $DMD/lib.
This option is effective only if it precedes the
.B \-l
option on the command line.
.if \nG \{\
.TP
.B \-M
Outputs a message for each multiply defined external definition.
'br \}
.TP
.B \-N
Puts the data section immediately following the text in the output file.
.TP
.B \-V
Outputs a message giving information about the version of mc68ld
being used.
.TP
.BR \-VS " num"
Uses
\f2num\f1
as a decimal version stamp
identifying the
.BR mc68a.out
file that is produced.  The version
stamp is stored in the optional header.
.if \nF \{\
.TP
.B \-X
Generates a standard UNIX file header within the ``optional header''
field in the output file.
'br \}
.DT
.br
.DT
.SH FILES
.PD 0
.TP 25
.ie 'mc68'' /lib/lib\fI?\fR.a
.el $DMD/lib/lib\fI?\fR.a
libraries
.if 'mc68'' \{\
.TP 25
/usr/lib/lib?.a
libraries
\}
.TP 25
mc68a.out
output file
.PD
.SH "SEE ALSO"
dmdcc(1), mc68as(1).
.br
a.out(4), ar(4) in the \f2UNIX System V Programmer's
Reference Manual\f1.
.bp
.SH WARNINGS
Through its options and input directives, the Motorola 68000 link editor gives
users great flexibility;
however, those who use the input directives must assume
some added responsibilities.
Input directives and options should insure the following properties
for programs:
.if 'mc68'b16' \{\
.IP \- 5
C programs must have data
.RB ( .data "), bss (" .bss ),
and stack space in one 64K byte region.
Stack space
.I must
be provided.
'br \}
.IP \- 5
C defines a zero pointer as null.
A pointer to which zero has been assigned must
not point to any object.
To satisfy this, users must not place any object
at virtual address zero in the data space.
.tr ~
.IP \- 5
When the link editor is called through
.IR dmdcc (1),
a startup routine is linked with the user's program. This
routine usually calls exit(~) [see
.IR exit (3R)]
after execution of the main program. If the user
calls the link editor directly, then the user must insure that
the program always calls exit(~) rather than falling through the
end of the entry routine.
.if 'mc68'b16' \{\
.IP \- 5
Without a transfer vector, all text (code)
must reside within a single 64K-byte area.
Transfer vector function linkage removes this
restriction.
.PP
By default, the link editor takes care of these
things.
Specifying regions or defining sections with names other
than
.BR .bss ", " .data ", " .text ", or"
.B .tv
can decrease the link editor's ability to do these
automatically.
In general, users should not specify regions when the
program uses a transfer vector.
'br \}
.if \nC \{\
.SH BUGS
.I mc68ld
can not currently create transfer vector symbols.
Thus no symbols created through assignment in an
input directive will be given an entry in the transfer vector.
In particular, this means the entry point of a program
can not be redefined by assignment to
.BR main .
Unsuspecting users who create such a symbol and expect it
to be in the transfer vector receive an obscure error
message about an invalid transfer vector relocation reference.
'br \}
.PP
The
\f3\-VS\f1 \f2num\f1
option has an effect only when the
.B "\-X"
option is also selected.