Return to mc68ld.1 CVS log

Up to [Research Unix] / researchv10dc / 630 / man / src / u_man / man1

Annotation of researchv10dc/630/man/src/u_man/man1/mc68ld.1, revision 1.1

1.1     ! root        1: .\"    @(#) ld.1:      2.3 11/17/83
        !             2: .ds ZZ DEVELOPMENT PACKAGE
        !             3: .TH MC68LD 1 "630 MTG" 
        !             4: .SH NAME
        !             5: mc68ld \- link editor for MC68000 object files
        !             6: .SH SYNOPSIS
        !             7: \f3mc68ld [\f1 options \f3]\f1 file-names
        !             8: .SH DESCRIPTION
        !             9: The
        !            10: .I mc68ld
        !            11: command
        !            12: combines several
        !            13: object files into one,
        !            14: performs relocation,
        !            15: resolves external symbols,
        !            16: and supports symbol table information
        !            17: for symbolic debugging.
        !            18: In the simplest case, the names of several object
        !            19: programs are given, and
        !            20: .I mc68ld
        !            21: combines them, producing
        !            22: an object module that can either be executed or
        !            23: used as input for a subsequent
        !            24: .I mc68ld
        !            25: run.
        !            26: The output of
        !            27: .I mc68ld
        !            28: is left in
        !            29: .BR mc68a.out .
        !            30: This file is executable
        !            31: if no errors occurred during the load.
        !            32: If any input file,
        !            33: .IR file-name ,
        !            34: is not an object file,
        !            35: .I mc68ld
        !            36: assumes it is either a text file containing link editor directives
        !            37: or an archive library.
        !            38: (See
        !            39: the \f2Link Editor\f1 in the \f2UNIX System V Support Tools
        !            40: Guide\f1 for a discussion of input directives.)
        !            41: .PP
        !            42: If any argument is a library, it is searched exactly once
        !            43: at the point it is encountered in the argument list.
        !            44: Only those routines defining an unresolved external
        !            45: reference are loaded.
        !            46: The order of library members is unimportant because
        !            47: \fImc68ld\fR passes through each library's (archive) symbol
        !            48: table as many times as necessary until no new
        !            49: external symbols are resolved and no new references are generated.
        !            50: .PP
        !            51: The following options are recognized by
        !            52: .IR mc68ld .
        !            53: .TP \w'\fB\-u\fP\ symname\ \ 'u
        !            54: .if !'mc68'' \{\
        !            55: .B \-a
        !            56: Produces an absolute file; gives warnings for undefined references.
        !            57: Relocation information is stripped from the output object file
        !            58: unless the
        !            59: .B \-r
        !            60: option is given. The
        !            61: .B \-r
        !            62: option is needed only when an absolute file should retain its
        !            63: relocation information (the normal case for the 630 MTG
        !            64: downloaded programs).
        !            65: If neither
        !            66: .BR \-a " nor " \-r
        !            67: is given,
        !            68: .B \-a
        !            69: is assumed.
        !            70: \}
        !            71: .TP
        !            72: .BR \-e " epsym"
        !            73: Sets the default entry point address for the output file to be that of
        !            74: the symbol
        !            75: .IR epsym .
        !            76: .if \nF \{\
        !            77: This option forces the
        !            78: .B \-X
        !            79: option to be set. \}
        !            80: .TP
        !            81: .BR \-f " fill"
        !            82: Sets the default fill pattern for ``holes'' within
        !            83: an output section as well as initialized bss sections.
        !            84: The argument \fIfill\fP is a two-byte constant.
        !            85: .if 'mc68'b16' \{\
        !            86: .TP
        !            87: .B \-i
        !            88: This option specifies that separate ``I'' and ``D'' space are to be
        !            89: generated.
        !            90: .B \-i
        !            91: has no effect if
        !            92: .B \-tv
        !            93: is given.
        !            94: This allows 64K of instructions and 64K of data.
        !            95: 'br \}
        !            96: .if 'mc68'x86' \{\
        !            97: .TP
        !            98: .B \-i
        !            99: This option specifies that separate ``I'' and ``D'' space is to be
        !           100: generated.
        !           101: The option
        !           102: .B \-i
        !           103: has no effect if
        !           104: .B \-tv
        !           105: is given.
        !           106: This allows up to 1 MB of text and 1 MB of data.
        !           107: 'br \}
        !           108: .ie \nD \{\
        !           109: .TP
        !           110: .BR \-l "x"
        !           111: Searchs a library
        !           112: .BI lib x .a,
        !           113: where \fIx\fR is up to seven characters.
        !           114: A library is searched when its name is encountered,
        !           115: so the placement of a \fB\-l\fR
        !           116: is significant.
        !           117: By default, libraries are located in
        !           118: .ie 'mc68''
        !           119: .BR /lib.
        !           120: .el $DMD/lib.
        !           121: 'br \}
        !           122: .el \{\
        !           123: .TP
        !           124: .BI \-l x
        !           125: Searches a library
        !           126: .BI lib x .a,
        !           127: where \fIx\fR is up to seven characters.
        !           128: A library is searched when its name is encountered,
        !           129: so the placement of a \fB\-l\fR
        !           130: is significant.
        !           131: By default, libraries are located in
        !           132: .ie 'mc68'' /lib and /usr/lib.
        !           133: .el $DMD/lib .
        !           134: 'br \}
        !           135: .TP
        !           136: .B \-m
        !           137: Produces a map or listing of the input/output sections
        !           138: on the standard output.
        !           139: .TP
        !           140: .BR \-o " outfile"
        !           141: Produces an output object file by the name 
        !           142: .IR outfile .
        !           143: The name of the default object file is
        !           144: .BR mc68a.out .
        !           145: .TP
        !           146: .B \-r
        !           147: Retains relocation entries in
        !           148: the output object file.
        !           149: Relocation entries must be saved if the 
        !           150: output file is to become an input file in a
        !           151: subsequent
        !           152: .I mc68ld
        !           153: run.
        !           154: .ie 'mc68'' The
        !           155: .el \{\
        !           156: Unless
        !           157: .B \-a
        !           158: is also given, the
        !           159: \}
        !           160: link editor will not complain about
        !           161: unresolved references.
        !           162: .TP
        !           163: .B \-s
        !           164: Strips line number entries and
        !           165: symbol table information
        !           166: from the output object file.
        !           167: .if \nG \{\
        !           168: .TP
        !           169: .B \-t
        !           170: Turns off the warning about multiply defined symbols that are
        !           171: not the same size.
        !           172: 'br \}
        !           173: .if \nC \{\
        !           174: .TP
        !           175: .B \-tv
        !           176: Transfer vector object files are expected.
        !           177: When libraries are searched with this option,
        !           178: component object modules with the wrong magic
        !           179: number are ignored (as are transfer vector modules
        !           180: when
        !           181: .B \-tv
        !           182: is not given).
        !           183: The default is
        !           184: .I no
        !           185: transfer vectors.
        !           186: 'br \}
        !           187: .TP
        !           188: .BR \-u " symname"
        !           189: Enters \fIsymname\fP as an undefined symbol
        !           190: in the symbol table.
        !           191: This is useful
        !           192: for loading entirely from a library, since initially the symbol
        !           193: table is empty and an unresolved reference is needed
        !           194: to force the loading of the first routine.
        !           195: .\" .if \nG \{\
        !           196: .\" .TP
        !           197: .\" .B \-x
        !           198: .\" Do not preserve local (non-.globl) symbols in the output symbol
        !           199: .\" table; enter external and static symbols only.  This option saves
        !           200: .\" some space in the output file.
        !           201: .\" 'br \}
        !           202: .if \nH \{\
        !           203: .TP
        !           204: .B \-z
        !           205: Do not bind anything to address zero.  This option will catch null
        !           206: pointers.
        !           207: .TP
        !           208: .B \-F
        !           209: Allows the object module to be paged.
        !           210: 'br \}
        !           211: .TP
        !           212: .BR \-L " dir"
        !           213: Changes the algorithm of searching for
        !           214: .BI lib x .a
        !           215: to look in
        !           216: .IR dir
        !           217: before looking in $DMD/lib.
        !           218: This option is effective only if it precedes the
        !           219: .B \-l
        !           220: option on the command line.
        !           221: .if \nG \{\
        !           222: .TP
        !           223: .B \-M
        !           224: Outputs a message for each multiply defined external definition.
        !           225: 'br \}
        !           226: .TP
        !           227: .B \-N
        !           228: Puts the data section immediately following the text in the output file.
        !           229: .TP
        !           230: .B \-V
        !           231: Outputs a message giving information about the version of mc68ld
        !           232: being used.
        !           233: .TP
        !           234: .BR \-VS " num"
        !           235: Uses
        !           236: \f2num\f1
        !           237: as a decimal version stamp
        !           238: identifying the
        !           239: .BR mc68a.out
        !           240: file that is produced.  The version
        !           241: stamp is stored in the optional header.
        !           242: .if \nF \{\
        !           243: .TP
        !           244: .B \-X
        !           245: Generates a standard UNIX file header within the ``optional header''
        !           246: field in the output file.
        !           247: 'br \}
        !           248: .DT
        !           249: .br
        !           250: .DT
        !           251: .SH FILES
        !           252: .PD 0
        !           253: .TP 25
        !           254: .ie 'mc68'' /lib/lib\fI?\fR.a
        !           255: .el $DMD/lib/lib\fI?\fR.a
        !           256: libraries
        !           257: .if 'mc68'' \{\
        !           258: .TP 25
        !           259: /usr/lib/lib?.a
        !           260: libraries
        !           261: \}
        !           262: .TP 25
        !           263: mc68a.out
        !           264: output file
        !           265: .PD
        !           266: .SH "SEE ALSO"
        !           267: dmdcc(1), mc68as(1).
        !           268: .br
        !           269: a.out(4), ar(4) in the \f2UNIX System V Programmer's
        !           270: Reference Manual\f1.
        !           271: .bp
        !           272: .SH WARNINGS
        !           273: Through its options and input directives, the Motorola 68000 link editor gives
        !           274: users great flexibility;
        !           275: however, those who use the input directives must assume
        !           276: some added responsibilities.
        !           277: Input directives and options should insure the following properties
        !           278: for programs:
        !           279: .if 'mc68'b16' \{\
        !           280: .IP \- 5
        !           281: C programs must have data
        !           282: .RB ( .data "), bss (" .bss ),
        !           283: and stack space in one 64K byte region.
        !           284: Stack space
        !           285: .I must
        !           286: be provided.
        !           287: 'br \}
        !           288: .IP \- 5
        !           289: C defines a zero pointer as null.
        !           290: A pointer to which zero has been assigned must
        !           291: not point to any object.
        !           292: To satisfy this, users must not place any object
        !           293: at virtual address zero in the data space.
        !           294: .tr ~
        !           295: .IP \- 5
        !           296: When the link editor is called through
        !           297: .IR dmdcc (1),
        !           298: a startup routine is linked with the user's program. This
        !           299: routine usually calls exit(~) [see
        !           300: .IR exit (3R)]
        !           301: after execution of the main program. If the user
        !           302: calls the link editor directly, then the user must insure that
        !           303: the program always calls exit(~) rather than falling through the
        !           304: end of the entry routine.
        !           305: .if 'mc68'b16' \{\
        !           306: .IP \- 5
        !           307: Without a transfer vector, all text (code)
        !           308: must reside within a single 64K-byte area.
        !           309: Transfer vector function linkage removes this
        !           310: restriction.
        !           311: .PP
        !           312: By default, the link editor takes care of these
        !           313: things.
        !           314: Specifying regions or defining sections with names other
        !           315: than
        !           316: .BR .bss ", " .data ", " .text ", or"
        !           317: .B .tv
        !           318: can decrease the link editor's ability to do these
        !           319: automatically.
        !           320: In general, users should not specify regions when the
        !           321: program uses a transfer vector.
        !           322: 'br \}
        !           323: .if \nC \{\
        !           324: .SH BUGS
        !           325: .I mc68ld
        !           326: can not currently create transfer vector symbols.
        !           327: Thus no symbols created through assignment in an
        !           328: input directive will be given an entry in the transfer vector.
        !           329: In particular, this means the entry point of a program
        !           330: can not be redefined by assignment to
        !           331: .BR main .
        !           332: Unsuspecting users who create such a symbol and expect it
        !           333: to be in the transfer vector receive an obscure error
        !           334: message about an invalid transfer vector relocation reference.
        !           335: 'br \}
        !           336: .PP
        !           337: The
        !           338: \f3\-VS\f1 \f2num\f1
        !           339: option has an effect only when the
        !           340: .B "\-X"
        !           341: option is also selected.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.