ld -- Command

Link relocatable object modules
ld [option ...] file ...

A compiler translates a file of source code into a relocatable object. This
relocatable  object cannot  be executed  by itself,  for calls  to routines
stored in  libraries have  not yet been  resolved.  ld combines,  or links,
relocatable object files with  routines stored in libraries produced by the
archiver  ar to  construct  an executable  file.   For this  reason, ld  is
sometimes called a linker, a link editor, or a loader.

ld scans  its arguments  in order and  interprets each option  as described
below.   Each non-option  argument  is either  a  relocatable object  file,
produced by cc, as, or ld,  or a library archive produced by ar. It rejects
all other arguments and prints a diagnostic message.

Each relocatable file argument is bound into the output file if its machine
type matches the  machine type of the first file  so bound; if it does not,
ld prints  a diagnostic message.   The symbol table  of the file  is merged
into the output symbol table and  the list of defined and undefined symbols
updated  appropriately.   If the  file  redefines a  symbol  defined in  an
earlier bound module, the  redefinition is reported and the link continues.
The last  such redefinition determines the value that  the symbol will have
in the output file, which may be acceptable but is probably an error.

Each  library  archive  argument  is  searched  only to  resolve  undefined
references, i.e., if there are no undefined symbols, the linker goes to the
next argument  immediately.  The library  is searched from  first module to
last and  any module that resolves  one or more undefined  symbols is bound
into the  output exactly as an explicitly named  relocatable file is bound.
The library is searched repeatedly until an entire scan adds nothing to the
executable file.

The order  of modules in  a library is  important in two  respects: it will
affect  the time  required to  search the  library, and,  if more  than one
module  resolves an  undefined  symbol, it  can  alter the  set of  library
modules bound into the output.

A library  will link faster if  the undefined symbols in  any given library
module are  resolved by a library  module that comes later  in the library.
Thus,  the low-level  library  modules, those  with  no undefined  symbols,
should come  at the end  of the library, whereas  the higher-level modules,
those  with many  undefined  symbols, should  come at  the beginning.   The
library  module  ranlib.sym, which  is  maintained by  the  ar s  modifier,
provides ld with a compressed index  to the symbols defined in the library.
But even with  the index, the library will link  much faster if the modules
occur in top-down rather than bottom-up order.

A library  can be constructed to provide a  type of ``conditional'' linking
if alternate  resolutions of undefined symbols are  archived in a carefully
thought-out order.  For instance, libc.a contains the modules

    finit.o
    exit.o
    _finish.o

in  precisely the  order given,  though some  other modules  may intervene.
finit.o  contains  most  of the  internals  of  the  STDIO library,  exit.o
contains the  exit() function, and  _finish.o contains an  empty version of
_finish(), the  function that  exit() calls  to close STDIO  streams before
process  termination.  If  a program  uses any  STDIO routines,  macros, or
data,  then finit.o  will be  bound  into the  output with  its version  of
finish(). If a program uses no  STDIO, then the ``dummy'' _finish.o will be
bound into the output because it is the first module that defines _finish()
that the linker encounters after exit.o adds the undefined reference.  This
saves approximately  3,000 bytes.   To set the  order of routines  within a
library, use the archiver ar.

COFF Linking

COHERENT uses  the Common Object  File Format (COFF).   This format renders
many advantages,  but it also places special demands  upon the linker.  The
following discussing  some of the complexities that  arise for linking into
the COFF format.

Under  COFF, common  variables  are kept  aligned according  to their  most
strongly aligned  contributor.  If name is linked  with another module that
also declares  name but sets it  to another length, the  linker creates one
such variable and  gives it the greater length of  the two.  ld deduces the
alignment of a common variable by  its length: if the length of a common is
divisible  by  four, it  is  aligned  on a  four-byte  boundary;  if it  is
divisible by two,  it is aligned on a two-byte  boundary.  Otherwise, it is
assumed  to  be  unaligned.  The  linker  supports  only  three classes  of
alignment:  four-byte, two-byte,  and unaligned.  It  then aligns  a common
variable according to its most strongly aligned contributor.

For example,  if one assembly-language module  contributes a .comm (common)
variable  named xyz  whose length  is four  bytes, and  another contributes
another xyz whose length is five bytes, ld gives the resulting xyz a length
of eight  bytes to satisfy the  length requirement (at least  five) and the
alignment requirement (four-byte boundary).

Or in  another example, if you  declare a C variable char x;  x is a common
variable, with a length of one  byte.  If another C module declares long x;
the  two x's  will share  a length  of four bytes.   However, in  the first
module sizeof(x)  == 1 and in  the second sizeof(x) ==  4. These will cause
warning messages to appear, which you can turn off by using the -q option.

After ld has made its first pass, it places all common variables at the end
of the  .bss segment: first the four-byte-aligned  variables, then the two-
byte-aligned, then the unaligned.

Options

ld recognizes the following options:

-e entry
     Specify the entry point of the output module, either as a symbol or as
     an absolute octal address.

-f   (Force)  Force  link  even  if  there  are  errors.   Results  may  be
     undefined.

-G   Suppress the common/global warning -- that is, tell ld not to complain
     if a global variable is also used as a common variable.

-i   This option  is obsolete, but is kept  for compatibility purposes.  If
     you include it in a makefile, ld will silently ignore it.

-K   Link a kernel segment.

-Ldirectory
     Search  directory  for  libraries  and  objects before  searching  the
     directories named in LIBPATH. Note that  you can have more than one -L
     option  in a  ld command  line.   For example,  if LIBPATH  is set  to
     /lib:/usr/lib, then the command line

         ld -L/search/First -L/search/Next a.o -lxyz

     tells ld to search for libraries libxyz.a and libc.a along the path:

         /search/First:/search/Next:/lib:/usr/lib

     The character that  separates entries in the path is  set by the macro
     LISTSEP. Header file path.h defines this to be the `:'.

-l name
     An abbreviation  for the library  /lib/libname.a or /usr/lib/libname.a
     if the first is not found.

-o file
     Write output to file. The default is a.out.

-q   Suppress all warning messages.

-Q   Suppress all error messages, not just warnings.

-r   Retain relocation  information in the output,  and issue no diagnostic
     message  for undefined  symbols.  This  option builds  a .o  file that
     appears as if its pieces had been compiled together.

-s   Strip  the symbol  table  from the  output.   The same  effect may  be
     obtained  by  using the  command  strip.  The -s  and  -r options  are
     mutually exclusive.

-u symbol
     Add symbol to the symbol table as a global reference, usually to force
     the linking of a particular library module.

-X   Discard local compiler-generated symbols beginning .L.

-x   Discard all local symbols.

ld reads the environmental variables LDHEAD and LDTAIL and appends them to,
respectively, the  beginning and end of its command  line.  For example, to
ensure that ld is always executed  with the option -d, insert the following
into your .profile:

    export LDHEAD=-d

Likewise, to  ensure that ld  always includes the  mathematics library libm
when it links, insert the following into your .profile:

    export LDTAIL=-lm

LIBPATH

Except when used with its -l option, ld does not know about paths: it links
exactly what  you tell it  to link via  the cc command line.   cc looks for
libraries by searching  the directories named in the environmental variable
LIBPATH. If you do not define  LIBPATH in your environment, it searches the
default LIBPATH  as defined in /usr/include/path.h.  If you define LIBPATH,
cc  searches the  directories in  the  order you  specify.  For  example, a
typical definition is:

    export LIBPATH=:/lib:/usr/lib

This searches the current directory `.', then /lib, then /usr/lib.

Linker-defined Symbols

ld defines the following set of symbols within an executable program:

__end_textEnd of the .text segment
__end_dataEnd of the .data segment
__end_bss End of the .bss segment
__end     End of the highest segment

Note that if  you have a segment named .xyz,  then ld will allow you to use
__end_xyz.

Files

a.out -- Default output
/coherent for -k option
/lib/lib*.a -- Libraries
/usr/lib/lib*.a -- More libraries

See Also

ar,
ar.h,
as,
cc,
cdmp,
coff.h,
commands,
l.out.h,
LIBPATH,
strip

Diagnostics

The following gives the error messages returned by  ld. The messages are in
alphabetical order; each  is marked as to whether it  is a fatal or warning
condition.  A  fatal message usually indicates a  condition that caused the
compiler to  terminate execution.  Warning messages point  out code that is
compilable, but may produce trouble when the program is executed.

archive 'string' is corrupt (fatal)
     This archive  makes no sense.  You  may wish to examine  this with the
     archiver ar.

file string: module string: bad header (warning)
     string does not look like a real object module.

can't find 'string' (fatal)
     ld cannot  find the requested library.  Make sure  that the cc command
     line points to the directory that holds the archive.

cannot create 'string' (fatal)
     ld cannot create its output file.

entry point 'string' not in .text (warning)
error reading 'string' (fatal)

'string' is not a COFF archive (fatal)
     All files ending .a should be  COFF archives.  You may need to rebuild
     this archive.

Library must be created with ar -s option (fatal)
     The option -s to ar gives libraries a symbol table for the use of ld.

No work (fatal)
     There were no object files loaded.

pass 1, n errors (fatal)
     At the end  of pass 1 there were n  errors detected.  The link stopped
     here.

symbol 'string' redefined in file 'string': module 'string' (warning)
     A symbol is defined in incompatible ways in different files.

symbol 'string' redefined in file 'string' (warning)
     A symbol is defined in incompatible ways in different files.

file string: module string: relocation out of range 0xn (warning)
     A relocation record points outside the range of its segment.

symbol  'string' severe  warning symbol  defined as a  common and  a global
     (warning)
     A symbol was defined as a common, e.g.

         int x;
     and as a global, e.g.:

         int x = 5;
     There is no good way to fix this without reading the code and thinking
     about  the  variable usage.   The  linker turned  the  global into  an
     external.  That is, it turned

         int x;
     into

         extern int x;
     This matches the UNIX linker.

file  string:  module  string: unknown  r_type  n  in  segment  n record  n
     (warning)
     Unknown type on COFF relocation record.

unlikely input file name 'string' (warning)
     Input file names must end .o for object or .a for archive.

symbol 'string' warning defined with lengths n and n (warning)
     A common was defined with different lengths, while this is legal it is
     very unusual in  C programs.  This warning may be  turned off with the
     flag -c.

symbol 'string' warning, redefines builtin symbol (warning)
     Some symbols  such as __end and __end_text are  special to the linker.
     In general,  symbols beginning `__'  are reserved to  implementors and
     should be avoided by users.  Your definition has been used.

write error (fatal)
     ld  cannot  write   the  executable  program.   Check  that  you  have
     permission to write into the target directory.

Notes

If you  are linking a  program by hand  (that is, running  ld independently
from the cc command), be  sure to include the appropriate run-time start-up
routine  with the  ld command  line; otherwise, the  program will  not link
correctly.

© 2012 by Stephen A. Ness