1: This is ld.info, produced by makeinfo version 4.8 from ld.texinfo.
    2: 
    3: START-INFO-DIR-ENTRY
    4: * Ld: (ld).                       The GNU linker.
    5: END-INFO-DIR-ENTRY
    6: 
    7:    This file documents the GNU linker LD (GNU Binutils) version 2.17.90.
    8: 
    9:    Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
   10: 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
   11: 
   12:    Permission is granted to copy, distribute and/or modify this document
   13: under the terms of the GNU Free Documentation License, Version 1.1 or
   14: any later version published by the Free Software Foundation; with no
   15: Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
   16: Texts.  A copy of the license is included in the section entitled "GNU
   17: Free Documentation License".
   18: 
   19: 
   20: File: ld.info,  Node: Top,  Next: Overview,  Up: (dir)
   21: 
   22: LD
   23: **
   24: 
   25: This file documents the GNU linker ld (GNU Binutils) version 2.17.90.
   26: 
   27:    This document is distributed under the terms of the GNU Free
   28: Documentation License.  A copy of the license is included in the
   29: section entitled "GNU Free Documentation License".
   30: 
   31: * Menu:
   32: 
   33: * Overview::                    Overview
   34: * Invocation::                  Invocation
   35: * Scripts::                     Linker Scripts
   36: 
   37: * Machine Dependent::           Machine Dependent Features
   38: 
   39: * BFD::                         BFD
   40: 
   41: * Reporting Bugs::              Reporting Bugs
   42: * MRI::                         MRI Compatible Script Files
   43: * GNU Free Documentation License::  GNU Free Documentation License
   44: * LD Index::                       LD Index
   45: 
   46: 
   47: File: ld.info,  Node: Overview,  Next: Invocation,  Prev: Top,  Up: Top
   48: 
   49: 1 Overview
   50: **********
   51: 
   52: `ld' combines a number of object and archive files, relocates their
   53: data and ties up symbol references. Usually the last step in compiling
   54: a program is to run `ld'.
   55: 
   56:    `ld' accepts Linker Command Language files written in a superset of
   57: AT&T's Link Editor Command Language syntax, to provide explicit and
   58: total control over the linking process.
   59: 
   60:    This version of `ld' uses the general purpose BFD libraries to
   61: operate on object files. This allows `ld' to read, combine, and write
   62: object files in many different formats--for example, COFF or `a.out'.
   63: Different formats may be linked together to produce any available kind
   64: of object file.  *Note BFD::, for more information.
   65: 
   66:    Aside from its flexibility, the GNU linker is more helpful than other
   67: linkers in providing diagnostic information.  Many linkers abandon
   68: execution immediately upon encountering an error; whenever possible,
   69: `ld' continues executing, allowing you to identify other errors (or, in
   70: some cases, to get an output file in spite of the error).
   71: 
   72: 
   73: File: ld.info,  Node: Invocation,  Next: Scripts,  Prev: Overview,  Up: Top
   74: 
   75: 2 Invocation
   76: ************
   77: 
   78: The GNU linker `ld' is meant to cover a broad range of situations, and
   79: to be as compatible as possible with other linkers.  As a result, you
   80: have many choices to control its behavior.
   81: 
   82: * Menu:
   83: 
   84: * Options::                     Command Line Options
   85: * Environment::                 Environment Variables
   86: 
   87: 
   88: File: ld.info,  Node: Options,  Next: Environment,  Up: Invocation
   89: 
   90: 2.1 Command Line Options
   91: ========================
   92: 
   93:    The linker supports a plethora of command-line options, but in actual
   94: practice few of them are used in any particular context.  For instance,
   95: a frequent use of `ld' is to link standard Unix object files on a
   96: standard, supported Unix system.  On such a system, to link a file
   97: `hello.o':
   98: 
   99:      ld -o OUTPUT /lib/crt0.o hello.o -lc
  100: 
  101:    This tells `ld' to produce a file called OUTPUT as the result of
  102: linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a',
  103: which will come from the standard search directories.  (See the
  104: discussion of the `-l' option below.)
  105: 
  106:    Some of the command-line options to `ld' may be specified at any
  107: point in the command line.  However, options which refer to files, such
  108: as `-l' or `-T', cause the file to be read at the point at which the
  109: option appears in the command line, relative to the object files and
  110: other file options.  Repeating non-file options with a different
  111: argument will either have no further effect, or override prior
  112: occurrences (those further to the left on the command line) of that
  113: option.  Options which may be meaningfully specified more than once are
  114: noted in the descriptions below.
  115: 
  116:    Non-option arguments are object files or archives which are to be
  117: linked together.  They may follow, precede, or be mixed in with
  118: command-line options, except that an object file argument may not be
  119: placed between an option and its argument.
  120: 
  121:    Usually the linker is invoked with at least one object file, but you
  122: can specify other forms of binary input files using `-l', `-R', and the
  123: script command language.  If _no_ binary input files at all are
  124: specified, the linker does not produce any output, and issues the
  125: message `No input files'.
  126: 
  127:    If the linker cannot recognize the format of an object file, it will
  128: assume that it is a linker script.  A script specified in this way
  129: augments the main linker script used for the link (either the default
  130: linker script or the one specified by using `-T').  This feature
  131: permits the linker to link against a file which appears to be an object
  132: or an archive, but actually merely defines some symbol values, or uses
  133: `INPUT' or `GROUP' to load other objects.  Note that specifying a
  134: script in this way merely augments the main linker script; use the `-T'
  135: option to replace the default linker script entirely.  *Note Scripts::.
  136: 
  137:    For options whose names are a single letter, option arguments must
  138: either follow the option letter without intervening whitespace, or be
  139: given as separate arguments immediately following the option that
  140: requires them.
  141: 
  142:    For options whose names are multiple letters, either one dash or two
  143: can precede the option name; for example, `-trace-symbol' and
  144: `--trace-symbol' are equivalent.  Note--there is one exception to this
  145: rule.  Multiple letter options that start with a lower case 'o' can
  146: only be preceded by two dashes.  This is to reduce confusion with the
  147: `-o' option.  So for example `-omagic' sets the output file name to
  148: `magic' whereas `--omagic' sets the NMAGIC flag on the output.
  149: 
  150:    Arguments to multiple-letter options must either be separated from
  151: the option name by an equals sign, or be given as separate arguments
  152: immediately following the option that requires them.  For example,
  153: `--trace-symbol foo' and `--trace-symbol=foo' are equivalent.  Unique
  154: abbreviations of the names of multiple-letter options are accepted.
  155: 
  156:    Note--if the linker is being invoked indirectly, via a compiler
  157: driver (e.g. `gcc') then all the linker command line options should be
  158: prefixed by `-Wl,' (or whatever is appropriate for the particular
  159: compiler driver) like this:
  160: 
  161:        gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
  162: 
  163:    This is important, because otherwise the compiler driver program may
  164: silently drop the linker options, resulting in a bad link.
  165: 
  166:    Here is a table of the generic command line switches accepted by the
  167: GNU linker:
  168: 
  169: `@FILE'
  170:      Read command-line options from FILE.  The options read are
  171:      inserted in place of the original @FILE option.  If FILE does not
  172:      exist, or cannot be read, then the option will be treated
  173:      literally, and not removed.
  174: 
  175:      Options in FILE are separated by whitespace.  A whitespace
  176:      character may be included in an option by surrounding the entire
  177:      option in either single or double quotes.  Any character
  178:      (including a backslash) may be included by prefixing the character
  179:      to be included with a backslash.  The FILE may itself contain
  180:      additional @FILE options; any such options will be processed
  181:      recursively.
  182: 
  183: `-aKEYWORD'
  184:      This option is supported for HP/UX compatibility.  The KEYWORD
  185:      argument must be one of the strings `archive', `shared', or
  186:      `default'.  `-aarchive' is functionally equivalent to `-Bstatic',
  187:      and the other two keywords are functionally equivalent to
  188:      `-Bdynamic'.  This option may be used any number of times.
  189: 
  190: `-AARCHITECTURE'
  191: `--architecture=ARCHITECTURE'
  192:      In the current release of `ld', this option is useful only for the
  193:      Intel 960 family of architectures.  In that `ld' configuration, the
  194:      ARCHITECTURE argument identifies the particular architecture in
  195:      the 960 family, enabling some safeguards and modifying the
  196:      archive-library search path.  *Note `ld' and the Intel 960 family:
  197:      i960, for details.
  198: 
  199:      Future releases of `ld' may support similar functionality for
  200:      other architecture families.
  201: 
  202: `-b INPUT-FORMAT'
  203: `--format=INPUT-FORMAT'
  204:      `ld' may be configured to support more than one kind of object
  205:      file.  If your `ld' is configured this way, you can use the `-b'
  206:      option to specify the binary format for input object files that
  207:      follow this option on the command line.  Even when `ld' is
  208:      configured to support alternative object formats, you don't
  209:      usually need to specify this, as `ld' should be configured to
  210:      expect as a default input format the most usual format on each
  211:      machine.  INPUT-FORMAT is a text string, the name of a particular
  212:      format supported by the BFD libraries.  (You can list the
  213:      available binary formats with `objdump -i'.)  *Note BFD::.
  214: 
  215:      You may want to use this option if you are linking files with an
  216:      unusual binary format.  You can also use `-b' to switch formats
  217:      explicitly (when linking object files of different formats), by
  218:      including `-b INPUT-FORMAT' before each group of object files in a
  219:      particular format.
  220: 
  221:      The default format is taken from the environment variable
  222:      `GNUTARGET'.  *Note Environment::.  You can also define the input
  223:      format from a script, using the command `TARGET'; see *Note Format
  224:      Commands::.
  225: 
  226: `-c MRI-COMMANDFILE'
  227: `--mri-script=MRI-COMMANDFILE'
  228:      For compatibility with linkers produced by MRI, `ld' accepts script
  229:      files written in an alternate, restricted command language,
  230:      described in *Note MRI Compatible Script Files: MRI.  Introduce
  231:      MRI script files with the option `-c'; use the `-T' option to run
  232:      linker scripts written in the general-purpose `ld' scripting
  233:      language.  If MRI-CMDFILE does not exist, `ld' looks for it in the
  234:      directories specified by any `-L' options.
  235: 
  236: `-d'
  237: `-dc'
  238: `-dp'
  239:      These three options are equivalent; multiple forms are supported
  240:      for compatibility with other linkers.  They assign space to common
  241:      symbols even if a relocatable output file is specified (with
  242:      `-r').  The script command `FORCE_COMMON_ALLOCATION' has the same
  243:      effect.  *Note Miscellaneous Commands::.
  244: 
  245: `-e ENTRY'
  246: `--entry=ENTRY'
  247:      Use ENTRY as the explicit symbol for beginning execution of your
  248:      program, rather than the default entry point.  If there is no
  249:      symbol named ENTRY, the linker will try to parse ENTRY as a number,
  250:      and use that as the entry address (the number will be interpreted
  251:      in base 10; you may use a leading `0x' for base 16, or a leading
  252:      `0' for base 8).  *Note Entry Point::, for a discussion of defaults
  253:      and other ways of specifying the entry point.
  254: 
  255: `--exclude-libs LIB,LIB,...'
  256:      Specifies a list of archive libraries from which symbols should
  257:      not be automatically exported. The library names may be delimited
  258:      by commas or colons.  Specifying `--exclude-libs ALL' excludes
  259:      symbols in all archive libraries from automatic export.  This
  260:      option is available only for the i386 PE targeted port of the
  261:      linker and for ELF targeted ports.  For i386 PE, symbols
  262:      explicitly listed in a .def file are still exported, regardless of
  263:      this option.  For ELF targeted ports, symbols affected by this
  264:      option will be treated as hidden.
  265: 
  266: `-E'
  267: `--export-dynamic'
  268:      When creating a dynamically linked executable, add all symbols to
  269:      the dynamic symbol table.  The dynamic symbol table is the set of
  270:      symbols which are visible from dynamic objects at run time.
  271: 
  272:      If you do not use this option, the dynamic symbol table will
  273:      normally contain only those symbols which are referenced by some
  274:      dynamic object mentioned in the link.
  275: 
  276:      If you use `dlopen' to load a dynamic object which needs to refer
  277:      back to the symbols defined by the program, rather than some other
  278:      dynamic object, then you will probably need to use this option when
  279:      linking the program itself.
  280: 
  281:      You can also use the dynamic list to control what symbols should
  282:      be added to the dynamic symbol table if the output format supports
  283:      it.  See the description of `--dynamic-list'.
  284: 
  285: `-EB'
  286:      Link big-endian objects.  This affects the default output format.
  287: 
  288: `-EL'
  289:      Link little-endian objects.  This affects the default output
  290:      format.
  291: 
  292: `-f'
  293: `--auxiliary NAME'
  294:      When creating an ELF shared object, set the internal DT_AUXILIARY
  295:      field to the specified name.  This tells the dynamic linker that
  296:      the symbol table of the shared object should be used as an
  297:      auxiliary filter on the symbol table of the shared object NAME.
  298: 
  299:      If you later link a program against this filter object, then, when
  300:      you run the program, the dynamic linker will see the DT_AUXILIARY
  301:      field.  If the dynamic linker resolves any symbols from the filter
  302:      object, it will first check whether there is a definition in the
  303:      shared object NAME.  If there is one, it will be used instead of
  304:      the definition in the filter object.  The shared object NAME need
  305:      not exist.  Thus the shared object NAME may be used to provide an
  306:      alternative implementation of certain functions, perhaps for
  307:      debugging or for machine specific performance.
  308: 
  309:      This option may be specified more than once.  The DT_AUXILIARY
  310:      entries will be created in the order in which they appear on the
  311:      command line.
  312: 
  313: `-F NAME'
  314: `--filter NAME'
  315:      When creating an ELF shared object, set the internal DT_FILTER
  316:      field to the specified name.  This tells the dynamic linker that
  317:      the symbol table of the shared object which is being created
  318:      should be used as a filter on the symbol table of the shared
  319:      object NAME.
  320: 
  321:      If you later link a program against this filter object, then, when
  322:      you run the program, the dynamic linker will see the DT_FILTER
  323:      field.  The dynamic linker will resolve symbols according to the
  324:      symbol table of the filter object as usual, but it will actually
  325:      link to the definitions found in the shared object NAME.  Thus the
  326:      filter object can be used to select a subset of the symbols
  327:      provided by the object NAME.
  328: 
  329:      Some older linkers used the `-F' option throughout a compilation
  330:      toolchain for specifying object-file format for both input and
  331:      output object files.  The GNU linker uses other mechanisms for
  332:      this purpose: the `-b', `--format', `--oformat' options, the
  333:      `TARGET' command in linker scripts, and the `GNUTARGET'
  334:      environment variable.  The GNU linker will ignore the `-F' option
  335:      when not creating an ELF shared object.
  336: 
  337: `-fini NAME'
  338:      When creating an ELF executable or shared object, call NAME when
  339:      the executable or shared object is unloaded, by setting DT_FINI to
  340:      the address of the function.  By default, the linker uses `_fini'
  341:      as the function to call.
  342: 
  343: `-g'
  344:      Ignored.  Provided for compatibility with other tools.
  345: 
  346: `-GVALUE'
  347: `--gpsize=VALUE'
  348:      Set the maximum size of objects to be optimized using the GP
  349:      register to SIZE.  This is only meaningful for object file formats
  350:      such as MIPS ECOFF which supports putting large and small objects
  351:      into different sections.  This is ignored for other object file
  352:      formats.
  353: 
  354: `-hNAME'
  355: `-soname=NAME'
  356:      When creating an ELF shared object, set the internal DT_SONAME
  357:      field to the specified name.  When an executable is linked with a
  358:      shared object which has a DT_SONAME field, then when the
  359:      executable is run the dynamic linker will attempt to load the
  360:      shared object specified by the DT_SONAME field rather than the
  361:      using the file name given to the linker.
  362: 
  363: `-i'
  364:      Perform an incremental link (same as option `-r').
  365: 
  366: `-init NAME'
  367:      When creating an ELF executable or shared object, call NAME when
  368:      the executable or shared object is loaded, by setting DT_INIT to
  369:      the address of the function.  By default, the linker uses `_init'
  370:      as the function to call.
  371: 
  372: `-lNAMESPEC'
  373: `--library=NAMESPEC'
  374:      Add the archive or object file specified by NAMESPEC to the list
  375:      of files to link.  This option may be used any number of times.
  376:      If NAMESPEC is of the form `:FILENAME', `ld' will search the
  377:      library path for a file called FILENAME, otherise it will search
  378:      the library path for a file called `libNAMESPEC.a'.
  379: 
  380:      On systems which support shared libraries, `ld' may also search for
  381:      files other than `libNAMESPEC.a'.  Specifically, on ELF and SunOS
  382:      systems, `ld' will search a directory for a library called
  383:      `libNAMESPEC.so' before searching for one called `libNAMESPEC.a'.
  384:      (By convention, a `.so' extension indicates a shared library.)
  385:      Note that this behavior does not apply to `:FILENAME', which
  386:      always specifies a file called FILENAME.
  387: 
  388:      The linker will search an archive only once, at the location where
  389:      it is specified on the command line.  If the archive defines a
  390:      symbol which was undefined in some object which appeared before
  391:      the archive on the command line, the linker will include the
  392:      appropriate file(s) from the archive.  However, an undefined
  393:      symbol in an object appearing later on the command line will not
  394:      cause the linker to search the archive again.
  395: 
  396:      See the `-(' option for a way to force the linker to search
  397:      archives multiple times.
  398: 
  399:      You may list the same archive multiple times on the command line.
  400: 
  401:      This type of archive searching is standard for Unix linkers.
  402:      However, if you are using `ld' on AIX, note that it is different
  403:      from the behaviour of the AIX linker.
  404: 
  405: `-LSEARCHDIR'
  406: `--library-path=SEARCHDIR'
  407:      Add path SEARCHDIR to the list of paths that `ld' will search for
  408:      archive libraries and `ld' control scripts.  You may use this
  409:      option any number of times.  The directories are searched in the
  410:      order in which they are specified on the command line.
  411:      Directories specified on the command line are searched before the
  412:      default directories.  All `-L' options apply to all `-l' options,
  413:      regardless of the order in which the options appear.
  414: 
  415:      If SEARCHDIR begins with `=', then the `=' will be replaced by the
  416:      "sysroot prefix", a path specified when the linker is configured.
  417: 
  418:      The default set of paths searched (without being specified with
  419:      `-L') depends on which emulation mode `ld' is using, and in some
  420:      cases also on how it was configured.  *Note Environment::.
  421: 
  422:      The paths can also be specified in a link script with the
  423:      `SEARCH_DIR' command.  Directories specified this way are searched
  424:      at the point in which the linker script appears in the command
  425:      line.
  426: 
  427: `-mEMULATION'
  428:      Emulate the EMULATION linker.  You can list the available
  429:      emulations with the `--verbose' or `-V' options.
  430: 
  431:      If the `-m' option is not used, the emulation is taken from the
  432:      `LDEMULATION' environment variable, if that is defined.
  433: 
  434:      Otherwise, the default emulation depends upon how the linker was
  435:      configured.
  436: 
  437: `-M'
  438: `--print-map'
  439:      Print a link map to the standard output.  A link map provides
  440:      information about the link, including the following:
  441: 
  442:         * Where object files are mapped into memory.
  443: 
  444:         * How common symbols are allocated.
  445: 
  446:         * All archive members included in the link, with a mention of
  447:           the symbol which caused the archive member to be brought in.
  448: 
  449:         * The values assigned to symbols.
  450: 
  451:           Note - symbols whose values are computed by an expression
  452:           which involves a reference to a previous value of the same
  453:           symbol may not have correct result displayed in the link map.
  454:           This is because the linker discards intermediate results and
  455:           only retains the final value of an expression.  Under such
  456:           circumstances the linker will display the final value
  457:           enclosed by square brackets.  Thus for example a linker
  458:           script containing:
  459: 
  460:                   foo = 1
  461:                   foo = foo * 4
  462:                   foo = foo + 8
  463: 
  464:           will produce the following output in the link map if the `-M'
  465:           option is used:
  466: 
  467:                   0x00000001                foo = 0x1
  468:                   [0x0000000c]                foo = (foo * 0x4)
  469:                   [0x0000000c]                foo = (foo + 0x8)
  470: 
  471:           See *Note Expressions:: for more information about
  472:           expressions in linker scripts.
  473: 
  474: `-n'
  475: `--nmagic'
  476:      Turn off page alignment of sections, and mark the output as
  477:      `NMAGIC' if possible.
  478: 
  479: `-N'
  480: `--omagic'
  481:      Set the text and data sections to be readable and writable.  Also,
  482:      do not page-align the data segment, and disable linking against
  483:      shared libraries.  If the output format supports Unix style magic
  484:      numbers, mark the output as `OMAGIC'. Note: Although a writable
  485:      text section is allowed for PE-COFF targets, it does not conform
  486:      to the format specification published by Microsoft.
  487: 
  488: `--no-omagic'
  489:      This option negates most of the effects of the `-N' option.  It
  490:      sets the text section to be read-only, and forces the data segment
  491:      to be page-aligned.  Note - this option does not enable linking
  492:      against shared libraries.  Use `-Bdynamic' for this.
  493: 
  494: `-o OUTPUT'
  495: `--output=OUTPUT'
  496:      Use OUTPUT as the name for the program produced by `ld'; if this
  497:      option is not specified, the name `a.out' is used by default.  The
  498:      script command `OUTPUT' can also specify the output file name.
  499: 
  500: `-O LEVEL'
  501:      If LEVEL is a numeric values greater than zero `ld' optimizes the
  502:      output.  This might take significantly longer and therefore
  503:      probably should only be enabled for the final binary.  At the
  504:      moment this option only affects ELF shared library generation.
  505:      Future releases of the linker may make more use of this option.
  506:      Also currently there is no difference in the linker's behaviour
  507:      for different non-zero values of this option.  Again this may
  508:      change with future releases.
  509: 
  510: `-q'
  511: `--emit-relocs'
  512:      Leave relocation sections and contents in fully linked executables.
  513:      Post link analysis and optimization tools may need this
  514:      information in order to perform correct modifications of
  515:      executables.  This results in larger executables.
  516: 
  517:      This option is currently only supported on ELF platforms.
  518: 
  519: `--force-dynamic'
  520:      Force the output file to have dynamic sections.  This option is
  521:      specific to VxWorks targets.
  522: 
  523: `-r'
  524: `--relocatable'
  525:      Generate relocatable output--i.e., generate an output file that
  526:      can in turn serve as input to `ld'.  This is often called "partial
  527:      linking".  As a side effect, in environments that support standard
  528:      Unix magic numbers, this option also sets the output file's magic
  529:      number to `OMAGIC'.  If this option is not specified, an absolute
  530:      file is produced.  When linking C++ programs, this option _will
  531:      not_ resolve references to constructors; to do that, use `-Ur'.
  532: 
  533:      When an input file does not have the same format as the output
  534:      file, partial linking is only supported if that input file does
  535:      not contain any relocations.  Different output formats can have
  536:      further restrictions; for example some `a.out'-based formats do
  537:      not support partial linking with input files in other formats at
  538:      all.
  539: 
  540:      This option does the same thing as `-i'.
  541: 
  542: `-R FILENAME'
  543: `--just-symbols=FILENAME'
  544:      Read symbol names and their addresses from FILENAME, but do not
  545:      relocate it or include it in the output.  This allows your output
  546:      file to refer symbolically to absolute locations of memory defined
  547:      in other programs.  You may use this option more than once.
  548: 
  549:      For compatibility with other ELF linkers, if the `-R' option is
  550:      followed by a directory name, rather than a file name, it is
  551:      treated as the `-rpath' option.
  552: 
  553: `-s'
  554: `--strip-all'
  555:      Omit all symbol information from the output file.
  556: 
  557: `-S'
  558: `--strip-debug'
  559:      Omit debugger symbol information (but not all symbols) from the
  560:      output file.
  561: 
  562: `-t'
  563: `--trace'
  564:      Print the names of the input files as `ld' processes them.
  565: 
  566: `-T SCRIPTFILE'
  567: `--script=SCRIPTFILE'
  568:      Use SCRIPTFILE as the linker script.  This script replaces `ld''s
  569:      default linker script (rather than adding to it), so COMMANDFILE
  570:      must specify everything necessary to describe the output file.
  571:      *Note Scripts::.  If SCRIPTFILE does not exist in the current
  572:      directory, `ld' looks for it in the directories specified by any
  573:      preceding `-L' options.  Multiple `-T' options accumulate.
  574: 
  575: `-dT SCRIPTFILE'
  576: `--default-script=SCRIPTFILE'
  577:      Use SCRIPTFILE as the default linker script.  *Note Scripts::.
  578: 
  579:      This option is similar to the `--script' option except that
  580:      processing of the script is delayed until after the rest of the
  581:      command line has been processed.  This allows options placed after
  582:      the `--default-script' option on the command line to affect the
  583:      behaviour of the linker script, which can be important when the
  584:      linker command line cannot be directly controlled by the user.
  585:      (eg because the command line is being constructed by another tool,
  586:      such as `gcc').
  587: 
  588: `-u SYMBOL'
  589: `--undefined=SYMBOL'
  590:      Force SYMBOL to be entered in the output file as an undefined
  591:      symbol.  Doing this may, for example, trigger linking of additional
  592:      modules from standard libraries.  `-u' may be repeated with
  593:      different option arguments to enter additional undefined symbols.
  594:      This option is equivalent to the `EXTERN' linker script command.
  595: 
  596: `-Ur'
  597:      For anything other than C++ programs, this option is equivalent to
  598:      `-r': it generates relocatable output--i.e., an output file that
  599:      can in turn serve as input to `ld'.  When linking C++ programs,
  600:      `-Ur' _does_ resolve references to constructors, unlike `-r'.  It
  601:      does not work to use `-Ur' on files that were themselves linked
  602:      with `-Ur'; once the constructor table has been built, it cannot
  603:      be added to.  Use `-Ur' only for the last partial link, and `-r'
  604:      for the others.
  605: 
  606: `--unique[=SECTION]'
  607:      Creates a separate output section for every input section matching
  608:      SECTION, or if the optional wildcard SECTION argument is missing,
  609:      for every orphan input section.  An orphan section is one not
  610:      specifically mentioned in a linker script.  You may use this option
  611:      multiple times on the command line;  It prevents the normal
  612:      merging of input sections with the same name, overriding output
  613:      section assignments in a linker script.
  614: 
  615: `-v'
  616: `--version'
  617: `-V'
  618:      Display the version number for `ld'.  The `-V' option also lists
  619:      the supported emulations.
  620: 
  621: `-x'
  622: `--discard-all'
  623:      Delete all local symbols.
  624: 
  625: `-X'
  626: `--discard-locals'
  627:      Delete all temporary local symbols.  (These symbols start with
  628:      system-specific local label prefixes, typically `.L' for ELF
  629:      systems or `L' for traditional a.out systems.)
  630: 
  631: `-y SYMBOL'
  632: `--trace-symbol=SYMBOL'
  633:      Print the name of each linked file in which SYMBOL appears.  This
  634:      option may be given any number of times.  On many systems it is
  635:      necessary to prepend an underscore.
  636: 
  637:      This option is useful when you have an undefined symbol in your
  638:      link but don't know where the reference is coming from.
  639: 
  640: `-Y PATH'
  641:      Add PATH to the default library search path.  This option exists
  642:      for Solaris compatibility.
  643: 
  644: `-z KEYWORD'
  645:      The recognized keywords are:
  646:     `combreloc'
  647:           Combines multiple reloc sections and sorts them to make
  648:           dynamic symbol lookup caching possible.
  649: 
  650:     `defs'
  651:           Disallows undefined symbols in object files.  Undefined
  652:           symbols in shared libraries are still allowed.
  653: 
  654:     `execstack'
  655:           Marks the object as requiring executable stack.
  656: 
  657:     `initfirst'
  658:           This option is only meaningful when building a shared object.
  659:           It marks the object so that its runtime initialization will
  660:           occur before the runtime initialization of any other objects
  661:           brought into the process at the same time.  Similarly the
  662:           runtime finalization of the object will occur after the
  663:           runtime finalization of any other objects.
  664: 
  665:     `interpose'
  666:           Marks the object that its symbol table interposes before all
  667:           symbols but the primary executable.
  668: 
  669:     `lazy'
  670:           When generating an executable or shared library, mark it to
  671:           tell the dynamic linker to defer function call resolution to
  672:           the point when the function is called (lazy binding), rather
  673:           than at load time.  Lazy binding is the default.
  674: 
  675:     `loadfltr'
  676:           Marks  the object that its filters be processed immediately at
  677:           runtime.
  678: 
  679:     `muldefs'
  680:           Allows multiple definitions.
  681: 
  682:     `nocombreloc'
  683:           Disables multiple reloc sections combining.
  684: 
  685:     `nocopyreloc'
  686:           Disables production of copy relocs.
  687: 
  688:     `nodefaultlib'
  689:           Marks the object that the search for dependencies of this
  690:           object will ignore any default library search paths.
  691: 
  692:     `nodelete'
  693:           Marks the object shouldn't be unloaded at runtime.
  694: 
  695:     `nodlopen'
  696:           Marks the object not available to `dlopen'.
  697: 
  698:     `nodump'
  699:           Marks the object can not be dumped by `dldump'.
  700: 
  701:     `noexecstack'
  702:           Marks the object as not requiring executable stack.
  703: 
  704:     `norelro'
  705:           Don't create an ELF `PT_GNU_RELRO' segment header in the
  706:           object.
  707: 
  708:     `now'
  709:           When generating an executable or shared library, mark it to
  710:           tell the dynamic linker to resolve all symbols when the
  711:           program is started, or when the shared library is linked to
  712:           using dlopen, instead of deferring function call resolution
  713:           to the point when the function is first called.
  714: 
  715:     `origin'
  716:           Marks the object may contain $ORIGIN.
  717: 
  718:     `relro'
  719:           Create an ELF `PT_GNU_RELRO' segment header in the object.
  720: 
  721:     `max-page-size=VALUE'
  722:           Set the emulation maximum page size to VALUE.
  723: 
  724:     `common-page-size=VALUE'
  725:           Set the emulation common page size to VALUE.
  726: 
  727: 
  728:      Other keywords are ignored for Solaris compatibility.
  729: 
  730: `-( ARCHIVES -)'
  731: `--start-group ARCHIVES --end-group'
  732:      The ARCHIVES should be a list of archive files.  They may be
  733:      either explicit file names, or `-l' options.
  734: 
  735:      The specified archives are searched repeatedly until no new
  736:      undefined references are created.  Normally, an archive is
  737:      searched only once in the order that it is specified on the
  738:      command line.  If a symbol in that archive is needed to resolve an
  739:      undefined symbol referred to by an object in an archive that
  740:      appears later on the command line, the linker would not be able to
  741:      resolve that reference.  By grouping the archives, they all be
  742:      searched repeatedly until all possible references are resolved.
  743: 
  744:      Using this option has a significant performance cost.  It is best
  745:      to use it only when there are unavoidable circular references
  746:      between two or more archives.
  747: 
  748: `--accept-unknown-input-arch'
  749: `--no-accept-unknown-input-arch'
  750:      Tells the linker to accept input files whose architecture cannot be
  751:      recognised.  The assumption is that the user knows what they are
  752:      doing and deliberately wants to link in these unknown input files.
  753:      This was the default behaviour of the linker, before release
  754:      2.14.  The default behaviour from release 2.14 onwards is to
  755:      reject such input files, and so the `--accept-unknown-input-arch'
  756:      option has been added to restore the old behaviour.
  757: