


LD(1)                    USER COMMANDS                      LD(1)



NAME
     ld, ld.so - link editor, dynamic link editor

SYNOPSIS
     ld [ -align datum ] [ -assert assertion-keyword ]
          [ -A name ] [ -Bbinding-keyword ] [ -d ] [ -dc ]
          [ -dp ] [ -D hex ] [ -e entry ] [ -lx ] [ -Ldir ]
          [ -M ] [ -n ] [ -N ] [ -o name ] [ -p ] [ -r ] [ -s ] [
     -S ]
          [ -t ] [ -T[text] hex ] [ -Tdata hex ] [ -u name ]
          [ -x ] [ -X ] [ -ysym ] [ -z ] filename ...

DESCRIPTION
     ld combines object programs to create an executable file  or
     another  object  program  suitable for further ld processing
     (with the -r  option).   The  object  modules  on  which  ld
     operates are specified on the command line, and can be:

          o+  simple object files, which typically end in  the  .o
             suffix, and are referred to as "dot-oh" files

          o+  ar(1V) library archives (.a), or "libraries"

          o+  dynamically-bound, sharable object files (.so),  are
             also  referred  to  as "shared libraries," which are
             created from previous ld executions.

     Unless an output file is specified, ld produces a file named
     a.out.   This file contains the object files given as input,
     appropriately combined to form an executable file.

OPTIONS
     When linking debugging or profiling objects, include the  -g
     or  -pg  option (see cc(1V)), as appropriate, in the ld com-
     mand.

     Options should appear before filenames, except for  abbrevi-
     ated library names specified with -l options, and some bind-
     ing control options specified by -B (which can  appear  any-
     where in the line).

     -align datum
          Force the global uninitialized data symbol datum  (usu-
          ally  a  FORTRAN  common  block)  to  be  page-aligned.
          Increase its size to a whole number of pages, and place
          its first byte at the start of a page.

     -assert assertion-keyword
          Check an assertion about the link  editing  being  per-
          formed.   The  assertion  desired  is  specified by the
          assertion-keyword string.  ld is silent if  the  asser-
          tion  holds,  else  it  yields a diagnostic and aborts.



Sun Release 4.1   Last change: 21 January 1990                  1






LD(1)                    USER COMMANDS                      LD(1)



          Valid  assertion-keyword's  and  their  interpretations
          are:

               definitions    If the resulting program  were  run
                              now,  there  would  be  no run-time
                              undefined symbol diagnostics.  This
                              assertion is set by default.

               nodefinitions  Permit the successful linking of  a
                              program with unresolved references.

               nosymbolic     There are  no  symbolic  relocation
                              items remaining to be resolved.

               pure-text      The resulting load has  no  reloca-
                              tion items remaining in its text.

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

     -Bbinding-keyword
          Specify allowed binding times for the items which  fol-
          low.  Allowed values of binding-keyword are:

          dynamic        Allow dynamic binding:  do  not  resolve
                         symbolic  references,  allow creation of
                         run-time symbol and relocation  environ-
                         ment.  -Bdynamic  is  the default.  When
                         -Bdynamic is  in  effect,  all  sharable
                         objects  encountered  until a succeeding
                         -Bstatic may be added dynamically to the
                         object   being   linked.    Non-sharable
                         objects are bound statically.

          nosymbolic     Do not perform symbolic relocation, even
                         if other options imply it.

          static         Bind statically.  Opposite of -Bdynamic.
                         Implied   when   either   -n  or  -N  is



Sun Release 4.1   Last change: 21 January 1990                  2






LD(1)                    USER COMMANDS                      LD(1)



                         specified.  Influences handling  of  all
                         objects following its specification on a
                         command line until the next -Bdynamic.

          symbolic       Force  symbolic  relocation.    Normally
                         implied  if  an  entry  point  has  been
                         specified with -e, or if dynamic loading
                         is in effect.

     -d   Force common storage for  uninitialized  variables  and
          other  common symbols to be allocated in the current ld
          run, even when the -r flag is present (which would oth-
          erwise  postpone  this  binding until the final linking
          phase).

     -dc  Do -d, but also copy  initialized  data  referenced  by
          this program from shared objects.

     -dp  Force an alias definition of undefined procedure  entry
          points.  Used  with  dynamic binding to improve sharing
          and the locality of run-time relocations.

     -D hex
          Pad the data segment with zero-valued bytes to make  it
          hex bytes long.

     -e entry
          Define the entry point: the entry argument is made  the
          name of the entry point of the loaded program.  Implies
          -Bsymbolic.

     -lx[.v]
          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.
          If  a  dynamically  loadable  object  is   found,   and
          -Bdynamic  is  in  effect  at that point on the command
          line, then ld prepares to access the object for reloca-
          tion at run-time.  In such a case, the optional .v suf-
          fix can be used to indicate a specific library version.

     -Ldir
          Add dir to the list of directories in which  to  search
          for  libraries.   Directories  specified  with  -L  are
          searched  before  the   standard   directories,   /lib,
          /usr/lib,  and /usr/local/lib.  When building a program
          in which one or more objects are loaded when  -Bdynamic
          is in effect, those directories specified by -L options
          will be "remembered" for use at execution  time.   This



Sun Release 4.1   Last change: 21 January 1990                  3






LD(1)                    USER COMMANDS                      LD(1)



          permits  the  construction of software that uses shared
          objects as libraries not residing in the standard loca-
          tions  and  avoids  requiring  the specification of the
          LD_LIBRARY_PATH environment variable in order  to  exe-
          cute  such  software.   Note  that such directories are
          retained in exactly the form specified in  the  option,
          which  means  that  relative  directory  specifications
          (i.e., not beginning with "/") will be evaluated  rela-
          tive  to the current directory when the program is run,
          not just during the operation of ld.

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

     -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  with  the  data  areas
          placed  at  the  beginning of the next address boundary
          following the end of the text.  Implies -Bstatic.

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

     -o name
          name is made the name of the ld output file, instead of
          a.out.

     -p   Arrange for the data segment to begin on a  page  boun-
          dary,  even  if  the  text  is  not shared (with the -N
          option).

     -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" diagnos-
          tics.

     -s   Strip the output, that is, remove the symbol table  and
          relocation  bits  to save space (but impair the useful-
          ness of the debuggers).  This information can  also  be
          removed by strip(1).

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

     -t   Trace: display the name of each  file  as  it  is  pro-
          cessed.

     -T[text]hex
          Start the text segment at location hex.  Specifying  -T
          is the same as using the -Ttext option.




Sun Release 4.1   Last change: 21 January 1990                  4






LD(1)                    USER COMMANDS                      LD(1)



     -Tdata hex
          Start the data segment at location hex.  This option is
          only  of  use  to programmers wishing to write code for
          PROMs, since the resulting code cannot be  executed  by
          the system.

     -u name
          Enter name as an undefined symbol.  This is useful  for
          loading wholly from a library, since initially the sym-
          bol table is  empty  and  an  unresolved  reference  is
          needed to force the loading of the first routine.

     -x   Preserve only global (non-.globl) symbols in the output
          symbol table; only enter external symbols.  This option
          saves some space in the output file.

     -X   Record local symbols,  except  for  those  whose  names
          begin  with  L.   This  option is used by cc to discard
          internally generated  labels  while  retaining  symbols
          local to routines.

     -ysym
          Display 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 usu-
          ally necessary to begin sym with an `_', as external C,
          FORTRAN and Pascal variables begin with underscores.

     -z   Arrange for the process demand paged from the resulting
          executable  file  (0413  "magic  number").  This is the
          default.  Results in a (32-byte) header on  the  output
          file  followed by text and data segments, each of which
          has a multiple of page-size  bytes  (being  padded  out
          with  null  characters in the file if necessary).  With
          this format the first few BSS segment symbols may actu-
          ally end up in the data segment; this is to avoid wast-
          ing the space resulting from rounding the data  segment
          size.  Implies -Bdynamic.

USAGE
  Command Line Processing
     In general, options should appear ahead of the list of files
     to  process.   Unless  otherwise specified, the effect of an
     option covers all of  ld  operations,  independent  of  that
     option's  placement on the command line.  Exceptions to this
     rule include some of the binding control  options  specified
     by `-B' and the abbreviated library-names specified by `-l'.
     These may appear anywhere, and their influence is  dependent
     upon  their  location.  Some  options  may  be obtained from
     environment variables, such options are  interpreted  before
     any on the command line (see ENVIRONMENT, below).




Sun Release 4.1   Last change: 21 January 1990                  5






LD(1)                    USER COMMANDS                      LD(1)



  Object File Processing
     The files specified on the command line are processed in the
     order  listed.  Information is extracted from each file, and
     concatenated to form the output.   The  specific  processing
     performed  on a given file depends upon whether it is a sim-
     ple object file, a library archive, or a shared library.

     Simple object (.o) files are concatenated to the  output  as
     they are encountered.

     Library archive (.a) files are searched exactly  once  each,
     as  each is encountered; only those archive entries matching
     an unresolved external  reference  are  extracted  and  con-
     catenated  to  the output.  If a member of an archive refer-
     ences a symbol  defined  by  another  member  of  that  same
     archive,  the member making the reference must appear before
     the member containing the definition.

     On Sun386i, a library contains a dictionary of symbols,   On
     other  Sun systems, processing library archives through ran-
     lib(1) provides this dictionary.  In addition, you  can  use
     lorder(1),  in  combination  with  tsort(1) to place library
     members in calling order (see  lorder(1)  for  details),  or
     both  (for  fastest  symbol lookup).  The first member of an
     archived processed  by  ranlib  has  the  reserved  name  of
     __.SYMDEF,  which  ld takes to be the dictionary of all sym-
     bols defined by members of the archive.

     Sharable objects (.so) are scanned  for  symbol  definitions
     and  references, but are not normally included in the output
     from ld, except in cases where a shared library exports ini-
     tialized  data  structures  and the -dc option is in effect.
     However, the occurrence of each sharable object file in  the
     ld  command  line is noted in the resulting executable file;
     this notation is utilized by an  execution-time  variant  of
     ld, ld.so, for deferred and dynamic loading and binding dur-
     ing  execution.   See  Execution-Time  Loading,  below,  for
     details.

     The -l option specifies a short name for an object  file  or
     archive used as a library.  The full name of the object file
     is derived by adding the prefix lib and a suffix  of  either
     .a  or  .so[.v]  to  indicate  an ar(1V) archive or a shared
     library, respectively.  The specific suffix used  is  deter-
     mined  through  rules  discussed  in  Binding and Relocation
     Semantics, below.

     ld searches for the desired object file through  a  list  of
     directories  specified  by -L options, the environment vari-
     able LD_LIBRARY_PATH, and  finally,  the  built-in  list  of
     standard    library   directories:   /lib,   /usr/lib,   and
     /usr/local/lib.



Sun Release 4.1   Last change: 21 January 1990                  6






LD(1)                    USER COMMANDS                      LD(1)



  Binding and Relocation Semantics
     The manner in which ld processes  a  given  object  file  is
     dependent  in  part  upon  the "binding mode" in which it is
     operating at the time the file is encountered.  This binding
     mode  is  specified  by the -B flag, which takes the keyword
     arguments:

          dynamic   Allow dynamic binding, do  not  resolve  sym-
                    bolic   references,  and  allow  creation  of
                    execution-time symbol and relocation informa-
                    tion.  This is the default setting.

          static    Force static binding, implied by options that
                    generate non-sharable executable formats.

     -Bdynamic and -Bstatic may be specified several  times,  and
     may  be  used to toggle each other on and off.  Like -l, the
     influence of each depends upon its location within the  com-
     mand  line.  When -Bdynamic is in effect, -l searches may be
     satisfied by the first occurrence of either form of  library
     (.so  or  .a),  but if both are encountered, the .so form is
     preferred.  When -Bstatic is in effect, ld  refuses  to  use
     any  .so  libraries it encounters; it continue searching for
     the .a form.  Furthermore, an explicit request to load a .so
     file is treated as an error.

     After ld has processed all  input  files  and  command  line
     options,  the form of the output it produces is based on the
     information provided in both. ld first tries to  reduce  all
     symbolic references to relative numerical offsets within the
     executable it is building.  To perform this "symbolic reduc-
     tion," ld must be able to determine that:

          o+  all information relating to  the  program  has  been
             provided,  in  particular,  no .so is to be added at
             execution time; and/or

          o+  the program has an entry point, and symbolic  reduc-
             tion can be performed for all symbols having defini-
             tions existing in the material provided.

     It should be noted that uninitialized  "common"  areas  (for
     example,  uninitialized C globals) are allocated by the link
     editor after it has collected all references.   In  particu-
     lar,  this  allocation can not occur in a program that still
     requires the addition of  information  contained  in  a  .so
     file,  as  the missing information may affect the allocation
     process.  Initialized  "commons"  however,   are   allocated
     within the executable in which their definition appears.

     After ld has performed all the symbolic reductions  it  can,
     it attempts to transform all relative references to absolute



Sun Release 4.1   Last change: 21 January 1990                  7






LD(1)                    USER COMMANDS                      LD(1)



     addresses.  ld is able to perform this "relative  reduction"
     only  if  it has been provided some absolute address, either
     implicitly through the specification of an entry  point,  or
     explicitly  through  ld command-line options. If, after per-
     forming all the reductions it  can,  there  are  no  further
     relocations  or definitions to perform, then ld has produced
     a completely linked executable.

  Execution-Time Loading
     In the event that one or more reductions  can  not  be  com-
     pleted,  the executable will require further link editing at
     execution time in order to be usable.  Such executables con-
     tain an data structure identified with the symbol __DYNAMIC.
     An incompletely linked "main" program should be linked  with
     a  "bootstrap"  routine  that  invokes ld.so, which uses the
     information contained in the  main  program's  __DYNAMIC  to
     assemble the rest of the executables constituting the entire
     program.  A standard Sun compilation driver (such as cc(1V))
     automatically  includes such a module in each "main" execut-
     able.

     When ld.so is given control on program startup, it finds all
     .so  files  specified  when the program was constructed (and
     all .so's on which they depend), and  loads  them  into  the
     address  space.  The algorithm by which such files are found
     mimics that used when ld is run, and like ld, can be  influ-
     enced  by  the setting of LD_LIBRARY_PATH and any -L options
     specified to ld when the program was built.  ld.so then com-
     pletes all remaining relocations, with the exception of pro-
     cedure call relocations; failure to  resolve  a  given  non-
     procedural  relocation results in termination of the program
     with an appropriate diagnostic.

     Procedure relocations  are  resolved  when  the  referencing
     instruction  is  first executed.  It should be noted that it
     is possible for "undefined symbol" diagnostics  to  be  pro-
     duced  during  program  execution  if  a given target is not
     defined when referenced.

     Although it is possible  for  binding  errors  to  occur  at
     execution-time, such an occurrence generally indicates some-
     thing wrong in the  maintenance  of  shared  objects.   ld's
     -assert   nodefinitions  function  (on by default) checks at
     ld-time whether or not an execution-time binding error would
     occur.

  Version Handling for Shared Libraries
     To  allow  the  independent  evolution  of  .so's  used   as
     libraries  and the programs which use them, ld's handling of
     .so files found through -l options  involves  the  retention
     and  management  of  version  control  information.  The .so
     files used as such "shared libraries" are post-fixed with  a



Sun Release 4.1   Last change: 21 January 1990                  8






LD(1)                    USER COMMANDS                      LD(1)



     Dewey-decimal  format  string  describing the version of the
     "library" contained in the file.

     The first decimal component is called the  library's  "major
     version"  number,  and  the second component its "minor ver-
     sion" number.  When ld records a .so used as a  library,  it
     also records these two numbers in the database used by ld.so
     at execution time.  In turn, ld.so  uses  these  numbers  to
     decide  which  of  multiple  versions  of a given library is
     "best" or whether any of the available versions are  accept-
     able.  The rules are:

          o+  Major Versions Identical: the major version used  at
             execution  time must exactly match the version found
             at ld-time.  Failure to  find  an  instance  of  the
             library with a matching major version causes a diag-
             nostic to be issued and the program's  execution  to
             be terminated.

          o+  Highest Minor Version: in the presence  of  multiple
             instances  of libraries that match the desired major
             version, ld.so uses the  highest  minor  version  it
             finds.   However, if the highest minor version found
             at execution time is less than the version found  at
             ld-time,  a  warning  diagnostic  is issued; program
             execution continues.

     The semantics of version numbers are such that major version
     numbers  should  be changed whenever interfaces are changed.
     Minor versions  should  be  changed  to  reflect  compatible
     updates  to  libraries, and programs will silently favor the
     highest compatible version they can obtain.

  Special Symbols
     A number of symbols have special meanings to ld and programs
     should  not  define  these  symbols.   The symbols described
     below are those actually seen by ld.  Note:  C  and  several
     other languages prepend symbols they use with `_'.

     _etext
          The first location after the text of the program.

     _edata
          The first location after initialized data.

     _end The first location after all data.

     __DYNAMIC
          Identifies  an  ld-produced  data  structure.   It   is
          defined  with  a  non-zero  value  in executables which
          require execution-time link editing.  By convention, if
          defined,  it  is  the  first symbol in the symbol table



Sun Release 4.1   Last change: 21 January 1990                  9






LD(1)                    USER COMMANDS                      LD(1)



          associated with an a.out file.

     __GLOBAL_OFFSET_TABLE_
          A position-independent reference to  an  ld-constructed
          table  of  addresses.   This  table is constructed from
          "position-independent"  data  references  occurring  in
          objects  that  have been assembled with the assembler's
          -k flag (invoked on behalf of C compilations  performed
          with  the  -pic  flag).   A related table (for which no
          symbol is  currently  defined)  contains  a  series  of
          transfer  instructions  and  is created from "position-
          independent" procedure calls or, if -dp is specified to
          ld, a list of undefined symbols.

     Symbols in object files beginning  with  the  letter  L  are
     taken to be local symbols and unless otherwise specified are
     purged from ld output files.

ENVIRONMENT
     LD_LIBRARY_PATH
          A colon-separated  list  of  directories  in  which  to
          search  for  libraries  specified  with  the -l option.
          Similar   to    the    PATH    environment    variable.
          LD_LIBRARY_PATH  also  affects library searching during
          execution-time loading, causing the search to use first
          those  directories  found  in the environment variable,
          then any  directories  specified  by  -L  options,  and
          finally   the   standard   directories   /usr/lib   and
          /usr/local/lib.  NOTE:  when  running  a  set-user-  or
          set-group-ID   program,  ld.so  will  only  search  for
          libraries  in  directories  it  "trusts",   which   are
          /usr/lib,  /usr/5lib,  /usr/local/lib,  and  any direc-
          tories specified within the executable as a  result  of
          -L options given when the executable was constructed.

     LD_OPTIONS
          A default set of options to ld.  LD_OPTIONS  is  inter-
          preted  by  ld just as though its value had been placed
          on the command line,  immediately  following  the  name
          used to invoke ld, as in:

          example% ld $LD_OPTIONS ... other-arguments ...

     Note: Environment variable-names beginning with the  charac-
     ters  `LD_' are reserved for possible future enhancements to
     ld.

FILES
     /usr/lib/lib*.a     libraries
     lib*.so.v           shared libraries
     lib*.sa.v           exported,  initialized  shared   library
                         data



Sun Release 4.1   Last change: 21 January 1990                 10






LD(1)                    USER COMMANDS                      LD(1)



     /usr/lib/ld.so      execution-time ld
     /usr/lib/*crt*.o    default program bootstraps
     a.out               output file
     /usr/local/lib

SEE ALSO
     ar(1V),  as(1),  cc(1V),  lorder(1),  ranlib(1),   strip(1),
     tsort(1), ldconfig(8)

BUGS
     Options are being overloaded and are an inappropriate  vehi-
     cle  for  describing to ld the wide variety of things it can
     do. There needs to be a link-editing language which  can  be
     used in the more complex situations.

     The -r option does not properly  handle  programs  assembled
     with  the  -k  (position-independent)  flag, invoked from cc
     with -pic or -PIC.





































Sun Release 4.1   Last change: 21 January 1990                 11



