ld

Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services

NAME

       ld - the GNU linker



SYNOPSIS

       ld     [-o output] objfile...
              [-Aarchitecture] [-b input-format] [-Bstatic]
              [-Bdynamic] [-Bsymbolic] [-c commandfile]
              [-d|-dc|-dp]
              [-defsym symbol = expression] [-e entry]
              [-embedded-relocs] [-E] [-export-dynamic] [-F]
              [-F format] [-format input-format] [-g] [-G size]
              [--help] [-i] [-lar] [-Lsearchdir] [-M] [-Map
              mapfile] [-m emulation] [-n|-N] [-noinhibit-exec]
              [-no-keep-memory] [-oformat output-format]
              [-R filename] [-relax] [-r|-Ur] [-rpath directory]
              [-rpath-link directory] [-S] [-s] [-shared]
              [-sort-common] [-split-by-reloc count]
              [-split-by-file] [-T commandfile] [-Ttext textorg]
              [-Tdata dataorg] [-Tbss bssorg] [-t] [-u sym] [-V]
              [-v] [--verbose] [--version] [-warn-common]
              [-warn-constructors] [-warn-multiple-gp]
              [-warn-once] [--whole-archive] [--no-whole-archive]
              [--wrap symbol] [-X] [-x]


DESCRIPTION

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

       ld accepts Linker Command Language files  to  provide  ex-
       plicit  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 ld: the GNU linker ,
       for full details on the command language and on other  as-
       pects of the GNU linker.

       This  version of ld uses the general purpose BFD libraries
       to operate on object files. This allows ld to  read,  com-
       bine,  and  write object files in many different formats--
       for example, COFF or  a.out.   Different  formats  may  be
       linked  together  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 encounter-
       ing an error; whenever possible, ld  continues  executing,
       allowing  you to identify other errors (or, in some cases,
       to get an output file in spite of the error).

       The GNU linker ld is meant to cover a broad range of situ-
       ations,  and  to  be  as compatible as possible with other
       linkers.  As a result, you have many  choices  to  control
       its  behavior  through the command line, and through envi-
       ronment variables.



OPTIONS

       The plethora of command-line options may  seem  intimidat-
       ing,  but  in  actual practice few of them are used in any
       particular context.  For instance, a frequent use of ld is
       to link standard Unix object files on a standard, support-
       ed Unix system.  On such a system, to link a file hello.o:

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

       This  tells  ld to produce a file called output as the re-
       sult 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 ld may be specified in any or-
       der,  and may be repeated at will.  For the most part, re-
       peating 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  op-
       tion.

       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
       objfile, may follow, precede, or be mixed in with command-
       line  options;  save  that  an objfile 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  no binary input files at all are specified, the linker
       does not produce 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
       arguments  immediately  following the option that requires
       them.


       -Aarchitecture
              In the current release of ld, this option is useful
              only for the Intel 960 family of architectures.  In
              that ld configuration, the architecture 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 in-
              structions 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 string identifying the
              architecture.

              For  example,  if  your  ld  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 ld may support similar function-
              ality for other architecture families.

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


       -b input-format
              Specify  the  binary  format for input object files
              that follow this option on the command  line.   You
              don't  usually  need to specify this, as ld is con-
              figured to expect as a  default  input  format  the
              most usual format on each machine.  input-format is
              a text string, the name of a particular format sup-
              ported  by the BFD libraries.  -format input-format
              has the same effect, as  does  the  script  command
              TARGET.

              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
              input-format before each group of object files in a
              particular format.

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


       -Bstatic
              Do not link against shared libraries.  This is only
              meaningful  on platforms for which shared libraries
              are supported.


       -Bdynamic
              Link against dynamic libraries.  This is only mean-
              ingful  on platforms for which shared libraries are
              supported.  This option is normally the default  on
              such platforms.


       -Bsymbolic
              When  creating a shared library, bind references to
              global symbols to the definition within the  shared
              library,  if  any.   Normally, it is possible for a
              program linked against a shared library to override
              the definition within the shared library.  This op-
              tion is only meaningful on ELF platforms which sup-
              port shared libraries.


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


              You  may also include a script of link commands di-
              rectly 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 speci-
              fied (-r).  The script command FORCE_COMMON_ALLOCA-
              TION has the same effect.


       -defsym symbol = expression
              Create a global symbol in the output file, contain-
              ing  the absolute address given by expression.  You
              may use this option as many times as  necessary  to
              define  multiple  symbols  in  the command line.  A
              limited form of arithmetic is supported for the ex-
              pression  in this context: you may give a hexadeci-
              mal constant or the name of an existing symbol,  or
              use  +  and  -  to add or subtract hexadecimal con-
              stants or symbols.  If you need more elaborate  ex-
              pressions,  consider  using the linker command lan-
              guage from a script.


       -e entry
               Use entry as the explicit symbol for beginning ex-
              ecution  of  your  program, rather than the default
              entry point.  for a discussion of defaults and oth-
              er ways of specifying the entry point.


       -embedded-relocs
              This  option  is  only meaningful when linking MIPS
              embedded PIC code, generated by the  -membedded-pic
              option to the GNU compiler and assembler.  It caus-
              es the linker to create a table which may  be  used
              at runtime to relocate any data which was statical-
              ly initialized to pointer values.  See the code  in
              testsuite/ld-empic for details.


       -E

       -export-dynamic
              When  creating  an ELF file, add all symbols to the
              dynamic symbol table.  Normally, the dynamic symbol
              table contains only symbols which are used by a dy-
              namic object.  This option is needed for some  uses
              of dlopen.


       -F

       -Fformat
              Some  older  linkers  used this option throughout a
              compilation toolchain  for  specifying  object-file
              format  for  both  input  and  output object files.
              ld's mechanisms (the -b or -format options for  in-
              put files, the 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 input-format
              Synonym for -b input-format.

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


       -G size
              Set the maximum size of objects to be optimized us-
              ing  the GP register to size under MIPS ECOFF.  Ig-
              nored for other object file formats.


       --help Print a summary of the command-line options on  the
              standard  output  and exit.  This option and --ver-
              sion begin with two dashes instead of one for  com-
              patibility  with other GNU programs.  The other op-
              tions start with only one  dash  for  compatibility
              with other linkers.


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


       -lar     Add  an  archive  file ar 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
              libar.a for every ar specified.


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

              The default set of paths  searched  (without  being
              specified  with  -L) depends on what emulation mode
              ld is using, 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     Print (to the standard output file) a link map--di-
              agnostic information about where symbols are mapped
              by ld, and information on global common storage al-
              location.


       -Map mapfile
              Print  to  the  file mapfile a link map--diagnostic
              information about where symbols are mapped  by  ld,
              and  information  on  global common storage alloca-
              tion.


       -m emulation
              Emulate the emulation linker.   You  can  list  the
              available  emulations  with the --verbose or -V op-
              tions.  This option overrides the  compiled-in  de-
              fault, which is the system for which you configured
              ld.


       -N     specifies readable and writable text and data  sec-
              tions.  If  the  output  format supports Unix style
              magic numbers, the output is marked as OMAGIC.

              When you use the `-N' option, the linker  does  not
              page-align the data segment.


       -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 pro-
              cess.  With this flag, you  can  specify  that  you
              wish  the output file retained even after non-fatal
              errors.


       -no-keep-memory
              The linker normally optimizes for speed over memory
              usage  by  caching the symbol tables of input files
              in memory.  This option tells the linker to instead
              optimize  for memory usage, by rereading the symbol
              tables as necessary.  This may be required  if  the
              linker  runs  out  of  memory space while linking a
              large executable.


       -o output
              output 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 al-
              so specify the output file name.


       -oformat output-format
              Specify  the  binary  format  for the output object
              file.  You don't usually need to specify  this,  as
              ld  is  configured  to  produce as a default output
              format the most usual format on each machine.  out-
              put-format is a text string, the name of a particu-
              lar format supported by  the  BFD  libraries.   The
              script  command  OUTPUT_FORMAT can also specify the
              output format, but this option overrides it.


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


       -relax An option with machine dependent effects.  Current-
              ly this option is only supported on the H8/300.

              On some platforms, use this option to perform glob-
              al optimizations  that  become  possible  when  the
              linker resolves addressing in your program, such as
              relaxing address modes  and  synthesizing  new  in-
              structions in the output object file.

              On  platforms where this is not supported, `-relax'
              is accepted, but has no effect.


       -r     Generates  relocatable  output--i.e.,  generate  an
              output  file that can in turn serve as input to ld.
              This is often called partial linking.   As  a  side
              effect,  in environments 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 option will not resolve
              references to constructors; -Ur is an  alternative.

              This option does the same as -i.


       -rpath directory
              Add a directory to the runtime library search path.
              This is used when linking an  ELF  executable  with
              shared  objects.  All -rpath arguments are concate-
              nated and passed to the runtime linker, which  uses
              them  to  locate  shared  objects  at runtime.  The
              -rpath option is also used when locating shared ob-
              jects which are needed by shared objects explicitly
              included in the link; see the  description  of  the
              -rpath-link  option.   If  -rpath  is not used when
              linking an ELF executable, the contents of the  en-
              vironment  variable  LD_RUN_PATH will be used if it
              is defined.

              The -rpath option may also be used  on  SunOS.   By
              default,  on  SunOS, the linker will form a runtime
              search patch out of all the -L options it is given.
              If a -rpath option is used, the runtime search path
              will be formed exclusively  using  the  -rpath  op-
              tions, ignoring the -L options.  This can be useful
              when using gcc, which adds many  -L  options  which
              may be on NFS mounted filesystems.


       -rpath-link directory
              When using ELF or SunOS, one shared library may re-
              quire another.  This  happens  when  an  ld -shared
              link  includes a shared library as one of the input
              files.

              When the linker encounters such a  dependency  when
              doing  a non-shared, non-relocateable link, it will
              automatically try to locate the required shared li-
              brary  and include it in the link, if it is not in-
              cluded explicitly.  In such a case, the -rpath-link
              option  specifies  the  first set of directories to
              search.  The -rpath-link option may specify  a  se-
              quence  of  directory  names either by specifying a
              list of names separated by colons, or by  appearing
              multiple times.

              If  the  required  shared library is not found, the
              linker will issue a warning and continue  with  the
              link.


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


       -s     Omits all symbol information from the output  file.


       -shared
              Create  a  shared  library.  This is currently only
              supported on ELF and SunOS platforms (on  SunOS  it
              is  not  required, as the linker will automatically
              create a shared library when  there  are  undefined
              symbols and the -e option is not used).


       -sort-common
              Normally,  when ld places the global common symbols
              in the appropriate output sections, it  sorts  them
              by size.  First come all the one byte symbols, then
              all the two bytes, then all  the  four  bytes,  and
              then  everything else.  This is to prevent gaps be-
              tween symbols due to alignment  constraints.   This
              option disables that sorting.


       -split-by-reloc count
              Trys  to  creates extra sections in the output file
              so that no single output section in the  file  con-
              tains  more than count relocations.  This is useful
              when generating huge  relocatable  for  downloading
              into certain real time kernels with the COFF object
              file format; since COFF cannot represent more  than
              65535  relocations  in a single section.  Note that
              this will fail to work  with  object  file  formats
              which do not support arbitrary sections.  The link-
              er will not split up individual input sections  for
              redistribution,  so  if a single input section con-
              tains more than count relocations one  output  sec-
              tion will contain that many relocations.


       -split-by-file
              Similar to -split-by-reloc but creates a new output
              section for each input file.


       -Tbss org

       -Tdata org

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


       -T commandfile
              Equivalent to -c commandfile; supported for compat-
              ibility with other tools.


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


       -u sym Forces  sym  to be entered in the output file as an
              undefined symbol.  This may, for  example,  trigger
              linking  of  additional  modules  from standard li-
              braries.  -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  out-
              put--i.e., an output file that can in turn serve as
              input to ld.  When linking C++ programs,  -Ur  will
              resolve references to constructors, unlike -r.


       --verbose
              Display the version number for ld and list the sup-
              ported emulations.  Display which input  files  can
              and can not be opened.

       -v, -V Display  the  version number for ld.  The -V option
              also lists the supported emulations.


       --version
              Display the version number for ld and exit.


       -warn-common
              Warn when a common symbol is combined with  another
              common  symbol  or  with a symbol definition.  Unix
              linkers allow this somewhat  sloppy  practice,  but
              linkers  on  some  other  operating systems do not.
              This option allows you to find  potential  problems
              from combining global symbols.


       -warn-constructors
              Warn  if any global constructors are used.  This is
              only useful for a few  object  file  formats.   For
              formats like COFF or ELF, the linker can not detect
              the use of global constructors.


       -warn-multiple-gp
              Warn if the output file requires  multiple  global-
              pointer values.  This option is only meaningful for
              certain processors, such as the Alpha.


       -warn-once
              Only warn once for each  undefined  symbol,  rather
              than once per module which refers to it.


       --whole-archive
              For  each archive mentioned on the command line af-
              ter the --whole-archive option, include  every  ob-
              ject  file  in the archive in the link, rather than
              searching  the  archive  for  the  required  object
              files.   This  is  normally used to turn an archive
              file into a shared library, forcing every object to
              be included in the resulting shared library.


       --no-whole-archive
              Turn  off  the effect of the --whole-archive option
              for archives which  appear  later  on  the  command
              line.


       --wrap symbol
              Use  a  wrapper function for symbol.  Any undefined
              reference to symbol will be resolved to __wrap_sym-
              bol.  Any undefined reference to __real_symbol will
              be resolved to symbol.


       -X     Delete all temporary local symbols.  For most  tar-
              gets,  this  is all local symbols whose names begin
              with `L'.


       -x     Delete all local symbols.





ENVIRONMENT

       You can change the behavior of  ld  with  the  environment
       variable GNUTARGET.

       GNUTARGET  determines  the input-file object format if you
       don't use -b (or its synonym -format).  Its  value  should
       be  one of the BFD names for an input format.  If there is
       no GNUTARGET in the environment, ld uses the natural  for-
       mat  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 po-
       tential 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 convention.





SEE ALSO

       objdump(1)
       `ld' and `binutils' entries in info
       ld:  the  GNU  linker, Steve Chamberlain and Roland Pesch;
       The GNU Binary Utilities, Roland H. Pesch.



COPYING

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

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

       Permission is granted to copy and distribute modified ver-
       sions  of  this  manual  under the conditions for verbatim
       copying, provided that the entire resulting  derived  work
       is  distributed  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 con-
       ditions for modified versions, except that this permission
       notice  may  be  included  in translations approved by the
       Free Software Foundation instead of in  the  original  En-
       glish.
Hurricane Electric Internet Services: Accounts starting at $9.95/month
Hurricane Electric Internet Services
Copyright (C) 1998 Hurricane Electric. All Rights Reserved.