296 lines
9.1 KiB
Groff
296 lines
9.1 KiB
Groff
.\"
|
|
.\" Copyright (c) 1993 Paul Kranenburg
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by Paul Kranenburg.
|
|
.\" 3. The name of the author may not be used to endorse or promote products
|
|
.\" derived from this software without specific prior written permission
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
|
|
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
|
|
.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
|
|
.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
|
|
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
|
|
.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
|
|
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
|
|
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
|
|
.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd October 14, 1993
|
|
.Dt LD 1
|
|
.Os
|
|
.Sh NAME
|
|
.Nm ld
|
|
.Nd link editor
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl fMNnrSstXxz
|
|
.Bk -words
|
|
.Op Fl A Ar symbol-file
|
|
.Op Fl assert Ar keyword
|
|
.Op Fl B Ns Ar linkmode
|
|
.Op Fl D Ar datasize
|
|
.Op Fl d Ar c
|
|
.Op Fl d Ar p
|
|
.Op Fl e Ar entry
|
|
.Op Fl l Ns Ar library-specifier
|
|
.Op Fl L Ns Ar library-search-path
|
|
.Op Fl nostdlib
|
|
.Op Fl O Ar filename
|
|
.Op Fl o Ar filename
|
|
.Op Fl R Ns Ar record-library-search-path
|
|
.Op Fl T Ar address
|
|
.Op Fl u Ar symbol
|
|
.Op Fl V Ar shlib-version
|
|
.Op Fl y Ar symbol
|
|
.Ek
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
combines the object and archive files given on the command line into a new
|
|
object file. The output object file is either an executable program, a
|
|
shared object suitable for loading at run-time, or an object file that can
|
|
once again be processed by
|
|
.Nm .
|
|
Object files and archives are processed in the order given on the command line.
|
|
.Pp
|
|
The options are as follows:
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Fl A Ar symbol-file
|
|
The the symbol-file is taken as a base for link-editing the object files
|
|
on the command line.
|
|
.It Fl assert Ar keyword
|
|
This option is here mainly for compatibility with SunOS
|
|
.Nm .
|
|
Most conditions which would cause a Sun assertion to fail will
|
|
currently always cause error or warning messages from
|
|
.Nm .
|
|
The only keyword implemented by
|
|
.Nm
|
|
is
|
|
.Ar pure-text ,
|
|
which generates a warning if a position independent object is being
|
|
created and some of the files being linked are not position
|
|
independent.
|
|
.It Fl B Ns Ar dynamic
|
|
Specifies that linking against dynamic libraries can take place. If a library
|
|
specifier of the form -lx appears on the command line,
|
|
.Nm
|
|
searches for a library of the from libx.so.n.m
|
|
(see the
|
|
.Fl l
|
|
option)
|
|
according to the search rules in effect. If such a file can not be
|
|
found a traditional archive is looked for.
|
|
This options can appear anywhere on the command line and is complementary
|
|
to
|
|
.Fl B Ns Ar static .
|
|
.It Fl B Ns Ar forcedynamic
|
|
This is similar to
|
|
.Fl B Ns Ar dynamic
|
|
except that if no dynamic libraries are linked against,
|
|
.Nm
|
|
will still produce a dynamic executable. This is useful for programs
|
|
which are static but still need to load dynamic objects at runtime.
|
|
.It Fl B Ns Ar static
|
|
The counterpart of
|
|
.Fl B Ns Ar dynamic .
|
|
This option turns off dynamic linking for
|
|
all library specifiers until a
|
|
.Fl B Ns Ar dynamic
|
|
is once again given. Any explicitly
|
|
mentioned shared object encountered on the command line while this option is
|
|
in effect is flagged as an error.
|
|
.It Fl B Ns Ar shareable
|
|
Instructs the linker to build a shared object from the object files rather
|
|
than a normal executable image.
|
|
.It Fl B Ns Ar symbolic
|
|
This option causes all symbolic references in the output to be resolved in
|
|
this link-edit session. The only remaining run-time relocation requirements are
|
|
.Em base-relative
|
|
relocations, ie. translation with respect to the load address. Failure to
|
|
resolve any symbolic reference causes an error to be reported.
|
|
.It Fl B Ns Ar forcearchive
|
|
Force all members of archives to be loaded, whether or not such members
|
|
contribute a definition to any plain object files. Useful for making a
|
|
shared library from an archive of PIC objects without having to unpack
|
|
the archive.
|
|
.It Fl B Ns Ar silly
|
|
Search for
|
|
.Em \.sa
|
|
silly archive companions of shared objects. Useful for compatibility with
|
|
version 3 shared objects.
|
|
.It Fl D Ar data-size
|
|
Set the size of the data segment. For sanity's sake, this should be larger
|
|
than the cumulative data sizes of the input files.
|
|
.It Fl d Ar c
|
|
Force allocation of commons even producing relocatable output.
|
|
.It Fl d Ar p
|
|
Force alias definitions of procedure calls in non-PIC code. Useful to
|
|
obtain shareable code in the presence of run-time relocations as such
|
|
calls will be re-directed through the Procedure Linkage Table (see
|
|
.Xr link 5 )
|
|
.It Fl e Ar entry-symbol
|
|
Specifies the entry symbol for an executable.
|
|
.It Fl f
|
|
List the resolved paths of all the object files and libraries on the
|
|
standard output, and exit.
|
|
.It Fl L Ns Ar path
|
|
Add
|
|
.Ar path
|
|
to the list of directories to search for libraries specified with the
|
|
.Fl l
|
|
option.
|
|
.It Fl l Ns Ar lib-spec
|
|
This option specifies a library to be considered for inclusion in the
|
|
output. If the
|
|
.Fl B Ns Ar dynamic
|
|
option is in effect, a shared library of the
|
|
form lib<spec>.so.m.n
|
|
(where
|
|
.Em m
|
|
is the major, and
|
|
.Em n
|
|
is the minor version number, respectively)
|
|
is searched for first. The
|
|
library with the highest version found in the search path is selected.
|
|
If no shared library is found or the
|
|
.Fl B Ns Ar static
|
|
options is in effect, an archive of the form lib<spec>.a is looked for in
|
|
the library search path.
|
|
.It Fl M
|
|
Produce output about the mapping of segments of the input files and the
|
|
values assigned to
|
|
(global)
|
|
symbols in the output file.
|
|
.It Fl N
|
|
Produce a
|
|
.Dv OMAGIC
|
|
output file.
|
|
.It Fl n
|
|
Produce a
|
|
.Dv NMAGIC
|
|
output file.
|
|
.It Fl nostdlib
|
|
Do not search the built-in path
|
|
(usually
|
|
.Dq /usr/lib )
|
|
for
|
|
.Fl l
|
|
specified libraries.
|
|
.It Fl O Ar filename
|
|
Specifies the name of the output file.
|
|
The file is created as
|
|
.Ar filename Ns Pa .tmp
|
|
and when output is complete renamed to
|
|
.Ar filename .
|
|
.It Fl o Ar filename
|
|
Specifies the name of the output file. Defaults to
|
|
.Dq Pa a.out .
|
|
.It Fl Q
|
|
Produce a
|
|
.Dv QMAGIC
|
|
.Pq Fx Ns / Ns Tn BSDi Ns -i386
|
|
output file. This is the default.
|
|
.It Fl r
|
|
Produce relocatable object file, suitable for another pass through
|
|
.Nm .
|
|
.It Fl R
|
|
Record the given path within the executable for run-time library search.
|
|
This only applies to dynamically linked executables.
|
|
.It Fl S
|
|
Strip all debugger symbols from the output.
|
|
.It Fl s
|
|
Strip all symbols from the output.
|
|
.It Fl T
|
|
Specifies the start address of the text segment, with respect to which
|
|
all input files will be relocated.
|
|
.It Fl t
|
|
Leave a trace of the input files as they are processed.
|
|
.It Fl u Ar symbol
|
|
Force
|
|
.Ar symbol
|
|
to be marked as undefined. Useful to force loading of an archive member
|
|
in the absence of any other references to that member.
|
|
.It Fl V Ar version
|
|
Put the given version number into the output shared library
|
|
(if one is created).
|
|
Useful to make shared libraries compatible with other operating
|
|
systems. E.g., SunOS 4.x libraries use version number 3. Defaults to 8.
|
|
.It Fl X
|
|
Discard local symbols in the input files that start with the letter
|
|
.Dq L
|
|
.It Fl x
|
|
Discard all local symbols in the input files.
|
|
.It Fl y Ar symbol
|
|
Trace the manipulations inflicted on
|
|
.Ar symbol
|
|
.It Fl Z
|
|
Make a
|
|
.Bx 386
|
|
.Dv ZMAGIC
|
|
output file.
|
|
.It Fl z
|
|
Make a
|
|
.Nx
|
|
.Dv ZMAGIC
|
|
output file.
|
|
.El
|
|
.Sh ENVIRONMENT
|
|
.Nm
|
|
utilizes the following environment variables:
|
|
.Bl -tag -width "LD_LIBRARY_PATH"
|
|
.It Ev LD_LIBRARY_PATH
|
|
This colon-separated list of directories is inserted into the search
|
|
path for libraries following any directories specified via
|
|
.Fl L
|
|
options and preceding the built-in path.
|
|
.\" .It Ev LD_NOSTD_PATH
|
|
.\" When set, do not search the built-in path for libraries.
|
|
.\" This is an alternative to the
|
|
.\" .Fl nostdlib
|
|
.\" command-line flag.
|
|
.El
|
|
.Sh FILES
|
|
.Sh SEE ALSO
|
|
.Xr ldd 1 ,
|
|
.Xr rtld 1 ,
|
|
.Xr link 5 ,
|
|
.Xr ldconfig 8
|
|
.Sh CAVEATS
|
|
An entry point must now explicitly be given if the output is intended to be
|
|
a normal executable program. This was not the case for the previous version of
|
|
.Nm .
|
|
.Sh BUGS
|
|
Shared objects are not properly checked for undefined symbols.
|
|
.Pp
|
|
Cascading of shared object defeats the
|
|
.Dq -Bstatic
|
|
option.
|
|
.Pp
|
|
All shared objects presented to
|
|
.Nm
|
|
are marked for run-time loading in the output file, even if no symbols
|
|
are needed from them.
|
|
.Sh HISTORY
|
|
A
|
|
.Nm
|
|
command appeared in
|
|
.At v1 .
|
|
The shared library model employed by
|
|
.Nm
|
|
appeared first in SunOS 4.0
|