Ignore:
Timestamp:
Sep 25, 2003, 9:27:01 PM (22 years ago)
Author:
zap
Message:

.

File:
1 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/binutils/ld/ld.1

    • Property cvs2svn:cvs-rev changed from 1.1.1.2 to 1.2
    r728 r729  
    1 .\" Automatically generated by Pod::Man v1.34, Pod::Parser v1.13
    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.  | will give a
    29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
    30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
    31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
    32 .tr \(*W-|\(bv\*(Tr
    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 "2003-06-12" "binutils-2.14" "GNU Development Tools"
    132 .SH "NAME"
    133 ld \- Using 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, or the manual
    149 ld: the \s-1GNU\s0 linker, for full details on the command language and
    150 on other aspects of the \s-1GNU\s0 linker.
    151 .PP
    152 This version of \fBld\fR uses the general purpose \s-1BFD\s0 libraries
    153 to operate on object files. This allows \fBld\fR to read, combine, and
    154 write object files in many different formats\-\-\-for example, \s-1COFF\s0 or
    155 \&\f(CW\*(C`a.out\*(C'\fR.  Different formats may be linked together to produce any
    156 available kind of object file. 
    157 .PP
    158 Aside from its flexibility, the \s-1GNU\s0 linker is more helpful than other
    159 linkers in providing diagnostic information.  Many linkers abandon
    160 execution immediately upon encountering an error; whenever possible,
    161 \&\fBld\fR continues executing, allowing you to identify other errors
    162 (or, in some cases, to get an output file in spite of the error).
    163 .PP
    164 The \s-1GNU\s0 linker \fBld\fR is meant to cover a broad range of situations,
    165 and to be as compatible as possible with other linkers.  As a result,
    166 you have many choices to control its behavior.
    167 .SH "OPTIONS"
    168 .IX Header "OPTIONS"
    169 The linker supports a plethora of command-line options, but in actual
    170 practice few of them are used in any particular context.
    171 For instance, a frequent use of \fBld\fR is to link standard Unix
    172 object files on a standard, supported Unix system.  On such a system, to
    173 link a file \f(CW\*(C`hello.o\*(C'\fR:
    174 .PP
    175 .Vb 1
    176 \&        ld -o <output> /lib/crt0.o hello.o -lc
    177 .Ve
    178 .PP
    179 This tells \fBld\fR to produce a file called \fIoutput\fR as the
    180 result of linking the file \f(CW\*(C`/lib/crt0.o\*(C'\fR with \f(CW\*(C`hello.o\*(C'\fR and
    181 the library \f(CW\*(C`libc.a\*(C'\fR, which will come from the standard search
    182 directories.  (See the discussion of the \fB\-l\fR option below.)
    183 .PP
    184 Some of the command-line options to \fBld\fR may be specified at any
    185 point in the command line.  However, options which refer to files, such
    186 as \fB\-l\fR or \fB\-T\fR, cause the file to be read at the point at
    187 which the option appears in the command line, relative to the object
    188 files and other file options.  Repeating non-file options with a
    189 different argument will either have no further effect, or override prior
    190 occurrences (those further to the left on the command line) of that
    191 option.  Options which may be meaningfully specified more than once are
    192 noted in the descriptions below.
    193 .PP
    194 Non-option arguments are object files or archives which are to be linked
    195 together.  They may follow, precede, or be mixed in with command-line
    196 options, except that an object file argument may not be placed between
    197 an option and its argument.
    198 .PP
    199 Usually the linker is invoked with at least one object file, but you can
    200 specify other forms of binary input files using \fB\-l\fR, \fB\-R\fR,
    201 and the script command language.  If \fIno\fR binary input files at all
    202 are specified, the linker does not produce any output, and issues the
    203 message \fBNo input files\fR.
    204 .PP
    205 If the linker cannot recognize the format of an object file, it will
    206 assume that it is a linker script.  A script specified in this way
    207 augments the main linker script used for the link (either the default
    208 linker script or the one specified by using \fB\-T\fR).  This feature
    209 permits the linker to link against a file which appears to be an object
    210 or an archive, but actually merely defines some symbol values, or uses
    211 \&\f(CW\*(C`INPUT\*(C'\fR or \f(CW\*(C`GROUP\*(C'\fR to load other objects.  Note that
    212 specifying a script in this way merely augments the main linker script;
    213 use the \fB\-T\fR option to replace the default linker script entirely.
    214 .PP
    215 For options whose names are a single letter,
    216 option arguments must either follow the option letter without intervening
    217 whitespace, or be given as separate arguments immediately following the
    218 option that requires them.
    219 .PP
    220 For options whose names are multiple letters, either one dash or two can
    221 precede the option name; for example, \fB\-trace\-symbol\fR and
    222 \&\fB\-\-trace\-symbol\fR are equivalent.  Note\-\-\-there is one exception to
    223 this rule.  Multiple letter options that start with a lower case 'o' can
    224 only be preceeded by two dashes.  This is to reduce confusion with the
    225 \&\fB\-o\fR option.  So for example \fB\-omagic\fR sets the output file
    226 name to \fBmagic\fR whereas \fB\-\-omagic\fR sets the \s-1NMAGIC\s0 flag on the
    227 output.
    228 .PP
    229 Arguments to multiple-letter options must either be separated from the
    230 option name by an equals sign, or be given as separate arguments
    231 immediately following the option that requires them.  For example,
    232 \&\fB\-\-trace\-symbol foo\fR and \fB\-\-trace\-symbol=foo\fR are equivalent.
    233 Unique abbreviations of the names of multiple-letter options are
    234 accepted.
    235 .PP
    236 Note\-\-\-if the linker is being invoked indirectly, via a compiler driver
    237 (e.g. \fBgcc\fR) then all the linker command line options should be
    238 prefixed by \fB\-Wl,\fR (or whatever is appropriate for the particular
    239 compiler driver) like this:
    240 .PP
    241 .Vb 1
    242 \&          gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
    243 .Ve
    244 .PP
    245 This is important, because otherwise the compiler driver program may
    246 silently drop the linker options, resulting in a bad link.
    247 .PP
    248 Here is a table of the generic command line switches accepted by the \s-1GNU\s0
    249 linker:
    250 .IP "\fB\-a\fR\fIkeyword\fR" 4
    251 .IX Item "-akeyword"
    252 This option is supported for \s-1HP/UX\s0 compatibility.  The \fIkeyword\fR
    253 argument must be one of the strings \fBarchive\fR, \fBshared\fR, or
    254 \&\fBdefault\fR.  \fB\-aarchive\fR is functionally equivalent to
    255 \&\fB\-Bstatic\fR, and the other two keywords are functionally equivalent
    256 to \fB\-Bdynamic\fR.  This option may be used any number of times.
    257 .IP "\fB\-A\fR\fIarchitecture\fR" 4
    258 .IX Item "-Aarchitecture"
    259 .PD 0
    260 .IP "\fB\-\-architecture=\fR\fIarchitecture\fR" 4
    261 .IX Item "--architecture=architecture"
    262 .PD
    263 In the current release of \fBld\fR, this option is useful only for the
    264 Intel 960 family of architectures.  In that \fBld\fR configuration, the
    265 \&\fIarchitecture\fR argument identifies the particular architecture in
    266 the 960 family, enabling some safeguards and modifying the
    267 archive-library search path. 
    268 .Sp
    269 Future releases of \fBld\fR may support similar functionality for
    270 other architecture families.
    271 .IP "\fB\-b\fR \fIinput-format\fR" 4
    272 .IX Item "-b input-format"
    273 .PD 0
    274 .IP "\fB\-\-format=\fR\fIinput-format\fR" 4
    275 .IX Item "--format=input-format"
    276 .PD
    277 \&\fBld\fR may be configured to support more than one kind of object
    278 file.  If your \fBld\fR is configured this way, you can use the
    279 \&\fB\-b\fR option to specify the binary format for input object files
    280 that follow this option on the command line.  Even when \fBld\fR is
    281 configured to support alternative object formats, you don't usually need
    282 to specify this, as \fBld\fR should be configured to expect as a
    283 default input format the most usual format on each machine.
    284 \&\fIinput-format\fR is a text string, the name of a particular format
    285 supported by the \s-1BFD\s0 libraries.  (You can list the available binary
    286 formats with \fBobjdump \-i\fR.)
    287 .Sp
    288 You may want to use this option if you are linking files with an unusual
    289 binary format.  You can also use \fB\-b\fR to switch formats explicitly (when
    290 linking object files of different formats), by including
    291 \&\fB\-b\fR \fIinput-format\fR before each group of object files in a
    292 particular format.
    293 .Sp
    294 The default format is taken from the environment variable
    295 \&\f(CW\*(C`GNUTARGET\*(C'\fR.
    296 .Sp
    297 You can also define the input format from a script, using the command
    298 \&\f(CW\*(C`TARGET\*(C'\fR;
    299 .IP "\fB\-c\fR \fIMRI-commandfile\fR" 4
    300 .IX Item "-c MRI-commandfile"
    301 .PD 0
    302 .IP "\fB\-\-mri\-script=\fR\fIMRI-commandfile\fR" 4
    303 .IX Item "--mri-script=MRI-commandfile"
    304 .PD
    305 For compatibility with linkers produced by \s-1MRI\s0, \fBld\fR accepts script
    306 files written in an alternate, restricted command language, described in
    307 the \s-1MRI\s0 Compatible Script Files section of \s-1GNU\s0 ld documentation.
    308 Introduce \s-1MRI\s0 script files with
    309 the option \fB\-c\fR; use the \fB\-T\fR option to run linker
    310 scripts written in the general-purpose \fBld\fR scripting language.
    311 If \fIMRI-cmdfile\fR does not exist, \fBld\fR looks for it in the directories
    312 specified by any \fB\-L\fR options.
    313 .IP "\fB\-d\fR" 4
    314 .IX Item "-d"
    315 .PD 0
    316 .IP "\fB\-dc\fR" 4
    317 .IX Item "-dc"
    318 .IP "\fB\-dp\fR" 4
    319 .IX Item "-dp"
    320 .PD
    321 These three options are equivalent; multiple forms are supported for
    322 compatibility with other linkers.  They assign space to common symbols
    323 even if a relocatable output file is specified (with \fB\-r\fR).  The
    324 script command \f(CW\*(C`FORCE_COMMON_ALLOCATION\*(C'\fR has the same effect.
    325 .IP "\fB\-e\fR \fIentry\fR" 4
    326 .IX Item "-e entry"
    327 .PD 0
    328 .IP "\fB\-\-entry=\fR\fIentry\fR" 4
    329 .IX Item "--entry=entry"
    330 .PD
    331 Use \fIentry\fR as the explicit symbol for beginning execution of your
    332 program, rather than the default entry point.  If there is no symbol
    333 named \fIentry\fR, the linker will try to parse \fIentry\fR as a number,
    334 and use that as the entry address (the number will be interpreted in
    335 base 10; you may use a leading \fB0x\fR for base 16, or a leading
    336 \&\fB0\fR for base 8). 
    337 .IP "\fB\-E\fR" 4
    338 .IX Item "-E"
    339 .PD 0
    340 .IP "\fB\-\-export\-dynamic\fR" 4
    341 .IX Item "--export-dynamic"
    342 .PD
    343 When creating a dynamically linked executable, add all symbols to the
    344 dynamic symbol table.  The dynamic symbol table is the set of symbols
    345 which are visible from dynamic objects at run time.
    346 .Sp
    347 If you do not use this option, the dynamic symbol table will normally
    348 contain only those symbols which are referenced by some dynamic object
    349 mentioned in the link.
    350 .Sp
    351 If you use \f(CW\*(C`dlopen\*(C'\fR to load a dynamic object which needs to refer
    352 back to the symbols defined by the program, rather than some other
    353 dynamic object, then you will probably need to use this option when
    354 linking the program itself.
    355 .Sp
    356 You can also use the version script to control what symbols should
    357 be added to the dynamic symbol table if the output format supports it.
    358 See the description of \fB\-\-version\-script\fR in \f(CW@ref\fR{\s-1VERSION\s0}.
    359 .IP "\fB\-EB\fR" 4
    360 .IX Item "-EB"
    361 Link big-endian objects.  This affects the default output format.
    362 .IP "\fB\-EL\fR" 4
    363 .IX Item "-EL"
    364 Link little-endian objects.  This affects the default output format.
    365 .IP "\fB\-f\fR" 4
    366 .IX Item "-f"
    367 .PD 0
    368 .IP "\fB\-\-auxiliary\fR \fIname\fR" 4
    369 .IX Item "--auxiliary name"
    370 .PD
    371 When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_AUXILIARY\s0 field
    372 to the specified name.  This tells the dynamic linker that the symbol
    373 table of the shared object should be used as an auxiliary filter on the
    374 symbol table of the shared object \fIname\fR.
    375 .Sp
    376 If you later link a program against this filter object, then, when you
    377 run the program, the dynamic linker will see the \s-1DT_AUXILIARY\s0 field.  If
    378 the dynamic linker resolves any symbols from the filter object, it will
    379 first check whether there is a definition in the shared object
    380 \&\fIname\fR.  If there is one, it will be used instead of the definition
    381 in the filter object.  The shared object \fIname\fR need not exist.
    382 Thus the shared object \fIname\fR may be used to provide an alternative
    383 implementation of certain functions, perhaps for debugging or for
    384 machine specific performance.
    385 .Sp
    386 This option may be specified more than once.  The \s-1DT_AUXILIARY\s0 entries
    387 will be created in the order in which they appear on the command line.
    388 .IP "\fB\-F\fR \fIname\fR" 4
    389 .IX Item "-F name"
    390 .PD 0
    391 .IP "\fB\-\-filter\fR \fIname\fR" 4
    392 .IX Item "--filter name"
    393 .PD
    394 When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_FILTER\s0 field to
    395 the specified name.  This tells the dynamic linker that the symbol table
    396 of the shared object which is being created should be used as a filter
    397 on the symbol table of the shared object \fIname\fR.
    398 .Sp
    399 If you later link a program against this filter object, then, when you
    400 run the program, the dynamic linker will see the \s-1DT_FILTER\s0 field.  The
    401 dynamic linker will resolve symbols according to the symbol table of the
    402 filter object as usual, but it will actually link to the definitions
    403 found in the shared object \fIname\fR.  Thus the filter object can be
    404 used to select a subset of the symbols provided by the object
    405 \&\fIname\fR.
    406 .Sp
    407 Some older linkers used the \fB\-F\fR option throughout a compilation
    408 toolchain for specifying object-file format for both input and output
    409 object files.
    410 The \s-1GNU\s0 linker uses other mechanisms for this purpose: the
    411 \&\fB\-b\fR, \fB\-\-format\fR, \fB\-\-oformat\fR options, the
    412 \&\f(CW\*(C`TARGET\*(C'\fR command in linker scripts, and the \f(CW\*(C`GNUTARGET\*(C'\fR
    413 environment variable.
    414 The \s-1GNU\s0 linker will ignore the \fB\-F\fR option when not
    415 creating an \s-1ELF\s0 shared object.
    416 .IP "\fB\-fini\fR \fIname\fR" 4
    417 .IX Item "-fini name"
    418 When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
    419 executable or shared object is unloaded, by setting \s-1DT_FINI\s0 to the
    420 address of the function.  By default, the linker uses \f(CW\*(C`_fini\*(C'\fR as
    421 the function to call.
    422 .IP "\fB\-g\fR" 4
    423 .IX Item "-g"
    424 Ignored.  Provided for compatibility with other tools.
    425 .IP "\fB\-G\fR\fIvalue\fR" 4
    426 .IX Item "-Gvalue"
    427 .PD 0
    428 .IP "\fB\-\-gpsize=\fR\fIvalue\fR" 4
    429 .IX Item "--gpsize=value"
    430 .PD
    431 Set the maximum size of objects to be optimized using the \s-1GP\s0 register to
    432 \&\fIsize\fR.  This is only meaningful for object file formats such as
    433 \&\s-1MIPS\s0 \s-1ECOFF\s0 which supports putting large and small objects into different
    434 sections.  This is ignored for other object file formats.
    435 .IP "\fB\-h\fR\fIname\fR" 4
    436 .IX Item "-hname"
    437 .PD 0
    438 .IP "\fB\-soname=\fR\fIname\fR" 4
    439 .IX Item "-soname=name"
    440 .PD
    441 When creating an \s-1ELF\s0 shared object, set the internal \s-1DT_SONAME\s0 field to
    442 the specified name.  When an executable is linked with a shared object
    443 which has a \s-1DT_SONAME\s0 field, then when the executable is run the dynamic
    444 linker will attempt to load the shared object specified by the \s-1DT_SONAME\s0
    445 field rather than the using the file name given to the linker.
    446 .IP "\fB\-i\fR" 4
    447 .IX Item "-i"
    448 Perform an incremental link (same as option \fB\-r\fR).
    449 .IP "\fB\-init\fR \fIname\fR" 4
    450 .IX Item "-init name"
    451 When creating an \s-1ELF\s0 executable or shared object, call \s-1NAME\s0 when the
    452 executable or shared object is loaded, by setting \s-1DT_INIT\s0 to the address
    453 of the function.  By default, the linker uses \f(CW\*(C`_init\*(C'\fR as the
    454 function to call.
    455 .IP "\fB\-l\fR\fIarchive\fR" 4
    456 .IX Item "-larchive"
    457 .PD 0
    458 .IP "\fB\-\-library=\fR\fIarchive\fR" 4
    459 .IX Item "--library=archive"
    460 .PD
    461 Add archive file \fIarchive\fR to the list of files to link.  This
    462 option may be used any number of times.  \fBld\fR will search its
    463 path-list for occurrences of \f(CW\*(C`lib\f(CIarchive\f(CW.a\*(C'\fR for every
    464 \&\fIarchive\fR specified.
    465 .Sp
    466 On systems which support shared libraries, \fBld\fR may also search for
    467 libraries with extensions other than \f(CW\*(C`.a\*(C'\fR.  Specifically, on \s-1ELF\s0
    468 and SunOS systems, \fBld\fR will search a directory for a library with
    469 an extension of \f(CW\*(C`.so\*(C'\fR before searching for one with an extension of
    470 \&\f(CW\*(C`.a\*(C'\fR.  By convention, a \f(CW\*(C`.so\*(C'\fR extension indicates a shared
    471 library.
    472 .Sp
    473 The linker will search an archive only once, at the location where it is
    474 specified on the command line.  If the archive defines a symbol which
    475 was undefined in some object which appeared before the archive on the
    476 command line, the linker will include the appropriate file(s) from the
    477 archive.  However, an undefined symbol in an object appearing later on
    478 the command line will not cause the linker to search the archive again.
    479 .Sp
    480 See the \fB\-(\fR option for a way to force the linker to search
    481 archives multiple times.
    482 .Sp
    483 You may list the same archive multiple times on the command line.
    484 .Sp
    485 This type of archive searching is standard for Unix linkers.  However,
    486 if you are using \fBld\fR on \s-1AIX\s0, note that it is different from the
    487 behaviour of the \s-1AIX\s0 linker.
    488 .IP "\fB\-L\fR\fIsearchdir\fR" 4
    489 .IX Item "-Lsearchdir"
    490 .PD 0
    491 .IP "\fB\-\-library\-path=\fR\fIsearchdir\fR" 4
    492 .IX Item "--library-path=searchdir"
    493 .PD
    494 Add path \fIsearchdir\fR to the list of paths that \fBld\fR will search
    495 for archive libraries and \fBld\fR control scripts.  You may use this
    496 option any number of times.  The directories are searched in the order
    497 in which they are specified on the command line.  Directories specified
    498 on the command line are searched before the default directories.  All
    499 \&\fB\-L\fR options apply to all \fB\-l\fR options, regardless of the
    500 order in which the options appear.
    501 .Sp
    502 If \fIsearchdir\fR begins with \f(CW\*(C`=\*(C'\fR, then the \f(CW\*(C`=\*(C'\fR will be replaced
    503 by the \fIsysroot prefix\fR, a path specified when the linker is configured.
    504 .Sp
    505 The default set of paths searched (without being specified with
    506 \&\fB\-L\fR) depends on which emulation mode \fBld\fR is using, and in
    507 some cases also on how it was configured. 
    508 .Sp
    509 The paths can also be specified in a link script with the
    510 \&\f(CW\*(C`SEARCH_DIR\*(C'\fR command.  Directories specified this way are searched
    511 at the point in which the linker script appears in the command line.
    512 .IP "\fB\-m\fR\fIemulation\fR" 4
    513 .IX Item "-memulation"
    514 Emulate the \fIemulation\fR linker.  You can list the available
    515 emulations with the \fB\-\-verbose\fR or \fB\-V\fR options.
    516 .Sp
    517 If the \fB\-m\fR option is not used, the emulation is taken from the
    518 \&\f(CW\*(C`LDEMULATION\*(C'\fR environment variable, if that is defined.
    519 .Sp
    520 Otherwise, the default emulation depends upon how the linker was
    521 configured.
    522 .IP "\fB\-M\fR" 4
    523 .IX Item "-M"
    524 .PD 0
    525 .IP "\fB\-\-print\-map\fR" 4
    526 .IX Item "--print-map"
    527 .PD
    528 Print a link map to the standard output.  A link map provides
    529 information about the link, including the following:
    530 .RS 4
    531 .IP "\(bu" 4
    532 Where object files and symbols are mapped into memory.
    533 .IP "\(bu" 4
    534 How common symbols are allocated.
    535 .IP "\(bu" 4
    536 All archive members included in the link, with a mention of the symbol
    537 which caused the archive member to be brought in.
    538 .RE
    539 .RS 4
    540 .RE
    541 .IP "\fB\-n\fR" 4
    542 .IX Item "-n"
    543 .PD 0
    544 .IP "\fB\-\-nmagic\fR" 4
    545 .IX Item "--nmagic"
    546 .PD
    547 Turn off page alignment of sections, and mark the output as
    548 \&\f(CW\*(C`NMAGIC\*(C'\fR if possible.
    549 .IP "\fB\-N\fR" 4
    550 .IX Item "-N"
    551 .PD 0
    552 .IP "\fB\-\-omagic\fR" 4
    553 .IX Item "--omagic"
    554 .PD
    555 Set the text and data sections to be readable and writable.  Also, do
    556 not page-align the data segment, and disable linking against shared
    557 libraries.  If the output format supports Unix style magic numbers,
    558 mark the output as \f(CW\*(C`OMAGIC\*(C'\fR.
    559 .IP "\fB\-\-no\-omagic\fR" 4
    560 .IX Item "--no-omagic"
    561 This option negates most of the effects of the \fB\-N\fR option.  It
    562 sets the text section to be read\-only, and forces the data segment to
    563 be page\-aligned.  Note \- this option does not enable linking against
    564 shared libraries.  Use \fB\-Bdynamic\fR for this.
    565 .IP "\fB\-o\fR \fIoutput\fR" 4
    566 .IX Item "-o output"
    567 .PD 0
    568 .IP "\fB\-\-output=\fR\fIoutput\fR" 4
    569 .IX Item "--output=output"
    570 .PD
    571 Use \fIoutput\fR as the name for the program produced by \fBld\fR; if this
    572 option is not specified, the name \fIa.out\fR is used by default.  The
    573 script command \f(CW\*(C`OUTPUT\*(C'\fR can also specify the output file name.
    574 .IP "\fB\-O\fR \fIlevel\fR" 4
    575 .IX Item "-O level"
    576 If \fIlevel\fR is a numeric values greater than zero \fBld\fR optimizes
    577 the output.  This might take significantly longer and therefore probably
    578 should only be enabled for the final binary.
    579 .IP "\fB\-q\fR" 4
    580 .IX Item "-q"
    581 .PD 0
    582 .IP "\fB\-\-emit\-relocs\fR" 4
    583 .IX Item "--emit-relocs"
    584 .PD
    585 Leave relocation sections and contents in fully linked exececutables.
    586 Post link analysis and optimization tools may need this information in
    587 order to perform correct modifications of executables.  This results
    588 in larger executables.
    589 .Sp
    590 This option is currently only supported on \s-1ELF\s0 platforms.
    591 .IP "\fB\-r\fR" 4
    592 .IX Item "-r"
    593 .PD 0
    594 .IP "\fB\-\-relocateable\fR" 4
    595 .IX Item "--relocateable"
    596 .PD
    597 Generate relocatable output\-\-\-i.e., generate an output file that can in
    598 turn serve as input to \fBld\fR.  This is often called \fIpartial
    599 linking\fR.  As a side effect, in environments that support standard Unix
    600 magic numbers, this option also sets the output file's magic number to
    601 \&\f(CW\*(C`OMAGIC\*(C'\fR.
    602 If this option is not specified, an absolute file is produced.  When
    603 linking \*(C+ programs, this option \fIwill not\fR resolve references to
    604 constructors; to do that, use \fB\-Ur\fR.
    605 .Sp
    606 When an input file does not have the same format as the output file,
    607 partial linking is only supported if that input file does not contain any
    608 relocations.  Different output formats can have further restrictions; for
    609 example some \f(CW\*(C`a.out\*(C'\fR\-based formats do not support partial linking
    610 with input files in other formats at all.
    611 .Sp
    612 This option does the same thing as \fB\-i\fR.
    613 .IP "\fB\-R\fR \fIfilename\fR" 4
    614 .IX Item "-R filename"
    615 .PD 0
    616 .IP "\fB\-\-just\-symbols=\fR\fIfilename\fR" 4
    617 .IX Item "--just-symbols=filename"
    618 .PD
    619 Read symbol names and their addresses from \fIfilename\fR, but do not
    620 relocate it or include it in the output.  This allows your output file
    621 to refer symbolically to absolute locations of memory defined in other
    622 programs.  You may use this option more than once.
    623 .Sp
    624 For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is
    625 followed by a directory name, rather than a file name, it is treated as
    626 the \fB\-rpath\fR option.
    627 .IP "\fB\-s\fR" 4
    628 .IX Item "-s"
    629 .PD 0
    630 .IP "\fB\-\-strip\-all\fR" 4
    631 .IX Item "--strip-all"
    632 .PD
    633 Omit all symbol information from the output file.
    634 .IP "\fB\-S\fR" 4
    635 .IX Item "-S"
    636 .PD 0
    637 .IP "\fB\-\-strip\-debug\fR" 4
    638 .IX Item "--strip-debug"
    639 .PD
    640 Omit debugger symbol information (but not all symbols) from the output file.
    641 .IP "\fB\-t\fR" 4
    642 .IX Item "-t"
    643 .PD 0
    644 .IP "\fB\-\-trace\fR" 4
    645 .IX Item "--trace"
    646 .PD
    647 Print the names of the input files as \fBld\fR processes them.
    648 .IP "\fB\-T\fR \fIscriptfile\fR" 4
    649 .IX Item "-T scriptfile"
    650 .PD 0
    651 .IP "\fB\-\-script=\fR\fIscriptfile\fR" 4
    652 .IX Item "--script=scriptfile"
    653 .PD
    654 Use \fIscriptfile\fR as the linker script.  This script replaces
    655 \&\fBld\fR's default linker script (rather than adding to it), so
    656 \&\fIcommandfile\fR must specify everything necessary to describe the
    657 output file.    If \fIscriptfile\fR does not exist in
    658 the current directory, \f(CW\*(C`ld\*(C'\fR looks for it in the directories
    659 specified by any preceding \fB\-L\fR options.  Multiple \fB\-T\fR
    660 options accumulate.
    661 .IP "\fB\-u\fR \fIsymbol\fR" 4
    662 .IX Item "-u symbol"
    663 .PD 0
    664 .IP "\fB\-\-undefined=\fR\fIsymbol\fR" 4
    665 .IX Item "--undefined=symbol"
    666 .PD
    667 Force \fIsymbol\fR to be entered in the output file as an undefined
    668 symbol.  Doing this may, for example, trigger linking of additional
    669 modules from standard libraries.  \fB\-u\fR may be repeated with
    670 different option arguments to enter additional undefined symbols.  This
    671 option is equivalent to the \f(CW\*(C`EXTERN\*(C'\fR linker script command.
    672 .IP "\fB\-Ur\fR" 4
    673 .IX Item "-Ur"
    674 For anything other than \*(C+ programs, this option is equivalent to
    675 \&\fB\-r\fR: it generates relocatable output\-\-\-i.e., an output file that can in
    676 turn serve as input to \fBld\fR.  When linking \*(C+ programs, \fB\-Ur\fR
    677 \&\fIdoes\fR resolve references to constructors, unlike \fB\-r\fR.
    678 It does not work to use \fB\-Ur\fR on files that were themselves linked
    679 with \fB\-Ur\fR; once the constructor table has been built, it cannot
    680 be added to.  Use \fB\-Ur\fR only for the last partial link, and
    681 \&\fB\-r\fR for the others.
    682 .IP "\fB\-\-unique[=\fR\fI\s-1SECTION\s0\fR\fB]\fR" 4
    683 .IX Item "--unique[=SECTION]"
    684 Creates a separate output section for every input section matching
    685 \&\fI\s-1SECTION\s0\fR, or if the optional wildcard \fI\s-1SECTION\s0\fR argument is
    686 missing, for every orphan input section.  An orphan section is one not
    687 specifically mentioned in a linker script.  You may use this option
    688 multiple times on the command line;  It prevents the normal merging of
    689 input sections with the same name, overriding output section assignments
    690 in a linker script.
    691 .IP "\fB\-v\fR" 4
    692 .IX Item "-v"
    693 .PD 0
    694 .IP "\fB\-\-version\fR" 4
    695 .IX Item "--version"
    696 .IP "\fB\-V\fR" 4
    697 .IX Item "-V"
    698 .PD
    699 Display the version number for \fBld\fR.  The \fB\-V\fR option also
    700 lists the supported emulations.
    701 .IP "\fB\-x\fR" 4
    702 .IX Item "-x"
    703 .PD 0
    704 .IP "\fB\-\-discard\-all\fR" 4
    705 .IX Item "--discard-all"
    706 .PD
    707 Delete all local symbols.
    708 .IP "\fB\-X\fR" 4
    709 .IX Item "-X"
    710 .PD 0
    711 .IP "\fB\-\-discard\-locals\fR" 4
    712 .IX Item "--discard-locals"
    713 .PD
    714 Delete all temporary local symbols.  For most targets, this is all local
    715 symbols whose names begin with \fBL\fR.
    716 .IP "\fB\-y\fR \fIsymbol\fR" 4
    717 .IX Item "-y symbol"
    718 .PD 0
    719 .IP "\fB\-\-trace\-symbol=\fR\fIsymbol\fR" 4
    720 .IX Item "--trace-symbol=symbol"
    721 .PD
    722 Print the name of each linked file in which \fIsymbol\fR appears.  This
    723 option may be given any number of times.  On many systems it is necessary
    724 to prepend an underscore.
    725 .Sp
    726 This option is useful when you have an undefined symbol in your link but
    727 don't know where the reference is coming from.
    728 .IP "\fB\-Y\fR \fIpath\fR" 4
    729 .IX Item "-Y path"
    730 Add \fIpath\fR to the default library search path.  This option exists
    731 for Solaris compatibility.
    732 .IP "\fB\-z\fR \fIkeyword\fR" 4
    733 .IX Item "-z keyword"
    734 The recognized keywords are \f(CW\*(C`initfirst\*(C'\fR, \f(CW\*(C`interpose\*(C'\fR,
    735 \&\f(CW\*(C`loadfltr\*(C'\fR, \f(CW\*(C`nodefaultlib\*(C'\fR, \f(CW\*(C`nodelete\*(C'\fR, \f(CW\*(C`nodlopen\*(C'\fR,
    736 \&\f(CW\*(C`nodump\*(C'\fR, \f(CW\*(C`now\*(C'\fR, \f(CW\*(C`origin\*(C'\fR, \f(CW\*(C`combreloc\*(C'\fR, \f(CW\*(C`nocombreloc\*(C'\fR
    737 and \f(CW\*(C`nocopyreloc\*(C'\fR.
    738 The other keywords are
    739 ignored for Solaris compatibility. \f(CW\*(C`initfirst\*(C'\fR marks the object
    740 to be initialized first at runtime before any other objects.
    741 \&\f(CW\*(C`interpose\*(C'\fR marks the object that its symbol table interposes
    742 before all symbols but the primary executable. \f(CW\*(C`loadfltr\*(C'\fR marks
    743 the object that its filtees be processed immediately at runtime.
    744 \&\f(CW\*(C`nodefaultlib\*(C'\fR marks the object that the search for dependencies
    745 of this object will ignore any default library search paths.
    746 \&\f(CW\*(C`nodelete\*(C'\fR marks the object shouldn't be unloaded at runtime.
    747 \&\f(CW\*(C`nodlopen\*(C'\fR marks the object not available to \f(CW\*(C`dlopen\*(C'\fR.
    748 \&\f(CW\*(C`nodump\*(C'\fR marks the object can not be dumped by \f(CW\*(C`dldump\*(C'\fR.
    749 \&\f(CW\*(C`now\*(C'\fR marks the object with the non-lazy runtime binding.
    750 \&\f(CW\*(C`origin\*(C'\fR marks the object may contain \f(CW$ORIGIN\fR.
    751 \&\f(CW\*(C`defs\*(C'\fR disallows undefined symbols.
    752 \&\f(CW\*(C`muldefs\*(C'\fR allows multiple definitions.
    753 \&\f(CW\*(C`combreloc\*(C'\fR combines multiple reloc sections and sorts them
    754 to make dynamic symbol lookup caching possible.
    755 \&\f(CW\*(C`nocombreloc\*(C'\fR disables multiple reloc sections combining.
    756 \&\f(CW\*(C`nocopyreloc\*(C'\fR disables production of copy relocs.
    757 .IP "\fB\-(\fR \fIarchives\fR \fB\-)\fR" 4
    758 .IX Item "-( archives -)"
    759 .PD 0
    760 .IP "\fB\-\-start\-group\fR \fIarchives\fR \fB\-\-end\-group\fR" 4
    761 .IX Item "--start-group archives --end-group"
    762 .PD
    763 The \fIarchives\fR should be a list of archive files.  They may be
    764 either explicit file names, or \fB\-l\fR options.
    765 .Sp
    766 The specified archives are searched repeatedly until no new undefined
    767 references are created.  Normally, an archive is searched only once in
    768 the order that it is specified on the command line.  If a symbol in that
    769 archive is needed to resolve an undefined symbol referred to by an
    770 object in an archive that appears later on the command line, the linker
    771 would not be able to resolve that reference.  By grouping the archives,
    772 they all be searched repeatedly until all possible references are
    773 resolved.
    774 .Sp
    775 Using this option has a significant performance cost.  It is best to use
    776 it only when there are unavoidable circular references between two or
    777 more archives.
    778 .IP "\fB\-\-accept\-unknown\-input\-arch\fR" 4
    779 .IX Item "--accept-unknown-input-arch"
    780 .PD 0
    781 .IP "\fB\-\-no\-accept\-unknown\-input\-arch\fR" 4
    782 .IX Item "--no-accept-unknown-input-arch"
    783 .PD
    784 Tells the linker to accept input files whose architecture cannot be
    785 recognised.  The assumption is that the user knows what they are doing
    786 and deliberately wants to link in these unknown input files.  This was
    787 the default behaviour of the linker, before release 2.14.  The default
    788 behaviour from release 2.14 onwards is to reject such input files, and
    789 so the \fB\-\-accept\-unknown\-input\-arch\fR option has been added to
    790 restore the old behaviour.
    791 .IP "\fB\-assert\fR \fIkeyword\fR" 4
    792 .IX Item "-assert keyword"
    793 This option is ignored for SunOS compatibility.
    794 .IP "\fB\-Bdynamic\fR" 4
    795 .IX Item "-Bdynamic"
    796 .PD 0
    797 .IP "\fB\-dy\fR" 4
    798 .IX Item "-dy"
    799 .IP "\fB\-call_shared\fR" 4
    800 .IX Item "-call_shared"
    801 .PD
    802 Link against dynamic libraries.  This is only meaningful on platforms
    803 for which shared libraries are supported.  This option is normally the
    804 default on such platforms.  The different variants of this option are
    805 for compatibility with various systems.  You may use this option
    806 multiple times on the command line: it affects library searching for
    807 \&\fB\-l\fR options which follow it.
    808 .IP "\fB\-Bgroup\fR" 4
    809 .IX Item "-Bgroup"
    810 Set the \f(CW\*(C`DF_1_GROUP\*(C'\fR flag in the \f(CW\*(C`DT_FLAGS_1\*(C'\fR entry in the dynamic
    811 section.  This causes the runtime linker to handle lookups in this
    812 object and its dependencies to be performed only inside the group.
    813 \&\fB\-\-no\-undefined\fR is implied.  This option is only meaningful on \s-1ELF\s0
    814 platforms which support shared libraries.
    815 .IP "\fB\-Bstatic\fR" 4
    816 .IX Item "-Bstatic"
    817 .PD 0
    818 .IP "\fB\-dn\fR" 4
    819 .IX Item "-dn"
    820 .IP "\fB\-non_shared\fR" 4
    821 .IX Item "-non_shared"
    822 .IP "\fB\-static\fR" 4
    823 .IX Item "-static"
    824 .PD
    825 Do not link against shared libraries.  This is only meaningful on
    826 platforms for which shared libraries are supported.  The different
    827 variants of this option are for compatibility with various systems.  You
    828 may use this option multiple times on the command line: it affects
    829 library searching for \fB\-l\fR options which follow it.
    830 .IP "\fB\-Bsymbolic\fR" 4
    831 .IX Item "-Bsymbolic"
    832 When creating a shared library, bind references to global symbols to the
    833 definition within the shared library, if any.  Normally, it is possible
    834 for a program linked against a shared library to override the definition
    835 within the shared library.  This option is only meaningful on \s-1ELF\s0
    836 platforms which support shared libraries.
    837 .IP "\fB\-\-check\-sections\fR" 4
    838 .IX Item "--check-sections"
    839 .PD 0
    840 .IP "\fB\-\-no\-check\-sections\fR" 4
    841 .IX Item "--no-check-sections"
    842 .PD
    843 Asks the linker \fInot\fR to check section addresses after they have
    844 been assigned to see if there any overlaps.  Normally the linker will
    845 perform this check, and if it finds any overlaps it will produce
    846 suitable error messages.  The linker does know about, and does make
    847 allowances for sections in overlays.  The default behaviour can be
    848 restored by using the command line switch \fB\-\-check\-sections\fR.
    849 .IP "\fB\-\-cref\fR" 4
    850 .IX Item "--cref"
    851 Output a cross reference table.  If a linker map file is being
    852 generated, the cross reference table is printed to the map file.
    853 Otherwise, it is printed on the standard output.
    854 .Sp
    855 The format of the table is intentionally simple, so that it may be
    856 easily processed by a script if necessary.  The symbols are printed out,
    857 sorted by name.  For each symbol, a list of file names is given.  If the
    858 symbol is defined, the first file listed is the location of the
    859 definition.  The remaining files contain references to the symbol.
    860 .IP "\fB\-\-no\-define\-common\fR" 4
    861 .IX Item "--no-define-common"
    862 This option inhibits the assignment of addresses to common symbols.
    863 The script command \f(CW\*(C`INHIBIT_COMMON_ALLOCATION\*(C'\fR has the same effect.
    864 .Sp
    865 The \fB\-\-no\-define\-common\fR option allows decoupling
    866 the decision to assign addresses to Common symbols from the choice
    867 of the output file type; otherwise a non-Relocatable output type
    868 forces assigning addresses to Common symbols.
    869 Using \fB\-\-no\-define\-common\fR allows Common symbols that are referenced
    870 from a shared library to be assigned addresses only in the main program.
    871 This eliminates the unused duplicate space in the shared library,
    872 and also prevents any possible confusion over resolving to the wrong
    873 duplicate when there are many dynamic modules with specialized search
    874 paths for runtime symbol resolution.
    875 .IP "\fB\-\-defsym\fR \fIsymbol\fR\fB=\fR\fIexpression\fR" 4
    876 .IX Item "--defsym symbol=expression"
    877 Create a global symbol in the output file, containing the absolute
    878 address given by \fIexpression\fR.  You may use this option as many
    879 times as necessary to define multiple symbols in the command line.  A
    880 limited form of arithmetic is supported for the \fIexpression\fR in this
    881 context: you may give a hexadecimal constant or the name of an existing
    882 symbol, or use \f(CW\*(C`+\*(C'\fR and \f(CW\*(C`\-\*(C'\fR to add or subtract hexadecimal
    883 constants or symbols.  If you need more elaborate expressions, consider
    884 using the linker command language from a script.  \fINote:\fR there should be no white
    885 space between \fIsymbol\fR, the equals sign (``\fB=\fR''), and
    886 \&\fIexpression\fR.
    887 .IP "\fB\-\-demangle[=\fR\fIstyle\fR\fB]\fR" 4
    888 .IX Item "--demangle[=style]"
    889 .PD 0
    890 .IP "\fB\-\-no\-demangle\fR" 4
    891 .IX Item "--no-demangle"
    892 .PD
    893 These options control whether to demangle symbol names in error messages
    894 and other output.  When the linker is told to demangle, it tries to
    895 present symbol names in a readable fashion: it strips leading
    896 underscores if they are used by the object file format, and converts \*(C+
    897 mangled symbol names into user readable names.  Different compilers have
    898 different mangling styles.  The optional demangling style argument can be used
    899 to choose an appropriate demangling style for your compiler.  The linker will
    900 demangle by default unless the environment variable \fB\s-1COLLECT_NO_DEMANGLE\s0\fR
    901 is set.  These options may be used to override the default.
    902 .IP "\fB\-\-dynamic\-linker\fR \fIfile\fR" 4
    903 .IX Item "--dynamic-linker file"
    904 Set the name of the dynamic linker.  This is only meaningful when
    905 generating dynamically linked \s-1ELF\s0 executables.  The default dynamic
    906 linker is normally correct; don't use this unless you know what you are
    907 doing.
    908 .IP "\fB\-\-embedded\-relocs\fR" 4
    909 .IX Item "--embedded-relocs"
    910 This option is only meaningful when linking \s-1MIPS\s0 embedded \s-1PIC\s0 code,
    911 generated by the \-membedded\-pic option to the \s-1GNU\s0 compiler and
    912 assembler.  It causes the linker to create a table which may be used at
    913 runtime to relocate any data which was statically initialized to pointer
    914 values.  See the code in testsuite/ld\-empic for details.
    915 .IP "\fB\-\-fatal\-warnings\fR" 4
    916 .IX Item "--fatal-warnings"
    917 Treat all warnings as errors.
    918 .IP "\fB\-\-force\-exe\-suffix\fR" 4
    919 .IX Item "--force-exe-suffix"
    920 Make sure that an output file has a .exe suffix.
    921 .Sp
    922 If a successfully built fully linked output file does not have a
    923 \&\f(CW\*(C`.exe\*(C'\fR or \f(CW\*(C`.dll\*(C'\fR suffix, this option forces the linker to copy
    924 the output file to one of the same name with a \f(CW\*(C`.exe\*(C'\fR suffix. This
    925 option is useful when using unmodified Unix makefiles on a Microsoft
    926 Windows host, since some versions of Windows won't run an image unless
    927 it ends in a \f(CW\*(C`.exe\*(C'\fR suffix.
    928 .IP "\fB\-\-no\-gc\-sections\fR" 4
    929 .IX Item "--no-gc-sections"
    930 .PD 0
    931 .IP "\fB\-\-gc\-sections\fR" 4
    932 .IX Item "--gc-sections"
    933 .PD
    934 Enable garbage collection of unused input sections.  It is ignored on
    935 targets that do not support this option.  This option is not compatible
    936 with \fB\-r\fR, nor should it be used with dynamic linking.  The default
    937 behaviour (of not performing this garbage collection) can be restored by
    938 specifying \fB\-\-no\-gc\-sections\fR on the command line.
    939 .IP "\fB\-\-help\fR" 4
    940 .IX Item "--help"
    941 Print a summary of the command-line options on the standard output and exit.
    942 .IP "\fB\-\-target\-help\fR" 4
    943 .IX Item "--target-help"
    944 Print a summary of all target specific options on the standard output and exit.
    945 .IP "\fB\-Map\fR \fImapfile\fR" 4
    946 .IX Item "-Map mapfile"
    947 Print a link map to the file \fImapfile\fR.  See the description of the
    948 \&\fB\-M\fR option, above.
    949 .IP "\fB\-\-no\-keep\-memory\fR" 4
    950 .IX Item "--no-keep-memory"
    951 \&\fBld\fR normally optimizes for speed over memory usage by caching the
    952 symbol tables of input files in memory.  This option tells \fBld\fR to
    953 instead optimize for memory usage, by rereading the symbol tables as
    954 necessary.  This may be required if \fBld\fR runs out of memory space
    955 while linking a large executable.
    956 .IP "\fB\-\-no\-undefined\fR" 4
    957 .IX Item "--no-undefined"
    958 .PD 0
    959 .IP "\fB\-z defs\fR" 4
    960 .IX Item "-z defs"
    961 .PD
    962 Normally when creating a non-symbolic shared library, undefined symbols
    963 are allowed and left to be resolved by the runtime loader.  This option
    964 disallows such undefined symbols if they come from regular object
    965 files.  The switch \fB\-\-no\-allow\-shlib\-undefined\fR controls the
    966 behaviour for shared objects being linked into the shared library.
    967 .IP "\fB\-\-allow\-multiple\-definition\fR" 4
    968 .IX Item "--allow-multiple-definition"
    969 .PD 0
    970 .IP "\fB\-z muldefs\fR" 4
    971 .IX Item "-z muldefs"
    972 .PD
    973 Normally when a symbol is defined multiple times, the linker will
    974 report a fatal error. These options allow multiple definitions and the
    975 first definition will be used.
    976 .IP "\fB\-\-allow\-shlib\-undefined\fR" 4
    977 .IX Item "--allow-shlib-undefined"
    978 .PD 0
    979 .IP "\fB\-\-no\-allow\-shlib\-undefined\fR" 4
    980 .IX Item "--no-allow-shlib-undefined"
    981 .PD
    982 Allow (the default) or disallow undefined symbols in shared objects.
    983 The setting of this switch overrides \fB\-\-no\-undefined\fR where
    984 shared objects are concerned.  Thus if \fB\-\-no\-undefined\fR is set
    985 but \fB\-\-no\-allow\-shlib\-undefined\fR is not, the net result will be
    986 that undefined symbols in regular object files will trigger an error,
    987 but undefined symbols in shared objects will be ignored.
    988 .Sp
    989 The reason that \fB\-\-allow\-shlib\-undefined\fR is the default is that
    990 the shared object being specified at link time may not be the same one
    991 that is available at load time, so the symbols might actually be
    992 resolvable at load time.  Plus there are some systems, (eg BeOS) where
    993 undefined symbols in shared libraries is normal since the kernel
    994 patches them at load time to select which function is most appropriate
    995 for the current architecture. eg. to dynamically select an appropriate
    996 memset function.  Apparently it is also normal for \s-1HPPA\s0 shared
    997 libraries to have undefined symbols.
    998 .IP "\fB\-\-no\-undefined\-version\fR" 4
    999 .IX Item "--no-undefined-version"
    1000 Normally when a symbol has an undefined version, the linker will ignore
    1001 it. This option disallows symbols with undefined version and a fatal error
    1002 will be issued instead.
    1003 .IP "\fB\-\-no\-warn\-mismatch\fR" 4
    1004 .IX Item "--no-warn-mismatch"
    1005 Normally \fBld\fR will give an error if you try to link together input
    1006 files that are mismatched for some reason, perhaps because they have
    1007 been compiled for different processors or for different endiannesses.
    1008 This option tells \fBld\fR that it should silently permit such possible
    1009 errors.  This option should only be used with care, in cases when you
    1010 have taken some special action that ensures that the linker errors are
    1011 inappropriate.
    1012 .IP "\fB\-\-no\-whole\-archive\fR" 4
    1013 .IX Item "--no-whole-archive"
    1014 Turn off the effect of the \fB\-\-whole\-archive\fR option for subsequent
    1015 archive files.
    1016 .IP "\fB\-\-noinhibit\-exec\fR" 4
    1017 .IX Item "--noinhibit-exec"
    1018 Retain the executable output file whenever it is still usable.
    1019 Normally, the linker will not produce an output file if it encounters
    1020 errors during the link process; it exits without writing an output file
    1021 when it issues any error whatsoever.
    1022 .IP "\fB\-nostdlib\fR" 4
    1023 .IX Item "-nostdlib"
    1024 Only search library directories explicitly specified on the
    1025 command line.  Library directories specified in linker scripts
    1026 (including linker scripts specified on the command line) are ignored.
    1027 .IP "\fB\-\-oformat\fR \fIoutput-format\fR" 4
    1028 .IX Item "--oformat output-format"
    1029 \&\fBld\fR may be configured to support more than one kind of object
    1030 file.  If your \fBld\fR is configured this way, you can use the
    1031 \&\fB\-\-oformat\fR option to specify the binary format for the output
    1032 object file.  Even when \fBld\fR is configured to support alternative
    1033 object formats, you don't usually need to specify this, as \fBld\fR
    1034 should be configured to produce as a default output format the most
    1035 usual format on each machine.  \fIoutput-format\fR is a text string, the
    1036 name of a particular format supported by the \s-1BFD\s0 libraries.  (You can
    1037 list the available binary formats with \fBobjdump \-i\fR.)  The script
    1038 command \f(CW\*(C`OUTPUT_FORMAT\*(C'\fR can also specify the output format, but
    1039 this option overrides it. 
    1040 .IP "\fB\-qmagic\fR" 4
    1041 .IX Item "-qmagic"
    1042 This option is ignored for Linux compatibility.
    1043 .IP "\fB\-Qy\fR" 4
    1044 .IX Item "-Qy"
    1045 This option is ignored for \s-1SVR4\s0 compatibility.
    1046 .IP "\fB\-\-relax\fR" 4
    1047 .IX Item "--relax"
    1048 An option with machine dependent effects.
    1049 This option is only supported on a few targets.
    1050 .Sp
    1051 On some platforms, the \fB\-\-relax\fR option performs global
    1052 optimizations that become possible when the linker resolves addressing
    1053 in the program, such as relaxing address modes and synthesizing new
    1054 instructions in the output object file.
    1055 .Sp
    1056 On some platforms these link time global optimizations may make symbolic
    1057 debugging of the resulting executable impossible.
    1058 This is known to be
    1059 the case for the Matsushita \s-1MN10200\s0 and \s-1MN10300\s0 family of processors.
    1060 .Sp
    1061 On platforms where this is not supported, \fB\-\-relax\fR is accepted,
    1062 but ignored.
    1063 .IP "\fB\-\-retain\-symbols\-file\fR \fIfilename\fR" 4
    1064 .IX Item "--retain-symbols-file filename"
    1065 Retain \fIonly\fR the symbols listed in the file \fIfilename\fR,
    1066 discarding all others.  \fIfilename\fR is simply a flat file, with one
    1067 symbol name per line.  This option is especially useful in environments
    1068 (such as VxWorks)
    1069 where a large global symbol table is accumulated gradually, to conserve
    1070 run-time memory.
    1071 .Sp
    1072 \&\fB\-\-retain\-symbols\-file\fR does \fInot\fR discard undefined symbols,
    1073 or symbols needed for relocations.
    1074 .Sp
    1075 You may only specify \fB\-\-retain\-symbols\-file\fR once in the command
    1076 line.  It overrides \fB\-s\fR and \fB\-S\fR.
    1077 .IP "\fB\-rpath\fR \fIdir\fR" 4
    1078 .IX Item "-rpath dir"
    1079 Add a directory to the runtime library search path.  This is used when
    1080 linking an \s-1ELF\s0 executable with shared objects.  All \fB\-rpath\fR
    1081 arguments are concatenated and passed to the runtime linker, which uses
    1082 them to locate shared objects at runtime.  The \fB\-rpath\fR option is
    1083 also used when locating shared objects which are needed by shared
    1084 objects explicitly included in the link; see the description of the
    1085 \&\fB\-rpath\-link\fR option.  If \fB\-rpath\fR is not used when linking an
    1086 \&\s-1ELF\s0 executable, the contents of the environment variable
    1087 \&\f(CW\*(C`LD_RUN_PATH\*(C'\fR will be used if it is defined.
    1088 .Sp
    1089 The \fB\-rpath\fR option may also be used on SunOS.  By default, on
    1090 SunOS, the linker will form a runtime search patch out of all the
    1091 \&\fB\-L\fR options it is given.  If a \fB\-rpath\fR option is used, the
    1092 runtime search path will be formed exclusively using the \fB\-rpath\fR
    1093 options, ignoring the \fB\-L\fR options.  This can be useful when using
    1094 gcc, which adds many \fB\-L\fR options which may be on \s-1NFS\s0 mounted
    1095 filesystems.
    1096 .Sp
    1097 For compatibility with other \s-1ELF\s0 linkers, if the \fB\-R\fR option is
    1098 followed by a directory name, rather than a file name, it is treated as
    1099 the \fB\-rpath\fR option.
    1100 .IP "\fB\-rpath\-link\fR \fI\s-1DIR\s0\fR" 4
    1101 .IX Item "-rpath-link DIR"
    1102 When using \s-1ELF\s0 or SunOS, one shared library may require another.  This
    1103 happens when an \f(CW\*(C`ld \-shared\*(C'\fR link includes a shared library as one
    1104 of the input files.
    1105 .Sp
    1106 When the linker encounters such a dependency when doing a non\-shared,
    1107 non-relocatable link, it will automatically try to locate the required
    1108 shared library and include it in the link, if it is not included
    1109 explicitly.  In such a case, the \fB\-rpath\-link\fR option
    1110 specifies the first set of directories to search.  The
    1111 \&\fB\-rpath\-link\fR option may specify a sequence of directory names
    1112 either by specifying a list of names separated by colons, or by
    1113 appearing multiple times.
    1114 .Sp
    1115 This option should be used with caution as it overrides the search path
    1116 that may have been hard compiled into a shared library. In such a case it
    1117 is possible to use unintentionally a different search path than the
    1118 runtime linker would do.
    1119 .Sp
    1120 The linker uses the following search paths to locate required shared
    1121 libraries.
    1122 .RS 4
    1123 .IP "1." 4
    1124 Any directories specified by \fB\-rpath\-link\fR options.
    1125 .IP "2." 4
    1126 Any directories specified by \fB\-rpath\fR options.  The difference
    1127 between \fB\-rpath\fR and \fB\-rpath\-link\fR is that directories
    1128 specified by \fB\-rpath\fR options are included in the executable and
    1129 used at runtime, whereas the \fB\-rpath\-link\fR option is only effective
    1130 at link time. It is for the native linker only.
    1131 .IP "3." 4
    1132 On an \s-1ELF\s0 system, if the \fB\-rpath\fR and \f(CW\*(C`rpath\-link\*(C'\fR options
    1133 were not used, search the contents of the environment variable
    1134 \&\f(CW\*(C`LD_RUN_PATH\*(C'\fR. It is for the native linker only.
    1135 .IP "4." 4
    1136 On SunOS, if the \fB\-rpath\fR option was not used, search any
    1137 directories specified using \fB\-L\fR options.
    1138 .IP "5." 4
    1139 For a native linker, the contents of the environment variable
    1140 \&\f(CW\*(C`LD_LIBRARY_PATH\*(C'\fR.
    1141 .IP "6." 4
    1142 For a native \s-1ELF\s0 linker, the directories in \f(CW\*(C`DT_RUNPATH\*(C'\fR or
    1143 \&\f(CW\*(C`DT_RPATH\*(C'\fR of a shared library are searched for shared
    1144 libraries needed by it. The \f(CW\*(C`DT_RPATH\*(C'\fR entries are ignored if
    1145 \&\f(CW\*(C`DT_RUNPATH\*(C'\fR entries exist.
    1146 .IP "7." 4
    1147 The default directories, normally \fI/lib\fR and \fI/usr/lib\fR.
    1148 .IP "8." 4
    1149 For a native linker on an \s-1ELF\s0 system, if the file \fI/etc/ld.so.conf\fR
    1150 exists, the list of directories found in that file.
    1151 .RE
    1152 .RS 4
    1153 .Sp
    1154 If the required shared library is not found, the linker will issue a
    1155 warning and continue with the link.
    1156 .RE
    1157 .IP "\fB\-shared\fR" 4
    1158 .IX Item "-shared"
    1159 .PD 0
    1160 .IP "\fB\-Bshareable\fR" 4
    1161 .IX Item "-Bshareable"
    1162 .PD
    1163 Create a shared library.  This is currently only supported on \s-1ELF\s0, \s-1XCOFF\s0
    1164 and SunOS platforms.  On SunOS, the linker will automatically create a
    1165 shared library if the \fB\-e\fR option is not used and there are
    1166 undefined symbols in the link.
    1167 .IP "\fB\-\-sort\-common\fR" 4
    1168 .IX Item "--sort-common"
    1169 This option tells \fBld\fR to sort the common symbols by size when it
    1170 places them in the appropriate output sections.  First come all the one
    1171 byte symbols, then all the two byte, then all the four byte, and then
    1172 everything else.  This is to prevent gaps between symbols due to
    1173 alignment constraints.
    1174 .IP "\fB\-\-split\-by\-file [\fR\fIsize\fR\fB]\fR" 4
    1175 .IX Item "--split-by-file [size]"
    1176 Similar to \fB\-\-split\-by\-reloc\fR but creates a new output section for
    1177 each input file when \fIsize\fR is reached.  \fIsize\fR defaults to a
    1178 size of 1 if not given.
    1179 .IP "\fB\-\-split\-by\-reloc [\fR\fIcount\fR\fB]\fR" 4
    1180 .IX Item "--split-by-reloc [count]"
    1181 Tries to creates extra sections in the output file so that no single
    1182 output section in the file contains more than \fIcount\fR relocations.
    1183 This is useful when generating huge relocatable files for downloading into
    1184 certain real time kernels with the \s-1COFF\s0 object file format; since \s-1COFF\s0
    1185 cannot represent more than 65535 relocations in a single section.  Note
    1186 that this will fail to work with object file formats which do not
    1187 support arbitrary sections.  The linker will not split up individual
    1188 input sections for redistribution, so if a single input section contains
    1189 more than \fIcount\fR relocations one output section will contain that
    1190 many relocations.  \fIcount\fR defaults to a value of 32768.
    1191 .IP "\fB\-\-stats\fR" 4
    1192 .IX Item "--stats"
    1193 Compute and display statistics about the operation of the linker, such
    1194 as execution time and memory usage.
    1195 .IP "\fB\-\-traditional\-format\fR" 4
    1196 .IX Item "--traditional-format"
    1197 For some targets, the output of \fBld\fR is different in some ways from
    1198 the output of some existing linker.  This switch requests \fBld\fR to
    1199 use the traditional format instead.
    1200 .Sp
    1201 For example, on SunOS, \fBld\fR combines duplicate entries in the
    1202 symbol string table.  This can reduce the size of an output file with
    1203 full debugging information by over 30 percent.  Unfortunately, the SunOS
    1204 \&\f(CW\*(C`dbx\*(C'\fR program can not read the resulting program (\f(CW\*(C`gdb\*(C'\fR has no
    1205 trouble).  The \fB\-\-traditional\-format\fR switch tells \fBld\fR to not
    1206 combine duplicate entries.
    1207 .IP "\fB\-\-section\-start\fR \fIsectionname\fR\fB=\fR\fIorg\fR" 4
    1208 .IX Item "--section-start sectionname=org"
    1209 Locate a section in the output file at the absolute
    1210 address given by \fIorg\fR.  You may use this option as many
    1211 times as necessary to locate multiple sections in the command
    1212 line.
    1213 \&\fIorg\fR must be a single hexadecimal integer;
    1214 for compatibility with other linkers, you may omit the leading
    1215 \&\fB0x\fR usually associated with hexadecimal values.  \fINote:\fR there
    1216 should be no white space between \fIsectionname\fR, the equals
    1217 sign (``\fB=\fR''), and \fIorg\fR.
    1218 .IP "\fB\-Tbss\fR \fIorg\fR" 4
    1219 .IX Item "-Tbss org"
    1220 .PD 0
    1221 .IP "\fB\-Tdata\fR \fIorg\fR" 4
    1222 .IX Item "-Tdata org"
    1223 .IP "\fB\-Ttext\fR \fIorg\fR" 4
    1224 .IX Item "-Ttext org"
    1225 .PD
    1226 Same as \-\-section\-start, with \f(CW\*(C`.bss\*(C'\fR, \f(CW\*(C`.data\*(C'\fR or
    1227 \&\f(CW\*(C`.text\*(C'\fR as the \fIsectionname\fR.
    1228 .IP "\fB\-\-dll\-verbose\fR" 4
    1229 .IX Item "--dll-verbose"
    1230 .PD 0
    1231 .IP "\fB\-\-verbose\fR" 4
    1232 .IX Item "--verbose"
    1233 .PD
    1234 Display the version number for \fBld\fR and list the linker emulations
    1235 supported.  Display which input files can and cannot be opened.  Display
    1236 the linker script being used by the linker.
    1237 .IP "\fB\-\-version\-script=\fR\fIversion-scriptfile\fR" 4
    1238 .IX Item "--version-script=version-scriptfile"
    1239 Specify the name of a version script to the linker.  This is typically
    1240 used when creating shared libraries to specify additional information
    1241 about the version hierarchy for the library being created.  This option
    1242 is only meaningful on \s-1ELF\s0 platforms which support shared libraries.
    1243 .IP "\fB\-\-warn\-common\fR" 4
    1244 .IX Item "--warn-common"
    1245 Warn when a common symbol is combined with another common symbol or with
    1246 a symbol definition.  Unix linkers allow this somewhat sloppy practice,
    1247 but linkers on some other operating systems do not.  This option allows
    1248 you to find potential problems from combining global symbols.
    1249 Unfortunately, some C libraries use this practice, so you may get some
    1250 warnings about symbols in the libraries as well as in your programs.
    1251 .Sp
    1252 There are three kinds of global symbols, illustrated here by C examples:
    1253 .RS 4
    1254 .IP "\fBint i = 1;\fR" 4
    1255 .IX Item "int i = 1;"
    1256 A definition, which goes in the initialized data section of the output
    1257 file.
    1258 .IP "\fBextern int i;\fR" 4
    1259 .IX Item "extern int i;"
    1260 An undefined reference, which does not allocate space.
    1261 There must be either a definition or a common symbol for the
    1262 variable somewhere.
    1263 .IP "\fBint i;\fR" 4
    1264 .IX Item "int i;"
    1265 A common symbol.  If there are only (one or more) common symbols for a
    1266 variable, it goes in the uninitialized data area of the output file.
    1267 The linker merges multiple common symbols for the same variable into a
    1268 single symbol.  If they are of different sizes, it picks the largest
    1269 size.  The linker turns a common symbol into a declaration, if there is
    1270 a definition of the same variable.
    1271 .RE
    1272 .RS 4
    1273 .Sp
    1274 The \fB\-\-warn\-common\fR option can produce five kinds of warnings.
    1275 Each warning consists of a pair of lines: the first describes the symbol
    1276 just encountered, and the second describes the previous symbol
    1277 encountered with the same name.  One or both of the two symbols will be
    1278 a common symbol.
    1279 .IP "1." 4
    1280 Turning a common symbol into a reference, because there is already a
    1281 definition for the symbol.
    1282 .Sp
    1283 .Vb 3
    1284 \&        <file>(<section>): warning: common of `<symbol>'
    1285 \&           overridden by definition
    1286 \&        <file>(<section>): warning: defined here
    1287 .Ve
    1288 .IP "2." 4
    1289 Turning a common symbol into a reference, because a later definition for
    1290 the symbol is encountered.  This is the same as the previous case,
    1291 except that the symbols are encountered in a different order.
    1292 .Sp
    1293 .Vb 3
    1294 \&        <file>(<section>): warning: definition of `<symbol>'
    1295 \&           overriding common
    1296 \&        <file>(<section>): warning: common is here
    1297 .Ve
    1298 .IP "3." 4
    1299 Merging a common symbol with a previous same-sized common symbol.
    1300 .Sp
    1301 .Vb 3
    1302 \&        <file>(<section>): warning: multiple common
    1303 \&           of `<symbol>'
    1304 \&        <file>(<section>): warning: previous common is here
    1305 .Ve
    1306 .IP "4." 4
    1307 Merging a common symbol with a previous larger common symbol.
    1308 .Sp
    1309 .Vb 3
    1310 \&        <file>(<section>): warning: common of `<symbol>'
    1311 \&           overridden by larger common
    1312 \&        <file>(<section>): warning: larger common is here
    1313 .Ve
    1314 .IP "5." 4
    1315 Merging a common symbol with a previous smaller common symbol.  This is
    1316 the same as the previous case, except that the symbols are
    1317 encountered in a different order.
    1318 .Sp
    1319 .Vb 3
    1320 \&        <file>(<section>): warning: common of `<symbol>'
    1321 \&           overriding smaller common
    1322 \&        <file>(<section>): warning: smaller common is here
    1323 .Ve
    1324 .RE
    1325 .RS 4
    1326 .RE
    1327 .IP "\fB\-\-warn\-constructors\fR" 4
    1328 .IX Item "--warn-constructors"
    1329 Warn if any global constructors are used.  This is only useful for a few
    1330 object file formats.  For formats like \s-1COFF\s0 or \s-1ELF\s0, the linker can not
    1331 detect the use of global constructors.
    1332 .IP "\fB\-\-warn\-multiple\-gp\fR" 4
    1333 .IX Item "--warn-multiple-gp"
    1334 Warn if multiple global pointer values are required in the output file.
    1335 This is only meaningful for certain processors, such as the Alpha.
    1336 Specifically, some processors put large-valued constants in a special
    1337 section.  A special register (the global pointer) points into the middle
    1338 of this section, so that constants can be loaded efficiently via a
    1339 base-register relative addressing mode.  Since the offset in
    1340 base-register relative mode is fixed and relatively small (e.g., 16
    1341 bits), this limits the maximum size of the constant pool.  Thus, in
    1342 large programs, it is often necessary to use multiple global pointer
    1343 values in order to be able to address all possible constants.  This
    1344 option causes a warning to be issued whenever this case occurs.
    1345 .IP "\fB\-\-warn\-once\fR" 4
    1346 .IX Item "--warn-once"
    1347 Only warn once for each undefined symbol, rather than once per module
    1348 which refers to it.
    1349 .IP "\fB\-\-warn\-section\-align\fR" 4
    1350 .IX Item "--warn-section-align"
    1351 Warn if the address of an output section is changed because of
    1352 alignment.  Typically, the alignment will be set by an input section.
    1353 The address will only be changed if it not explicitly specified; that
    1354 is, if the \f(CW\*(C`SECTIONS\*(C'\fR command does not specify a start address for
    1355 the section.
    1356 .IP "\fB\-\-whole\-archive\fR" 4
    1357 .IX Item "--whole-archive"
    1358 For each archive mentioned on the command line after the
    1359 \&\fB\-\-whole\-archive\fR option, include every object file in the archive
    1360 in the link, rather than searching the archive for the required object
    1361 files.  This is normally used to turn an archive file into a shared
    1362 library, forcing every object to be included in the resulting shared
    1363 library.  This option may be used more than once.
    1364 .Sp
    1365 Two notes when using this option from gcc: First, gcc doesn't know
    1366 about this option, so you have to use \fB\-Wl,\-whole\-archive\fR.
    1367 Second, don't forget to use \fB\-Wl,\-no\-whole\-archive\fR after your
    1368 list of archives, because gcc will add its own list of archives to
    1369 your link and you may not want this flag to affect those as well.
    1370 .IP "\fB\-\-wrap\fR \fIsymbol\fR" 4
    1371 .IX Item "--wrap symbol"
    1372 Use a wrapper function for \fIsymbol\fR.  Any undefined reference to
    1373 \&\fIsymbol\fR will be resolved to \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR.  Any
    1374 undefined reference to \f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR will be resolved to
    1375 \&\fIsymbol\fR.
    1376 .Sp
    1377 This can be used to provide a wrapper for a system function.  The
    1378 wrapper function should be called \f(CW\*(C`_\|_wrap_\f(CIsymbol\f(CW\*(C'\fR.  If it
    1379 wishes to call the system function, it should call
    1380 \&\f(CW\*(C`_\|_real_\f(CIsymbol\f(CW\*(C'\fR.
    1381 .Sp
    1382 Here is a trivial example:
    1383 .Sp
    1384 .Vb 6
    1385 \&        void *
    1386 \&        __wrap_malloc (int c)
    1387 \&        {
    1388 \&          printf ("malloc called with %ld\en", c);
    1389 \&          return __real_malloc (c);
    1390 \&        }
    1391 .Ve
    1392 .Sp
    1393 If you link other code with this file using \fB\-\-wrap malloc\fR, then
    1394 all calls to \f(CW\*(C`malloc\*(C'\fR will call the function \f(CW\*(C`_\|_wrap_malloc\*(C'\fR
    1395 instead.  The call to \f(CW\*(C`_\|_real_malloc\*(C'\fR in \f(CW\*(C`_\|_wrap_malloc\*(C'\fR will
    1396 call the real \f(CW\*(C`malloc\*(C'\fR function.
    1397 .Sp
    1398 You may wish to provide a \f(CW\*(C`_\|_real_malloc\*(C'\fR function as well, so that
    1399 links without the \fB\-\-wrap\fR option will succeed.  If you do this,
    1400 you should not put the definition of \f(CW\*(C`_\|_real_malloc\*(C'\fR in the same
    1401 file as \f(CW\*(C`_\|_wrap_malloc\*(C'\fR; if you do, the assembler may resolve the
    1402 call before the linker has a chance to wrap it to \f(CW\*(C`malloc\*(C'\fR.
    1403 .IP "\fB\-\-enable\-new\-dtags\fR" 4
    1404 .IX Item "--enable-new-dtags"
    1405 .PD 0
    1406 .IP "\fB\-\-disable\-new\-dtags\fR" 4
    1407 .IX Item "--disable-new-dtags"
    1408 .PD
    1409 This linker can create the new dynamic tags in \s-1ELF\s0. But the older \s-1ELF\s0
    1410 systems may not understand them. If you specify
    1411 \&\fB\-\-enable\-new\-dtags\fR, the dynamic tags will be created as needed.
    1412 If you specify \fB\-\-disable\-new\-dtags\fR, no new dynamic tags will be
    1413 created. By default, the new dynamic tags are not created. Note that
    1414 those options are only available for \s-1ELF\s0 systems.
    1415 .PP
    1416 The i386 \s-1PE\s0 linker supports the \fB\-shared\fR option, which causes
    1417 the output to be a dynamically linked library (\s-1DLL\s0) instead of a
    1418 normal executable.  You should name the output \f(CW\*(C`*.dll\*(C'\fR when you
    1419 use this option.  In addition, the linker fully supports the standard
    1420 \&\f(CW\*(C`*.def\*(C'\fR files, which may be specified on the linker command line
    1421 like an object file (in fact, it should precede archives it exports
    1422 symbols from, to ensure that they get linked in, just like a normal
    1423 object file).
    1424 .PP
    1425 In addition to the options common to all targets, the i386 \s-1PE\s0 linker
    1426 support additional command line options that are specific to the i386
    1427 \&\s-1PE\s0 target.  Options that take values may be separated from their
    1428 values by either a space or an equals sign.
    1429 .IP "\fB\-\-add\-stdcall\-alias\fR" 4
    1430 .IX Item "--add-stdcall-alias"
    1431 If given, symbols with a stdcall suffix (@\fInn\fR) will be exported
    1432 as-is and also with the suffix stripped.
    1433 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1434 .IP "\fB\-\-base\-file\fR \fIfile\fR" 4
    1435 .IX Item "--base-file file"
    1436 Use \fIfile\fR as the name of a file in which to save the base
    1437 addresses of all the relocations needed for generating DLLs with
    1438 \&\fIdlltool\fR.
    1439 [This is an i386 \s-1PE\s0 specific option]
    1440 .IP "\fB\-\-dll\fR" 4
    1441 .IX Item "--dll"
    1442 Create a \s-1DLL\s0 instead of a regular executable.  You may also use
    1443 \&\fB\-shared\fR or specify a \f(CW\*(C`LIBRARY\*(C'\fR in a given \f(CW\*(C`.def\*(C'\fR
    1444 file.
    1445 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1446 .IP "\fB\-\-enable\-stdcall\-fixup\fR" 4
    1447 .IX Item "--enable-stdcall-fixup"
    1448 .PD 0
    1449 .IP "\fB\-\-disable\-stdcall\-fixup\fR" 4
    1450 .IX Item "--disable-stdcall-fixup"
    1451 .PD
    1452 If the link finds a symbol that it cannot resolve, it will attempt to
    1453 do ``fuzzy linking'' by looking for another defined symbol that differs
    1454 only in the format of the symbol name (cdecl vs stdcall) and will
    1455 resolve that symbol by linking to the match.  For example, the
    1456 undefined symbol \f(CW\*(C`_foo\*(C'\fR might be linked to the function
    1457 \&\f(CW\*(C`_foo@12\*(C'\fR, or the undefined symbol \f(CW\*(C`_bar@16\*(C'\fR might be linked
    1458 to the function \f(CW\*(C`_bar\*(C'\fR.  When the linker does this, it prints a
    1459 warning, since it normally should have failed to link, but sometimes
    1460 import libraries generated from third-party dlls may need this feature
    1461 to be usable.  If you specify \fB\-\-enable\-stdcall\-fixup\fR, this
    1462 feature is fully enabled and warnings are not printed.  If you specify
    1463 \&\fB\-\-disable\-stdcall\-fixup\fR, this feature is disabled and such
    1464 mismatches are considered to be errors.
    1465 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1466 .IP "\fB\-\-export\-all\-symbols\fR" 4
    1467 .IX Item "--export-all-symbols"
    1468 If given, all global symbols in the objects used to build a \s-1DLL\s0 will
    1469 be exported by the \s-1DLL\s0.  Note that this is the default if there
    1470 otherwise wouldn't be any exported symbols.  When symbols are
    1471 explicitly exported via \s-1DEF\s0 files or implicitly exported via function
    1472 attributes, the default is to not export anything else unless this
    1473 option is given.  Note that the symbols \f(CW\*(C`DllMain@12\*(C'\fR,
    1474 \&\f(CW\*(C`DllEntryPoint@0\*(C'\fR, \f(CW\*(C`DllMainCRTStartup@12\*(C'\fR, and
    1475 \&\f(CW\*(C`impure_ptr\*(C'\fR will not be automatically
    1476 exported.  Also, symbols imported from other DLLs will not be
    1477 re\-exported, nor will symbols specifying the \s-1DLL\s0's internal layout
    1478 such as those beginning with \f(CW\*(C`_head_\*(C'\fR or ending with
    1479 \&\f(CW\*(C`_iname\*(C'\fR.  In addition, no symbols from \f(CW\*(C`libgcc\*(C'\fR,
    1480 \&\f(CW\*(C`libstd++\*(C'\fR, \f(CW\*(C`libmingw32\*(C'\fR, or \f(CW\*(C`crtX.o\*(C'\fR will be exported.
    1481 Symbols whose names begin with \f(CW\*(C`_\|_rtti_\*(C'\fR or \f(CW\*(C`_\|_builtin_\*(C'\fR will
    1482 not be exported, to help with \*(C+ DLLs.  Finally, there is an
    1483 extensive list of cygwin-private symbols that are not exported
    1484 (obviously, this applies on when building DLLs for cygwin targets).
    1485 These cygwin-excludes are: \f(CW\*(C`_cygwin_dll_entry@12\*(C'\fR,
    1486 \&\f(CW\*(C`_cygwin_crt0_common@8\*(C'\fR, \f(CW\*(C`_cygwin_noncygwin_dll_entry@12\*(C'\fR,
    1487 \&\f(CW\*(C`_fmode\*(C'\fR, \f(CW\*(C`_impure_ptr\*(C'\fR, \f(CW\*(C`cygwin_attach_dll\*(C'\fR,
    1488 \&\f(CW\*(C`cygwin_premain0\*(C'\fR, \f(CW\*(C`cygwin_premain1\*(C'\fR, \f(CW\*(C`cygwin_premain2\*(C'\fR,
    1489 \&\f(CW\*(C`cygwin_premain3\*(C'\fR, and \f(CW\*(C`environ\*(C'\fR.
    1490 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1491 .IP "\fB\-\-exclude\-symbols\fR \fIsymbol\fR\fB,\fR\fIsymbol\fR\fB,...\fR" 4
    1492 .IX Item "--exclude-symbols symbol,symbol,..."
    1493 Specifies a list of symbols which should not be automatically
    1494 exported.  The symbol names may be delimited by commas or colons.
    1495 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1496 .IP "\fB\-\-exclude\-libs\fR \fIlib\fR\fB,\fR\fIlib\fR\fB,...\fR" 4
    1497 .IX Item "--exclude-libs lib,lib,..."
    1498 Specifies a list of archive libraries from which symbols should not be automatically
    1499 exported. The library names may be delimited by commas or colons.  Specifying
    1500 \&\f(CW\*(C`\-\-exclude\-libs ALL\*(C'\fR excludes symbols in all archive libraries from
    1501 automatic export. Symbols explicitly listed in a .def file are still exported,
    1502 regardless of this option.
    1503 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1504 .IP "\fB\-\-file\-alignment\fR" 4
    1505 .IX Item "--file-alignment"
    1506 Specify the file alignment.  Sections in the file will always begin at
    1507 file offsets which are multiples of this number.  This defaults to
    1508 512.
    1509 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1510 .IP "\fB\-\-heap\fR \fIreserve\fR" 4
    1511 .IX Item "--heap reserve"
    1512 .PD 0
    1513 .IP "\fB\-\-heap\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
    1514 .IX Item "--heap reserve,commit"
    1515 .PD
    1516 Specify the amount of memory to reserve (and optionally commit) to be
    1517 used as heap for this program.  The default is 1Mb reserved, 4K
    1518 committed.
    1519 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1520 .IP "\fB\-\-image\-base\fR \fIvalue\fR" 4
    1521 .IX Item "--image-base value"
    1522 Use \fIvalue\fR as the base address of your program or dll.  This is
    1523 the lowest memory location that will be used when your program or dll
    1524 is loaded.  To reduce the need to relocate and improve performance of
    1525 your dlls, each should have a unique base address and not overlap any
    1526 other dlls.  The default is 0x400000 for executables, and 0x10000000
    1527 for dlls.
    1528 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1529 .IP "\fB\-\-kill\-at\fR" 4
    1530 .IX Item "--kill-at"
    1531 If given, the stdcall suffixes (@\fInn\fR) will be stripped from
    1532 symbols before they are exported.
    1533 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1534 .IP "\fB\-\-major\-image\-version\fR \fIvalue\fR" 4
    1535 .IX Item "--major-image-version value"
    1536 Sets the major number of the ``image version''.  Defaults to 1.
    1537 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1538 .IP "\fB\-\-major\-os\-version\fR \fIvalue\fR" 4
    1539 .IX Item "--major-os-version value"
    1540 Sets the major number of the ``os version''.  Defaults to 4.
    1541 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1542 .IP "\fB\-\-major\-subsystem\-version\fR \fIvalue\fR" 4
    1543 .IX Item "--major-subsystem-version value"
    1544 Sets the major number of the ``subsystem version''.  Defaults to 4.
    1545 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1546 .IP "\fB\-\-minor\-image\-version\fR \fIvalue\fR" 4
    1547 .IX Item "--minor-image-version value"
    1548 Sets the minor number of the ``image version''.  Defaults to 0.
    1549 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1550 .IP "\fB\-\-minor\-os\-version\fR \fIvalue\fR" 4
    1551 .IX Item "--minor-os-version value"
    1552 Sets the minor number of the ``os version''.  Defaults to 0.
    1553 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1554 .IP "\fB\-\-minor\-subsystem\-version\fR \fIvalue\fR" 4
    1555 .IX Item "--minor-subsystem-version value"
    1556 Sets the minor number of the ``subsystem version''.  Defaults to 0.
    1557 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1558 .IP "\fB\-\-output\-def\fR \fIfile\fR" 4
    1559 .IX Item "--output-def file"
    1560 The linker will create the file \fIfile\fR which will contain a \s-1DEF\s0
    1561 file corresponding to the \s-1DLL\s0 the linker is generating.  This \s-1DEF\s0 file
    1562 (which should be called \f(CW\*(C`*.def\*(C'\fR) may be used to create an import
    1563 library with \f(CW\*(C`dlltool\*(C'\fR or may be used as a reference to
    1564 automatically or implicitly exported symbols.
    1565 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1566 .IP "\fB\-\-out\-implib\fR \fIfile\fR" 4
    1567 .IX Item "--out-implib file"
    1568 The linker will create the file \fIfile\fR which will contain an
    1569 import lib corresponding to the \s-1DLL\s0 the linker is generating. This
    1570 import lib (which should be called \f(CW\*(C`*.dll.a\*(C'\fR or \f(CW\*(C`*.a\*(C'\fR
    1571 may be used to link clients against the generated \s-1DLL\s0; this behavior
    1572 makes it possible to skip a separate \f(CW\*(C`dlltool\*(C'\fR import library
    1573 creation step.
    1574 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1575 .IP "\fB\-\-enable\-auto\-image\-base\fR" 4
    1576 .IX Item "--enable-auto-image-base"
    1577 Automatically choose the image base for DLLs, unless one is specified
    1578 using the \f(CW\*(C`\-\-image\-base\*(C'\fR argument.  By using a hash generated
    1579 from the dllname to create unique image bases for each \s-1DLL\s0, in-memory
    1580 collisions and relocations which can delay program execution are
    1581 avoided.
    1582 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1583 .IP "\fB\-\-disable\-auto\-image\-base\fR" 4
    1584 .IX Item "--disable-auto-image-base"
    1585 Do not automatically generate a unique image base.  If there is no
    1586 user-specified image base (\f(CW\*(C`\-\-image\-base\*(C'\fR) then use the platform
    1587 default.
    1588 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1589 .IP "\fB\-\-dll\-search\-prefix\fR \fIstring\fR" 4
    1590 .IX Item "--dll-search-prefix string"
    1591 When linking dynamically to a dll without an import library,
    1592 search for \f(CW\*(C`<string><basename>.dll\*(C'\fR in preference to
    1593 \&\f(CW\*(C`lib<basename>.dll\*(C'\fR. This behavior allows easy distinction
    1594 between DLLs built for the various \*(L"subplatforms\*(R": native, cygwin,
    1595 uwin, pw, etc.  For instance, cygwin DLLs typically use
    1596 \&\f(CW\*(C`\-\-dll\-search\-prefix=cyg\*(C'\fR.
    1597 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1598 .IP "\fB\-\-enable\-auto\-import\fR" 4
    1599 .IX Item "--enable-auto-import"
    1600 Do sophisticated linking of \f(CW\*(C`_symbol\*(C'\fR to \f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for
    1601 \&\s-1DATA\s0 imports from DLLs, and create the necessary thunking symbols when
    1602 building the import libraries with those \s-1DATA\s0 exports.  This generally
    1603 will 'just work' \*(-- but sometimes you may see this message:
    1604 .Sp
    1605 "variable '<var>' can't be auto\-imported. Please read the
    1606 documentation for ld's \f(CW\*(C`\-\-enable\-auto\-import\*(C'\fR for details."
    1607 .Sp
    1608 This message occurs when some (sub)expression accesses an address
    1609 ultimately given by the sum of two constants (Win32 import tables only
    1610 allow one).  Instances where this may occur include accesses to member
    1611 fields of struct variables imported from a \s-1DLL\s0, as well as using a
    1612 constant index into an array variable imported from a \s-1DLL\s0.  Any
    1613 multiword variable (arrays, structs, long long, etc) may trigger
    1614 this error condition.  However, regardless of the exact data type
    1615 of the offending exported variable, ld will always detect it, issue
    1616 the warning, and exit.
    1617 .Sp
    1618 There are several ways to address this difficulty, regardless of the
    1619 data type of the exported variable:
    1620 .Sp
    1621 One way is to use \-\-enable\-runtime\-pseudo\-reloc switch. This leaves the task
    1622 of adjusting references in your client code for runtime environment, so
    1623 this method works only when runtime environtment supports this feature.
    1624 .Sp
    1625 A second solution is to force one of the 'constants' to be a variable \*(--
    1626 that is, unknown and un-optimizable at compile time.  For arrays,
    1627 there are two possibilities: a) make the indexee (the array's address)
    1628 a variable, or b) make the 'constant' index a variable.  Thus:
    1629 .Sp
    1630 .Vb 3
    1631 \&        extern type extern_array[];
    1632 \&        extern_array[1] -->
    1633 \&           { volatile type *t=extern_array; t[1] }
    1634 .Ve
    1635 .Sp
    1636 or
    1637 .Sp
    1638 .Vb 3
    1639 \&        extern type extern_array[];
    1640 \&        extern_array[1] -->
    1641 \&           { volatile int t=1; extern_array[t] }
    1642 .Ve
    1643 .Sp
    1644 For structs (and most other multiword data types) the only option
    1645 is to make the struct itself (or the long long, or the ...) variable:
    1646 .Sp
    1647 .Vb 3
    1648 \&        extern struct s extern_struct;
    1649 \&        extern_struct.field -->
    1650 \&           { volatile struct s *t=&extern_struct; t->field }
    1651 .Ve
    1652 .Sp
    1653 or
    1654 .Sp
    1655 .Vb 3
    1656 \&        extern long long extern_ll;
    1657 \&        extern_ll -->
    1658 \&          { volatile long long * local_ll=&extern_ll; *local_ll }
    1659 .Ve
    1660 .Sp
    1661 A third method of dealing with this difficulty is to abandon
    1662 \&'auto\-import' for the offending symbol and mark it with
    1663 \&\f(CW\*(C`_\|_declspec(dllimport)\*(C'\fR.  However, in practice that
    1664 requires using compile-time #defines to indicate whether you are
    1665 building a \s-1DLL\s0, building client code that will link to the \s-1DLL\s0, or
    1666 merely building/linking to a static library.   In making the choice
    1667 between the various methods of resolving the 'direct address with
    1668 constant offset' problem, you should consider typical real-world usage:
    1669 .Sp
    1670 Original:
    1671 .Sp
    1672 .Vb 7
    1673 \&        --foo.h
    1674 \&        extern int arr[];
    1675 \&        --foo.c
    1676 \&        #include "foo.h"
    1677 \&        void main(int argc, char **argv){
    1678 \&          printf("%d\en",arr[1]);
    1679 \&        }
    1680 .Ve
    1681 .Sp
    1682 Solution 1:
    1683 .Sp
    1684 .Vb 9
    1685 \&        --foo.h
    1686 \&        extern int arr[];
    1687 \&        --foo.c
    1688 \&        #include "foo.h"
    1689 \&        void main(int argc, char **argv){
    1690 \&          /* This workaround is for win32 and cygwin; do not "optimize" */
    1691 \&          volatile int *parr = arr;
    1692 \&          printf("%d\en",parr[1]);
    1693 \&        }
    1694 .Ve
    1695 .Sp
    1696 Solution 2:
    1697 .Sp
    1698 .Vb 14
    1699 \&        --foo.h
    1700 \&        /* Note: auto-export is assumed (no __declspec(dllexport)) */
    1701 \&        #if (defined(_WIN32) || defined(__CYGWIN__)) && \e
    1702 \&          !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
    1703 \&        #define FOO_IMPORT __declspec(dllimport)
    1704 \&        #else
    1705 \&        #define FOO_IMPORT
    1706 \&        #endif
    1707 \&        extern FOO_IMPORT int arr[];
    1708 \&        --foo.c
    1709 \&        #include "foo.h"
    1710 \&        void main(int argc, char **argv){
    1711 \&          printf("%d\en",arr[1]);
    1712 \&        }
    1713 .Ve
    1714 .Sp
    1715 A fourth way to avoid this problem is to re-code your
    1716 library to use a functional interface rather than a data interface
    1717 for the offending variables (e.g. \fIset_foo()\fR and \fIget_foo()\fR accessor
    1718 functions).
    1719 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1720 .IP "\fB\-\-disable\-auto\-import\fR" 4
    1721 .IX Item "--disable-auto-import"
    1722 Do not attempt to do sophisticalted linking of \f(CW\*(C`_symbol\*(C'\fR to
    1723 \&\f(CW\*(C`_\|_imp_\|_symbol\*(C'\fR for \s-1DATA\s0 imports from DLLs.
    1724 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1725 .IP "\fB\-\-enable\-runtime\-pseudo\-reloc\fR" 4
    1726 .IX Item "--enable-runtime-pseudo-reloc"
    1727 If your code contains expressions described in \-\-enable\-auto\-import section,
    1728 that is, \s-1DATA\s0 imports from \s-1DLL\s0 with non-zero offset, this switch will create
    1729 a vector of 'runtime pseudo relocations' which can be used by runtime
    1730 environment to adjust references to such data in your client code.
    1731 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1732 .IP "\fB\-\-disable\-runtime\-pseudo\-reloc\fR" 4
    1733 .IX Item "--disable-runtime-pseudo-reloc"
    1734 Do not create pseudo relocations for non-zero offset \s-1DATA\s0 imports from
    1735 DLLs.  This is the default.
    1736 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1737 .IP "\fB\-\-enable\-extra\-pe\-debug\fR" 4
    1738 .IX Item "--enable-extra-pe-debug"
    1739 Show additional debug info related to auto-import symbol thunking.
    1740 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1741 .IP "\fB\-\-section\-alignment\fR" 4
    1742 .IX Item "--section-alignment"
    1743 Sets the section alignment.  Sections in memory will always begin at
    1744 addresses which are a multiple of this number.  Defaults to 0x1000.
    1745 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1746 .IP "\fB\-\-stack\fR \fIreserve\fR" 4
    1747 .IX Item "--stack reserve"
    1748 .PD 0
    1749 .IP "\fB\-\-stack\fR \fIreserve\fR\fB,\fR\fIcommit\fR" 4
    1750 .IX Item "--stack reserve,commit"
    1751 .PD
    1752 Specify the amount of memory to reserve (and optionally commit) to be
    1753 used as stack for this program.  The default is 2Mb reserved, 4K
    1754 committed.
    1755 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1756 .IP "\fB\-\-subsystem\fR \fIwhich\fR" 4
    1757 .IX Item "--subsystem which"
    1758 .PD 0
    1759 .IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR" 4
    1760 .IX Item "--subsystem which:major"
    1761 .IP "\fB\-\-subsystem\fR \fIwhich\fR\fB:\fR\fImajor\fR\fB.\fR\fIminor\fR" 4
    1762 .IX Item "--subsystem which:major.minor"
    1763 .PD
    1764 Specifies the subsystem under which your program will execute.  The
    1765 legal values for \fIwhich\fR are \f(CW\*(C`native\*(C'\fR, \f(CW\*(C`windows\*(C'\fR,
    1766 \&\f(CW\*(C`console\*(C'\fR, and \f(CW\*(C`posix\*(C'\fR.  You may optionally set the
    1767 subsystem version also.
    1768 [This option is specific to the i386 \s-1PE\s0 targeted port of the linker]
    1769 .SH "ENVIRONMENT"
    1770 .IX Header "ENVIRONMENT"
    1771 You can change the behavior of \fBld\fR with the environment variables
    1772 \&\f(CW\*(C`GNUTARGET\*(C'\fR,
    1773 \&\f(CW\*(C`LDEMULATION\*(C'\fR and \f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR.
    1774 .PP
    1775 \&\f(CW\*(C`GNUTARGET\*(C'\fR determines the input-file object format if you don't
    1776 use \fB\-b\fR (or its synonym \fB\-\-format\fR).  Its value should be one
    1777 of the \s-1BFD\s0 names for an input format.  If there is no
    1778 \&\f(CW\*(C`GNUTARGET\*(C'\fR in the environment, \fBld\fR uses the natural format
    1779 of the target. If \f(CW\*(C`GNUTARGET\*(C'\fR is set to \f(CW\*(C`default\*(C'\fR then \s-1BFD\s0
    1780 attempts to discover the input format by examining binary input files;
    1781 this method often succeeds, but there are potential ambiguities, since
    1782 there is no method of ensuring that the magic number used to specify
    1783 object-file formats is unique.  However, the configuration procedure for
    1784 \&\s-1BFD\s0 on each system places the conventional format for that system first
    1785 in the search\-list, so ambiguities are resolved in favor of convention.
    1786 .PP
    1787 \&\f(CW\*(C`LDEMULATION\*(C'\fR determines the default emulation if you don't use the
    1788 \&\fB\-m\fR option.  The emulation can affect various aspects of linker
    1789 behaviour, particularly the default linker script.  You can list the
    1790 available emulations with the \fB\-\-verbose\fR or \fB\-V\fR options.  If
    1791 the \fB\-m\fR option is not used, and the \f(CW\*(C`LDEMULATION\*(C'\fR environment
    1792 variable is not defined, the default emulation depends upon how the
    1793 linker was configured.
    1794 .PP
    1795 Normally, the linker will default to demangling symbols.  However, if
    1796 \&\f(CW\*(C`COLLECT_NO_DEMANGLE\*(C'\fR is set in the environment, then it will
    1797 default to not demangling symbols.  This environment variable is used in
    1798 a similar fashion by the \f(CW\*(C`gcc\*(C'\fR linker wrapper program.  The default
    1799 may be overridden by the \fB\-\-demangle\fR and \fB\-\-no\-demangle\fR
    1800 options.
    1801 .SH "SEE ALSO"
    1802 .IX Header "SEE ALSO"
    1803 \&\fIar\fR\|(1), \fInm\fR\|(1), \fIobjcopy\fR\|(1), \fIobjdump\fR\|(1), \fIreadelf\fR\|(1) and
    1804 the Info entries for \fIbinutils\fR and
    1805 \&\fIld\fR.
    1806 .SH "COPYRIGHT"
    1807 .IX Header "COPYRIGHT"
    1808 Copyright (c) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
    1809 2002, 2003 Free Software Foundation, Inc.
    1810 .PP
    1811 Permission is granted to copy, distribute and/or modify this document
    1812 under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.1
    1813 or any later version published by the Free Software Foundation;
    1814 with no Invariant Sections, with no Front-Cover Texts, and with no
    1815 Back-Cover Texts.  A copy of the license is included in the
    1816 section entitled ``\s-1GNU\s0 Free Documentation License''.
Note: See TracChangeset for help on using the changeset viewer.