ld.1

早期freebsd实现

.\" This source code is a product of Sun Microsystems, Inc. and is provided
.\" for unrestricted use provided that this legend is included on all tape
.\" media and as a part of the software program in whole or part.  Users
.\" may copy or modify this source code without charge, but are not authorized
.\" to license or distribute it to anyone else except as part of a product or
.\" program developed by the user.
.\"
.\" THIS PROGRAM CONTAINS SOURCE CODE COPYRIGHTED BY SUN MICROSYSTEMS, INC.
.\" SUN MICROSYSTEMS, INC., MAKES NO REPRESENTATIONS ABOUT THE SUITABLITY
.\" OF SUCH SOURCE CODE FOR ANY PURPOSE.  IT IS PROVIDED "AS IS" WITHOUT
.\" EXPRESS OR IMPLIED WARRANTY OF ANY KIND.  SUN MICROSYSTEMS, INC. DISCLAIMS
.\" ALL WARRANTIES WITH REGARD TO SUCH SOURCE CODE, INCLUDING ALL IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  IN
.\" NO EVENT SHALL SUN MICROSYSTEMS, INC. BE LIABLE FOR ANY SPECIAL, INDIRECT,
.\" INCIDENTAL, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING
.\" FROM USE OF SUCH SOURCE CODE, REGARDLESS OF THE THEORY OF LIABILITY.
.\" 
.\" This source code is provided with no support and without any obligation on
.\" the part of Sun Microsystems, Inc. to assist in its use, correction, 
.\" modification or enhancement.
.\"
.\" SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT TO THE
.\" INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY PATENTS BY THIS
.\" SOURCE CODE OR ANY PART THEREOF.
.\"
.\" Sun Microsystems, Inc.
.\" 2550 Garcia Avenue
.\" Mountain View, California 94043
.\"
.\" Copyright (c) 1991 Sun Microsystems, Inc.
.\"
.\" @(#)ld.1 1.48 90/02/02 SMI;  
.TH LD 1 "21 January 1990"
.SH NAME
ld, ld.so \- link editor, dynamic link editor
.SH SYNOPSIS
.B ld
[
.BI \-align " datum"
] [
.BI \-assert " assertion-keyword"
]
.if n .ti +0.5i
[
.BI \-A " name"
] [
.BI \-B "binding-keyword"
] [
.B \-d
] 
.if t .ti +0.5i
[
.B \-dc
]
.if n .ti +0.5i
[
.B \-dp
] [
.BI \-D " hex"
] [
.BI \-e " entry"
] [
.BI \-l x
] [
.BI \-L dir
]
.if n .ti +0.5i
[
.B \-M
] [
.B \-n
] [
.B \-N
] [
.BI \-o " name"
] [
.B \-p
]
.if t .ti +0.5i
[
.B \-r
] [
.B \-s
] [
.B \-S
]
.if n .ti +0.5i
[
.B \-t
] [
.BR \-T \|[\| text \|]
.I hex
] [
.BI \-Tdata " hex"
] [
.BI \-u " name"
]
.if n .ti +0.5i
[
.B \-x
] [
.B \-X
] [
.BI \-y sym
] 
.if t .ti +0.5i
[
.B \-z
] 
.I filename
\&.\|.\|.
.SH DESCRIPTION
.IX  "ld command"  ""  "\fLld\fP \(em link editor"
.IX  "programming tools"  "ld command"  ""  "\fLld\fP \(em link editor"
.IX  "link editor"  ""  "link editor \(em \fLld\fP"
.LP
.B ld
combines object programs to create an
.I executable
file or another object program suitable for further
.B ld
processing
(with the 
.B \-r
option).  The object modules on which 
.B ld
operates are specified on the command line, and can be:
.RS
.TP 3
\(bu
simple object files, which typically end in the
.BR .o 
suffix, and are referred to as \*(lqdot-oh\*(rq files
.TP 3
\(bu
.BR ar (1V)
library archives
.RB ( .a ),
or \*(lqlibraries\*(rq
.TP 3
\(bu
dynamically-bound, sharable object files 
.RB ( .so ),
are also referred to as \*(lqshared libraries,\*(rq
which are created from previous
.B ld
executions.
.RE
.LP
Unless an output file is specified,
.B ld
produces a file named
.BR a.out .
This file contains the object files given as input,
appropriately combined to form an executable file.
.SH OPTIONS
When linking debugging or profiling objects, include the
.B \-g
or
.B \-pg
option (see
.BR cc (1V)),
as appropriate, in the
.B ld
command.
.LP
Options should appear before
filenames, except for abbreviated library
names specified with
.B \-l
options, and some binding control options specified by
.BR \-B 
(which can appear anywhere in the line).
.TP 
.BI \-align " datum"
Force the global uninitialized data symbol
.I datum
(usually a 
.SM FORTRAN 
common block) to be page-aligned.  Increase its size to a whole number of
pages, and place its first byte at the start of a page.
.TP
.BI \-assert " assertion-keyword"
Check an assertion about the link editing being performed.  The assertion
desired is specified by the
.I assertion-keyword
string.
.B ld
is silent if the assertion holds, else it yields a diagnostic and aborts.
Valid
.IR assertion-keyword 's
and their interpretations are:
.RS
.RS
.TP 15
.B definitions
If the resulting program were run now, there would be no run-time undefined 
symbol diagnostics.  This assertion is set by default.
.TP
.B nodefinitions
Permit the successful linking of a program with
unresolved references.
.TP
.B nosymbolic
There are no symbolic relocation items remaining to be resolved.
.TP
.B pure-text
The resulting load has no relocation items remaining in its text.
.RE
.RE
.TP
.BI \-A " name"
Incremental loading: linking is to be done in a manner so that the
resulting object may be read into an already executing program. 
.I name
is the name of a file whose symbol table is taken as a basis
on which to define additional symbols.
Only newly linked material is 
entered into the text and data portions of 
.BR a.out ,
but the new symbol table will reflect all symbols defined before and after
the incremental load. 
This argument must appear before any other object
file in the argument list.
One or both of the 
.B \-T
options may be used as well, and will be taken to mean that the newly linked
segment will commence at the corresponding addresses (which must be a multiple
of the page size). 
The default value is the old value of 
.BR _end .
.br
.ne 10
.TP
.BI \-B binding-keyword
Specify allowed binding times for the items which follow.  Allowed values of
.I binding-keyword
are:
.RS
.TP 15
.B dynamic
Allow dynamic binding: do not resolve symbolic references, allow creation of
run-time symbol and relocation environment. 
.B -Bdynamic
is the default.
When
.B \-Bdynamic
is in effect, all sharable objects encountered until a 
succeeding
.B \-Bstatic
may be added dynamically to the object being 
linked.  Non-sharable objects are bound statically.
.TP
.B nosymbolic
Do not perform symbolic relocation, even if other options imply it.
.TP
.B static
Bind statically.  Opposite of
.BR \-Bdynamic .
Implied when either
.B \-n
or
.B \-N
is specified.  Influences handling of all objects
following its specification on a command line until the next
.BR \-Bdynamic .
.TP
.B symbolic
Force symbolic relocation.  Normally implied if an entry point has been
specified with
.BR \-e ,
or if dynamic loading is in effect.
.RE
.TP 
.B  \-d
Force common storage for uninitialized variables and other
common symbols to be allocated in the current 
.B ld
run, even when the
.B \-r
flag is present (which would otherwise postpone this binding
until the final linking phase).
.TP
.B \-dc
Do
.BR \-d ,
but also copy initialized data referenced by this program
from shared objects.
.TP
.B \-dp
Force an alias definition of undefined procedure entry points. 
Used with dynamic binding to improve sharing and the locality
of run-time relocations.
.TP
.BI \-D " hex"
Pad the data segment with zero-valued bytes to make it
.I hex
bytes long.
.TP
.BI \-e " entry"
Define the entry point: the
.I entry
argument is made the 
name of the entry point of the loaded program.  Implies
.BR \-Bsymbolic .
.TP 
.BI \-l x\|\fR[ . v\|\fR] 
This option is an abbreviation for the library name
.BI lib x .a\fR,
where
.I x
is a string.  
.B ld
searches for libraries first in any directories specified with
.B \-L
options, then in the standard directories
.BR /lib ,
.BR /usr/lib ,
and
.BR /usr/local/lib .
A library is searched when its name is encountered, 
so the placement of a
.B \-l
is significant.  If a dynamically loadable object is found, and 
.B \-Bdynamic
is in effect at that point on the command line, then
.B ld
prepares to access the object for relocation at run-time.  In such a
case, the optional
.BI . v
suffix can be used to indicate a specific library version.
.br
.ne 5
.TP
.BI \-L dir
Add
.I dir
to the list of directories in which to search for libraries.
Directories specified with 
.B \-L
are searched before the standard directories,
.BR /lib ,
.BR /usr/lib ,
and
.BR /usr/local/lib .
When building a program in which one or more objects are loaded when
.B -Bdynamic
is in effect, those directories specified by 
.B \-L
options will be \*(lqremembered\*(rq for use at execution time.  This permits
the construction of software that uses shared objects as libraries not 
residing
in the standard locations and avoids requiring the specification of 
the
.SB LD_LIBRARY_PATH
environment variable
in order to execute such software.  Note that such directories are
retained in
.I exactly
the form specified in the option, which means that relative directory
specifications (i.e., not beginning with \*(lq/\*(rq) will be evaluated
relative to the current directory when the program is
.IR run ,
not just during the operation of
.BR ld .
.TP
.B \-M
Produce a primitive load map, listing the names of the files
which will be loaded.
.TP 
.B  \-n
Arrange (by giving the output file a 0410 \*(lqmagic number\*(rq)
that when the output
file is executed, the text portion will be read-only with the data areas
placed at the beginning of the next address boundary following the end of
the text.  Implies
.BR \-Bstatic .
.TP
.B \-N
Do not make the text portion read-only.  (Use \*(lqmagic number\*(rq 0407.)
Implies
.BR \-Bstatic .
.TP 
.BI  \-o " name"
.I name
is made the name of the
.B ld
output file, instead of
.BR a.out .
.br
.ne 3
.TP 
.B \-p
Arrange for the data segment to begin on a page boundary, even if the text is 
not shared (with the
.B \-N
option).
.TP 
.B  \-r
Generate relocation bits in the output file
so that it can be the subject of another
.B ld
run.  This flag also prevents final definitions from being given to common
symbols, and suppresses the \*(lqundefined symbol\*(rq diagnostics.
.TP 
.B \-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
.BR strip (1).
.TP
.B \-S
Strip the output by removing all symbols except locals and globals.
.TP
.B \-t
Trace: display the name of each file as it is processed.
.br
.ne 5
.TP
.BR \-T \|[\| text \|]\| \fIhex\fR
Start the text segment at location
.IR hex .  
Specifying 
.B \-T
is the same as using the
.B \-Ttext
option.
.TP
.BI \-Tdata " hex"
Start the data segment at location
.IR hex .
This option is only of use
to programmers wishing to write code for 
.SM PROM\s0s,
since the resulting code cannot be executed by the system.
.TP 
.BI  \-u " name"
Enter
.I name
as an undefined symbol.
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
Preserve only global (non-\fB.globl\fP) symbols in the output symbol
table; only enter external symbols.
This option saves some space in the output file.
.TP 
.B \-X
Record local symbols, except for those whose names begin with
.BR L .
This option is used by
.B cc
to discard internally generated labels while
retaining symbols local to routines.
.TP
.BI \-y sym
Display each file in which
.I 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
.I sym
with an
.RB ` _ ',
as external C,
.SM FORTRAN
and Pascal variables begin
with underscores.
.TP
.B \-z
Arrange for the process demand paged from the resulting executable
file (0413 \*(lqmagic number\*(rq).  This is the default.
Results in a (32-byte) header on the output file followed by
text and data segments, each of which has a multiple of page-size
bytes (being padded out with
null
characters in the file if necessary).
With this format the first few
.SM BSS
segment symbols may actually end up
in the data segment;
this is to avoid wasting the space resulting from rounding the data 
segment size.  Implies
.BR \-Bdynamic .
.SH USAGE
.SS Command Line Processing
.LP
In general, options should appear ahead of the list of files to
process.  Unless otherwise specified, the
effect of an option covers all of
.B ld
operations, independent
of that option's placement on the command line.  Exceptions to this
rule include some of the binding control options specified by
.RB ` \-B '