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