2 .\" Copyright (c) 1993 Paul Kranenburg
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. All advertising materials mentioning features or use of this software
14 .\" must display the following acknowledgement:
15 .\" This product includes software developed by Paul Kranenburg.
16 .\" 3. The name of the author may not be used to endorse or promote products
17 .\" derived from this software without specific prior written permission
19 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
20 .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
21 .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
22 .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
23 .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
24 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25 .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
26 .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
27 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
28 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 .\" $FreeBSD: src/gnu/usr.bin/ld/ld.1,v 1.21.2.4 2001/08/16 10:14:57 ru Exp $
42 .Op Fl A Ar symbol-file
43 .Op Fl assert Ar keyword
44 .Op Fl B Ns Ar linkmode
49 .Op Fl l Ns Ar library-specifier
50 .Op Fl L Ns Ar library-search-path
54 .Op Fl R Ns Ar record-library-search-path
57 .Op Fl V Ar shlib-version
62 combines the object and archive files given on the command line into a new
63 object file. The output object file is either an executable program, a
64 shared object suitable for loading at run-time, or an object file that can
65 once again be processed by
67 Object files and archives are processed in the order given on the command line.
69 The options are as follows:
71 .Bl -tag -width indent
72 .It Fl A Ar symbol-file
73 The the symbol-file is taken as a base for link-editing the object files
75 .It Fl assert Ar keyword
76 This option is here mainly for compatibility with SunOS
78 Most conditions which would cause a Sun assertion to fail will
79 currently always cause error or warning messages from
81 The only keyword implemented by
85 which generates a warning if a position independent object is being
86 created and some of the files being linked are not position
88 .It Fl B Ns Ar dynamic
89 Specifies that linking against dynamic libraries can take place. If a library
90 specifier of the form -lx appears on the command line,
92 searches for a library of the from libx.so.n.m
96 according to the search rules in effect. If such a file can not be
97 found a traditional archive is looked for.
98 This options can appear anywhere on the command line and is complementary
101 .It Fl B Ns Ar forcedynamic
104 except that if no dynamic libraries are linked against,
106 will still produce a dynamic executable. This is useful for programs
107 which are static but still need to load dynamic objects at runtime.
108 .It Fl B Ns Ar static
110 .Fl B Ns Ar dynamic .
111 This option turns off dynamic linking for
112 all library specifiers until a
114 is once again given. Any explicitly
115 mentioned shared object encountered on the command line while this option is
116 in effect is flagged as an error.
117 .It Fl B Ns Ar shareable
118 Instructs the linker to build a shared object from the object files rather
119 than a normal executable image.
120 .It Fl B Ns Ar symbolic
121 This option causes all symbolic references in the output to be resolved in
122 this link-edit session. The only remaining run-time relocation requirements are
124 relocations, ie. translation with respect to the load address. Failure to
125 resolve any symbolic reference causes an error to be reported.
126 .It Fl B Ns Ar forcearchive
127 Force all members of archives to be loaded, whether or not such members
128 contribute a definition to any plain object files. Useful for making a
129 shared library from an archive of PIC objects without having to unpack
134 silly archive companions of shared objects. Useful for compatibility with
135 version 3 shared objects.
136 .It Fl D Ar data-size
137 Set the size of the data segment. For sanity's sake, this should be larger
138 than the cumulative data sizes of the input files.
140 Force allocation of commons even producing relocatable output.
142 Force alias definitions of procedure calls in non-PIC code. Useful to
143 obtain shareable code in the presence of run-time relocations as such
144 calls will be re-directed through the Procedure Linkage Table (see
146 .It Fl e Ar entry-symbol
147 Specifies the entry symbol for an executable.
149 List the resolved paths of all the object files and libraries on the
150 standard output, and exit.
154 to the list of directories to search for libraries specified with the
157 .It Fl l Ns Ar lib-spec
158 This option specifies a library to be considered for inclusion in the
161 option is in effect, a shared library of the
162 form lib<spec>.so.m.n
167 is the minor version number, respectively)
168 is searched for first. The
169 library with the highest version found in the search path is selected.
170 If no shared library is found or the
172 options is in effect, an archive of the form lib<spec>.a is looked for in
173 the library search path.
175 Produce output about the mapping of segments of the input files and the
178 symbols in the output file.
188 Do not search the built-in path
195 Specifies the name of the output file.
196 The file is created as
197 .Ar filename Ns Pa .tmp
198 and when output is complete renamed to
201 Specifies the name of the output file. Defaults to
206 .Pq Fx Ns / Ns Tn BSDi Ns -i386
207 output file. This is the default.
209 Produce relocatable object file, suitable for another pass through
212 Record the given path within the executable for run-time library search.
213 This only applies to dynamically linked executables.
215 Strip all debugger symbols from the output.
217 Strip all symbols from the output.
219 Specifies the start address of the text segment, with respect to which
220 all input files will be relocated.
222 Leave a trace of the input files as they are processed.
226 to be marked as undefined. Useful to force loading of an archive member
227 in the absence of any other references to that member.
229 Put the given version number into the output shared library
231 Useful to make shared libraries compatible with other operating
232 systems. E.g., SunOS 4.x libraries use version number 3. Defaults to 8.
234 Discard local symbols in the input files that start with the letter
237 Discard all local symbols in the input files.
239 Trace the manipulations inflicted on
254 utilizes the following environment variables:
255 .Bl -tag -width "LD_LIBRARY_PATH"
256 .It Ev LD_LIBRARY_PATH
257 This colon-separated list of directories is inserted into the search
258 path for libraries following any directories specified via
260 options and preceding the built-in path.
261 .\" .It Ev LD_NOSTD_PATH
262 .\" When set, do not search the built-in path for libraries.
263 .\" This is an alternative to the
265 .\" command-line flag.
274 An entry point must now explicitly be given if the output is intended to be
275 a normal executable program. This was not the case for the previous version of
278 Shared objects are not properly checked for undefined symbols.
280 Cascading of shared object defeats the
284 All shared objects presented to
286 are marked for run-time loading in the output file, even if no symbols
287 are needed from them.
293 The shared library model employed by
295 appeared first in SunOS 4.0