1: .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
    2: .\"
    3: .\" Standard preamble:
    4: .\" ========================================================================
    5: .de Sh \" Subsection heading
    6: .br
    7: .if t .Sp
    8: .ne 5
    9: .PP
   10: \fB\\$1\fR
   11: .PP
   12: ..
   13: .de Sp \" Vertical space (when we can't use .PP)
   14: .if t .sp .5v
   15: .if n .sp
   16: ..
   17: .de Vb \" Begin verbatim text
   18: .ft CW
   19: .nf
   20: .ne \\$1
   21: ..
   22: .de Ve \" End verbatim text
   23: .ft R
   24: .fi
   25: ..
   26: .\" Set up some character translations and predefined strings.  \*(-- will
   27: .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
   28: .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
   29: .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
   30: .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
   31: .\" nothing in troff, for use with C<>.
   32: .tr \(*W-
   33: .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
   34: .ie n \{\
   35: .    ds -- \(*W-
   36: .    ds PI pi
   37: .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
   38: .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
   39: .    ds L" ""
   40: .    ds R" ""
   41: .    ds C` ""
   42: .    ds C' ""
   43: 'br\}
   44: .el\{\
   45: .    ds -- \|\(em\|
   46: .    ds PI \(*p
   47: .    ds L" ``
   48: .    ds R" ''
   49: 'br\}
   50: .\"
   51: .\" If the F register is turned on, we'll generate index entries on stderr for
   52: .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
   53: .\" entries marked with X<> in POD.  Of course, you'll have to process the
   54: .\" output yourself in some meaningful fashion.
   55: .if \nF \{\
   56: .    de IX
   57: .    tm Index:\\$1\t\\n%\t"\\$2"
   58: ..
   59: .    nr % 0
   60: .    rr F
   61: .\}
   62: .\"
   63: .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
   64: .\" way too many mistakes in technical documents.
   65: .hy 0
   66: .\"
   67: .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
   68: .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
   69: .    \" fudge factors for nroff and troff
   70: .if n \{\
   71: .    ds #H 0
   72: .    ds #V .8m
   73: .    ds #F .3m
   74: .    ds #[ \f1
   75: .    ds #] \fP
   76: .\}
   77: .if t \{\
   78: .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
   79: .    ds #V .6m
   80: .    ds #F 0
   81: .    ds #[ \&
   82: .    ds #] \&
   83: .\}
   84: .    \" simple accents for nroff and troff
   85: .if n \{\
   86: .    ds ' \&
   87: .    ds ` \&
   88: .    ds ^ \&
   89: .    ds , \&
   90: .    ds ~ ~
   91: .    ds /
   92: .\}
   93: .if t \{\
   94: .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
   95: .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
   96: .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
   97: .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
   98: .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
   99: .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  100: .\}
  101: .    \" troff and (daisy-wheel) nroff accents
  102: .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  103: .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
  104: .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
  105: .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
  106: .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
  107: .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
  108: .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
  109: .ds ae a\h'-(\w'a'u*4/10)'e
  110: .ds Ae A\h'-(\w'A'u*4/10)'E
  111: .    \" corrections for vroff
  112: .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
  113: .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
  114: .    \" for low resolution devices (crt and lpr)
  115: .if \n(.H>23 .if \n(.V>19 \
  116: \{\
  117: .    ds : e
  118: .    ds 8 ss
  119: .    ds o a
  120: .    ds d- d\h'-1'\(ga
  121: .    ds D- D\h'-1'\(hy
  122: .    ds th \o'bp'
  123: .    ds Th \o'LP'
  124: .    ds ae ae
  125: .    ds Ae AE
  126: .\}
  127: .rm #[ #] #H #V #F C
  128: .\" ========================================================================
  129: .\"
  130: .IX Title "LD 1"
  131: .TH LD 1 "2007-08-28" "binutils-2.18" "GNU Development Tools"
  132: .SH "NAME"
  133: ld \- The GNU linker
  134: .SH "SYNOPSIS"
  135: .IX Header "SYNOPSIS"
  136: ld [\fBoptions\fR] \fIobjfile\fR ...
  137: .SH "DESCRIPTION"
  138: .IX Header "DESCRIPTION"
  139: \&\fBld\fR combines a number of object and archive files, relocates
  140: their data and ties up symbol references. Usually the last step in
  141: compiling a program is to run \fBld\fR.
  142: .PP
  143: \&\fBld\fR accepts Linker Command Language files written in
  144: a superset of \s-1AT&T\s0's Link Editor Command Language syntax,
  145: to provide explicit and total control over the linking process.
  146: .PP
  147: This man page does not describe the command language; see the
  148: \&\fBld\fR entry in \f(CW\*(C`info\*(C'\fR for full details on the command
  149: language and on other aspects of the \s-1GNU\s0 linker.
  150: .PP
  151: This version of \fBld\fR uses the general purpose \s-1BFD\s0 libraries
  152: to operate on object files. This allows \fBld\fR to read, combine, and
  153: write object files in many different formats\-\-\-for example, \s-1COFF\s0 or
  154: \&\f(CW\*(C`a.out\*(C'\fR.  Different formats may be linked together to produce any
  155: available kind of object file.  
  156: .PP
  157: Aside from its flexibility, the \s-1GNU\s0 linker is more helpful than other
  158: linkers in providing diagnostic information.  Many linkers abandon
  159: execution immediately upon encountering an error; whenever possible,
  160: \&\fBld\fR continues executing, allowing you to identify other errors
  161: (or, in some cases, to get an output file in spite of the error).
  162: .PP
  163: The \s-1GNU\s0 linker \fBld\fR is meant to cover a broad range of situations,
  164: and to be as compatible as possible with other linkers.  As a result,
  165: you have many choices to control its behavior.
  166: .SH "OPTIONS"
  167: .IX Header "OPTIONS"
  168: The linker supports a plethora of command-line options, but in actual
  169: practice few of them are used in any particular context.
  170: For instance, a frequent use of \fBld\fR is to link standard Unix
  171: object files on a standard, supported Unix system.  On such a system, to
  172: link a file \f(CW\*(C`hello.o\*(C'\fR:
  173: .PP
  174: .Vb 1
  175: \&        ld \-o <output> /lib/crt0.o hello.o \-lc
  176: .Ve
  177: .PP
  178: This tells \fBld\fR to produce a file called \fIoutput\fR as the
  179: result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and
  180: the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search
  181: directories.  (See the discussion of the \fB\-l\fR option below.)
  182: .PP
  183: Some of the command-line options to \fBld\fR may be specified at any
  184: point in the command line.  However, options which refer to files, such
  185: as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at
  186: which the option appears in the command line, relative to the object
  187: files and other file options.  Repeating non-file options with a
  188: different argument will either have no further effect, or override prior
  189: occurrences (those further to the left on the command line) of that
  190: option.  Options which may be meaningfully specified more than once are
  191: noted in the descriptions below.
  192: .PP
  193: Non-option arguments are object files or archives which are to be linked
  194: together.  They may follow, precede, or be mixed in with command-line
  195: options, except that an object file argument may not be placed between
  196: an option and its argument.
  197: .PP
  198: Usually the linker is invoked with at least one object file, but you can
  199: specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR,
  200: and the script command language.  If \fIno\fR binary input files at all
  201: are specified, the linker does not produce any output, and issues the
  202: message \fBNo input files\fR.
  203: .PP
  204: If the linker cannot recognize the format of an object file, it will
  205: assume that it is a linker script.  A script specified in this way
  206: augments the main linker script used for the link (either the default
  207: linker script or the one specified by using \fB\-T\fR).  This feature
  208: permits the linker to link against a file which appears to be an object
  209: or an archive, but actually merely defines some symbol values, or uses
  210: \&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects.  Note that
  211: specifying a script in this way merely augments the main linker script;
  212: use the \fB\-T\fR option to replace the default linker script entirely.
  213: .PP
  214: For options whose names are a single letter,
  215: option arguments must either follow the option letter without intervening
  216: whitespace, or be given as separate arguments immediately following the
  217: option that requires them.
  218: .PP
  219: For options whose names are multiple letters, either one dash or two can
  220: precede the option name; for example, \fB\-trace\-symbol\fR and
  221: \&\fB\-\-trace\-symbol\fR are equivalent.  Note\-\-\-there is one exception to
  222: this rule.  Multiple letter options that start with a lower case 'o' can
  223: only be preceded by two dashes.  This is to reduce confusion with the
  224: \&\fB\-o\fR option.  So for example \fB\-omagic\fR sets the output file
  225: name to \fBmagic\fR whereas \fB\-\-omagic\fR sets the \s-1NMAGIC\s0 flag on the
  226: output.
  227: .PP
  228: Arguments to multiple-letter options must either be separated from the
  229: option name by an equals sign, or be given as separate arguments
  230: immediately following the option that requires them.  For example,
  231: \&\fB\-\-trace\-symbol foo\fR and \fB\-\-trace\-symbol=foo\fR are equivalent.
  232: Unique abbreviations of the names of multiple-letter options are
  233: accepted.
  234: .PP
  235: Note\-\-\-if the linker is being invoked indirectly, via a compiler driver
  236: (e.g. \fBgcc\fR) then all the linker command line options should be
  237: prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular
  238: compiler driver) like this:
  239: .PP
  240: .Vb 1
  241: \&          gcc \-Wl,\-\-startgroup foo.o bar.o \-Wl,\-\-endgroup
  242: .Ve
  243: .PP
  244: This is important, because otherwise the compiler driver program may
  245: silently drop the linker options, resulting in a bad link.
  246: .PP
  247: Here is a table of the generic command line switches accepted by the \s-1GNU\s0
  248: linker:
  249: .IP "\fB@\fR\fIfile\fR" 4
  250: .IX Item "@file"
  251: Read command-line options from \fIfile\fR.  The options read are
  252: inserted in place of the original @\fIfile\fR option.  If \fIfile\fR
  253: does not exist, or cannot be read, then the option will be treated
  254: literally, and not removed.  
  255: .Sp
  256: Options in \fIfile\fR are separated by whitespace.  A whitespace
  257: character may be included in an option by surrounding the entire
  258: option in either single or double quotes.  Any character (including a
  259: backslash) may be included by prefixing the character to be included
  260: with a backslash.  The \fIfile\fR may itself contain additional
  261: @\fIfile\fR options; any such options will be processed recursively.
  262: .IP "\fB\-a\fR\fIkeyword\fR" 4
  263: .IX Item "-akeyword"
  264: This option is supported for \s-1HP/UX\s0 compatibility.  The \fIkeyword\fR
  265: argument must be one of the strings \fBarchive\fR, \fBshared\fR, or
  266: \&\fBdefault\fR.  \fB\-aarchive\fR is functionally equivalent to
  267: \&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent
  268: to \fB\-Bdynamic\fR.  This option may be used any number of times.
  269: .IP "\fB\-A\fR\fIarchitecture\fR" 4
  270: .IX Item "-Aarchitecture"
  271: .PD 0
  272: .IP "\fB\-\-architecture=\fR\fIarchitecture\fR" 4
  273: .IX Item "--architecture=architecture"
  274: .PD
  275: In the current release of \fBld\fR, this option is useful only for the
  276: Intel 960 family of architectures.  In that \fBld\fR configuration, the
  277: \&\fIarchitecture\fR argument identifies the particular architecture in
  278: the 960 family, enabling some safeguards and modifying the
  279: archive-library search path.  
  280: .Sp
  281: Future releases of \fBld\fR may support similar functionality for
  282: other architecture families.
  283: .IP "\fB\-b\fR \fIinput-format\fR" 4
  284: .IX Item "-b input-format"
  285: .PD 0
  286: .IP "\fB\-\-format=\fR\fIinput-format\fR" 4
  287: .IX Item "--format=input-format"
  288: .PD
  289: \&\fBld\fR may be configured to support more than one kind of object
  290: file.  If your \fBld\fR is configured this way, you can use the
  291: \&\fB\-b\fR option to specify the binary format for input object files
  292: that follow this option on the command line.  Even when \fBld\fR is
  293: configured to support alternative object formats, you don't usually need
  294: to specify this, as \fBld\fR should be configured to expect as a
  295: default input format the most usual format on each machine.
  296: \&\fIinput-format\fR is a text string, the name of a particular format
  297: supported by the \s-1BFD\s0 libraries.  (You can list the available binary
  298: formats with \fBobjdump \-i\fR.)
  299: .Sp
  300: You may want to use this option if you are linking files with an unusual
  301: binary format.  You can also use \fB\-b\fR to switch formats explicitly (when
  302: linking object files of different formats), by including
  303: \&\fB\-b\fR \fIinput-format\fR before each group of object files in a
  304: particular format.
  305: .Sp
  306: The default format is taken from the environment variable
  307: \&\f(CW\*(C`GNUTARGET\*(C'\fR.
  308: .Sp
  309: You can also define the input format from a script, using the command
  310: \&\f(CW\*(C`TARGET\*(C'\fR;
  311: .IP "\fB\-c\fR \fIMRI-commandfile\fR" 4
  312: .IX Item "-c MRI-commandfile"
  313: .PD 0
  314: .IP "\fB\-\-mri\-script=\fR\fIMRI-commandfile\fR" 4
  315: .IX Item "--mri-script=MRI-commandfile"
  316: .PD
  317: For compatibility with linkers produced by \s-1MRI\s0, \fBld\fR accepts script
  318: files written in an alternate, restricted command language, described in
  319: the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation.
  320: Introduce \s-1MRI\s0 script files with
  321: the option \fB\-c\fR; use the \fB\-T\fR option to run linker
  322: scripts written in the general-purpose \fBld\fR scripting language.
  323: If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories
  324: specified by any \fB\-L\fR options.
  325: .IP "\fB\-d\fR" 4
  326: .IX Item "-d"
  327: .PD 0
  328: .IP "\fB\-dc\fR" 4
  329: .IX Item "-dc"
  330: .IP "\fB\-dp\fR" 4
  331: .IX Item "-dp"
  332: .PD
  333: These three options are equivalent; multiple forms are supported for
  334: compatibility with other linkers.  They assign space to common symbols
  335: even if a relocatable output file is specified (with \fB\-r\fR).  The
  336: script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect.
  337: .IP "\fB\-e\fR \fIentry\fR" 4
  338: .IX Item "-e entry"
  339: .PD 0
  340: .IP "\fB\-\-entry=\fR\fIentry\fR" 4
  341: .IX Item "--entry=entry"
  342: .PD
  343: Use \fIentry\fR as the explicit symbol for beginning execution of your
  344: program, rather than the default entry point.  If there is no symbol
  345: named \fIentry\fR, the linker will try to parse \fIentry\fR as a number,
  346: and use that as the entry address (the number will be interpreted in
  347: base 10; you may use a leading \fB0x\fR for base 16, or a leading
  348: \&\fB0\fR for base 8).  
  349: .IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4
  350: .IX Item "--exclude-libs lib,lib,..."
  351: Specifies a list of archive libraries from which symbols should not be automatically
  352: exported. The library names may be delimited by commas or colons.  Specifying
  353: \&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from
  354: automatic export.  This option is available only for the i386 \s-1PE\s0 targeted
  355: port of the linker and for \s-1ELF\s0 targeted ports.  For i386 \s-1PE\s0, symbols
  356: explicitly listed in a .def file are still exported, regardless of this
  357: option.  For \s-1ELF\s0 targeted ports, symbols affected by this option will
  358: be treated as hidden.
  359: .IP "\fB\-E\fR" 4
  360: .IX Item "-E"
  361: .PD 0
  362: .IP "\fB\-\-export\-dynamic\fR" 4
  363: .IX Item "--export-dynamic"
  364: .PD
  365: When creating a dynamically linked executable, add all symbols to the
  366: dynamic symbol table.  The dynamic symbol table is the set of symbols
  367: which are visible from dynamic objects at run time.
  368: .Sp
  369: If you do not use this option, the dynamic symbol table will normally
  370: contain only those symbols which are referenced by some dynamic object
  371: mentioned in the link.
  372: .Sp
  373: If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer
  374: back to the symbols defined by the program, rather than some other
  375: dynamic object, then you will probably need to use this option when
  376: linking the program itself.
  377: .Sp
  378: You can also use the dynamic list to control what symbols should
  379: be added to the dynamic symbol table if the output format supports it.
  380: See the description of \fB\-\-dynamic\-list\fR.
  381: .IP "\fB\-EB\fR" 4
  382: .IX Item "-EB"
  383: Link big-endian objects.  This affects the default output format.
  384: .IP "\fB\-EL\fR" 4
  385: .IX Item "-EL"
  386: Link little-endian objects.  This affects the default output format.
  387: .IP "\fB\-f\fR" 4
  388: .IX Item "-f"
  389: .PD 0
  390: .IP "\fB\-\-auxiliary\fR \fIname\fR" 4
  391: .IX Item "--auxiliary name"
  392: .PD
  393: When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 field
  394: to the specified name.  This tells the dynamic linker that the symbol
  395: table of the shared object should be used as an auxiliary filter on the
  396: symbol table of the shared object \fIname\fR.
  397: .Sp
  398: If you later link a program against this filter object, then, when you
  399: run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 field.  If
  400: the dynamic linker resolves any symbols from the filter object, it will
  401: first check whether there is a definition in the shared object
  402: \&\fIname\fR.  If there is one, it will be used instead of the definition
  403: in the filter object.  The shared object \fIname\fR need not exist.
  404: Thus the shared object \fIname\fR may be used to provide an alternative
  405: implementation of certain functions, perhaps for debugging or for
  406: machine specific performance.
  407: .Sp
  408: This option may be specified more than once.  The \s-1DT_AUXILIARY\s0 entries
  409: will be created in the order in which they appear on the command line.
  410: .IP "\fB\-F\fR \fIname\fR" 4
  411: .IX Item "-F name"
  412: .PD 0
  413: .IP "\fB\-\-filter\fR \fIname\fR" 4
  414: .IX Item "--filter name"
  415: .PD
  416: When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 field to
  417: the specified name.  This tells the dynamic linker that the symbol table
  418: of the shared object which is being created should be used as a filter
  419: on the symbol table of the shared object \fIname\fR.
  420: .Sp
  421: If you later link a program against this filter object, then, when you
  422: run the program, the dynamic linker will see the \s-1DT_FILTER\s0 field.  The
  423: dynamic linker will resolve symbols according to the symbol table of the
  424: filter object as usual, but it will actually link to the definitions
  425: found in the shared object \fIname\fR.  Thus the filter object can be
  426: used to select a subset of the symbols provided by the object
  427: \&\fIname\fR.
  428: .Sp
  429: Some older linkers used the \fB\-F\fR option throughout a compilation
  430: toolchain for specifying object-file format for both input and output
  431: object files.
  432: The \s-1GNU\s0 linker uses other mechanisms for this purpose: the
  433: \&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the
  434: \&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR
  435: environment variable.
  436: The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not
  437: creating an \s-1ELF\s0 shared object.
  438: .IP "\fB\-fini\fR \fIname\fR" 4
  439: .IX Item "-fini name"
  440: When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
  441: executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the
  442: address of the function.  By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as
  443: the function to call.
  444: .IP "\fB\-g\fR" 4
  445: .IX Item "-g"
  446: Ignored.  Provided for compatibility with other tools.
  447: .IP "\fB\-G\fR\fIvalue\fR" 4
  448: .IX Item "-Gvalue"
  449: .PD 0
  450: .IP "\fB\-\-gpsize=\fR\fIvalue\fR" 4
  451: .IX Item "--gpsize=value"
  452: .PD
  453: Set the maximum size of objects to be optimized using the \s-1GP\s0 register to
  454: \&\fIsize\fR.  This is only meaningful for object file formats such as
  455: \&\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different
  456: sections.  This is ignored for other object file formats.
  457: .IP "\fB\-h\fR\fIname\fR" 4
  458: .IX Item "-hname"
  459: .PD 0
  460: .IP "\fB\-soname=\fR\fIname\fR" 4
  461: .IX Item "-soname=name"
  462: .PD
  463: When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to
  464: the specified name.  When an executable is linked with a shared object
  465: which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic
  466: linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0
  467: field rather than the using the file name given to the linker.
  468: .IP "\fB\-i\fR" 4
  469: .IX Item "-i"
  470: Perform an incremental link (same as option \fB\-r\fR).
  471: .IP "\fB\-init\fR \fIname\fR" 4
  472: .IX Item "-init name"
  473: When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
  474: executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address
  475: of the function.  By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the
  476: function to call.
  477: .IP "\fB\-l\fR\fInamespec\fR" 4
  478: .IX Item "-lnamespec"
  479: .PD 0
  480: .IP "\fB\-\-library=\fR\fInamespec\fR" 4
  481: .IX Item "--library=namespec"
  482: .PD
  483: Add the archive or object file specified by \fInamespec\fR to the
  484: list of files to link.  This option may be used any number of times.
  485: If \fInamespec\fR is of the form \fI:\fIfilename\fI\fR, \fBld\fR
  486: will search the library path for a file called \fIfilename\fR, otherise it
  487: will search the library path for a file called \fIlib\fInamespec\fI.a\fR.
  488: .Sp
  489: On systems which support shared libraries, \fBld\fR may also search for
  490: files other than \fIlib\fInamespec\fI.a\fR.  Specifically, on \s-1ELF\s0
  491: and SunOS systems, \fBld\fR will search a directory for a library
  492: called \fIlib\fInamespec\fI.so\fR before searching for one called
  493: \&\fIlib\fInamespec\fI.a\fR.  (By convention, a \f(CW\*(C`.so\*(C'\fR extension
  494: indicates a shared library.)  Note that this behavior does not apply
  495: to \fI:\fIfilename\fI\fR, which always specifies a file called
  496: \&\fIfilename\fR.
  497: .Sp
  498: The linker will search an archive only once, at the location where it is
  499: specified on the command line.  If the archive defines a symbol which
  500: was undefined in some object which appeared before the archive on the
  501: command line, the linker will include the appropriate file(s) from the
  502: archive.  However, an undefined symbol in an object appearing later on
  503: the command line will not cause the linker to search the archive again.
  504: .Sp
  505: See the \fB\-(\fR option for a way to force the linker to search
  506: archives multiple times.
  507: .Sp
  508: You may list the same archive multiple times on the command line.
  509: .Sp
  510: This type of archive searching is standard for Unix linkers.  However,
  511: if you are using \fBld\fR on \s-1AIX\s0, note that it is different from the
  512: behaviour of the \s-1AIX\s0 linker.
  513: .IP "\fB\-L\fR\fIsearchdir\fR" 4
  514: .IX Item "-Lsearchdir"
  515: .PD 0
  516: .IP "\fB\-\-library\-path=\fR\fIsearchdir\fR" 4
  517: .IX Item "--library-path=searchdir"
  518: .PD
  519: Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search
  520: for archive libraries and \fBld\fR control scripts.  You may use this
  521: option any number of times.  The directories are searched in the order
  522: in which they are specified on the command line.  Directories specified
  523: on the command line are searched before the default directories.  All
  524: \&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the
  525: order in which the options appear.
  526: .Sp
  527: If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced
  528: by the \fIsysroot prefix\fR, a path specified when the linker is configured.
  529: .Sp
  530: The default set of paths searched (without being specified with
  531: \&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in
  532: some cases also on how it was configured.  
  533: .Sp
  534: The paths can also be specified in a link script with the
  535: \&\f(CW\*(C`SEARCH_DIR\*(C'\fR command.  Directories specified this way are searched
  536: at the point in which the linker script appears in the command line.
  537: .IP "\fB\-m\fR\fIemulation\fR" 4
  538: .IX Item "-memulation"
  539: Emulate the \fIemulation\fR linker.  You can list the available
  540: emulations with the \fB\-\-verbose\fR or \fB\-V\fR options.
  541: .Sp
  542: If the \fB\-m\fR option is not used, the emulation is taken from the
  543: \&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined.
  544: .Sp
  545: Otherwise, the default emulation depends upon how the linker was
  546: configured.
  547: .IP "\fB\-M\fR" 4
  548: .IX Item "-M"
  549: .PD 0
  550: .IP "\fB\-\-print\-map\fR" 4
  551: .IX Item "--print-map"
  552: .PD
  553: Print a link map to the standard output.  A link map provides
  554: information about the link, including the following:
  555: .RS 4
  556: .IP "*" 4
  557: Where object files are mapped into memory.
  558: .IP "*" 4
  559: How common symbols are allocated.
  560: .IP "*" 4
  561: All archive members included in the link, with a mention of the symbol
  562: which caused the archive member to be brought in.
  563: .IP "*" 4
  564: The values assigned to symbols.
  565: .Sp
  566: Note \- symbols whose values are computed by an expression which
  567: involves a reference to a previous value of the same symbol may not
  568: have correct result displayed in the link map.  This is because the
  569: linker discards intermediate results and only retains the final value
  570: of an expression.  Under such circumstances the linker will display
  571: the final value enclosed by square brackets.  Thus for example a
  572: linker script containing:
  573: .Sp
  574: .Vb 3
  575: \&           foo = 1
  576: \&           foo = foo * 4
  577: \&           foo = foo + 8
  578: .Ve
  579: .Sp
  580: will produce the following output in the link map if the \fB\-M\fR
  581: option is used:
  582: .Sp
  583: .Vb 3
  584: \&           0x00000001                foo = 0x1
  585: \&           [0x0000000c]                foo = (foo * 0x4)
  586: \&           [0x0000000c]                foo = (foo + 0x8)
  587: .Ve
  588: .Sp
  589: See \fBExpressions\fR for more information about expressions in linker
  590: scripts.
  591: .RE
  592: .RS 4
  593: .RE
  594: .IP "\fB\-n\fR" 4
  595: .IX Item "-n"
  596: .PD 0
  597: .IP "\fB\-\-nmagic\fR" 4
  598: .IX Item "--nmagic"
  599: .PD
  600: Turn off page alignment of sections, and mark the output as
  601: \&\f(CW\*(C`NMAGIC\*(C'\fR if possible.
  602: .IP "\fB\-N\fR" 4
  603: .IX Item "-N"
  604: .PD 0
  605: .IP "\fB\-\-omagic\fR" 4
  606: .IX Item "--omagic"
  607: .PD
  608: Set the text and data sections to be readable and writable.  Also, do
  609: not page-align the data segment, and disable linking against shared
  610: libraries.  If the output format supports Unix style magic numbers,
  611: mark the output as \f(CW\*(C`OMAGIC\*(C'\fR. Note: Although a writable text section
  612: is allowed for PE-COFF targets, it does not conform to the format
  613: specification published by Microsoft.
  614: .IP "\fB\-\-no\-omagic\fR" 4
  615: .IX Item "--no-omagic"
  616: This option negates most of the effects of the \fB\-N\fR option.  It
  617: sets the text section to be read\-only, and forces the data segment to
  618: be page\-aligned.  Note \- this option does not enable linking against
  619: shared libraries.  Use \fB\-Bdynamic\fR for this.
  620: .IP "\fB\-o\fR \fIoutput\fR" 4
  621: .IX Item "-o output"
  622: .PD 0
  623: .IP "\fB\-\-output=\fR\fIoutput\fR" 4
  624: .IX Item "--output=output"
  625: .PD
  626: Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this
  627: option is not specified, the name \fIa.out\fR is used by default.  The
  628: script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name.
  629: .IP "\fB\-O\fR \fIlevel\fR" 4
  630: .IX Item "-O level"
  631: If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes
  632: the output.  This might take significantly longer and therefore probably
  633: should only be enabled for the final binary.  At the moment this
  634: option only affects \s-1ELF\s0 shared library generation.  Future releases of
  635: the linker may make more use of this option.  Also currently there is
  636: no difference in the linker's behaviour for different non-zero values
  637: of this option.  Again this may change with future releases.
  638: .IP "\fB\-q\fR" 4
  639: .IX Item "-q"
  640: .PD 0
  641: .IP "\fB\-\-emit\-relocs\fR" 4
  642: .IX Item "--emit-relocs"
  643: .PD
  644: Leave relocation sections and contents in fully linked executables.
  645: Post link analysis and optimization tools may need this information in
  646: order to perform correct modifications of executables.  This results
  647: in larger executables.
  648: .Sp
  649: This option is currently only supported on \s-1ELF\s0 platforms.
  650: .IP "\fB\-\-force\-dynamic\fR" 4
  651: .IX Item "--force-dynamic"
  652: Force the output file to have dynamic sections.  This option is specific
  653: to VxWorks targets.
  654: .IP "\fB\-r\fR" 4
  655: .IX Item "-r"
  656: .PD 0
  657: .IP "\fB\-\-relocatable\fR" 4
  658: .IX Item "--relocatable"
  659: .PD
  660: Generate relocatable output\-\-\-i.e., generate an output file that can in
  661: turn serve as input to \fBld\fR.  This is often called \fIpartial
  662: linking\fR.  As a side effect, in environments that support standard Unix
  663: magic numbers, this option also sets the output file's magic number to
  664: \&\f(CW\*(C`OMAGIC\*(C'\fR.
  665: If this option is not specified, an absolute file is produced.  When
  666: linking \*(C+ programs, this option \fIwill not\fR resolve references to
  667: constructors; to do that, use \fB\-Ur\fR.
  668: .Sp
  669: When an input file does not have the same format as the output file,
  670: partial linking is only supported if that input file does not contain any
  671: relocations.  Different output formats can have further restrictions; for
  672: example some \f(CW\*(C`a.out\*(C'\fR\-based formats do not support partial linking
  673: with input files in other formats at all.
  674: .Sp
  675: This option does the same thing as \fB\-i\fR.
  676: .IP "\fB\-R\fR \fIfilename\fR" 4
  677: .IX Item "-R filename"
  678: .PD 0
  679: .IP "\fB\-\-just\-symbols=\fR\fIfilename\fR" 4
  680: .IX Item "--just-symbols=filename"
  681: .PD
  682: Read symbol names and their addresses from \fIfilename\fR, but do not
  683: relocate it or include it in the output.  This allows your output file
  684: to refer symbolically to absolute locations of memory defined in other
  685: programs.  You may use this option more than once.
  686: .Sp
  687: For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is
  688: followed by a directory name, rather than a file name, it is treated as
  689: the \fB\-rpath\fR option.
  690: .IP "\fB\-s\fR" 4
  691: .IX Item "-s"
  692: .PD 0
  693: .IP "\fB\-\-strip\-all\fR" 4
  694: .IX Item "--strip-all"
  695: .PD
  696: Omit all symbol information from the output file.
  697: .IP "\fB\-S\fR" 4
  698: .IX Item "-S"
  699: .PD 0
  700: .IP "\fB\-\-strip\-debug\fR" 4
  701: .IX Item "--strip-debug"
  702: .PD
  703: Omit debugger symbol information (but not all symbols) from the output file.
  704: .IP "\fB\-t\fR" 4
  705: .IX Item "-t"
  706: .PD 0
  707: .IP "\fB\-\-trace\fR" 4
  708: .IX Item "--trace"
  709: .PD
  710: Print the names of the input files as \fBld\fR processes them.
  711: .IP "\fB\-T\fR \fIscriptfile\fR" 4
  712: .IX Item "-T scriptfile"
  713: .PD 0
  714: .IP "\fB\-\-script=\fR\fIscriptfile\fR" 4
  715: .IX Item "--script=scriptfile"
  716: .PD
  717: Use \fIscriptfile\fR as the linker script.  This script replaces
  718: \&\fBld\fR's default linker script (rather than adding to it), so
  719: \&\fIcommandfile\fR must specify everything necessary to describe the
  720: output file.    If \fIscriptfile\fR does not exist in
  721: the current directory, \f(CW\*(C`ld\*(C'\fR looks for it in the directories
  722: specified by any preceding \fB\-L\fR options.  Multiple \fB\-T\fR
  723: options accumulate.
  724: .IP "\fB\-dT\fR \fIscriptfile\fR" 4
  725: .IX Item "-dT scriptfile"
  726: .PD 0
  727: .IP "\fB\-\-default\-script=\fR\fIscriptfile\fR" 4
  728: .IX Item "--default-script=scriptfile"
  729: .PD
  730: Use \fIscriptfile\fR as the default linker script.  
  731: .Sp
  732: This option is similar to the \fB\-\-script\fR option except that
  733: processing of the script is delayed until after the rest of the
  734: command line has been processed.  This allows options placed after the
  735: \&\fB\-\-default\-script\fR option on the command line to affect the
  736: behaviour of the linker script, which can be important when the linker
  737: command line cannot be directly controlled by the user.  (eg because
  738: the command line is being constructed by another tool, such as
  739: \&\fBgcc\fR).
  740: .IP "\fB\-u\fR \fIsymbol\fR" 4
  741: .IX Item "-u symbol"
  742: .PD 0
  743: .IP "\fB\-\-undefined=\fR\fIsymbol\fR" 4
  744: .IX Item "--undefined=symbol"
  745: .PD
  746: Force \fIsymbol\fR to be entered in the output file as an undefined
  747: symbol.  Doing this may, for example, trigger linking of additional
  748: modules from standard libraries.  \fB\-u\fR may be repeated with
  749: different option arguments to enter additional undefined symbols.  This
  750: option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command.
  751: .IP "\fB\-Ur\fR" 4
  752: .IX Item "-Ur"
  753: For anything other than \*(C+ programs, this option is equivalent to
  754: \&\fB\-r\fR: it generates relocatable output\-\-\-i.e., an output file that can in
  755: turn serve as input to \fBld\fR.  When linking \*(C+ programs, \fB\-Ur\fR
  756: \&\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR.
  757: It does not work to use \fB\-Ur\fR on files that were themselves linked
  758: with \fB\-Ur\fR; once the constructor table has been built, it cannot
  759: be added to.  Use \fB\-Ur\fR only for the last partial link, and
  760: \&\fB\-r\fR for the others.
  761: .IP "\fB\-\-unique[=\fR\fI\s-1SECTION\s0\fR\fB]\fR" 4
  762: .IX Item "--unique[=SECTION]"
  763: Creates a separate output section for every input section matching
  764: \&\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\fR argument is
  765: missing, for every orphan input section.  An orphan section is one not
  766: specifically mentioned in a linker script.  You may use this option
  767: multiple times on the command line;  It prevents the normal merging of
  768: input sections with the same name, overriding output section assignments
  769: in a linker script.
  770: .IP "\fB\-v\fR" 4
  771: .IX Item "-v"
  772: .PD 0
  773: .IP "\fB\-\-version\fR" 4
  774: .IX Item "--version"