SYNOPSIS

       ld [options] objfile ...


DESCRIPTION

       ld  combines  a  number of object and archive files, relo­
       cates their data and ties up  symbol  references.  Usually
       the last step in compiling a program is to run ld.

       ld  accepts  Linker  Command  Language  files written in a
       superset of AT&T's Link Editor Command Language syntax, to
       provide  explicit  and total control over the linking pro­
       cess.

       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
       aspects 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 for­
       mats---for example, COFF or  "a.out".   Different  formats
       may  be  linked  together to produce any available kind of
       object file.

       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.


OPTIONS

       The linker supports a plethora  of  command-line  options,
       but in actual practice few of them are used in any partic­
       ular context.  For instance, a frequent use of  ld  is  to
       link  standard  Unix object files on a standard, supported
       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
       result  of  linking  the file "/lib/crt0.o" with "hello.o"
       and the library "libc.a", which will come from  the  stan­
       dard  search  directories.   (See the discussion of the -l
       option below.)

       be mixed in with  command-line  options,  except  that  an
       object  file  argument may not be placed between an option
       and its argument.

       Usually the linker is invoked with  at  least  one  object
       file,  but  you  can  specify  other forms of binary input
       files using -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.

       If  the  linker  can not recognize the format of an object
       file, it will assume that it is a linker script.  A script
       specified in this way augments the main linker script used
       for the link (either the default linker script or the  one
       specified  by  using -T).  This feature permits the linker
       to link against a file which appears to be an object or an
       archive,  but  actually merely defines some symbol values,
       or uses "INPUT" or "GROUP" to load  other  objects.   Note
       that  specifying  a script in this way merely augments the
       main linker script; use  the  -T  option  to  replace  the
       default linker script entirely.

       For  options whose names are a single letter, option argu­
       ments must either follow the option letter without  inter­
       vening whitespace, or be given as separate arguments imme­
       diately following the option that requires them.

       For options whose names are multiple letters,  either  one
       dash  or  two  can  precede  the option name; for example,
       -trace-symbol and --trace-symbol are equivalent.   Note  -
       there  is  one  exception  to  this rule.  Multiple letter
       options that start with a lower case 'o' can only be  pre­
       ceeded  by  two  dashes.  This is to reduce confusion with
       the -o option.  So for example  -omagic  sets  the  output
       file  name  to magic whereas --omagic sets the NMAGIC flag
       on the output.

       Arguments to multiple-letter options must either be  sepa­
       rated  from the option name by an equals sign, or be given
       as separate arguments  immediately  following  the  option
       that  requires  them.  For example, --trace-symbol foo and
       --trace-symbol=foo are equivalent.   Unique  abbreviations
       of the names of multiple-letter options are accepted.

       Note  -  if  the linker is being invoked indirectly, via a
       compiler driver (eg gcc) then all the linker command  line
       options  should be prefixed by -Wl, (or whatever is appro­
       priate for the particular compiler driver) like this:

                 gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup


       -Aarchitecture
       --architecture=architecture
           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 iden­
           tifies  the particular architecture in the 960 family,
           enabling some safeguards and  modifying  the  archive-
           library search path.

           Future  releases of ld may support similar functional­
           ity for other architecture families.

       -b input-format
       --format=input-format
           ld may be configured to support more than one kind  of
           object  file.   If your ld is configured this way, you
           can use the -b option to specify the binary format for
           input object files that follow this option on the com­
           mand line.  Even when  ld  is  configured  to  support
           alternative  object formats, you don't usually need to
           specify this, as ld should be configured 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  supported  by  the  BFD libraries.
           (You can list the available binary formats  with  obj­
           dump -i.)

           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 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";

       -c MRI-commandfile
       --mri-script=MRI-commandfile
           For compatibility with linkers  produced  by  MRI,  ld
           accepts   script   files   written  in  an  alternate,
           restricted command language, described in the MRI Com­
           patible  Script Files section of GNU ld documentation.
           Introduce MRI script files with the option -c; use the
           -T  option  to  run linker scripts written in the gen­
           eral-purpose ld scripting  language.   If  MRI-cmdfile
           does  not  exist,  ld  looks for it in the directories
           specified by any -L options.
           will try to parse entry as a number, and use  that  as
           the  entry  address (the number will be interpreted in
           base 10; you may use a leading 0x for base  16,  or  a
           leading 0 for base 8).

       -E
       --export-dynamic
           When creating a dynamically linked executable, add all
           symbols to the dynamic symbol table.  The dynamic sym­
           bol table is the set of symbols which are visible from
           dynamic objects at run time.

           If you do not use  this  option,  the  dynamic  symbol
           table  will  normally contain only those symbols which
           are referenced by some dynamic object mentioned in the
           link.

           If  you  use  "dlopen"  to load a dynamic object which
           needs to refer back to the symbols defined by the pro­
           gram,  rather than some other dynamic object, then you
           will probably need to use this option when linking the
           program itself.

           You  can  also  use the version script to control what
           symbols should be added to the dynamic symbol table if
           the output format supports it.  See the description of
           --version-script in @ref{VERSION}.

       -EB Link big-endian objects.   This  affects  the  default
           output format.

       -EL Link  little-endian objects.  This affects the default
           output format.

       -f
       --auxiliary name
           When creating an ELF shared object, set  the  internal
           DT_AUXILIARY  field to the specified name.  This tells
           the dynamic linker that the symbol table of the shared
           object  should  be  used as an auxiliary filter on the
           symbol table of the shared object name.

           If you  later  link  a  program  against  this  filter
           object,  then,  when  you run the program, the dynamic
           linker  will  see  the  DT_AUXILIARY  field.   If  the
           dynamic  linker  resolves  any symbols from the filter
           object, it will first check whether there is a defini­
           tion  in  the shared object name.  If there is one, it
           will be used instead of the definition in  the  filter
           object.   The shared object name need not exist.  Thus
           the shared object name  may  be  used  to  provide  an
           alternative  implementation of certain functions, per­

           If  you  later  link  a  program  against  this filter
           object, then, when you run the  program,  the  dynamic
           linker  will  see  the  DT_FILTER  field.  The dynamic
           linker will resolve symbols according  to  the  symbol
           table of the filter object as usual, but it will actu­
           ally link to  the  definitions  found  in  the  shared
           object  name.   Thus  the filter object can be used to
           select a subset of the symbols provided by the  object
           name.

           Some  older  linkers  used  the -F option throughout a
           compilation toolchain for specifying object-file  for­
           mat  for  both input and output object files.  The GNU
           linker uses other mechanisms for this purpose: the -b,
           --format,  --oformat  options, the "TARGET" command in
           linker scripts, and the "GNUTARGET" environment  vari­
           able.   The  GNU linker will ignore the -F option when
           not creating an ELF shared object.

       -fini name
           When creating an ELF executable or shared object, call
           NAME when the executable or shared object is unloaded,
           by setting DT_FINI to the address of the function.  By
           default,  the  linker  uses "_fini" as the function to
           call.

       -g  Ignored.  Provided for compatibility with other tools.

       -Gvalue
       --gpsize=value
           Set  the maximum size of objects to be optimized using
           the GP register to size.  This is only meaningful  for
           object  file formats such as MIPS ECOFF which supports
           putting large and small objects  into  different  sec­
           tions.  This is ignored for other object file formats.

       -hname
       -soname=name
           When creating an ELF shared object, set  the  internal
           DT_SONAME  field  to the specified name.  When an exe­
           cutable is linked with a shared  object  which  has  a
           DT_SONAME  field,  then when the executable is run the
           dynamic linker will attempt to load the shared  object
           specified by the DT_SONAME field rather than the using
           the file name given to the linker.

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

       -init name
           When creating an ELF executable or shared object, call
           NAME  when  the executable or shared object is loaded,
           a directory for a library with an extension  of  ".so"
           before  searching  for  one with an extension of ".a".
           By convention, a ".so" extension  indicates  a  shared
           library.

           The  linker  will  search an archive only once, at the
           location where it is specified on  the  command  line.
           If the archive defines a symbol which was undefined in
           some object which appeared before the archive  on  the
           command  line, the linker will include the appropriate
           file(s) from the archive.  However, an undefined  sym­
           bol  in  an object appearing later on the command line
           will not cause the linker to search the archive again.

           See  the  -(  option  for a way to force the linker to
           search archives multiple times.

           You may list the same archive multiple  times  on  the
           command line.

           This  type  of  archive searching is standard for Unix
           linkers.  However, if you are using ld  on  AIX,  note
           that  it  is  different  from the behaviour of the AIX
           linker.

       -Lsearchdir
       --library-path=searchdir
           Add path searchdir to the list of paths that  ld  will
           search  for  archive libraries and ld control scripts.
           You may use this option  any  number  of  times.   The
           directories  are  searched  in the order in which they
           are specified on the command line.  Directories speci­
           fied  on  the  command  line  are  searched before the
           default directories.  All -L options apply to  all  -l
           options,  regardless of the order in which the options
           appear.

           If searchdir begins with "=", then  the  "="  will  be
           replaced  by the sysroot prefix, a path specified when
           the linker is configured.

           The default set of paths searched (without being spec­
           ified  with  -L) depends on which emulation mode ld is
           using, and in some cases also on how  it  was  config­
           ured.

           The  paths can also be specified in a link script with
           the "SEARCH_DIR" command.  Directories specified  this
           way  are  searched  at  the  point in which the linker
           script appears in the command line.

       -memulation
           following:

           ·   Where object files and  symbols  are  mapped  into
               memory.

           ·   How common symbols are allocated.

           ·   All  archive  members included in the link, with a
               mention of the symbol  which  caused  the  archive
               member to be brought in.

       -n
       --nmagic
           Turn off page alignment of sections, and mark the out­
           put as "NMAGIC" if possible.

       -N
       --omagic
           Set the text and data  sections  to  be  readable  and
           writable.   Also,  do not page-align the data segment,
           and disable linking against shared libraries.  If  the
           output  format supports Unix style magic numbers, mark
           the output as "OMAGIC".

       --no-omagic
           This option negates most of  the  effects  of  the  -N
           option.  It sets the text section to be read-only, and
           forces the data segment to be  page-aligned.   Note  -
           this  option  does  not  enable linking against shared
           libraries.  Use -Bdynamic for this.

       -o output
       --output=output
           Use output as the 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.

       -O level
           If  level  is  a  numeric  values greater than zero ld
           optimizes the output.  This might  take  significantly
           longer  and  therefore probably should only be enabled
           for the final binary.

       -q
       --emit-relocs
           Leave relocation sections and contents in fully linked
           exececutables.   Post  link  analysis and optimization
           tools may need this information in  order  to  perform
           correct modifications of executables.  This results in
           larger executables.


           When  an  input  file does not have the same format as
           the output file, partial linking is only supported  if
           that  input  file  does  not  contain any relocations.
           Different output formats  can  have  further  restric­
           tions;  for  example some "a.out"-based formats do not
           support partial linking with input files in other for­
           mats at all.

           This option does the same thing as -i.

       -R filename
       --just-symbols=filename
           Read  symbol  names and their addresses from filename,
           but do not relocate it or include it  in  the  output.
           This  allows your output file to refer symbolically to
           absolute locations of memory  defined  in  other  pro­
           grams.  You may use this option more than once.

           For  compatibility  with  other ELF linkers, if the -R
           option is followed by a directory name, rather than  a
           file name, it is treated as the -rpath option.

       -s
       --strip-all
           Omit all symbol information from the output file.

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

       -t
       --trace
           Print the names of the input  files  as  ld  processes
           them.

       -T scriptfile
       --script=scriptfile
           Use  scriptfile  as  the  linker  script.  This script
           replaces  ld's  default  linker  script  (rather  than
           adding  to it), so commandfile must specify everything
           necessary to describe the output file.     If  script­
           file  does  not  exist  in the current directory, "ld"
           looks for it in the directories specified by any  pre­
           ceding -L options.  Multiple -T options accumulate.

       -u symbol
       --undefined=symbol
           Force  symbol  to  be entered in the output file as an
           undefined symbol.  Doing this may, for example,  trig­
           ger   linking  of  additional  modules  from  standard

       --unique[=SECTION]
           Creates a separate output section for every input sec­
           tion matching SECTION, or  if  the  optional  wildcard
           SECTION  argument  is  missing, for every orphan input
           section.  An orphan section is  one  not  specifically
           mentioned in a linker script.  You may use this option
           multiple times on the command line;  It  prevents  the
           normal  merging  of input sections with the same name,
           overriding output  section  assignments  in  a  linker
           script.

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

       -x
       --discard-all
           Delete all local symbols.

       -X
       --discard-locals
           Delete all temporary local symbols.  For most targets,
           this is all local symbols whose names begin with L.

       -y symbol
       --trace-symbol=symbol
           Print  the  name  of  each linked file in which symbol
           appears.  This option  may  be  given  any  number  of
           times.   On many systems it is necessary to prepend an
           underscore.

           This option is useful when you have an undefined  sym­
           bol in your link but don't know where the reference is
           coming from.

       -Y path
           Add path to the default  library  search  path.   This
           option exists for Solaris compatibility.

       -z keyword
           The  recognized keywords are "initfirst", "interpose",
           "loadfltr",  "nodefaultlib",  "nodelete",  "nodlopen",
           "nodump",  "now", "origin", "combreloc", "nocombreloc"
           and "nocopyreloc".  The other keywords are ignored for
           Solaris compatibility. "initfirst" marks the object to
           be initialized  first  at  runtime  before  any  other
           objects.  "interpose" marks the object that its symbol
           table interposes before all symbols  but  the  primary
           executable.  "loadfltr" marks the object that its fil­
           tees be processed immediately at runtime.  "nodefault­

       -( archives -)
       --start-group archives --end-group
           The archives should be a list of archive files.   They
           may be either explicit file names, or -l options.

           The  specified  archives are searched repeatedly until
           no new undefined references are created.  Normally, an
           archive  is searched only once in the order that it is
           specified on the command line.  If a  symbol  in  that
           archive  is  needed  to  resolve  an  undefined symbol
           referred to by an object in an  archive  that  appears
           later  on  the  command  line, the linker would not be
           able to  resolve  that  reference.   By  grouping  the
           archives,  they  all  be searched repeatedly until all
           possible references are resolved.

           Using this option has a significant performance  cost.
           It  is  best to use it only when there are unavoidable
           circular references between two or more archives.

       --accept-unknown-input-arch
       --no-accept-unknown-input-arch
           Tells the linker to accept input files whose architec­
           ture cannot be recognised.  The assumption is that the
           user knows what they are doing and deliberately  wants
           to  link  in  these unknown input files.  This was the
           default behaviour of the linker, before release  2.14.
           The  default behaviour from release 2.14 onwards is to
           reject    such    input    files,    and    so     the
           --accept-unknown-input-arch  option  has been added to
           restore the old behaviour.

       -assert keyword
           This option is ignored for SunOS compatibility.

       -Bdynamic
       -dy
       -call_shared
           Link against dynamic libraries.  This is only meaning­
           ful  on  platforms for which shared libraries are sup­
           ported.  This option is normally the default  on  such
           platforms.   The different variants of this option are
           for compatibility with various systems.  You  may  use
           this  option  multiple  times  on the command line: it
           affects library searching for -l options which  follow
           it.

       -Bgroup
           Set the "DF_1_GROUP" flag in the "DT_FLAGS_1" entry in
           the dynamic section.  This causes the  runtime  linker
           to  handle lookups in this object and its dependencies
           it.

       -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  pro­
           gram  linked  against a shared library to override the
           definition within the shared library.  This option  is
           only  meaningful on ELF platforms which support shared
           libraries.

       --check-sections
       --no-check-sections
           Asks the linker not to check section  addresses  after
           they  have been assigned to see if there any overlaps.
           Normally the linker will perform this check, and if it
           finds any overlaps it will produce suitable error mes­
           sages.  The linker does  know  about,  and  does  make
           allowances  for  sections  in  overlays.   The default
           behaviour can be restored by using  the  command  line
           switch --check-sections.

       --cref
           Output  a cross reference table.  If a linker map file
           is being  generated,  the  cross  reference  table  is
           printed  to the map file.  Otherwise, it is printed on
           the standard output.

           The format of the table is  intentionally  simple,  so
           that  it may be easily processed by a script if neces­
           sary.  The symbols are printed out,  sorted  by  name.
           For  each  symbol,  a list of file names is given.  If
           the symbol is defined, the first file  listed  is  the
           location  of the definition.  The remaining files con­
           tain references to the symbol.

       --no-define-common
           This option inhibits the assignment  of  addresses  to
           common  symbols.   The  script  command  "INHIBIT_COM­
           MON_ALLOCATION" has the same effect.

           The --no-define-common option  allows  decoupling  the
           decision  to  assign  addresses to Common symbols from
           the choice of the output file type; otherwise  a  non-
           Relocatable  output type forces assigning addresses to
           Common symbols.  Using --no-define-common allows  Com­
           mon  symbols that are referenced from a shared library
           to be assigned addresses only  in  the  main  program.
           This  eliminates  the  unused  duplicate  space in the
           shared library, and also prevents any possible  confu­
           sion  over resolving to the wrong duplicate when there
           are many dynamic modules with specialized search paths
           sign (``=''), and expression.

       --demangle[=style]
       --no-demangle
           These options control whether to demangle symbol names
           in  error  messages and other output.  When the linker
           is told to demangle, it tries to present symbol  names
           in  a  readable fashion: it strips leading underscores
           if they are used by the object file format,  and  con­
           verts  C++  mangled  symbol  names  into user readable
           names.  Different compilers  have  different  mangling
           styles.  The optional demangling style argument can be
           used to choose an  appropriate  demangling  style  for
           your  compiler.   The  linker will demangle by default
           unless the environment variable COLLECT_NO_DEMANGLE is
           set.   These  options  may  be  used  to  override the
           default.

       --dynamic-linker file
           Set the name of the  dynamic  linker.   This  is  only
           meaningful when generating dynamically linked ELF exe­
           cutables.  The default dynamic linker is normally cor­
           rect;  don't  use  this  unless  you know what you are
           doing.

       --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  causes
           the linker to create a table which may be used at run­
           time to relocate any data which  was  statically  ini­
           tialized  to  pointer  values.   See the code in test­
           suite/ld-empic for details.

       --fatal-warnings
           Treat all warnings as errors.

       --force-exe-suffix
           Make sure that an output file has a .exe suffix.

           If a successfully built fully linked output file  does
           not have a ".exe" or ".dll" suffix, this option forces
           the linker to copy the output file to one of the  same
           name  with a ".exe" suffix. This option is useful when
           using unmodified Unix makefiles on a Microsoft Windows
           host,  since  some  versions  of  Windows won't run an
           image unless it ends in a ".exe" suffix.

       --no-gc-sections
       --gc-sections
           Enable garbage collection of  unused  input  sections.
           It  is  ignored  on  targets  that do not support this

       -Map mapfile
           Print a  link  map  to  the  file  mapfile.   See  the
           description of the -M option, above.

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

       --no-undefined
       -z defs
           Normally when creating a non-symbolic shared  library,
           undefined  symbols are allowed and left to be resolved
           by the runtime loader.  These options  disallows  such
           undefined symbols.

       --allow-multiple-definition
       -z muldefs
           Normally  when a symbol is defined multiple times, the
           linker will report a fatal error. These options  allow
           multiple  definitions and the first definition will be
           used.

       --allow-shlib-undefined
           Allow undefined symbols in shared objects  even   when
           --no-undefined  is  set.  The  net result will be that
           undefined symbols in regular objects will still  trig­
           ger  an error, but undefined symbols in shared objects
           will be ignored.  The implementation  of  no_undefined
           makes  the  assumption  that  the  runtime linker will
           choke on undefined symbols.  However there is at least
           one  system  (BeOS)  where undefined symbols in shared
           libraries is normal since the kernel patches  them  at
           load time to select which function is most appropriate
           for the current architecture.  I.E. dynamically select
           an appropriate memset function.  Apparently it is also
           normal for HPPA shared  libraries  to  have  undefined
           symbols.

       --no-undefined-version
           Normally  when  a symbol has an undefined version, the
           linker will ignore it. This option  disallows  symbols
           with  undefined  version  and  a  fatal  error will be
           issued instead.

       --no-warn-mismatch
           Normally ld will give an error  if  you  try  to  link
           together input files that are mismatched for some rea­
           son, perhaps because they have been compiled for  dif­
           cess; it exits without writing an output file when  it
           issues any error whatsoever.

       -nostdlib
           Only  search  library directories explicitly specified
           on the command line.  Library directories specified in
           linker  scripts (including linker scripts specified on
           the command line) are ignored.

       --oformat output-format
           ld may be configured to support more than one kind  of
           object  file.   If your ld is configured this way, you
           can use the --oformat option  to  specify  the  binary
           format  for  the  output object file.  Even when ld is
           configured to support alternative object formats,  you
           don't  usually  need  to specify this, as ld should be
           configured to produce as a default output  format  the
           most usual format on each machine.  output-format is a
           text string, the name of a particular format supported
           by  the  BFD  libraries.   (You can list the available
           binary formats with objdump -i.)  The  script  command
           "OUTPUT_FORMAT"  can  also  specify the output format,
           but this option overrides it.

       -qmagic
           This option is ignored for Linux compatibility.

       -Qy This option is ignored for SVR4 compatibility.

       --relax
           An option with machine dependent effects.  This option
           is only supported on a few targets.

           On  some platforms, the --relax option performs global
           optimizations that become  possible  when  the  linker
           resolves  addressing  in the program, such as relaxing
           address modes and synthesizing new instructions in the
           output object file.

           On some platforms these link time global optimizations
           may make symbolic  debugging  of  the  resulting  exe­
           cutable  impossible.  This is known to be the case for
           the Matsushita MN10200 and MN10300 family  of  proces­
           sors.

           On  platforms  where this is not supported, --relax is
           accepted, but ignored.

       --retain-symbols-file filename
           Retain only the symbols listed in the  file  filename,
           discarding  all  others.   filename  is  simply a flat
           file, with one symbol name per line.  This  option  is
           and passed to the runtime linker, which uses  them  to
           locate  shared  objects at runtime.  The -rpath option
           is also used when locating shared  objects  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 environment 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 options,
           ignoring the -L options.   This  can  be  useful  when
           using  gcc, which adds many -L options which may be on
           NFS mounted filesystems.

           For compatibility with other ELF linkers,  if  the  -R
           option  is followed by a directory name, rather than a
           file name, it is treated as the -rpath option.

       -rpath-link DIR
           When using  ELF  or  SunOS,  one  shared  library  may
           require  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-relocatable  link,  it  will
           automatically   try  to  locate  the  required  shared
           library and include it in  the  link,  if  it  is  not
           included  explicitly.  In such a case, the -rpath-link
           option specifies  the  first  set  of  directories  to
           search.  The -rpath-link option may specify a sequence
           of directory names either  by  specifying  a  list  of
           names  separated  by  colons, or by appearing multiple
           times.

           This option should be used with caution  as  it  over­
           rides the search path that may have been hard compiled
           into a shared library. In such a case it  is  possible
           to  use  unintentionally  a different search path than
           the runtime linker would do.

           The linker uses the following search paths  to  locate
           required shared libraries.

           1.  Any  directories specified by -rpath-link options.

           2.  Any directories specified by -rpath options.   The
               difference  between -rpath and -rpath-link is that
               ment variable "LD_LIBRARY_PATH".

           6.  For  a  native  ELF  linker,  the  directories  in
               "DT_RUNPATH" or "DT_RPATH" of a shared library are
               searched  for  shared  libraries needed by it. The
               "DT_RPATH" entries  are  ignored  if  "DT_RUNPATH"
               entries exist.

           7.  The   default   directories,   normally  /lib  and
               /usr/lib.

           8.  For a native linker on an ELF system, if the  file
               /etc/ld.so.conf  exists,  the  list of directories
               found in that file.

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

       -shared
       -Bshareable
           Create a shared library.  This is currently only  sup­
           ported  on  ELF, XCOFF and SunOS platforms.  On SunOS,
           the linker will automatically create a shared  library
           if  the  -e option is not used and there are undefined
           symbols in the link.

       --sort-common
           This option tells ld to sort  the  common  symbols  by
           size  when  it  places  them in the appropriate output
           sections.  First come all the one byte  symbols,  then
           all  the  two  byte,  then all the four byte, and then
           everything else.  This is to prevent gaps between sym­
           bols due to alignment constraints.

       --split-by-file [size]
           Similar  to  --split-by-reloc but creates a new output
           section for each input  file  when  size  is  reached.
           size defaults to a size of 1 if not given.

       --split-by-reloc [count]
           Tries  to creates extra sections in the output file so
           that no single output section  in  the  file  contains
           more than count relocations.  This is useful when gen­
           erating huge relocatable files  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 linker will not split
           up individual input sections for redistribution, so if
           a  single input section contains more than count relo­
           in the symbol string table.  This can reduce the  size
           of  an  output file with full debugging information by
           over 30 percent.  Unfortunately, the SunOS "dbx"  pro­
           gram  can not read the resulting program ("gdb" has no
           trouble).  The --traditional-format switch tells ld to
           not combine duplicate entries.

       --section-start sectionname=org
           Locate  a  section  in the output file at the absolute
           address given by org.  You may use this option as many
           times  as necessary to locate multiple sections in the
           command line.  org must be a single hexadecimal  inte­
           ger;  for  compatibility  with  other linkers, you may
           omit the leading 0x usually associated with  hexadeci­
           mal  values.   Note:  there  should  be no white space
           between sectionname, the equals sign (``=''), and org.

       -Tbss org
       -Tdata org
       -Ttext org
           Use   org   as   the  starting  address  for---respec­
           tively---the "bss", "data", or the "text"  segment  of
           the  output  file.   org  must be a single hexadecimal
           integer; for compatibility with other linkers, you may
           omit  the leading 0x usually associated with hexadeci­
           mal values.

       --dll-verbose
       --verbose
           Display the version number for ld and list the  linker
           emulations  supported.   Display which input files can
           and cannot be opened.  Display the linker script being
           used by the linker.

       --version-script=version-scriptfile
           Specify  the  name  of a version script to the linker.
           This is typically used when creating shared  libraries
           to  specify  additional  information about the version
           heirarchy for the library being created.  This  option
           is  only  meaningful  on  ELF  platforms which support
           shared libraries.

       --warn-common
           Warn when a common symbol  is  combined  with  another
           common symbol or with a symbol definition.  Unix link­
           ers 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.   Unfortunately, some C libraries use
           this practice, so you may get some warnings about sym­
           bols in the libraries as well as in your programs.

               common symbols for a  variable,  it  goes  in  the
               uninitialized  data  area of the output file.  The
               linker merges multiple common symbols for the same
               variable  into  a  single  symbol.  If they are of
               different sizes, it picks the largest  size.   The
               linker  turns  a common symbol into a declaration,
               if there is a definition of the same variable.

           The --warn-common option can  produce  five  kinds  of
           warnings.   Each  warning consists of a pair of lines:
           the first describes the symbol just  encountered,  and
           the  second  describes the previous symbol encountered
           with the same name.  One or both of  the  two  symbols
           will be a common symbol.

           1.  Turning  a common symbol into a reference, because
               there is already a definition for the symbol.

                       <file>(<section>): warning: common of `<symbol>'
                          overridden by definition
                       <file>(<section>): warning: defined here

           2.  Turning a common symbol into a reference,  because
               a  later definition for the symbol is encountered.
               This is the same as the previous case, except that
               the  symbols are encountered in a different order.

                       <file>(<section>): warning: definition of `<symbol>'
                          overriding common
                       <file>(<section>): warning: common is here

           3.  Merging a common symbol with a previous same-sized
               common symbol.

                       <file>(<section>): warning: multiple common
                          of `<symbol>'
                       <file>(<section>): warning: previous common is here

           4.  Merging  a  common  symbol  with a previous larger
               common symbol.

                       <file>(<section>): warning: common of `<symbol>'
                          overridden by larger common
                       <file>(<section>): warning: larger common is here

           5.  Merging a common symbol with  a  previous  smaller
               common  symbol.   This is the same as the previous
               case, except that the symbols are encountered in a
               different order.

                       <file>(<section>): warning: common of `<symbol>'
                          overriding smaller common

           points  into  the middle of this section, so that con­
           stants can be loaded efficiently via  a  base-register
           relative  addressing  mode.  Since the offset in base-
           register relative mode is fixed and  relatively  small
           (e.g.,  16  bits), this limits the maximum size of the
           constant pool.  Thus, in large programs, it  is  often
           necessary  to  use  multiple  global pointer values in
           order to be able to address  all  possible  constants.
           This  option  causes  a  warning to be issued whenever
           this case occurs.

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

       --warn-section-align
           Warn  if  the  address of an output section is changed
           because of alignment.  Typically, the  alignment  will
           be  set by an input section.  The address will only be
           changed if it not explicitly specified;  that  is,  if
           the  "SECTIONS"  command  does  not  specify  a  start
           address for the section.

       --whole-archive
           For each archive mentioned on the command  line  after
           the  --whole-archive option, include every object file
           in the archive in the link, rather than searching  the
           archive  for  the required object files.  This is nor­
           mally used to turn  an  archive  file  into  a  shared
           library,  forcing  every  object to be included in the
           resulting shared library.  This  option  may  be  used
           more than once.

           Two  notes when using this option from gcc: First, gcc
           doesn't know about this option, so  you  have  to  use
           -Wl,-whole-archive.    Second,  don't  forget  to  use
           -Wl,-no-whole-archive after  your  list  of  archives,
           because  gcc will add its own list of archives to your
           link and you may not want this flag to affect those as
           well.

       --wrap symbol
           Use a wrapper function for symbol.  Any undefined ref­
           erence to symbol will be resolved to  "__wrap_symbol".
           Any  undefined  reference  to  "__real_symbol" will be
           resolved to symbol.

           This can be used to provide a  wrapper  for  a  system
           function.   The  wrapper  function  should  be  called
           "__wrap_symbol".  If it  wishes  to  call  the  system
           function, it should call "__real_symbol".

           If  you  link  other  code with this file using --wrap
           malloc, then all calls to "malloc" will call the func­
           tion    "__wrap_malloc"    instead.    The   call   to
           "__real_malloc" in "__wrap_malloc" will call the  real
           "malloc" function.

           You  may wish to provide a "__real_malloc" function as
           well, so that links without  the  --wrap  option  will
           succeed.  If you do this, you should not put the defi­
           nition  of  "__real_malloc"  in  the  same   file   as
           "__wrap_malloc";  if you do, the assembler may resolve
           the call before the linker has a chance to wrap it  to
           "malloc".

       --enable-new-dtags
       --disable-new-dtags
           This  linker  can  create the new dynamic tags in ELF.
           But the older ELF systems may not understand them.  If
           you  specify --enable-new-dtags, the dynamic tags will
           be  created  as  needed.   If   you   specify   --dis­
           able-new-dtags,  no  new dynamic tags will be created.
           By default, the new dynamic tags are not created. Note
           that those options are only available for ELF systems.

       The i386 PE linker  supports  the  -shared  option,  which
       causes the output to be a dynamically linked library (DLL)
       instead of a normal executable.  You should name the  out­
       put  "*.dll"  when  you use this option.  In addition, the
       linker fully supports the standard  "*.def"  files,  which
       may be specified on the linker command line like an object
       file (in fact, it should precede archives it exports  sym­
       bols  from, to ensure that they get linked in, just like a
       normal object file).

       In addition to the options common to all targets, the i386
       PE linker support additional command line options that are
       specific to the i386 PE target.  Options that take  values
       may be separated from their values by either a space or an
       equals sign.

       --add-stdcall-alias
           If given, symbols with a stdcall suffix (@nn) will  be
           exported as-is and also with the suffix stripped.

       --base-file file
           Use  file  as  the name of a file in which to save the
           base addresses of all the relocations needed for  gen­
           erating DLLs with dlltool.

       --dll
           Create a DLL instead of a regular executable.  You may
           also use -shared or specify a  "LIBRARY"  in  a  given
           libraries  generated  from  third-party  dlls may need
           this  feature  to   be   usable.    If   you   specify
           --enable-stdcall-fixup,  this feature is fully enabled
           and warnings are not printed.  If you  specify  --dis­
           able-stdcall-fixup,  this feature is disabled and such
           mismatches are considered to be errors.

       --export-all-symbols
           If given, all global symbols in the  objects  used  to
           build  a  DLL  will be exported by the DLL.  Note that
           this is the default if there otherwise wouldn't be any
           exported   symbols.    When   symbols  are  explicitly
           exported via DEF  files  or  implicitly  exported  via
           function attributes, the default is to not export any­
           thing else unless this option is given.  Note that the
           symbols  "DllMain@12", "DllEntryPoint@0", "DllMainCRT­
           Startup@12", and "impure_ptr" will  not  be  automati­
           cally  exported.   Also,  symbols  imported from other
           DLLs will not be re-exported, nor will symbols  speci­
           fying  the  DLL's internal layout such as those begin­
           ning with "_head_" or ending with "_iname".  In  addi­
           tion,  no  symbols  from  "libgcc",  "libstd++", "lib­
           mingw32", or "crtX.o" will be exported.  Symbols whose
           names begin with "__rtti_" or "__builtin_" will not be
           exported, to help with C++ DLLs.  Finally, there is an
           extensive  list of cygwin-private symbols that are not
           exported (obviously, this  applies  on  when  building
           DLLs  for cygwin targets).  These cygwin-excludes are:
           "_cygwin_dll_entry@12",       "_cygwin_crt0_common@8",
           "_cygwin_noncygwin_dll_entry@12",            "_fmode",
           "_impure_ptr", "cygwin_attach_dll", "cygwin_premain0",
           "cygwin_premain1",   "cygwin_premain2",   "cygwin_pre­
           main3", and "environ".

       --exclude-symbols symbol,symbol,...
           Specifies a list of symbols which should not be  auto­
           matically exported.  The symbol names may be delimited
           by commas or colons.

       --exclude-libs lib,lib,...
           Specifies a list of archive libraries from which  sym­
           bols should not be automatically exported. The library
           names may be delimited by commas or colons.   Specify­
           ing  "--exclude-libs  ALL"  excludes  symbols  in  all
           archive  libraries  from  automatic  export.   Symbols
           explicitly  listed  in a .def file are still exported,
           regardless of this option.

       --file-alignment
           Specify the file alignment.  Sections in the file will
           always  begin  at  file offsets which are multiples of
           this number.  This defaults to 512.
           bles, and 0x10000000 for dlls.

       --kill-at
           If given, the stdcall suffixes (@nn) will be  stripped
           from symbols before they are exported.

       --major-image-version value
           Sets   the   major  number  of  the  "image  version".
           Defaults to 1.

       --major-os-version value
           Sets the major number of the "os  version".   Defaults
           to 4.

       --major-subsystem-version value
           Sets  the  major  number  of  the "subsystem version".
           Defaults to 4.

       --minor-image-version value
           Sets  the  minor  number  of  the   "image   version".
           Defaults to 0.

       --minor-os-version value
           Sets  the  minor number of the "os version".  Defaults
           to 0.

       --minor-subsystem-version value
           Sets the minor  number  of  the  "subsystem  version".
           Defaults to 0.

       --output-def file
           The  linker  will create the file file which will con­
           tain a DEF file corresponding to the DLL the linker is
           generating.   This  DEF  file  (which should be called
           "*.def") may be used to create an import library  with
           "dlltool"  or  may be used as a reference to automati­
           cally or implicitly exported symbols.

       --out-implib file
           The linker will create the file file which  will  con­
           tain an import lib corresponding to the DLL the linker
           is generating. This import lib (which should be called
           "*.dll.a" or "*.a" may be used to link clients against
           the generated DLL; this behavior makes it possible  to
           skip  a  separate  "dlltool"  import  library creation
           step.

       --enable-auto-image-base
           Automatically choose the image base for  DLLs,  unless
           one  is  specified  using the "--image-base" argument.
           By using a hash generated from the dllname  to  create
           unique  image bases for each DLL, in-memory collisions
           For    instance,    cygwin    DLLs    typically    use
           "--dll-search-prefix=cyg".

       --enable-auto-import
           Do  sophisticated linking of "_symbol" to "__imp__sym­
           bol" for DATA imports from DLLs, and create the neces­
           sary   thunking   symbols  when  building  the  import
           libraries with those  DATA  exports.   This  generally
           will  'just  work'  --  but sometimes you may see this
           message:

           "variable '<var>' can't be auto-imported. Please  read
           the  documentation for ld's "--enable-auto-import" for
           details."

           This message occurs when some (sub)expression accesses
           an  address  ultimately  given  by the sum of two con­
           stants  (Win32  import   tables   only   allow   one).
           Instances  where  this  may  occur include accesses to
           member fields of struct variables imported from a DLL,
           as  well as using a constant index into an array vari­
           able imported from  a  DLL.   Any  multiword  variable
           (arrays,  structs,  long  long,  etc) may trigger this
           error condition.  However,  regardless  of  the  exact
           data  type of the offending exported variable, ld will
           always detect it, issue the warning, and exit.

           There are several ways  to  address  this  difficulty,
           regardless of the data type of the exported variable:

           One   way   is  to  use  --enable-runtime-pseudo-reloc
           switch. This leaves the task of  adjusting  references
           in  your  client code for runtime environment, so this
           method works only when runtime  environtment  supports
           this feature.

           A  second  solution is to force one of the 'constants'
           to be a variable -- that is, unknown  and  un-optimiz­
           able  at compile time.  For arrays, there are two pos­
           sibilities: a) make the indexee (the array's  address)
           a  variable,  or  b) make the 'constant' index a vari­
           able.  Thus:

                   extern type extern_array[];
                   extern_array[1] -->
                      { volatile type *t=extern_array; t[1] }

           or

                   extern type extern_array[];
                   extern_array[1] -->
                      { volatile int t=1; extern_array[t] }

                   extern_ll -->
                     { volatile long long * local_ll=&extern_ll; *local_ll }

           A third method of dealing with this difficulty  is  to
           abandon  'auto-import'  for  the  offending symbol and
           mark it  with  "__declspec(dllimport)".   However,  in
           practice  that requires using compile-time #defines to
           indicate whether you  are  building  a  DLL,  building
           client  code  that  will  link  to  the DLL, or merely
           building/linking to a static library.   In making  the
           choice  between  the  various methods of resolving the
           'direct address with  constant  offset'  problem,  you
           should consider typical real-world usage:

           Original:

                   --foo.h
                   extern int arr[];
                   --foo.c
                   #include "foo.h"
                   void main(int argc, char **argv){
                     printf("%d\n",arr[1]);
                   }

           Solution 1:

                   --foo.h
                   extern int arr[];
                   --foo.c
                   #include "foo.h"
                   void main(int argc, char **argv){
                     /* This workaround is for win32 and cygwin; do not "optimize" */
                     volatile int *parr = arr;
                     printf("%d\n",parr[1]);
                   }

           Solution 2:

                   --foo.h
                   /* Note: auto-export is assumed (no __declspec(dllexport)) */
                   #if (defined(_WIN32) || defined(__CYGWIN__)) && \
                     !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
                   #define FOO_IMPORT __declspec(dllimport)
                   #else
                   #define FOO_IMPORT
                   #endif
                   extern FOO_IMPORT int arr[];
                   --foo.c
                   #include "foo.h"
                   void main(int argc, char **argv){
                     printf("%d\n",arr[1]);
                   }

           a vector of 'runtime pseudo relocations' which can  be
           used  by  runtime  environment to adjust references to
           such data in your client code.

       --disable-runtime-pseudo-reloc
           Do not create pseudo relocations for  non-zero  offset
           DATA imports from DLLs.  This is the default.

       --enable-extra-pe-debug
           Show additional debug info related to auto-import sym­
           bol thunking.

       --section-alignment
           Sets the section alignment.  Sections in  memory  will
           always begin at addresses which are a multiple of this
           number.  Defaults to 0x1000.

       --stack reserve
       --stack reserve,commit
           Specify the amount of memory to reserve  (and  option­
           ally  commit)  to  be  used as stack for this program.
           The default is 2Mb reserved, 4K committed.

       --subsystem which
       --subsystem which:major
       --subsystem which:major.minor
           Specifies the subsystem under which your program  will
           execute.   The  legal  values  for which are "native",
           "windows", "console", and "posix".  You may optionally
           set the subsystem version also.


ENVIRONMENT

       You  can  change  the  behavior of ld with the environment
       variables   "GNUTARGET",    "LDEMULATION",    and    "COL­
       LECT_NO_DEMANGLE".

       "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
       format  of  the target. If "GNUTARGET" is set to "default"
       then BFD attempts to discover the input format by  examin­
       ing  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 specify object-
       file formats is unique.  However, the configuration proce­
       dure 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.

       "LDEMULATION"  determines  the  default  emulation  if you
       don't use the -m option.  The emulation can affect various


SEE ALSO

       ar(1),  nm(1),  objcopy(1), objdump(1), readelf(1) and the
       Info entries for binutils and ld.


COPYRIGHT

       Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99,  2000,
       2001, 2002, 2003 Free Software Foundation, Inc.

       Permission  is  granted  to copy, distribute and/or modify
       this document under the terms of the GNU  Free  Documenta­
       tion  License,  Version 1.1 or any later version published
       by the Free Software Foundation; with  no  Invariant  Sec­
       tions,  with  no Front-Cover Texts, and with no Back-Cover
       Texts.  A copy of the license is included in  the  section
       entitled "GNU Free Documentation License".



binutils-2.13.90.0.18       2003-03-13                      LD(1)

Man(1) output converted with man2html