4.3BSD - /usr/man/cat1/ld.0

LD(1)                                                                    LD(1)


NAME
       ld - link editor

SYNOPSIS
       ld [ option ] ... file ...

DESCRIPTION
       Ld  combines several object programs into one, resolves external refer‐
       ences, and searches libraries.  In the  simplest  case  several  object
       files are given, and ld combines them, producing an object module which
       can be either executed or become the input for a further ld  run.   (In
       the latter case, the -r option must be given to preserve the relocation
       bits.)  The output of ld is left on a.out.   This  file  is  made  exe‐
       cutable only if no errors occurred during the load.

       The  argument  routines  are  concatenated in the order specified.  The
       entry point of the output is the beginning of the first routine (unless
       the -e option is specified).

       If  any argument is a library, it is searched exactly once at the point
       it is encountered in the argument list.  Only those  routines  defining
       an  unresolved  external  reference  are  loaded.   If a routine from a
       library references another routine in the library, and the library  has
       not  been  processed  by  ranlib(1), the referenced routine must appear
       after the referencing routine in the library.  Thus the order  of  pro‐
       grams within libraries may be important.  The first member of a library
       should be a file named ‘__.SYMDEF’, which is understood to be a dictio‐
       nary  for  the  library  as  produced  by  ranlib(1); the dictionary is
       searched iteratively to satisfy as many references as possible.

       The symbols ‘_etext’, ‘_edata’ and ‘_end’ (‘etext’, ‘edata’  and  ‘end’
       in  C)  are reserved, and if referred to, are set to the first location
       above the program, the first location above initialized data,  and  the
       first  location above all data respectively.  It is erroneous to define
       these symbols.

       Ld understands several options.  Except  for  -l,  they  should  appear
       before the file names.

       -A     This  option  specifies incremental loading, i.e.  linking is to
              be done in a manner so that the resulting  object  may  be  read
              into  an  already  executing  program.  The next argument is the
              name of a file whose symbol table will be taken as  a  basis  on
              which  to define additional symbols.  Only newly linked material
              will be entered into the text and data portions  of  a.out,  but
              the  new  symbol  table will reflect every symbol defined before
              and after the  incremental  load.   This  argument  must  appear
              before  any  other  object  file  in  the argument list.  The -T
              option may be used as well, and will be taken to mean  that  the
              newly  linked segment will commence at the corresponding address
              (which must be a multiple of 1024).  The default  value  is  the
              old value of _end.

       -D     Take  the next argument as a hexadecimal number and pad the data
              segment with zero bytes to the indicated length.

       -d     Force definition of common  storage  even  if  the  -r  flag  is
              present.

       -e     The  following  argument  is  taken  to be the name of the entry
              point of the loaded program; location 0 is the default.

       -Ldir  Add dir to the  list  of  directories  in  which  libraries  are
              searched for.  Directories specified with -L are searched before
              the standard directories.

       -lx    This option is an abbreviation for the  library  name  ‘libx.a’,
              where  x  is  a  string.  Ld searches for libraries first in any
              directories specified with -L  options,  then  in  the  standard
              directories ‘/lib’, ‘/usr/lib’, and ‘/usr/local/lib’.  A library
              is searched when its name is encountered, so the placement of  a
              -l is significant.

       -M     produce  a  primitive  load  map, listing the names of the files
              which will be loaded.

       -N     Do not make the text portion read only or sharable.  (Use "magic
              number" 0407.)

       -n     Arrange  (by  giving the output file a 0410 "magic number") that
              when the output file is executed, the text portion will be read-
              only  and  shared  among  all  users  executing  the file.  This
              involves moving the data areas up to  the  first  possible  1024
              byte boundary following the end of the text.

       -o     The  name argument after -o is used as the name of the ld output
              file, instead of a.out.

       -r     Generate relocation bits in the output file so that  it  can  be
              the  subject  of  another ld run.  This flag also prevents final
              definitions from being given to common symbols,  and  suppresses
              the ‘undefined symbol’ diagnostics.

       -S     ‘Strip’  the  output  by  removing all symbols except locals and
              globals.

       -s     ‘Strip’ the output, that is, remove the symbol table and reloca‐
              tion bits to save space (but impair the usefulness of the debug‐
              gers).  This information can also be removed by strip(1).

       -T     The next argument is a hexadecimal number which  sets  the  text
              segment origin.  The default origin is 0.

       -t     ("trace")  Print the name of each file as it is processed.

       -u     Take  the  following  argument as a symbol and enter it as unde‐
              fined in the symbol table.  This is useful  for  loading  wholly
              from a library, since initially the symbol table is empty and an
              unresolved reference is needed to force the loading of the first
              routine.

       -X     Save  local symbols except for those whose names begin with ‘L’.
              This option is used by  cc(1)  to  discard  internally-generated
              labels while retaining symbols local to routines.

       -x     Do  not preserve local (non-.globl) symbols in the output symbol
              table; only enter external  symbols.   This  option  saves  some
              space in the output file.

       -ysym  Indicate  each  file  in which sym appears, its type and whether
              the file defines or references it.  Many  such  options  may  be
              given  to trace many symbols.  (It is usually necessary to begin
              sym with an ‘_’, as external C,  FORTRAN  and  Pascal  variables
              begin with underscores.)

       -z     Arrange  for the process to be loaded on demand from the result‐
              ing executable file (413 format) rather than preloaded.  This is
              the  default.   Results in a 1024 byte header on the output file
              followed by a text and data segment each of which  have  size  a
              multiple  of 1024 bytes (being padded out with nulls in the file
              if necessary).  With this format the first few BSS segment  sym‐
              bols may actually appear (from the output of size(1)) to live in
              the data segment; this to avoid wasting the space resulting from
              data segment size roundup.

FILES
       /lib/lib*.a            libraries
       /usr/lib/lib*.a        more libraries
       /usr/local/lib/lib*.a  still more libraries
       a.out                  output file

SEE ALSO
       as(1), ar(1), cc(1), ranlib(1)

BUGS
       There is no way to force data to be page aligned.  Ld pads images which
       are to be demand loaded from the file system to the next page  boundary
       to avoid a bug in the system.


4th Berkeley Distribution         May 8, 1986                            LD(1)