ld man page on 4.4BSD

Man page or keyword search:  
man Server   1065 pages
apropos Keyword Search (all sections)
Output format
4.4BSD logo
[printable version]

LD(1)									 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:

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

	      ·	 ar(1V) library archives (.a), or “libraries”

	      ·	 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  com‐
       bined 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 command.

       Options should appear before filenames, except for abbreviated  library
       names specified with -l options, and some binding control options spec‐
       ified by -B (which can appear anywhere in the line).

       -align datum
	      Force the global uninitialized data symbol datum (usually a FOR‐
	      TRAN  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 performed.  The
	      assertion desired is specified by the assertion-keyword  string.
	      ld is silent if the assertion holds, else it yields a diagnostic
	      and aborts.  Valid assertion-keyword's and their interpretations
	      are:

		     definitions    If	the  resulting	program	 were run now,
				    there would be no run-time undefined  sym‐
				    bol 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 relocation 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  pro‐
	      gram.  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  cor‐
	      responding  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  follow.
	      Allowed values of binding-keyword are:

	      dynamic	     Allow  dynamic  binding:  do not resolve symbolic
			     references, allow creation of run-time symbol and
			     relocation	  environment.	  -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  specified.   Influences
			     handling  of all objects following its specifica‐
			     tion 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  com‐
	      mon symbols to be allocated in the current ld run, even when the
	      -r flag is present (which would otherwise 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 relocation at run-time.  In
	      such a case, the optional .v suffix 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
	      permits the construction of software that uses shared objects as
	      libraries not residing in	 the  standard	locations  and	avoids
	      requiring	 the  specification of the LD_LIBRARY_PATH environment
	      variable in order to execute  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 relative 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 boundary, 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” diagnostics.

       -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).

       -S     Strip the output by removing all symbols except locals and glob‐
	      als.

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

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

       -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 symbol 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 usually  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  exe‐
	      cutable  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 actually 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 con‐
       trol options specified by `-B' and the abbreviated library-names speci‐
       fied by `-l'.  These may appear anywhere, and their influence is depen‐
       dent upon their location.  Some options may be obtained	from  environ‐
       ment  variables, such options are interpreted before any on the command
       line (see ENVIRONMENT, below).

   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 simple 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 concatenated to the output.	If a member of
       an archive references 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 ranlib(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 symbols defined by members of  the
       archive.

       Sharable	 objects  (.so)	 are scanned for symbol definitions and refer‐
       ences, but are not normally included in the output from ld,  except  in
       cases  where  a	shared library exports initialized 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 during 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 determined 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 variable LD_LIBRARY_PATH,  and
       finally,	 the  built-in	list  of  standard  library directories: /lib,
       /usr/lib, and /usr/local/lib.

   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 symbolic refer‐
			ences, and allow creation of execution-time symbol and
			relocation information.	 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 command 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 reduction,” ld must be able to determine that:

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

	      ·	 the program has an entry point, and symbolic reduction can be
		 performed for all symbols having definitions 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 particular, 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 exe‐
       cutable in which their definition appears.

       After  ld has performed all the symbolic reductions it can, it attempts
       to transform all relative references to absolute 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
       performing 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 completed, the exe‐
       cutable will require further link editing at execution time in order to
       be usable.  Such executables contain 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” executable.

       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 influenced by the setting of	LD_LIBRARY_PATH	 and  any  -L  options
       specified  to  ld when the program was built.  ld.so then completes all
       remaining relocations, with the exception  of  procedure	 call  reloca‐
       tions;  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 produced 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 something wrong in  the  mainte‐
       nance  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 infor‐
       mation.	The .so files used as such “shared libraries”  are  post-fixed
       with  a	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 version” 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 acceptable.  The
       rules are:

	      ·	 Major Versions Identical: the major version used at execution
		 time  must exactly match the version found at ld-time.	 Fail‐
		 ure to find an instance of the library with a matching	 major
		 version  causes  a  diagnostic to be issued and the program's
		 execution to be terminated.

	      ·	 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 ver‐
		 sion found at ld-time, a warning diagnostic is	 issued;  pro‐
		 gram 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 pro‐
       grams 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 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-indepen‐
	      dent” data references occurring in objects that have been assem‐
	      bled with the assembler's -k flag (invoked on behalf of C compi‐
	      lations  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	 unde‐
	      fined 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 directories	speci‐
	      fied  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 interpreted 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  characters	 `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
       /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), ldcon‐
       fig(8)

BUGS
       Options are being overloaded  and  are  an  inappropriate  vehicle  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 situa‐
       tions.

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

				21 January 1990				 LD(1)
[top]

List of man pages available for 4.4BSD

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net