ld(1)									ld(1)



NAME

  ld, uld - link editor and ucode link editor

SYNOPSIS

  ld [ option ... ] file ...
  uld [ option ... ] file ...

DESCRIPTION

  The ld command invokes the DEC OSF/1 link editor which links extended coff
  object files.	 The archive format understood by ld is the one created by
  the archiver ar(1).

  The ld command combines several object files into one, performs relocation,
  resolves external symbols, builds tables and relocation information for
  run-time linkage in case of doing a shared link, and supports symbol table
  information for symbolic debugging.  In the simplest case, the names of
  several object files are given.  The ld command combines them, producing an
  object module that can be executed or used as input for a subsequent ld
  run.	(In the latter case, the -r option must be given to preserve the
  relocation entries.) The output of ld is left in a.out.  By default, this
  file is a dynamic executable if no errors occurred during the load.

  The argument object files are concatenated in the order specified.  The
  entry point of the output is the beginning of the text segment (unless the
  -e option is specified).

  The uld command combines several ucode object files and libraries into one
  ucode object file.  It ``hides'' external symbols for better optimizations
  by subsequent compiler passes.  The symbol tables of coff object files
  loaded with ucode object files are used to determine what external symbols
  not to ``hide'' along with files specified by the user that contain lists
  of symbol names.

  If any argument is a library, it is searched exactly once at the point it
  is encountered in the argument list.	There are two kinds of libraries,
  archives and dynamic shared objects.	Archives are used if the output is to
  be static.  In that case, only those object files defining an unresolved
  external reference are loaded.  Shared objects are normally used if the
  output is to be dynamic.  In that case, only the name is used for external
  resolution, no object is included as part of the output object file.

  The library (archive) symbol table (see ar(1)) is a hash table and is
  searched to resolved external references that can be satisfied by library
  members.  The ordering of library members is important.  See lorder(1).

  The following options are recognized by both ld and uld .  Those options
  used by one and not the other are ignored.  Any option can be preceded by a
  k (for example -ko outfile) and except for -klx have the same meaning with
  or without the preceding k.  This is done so that these options can be
  passed to both link editors through compiler drivers.

  Position-sensitive options affect link behavior for objects and libraries
  that follow the option in the command.  These options include -L, -all,
  -exclude, -exported_symbol, -hidden, -hidden_symbol, -kl, -l, -none,
  -non_hidden, and -no_archive.	 They are described in detail below.

  The symbols _etext, _edata, _end, _ftext, _fdata, _fbss, _gp, .fini, .data,
  .text, .init, .rdata, .sdata, .sbss, .bs, .lit4, .lit8, .comment, __istart,
  __fstart, data_init_table, _DYNAMIC, _DYNAMIC_LINK, _BASE_ADDRESS,
  _GOT_OFFSET, _procedure_tabl, _procedure_table_size,
  _procedure_string_table, _cobol_main, and _unwind are reserved.  If the
  -std1 flag is not set (see the cc(1|) reference page), the symbols etext,
  edata, end, and unwind are also reserved.  These loader defined symbols if
  referred to, are set their values as described in end(3).  Undefined
  results may occur if user code defines these symbols.

  Symbol names that start with __init_ and __fini_ have special meaning to
  the loader.  All routines that start with __init_ are treated, by default,
  as initialization routines.  These are routines that are called without an
  argument when the file that contains them is loaded, or when the program
  that contains them is started.  All routines that start with __fini_ are
  treated by default as termination routines, which are routines that are
  called without an argument when the file that contains them is unloaded, or
  when the program that contains them exits.

  Any executable program that references the builtin symbol _fpdata_size
  (either directly or through a shared object) and all shared objects,
  whether or not they reference the builtin symbol, cause ld to generate and
  include code and data to support exception handling.	For shared objects,
  this is always done because the person creating the shared object might not
  know whether the program referencing the shared object uses exception han-
  dling.  This support is needed so that the exception handling system can
  unwind stack frames and find handlers for exceptions.	 See
  exception_intro(3).

  Exception support consists of the following:

    +  Generating data structures that the exception system can use to per-
       form unwinds

    +  Generating .init and .fini section calls to register the exception
       data structures within the exception system

    +  Linking libexc_init.a, which contains a set of bridge routines that
       call the exception system registration routines.	 The libexc_init.a
       file is an object file with a .a suffix so that the -L option can be
       used to find it.

  The libc library has a set of dummy routines that replace the exception
  routines when the exception system is not present.  By default, this
  replacement works because libexc is generally specified libc on the link
  line.	 The cc(1) command ensures that libc is the last library on the com-
  mand line unless otherwise specified.	 Users requiring the exception system
  must not explicitly specify libc before libexc on the command line.

FLAGS

  When searching for libraries, ld looks for them, by default, in the follow-
  ing directories:

   1.  /usr/shlib

   2.  /usr/ccs/lib

   3.  /usr/lib/cmplrs/cc

   4.  /usr/lib

   5.  /usr/local/lib

   6.  /var/shlib

  You can alter the ld command's library directory search order for all
  libraries subsequently referenced on the command line by using the follow-
  ing position-dependent qualifiers.  Note that any of these options is
  effective only if it precedes the -l option on the command line for the
  libraries it is meant to affect.

  -Ldir
      Change the library directory search order for shared object and archive
      libraries (for instance, lib x.{so,  a}), and ucode object libraries
      (for instance, libx.b), so that ld looks for them in dir before the
      default library directories.

  -L  Change the library directory search order for shared object and archive
      libraries (libx.{so, a}), and ucode object libraries (libx.b), so that
      ld never looks for them in the default library directories.  Use this
      option when the default library directories should not be searched and
      only the directories specified by -Ldir are to be searched.

  -Kdir
      Eliminate the search of the default library directories and instead
      cause ld to search the single directory dir.  Instead of using this
      option, which is intended exclusively for the compiler driver, you
      should use the -L and -Ldir options in combination to obtain a similar
      effect.

  When linking a shared object, ld searches all library directories in order
  for the shared object library (libx.so).  If it cannot find the shared
  object library, it again searches all library directories in order for the
  archive library (libx.a).

  You use the following switch to alter the manner in which ld searches
  library directories for shared object and archive libraries:

  -oldstyle_liblookup
      Cause ld to search in order each library directory once, first for the
      shared object library (libx.so) and then for the archive library
      (libx.a).

  It omits the search for the archive library if the -no_archive option pre-
  cedes the library name on the ld command line.  When linking a ucode object
  library, ld searches the library directories in order for libx.b.

  Use the following position-dependent qualifiers to determine which
  libraries ld searches for in the library directories when resolving symbol
  names.  Note that, because ld searches for a shared object or archive
  library (or ucode object library) when it encounters its name on the com-
  mand line, the order of these options is significant.

  -lx Search a library libx.{so, a}, where x is a string.

  -qlx
      This option is identical to the -lx option in usage and behavior with
      this difference: if the library specified by -lx is not found, the
      linker does not produce error or warning messages.  However, the linker
      reports unresolved symbol errors and other link time errors normally.

  -klx
      Search a library libx.b, where x is a string.  These libraries are
      intended to be ucode object libraries.  In all other ways, this option
      is like the -lx option.

  The ld command also accepts the following options:

  -o outfile
      Produce an output object file by the name outfile. The name of the
      default object file is a.out.

  -p file
      Preserve (do not ``hide'') the symbol names listed in file when loading
      ucode object files.  The symbol names in the file are separated by
      blanks, tabs, or newlines.

  -s  Strip the symbolic information from the output object file.

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

  -r  Retain relocation entries in the output file.  Relocation entries must
      be saved if the output file is to become an input file in a subsequent
      ld run.  This option also prevents final definitions from being given
      to common symbols, and suppresses the `undefined symbol' diagnostics.

  -d  Force definition of common storage and define loader defined symbols
      even if -r is present.

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

  -F or -z
      Arrange for the process to be loaded on demand from the resulting exe-
      cutable file (413 format) rather than preloaded, a ZMAGIC file.  This
      is the default.

  -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, an NMAGIC file.  The default text
      segment address is 0x20000000 and the default data segment address is
      0x40000000.

  -nN 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, an NMAGIC file.  This involves mov-
      ing the data areas up to the first possible pagesize byte boundary fol-
      lowing the end of the text.

  -N  Place the data section immediately after the text and do not make the
      text portion read only or sharable, an OMAGIC file.  (Use "magic
      number" 0407.)

  -T num
      Set the text segment origin.  The argument num is a hexadecimal number.
      See the notes section for restrictions.

  -D num
      Set the data segment origin.  The argument num is a hexadecimal number.
      See the notes section for restrictions.

  -B num
      Set the bss segment origin.  The argument num is a hexadecimal number.
      This option can be used only if the final object is an OMAGIC file.

  -e epsym
      Set the default entry point address for the output file to be that of
      the symbol epsym.

  -m  Produce a map or listing of the input/output sections on the standard
      output (UNIX system V-like map).

  -M  Produce a primitive load map, listing the names of the files that will
      be loaded (UNIX 4.3bsd-like map).

  -S  Set silent mode and suppress non-fatal errors.

  -v  Set verbose mode.	 Print the name of each file as it is processed.

  -ysym
      Indicate each file in which sym appears, sym's type and whether the
      file defines or references sym.  Many such options may be given to
      trace many symbols.

  -V  Print a message giving information about the version of ld being used.

  -VS num
      Use num as the decimal version stamp to identify the a.out file that is
      produced.	 The version stamp is stored in the optional and symbolic
      headers.

  -f fill
      Set the fill pattern for ``holes'' within an output section.  The argu-
      ment fill is a four-byte hexadecimal constant.

  -b  Do not merge the symbolic information entries for the same file into
      one entry for that file.	This is only needed when the symbolic infor-
      mation from the same file appears differently in any of the objects to
      be linked.  This can occur when object files are compiled, by means of
      conditional compilation, with an apparently different version of an
      include file.

  -A file
      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, file, is the name of a file
      whose symbol table will be taken as a basis on which to define addi-
      tional 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 argu-
      ment 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 correct multiple for the resulting object type).  The default
      resulting object type is an OMAGIC file and the default starting
      address of the text is the old value of end rounded to SCNROUND as
      defined in the include file . Using the defaults, when this
      file is read into an already executing program the initial value of the
      break must also be rounded.

  -non_shared
      Produce a static executable.  The output object created will not use
      any shared objects during execution.  The -init and/or the -fini
      switches cannot be used in combination with the -non_shared switch.
      This is the default.

  -noprefix_recognition
      This option disables the automatic recognition of symbols prefixed with
      __init as initialization routines, and of symbols prefixed with __fini_
      as termination routines.	This option is only for applications that
      already have defined symbols with the prefixes __init_ or __fini_.

  -shared
      Produce a shared object.	This includes creating all of the tables for
      run-time linking and resolving references to other specified shared
      objects.	The object created may be used by the linker to make dynamic
      executables.

  -call_shared
      Produce a dynamic executable.  The object created may use shared
      objects at run-time.

  -hidden_symbol symbol
      Used for shared linkage.	The linker turns the symbol following this
      flag into a local.  This must appear before the symbol is used or
      defined.

  -hidden
      Turns all external symbols from objects following this flag into
      locals.  This option is meaningful for shared linkage only.

  -exported_symbol  pattern
      Turns off the hidden option for a single symbol, specified by pattern.
      Pattern matching uses shell wildcard characters (?, *, [, ]).  For more
      information, see sh(1).

  -expect_unresolved pattern
      Any unresolved symbols matching pattern are not displayed and are not
      treated as errors or warnings.  You can enter this option multiple
      times.  The patterns use shell wildcard characters (?, *, [, ]) which
      must be properly quoted so they will not be expanded by the shell.  For
      more information, see sh(1).

  -warning_unresolved
      Unresolved symbols, except those matching -expect_unresolved, produce a
      warning message.	This is the default behavior for building shared
      libraries.

  -error_unresolved
      Unresolved symbols, except those matching -expect_unresolved, produce
      an error and the link fails.  This is the default behavior for linking
      executable programs.

  -all
      Link in all of the objects from the archives following this flag.	 This
      option is used in conjunction with -shared option to create a shared
      object.

  -none
      Turns off the -all option.

  -exclude object
      Used in conjunction with -all and -shared.  The object specified will
      be excluded in making the shared object.

  -no_archive
      Requires that -l references must resolve to shared objects.  Normally,
      if the shared object as specified by the -l is not found, the linker
      attempts to find the corresponding archive to resolve undefined sym-
      bols.  This option disallows using those archives.  Note that this
      option is positional and can be used more than once.  It affects only
      those options that follow it.

  -check_registry location_file
      Check the location of this shared object's segments and make sure they
      stay out of the way of others in the location_file.  Multiple instances
      of this option are allowed.  This option is used with -shared.

  -update_registry location_file
      Register the location of this shared object's segments and make sure
      they stay out of the way of others in the location_file.	Location_file
      is updated if it is writable.  This option is used with -shared.

  -no_library_replacement
      Turns on a flag in the dynamic section so that rld does not allow exec-
      time or run-time changing of the path (except for super user) to find
      the shared objects.  Typically, used for security purposes on system
      utilities.

  -rpath path
      Creates an rpath record containing the specified path string.  The path
      string is a colon-separated list of directories that is meaningful only
      when creating an executable with shared linkage.	Additional rpath
      directories found in shared objects on the link command line will be
      appended to path.	 Duplicate entries will be excluded.  The run-time
      loader uses the rpath record to search for shared libraries at run
      time.

  -soname shared_object_name
      Sets DT_SONAME for a shared object.  Use in conjunction with -shared
      option.  The name may be a single component name (e.g. libc.a), a full
      (starting with a slash), or relative pathname (containing a slash).
      The default DT_SONAME used for shared objects is the filename component
      of the output file name.	Specify the output file name using the -o
      option as described above.

  -init symbol
      Make the procedure represented by the symbol an initialization routine,
      which is a routine that is called without an argument when the file
      that contains the routine is loaded, or when the program that contains
      the routine is started.

  -fini symbol
      Make the procedure represented by the symbol a termination routine,
      which is a routine that is called without an argument when the file
      that contains the routine is unloaded, or when the program that con-
      tains the routine exits.

  -transitive_link
      Causes ld to link in any shared object that occurs in the dependency
      list in addition to those shared objects on the link command line.  If
      ld cannot find the shared object in the dependency list, it will cause
      a fatal error.

  -O0 Turns off all code optimizations performed by the ld.  This is the
      default.

  -O1 Turns on the code optimizations that can be performed quickly with lit-
      tle additional time and memory overhead during the link.	Note that
      cc(1) passes -O1 as the default when linking.

  -O2, -O3
      Turns on all code optimizations that can be performed by the linker.

  -exact_version
      Sets a flag in the dynamic object produced by the linker, asking the
      run-time loader to ensure that the shared libraries this dynamic object
      uses at run time match the shared libraries referenced at link time.
      By default, a shared library's version is included in the match test.
      This option requires a stricter test which includes shared library
      checksums and timestamps.

      This option is used when building a dynamic executable file (with
      -call_shared) or a shared library (with -shared).

  -set_version version-string
      Establishes the version identifier (or identifiers) associated with a
      shared library.  The string version-string is either a single version
      identifier or a colon-separated list of version identifiers.  No res-
      trictions are placed on the names of version identifiers; however, it
      is highly recommended that UNIX directory naming conventions be fol-
      lowed.

      If a shared library is built with this option, any executable built
      against it will record a dependency on the specified version or, if a
      list of version identifiers is specified, the rightmost version speci-
      fied in the list.	 If a shared library is built with a list of version
      identifiers, the run-time loader will allow any executable to run that
      has a shared library dependency on any of the listed versions.

      This option is only useful when building a shared library (with
      -shared).

  -depth_ring_search
      This option is used in conjunction with -call_shared.  The linker sets
      a flag in dynamic objects requesting a depth_first, ring_search method
      for resolving symbol references between shared objects.  See loader(5)
      for a complete description of this alternate symbol resolution policy.

  -taso
      This option tells the linker that the executable should be loaded in
      the lower 31-bit addressable virtual address range.  The -T and -D
      options to the ld(1) command can also be used to ensure that the text
      and data segments addresses, respectively, are loaded into low memory.
      The -taso option, however, in addition to setting default addresses for
      text and data segments, also causes shared libraries linked outside the
      31-bit address space to be appropriately relocated by the loader.	 If
      you specify -taso and also specify text and data segment addresses with
      -T and -D, those addresses override the -taso default addresses.	The
      -taso option is useful for porting 32-bit programs to the DEC OSF/1
      operating system.

  -om Generates an OMAGIC file suitable for input to the om post-link optim-
      izer.  This flag should be used only with the cc command.

OBJECT AND LIBRARY ORDERING

  The ordering of object files, archive libraries and shared libraries on the
  command line affects how symbols are resolved.  For example, if an archive
  library is ordered before an object file or shared library that references
  one of its symbols, the linker may report that symbol as unresolved.

  Unresolved symbol errors can be avoided by following the suggestions below:

    +  Object files should be ordered before all archive libraries and shared
       libraries.

    +  If archives and shared libraries cannot be specified in dependency
       order, shared libraries should be ordered before archive libraries.

    +  If necessary, archives can be specified more than once on the link
       command line.

  Symbols defined in object files are always included in the output object.
  Ordering object files first might prevent the inclusion of conflicting sym-
  bols also defined in archive libraries or shared libraries specified on the
  link command line.

  As each object, archive library and shared library is processed by ld, new
  symbol definitions and references are added to the output object.  If a
  symbol reference is added for a symbol that does not yet have an associated
  symbol definition, it is an "undefined" symbol.  The linker must find a
  definition of each undefined symbol in an object, archive, or shared
  library occurring later on the command line.


  When the linker processes an archive library, it extracts objects from the
  archive that define any symbols that are currently undefined.	 As each
  object is extracted from an archive library, the linker processes the
  object, identifies any additional "undefined" symbols, and extracts the
  objects which define those symbols.

  When the linker processes a shared library, it extracts symbol definitions
  from the shared library for symbols that are currently undefined.  These
  symbol definitions are added to the output object.  The shared library
  might also define many symbols that are not added to the output object.
  These symbols will not be considered as additional objects.  Archive
  libraries and shared libraries are processed; however, the linker will not
  report these symbols as unresolved if they are referenced in objects
  ordered after the shared library on the command line.

  The linker also identifies new undefined symbols while processing a shared
  library.  These undefined symbols are not added to the output object and
  are not reported as unresolved, but the linker will consider these unde-
  fined symbols as it processes additional objects on the command line.

COMMON SYMBOL RESOLUTION

  A symbol's class determines how the linker will resolve it, particularly
  when there are multiple objects, archives and shared libraries on the com-
  mand line that define the same symbol.  In general, if the linker processes
  more than one object defining the same text or data symbol, it will report
  an error indicating that the symbol is multiply defined.  On the other
  hand, certain classes of symbols such as commons and allocated commons can
  be defined in multiple objects and libraries without causing multiple-
  definition errors.

  The linker uses symbol class, size, and command-line ordering to determine
  which symbol definition to use in the output object.	Symbols are selected
  according to the following precedence, in descending order:

   1.  Data or text

   2.  Largest allocated common

   3.  Largest common

  Common symbols are characterized by their size and type only.	 These sym-
  bols are displayed as type "C" in nm output.

  Allocated common symbols are commons that have an address as well as a size
  and type.  These symbols are displayed as type "S" or "B" in nm output.
  All other symbols are either data, text, or undefined.

  The linker searches archive libraries only to extract symbols that are
  undefined.  It does not replace an existing symbol definition with a symbol
  of higher precedence extracted from an archive.  The linker applies the
  precedences rules only when choosing between multiple symbol definitions in
  object files and shared libraries.

NOTES

  Any of the three types of objects can be run on DEC OSF/1 systems.  The
  segments must not overlap and all addresses must be less than
  0x40000000000.  The stack starts below the text segment and grows through
  lower addresses so space should be left for it.  For ZMAGIC files the
  default text segment address is 0x120000000 and the default data segment
  address is 0x140000000.

  For NMAGIC files the default text segment is 0x20000000 and the default
  data segment address is 0x40000000.  For OMAGIC files the default text seg-
  ment address is 0x10000000 with the data segment following the text
  segment.  The default for all types of files is that the bss segment fol-
  lows the data segment.

  An additional constraint is that all addresses within an executable's data
  segment must not be any farther than 0x7fff8000 from all addresses within
  the text segment.

  The bss segment has no distance requirement for NMAGIC and ZMAGIC files.
  For OMAGIC files to be run under the operating system, the -B flag should
  not be used because the bss segment must follow the data segment, which is
  the default.

FILES

  /usr/shlib/lib*.so
	       shared libraries

  /usr/ccs/lib/*
	       libraries, include files, and other files

  /usr/lib/cmplrs/cc/*
	       compiler executable files

  /usr/lib     directory

  /usr/local/lib
	       directory

  a.out	       output file

RELATED INFORMATION

  as(1), ar(1), cc(1), end(3), loader(5)
  Programmer's Guide
  Assembly Language Programmer's Guide