[0m


LD(1)		    UNIX Programmer's Manual		    LD(1)



[1mNAME
     [0mld - link editor

[1mSYNOPSIS
     ld [0m[ option ] ... file ...

[1mDESCRIPTION
     [0m_l_d combines several object programs into one, resolves
     external references, and searches libraries.  In the sim-
     plest case several object _f_i_l_e_s are given, and _l_d combines
     them, producing an object module which can be either exe-
     cuted or become the input for a further _l_d run.  (In the
     latter case, the [1m-r [0moption must be given to preserve the
     relocation bits.) The output of _l_d is left on [1ma.out[0m.  This
     file is made executable only if no errors occurred during
     the load.

     The argument routines are concatenated in the order speci-
     fied.

     If any argument is a library, it is searched exactly once at
     the point it is encountered in the argument list.	Only
     those archive members defining an unresolved external refer-
     ence are loaded.  If a member from a library references
     another member in the library, and the library has not been
     processed by _r_a_n_l_i_b(1), the referenced routine must appear
     after the referencing routine in the library.  Thus the
     order of programs within libraries may be important.  See
     _t_s_o_r_t(1), _l_o_r_d_e_r(1).  The first member of a library should
     be a file named `__.SYMDEF', which is understood to be a
     dictionary for the library as produced by _r_a_n_l_i_b(1); the
     dictionary is searched iteratively to satisfy as many refer-
     ences as possible.

     The symbols `__etext', `__edata', `__end', `__estext' and
     `__esdata' (`_etext', `_edata', `_end', `_estext' and
     `_esdata' in C) are reserved, and if referred to, are set to
     the first location above the program, the first location
     above initialized data, the first location above all program
     data, the first location after shared library text and the
     first location in shared library data respectively.  It is
     erroneous to define these symbols.

     _l_d understands several options.  The option [1m-A [0mmust come
     before all file name or [1m-l [0marguments, with this exception
     option order, except for [1m-D[0m, is unimportant.  Argument order
     is obviously crucially important because _l_d only makes a
     single pass over the arguments to determine symbol defini-
     tions.

     [1m-A   [0mThis option specifies incremental loading, i.e.  link-
	  ing is to be done in a manner so that the resulting



Printed 31/1/92     Revision 1.10 of 22/11/90			1






LD(1)		    UNIX Programmer's Manual		    LD(1)



	  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 addi-
	  tional symbols.  Only newly linked material will be
	  entered into the text and data portions of [1ma.out[0m, 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 argu-
	  ment list.  Incremental loading is incompatible with
	  the use of shared libraries - although the argument to
	  [1m-A [0mmay refer to a shared library nothing included in
	  the linked output may.  The [1m-T [0moption may be used as
	  well, and will be taken to mean that the newly linked
	  segment will commence at the corresponding address.
	  The default value is the old value of `__end'.

     [1m-d   [0mForce definition of common storage even if the [1m-r [0mflag
	  is present.  This option also causes _l_d to output a
	  list of undefined symbols when [1m-r [0mis present, however
	  [1m-r [0mstill prevents the definition of `__end', `__edata'
	  and `__etext'.

     [1m-e   [0mThe following argument is taken to be the name of the
	  entry point of the loaded program; the symbol `start'
	  is the default.  Note that this is only of use for
	  assembler programs, since high level languages require
	  a run time environment which must be entered before any
	  user routines are called.

     [1m-i   [0mProduce impure demand load output - a demand loadable
	  executable with a writable text segment.  The output
	  has magic number 0613.

     [1m-L[0m_d_i_r
	  Add _d_i_r to the list of directories in which libraries
	  are searched for.  Directories specified with [1m-L [0mare
	  searched before the standard directories.  All [1m-L [0margu-
	  ments are read before _l_d starts to read the input argu-
	  ments - thus although order is important within the [1m-L
	  [0marguments order relative to other arguments is not.
	  The default list of directories is `/usr/lib' then
	  `/usr/local/lib'.

     [1m-l[0m_x  This option is an abbreviation for the library name
	  `lib_x.a', where _x is a string.  _l_d searches for
	  libraries first in any directories specified with [1m-L
	  [0moptions, then in the standard directories `/usr/lib'
	  and `/usr/local/lib' (see the description of [1m-L[0m.) A
	  library is searched when its name is encountered, so
	  the placement of a [1m-l [0mis significant.

     [1m-M   [0mproduce a primitive load map, listing the names of the



Printed 31/1/92     Revision 1.10 of 22/11/90			2






LD(1)		    UNIX Programmer's Manual		    LD(1)



	  files which will be loaded.

     [1m-o   [0mThe _n_a_m_e argument after [1m-o [0mis used as the name of the
	  _l_d output file, instead of [1ma.out[0m.

     [1m-N   [0mDo not make the text portion read only or sharable.
	  (Use `magic number' 0407.) The resultant executable
	  cannot be loaded by the kernel (only demand loadable
	  executables are supported.) [1m-N [0mshould only be used when
	  producing output for use in a further link step.

     [1m-Q   [0mSqueeze the output executable, which must be in demand
	  load format.	The program _s_q_u_e_e_z_e(1) must exist on the
	  path of _l_d for this to work.

     [1m-r   [0mGenerate relocation bits in the output file so that it
	  can be the subject of another _l_d run.  This flag also
	  prevents final definitions from being given to common
	  symbols, and suppresses the `undefined symbol' diagnos-
	  tics.  The output will have magic number 0407 (OMAGIC.)

     [1m-s   [0m`Strip' the output, that is, remove the symbol table
	  and relocation bits to save space (but impair the use-
	  fulness of the debuggers).  This information can also
	  be removed by _s_t_r_i_p(1).

     [1m-t   [0m(`trace')  Print the name of each file as it is pro-
	  cessed.

     [1m-u   [0mTake the following argument as a symbol and enter it as
	  undefined in the symbol table.  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.

     [1m-X   [0mSave local symbols except for those whose names begin
	  with `L'.  This option is used by _c_c(1) to discard
	  internally-generated labels while retaining symbols
	  local to routines.

     [1m-x   [0mDo not preserve local (non-.globl) symbols in the out-
	  put symbol table; only enter external symbols.  This
	  option saves some space in the output file.

     [1m-y[0m_s_y_m
	  Indicate each file in which _s_y_m 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 _s_y_m with an `_', as external
	  C, FORTRAN and Pascal variables begin with under-
	  scores.)




Printed 31/1/92     Revision 1.10 of 22/11/90			3






LD(1)		    UNIX Programmer's Manual		    LD(1)



     [1m-z   [0mArrange for the process to be loaded on demand from the
	  resulting executable file (413 format) rather than
	  preloaded.  This is the default.  Results in a 32768
	  byte header on the output file followed by a text and
	  data segment each of which have size a multiple of
	  _p_a_g_e_s_i_z_e bytes (default 32768 - see [1m-P[0m.) The file is in
	  effect padded with nulls.  With this format the first
	  few BSS segment symbols may be placed at the end of the
	  data segment of the output.  This is to avoid wasting
	  space resulting from the data segment size roundup.

     [1m-Z   [0mProduce a shared library.  The output is in a suitable
	  format for the kernel to load as a shared library.  The
	  magic number has the `I am a shared library' flag set.
	  The data used by the library is placed at the top of
	  the address space (above the stack.)	The entry point
	  stored in the output _a._o_u_t file is set to the address
	  of the first byte of the data.

     The following options are not used for normal programs,
     since they can easily produce images that the kernel will
     not correctly run. They can be used in cross-development
     environments or as modifiers to some of the other options
     (e.g.  [1m-A [0mand [1m-Z[0m).  They should be used with caution.

     [1m-B   [0mSet the base of the text portion of the output - unlike
	  [1m-T [0mthis causes a gap to be left in the output
	  corresponding to the difference between the origin of
	  the text segment and the base of the output text, the
	  resulting executable will thus execute correctly when
	  loaded by the kernel.  The argument is a hexadecimal
	  number.

     [1m-D   [0mTake the next argument as a hexadecimal number and pad
	  the data segment with zero bytes to the indicated
	  length.  The argument may appear between input files.

     [1m-E   [0mThe next argument is interpreted as a hexadecimal
	  number addressing the byte beyond the end of the data
	  segment of the program.  Thus [1m-E [0mspecifies the value _l_d
	  will give to `__end'.  The option is not compatible
	  with [1m-H[0m.  [1m-H [0mis normally used with [1m-Z [0mto specify the
	  position of shared library data.

     [1m-H   [0mThe next argument is interpreted as a decimal number
	  specifying the size of a hole between the text and data
	  segments.  The option is not compatible with [1m-E[0m.

     [1m-P   [0mThe next argument is interpreted as a hexadecimal
	  number defining the page size of the target machine.
	  This is used to determine the rounding used for the
	  text segment size of demand loaded output.  The default



Printed 31/1/92     Revision 1.10 of 22/11/90			4






LD(1)		    UNIX Programmer's Manual		    LD(1)



	  is 32768 (hex 8000.)

     [1m-T   [0mThe next argument is a hexadecimal number which sets
	  the text segment origin.  The default origin is 32768
	  (hex 8000.)  If the text segment origin is changed the
	  kernel will not be able to (correctly) load the execut-
	  able.  See also [1m-E[0m.

[1mDIAGNOSTICS
     [0m_l_d detects two significant user errors - undefined symbols
     and multiply defined symbols.  Undefined symbols arise when
     a reference to an external symbol is not resolved by a
     definition of the same (external) symbol in another input
     file or archive member.  This is an error unless the [1m-r
     [0moption is given.

     Multiply defined symbols arise when two or more modules con-
     tain a definition of the same external symbol and the defin-
     itions are different - _l_d will allow multiple definitions if
     they have the same value (after relocation.)

     With correctly formed input modules this only applies to
     external symbols - it is impossible to form undefined non-
     external symbols with the normal tools, and non-external
     symbols are not used to resolve external references, there-
     fore multiple definitions are impossible.

     When using shared libraries multiple definitions may occur
     with programs which work with the equivalent non-shared
     libraries.  This is because a shared library defines a large
     number of symbols, many of which would not have been
     included if the program had been linked with a non-shared
     library.  Thus programs which accidentally redefine symbols
     from a library will give rise to multiple symbol declara-
     tions when linked with a shared version of the library.  In
     many cases this will be a genuine bug in the program (wher-
     ever parts of the library which the program uses depend on
     the original definition of the symbol in question.)

     The only sure way of avoiding multiple declarations of sym-
     bols in a system which uses separate compilation is to adopt
     a naming convention for external function and data symbols
     which guarantees that they are unique.  One typical scheme
     uses names of the form "module_name", where "name" is a
     descriptive name appropriate to the function or data, and
     "module" is a name for a small piece of code containing
     closely related functions - normally confined to a single
     source file.

     Notice that _l_d is not capable of doing even the most basic
     type checking of a symbol - no information is stored with an
     undefined symbol to say whether it is expected to be a



Printed 31/1/92     Revision 1.10 of 22/11/90			5






LD(1)		    UNIX Programmer's Manual		    LD(1)



     reference to text or data, thus _l_d will quite happily
     satisfy a request for a definition of a symbol refering to a
     byte of (writable) data with a symbol refering to a func-
     tion.

[1mFILES
     [0m/usr/lib/lib*.a	    libraries
     /usr/local/lib/lib*.a  more libraries
     a.out		    output file

[1mSEE ALSO
     [0mas(1), ar(1), cc(1), ranlib(1), mkshare(1), phead(1),
     strip(1), tsort(1), lorder(1), squeeze(1), unsqueeze(1)

[1mBUGS
     [0mSpecifying the option [1m-T [0mcreates an executable which the
     kernel will load into the wrong place - normally resulting
     in the program immediately crashing.  Other combinations of
     options can have similar effects.	This is because the _a._o_u_t
     header does not contain sufficient information to allow text
     and data to be loaded into arbitrary positions in the
     address space.

[1mFEATURES
     [0mThe option [1m-n [0mis not supported - it should produce read-only
     text executables which are not demand loadable (NMAGIC -
     0410 magic number.)  There is never any advantage in using
     this format.  Thus the option is converted (with a warning)
     to [1m-z[0m.

     The shared library scheme is a simple one.  Programs may
     share the text in a shared library by being linked with it.
     Each program may depend on only one shared library (although
     that shared library may itself depend on another).  There is
     no support for dynamic loading or other niceties.




















Printed 31/1/92     Revision 1.10 of 22/11/90			6



[0m