


gld(1)                GNU Development Tools                gld(1)



NAME
     gld - the GNU linker


SYNOPSIS
     gld  [-o _o_u_t_p_u_t] _o_b_j_f_i_l_e_s...
          [-A_a_r_c_h_i_t_e_c_t_u_r_e] [-b _i_n_p_u_t-_f_o_r_m_a_t] [-Bstatic]
          [-c _c_o_m_m_a_n_d_f_i_l_e] [-d|-dc|-dp]
          [-defsym _s_y_m_b_o_l = _e_x_p_r_e_s_s_i_o_n] [-e _e_n_t_r_y] [-F]
          [-F _f_o_r_m_a_t] [-format _i_n_p_u_t-_f_o_r_m_a_t] [-g] [-i] [-l_a_r]
          [-L_s_e_a_r_c_h_d_i_r] [-M|-m] [-n] [-noinhibit-exec]
          [-R _f_i_l_e_n_a_m_e] [-r|-Ur] [-S] [-s] [-T _c_o_m_m_a_n_d_f_i_l_e]
          [-Ttext _t_e_x_t_o_r_g] [-Tdata _d_a_t_a_o_r_g] [-Tbss _b_s_s_o_r_g] [-t]
          [-u _s_y_m] [-v] [-X] [-x] [{_s_c_r_i_p_t}]

DESCRIPTION
     gld combines a number of object and archive files, relocates
     their  data  and  ties  up symbol references. Often the last
     step in building a new compiled program to run is a call  to
     gld.

     gld accepts Linker Command Language files to provide  expli-
     cit  and  total  control over the linking process.  This man
     page does not describe the command language;  see  the  `ld'
     entry  in  `info',  or  the manual _g_l_d: _t_h_e _G_N_U _l_i_n_k_e_r , for
     full details on the command language and on other aspects of
     the GNU linker.

     This version of gld uses the general purpose  BFD  libraries
     to  operate  on  object files. This allows gld to read, com-
     bine, and write object files in many  different  formats-for
     example, COFF or a.out.  Different formats may be linked to-
     gether to produce any available kind of  object  file.   You
     can  use  `objdump -i' to get a list of formats supported on
     various architectures; see objdump(1).

     Aside from its flexibility, the GNU linker is  more  helpful
     than  other  linkers  in  providing  diagnostic information.
     Many linkers abandon execution immediately upon encountering
     an error; whenever possible, gld continues executing, allow-
     ing you to identify other errors (or, in some cases, to  get
     an output file in spite of the error).

     The GNU linker gld is meant to cover a broad range of situa-
     tions,  and to be as compatible as possible with other link-
     ers.  As a result, you have  many  choices  to  control  its
     behavior  through  the command line, and through environment
     variables.


OPTIONS
     The plethora of command-line options may seem  intimidating,



cygnus support    Last change: 5 November 1991                  1






gld(1)                GNU Development Tools                gld(1)



     but  in actual practice few of them are used in any particu-
     lar context.  For instance, a frequent use of gld is to link
     standard  Unix  object  files  on a standard, supported Unix
     system.  On such a system, to link a file hello.o:

     $ gld -o output /lib/crt0.o hello.o -lc

     This tells gld to produce a file called output as the result
     of linking the file /lib/crt0.o with hello.o and the library
     libc.a which will come from the standard search directories.

     The command-line options to gld may be specified in any ord-
     er, and may be repeated at will.  For the most part, repeat-
     ing an option with a different argument will either have  no
     further effect, or override prior occurrences (those further
     to the left on the command line) of an option.

     The exceptions-which may  meaningfully  be  used  more  than
     once-are  -A,  -b (or its synonym -format), -defsym, -L, -l,
     -R, and -u.

     The list of object files to be  linked  together,  shown  as
     _o_b_j_f_i_l_e_s,  may follow, precede, or be mixed in with command-
     line options; save that an  _o_b_j_f_i_l_e_s  argument  may  not  be
     placed between an option flag and its argument.

     Usually the linker is invoked with at least one object file,
     but  other forms of binary input files can also be specified
     with -l, -R, and the script command language.  If _n_o  binary
     input  files  at all are specified, the linker does not pro-
     duce any output, and issues the message `No input files'.

     Option  arguments  must  either  follow  the  option  letter
     without  intervening whitespace, or be given as separate ar-
     guments immediately following the option that requires them.


     _o_b_j_f_i_l_e_s...
          The object files _o_b_j_f_i_l_e_s to be linked.


     -A_a_r_c_h_i_t_e_c_t_u_r_e
           In the current release of gld, this option  is  useful
          only  for  the  Intel  960 family of architectures.  In
          that gld configuration, the  _a_r_c_h_i_t_e_c_t_u_r_e  argument  is
          one  of the two-letter names identifying members of the
          960 family; the option  specifies  the  desired  output
          target,  and  warns of any incompatible instructions in
          the input files.  It also modifies the linker's  search
          strategy  for  archive libraries, to support the use of
          libraries specific to each particular architecture,  by
          including  in  the  search loop names suffixed with the



cygnus support    Last change: 5 November 1991                  2






gld(1)                GNU Development Tools                gld(1)



          string identifying the architecture.

          For example, if your gld command line  included  `-ACA'
          as  well  as  `-ltry',  the  linker  would look (in its
          built-in search paths, and in  any  paths  you  specify
          with -L) for a library with the names

          try
          libtry.a
          tryca
          libtryca.a


          The first two possibilities would be considered in  any
          event; the last two are due to the use of `-ACA'.

          Future releases of gld may support similar functionali-
          ty for other architecture families.

          You can meaningfully use -A more than once on a command
          line,  if  an architecture family allows combination of
          target architectures; each use will add another pair of
          name  variants  to  search  for when -l specifies a li-
          brary.


     -b _i_n_p_u_t-_f_o_r_m_a_t
           Specify the binary format for input object files  that
          follow this option on the command line.  You don't usu-
          ally need to specify this, as gld is configured to  ex-
          pect as a default input format the most usual format on
          each machine.  _i_n_p_u_t-_f_o_r_m_a_t is a text string, the  name
          of  a particular format supported by the BFD libraries.
          -format _i_n_p_u_t-_f_o_r_m_a_t has the same effect.

          You may want to use this  option  if  you  are  linking
          files  with an unusual binary format.  You can also use
          -b to switch formats explicitly  (when  linking  object
          files  of  different  formats),  by including -b _i_n_p_u_t-
          _f_o_r_m_a_t before each group of object files in a  particu-
          lar format.

          The default format is taken from the environment  vari-
          able  GNUTARGET.   You can also define the input format
          from a script, using the command TARGET.


     -Bstatic
          This flag is accepted  for  command-line  compatibility
          with the SunOS linker, but has no effect on gld.





cygnus support    Last change: 5 November 1991                  3






gld(1)                GNU Development Tools                gld(1)



     -c _c_o_m_m_a_n_d_f_i_l_e
           Directs gld to read link commands from the  file  _c_o_m_-
          _m_a_n_d_f_i_l_e.   These  commands  will  completely  override
          gld's default link format (rather than adding  to  it);
          _c_o_m_m_a_n_d_f_i_l_e   must   specify  everything  necessary  to
          describe the target format.


          You may also include a script of link commands directly
          in  the  command  line by bracketing it between `{' and
          `}' characters.


     -d

     -dc

     -dp  These three options are equivalent; multiple forms  are
          supported  for  compatibility  with other linkers.  Use
          any of them to make ld assign space to  common  symbols
          even  if  a  relocatable output file is specified (-r).
          The script command FORCE_COMMON_ALLOCATION has the same
          effect.


     -defsym _s_y_m_b_o_l
           = _e_x_p_r_e_s_s_i_o_n Create a  global  symbol  in  the  output
          file,  containing the absolute address given by _e_x_p_r_e_s_-
          _s_i_o_n.  You may use this option as many times as  neces-
          sary to define multiple symbols in the command line.  A
          limited form of arithmetic is supported for the _e_x_p_r_e_s_-
          _s_i_o_n  in  this context: you may give a hexadecimal con-
          stant or the name of an existing symbol, or use + and -
          to  add  or  subtract hexadecimal constants or symbols.
          If you need more elaborate expressions, consider  using
          the linker command language from a script.


     -e _e_n_t_r_y
           Use _e_n_t_r_y as the explicit symbol for beginning  execu-
          tion  of  your  program,  rather than the default entry
          point.  for a discussion of defaults and other ways  of
          specifying the entry point.


     -F

     -F_f_o_r_m_a_t
           Some older linkers used this option throughout a  com-
          pilation  toolchain  for  specifying object-file format
          for both input and output object files.  gld's  mechan-
          isms  (the  -b  or -format options for input files, the



cygnus support    Last change: 5 November 1991                  4






gld(1)                GNU Development Tools                gld(1)



          TARGET command in linker scripts for output files,  the
          GNUTARGET  environment variable) are more flexible, but
          but it accepts (and ignores) the  -F  option  flag  for
          compatibility  with  scripts  written  to  call the old
          linker.


     -format _i_n_p_u_t-_f_o_r_m_a_t
           Synonym for -b _i_n_p_u_t-_f_o_r_m_a_t.


     -g   Accepted, but ignored; provided for compatibility  with
          other tools.


     -i   Perform an incremental link (same as option -r).


     -l_a_r  Add an archive file _a_r to the list of files  to  link.
          This  option  may be used any number of times.  ld will
          search its path-list for  occurrences  of  lib_a_r.a  for
          every _a_r specified.


     -L_s_e_a_r_c_h_d_i_r
           This command adds path _s_e_a_r_c_h_d_i_r to the list of  paths
          that  gld  will  search for archive libraries.  You may
          use this option any number of times.

          The default set of paths searched (without being speci-
          fied with -L) depends on what emulation mode gld is us-
          ing, and in some cases also on how it  was  configured.
          The  paths  can also be specified in a link script with
          the SEARCH_DIR command.


     -M

     -m   Print  (to  the  standard  output  file)  a  link  map-
          diagnostic  information  about where symbols are mapped
          by ld, and information on global common storage alloca-
          tion.


     -n   sets the text segment to be read only,  and  NMAGIC  is
          written if possible.


     -noinhibit-exec
          Normally, the linker will not produce an output file if
          it  encounters  errors  during  the link process.  With
          this flag, you can specify that  you  wish  the  output



cygnus support    Last change: 5 November 1991                  5






gld(1)                GNU Development Tools                gld(1)



          file retained even after non-fatal errors.


     -o _o_u_t_p_u_t
           _o_u_t_p_u_t _o_u_t_p_u_t is a name for the  program  produced  by
          ld;  if  this option is not specified, the name `a.out'
          is used by default.  The script command OUTPUT can also
          specify the output file name.


     -R _f_i_l_e_n_a_m_e
           _f_i_l_e  Read  symbol  names  and  their  addresses  from
          _f_i_l_e_n_a_m_e,  but  do not relocate it or include it in the
          output.  This allows your output file to refer symboli-
          cally  to absolute locations of memory defined in other
          programs.


     -r   Generates relocatable output-i.e., generate  an  output
          file  that  can in turn serve as input to gld.  This is
          often called _p_a_r_t_i_a_l linking.  As a side effect, in en-
          vironments  that  support  standard Unix magic numbers,
          this option also sets the output file's magic number to
          OMAGIC.   If  this option is not specified, an absolute
          file is produced.  When linking C++ programs, this  op-
          tion  _w_i_l_l  _n_o_t resolve references to constructors; -Ur
          is an alternative.

          This option does the same as -i.


     -S   Omits debugger symbol information (but not all symbols)
          from the output file.


     -s   Omits all symbol information from the output file.


     { _s_c_r_i_p_t }
          You can, if you wish, include a script of  linker  com-
          mands directly in the command line instead of referring
          to it via an input file.  When the character `{' occurs
          on  the command line, the linker switches to interpret-
          ing the command language until the end of the  list  of
          commands  is  reached-flagged with a closing brace `}'.
          Other command-line options will not be recognized while
          parsing  the  script.  for a description of the command
          language.


     -Tbss _o_r_g




cygnus support    Last change: 5 November 1991                  6






gld(1)                GNU Development Tools                gld(1)



     -Tdata _o_r_g

     -Ttext _o_r_g
          Use _o_r_g as the  starting  address  for-respectively-the
          bss,  data,  or  the  text  segment of the output file.
          _t_e_x_t_o_r_g must be a hexadecimal integer.


     -T _c_o_m_m_a_n_d_f_i_l_e


     -T_c_o_m_m_a_n_d_f_i_l_e
          Equivalent to -c _c_o_m_m_a_n_d_f_i_l_e; supported for compatibil-
          ity with other tools.


     -t   Prints names of input files as ld processes them.


     -u _s_y_m
           _s_y_m Forces _s_y_m to be entered in the output file as  an
          undefined symbol.  This may, for example, trigger link-
          ing of additional modules from standard libraries.   -u
          may  be  repeated  with  different  option arguments to
          enter additional undefined symbols.


     -Ur  For anything other than C++ programs,  this  option  is
          equivalent to -r: it generates relocatable output-i.e.,
          an output file that can in turn serve as input to  gld.
          When  linking C++ programs, -Ur _w_i_l_l resolve references
          to constructors, unlike -r.


     -v   Display the version number for gld.


     -X   If -s or -S is also specified, delete only  local  sym-
          bols beginning with `L'.


     -x   If -s or -S is also specified, delete  all  local  sym-
          bols, not just those beginning with `L'.


ENVIRONMENT
     gld always consults two environment variables: GNUTARGET and
     LDEMULATION.   Depending on the setting of the latter, other
     environment variables may be used as well.

     GNUTARGET determines the input-file  object  format  if  you
     don't  use -b (or its synonym -format).  Its value should be



cygnus support    Last change: 5 November 1991                  7






gld(1)                GNU Development Tools                gld(1)



     one of the BFD names for an input format.  If  there  is  no
     GNUTARGET in the environment, gld uses the natural format of
     the host. If GNUTARGET is set to default then  BFD  attempts
     to  discover  the  input  format  by  examining binary input
     files; this method often succeeds, but there  are  potential
     ambiguities,  since  there is no method of ensuring that the
     magic number used to flag  object-file  formats  is  unique.
     However,  the configuration procedure for BFD on each system
     places the conventional format for that system first in  the
     search-list, so ambiguities are resolved in favor of conven-
     tion.

     LDEMULATION controls some aspects  of  gld's  dominant  per-
     sonality.  Although gld is flexible enough to permit its use
     in many contexts regardless of configuration,  you  can  use
     this  variable to make it act more like one or another older
     linker by default.

     In particular, the value of LDEMULATION  controls  what  de-
     fault linker script is used (thereby controlling the default
     input and output formats; ; what default paths are  searched
     for  archive libraries; and in some cases whether additional
     linker script commands are available.

     Here is the current set of emulations available:


     LDEMULATION=gld
          Emulate the older GNU linker.  When this  emulation  is
          selected, the default library search paths are

          /lib
          /usr/lib
          /usr/local/lib/lib


          The default output format is set to  a.out-generic-big,
          and  the default machine is the system's configured BFD
          default.


     LDEMULATION=gld68k
          A variant of the gld emulation; only differs in specif-
          ically setting the default BFD machine as m68k.


     LDEMULATION=gld960
          Emulate the Intel port of the older gld  for  the  i960
          architectures.   The  default  library search paths are
          taken from two other environment variables, G960LIB and
          G960BASE.   The  default architecture is i960.  The de-
          fault output format is set to b.out.big,  and  in  fact



cygnus support    Last change: 5 November 1991                  8






gld(1)                GNU Development Tools                gld(1)



          the  default  output file name (if -o is not specified)
          is b.out, to reflect this variant format, for this emu-
          lation.

          This emulation can behave slightly differently  depend-
          ing  on  the  setting  of  the  gld compile-time switch
          GNU960.  If gld is compiled with GNU960  defined,  then
          an  additional environment variable-GNUTARGET-is avail-
          able; its value, if available, specifies some other de-
          fault output format than b.out.big.


     LDEMULATION=gldm88kbcs
          Sets the output format to m88kbcs and the  architecture
          to m88k.  Default library search paths are

          /lib
          /usr/lib
          /usr/local/lib



     LDEMULATION=lnk960
          Emulate the Intel linker lnk960.   The  default  output
          format  is  coff-Intel-big.   With  this emulation, gld
          supports the additional script commands HLL and  SYSLIB
          for  specification  of  library  archives.  This is the
          only emulation with extensive support for the  -A  (ar-
          chitecture)  command-line  option.  By default, the ar-
          chitecture CORE is assumed, but you  can  choose  addi-
          tional  features  from  the i960 architecture family by
          using one of the following with -A  (or  by  using  the
          OUTPUT_ARCH command from a script):

          CORE
          KB
          SB
          MC
          XA
          CA
          KA
          SA


          The default libraries are chosen with some attention to
          the architecture selected; the core library `cg' is al-
          ways included, but the library  fpg  is  also  used  if
          you've  specified  any  of the architectures KA, SA, or
          CA.

          Like gld960, this emulation uses additional environment
          variables  to  set  the  default  library search paths.



cygnus support    Last change: 5 November 1991                  9






gld(1)                GNU Development Tools                gld(1)



          Also like gld960, the behavior  of  this  emulation  is
          slightly  different depending on whether gld itself was
          compiled with GNU960 defined.

          If your gld was compiled with GNU960 defined,  the  de-
          fault  paths  are  taken  from  all  three  of G960LIB,
          G960BASE, and I960BASE.  For the first two,  paths  you
          supply  are automatically suffixed with `/lib/libcoff';
          for the last, your path is automatically suffixed  with
          `/lib'.

          If your gld was _n_o_t compiled with GNU960  defined,  the
          default  paths are taken from I960BASE, and G960BASE is
          only consulted if I960BASE is undefined.  In this  case
          G960LIB is not used at all.


     LDEMULATION=vanilla
          This is the least specific setting for  gld.   You  can
          set  LDEMULATION=vanilla  to disable emulation of other
          linkers.  This  setting  makes  gld  take  the  default
          machine  from  the  BFD  configuration  on your system;
          a.out-generic-big is the default target.  No other  de-
          faults are specified.


SEE ALSO
     objdump(1)
     `ld' and `binutils' entries in info
     _g_l_d: _t_h_e _G_N_U _l_i_n_k_e_r, Steve Chamberlain and Roland Pesch; _T_h_e
     _G_N_U _B_i_n_a_r_y _U_t_i_l_i_t_i_e_s, Roland H. Pesch.


COPYING
     Copyright (c) 1991 Free Software Foundation, Inc.

     Permission is granted to make and distribute verbatim copies
     of  this  manual provided the copyright notice and this per-
     mission notice are preserved on all copies.

     Permission is granted to copy and distribute  modified  ver-
     sions of this manual under the conditions for verbatim copy-
     ing, provided that the entire resulting derived work is dis-
     tributed under the terms of a permission notice identical to
     this one.

     Permission is granted to copy and distribute translations of
     this  manual  into  another language, under the above condi-
     tions for modified versions, except that this permission no-
     tice  may  be  included in translations approved by the Free
     Software Foundation instead of in the original English.




cygnus support    Last change: 5 November 1991                 10



