gnu/usr.bin/ld/ld.1aout

   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.1aout,v 1.21.2.3 2001/08/16 10:25:06 ru Exp $
  31 .\"
  32 .Dd October 14, 1993
  33 .Dt LD 1
  34 .Os
  35 .Sh NAME
  36 .Nm ld
  37 .Nd link editor
  38 .Sh SYNOPSIS
  39 .Nm ld
  40 .Op Fl fMNnrSstXxz
  41 .Bk -words
  42 .Op Fl A Ar symbol-file
  43 .Op Fl assert Ar keyword
  44 .Op Fl B Ns Ar linkmode
  45 .Op Fl D Ar datasize
  46 .Op Fl d Ar c
  47 .Op Fl d Ar p
  48 .Op Fl e Ar entry
  49 .Op Fl l Ns Ar library-specifier
  50 .Op Fl L Ns Ar library-search-path
  51 .Op Fl nostdlib
  52 .Op Fl O Ar filename
  53 .Op Fl o Ar filename
  54 .Op Fl R Ns Ar record-library-search-path
  55 .Op Fl T Ar address
  56 .Op Fl u Ar symbol
  57 .Op Fl V Ar shlib-version
  58 .Op Fl y Ar symbol
  59 .Ek
  60 .Sh DESCRIPTION
  61 .Nm
  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
  66 .Nm .
  67 Object files and archives are processed in the order given on the command line.
  68 .Pp
  69 The options are as follows:
  70 .Pp
  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
  74 on the command line.
  75 .It Fl assert Ar keyword
  76 This option is here mainly for compatibility with SunOS
  77 .Nm .
  78 Most conditions which would cause a Sun assertion to fail will
  79 currently always cause error or warning messages from
  80 .Nm .
  81 The only keyword implemented by
  82 .Nm
  83 is
  84 .Nm pure-text ,
  85 which generates a warning if a position independent object is being
  86 created and some of the files being linked are not position
  87 independent.
  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,
  91 .Nm
  92 searches for a library of the from libx.so.n.m
  93 (see the
  94 .Fl l
  95 option)
  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
  99 to
 100 .Fl B Ns Ar static .
 101 .It Fl B Ns Ar forcedynamic
 102 This is similar to
 103 .Fl B Ns Ar dynamic
 104 except that if no dynamic libraries are linked against,
 105 .Nm
 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
 109 The counterpart of
 110 .Fl B Ns Ar dynamic .
 111 This option turns off dynamic linking for
 112 all library specifiers until a
 113 .Fl B Ns Ar dynamic
 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
 123 .Em base-relative
 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
 130 the archive.
 131 .It Fl B Ns Ar silly
 132 Search for
 133 .Em \.sa
 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.
 139 .It Fl d Ar c
 140 Force allocation of commons even producing relocatable output.
 141 .It Fl d Ar p
 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
 145 .Xr link 5 )
 146 .It Fl e Ar entry-symbol
 147 Specifies the entry symbol for an executable.
 148 .It Fl f
 149 List the resolved paths of all the object files and libraries on the
 150 standard output, and exit.
 151 .It Fl L Ns Ar path
 152 Add
 153 .Ar path
 154 to the list of directories to search for libraries specified with the
 155 .Fl l
 156 option.
 157 .It Fl l Ns Ar lib-spec
 158 This option specifies a library to be considered for inclusion in the
 159 output. If the
 160 .Fl B Ns Ar dynamic
 161 option is in effect, a shared library of the
 162 form lib<spec>.so.m.n
 163 (where
 164 .Em m
 165 is the major, and
 166 .Em 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
 171 .Fl B Ns Ar static
 172 options is in effect, an archive of the form lib<spec>.a is looked for in
 173 the library search path.
 174 .It Fl M
 175 Produce output about the mapping of segments of the input files and the
 176 values assigned to
 177 (global)
 178 symbols in the output file.
 179 .It Fl N
 180 Produce a
 181 .Dv OMAGIC
 182 output file.
 183 .It Fl n
 184 Produce a
 185 .Dv NMAGIC
 186 output file.
 187 .It Fl nostdlib
 188 Do not search the built-in path
 189 (usually
 190 .Dq /usr/lib )
 191 for
 192 .Fl l
 193 specified libraries.
 194 .It Fl O Ar filename
 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
 199 .Ar filename .
 200 .It Fl o Ar filename
 201 Specifies the name of the output file. Defaults to
 202 .Dq Pa a.out .
 203 .It Fl Q
 204 Produce a
 205 .Dv QMAGIC
 206 .Pq Fx , Bsx Ns -i386
 207 output file.  This is the default.
 208 .It Fl r
 209 Produce relocatable object file, suitable for another pass through
 210 .Nm .
 211 .It Fl R
 212 Record the given path within the executable for run-time library search.
 213 This only applies to dynamically linked executables.
 214 .It Fl S
 215 Strip all debugger symbols from the output.
 216 .It Fl s
 217 Strip all symbols from the output.
 218 .It Fl T
 219 Specifies the start address of the text segment, with respect to which
 220 all input files will be relocated.
 221 .It Fl t
 222 Leave a trace of the input files as they are processed.
 223 .It Fl u Ar symbol
 224 Force
 225 .Ar symbol
 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.
 228 .It Fl V Ar version
 229 Put the given version number into the output shared library
 230 (if one is created).
 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.
 233 .It Fl X
 234 Discard local symbols in the input files that start with the letter
 235 .Dq L
 236 .It Fl x
 237 Discard all local symbols in the input files.
 238 .It Fl y Ar symbol
 239 Trace the manipulations inflicted on
 240 .Ar symbol
 241 .It Fl Z
 242 Make a
 243 .Bx 386
 244 .Dv ZMAGIC
 245 output file.
 246 .It Fl z
 247 Make a
 248 .Nx
 249 .Dv ZMAGIC
 250 output file.
 251 .El
 252 .Sh ENVIRONMENT
 253 .Nm
 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
 259 .Fl L
 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
 264 .\" .Fl nostdlib
 265 .\" command-line flag.
 266 .El
 267 .Sh FILES
 268 .Sh SEE ALSO
 269 .Xr ldd 1 ,
 270 .Xr rtld 1 ,
 271 .Xr link 5 ,
 272 .Xr ldconfig 8
 273 .Sh CAVEATS
 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
 276 .Nm .
 277 .Sh BUGS
 278 Shared objects are not properly checked for undefined symbols.
 279 .Pp
 280 Cascading of shared object defeats the
 281 .Dq -Bstatic
 282 option.
 283 .Pp
 284 All shared objects presented to
 285 .Nm
 286 are marked for run-time loading in the output file, even if no symbols
 287 are needed from them.
 288 .Sh HISTORY
 289 A
 290 .Nm
 291 command appeared in
 292 .At v1 .
 293 The shared library model employed by
 294 .Nm
 295 appeared first in SunOS 4.0