gnu/usr.bin/ld/ld.1

   1 .\"
   2 .\" Copyright (c) 1993 Paul Kranenburg
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   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
  18 .\"
  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.
  29 .\"
  30 .\" $FreeBSD: src/gnu/usr.bin/ld/ld.1,v 1.21.2.4 2001/08/16 10:14:57 ru Exp $
  31 .\" $DragonFly: src/gnu/usr.bin/ld/Attic/ld.1,v 1.2 2003/06/17 04:25:46 dillon Exp $
  32 .\"
  33 .Dd October 14, 1993
  34 .Dt LD 1
  35 .Os
  36 .Sh NAME
  37 .Nm ld
  38 .Nd link editor
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Fl fMNnrSstXxz
  42 .Bk -words
  43 .Op Fl A Ar symbol-file
  44 .Op Fl assert Ar keyword
  45 .Op Fl B Ns Ar linkmode
  46 .Op Fl D Ar datasize
  47 .Op Fl d Ar c
  48 .Op Fl d Ar p
  49 .Op Fl e Ar entry
  50 .Op Fl l Ns Ar library-specifier
  51 .Op Fl L Ns Ar library-search-path
  52 .Op Fl nostdlib
  53 .Op Fl O Ar filename
  54 .Op Fl o Ar filename
  55 .Op Fl R Ns Ar record-library-search-path
  56 .Op Fl T Ar address
  57 .Op Fl u Ar symbol
  58 .Op Fl V Ar shlib-version
  59 .Op Fl y Ar symbol
  60 .Ek
  61 .Sh DESCRIPTION
  62 .Nm
  63 combines the object and archive files given on the command line into a new
  64 object file. The output object file is either an executable program, a
  65 shared object suitable for loading at run-time, or an object file that can
  66 once again be processed by
  67 .Nm .
  68 Object files and archives are processed in the order given on the command line.
  69 .Pp
  70 The options are as follows:
  71 .Pp
  72 .Bl -tag -width indent
  73 .It Fl A Ar symbol-file
  74 The the symbol-file is taken as a base for link-editing the object files
  75 on the command line.
  76 .It Fl assert Ar keyword
  77 This option is here mainly for compatibility with SunOS
  78 .Nm .
  79 Most conditions which would cause a Sun assertion to fail will
  80 currently always cause error or warning messages from
  81 .Nm .
  82 The only keyword implemented by
  83 .Nm
  84 is
  85 .Ar pure-text ,
  86 which generates a warning if a position independent object is being
  87 created and some of the files being linked are not position
  88 independent.
  89 .It Fl B Ns Ar dynamic
  90 Specifies that linking against dynamic libraries can take place. If a library
  91 specifier of the form -lx appears on the command line,
  92 .Nm
  93 searches for a library of the from libx.so.n.m
  94 (see the
  95 .Fl l
  96 option)
  97 according to the search rules in effect. If such a file can not be
  98 found a traditional archive is looked for.
  99 This options can appear anywhere on the command line and is complementary
 100 to
 101 .Fl B Ns Ar static .
 102 .It Fl B Ns Ar forcedynamic
 103 This is similar to
 104 .Fl B Ns Ar dynamic
 105 except that if no dynamic libraries are linked against,
 106 .Nm
 107 will still produce a dynamic executable.  This is useful for programs
 108 which are static but still need to load dynamic objects at runtime.
 109 .It Fl B Ns Ar static
 110 The counterpart of
 111 .Fl B Ns Ar dynamic .
 112 This option turns off dynamic linking for
 113 all library specifiers until a
 114 .Fl B Ns Ar dynamic
 115 is once again given. Any explicitly
 116 mentioned shared object encountered on the command line while this option is
 117 in effect is flagged as an error.
 118 .It Fl B Ns Ar shareable
 119 Instructs the linker to build a shared object from the object files rather
 120 than a normal executable image.
 121 .It Fl B Ns Ar symbolic
 122 This option causes all symbolic references in the output to be resolved in
 123 this link-edit session. The only remaining run-time relocation requirements are
 124 .Em base-relative
 125 relocations, ie. translation with respect to the load address. Failure to
 126 resolve any symbolic reference causes an error to be reported.
 127 .It Fl B Ns Ar forcearchive
 128 Force all members of archives to be loaded, whether or not such members
 129 contribute a definition to any plain object files. Useful for making a
 130 shared library from an archive of PIC objects without having to unpack
 131 the archive.
 132 .It Fl B Ns Ar silly
 133 Search for
 134 .Em \.sa
 135 silly archive companions of shared objects. Useful for compatibility with
 136 version 3 shared objects.
 137 .It Fl D Ar data-size
 138 Set the size of the data segment. For sanity's sake, this should be larger
 139 than the cumulative data sizes of the input files.
 140 .It Fl d Ar c
 141 Force allocation of commons even producing relocatable output.
 142 .It Fl d Ar p
 143 Force alias definitions of procedure calls in non-PIC code. Useful to
 144 obtain shareable code in the presence of run-time relocations as such
 145 calls will be re-directed through the Procedure Linkage Table (see
 146 .Xr link 5 )
 147 .It Fl e Ar entry-symbol
 148 Specifies the entry symbol for an executable.
 149 .It Fl f
 150 List the resolved paths of all the object files and libraries on the
 151 standard output, and exit.
 152 .It Fl L Ns Ar path
 153 Add
 154 .Ar path
 155 to the list of directories to search for libraries specified with the
 156 .Fl l
 157 option.
 158 .It Fl l Ns Ar lib-spec
 159 This option specifies a library to be considered for inclusion in the
 160 output. If the
 161 .Fl B Ns Ar dynamic
 162 option is in effect, a shared library of the
 163 form lib<spec>.so.m.n
 164 (where
 165 .Em m
 166 is the major, and
 167 .Em n
 168 is the minor version number, respectively)
 169 is searched for first. The
 170 library with the highest version found in the search path is selected.
 171 If no shared library is found or the
 172 .Fl B Ns Ar static
 173 options is in effect, an archive of the form lib<spec>.a is looked for in
 174 the library search path.
 175 .It Fl M
 176 Produce output about the mapping of segments of the input files and the
 177 values assigned to
 178 (global)
 179 symbols in the output file.
 180 .It Fl N
 181 Produce a
 182 .Dv OMAGIC
 183 output file.
 184 .It Fl n
 185 Produce a
 186 .Dv NMAGIC
 187 output file.
 188 .It Fl nostdlib
 189 Do not search the built-in path
 190 (usually
 191 .Dq /usr/lib )
 192 for
 193 .Fl l
 194 specified libraries.
 195 .It Fl O Ar filename
 196 Specifies the name of the output file.
 197 The file is created as
 198 .Ar filename Ns Pa .tmp
 199 and when output is complete renamed to
 200 .Ar filename .
 201 .It Fl o Ar filename
 202 Specifies the name of the output file. Defaults to
 203 .Dq Pa a.out .
 204 .It Fl Q
 205 Produce a
 206 .Dv QMAGIC
 207 .Pq Fx Ns / Ns Tn BSDi Ns -i386
 208 output file.  This is the default.
 209 .It Fl r
 210 Produce relocatable object file, suitable for another pass through
 211 .Nm .
 212 .It Fl R
 213 Record the given path within the executable for run-time library search.
 214 This only applies to dynamically linked executables.
 215 .It Fl S
 216 Strip all debugger symbols from the output.
 217 .It Fl s
 218 Strip all symbols from the output.
 219 .It Fl T
 220 Specifies the start address of the text segment, with respect to which
 221 all input files will be relocated.
 222 .It Fl t
 223 Leave a trace of the input files as they are processed.
 224 .It Fl u Ar symbol
 225 Force
 226 .Ar symbol
 227 to be marked as undefined. Useful to force loading of an archive member
 228 in the absence of any other references to that member.
 229 .It Fl V Ar version
 230 Put the given version number into the output shared library
 231 (if one is created).
 232 Useful to make shared libraries compatible with other operating
 233 systems. E.g., SunOS 4.x libraries use version number 3. Defaults to 8.
 234 .It Fl X
 235 Discard local symbols in the input files that start with the letter
 236 .Dq L
 237 .It Fl x
 238 Discard all local symbols in the input files.
 239 .It Fl y Ar symbol
 240 Trace the manipulations inflicted on
 241 .Ar symbol
 242 .It Fl Z
 243 Make a
 244 .Bx 386
 245 .Dv ZMAGIC
 246 output file.
 247 .It Fl z
 248 Make a
 249 .Nx
 250 .Dv ZMAGIC
 251 output file.
 252 .El
 253 .Sh ENVIRONMENT
 254 .Nm
 255 utilizes the following environment variables:
 256 .Bl -tag -width "LD_LIBRARY_PATH"
 257 .It Ev LD_LIBRARY_PATH
 258 This colon-separated list of directories is inserted into the search
 259 path for libraries following any directories specified via
 260 .Fl L
 261 options and preceding the built-in path.
 262 .\" .It Ev LD_NOSTD_PATH
 263 .\" When set, do not search the built-in path for libraries.
 264 .\" This is an alternative to the
 265 .\" .Fl nostdlib
 266 .\" command-line flag.
 267 .El
 268 .Sh FILES
 269 .Sh SEE ALSO
 270 .Xr ldd 1 ,
 271 .Xr rtld 1 ,
 272 .Xr link 5 ,
 273 .Xr ldconfig 8
 274 .Sh CAVEATS
 275 An entry point must now explicitly be given if the output is intended to be
 276 a normal executable program. This was not the case for the previous version of
 277 .Nm .
 278 .Sh BUGS
 279 Shared objects are not properly checked for undefined symbols.
 280 .Pp
 281 Cascading of shared object defeats the
 282 .Dq -Bstatic
 283 option.
 284 .Pp
 285 All shared objects presented to
 286 .Nm
 287 are marked for run-time loading in the output file, even if no symbols
 288 are needed from them.
 289 .Sh HISTORY
 290 A
 291 .Nm
 292 command appeared in
 293 .At v1 .
 294 The shared library model employed by
 295 .Nm
 296 appeared first in SunOS 4.0