OpenCores
URL https://opencores.org/ocsvn/openrisc/openrisc/trunk

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-stable/] [binutils-2.20.1/] [ld/] [ld.info] - Blame information for rev 818

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 205 julius
This is ld.info, produced by makeinfo version 4.8 from ld.texinfo.
2
 
3
START-INFO-DIR-ENTRY
4
* Ld: (ld).                       The GNU linker.
5
END-INFO-DIR-ENTRY
6
 
7
   This file documents the GNU linker LD (GNU Binutils) version 2.20.
8
 
9
   Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001,
10
2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software
11
Foundation, Inc.
12
 
13
   Permission is granted to copy, distribute and/or modify this document
14
under the terms of the GNU Free Documentation License, Version 1.3 or
15
any later version published by the Free Software Foundation; with no
16
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
17
Texts.  A copy of the license is included in the section entitled "GNU
18
Free Documentation License".
19
 
20

21
File: ld.info,  Node: Top,  Next: Overview,  Up: (dir)
22
 
23
LD
24
**
25
 
26
This file documents the GNU linker ld (GNU Binutils) version 2.20.
27
 
28
   This document is distributed under the terms of the GNU Free
29
Documentation License version 1.3.  A copy of the license is included
30
in the section entitled "GNU Free Documentation License".
31
 
32
* Menu:
33
 
34
* Overview::                    Overview
35
* Invocation::                  Invocation
36
* Scripts::                     Linker Scripts
37
 
38
* Machine Dependent::           Machine Dependent Features
39
 
40
* BFD::                         BFD
41
 
42
* Reporting Bugs::              Reporting Bugs
43
* MRI::                         MRI Compatible Script Files
44
* GNU Free Documentation License::  GNU Free Documentation License
45
* LD Index::                       LD Index
46
 
47

48
File: ld.info,  Node: Overview,  Next: Invocation,  Prev: Top,  Up: Top
49
 
50
1 Overview
51
**********
52
 
53
`ld' combines a number of object and archive files, relocates their
54
data and ties up symbol references. Usually the last step in compiling
55
a program is to run `ld'.
56
 
57
   `ld' accepts Linker Command Language files written in a superset of
58
AT&T's Link Editor Command Language syntax, to provide explicit and
59
total control over the linking process.
60
 
61
   This version of `ld' uses the general purpose BFD libraries to
62
operate on object files. This allows `ld' to read, combine, and write
63
object files in many different formats--for example, COFF or `a.out'.
64
Different formats may be linked together to produce any available kind
65
of object file.  *Note BFD::, for more information.
66
 
67
   Aside from its flexibility, the GNU linker is more helpful than other
68
linkers in providing diagnostic information.  Many linkers abandon
69
execution immediately upon encountering an error; whenever possible,
70
`ld' continues executing, allowing you to identify other errors (or, in
71
some cases, to get an output file in spite of the error).
72
 
73

74
File: ld.info,  Node: Invocation,  Next: Scripts,  Prev: Overview,  Up: Top
75
 
76
2 Invocation
77
************
78
 
79
The GNU linker `ld' is meant to cover a broad range of situations, and
80
to be as compatible as possible with other linkers.  As a result, you
81
have many choices to control its behavior.
82
 
83
* Menu:
84
 
85
* Options::                     Command Line Options
86
* Environment::                 Environment Variables
87
 
88

89
File: ld.info,  Node: Options,  Next: Environment,  Up: Invocation
90
 
91
2.1 Command Line Options
92
========================
93
 
94
   The linker supports a plethora of command-line options, but in actual
95
practice few of them are used in any particular context.  For instance,
96
a frequent use of `ld' is to link standard Unix object files on a
97
standard, supported Unix system.  On such a system, to link a file
98
`hello.o':
99
 
100
     ld -o OUTPUT /lib/crt0.o hello.o -lc
101
 
102
   This tells `ld' to produce a file called OUTPUT as the result of
103
linking the file `/lib/crt0.o' with `hello.o' and the library `libc.a',
104
which will come from the standard search directories.  (See the
105
discussion of the `-l' option below.)
106
 
107
   Some of the command-line options to `ld' may be specified at any
108
point in the command line.  However, options which refer to files, such
109
as `-l' or `-T', cause the file to be read at the point at which the
110
option appears in the command line, relative to the object files and
111
other file options.  Repeating non-file options with a different
112
argument will either have no further effect, or override prior
113
occurrences (those further to the left on the command line) of that
114
option.  Options which may be meaningfully specified more than once are
115
noted in the descriptions below.
116
 
117
   Non-option arguments are object files or archives which are to be
118
linked together.  They may follow, precede, or be mixed in with
119
command-line options, except that an object file argument may not be
120
placed between an option and its argument.
121
 
122
   Usually the linker is invoked with at least one object file, but you
123
can specify other forms of binary input files using `-l', `-R', and the
124
script command language.  If _no_ binary input files at all are
125
specified, the linker does not produce any output, and issues the
126
message `No input files'.
127
 
128
   If the linker cannot recognize the format of an object file, it will
129
assume that it is a linker script.  A script specified in this way
130
augments the main linker script used for the link (either the default
131
linker script or the one specified by using `-T').  This feature
132
permits the linker to link against a file which appears to be an object
133
or an archive, but actually merely defines some symbol values, or uses
134
`INPUT' or `GROUP' to load other objects.  Specifying a script in this
135
way merely augments the main linker script, with the extra commands
136
placed after the main script; use the `-T' option to replace the
137
default linker script entirely, but note the effect of the `INSERT'
138
command.  *Note Scripts::.
139
 
140
   For options whose names are a single letter, option arguments must
141
either follow the option letter without intervening whitespace, or be
142
given as separate arguments immediately following the option that
143
requires them.
144
 
145
   For options whose names are multiple letters, either one dash or two
146
can precede the option name; for example, `-trace-symbol' and
147
`--trace-symbol' are equivalent.  Note--there is one exception to this
148
rule.  Multiple letter options that start with a lower case 'o' can
149
only be preceded by two dashes.  This is to reduce confusion with the
150
`-o' option.  So for example `-omagic' sets the output file name to
151
`magic' whereas `--omagic' sets the NMAGIC flag on the output.
152
 
153
   Arguments to multiple-letter options must either be separated from
154
the option name by an equals sign, or be given as separate arguments
155
immediately following the option that requires them.  For example,
156
`--trace-symbol foo' and `--trace-symbol=foo' are equivalent.  Unique
157
abbreviations of the names of multiple-letter options are accepted.
158
 
159
   Note--if the linker is being invoked indirectly, via a compiler
160
driver (e.g. `gcc') then all the linker command line options should be
161
prefixed by `-Wl,' (or whatever is appropriate for the particular
162
compiler driver) like this:
163
 
164
       gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
165
 
166
   This is important, because otherwise the compiler driver program may
167
silently drop the linker options, resulting in a bad link.  Confusion
168
may also arise when passing options that require values through a
169
driver, as the use of a space between option and argument acts as a
170
separator, and causes the driver to pass only the option to the linker
171
and the argument to the compiler.  In this case, it is simplest to use
172
the joined forms of both single- and multiple-letter options, such as:
173
 
174
       gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
175
 
176
   Here is a table of the generic command line switches accepted by the
177
GNU linker:
178
 
179
`@FILE'
180
     Read command-line options from FILE.  The options read are
181
     inserted in place of the original @FILE option.  If FILE does not
182
     exist, or cannot be read, then the option will be treated
183
     literally, and not removed.
184
 
185
     Options in FILE are separated by whitespace.  A whitespace
186
     character may be included in an option by surrounding the entire
187
     option in either single or double quotes.  Any character
188
     (including a backslash) may be included by prefixing the character
189
     to be included with a backslash.  The FILE may itself contain
190
     additional @FILE options; any such options will be processed
191
     recursively.
192
 
193
`-a KEYWORD'
194
     This option is supported for HP/UX compatibility.  The KEYWORD
195
     argument must be one of the strings `archive', `shared', or
196
     `default'.  `-aarchive' is functionally equivalent to `-Bstatic',
197
     and the other two keywords are functionally equivalent to
198
     `-Bdynamic'.  This option may be used any number of times.
199
 
200
`-A ARCHITECTURE'
201
`--architecture=ARCHITECTURE'
202
     In the current release of `ld', this option is useful only for the
203
     Intel 960 family of architectures.  In that `ld' configuration, the
204
     ARCHITECTURE argument identifies the particular architecture in
205
     the 960 family, enabling some safeguards and modifying the
206
     archive-library search path.  *Note `ld' and the Intel 960 family:
207
     i960, for details.
208
 
209
     Future releases of `ld' may support similar functionality for
210
     other architecture families.
211
 
212
`-b INPUT-FORMAT'
213
`--format=INPUT-FORMAT'
214
     `ld' may be configured to support more than one kind of object
215
     file.  If your `ld' is configured this way, you can use the `-b'
216
     option to specify the binary format for input object files that
217
     follow this option on the command line.  Even when `ld' is
218
     configured to support alternative object formats, you don't
219
     usually need to specify this, as `ld' should be configured to
220
     expect as a default input format the most usual format on each
221
     machine.  INPUT-FORMAT is a text string, the name of a particular
222
     format supported by the BFD libraries.  (You can list the
223
     available binary formats with `objdump -i'.)  *Note BFD::.
224
 
225
     You may want to use this option if you are linking files with an
226
     unusual binary format.  You can also use `-b' to switch formats
227
     explicitly (when linking object files of different formats), by
228
     including `-b INPUT-FORMAT' before each group of object files in a
229
     particular format.
230
 
231
     The default format is taken from the environment variable
232
     `GNUTARGET'.  *Note Environment::.  You can also define the input
233
     format from a script, using the command `TARGET'; see *Note Format
234
     Commands::.
235
 
236
`-c MRI-COMMANDFILE'
237
`--mri-script=MRI-COMMANDFILE'
238
     For compatibility with linkers produced by MRI, `ld' accepts script
239
     files written in an alternate, restricted command language,
240
     described in *Note MRI Compatible Script Files: MRI.  Introduce
241
     MRI script files with the option `-c'; use the `-T' option to run
242
     linker scripts written in the general-purpose `ld' scripting
243
     language.  If MRI-CMDFILE does not exist, `ld' looks for it in the
244
     directories specified by any `-L' options.
245
 
246
`-d'
247
`-dc'
248
`-dp'
249
     These three options are equivalent; multiple forms are supported
250
     for compatibility with other linkers.  They assign space to common
251
     symbols even if a relocatable output file is specified (with
252
     `-r').  The script command `FORCE_COMMON_ALLOCATION' has the same
253
     effect.  *Note Miscellaneous Commands::.
254
 
255
`-e ENTRY'
256
`--entry=ENTRY'
257
     Use ENTRY as the explicit symbol for beginning execution of your
258
     program, rather than the default entry point.  If there is no
259
     symbol named ENTRY, the linker will try to parse ENTRY as a number,
260
     and use that as the entry address (the number will be interpreted
261
     in base 10; you may use a leading `0x' for base 16, or a leading
262
     `0' for base 8).  *Note Entry Point::, for a discussion of defaults
263
     and other ways of specifying the entry point.
264
 
265
`--exclude-libs LIB,LIB,...'
266
     Specifies a list of archive libraries from which symbols should
267
     not be automatically exported.  The library names may be delimited
268
     by commas or colons.  Specifying `--exclude-libs ALL' excludes
269
     symbols in all archive libraries from automatic export.  This
270
     option is available only for the i386 PE targeted port of the
271
     linker and for ELF targeted ports.  For i386 PE, symbols
272
     explicitly listed in a .def file are still exported, regardless of
273
     this option.  For ELF targeted ports, symbols affected by this
274
     option will be treated as hidden.
275
 
276
`--exclude-modules-for-implib MODULE,MODULE,...'
277
     Specifies a list of object files or archive members, from which
278
     symbols should not be automatically exported, but which should be
279
     copied wholesale into the import library being generated during
280
     the link.  The module names may be delimited by commas or colons,
281
     and must match exactly the filenames used by `ld' to open the
282
     files; for archive members, this is simply the member name, but
283
     for object files the name listed must include and match precisely
284
     any path used to specify the input file on the linker's
285
     command-line.  This option is available only for the i386 PE
286
     targeted port of the linker.  Symbols explicitly listed in a .def
287
     file are still exported, regardless of this option.
288
 
289
`-E'
290
`--export-dynamic'
291
`--no-export-dynamic'
292
     When creating a dynamically linked executable, using the `-E'
293
     option or the `--export-dynamic' option causes the linker to add
294
     all symbols to the dynamic symbol table.  The dynamic symbol table
295
     is the set of symbols which are visible from dynamic objects at
296
     run time.
297
 
298
     If you do not use either of these options (or use the
299
     `--no-export-dynamic' option to restore the default behavior), the
300
     dynamic symbol table will normally contain only those symbols
301
     which are referenced by some dynamic object mentioned in the link.
302
 
303
     If you use `dlopen' to load a dynamic object which needs to refer
304
     back to the symbols defined by the program, rather than some other
305
     dynamic object, then you will probably need to use this option when
306
     linking the program itself.
307
 
308
     You can also use the dynamic list to control what symbols should
309
     be added to the dynamic symbol table if the output format supports
310
     it.  See the description of `--dynamic-list'.
311
 
312
     Note that this option is specific to ELF targeted ports.  PE
313
     targets support a similar function to export all symbols from a
314
     DLL or EXE; see the description of `--export-all-symbols' below.
315
 
316
`-EB'
317
     Link big-endian objects.  This affects the default output format.
318
 
319
`-EL'
320
     Link little-endian objects.  This affects the default output
321
     format.
322
 
323
`-f NAME'
324
`--auxiliary=NAME'
325
     When creating an ELF shared object, set the internal DT_AUXILIARY
326
     field to the specified name.  This tells the dynamic linker that
327
     the symbol table of the shared object should be used as an
328
     auxiliary filter on the symbol table of the shared object NAME.
329
 
330
     If you later link a program against this filter object, then, when
331
     you run the program, the dynamic linker will see the DT_AUXILIARY
332
     field.  If the dynamic linker resolves any symbols from the filter
333
     object, it will first check whether there is a definition in the
334
     shared object NAME.  If there is one, it will be used instead of
335
     the definition in the filter object.  The shared object NAME need
336
     not exist.  Thus the shared object NAME may be used to provide an
337
     alternative implementation of certain functions, perhaps for
338
     debugging or for machine specific performance.
339
 
340
     This option may be specified more than once.  The DT_AUXILIARY
341
     entries will be created in the order in which they appear on the
342
     command line.
343
 
344
`-F NAME'
345
`--filter=NAME'
346
     When creating an ELF shared object, set the internal DT_FILTER
347
     field to the specified name.  This tells the dynamic linker that
348
     the symbol table of the shared object which is being created
349
     should be used as a filter on the symbol table of the shared
350
     object NAME.
351
 
352
     If you later link a program against this filter object, then, when
353
     you run the program, the dynamic linker will see the DT_FILTER
354
     field.  The dynamic linker will resolve symbols according to the
355
     symbol table of the filter object as usual, but it will actually
356
     link to the definitions found in the shared object NAME.  Thus the
357
     filter object can be used to select a subset of the symbols
358
     provided by the object NAME.
359
 
360
     Some older linkers used the `-F' option throughout a compilation
361
     toolchain for specifying object-file format for both input and
362
     output object files.  The GNU linker uses other mechanisms for
363
     this purpose: the `-b', `--format', `--oformat' options, the
364
     `TARGET' command in linker scripts, and the `GNUTARGET'
365
     environment variable.  The GNU linker will ignore the `-F' option
366
     when not creating an ELF shared object.
367
 
368
`-fini=NAME'
369
     When creating an ELF executable or shared object, call NAME when
370
     the executable or shared object is unloaded, by setting DT_FINI to
371
     the address of the function.  By default, the linker uses `_fini'
372
     as the function to call.
373
 
374
`-g'
375
     Ignored.  Provided for compatibility with other tools.
376
 
377
`-G VALUE'
378
`--gpsize=VALUE'
379
     Set the maximum size of objects to be optimized using the GP
380
     register to SIZE.  This is only meaningful for object file formats
381
     such as MIPS ECOFF which supports putting large and small objects
382
     into different sections.  This is ignored for other object file
383
     formats.
384
 
385
`-h NAME'
386
`-soname=NAME'
387
     When creating an ELF shared object, set the internal DT_SONAME
388
     field to the specified name.  When an executable is linked with a
389
     shared object which has a DT_SONAME field, then when the
390
     executable is run the dynamic linker will attempt to load the
391
     shared object specified by the DT_SONAME field rather than the
392
     using the file name given to the linker.
393
 
394
`-i'
395
     Perform an incremental link (same as option `-r').
396
 
397
`-init=NAME'
398
     When creating an ELF executable or shared object, call NAME when
399
     the executable or shared object is loaded, by setting DT_INIT to
400
     the address of the function.  By default, the linker uses `_init'
401
     as the function to call.
402
 
403
`-l NAMESPEC'
404
`--library=NAMESPEC'
405
     Add the archive or object file specified by NAMESPEC to the list
406
     of files to link.  This option may be used any number of times.
407
     If NAMESPEC is of the form `:FILENAME', `ld' will search the
408
     library path for a file called FILENAME, otherwise it will search
409
     the library path for a file called `libNAMESPEC.a'.
410
 
411
     On systems which support shared libraries, `ld' may also search for
412
     files other than `libNAMESPEC.a'.  Specifically, on ELF and SunOS
413
     systems, `ld' will search a directory for a library called
414
     `libNAMESPEC.so' before searching for one called `libNAMESPEC.a'.
415
     (By convention, a `.so' extension indicates a shared library.)
416
     Note that this behavior does not apply to `:FILENAME', which
417
     always specifies a file called FILENAME.
418
 
419
     The linker will search an archive only once, at the location where
420
     it is specified on the command line.  If the archive defines a
421
     symbol which was undefined in some object which appeared before
422
     the archive on the command line, the linker will include the
423
     appropriate file(s) from the archive.  However, an undefined
424
     symbol in an object appearing later on the command line will not
425
     cause the linker to search the archive again.
426
 
427
     See the `-(' option for a way to force the linker to search
428
     archives multiple times.
429
 
430
     You may list the same archive multiple times on the command line.
431
 
432
     This type of archive searching is standard for Unix linkers.
433
     However, if you are using `ld' on AIX, note that it is different
434
     from the behaviour of the AIX linker.
435
 
436
`-L SEARCHDIR'
437
`--library-path=SEARCHDIR'
438
     Add path SEARCHDIR to the list of paths that `ld' will search for
439
     archive libraries and `ld' control scripts.  You may use this
440
     option any number of times.  The directories are searched in the
441
     order in which they are specified on the command line.
442
     Directories specified on the command line are searched before the
443
     default directories.  All `-L' options apply to all `-l' options,
444
     regardless of the order in which the options appear.  `-L' options
445
     do not affect how `ld' searches for a linker script unless `-T'
446
     option is specified.
447
 
448
     If SEARCHDIR begins with `=', then the `=' will be replaced by the
449
     "sysroot prefix", a path specified when the linker is configured.
450
 
451
     The default set of paths searched (without being specified with
452
     `-L') depends on which emulation mode `ld' is using, and in some
453
     cases also on how it was configured.  *Note Environment::.
454
 
455
     The paths can also be specified in a link script with the
456
     `SEARCH_DIR' command.  Directories specified this way are searched
457
     at the point in which the linker script appears in the command
458
     line.
459
 
460
`-m EMULATION'
461
     Emulate the EMULATION linker.  You can list the available
462
     emulations with the `--verbose' or `-V' options.
463
 
464
     If the `-m' option is not used, the emulation is taken from the
465
     `LDEMULATION' environment variable, if that is defined.
466
 
467
     Otherwise, the default emulation depends upon how the linker was
468
     configured.
469
 
470
`-M'
471
`--print-map'
472
     Print a link map to the standard output.  A link map provides
473
     information about the link, including the following:
474
 
475
        * Where object files are mapped into memory.
476
 
477
        * How common symbols are allocated.
478
 
479
        * All archive members included in the link, with a mention of
480
          the symbol which caused the archive member to be brought in.
481
 
482
        * The values assigned to symbols.
483
 
484
          Note - symbols whose values are computed by an expression
485
          which involves a reference to a previous value of the same
486
          symbol may not have correct result displayed in the link map.
487
          This is because the linker discards intermediate results and
488
          only retains the final value of an expression.  Under such
489
          circumstances the linker will display the final value
490
          enclosed by square brackets.  Thus for example a linker
491
          script containing:
492
 
493
                  foo = 1
494
                  foo = foo * 4
495
                  foo = foo + 8
496
 
497
          will produce the following output in the link map if the `-M'
498
          option is used:
499
 
500
                  0x00000001                foo = 0x1
501
                  [0x0000000c]                foo = (foo * 0x4)
502
                  [0x0000000c]                foo = (foo + 0x8)
503
 
504
          See *Note Expressions:: for more information about
505
          expressions in linker scripts.
506
 
507
`-n'
508
`--nmagic'
509
     Turn off page alignment of sections, and mark the output as
510
     `NMAGIC' if possible.
511
 
512
`-N'
513
`--omagic'
514
     Set the text and data sections to be readable and writable.  Also,
515
     do not page-align the data segment, and disable linking against
516
     shared libraries.  If the output format supports Unix style magic
517
     numbers, mark the output as `OMAGIC'. Note: Although a writable
518
     text section is allowed for PE-COFF targets, it does not conform
519
     to the format specification published by Microsoft.
520
 
521
`--no-omagic'
522
     This option negates most of the effects of the `-N' option.  It
523
     sets the text section to be read-only, and forces the data segment
524
     to be page-aligned.  Note - this option does not enable linking
525
     against shared libraries.  Use `-Bdynamic' for this.
526
 
527
`-o OUTPUT'
528
`--output=OUTPUT'
529
     Use OUTPUT as the name for the program produced by `ld'; if this
530
     option is not specified, the name `a.out' is used by default.  The
531
     script command `OUTPUT' can also specify the output file name.
532
 
533
`-O LEVEL'
534
     If LEVEL is a numeric values greater than zero `ld' optimizes the
535
     output.  This might take significantly longer and therefore
536
     probably should only be enabled for the final binary.  At the
537
     moment this option only affects ELF shared library generation.
538
     Future releases of the linker may make more use of this option.
539
     Also currently there is no difference in the linker's behaviour
540
     for different non-zero values of this option.  Again this may
541
     change with future releases.
542
 
543
`-q'
544
`--emit-relocs'
545
     Leave relocation sections and contents in fully linked executables.
546
     Post link analysis and optimization tools may need this
547
     information in order to perform correct modifications of
548
     executables.  This results in larger executables.
549
 
550
     This option is currently only supported on ELF platforms.
551
 
552
`--force-dynamic'
553
     Force the output file to have dynamic sections.  This option is
554
     specific to VxWorks targets.
555
 
556
`-r'
557
`--relocatable'
558
     Generate relocatable output--i.e., generate an output file that
559
     can in turn serve as input to `ld'.  This is often called "partial
560
     linking".  As a side effect, in environments that support standard
561
     Unix magic numbers, this option also sets the output file's magic
562
     number to `OMAGIC'.  If this option is not specified, an absolute
563
     file is produced.  When linking C++ programs, this option _will
564
     not_ resolve references to constructors; to do that, use `-Ur'.
565
 
566
     When an input file does not have the same format as the output
567
     file, partial linking is only supported if that input file does
568
     not contain any relocations.  Different output formats can have
569
     further restrictions; for example some `a.out'-based formats do
570
     not support partial linking with input files in other formats at
571
     all.
572
 
573
     This option does the same thing as `-i'.
574
 
575
`-R FILENAME'
576
`--just-symbols=FILENAME'
577
     Read symbol names and their addresses from FILENAME, but do not
578
     relocate it or include it in the output.  This allows your output
579
     file to refer symbolically to absolute locations of memory defined
580
     in other programs.  You may use this option more than once.
581
 
582
     For compatibility with other ELF linkers, if the `-R' option is
583
     followed by a directory name, rather than a file name, it is
584
     treated as the `-rpath' option.
585
 
586
`-s'
587
`--strip-all'
588
     Omit all symbol information from the output file.
589
 
590
`-S'
591
`--strip-debug'
592
     Omit debugger symbol information (but not all symbols) from the
593
     output file.
594
 
595
`-t'
596
`--trace'
597
     Print the names of the input files as `ld' processes them.
598
 
599
`-T SCRIPTFILE'
600
`--script=SCRIPTFILE'
601
     Use SCRIPTFILE as the linker script.  This script replaces `ld''s
602
     default linker script (rather than adding to it), so COMMANDFILE
603
     must specify everything necessary to describe the output file.
604
     *Note Scripts::.  If SCRIPTFILE does not exist in the current
605
     directory, `ld' looks for it in the directories specified by any
606
     preceding `-L' options.  Multiple `-T' options accumulate.
607
 
608
`-dT SCRIPTFILE'
609
`--default-script=SCRIPTFILE'
610
     Use SCRIPTFILE as the default linker script.  *Note Scripts::.
611
 
612
     This option is similar to the `--script' option except that
613
     processing of the script is delayed until after the rest of the
614
     command line has been processed.  This allows options placed after
615
     the `--default-script' option on the command line to affect the
616
     behaviour of the linker script, which can be important when the
617
     linker command line cannot be directly controlled by the user.
618
     (eg because the command line is being constructed by another tool,
619
     such as `gcc').
620
 
621
`-u SYMBOL'
622
`--undefined=SYMBOL'
623
     Force SYMBOL to be entered in the output file as an undefined
624
     symbol.  Doing this may, for example, trigger linking of additional
625
     modules from standard libraries.  `-u' may be repeated with
626
     different option arguments to enter additional undefined symbols.
627
     This option is equivalent to the `EXTERN' linker script command.
628
 
629
`-Ur'
630
     For anything other than C++ programs, this option is equivalent to
631
     `-r': it generates relocatable output--i.e., an output file that
632
     can in turn serve as input to `ld'.  When linking C++ programs,
633
     `-Ur' _does_ resolve references to constructors, unlike `-r'.  It
634
     does not work to use `-Ur' on files that were themselves linked
635
     with `-Ur'; once the constructor table has been built, it cannot
636
     be added to.  Use `-Ur' only for the last partial link, and `-r'
637
     for the others.
638
 
639
`--unique[=SECTION]'
640
     Creates a separate output section for every input section matching
641
     SECTION, or if the optional wildcard SECTION argument is missing,
642
     for every orphan input section.  An orphan section is one not
643
     specifically mentioned in a linker script.  You may use this option
644
     multiple times on the command line;  It prevents the normal
645
     merging of input sections with the same name, overriding output
646
     section assignments in a linker script.
647
 
648
`-v'
649
`--version'
650
`-V'
651
     Display the version number for `ld'.  The `-V' option also lists
652
     the supported emulations.
653
 
654
`-x'
655
`--discard-all'
656
     Delete all local symbols.
657
 
658
`-X'
659
`--discard-locals'
660
     Delete all temporary local symbols.  (These symbols start with
661
     system-specific local label prefixes, typically `.L' for ELF
662
     systems or `L' for traditional a.out systems.)
663
 
664
`-y SYMBOL'
665
`--trace-symbol=SYMBOL'
666
     Print the name of each linked file in which SYMBOL appears.  This
667
     option may be given any number of times.  On many systems it is
668
     necessary to prepend an underscore.
669
 
670
     This option is useful when you have an undefined symbol in your
671
     link but don't know where the reference is coming from.
672
 
673
`-Y PATH'
674
     Add PATH to the default library search path.  This option exists
675
     for Solaris compatibility.
676
 
677
`-z KEYWORD'
678
     The recognized keywords are:
679
    `combreloc'
680
          Combines multiple reloc sections and sorts them to make
681
          dynamic symbol lookup caching possible.
682
 
683
    `defs'
684
          Disallows undefined symbols in object files.  Undefined
685
          symbols in shared libraries are still allowed.
686
 
687
    `execstack'
688
          Marks the object as requiring executable stack.
689
 
690
    `initfirst'
691
          This option is only meaningful when building a shared object.
692
          It marks the object so that its runtime initialization will
693
          occur before the runtime initialization of any other objects
694
          brought into the process at the same time.  Similarly the
695
          runtime finalization of the object will occur after the
696
          runtime finalization of any other objects.
697
 
698
    `interpose'
699
          Marks the object that its symbol table interposes before all
700
          symbols but the primary executable.
701
 
702
    `lazy'
703
          When generating an executable or shared library, mark it to
704
          tell the dynamic linker to defer function call resolution to
705
          the point when the function is called (lazy binding), rather
706
          than at load time.  Lazy binding is the default.
707
 
708
    `loadfltr'
709
          Marks  the object that its filters be processed immediately at
710
          runtime.
711
 
712
    `muldefs'
713
          Allows multiple definitions.
714
 
715
    `nocombreloc'
716
          Disables multiple reloc sections combining.
717
 
718
    `nocopyreloc'
719
          Disables production of copy relocs.
720
 
721
    `nodefaultlib'
722
          Marks the object that the search for dependencies of this
723
          object will ignore any default library search paths.
724
 
725
    `nodelete'
726
          Marks the object shouldn't be unloaded at runtime.
727
 
728
    `nodlopen'
729
          Marks the object not available to `dlopen'.
730
 
731
    `nodump'
732
          Marks the object can not be dumped by `dldump'.
733
 
734
    `noexecstack'
735
          Marks the object as not requiring executable stack.
736
 
737
    `norelro'
738
          Don't create an ELF `PT_GNU_RELRO' segment header in the
739
          object.
740
 
741
    `now'
742
          When generating an executable or shared library, mark it to
743
          tell the dynamic linker to resolve all symbols when the
744
          program is started, or when the shared library is linked to
745
          using dlopen, instead of deferring function call resolution
746
          to the point when the function is first called.
747
 
748
    `origin'
749
          Marks the object may contain $ORIGIN.
750
 
751
    `relro'
752
          Create an ELF `PT_GNU_RELRO' segment header in the object.
753
 
754
    `max-page-size=VALUE'
755
          Set the emulation maximum page size to VALUE.
756
 
757
    `common-page-size=VALUE'
758
          Set the emulation common page size to VALUE.
759
 
760
 
761
     Other keywords are ignored for Solaris compatibility.
762
 
763
`-( ARCHIVES -)'
764
`--start-group ARCHIVES --end-group'
765
     The ARCHIVES should be a list of archive files.  They may be
766
     either explicit file names, or `-l' options.
767
 
768
     The specified archives are searched repeatedly until no new
769
     undefined references are created.  Normally, an archive is
770
     searched only once in the order that it is specified on the
771
     command line.  If a symbol in that archive is needed to resolve an
772
     undefined symbol referred to by an object in an archive that
773
     appears later on the command line, the linker would not be able to
774
     resolve that reference.  By grouping the archives, they all be
775
     searched repeatedly until all possible references are resolved.
776
 
777
     Using this option has a significant performance cost.  It is best
778
     to use it only when there are unavoidable circular references
779
     between two or more archives.
780
 
781
`--accept-unknown-input-arch'
782
`--no-accept-unknown-input-arch'
783
     Tells the linker to accept input files whose architecture cannot be
784
     recognised.  The assumption is that the user knows what they are
785
     doing and deliberately wants to link in these unknown input files.
786
     This was the default behaviour of the linker, before release
787
     2.14.  The default behaviour from release 2.14 onwards is to
788
     reject such input files, and so the `--accept-unknown-input-arch'
789
     option has been added to restore the old behaviour.
790
 
791
`--as-needed'
792
`--no-as-needed'
793
     This option affects ELF DT_NEEDED tags for dynamic libraries
794
     mentioned on the command line after the `--as-needed' option.
795
     Normally, the linker will add a DT_NEEDED tag for each dynamic
796
     library mentioned on the command line, regardless of whether the
797
     library is actually needed.  `--as-needed' causes a DT_NEEDED tag
798
     to only be emitted for a library that satisfies a symbol reference
799
     from regular objects which is undefined at the point that the
800
     library was linked, or, if the library is not found in the
801
     DT_NEEDED lists of other libraries linked up to that point, a
802
     reference from another dynamic library.  `--no-as-needed' restores
803
     the default behaviour.
804
 
805
`--add-needed'
806
`--no-add-needed'
807
     This option affects the treatment of dynamic libraries from ELF
808
     DT_NEEDED tags in dynamic libraries mentioned on the command line
809
     after the `--no-add-needed' option.  Normally, the linker will add
810
     a DT_NEEDED tag for each dynamic library from DT_NEEDED tags.
811
     `--no-add-needed' causes DT_NEEDED tags will never be emitted for
812
     those libraries from DT_NEEDED tags. `--add-needed' restores the
813
     default behaviour.
814
 
815
`-assert KEYWORD'
816
     This option is ignored for SunOS compatibility.
817
 
818
`-Bdynamic'
819
`-dy'
820
`-call_shared'
821
     Link against dynamic libraries.  This is only meaningful on
822
     platforms for which shared libraries are supported.  This option
823
     is normally the default on such platforms.  The different variants
824
     of this option are for compatibility with various systems.  You
825
     may use this option multiple times on the command line: it affects
826
     library searching for `-l' options which follow it.
827
 
828
`-Bgroup'
829
     Set the `DF_1_GROUP' flag in the `DT_FLAGS_1' entry in the dynamic
830
     section.  This causes the runtime linker to handle lookups in this
831
     object and its dependencies to be performed only inside the group.
832
     `--unresolved-symbols=report-all' is implied.  This option is only
833
     meaningful on ELF platforms which support shared libraries.
834
 
835
`-Bstatic'
836
`-dn'
837
`-non_shared'
838
`-static'
839
     Do not link against shared libraries.  This is only meaningful on
840
     platforms for which shared libraries are supported.  The different
841
     variants of this option are for compatibility with various
842
     systems.  You may use this option multiple times on the command
843
     line: it affects library searching for `-l' options which follow
844
     it.  This option also implies `--unresolved-symbols=report-all'.
845
     This option can be used with `-shared'.  Doing so means that a
846
     shared library is being created but that all of the library's
847
     external references must be resolved by pulling in entries from
848
     static libraries.
849
 
850
`-Bsymbolic'
851
     When creating a shared library, bind references to global symbols
852
     to the definition within the shared library, if any.  Normally, it
853
     is possible for a program linked against a shared library to
854
     override the definition within the shared library.  This option is
855
     only meaningful on ELF platforms which support shared libraries.
856
 
857
`-Bsymbolic-functions'
858
     When creating a shared library, bind references to global function
859
     symbols to the definition within the shared library, if any.  This
860
     option is only meaningful on ELF platforms which support shared
861
     libraries.
862
 
863
`--dynamic-list=DYNAMIC-LIST-FILE'
864
     Specify the name of a dynamic list file to the linker.  This is
865
     typically used when creating shared libraries to specify a list of
866
     global symbols whose references shouldn't be bound to the
867
     definition within the shared library, or creating dynamically
868
     linked executables to specify a list of symbols which should be
869
     added to the symbol table in the executable.  This option is only
870
     meaningful on ELF platforms which support shared libraries.
871
 
872
     The format of the dynamic list is the same as the version node
873
     without scope and node name.  See *Note VERSION:: for more
874
     information.
875
 
876
`--dynamic-list-data'
877
     Include all global data symbols to the dynamic list.
878
 
879
`--dynamic-list-cpp-new'
880
     Provide the builtin dynamic list for C++ operator new and delete.
881
     It is mainly useful for building shared libstdc++.
882
 
883
`--dynamic-list-cpp-typeinfo'
884
     Provide the builtin dynamic list for C++ runtime type
885
     identification.
886
 
887
`--check-sections'
888
`--no-check-sections'
889
     Asks the linker _not_ to check section addresses after they have
890
     been assigned to see if there are any overlaps.  Normally the
891
     linker will perform this check, and if it finds any overlaps it
892
     will produce suitable error messages.  The linker does know about,
893
     and does make allowances for sections in overlays.  The default
894
     behaviour can be restored by using the command line switch
895
     `--check-sections'.  Section overlap is not usually checked for
896
     relocatable links.  You can force checking in that case by using
897
     the `--check-sections' option.
898
 
899
`--cref'
900
     Output a cross reference table.  If a linker map file is being
901
     generated, the cross reference table is printed to the map file.
902
     Otherwise, it is printed on the standard output.
903
 
904
     The format of the table is intentionally simple, so that it may be
905
     easily processed by a script if necessary.  The symbols are
906
     printed out, sorted by name.  For each symbol, a list of file
907
     names is given.  If the symbol is defined, the first file listed
908
     is the location of the definition.  The remaining files contain
909
     references to the symbol.
910
 
911
`--no-define-common'
912
     This option inhibits the assignment of addresses to common symbols.
913
     The script command `INHIBIT_COMMON_ALLOCATION' has the same effect.
914
     *Note Miscellaneous Commands::.
915
 
916
     The `--no-define-common' option allows decoupling the decision to
917
     assign addresses to Common symbols from the choice of the output
918
     file type; otherwise a non-Relocatable output type forces
919
     assigning addresses to Common symbols.  Using `--no-define-common'
920
     allows Common symbols that are referenced from a shared library to
921
     be assigned addresses only in the main program.  This eliminates
922
     the unused duplicate space in the shared library, and also
923
     prevents any possible confusion over resolving to the wrong
924
     duplicate when there are many dynamic modules with specialized
925
     search paths for runtime symbol resolution.
926
 
927
`--defsym=SYMBOL=EXPRESSION'
928
     Create a global symbol in the output file, containing the absolute
929
     address given by EXPRESSION.  You may use this option as many
930
     times as necessary to define multiple symbols in the command line.
931
     A limited form of arithmetic is supported for the EXPRESSION in
932
     this context: you may give a hexadecimal constant or the name of
933
     an existing symbol, or use `+' and `-' to add or subtract
934
     hexadecimal constants or symbols.  If you need more elaborate
935
     expressions, consider using the linker command language from a
936
     script (*note Assignment: Symbol Definitions: Assignments.).
937
     _Note:_ there should be no white space between SYMBOL, the equals
938
     sign ("<=>"), and EXPRESSION.
939
 
940
`--demangle[=STYLE]'
941
`--no-demangle'
942
     These options control whether to demangle symbol names in error
943
     messages and other output.  When the linker is told to demangle,
944
     it tries to present symbol names in a readable fashion: it strips
945
     leading underscores if they are used by the object file format,
946
     and converts C++ mangled symbol names into user readable names.
947
     Different compilers have different mangling styles.  The optional
948
     demangling style argument can be used to choose an appropriate
949
     demangling style for your compiler.  The linker will demangle by
950
     default unless the environment variable `COLLECT_NO_DEMANGLE' is
951
     set.  These options may be used to override the default.
952
 
953
`-IFILE'
954
`--dynamic-linker=FILE'
955
     Set the name of the dynamic linker.  This is only meaningful when
956
     generating dynamically linked ELF executables.  The default dynamic
957
     linker is normally correct; don't use this unless you know what
958
     you are doing.
959
 
960
`--fatal-warnings'
961
`--no-fatal-warnings'
962
     Treat all warnings as errors.  The default behaviour can be
963
     restored with the option `--no-fatal-warnings'.
964
 
965
`--force-exe-suffix'
966
     Make sure that an output file has a .exe suffix.
967
 
968
     If a successfully built fully linked output file does not have a
969
     `.exe' or `.dll' suffix, this option forces the linker to copy the
970
     output file to one of the same name with a `.exe' suffix. This
971
     option is useful when using unmodified Unix makefiles on a
972
     Microsoft Windows host, since some versions of Windows won't run
973
     an image unless it ends in a `.exe' suffix.
974
 
975
`--gc-sections'
976
`--no-gc-sections'
977
     Enable garbage collection of unused input sections.  It is ignored
978
     on targets that do not support this option.  The default behaviour
979
     (of not performing this garbage collection) can be restored by
980
     specifying `--no-gc-sections' on the command line.
981
 
982
     `--gc-sections' decides which input sections are used by examining
983
     symbols and relocations.  The section containing the entry symbol
984
     and all sections containing symbols undefined on the command-line
985
     will be kept, as will sections containing symbols referenced by
986
     dynamic objects.  Note that when building shared libraries, the
987
     linker must assume that any visible symbol is referenced.  Once
988
     this initial set of sections has been determined, the linker
989
     recursively marks as used any section referenced by their
990
     relocations.  See `--entry' and `--undefined'.
991
 
992
     This option can be set when doing a partial link (enabled with
993
     option `-r').  In this case the root of symbols kept must be
994
     explicitely specified either by an `--entry' or `--undefined'
995
     option or by a `ENTRY' command in the linker script.
996
 
997
`--print-gc-sections'
998
`--no-print-gc-sections'
999
     List all sections removed by garbage collection.  The listing is
1000
     printed on stderr.  This option is only effective if garbage
1001
     collection has been enabled via the `--gc-sections') option.  The
1002
     default behaviour (of not listing the sections that are removed)
1003
     can be restored by specifying `--no-print-gc-sections' on the
1004
     command line.
1005
 
1006
`--help'
1007
     Print a summary of the command-line options on the standard output
1008
     and exit.
1009
 
1010
`--target-help'
1011
     Print a summary of all target specific options on the standard
1012
     output and exit.
1013
 
1014
`-Map=MAPFILE'
1015
     Print a link map to the file MAPFILE.  See the description of the
1016
     `-M' option, above.
1017
 
1018
`--no-keep-memory'
1019
     `ld' normally optimizes for speed over memory usage by caching the
1020
     symbol tables of input files in memory.  This option tells `ld' to
1021
     instead optimize for memory usage, by rereading the symbol tables
1022
     as necessary.  This may be required if `ld' runs out of memory
1023
     space while linking a large executable.
1024
 
1025
`--no-undefined'
1026
`-z defs'
1027
     Report unresolved symbol references from regular object files.
1028
     This is done even if the linker is creating a non-symbolic shared
1029
     library.  The switch `--[no-]allow-shlib-undefined' controls the
1030
     behaviour for reporting unresolved references found in shared
1031
     libraries being linked in.
1032
 
1033
`--allow-multiple-definition'
1034
`-z muldefs'
1035
     Normally when a symbol is defined multiple times, the linker will
1036
     report a fatal error. These options allow multiple definitions and
1037
     the first definition will be used.
1038
 
1039
`--allow-shlib-undefined'
1040
`--no-allow-shlib-undefined'
1041
     Allows or disallows undefined symbols in shared libraries.  This
1042
     switch is similar to `--no-undefined' except that it determines
1043
     the behaviour when the undefined symbols are in a shared library
1044
     rather than a regular object file.  It does not affect how
1045
     undefined symbols in regular object files are handled.
1046
 
1047
     The default behaviour is to report errors for any undefined symbols
1048
     referenced in shared libraries if the linker is being used to
1049
     create an executable, but to allow them if the linker is being
1050
     used to create a shared library.
1051
 
1052
     The reasons for allowing undefined symbol references in shared
1053
     libraries specified at link time are that:
1054
 
1055
        * A shared library specified at link time may not be the same
1056
          as the one that is available at load time, so the symbol
1057
          might actually be resolvable at load time.
1058
 
1059
        * There are some operating systems, eg BeOS and HPPA, where
1060
          undefined symbols in shared libraries are normal.
1061
 
1062
          The BeOS kernel for example patches shared libraries at load
1063
          time to select whichever function is most appropriate for the
1064
          current architecture.  This is used, for example, to
1065
          dynamically select an appropriate memset function.
1066
 
1067
`--no-undefined-version'
1068
     Normally when a symbol has an undefined version, the linker will
1069
     ignore it. This option disallows symbols with undefined version
1070
     and a fatal error will be issued instead.
1071
 
1072
`--default-symver'
1073
     Create and use a default symbol version (the soname) for
1074
     unversioned exported symbols.
1075
 
1076
`--default-imported-symver'
1077
     Create and use a default symbol version (the soname) for
1078
     unversioned imported symbols.
1079
 
1080
`--no-warn-mismatch'
1081
     Normally `ld' will give an error if you try to link together input
1082
     files that are mismatched for some reason, perhaps because they
1083
     have been compiled for different processors or for different
1084
     endiannesses.  This option tells `ld' that it should silently
1085
     permit such possible errors.  This option should only be used with
1086
     care, in cases when you have taken some special action that
1087
     ensures that the linker errors are inappropriate.
1088
 
1089
`--no-warn-search-mismatch'
1090
     Normally `ld' will give a warning if it finds an incompatible
1091
     library during a library search.  This option silences the warning.
1092
 
1093
`--no-whole-archive'
1094
     Turn off the effect of the `--whole-archive' option for subsequent
1095
     archive files.
1096
 
1097
`--noinhibit-exec'
1098
     Retain the executable output file whenever it is still usable.
1099
     Normally, the linker will not produce an output file if it
1100
     encounters errors during the link process; it exits without
1101
     writing an output file when it issues any error whatsoever.
1102
 
1103
`-nostdlib'
1104
     Only search library directories explicitly specified on the
1105
     command line.  Library directories specified in linker scripts
1106
     (including linker scripts specified on the command line) are
1107
     ignored.
1108
 
1109
`--oformat=OUTPUT-FORMAT'
1110
     `ld' may be configured to support more than one kind of object
1111
     file.  If your `ld' is configured this way, you can use the
1112
     `--oformat' option to specify the binary format for the output
1113
     object file.  Even when `ld' is configured to support alternative
1114
     object formats, you don't usually need to specify this, as `ld'
1115
     should be configured to produce as a default output format the most
1116
     usual format on each machine.  OUTPUT-FORMAT is a text string, the
1117
     name of a particular format supported by the BFD libraries.  (You
1118
     can list the available binary formats with `objdump -i'.)  The
1119
     script command `OUTPUT_FORMAT' can also specify the output format,
1120
     but this option overrides it.  *Note BFD::.
1121
 
1122
`-pie'
1123
`--pic-executable'
1124
     Create a position independent executable.  This is currently only
1125
     supported on ELF platforms.  Position independent executables are
1126
     similar to shared libraries in that they are relocated by the
1127
     dynamic linker to the virtual address the OS chooses for them
1128
     (which can vary between invocations).  Like normal dynamically
1129
     linked executables they can be executed and symbols defined in the
1130
     executable cannot be overridden by shared libraries.
1131
 
1132
`-qmagic'
1133
     This option is ignored for Linux compatibility.
1134
 
1135
`-Qy'
1136
     This option is ignored for SVR4 compatibility.
1137
 
1138
`--relax'
1139
     An option with machine dependent effects.  This option is only
1140
     supported on a few targets.  *Note `ld' and the H8/300: H8/300.
1141
     *Note `ld' and the Intel 960 family: i960.  *Note `ld' and Xtensa
1142
     Processors: Xtensa.  *Note `ld' and the 68HC11 and 68HC12:
1143
     M68HC11/68HC12.  *Note `ld' and PowerPC 32-bit ELF Support:
1144
     PowerPC ELF32.
1145
 
1146
     On some platforms, the `--relax' option performs global
1147
     optimizations that become possible when the linker resolves
1148
     addressing in the program, such as relaxing address modes and
1149
     synthesizing new instructions in the output object file.
1150
 
1151
     On some platforms these link time global optimizations may make
1152
     symbolic debugging of the resulting executable impossible.  This
1153
     is known to be the case for the Matsushita MN10200 and MN10300
1154
     family of processors.
1155
 
1156
     On platforms where this is not supported, `--relax' is accepted,
1157
     but ignored.
1158
 
1159
`--retain-symbols-file=FILENAME'
1160
     Retain _only_ the symbols listed in the file FILENAME, discarding
1161
     all others.  FILENAME is simply a flat file, with one symbol name
1162
     per line.  This option is especially useful in environments (such
1163
     as VxWorks) where a large global symbol table is accumulated
1164
     gradually, to conserve run-time memory.
1165
 
1166
     `--retain-symbols-file' does _not_ discard undefined symbols, or
1167
     symbols needed for relocations.
1168
 
1169
     You may only specify `--retain-symbols-file' once in the command
1170
     line.  It overrides `-s' and `-S'.
1171
 
1172
`-rpath=DIR'
1173
     Add a directory to the runtime library search path.  This is used
1174
     when linking an ELF executable with shared objects.  All `-rpath'
1175
     arguments are concatenated and passed to the runtime linker, which
1176
     uses them to locate shared objects at runtime.  The `-rpath'
1177
     option is also used when locating shared objects which are needed
1178
     by shared objects explicitly included in the link; see the
1179
     description of the `-rpath-link' option.  If `-rpath' is not used
1180
     when linking an ELF executable, the contents of the environment
1181
     variable `LD_RUN_PATH' will be used if it is defined.
1182
 
1183
     The `-rpath' option may also be used on SunOS.  By default, on
1184
     SunOS, the linker will form a runtime search patch out of all the
1185
     `-L' options it is given.  If a `-rpath' option is used, the
1186
     runtime search path will be formed exclusively using the `-rpath'
1187
     options, ignoring the `-L' options.  This can be useful when using
1188
     gcc, which adds many `-L' options which may be on NFS mounted file
1189
     systems.
1190
 
1191
     For compatibility with other ELF linkers, if the `-R' option is
1192
     followed by a directory name, rather than a file name, it is
1193
     treated as the `-rpath' option.
1194
 
1195
`-rpath-link=DIR'
1196
     When using ELF or SunOS, one shared library may require another.
1197
     This happens when an `ld -shared' link includes a shared library
1198
     as one of the input files.
1199
 
1200
     When the linker encounters such a dependency when doing a
1201
     non-shared, non-relocatable link, it will automatically try to
1202
     locate the required shared library and include it in the link, if
1203
     it is not included explicitly.  In such a case, the `-rpath-link'
1204
     option specifies the first set of directories to search.  The
1205
     `-rpath-link' option may specify a sequence of directory names
1206
     either by specifying a list of names separated by colons, or by
1207
     appearing multiple times.
1208
 
1209
     This option should be used with caution as it overrides the search
1210
     path that may have been hard compiled into a shared library. In
1211
     such a case it is possible to use unintentionally a different
1212
     search path than the runtime linker would do.
1213
 
1214
     The linker uses the following search paths to locate required
1215
     shared libraries:
1216
       1. Any directories specified by `-rpath-link' options.
1217
 
1218
       2. Any directories specified by `-rpath' options.  The difference
1219
          between `-rpath' and `-rpath-link' is that directories
1220
          specified by `-rpath' options are included in the executable
1221
          and used at runtime, whereas the `-rpath-link' option is only
1222
          effective at link time. Searching `-rpath' in this way is
1223
          only supported by native linkers and cross linkers which have
1224
          been configured with the `--with-sysroot' option.
1225
 
1226
       3. On an ELF system, for native linkers, if the `-rpath' and
1227
          `-rpath-link' options were not used, search the contents of
1228
          the environment variable `LD_RUN_PATH'.
1229
 
1230
       4. On SunOS, if the `-rpath' option was not used, search any
1231
          directories specified using `-L' options.
1232
 
1233
       5. For a native linker, the search the contents of the
1234
          environment variable `LD_LIBRARY_PATH'.
1235
 
1236
       6. For a native ELF linker, the directories in `DT_RUNPATH' or
1237
          `DT_RPATH' of a shared library are searched for shared
1238
          libraries needed by it. The `DT_RPATH' entries are ignored if
1239
          `DT_RUNPATH' entries exist.
1240
 
1241
       7. The default directories, normally `/lib' and `/usr/lib'.
1242
 
1243
       8. For a native linker on an ELF system, if the file
1244
          `/etc/ld.so.conf' exists, the list of directories found in
1245
          that file.
1246
 
1247
     If the required shared library is not found, the linker will issue
1248
     a warning and continue with the link.
1249
 
1250
`-shared'
1251
`-Bshareable'
1252
     Create a shared library.  This is currently only supported on ELF,
1253
     XCOFF and SunOS platforms.  On SunOS, the linker will
1254
     automatically create a shared library if the `-e' option is not
1255
     used and there are undefined symbols in the link.
1256
 
1257
`--sort-common'
1258
`--sort-common=ascending'
1259
`--sort-common=descending'
1260
     This option tells `ld' to sort the common symbols by alignment in
1261
     ascending or descending order when it places them in the
1262
     appropriate output sections.  The symbol alignments considered are
1263
     sixteen-byte or larger, eight-byte, four-byte, two-byte, and
1264
     one-byte. This is to prevent gaps between symbols due to alignment
1265
     constraints.  If no sorting order is specified, then descending
1266
     order is assumed.
1267
 
1268
`--sort-section=name'
1269
     This option will apply `SORT_BY_NAME' to all wildcard section
1270
     patterns in the linker script.
1271
 
1272
`--sort-section=alignment'
1273
     This option will apply `SORT_BY_ALIGNMENT' to all wildcard section
1274
     patterns in the linker script.
1275
 
1276
`--split-by-file[=SIZE]'
1277
     Similar to `--split-by-reloc' but creates a new output section for
1278
     each input file when SIZE is reached.  SIZE defaults to a size of
1279
     1 if not given.
1280
 
1281
`--split-by-reloc[=COUNT]'
1282
     Tries to creates extra sections in the output file so that no
1283
     single output section in the file contains more than COUNT
1284
     relocations.  This is useful when generating huge relocatable
1285
     files for downloading into certain real time kernels with the COFF
1286
     object file format; since COFF cannot represent more than 65535
1287
     relocations in a single section.  Note that this will fail to work
1288
     with object file formats which do not support arbitrary sections.
1289
     The linker will not split up individual input sections for
1290
     redistribution, so if a single input section contains more than
1291
     COUNT relocations one output section will contain that many
1292
     relocations.  COUNT defaults to a value of 32768.
1293
 
1294
`--stats'
1295
     Compute and display statistics about the operation of the linker,
1296
     such as execution time and memory usage.
1297
 
1298
`--sysroot=DIRECTORY'
1299
     Use DIRECTORY as the location of the sysroot, overriding the
1300
     configure-time default.  This option is only supported by linkers
1301
     that were configured using `--with-sysroot'.
1302
 
1303
`--traditional-format'
1304
     For some targets, the output of `ld' is different in some ways from
1305
     the output of some existing linker.  This switch requests `ld' to
1306
     use the traditional format instead.
1307
 
1308
     For example, on SunOS, `ld' combines duplicate entries in the
1309
     symbol string table.  This can reduce the size of an output file
1310
     with full debugging information by over 30 percent.
1311
     Unfortunately, the SunOS `dbx' program can not read the resulting
1312
     program (`gdb' has no trouble).  The `--traditional-format' switch
1313
     tells `ld' to not combine duplicate entries.
1314
 
1315
`--section-start=SECTIONNAME=ORG'
1316
     Locate a section in the output file at the absolute address given
1317
     by ORG.  You may use this option as many times as necessary to
1318
     locate multiple sections in the command line.  ORG must be a
1319
     single hexadecimal integer; for compatibility with other linkers,
1320
     you may omit the leading `0x' usually associated with hexadecimal
1321
     values.  _Note:_ there should be no white space between
1322
     SECTIONNAME, the equals sign ("<=>"), and ORG.
1323
 
1324
`-Tbss=ORG'
1325
`-Tdata=ORG'
1326
`-Ttext=ORG'
1327
     Same as `--section-start', with `.bss', `.data' or `.text' as the
1328
     SECTIONNAME.
1329
 
1330
`-Ttext-segment=ORG'
1331
     When creating an ELF executable or shared object, it will set the
1332
     address of the first byte of the text segment.
1333
 
1334
`--unresolved-symbols=METHOD'
1335
     Determine how to handle unresolved symbols.  There are four
1336
     possible values for `method':
1337
 
1338
    `ignore-all'
1339
          Do not report any unresolved symbols.
1340
 
1341
    `report-all'
1342
          Report all unresolved symbols.  This is the default.
1343
 
1344
    `ignore-in-object-files'
1345
          Report unresolved symbols that are contained in shared
1346
          libraries, but ignore them if they come from regular object
1347
          files.
1348
 
1349
    `ignore-in-shared-libs'
1350
          Report unresolved symbols that come from regular object
1351
          files, but ignore them if they come from shared libraries.
1352
          This can be useful when creating a dynamic binary and it is
1353
          known that all the shared libraries that it should be
1354
          referencing are included on the linker's command line.
1355
 
1356
     The behaviour for shared libraries on their own can also be
1357
     controlled by the `--[no-]allow-shlib-undefined' option.
1358
 
1359
     Normally the linker will generate an error message for each
1360
     reported unresolved symbol but the option
1361
     `--warn-unresolved-symbols' can change this to a warning.
1362
 
1363
`--dll-verbose'
1364
`--verbose'
1365
     Display the version number for `ld' and list the linker emulations
1366
     supported.  Display which input files can and cannot be opened.
1367
     Display the linker script being used by the linker.
1368
 
1369
`--version-script=VERSION-SCRIPTFILE'
1370
     Specify the name of a version script to the linker.  This is
1371
     typically used when creating shared libraries to specify
1372
     additional information about the version hierarchy for the library
1373
     being created.  This option is only fully supported on ELF
1374
     platforms which support shared libraries; see *Note VERSION::.  It
1375
     is partially supported on PE platforms, which can use version
1376
     scripts to filter symbol visibility in auto-export mode: any
1377
     symbols marked `local' in the version script will not be exported.
1378
     *Note WIN32::.
1379
 
1380
`--warn-common'
1381
     Warn when a common symbol is combined with another common symbol
1382
     or with a symbol definition.  Unix linkers allow this somewhat
1383
     sloppy practise, but linkers on some other operating systems do
1384
     not.  This option allows you to find potential problems from
1385
     combining global symbols.  Unfortunately, some C libraries use
1386
     this practise, so you may get some warnings about symbols in the
1387
     libraries as well as in your programs.
1388
 
1389
     There are three kinds of global symbols, illustrated here by C
1390
     examples:
1391
 
1392
    `int i = 1;'
1393
          A definition, which goes in the initialized data section of
1394
          the output file.
1395
 
1396
    `extern int i;'
1397
          An undefined reference, which does not allocate space.  There
1398
          must be either a definition or a common symbol for the
1399
          variable somewhere.
1400
 
1401
    `int i;'
1402
          A common symbol.  If there are only (one or more) common
1403
          symbols for a variable, it goes in the uninitialized data
1404
          area of the output file.  The linker merges multiple common
1405
          symbols for the same variable into a single symbol.  If they
1406
          are of different sizes, it picks the largest size.  The
1407
          linker turns a common symbol into a declaration, if there is
1408
          a definition of the same variable.
1409
 
1410
     The `--warn-common' option can produce five kinds of warnings.
1411
     Each warning consists of a pair of lines: the first describes the
1412
     symbol just encountered, and the second describes the previous
1413
     symbol encountered with the same name.  One or both of the two
1414
     symbols will be a common symbol.
1415
 
1416
       1. Turning a common symbol into a reference, because there is
1417
          already a definition for the symbol.
1418
               FILE(SECTION): warning: common of `SYMBOL'
1419
                  overridden by definition
1420
               FILE(SECTION): warning: defined here
1421
 
1422
       2. Turning a common symbol into a reference, because a later
1423
          definition for the symbol is encountered.  This is the same
1424
          as the previous case, except that the symbols are encountered
1425
          in a different order.
1426
               FILE(SECTION): warning: definition of `SYMBOL'
1427
                  overriding common
1428
               FILE(SECTION): warning: common is here
1429
 
1430
       3. Merging a common symbol with a previous same-sized common
1431
          symbol.
1432
               FILE(SECTION): warning: multiple common
1433
                  of `SYMBOL'
1434
               FILE(SECTION): warning: previous common is here
1435
 
1436
       4. Merging a common symbol with a previous larger common symbol.
1437
               FILE(SECTION): warning: common of `SYMBOL'
1438
                  overridden by larger common
1439
               FILE(SECTION): warning: larger common is here
1440
 
1441
       5. Merging a common symbol with a previous smaller common
1442
          symbol.  This is the same as the previous case, except that
1443
          the symbols are encountered in a different order.
1444
               FILE(SECTION): warning: common of `SYMBOL'
1445
                  overriding smaller common
1446
               FILE(SECTION): warning: smaller common is here
1447
 
1448
`--warn-constructors'
1449
     Warn if any global constructors are used.  This is only useful for
1450
     a few object file formats.  For formats like COFF or ELF, the
1451
     linker can not detect the use of global constructors.
1452
 
1453
`--warn-multiple-gp'
1454
     Warn if multiple global pointer values are required in the output
1455
     file.  This is only meaningful for certain processors, such as the
1456
     Alpha.  Specifically, some processors put large-valued constants
1457
     in a special section.  A special register (the global pointer)
1458
     points into the middle of this section, so that constants can be
1459
     loaded efficiently via a base-register relative addressing mode.
1460
     Since the offset in base-register relative mode is fixed and
1461
     relatively small (e.g., 16 bits), this limits the maximum size of
1462
     the constant pool.  Thus, in large programs, it is often necessary
1463
     to use multiple global pointer values in order to be able to
1464
     address all possible constants.  This option causes a warning to
1465
     be issued whenever this case occurs.
1466
 
1467
`--warn-once'
1468
     Only warn once for each undefined symbol, rather than once per
1469
     module which refers to it.
1470
 
1471
`--warn-section-align'
1472
     Warn if the address of an output section is changed because of
1473
     alignment.  Typically, the alignment will be set by an input
1474
     section.  The address will only be changed if it not explicitly
1475
     specified; that is, if the `SECTIONS' command does not specify a
1476
     start address for the section (*note SECTIONS::).
1477
 
1478
`--warn-shared-textrel'
1479
     Warn if the linker adds a DT_TEXTREL to a shared object.
1480
 
1481
`--warn-alternate-em'
1482
     Warn if an object has alternate ELF machine code.
1483
 
1484
`--warn-unresolved-symbols'
1485
     If the linker is going to report an unresolved symbol (see the
1486
     option `--unresolved-symbols') it will normally generate an error.
1487
     This option makes it generate a warning instead.
1488
 
1489
`--error-unresolved-symbols'
1490
     This restores the linker's default behaviour of generating errors
1491
     when it is reporting unresolved symbols.
1492
 
1493
`--whole-archive'
1494
     For each archive mentioned on the command line after the
1495
     `--whole-archive' option, include every object file in the archive
1496
     in the link, rather than searching the archive for the required
1497
     object files.  This is normally used to turn an archive file into
1498
     a shared library, forcing every object to be included in the
1499
     resulting shared library.  This option may be used more than once.
1500
 
1501
     Two notes when using this option from gcc: First, gcc doesn't know
1502
     about this option, so you have to use `-Wl,-whole-archive'.
1503
     Second, don't forget to use `-Wl,-no-whole-archive' after your
1504
     list of archives, because gcc will add its own list of archives to
1505
     your link and you may not want this flag to affect those as well.
1506
 
1507
`--wrap=SYMBOL'
1508
     Use a wrapper function for SYMBOL.  Any undefined reference to
1509
     SYMBOL will be resolved to `__wrap_SYMBOL'.  Any undefined
1510
     reference to `__real_SYMBOL' will be resolved to SYMBOL.
1511
 
1512
     This can be used to provide a wrapper for a system function.  The
1513
     wrapper function should be called `__wrap_SYMBOL'.  If it wishes
1514
     to call the system function, it should call `__real_SYMBOL'.
1515
 
1516
     Here is a trivial example:
1517
 
1518
          void *
1519
          __wrap_malloc (size_t c)
1520
          {
1521
            printf ("malloc called with %zu\n", c);
1522
            return __real_malloc (c);
1523
          }
1524
 
1525
     If you link other code with this file using `--wrap malloc', then
1526
     all calls to `malloc' will call the function `__wrap_malloc'
1527
     instead.  The call to `__real_malloc' in `__wrap_malloc' will call
1528
     the real `malloc' function.
1529
 
1530
     You may wish to provide a `__real_malloc' function as well, so that
1531
     links without the `--wrap' option will succeed.  If you do this,
1532
     you should not put the definition of `__real_malloc' in the same
1533
     file as `__wrap_malloc'; if you do, the assembler may resolve the
1534
     call before the linker has a chance to wrap it to `malloc'.
1535
 
1536
`--eh-frame-hdr'
1537
     Request creation of `.eh_frame_hdr' section and ELF
1538
     `PT_GNU_EH_FRAME' segment header.
1539
 
1540
`--enable-new-dtags'
1541
`--disable-new-dtags'
1542
     This linker can create the new dynamic tags in ELF. But the older
1543
     ELF systems may not understand them. If you specify
1544
     `--enable-new-dtags', the dynamic tags will be created as needed.
1545
     If you specify `--disable-new-dtags', no new dynamic tags will be
1546
     created. By default, the new dynamic tags are not created. Note
1547
     that those options are only available for ELF systems.
1548
 
1549
`--hash-size=NUMBER'
1550
     Set the default size of the linker's hash tables to a prime number
1551
     close to NUMBER.  Increasing this value can reduce the length of
1552
     time it takes the linker to perform its tasks, at the expense of
1553
     increasing the linker's memory requirements.  Similarly reducing
1554
     this value can reduce the memory requirements at the expense of
1555
     speed.
1556
 
1557
`--hash-style=STYLE'
1558
     Set the type of linker's hash table(s).  STYLE can be either
1559
     `sysv' for classic ELF `.hash' section, `gnu' for new style GNU
1560
     `.gnu.hash' section or `both' for both the classic ELF `.hash' and
1561
     new style GNU `.gnu.hash' hash tables.  The default is `sysv'.
1562
 
1563
`--reduce-memory-overheads'
1564
     This option reduces memory requirements at ld runtime, at the
1565
     expense of linking speed.  This was introduced to select the old
1566
     O(n^2) algorithm for link map file generation, rather than the new
1567
     O(n) algorithm which uses about 40% more memory for symbol storage.
1568
 
1569
     Another effect of the switch is to set the default hash table size
1570
     to 1021, which again saves memory at the cost of lengthening the
1571
     linker's run time.  This is not done however if the `--hash-size'
1572
     switch has been used.
1573
 
1574
     The `--reduce-memory-overheads' switch may be also be used to
1575
     enable other tradeoffs in future versions of the linker.
1576
 
1577
`--build-id'
1578
`--build-id=STYLE'
1579
     Request creation of `.note.gnu.build-id' ELF note section.  The
1580
     contents of the note are unique bits identifying this linked file.
1581
     STYLE can be `uuid' to use 128 random bits, `sha1' to use a
1582
     160-bit SHA1 hash on the normative parts of the output contents,
1583
     `md5' to use a 128-bit MD5 hash on the normative parts of the
1584
     output contents, or `0xHEXSTRING' to use a chosen bit string
1585
     specified as an even number of hexadecimal digits (`-' and `:'
1586
     characters between digit pairs are ignored).  If STYLE is omitted,
1587
     `sha1' is used.
1588
 
1589
     The `md5' and `sha1' styles produces an identifier that is always
1590
     the same in an identical output file, but will be unique among all
1591
     nonidentical output files.  It is not intended to be compared as a
1592
     checksum for the file's contents.  A linked file may be changed
1593
     later by other tools, but the build ID bit string identifying the
1594
     original linked file does not change.
1595
 
1596
     Passing `none' for STYLE disables the setting from any
1597
     `--build-id' options earlier on the command line.
1598
 
1599
2.1.1 Options Specific to i386 PE Targets
1600
-----------------------------------------
1601
 
1602
The i386 PE linker supports the `-shared' option, which causes the
1603
output to be a dynamically linked library (DLL) instead of a normal
1604
executable.  You should name the output `*.dll' when you use this
1605
option.  In addition, the linker fully supports the standard `*.def'
1606
files, which may be specified on the linker command line like an object
1607
file (in fact, it should precede archives it exports symbols from, to
1608
ensure that they get linked in, just like a normal object file).
1609
 
1610
   In addition to the options common to all targets, the i386 PE linker
1611
support additional command line options that are specific to the i386
1612
PE target.  Options that take values may be separated from their values
1613
by either a space or an equals sign.
1614
 
1615
`--add-stdcall-alias'
1616
     If given, symbols with a stdcall suffix (@NN) will be exported
1617
     as-is and also with the suffix stripped.  [This option is specific
1618
     to the i386 PE targeted port of the linker]
1619
 
1620
`--base-file FILE'
1621
     Use FILE as the name of a file in which to save the base addresses
1622
     of all the relocations needed for generating DLLs with `dlltool'.
1623
     [This is an i386 PE specific option]
1624
 
1625
`--dll'
1626
     Create a DLL instead of a regular executable.  You may also use
1627
     `-shared' or specify a `LIBRARY' in a given `.def' file.  [This
1628
     option is specific to the i386 PE targeted port of the linker]
1629
 
1630
`--enable-long-section-names'
1631
`--disable-long-section-names'
1632
     The PE variants of the Coff object format add an extension that
1633
     permits the use of section names longer than eight characters, the
1634
     normal limit for Coff.  By default, these names are only allowed
1635
     in object files, as fully-linked executable images do not carry
1636
     the Coff string table required to support the longer names.  As a
1637
     GNU extension, it is possible to allow their use in executable
1638
     images as well, or to (probably pointlessly!)  disallow it in
1639
     object files, by using these two options.  Executable images
1640
     generated with these long section names are slightly non-standard,
1641
     carrying as they do a string table, and may generate confusing
1642
     output when examined with non-GNU PE-aware tools, such as file
1643
     viewers and dumpers.  However, GDB relies on the use of PE long
1644
     section names to find Dwarf-2 debug information sections in an
1645
     executable image at runtime, and so if neither option is specified
1646
     on the command-line, `ld' will enable long section names,
1647
     overriding the default and technically correct behaviour, when it
1648
     finds the presence of debug information while linking an executable
1649
     image and not stripping symbols.  [This option is valid for all PE
1650
     targeted ports of the linker]
1651
 
1652
`--enable-stdcall-fixup'
1653
`--disable-stdcall-fixup'
1654
     If the link finds a symbol that it cannot resolve, it will attempt
1655
     to do "fuzzy linking" by looking for another defined symbol that
1656
     differs only in the format of the symbol name (cdecl vs stdcall)
1657
     and will resolve that symbol by linking to the match.  For
1658
     example, the undefined symbol `_foo' might be linked to the
1659
     function `_foo@12', or the undefined symbol `_bar@16' might be
1660
     linked to the function `_bar'.  When the linker does this, it
1661
     prints a warning, since it normally should have failed to link,
1662
     but sometimes import libraries generated from third-party dlls may
1663
     need this feature to be usable.  If you specify
1664
     `--enable-stdcall-fixup', this feature is fully enabled and
1665
     warnings are not printed.  If you specify
1666
     `--disable-stdcall-fixup', this feature is disabled and such
1667
     mismatches are considered to be errors.  [This option is specific
1668
     to the i386 PE targeted port of the linker]
1669
 
1670
`--export-all-symbols'
1671
     If given, all global symbols in the objects used to build a DLL
1672
     will be exported by the DLL.  Note that this is the default if
1673
     there otherwise wouldn't be any exported symbols.  When symbols are
1674
     explicitly exported via DEF files or implicitly exported via
1675
     function attributes, the default is to not export anything else
1676
     unless this option is given.  Note that the symbols `DllMain@12',
1677
     `DllEntryPoint@0', `DllMainCRTStartup@12', and `impure_ptr' will
1678
     not be automatically exported.  Also, symbols imported from other
1679
     DLLs will not be re-exported, nor will symbols specifying the
1680
     DLL's internal layout such as those beginning with `_head_' or
1681
     ending with `_iname'.  In addition, no symbols from `libgcc',
1682
     `libstd++', `libmingw32', or `crtX.o' will be exported.  Symbols
1683
     whose names begin with `__rtti_' or `__builtin_' will not be
1684
     exported, to help with C++ DLLs.  Finally, there is an extensive
1685
     list of cygwin-private symbols that are not exported (obviously,
1686
     this applies on when building DLLs for cygwin targets).  These
1687
     cygwin-excludes are: `_cygwin_dll_entry@12',
1688
     `_cygwin_crt0_common@8', `_cygwin_noncygwin_dll_entry@12',
1689
     `_fmode', `_impure_ptr', `cygwin_attach_dll', `cygwin_premain0',
1690
     `cygwin_premain1', `cygwin_premain2', `cygwin_premain3', and
1691
     `environ'.  [This option is specific to the i386 PE targeted port
1692
     of the linker]
1693
 
1694
`--exclude-symbols SYMBOL,SYMBOL,...'
1695
     Specifies a list of symbols which should not be automatically
1696
     exported.  The symbol names may be delimited by commas or colons.
1697
     [This option is specific to the i386 PE targeted port of the
1698
     linker]
1699
 
1700
`--file-alignment'
1701
     Specify the file alignment.  Sections in the file will always
1702
     begin at file offsets which are multiples of this number.  This
1703
     defaults to 512.  [This option is specific to the i386 PE targeted
1704
     port of the linker]
1705
 
1706
`--heap RESERVE'
1707
`--heap RESERVE,COMMIT'
1708
     Specify the number of bytes of memory to reserve (and optionally
1709
     commit) to be used as heap for this program.  The default is 1Mb
1710
     reserved, 4K committed.  [This option is specific to the i386 PE
1711
     targeted port of the linker]
1712
 
1713
`--image-base VALUE'
1714
     Use VALUE as the base address of your program or dll.  This is the
1715
     lowest memory location that will be used when your program or dll
1716
     is loaded.  To reduce the need to relocate and improve performance
1717
     of your dlls, each should have a unique base address and not
1718
     overlap any other dlls.  The default is 0x400000 for executables,
1719
     and 0x10000000 for dlls.  [This option is specific to the i386 PE
1720
     targeted port of the linker]
1721
 
1722
`--kill-at'
1723
     If given, the stdcall suffixes (@NN) will be stripped from symbols
1724
     before they are exported.  [This option is specific to the i386 PE
1725
     targeted port of the linker]
1726
 
1727
`--large-address-aware'
1728
     If given, the appropriate bit in the "Characteristics" field of
1729
     the COFF header is set to indicate that this executable supports
1730
     virtual addresses greater than 2 gigabytes.  This should be used
1731
     in conjunction with the /3GB or /USERVA=VALUE megabytes switch in
1732
     the "[operating systems]" section of the BOOT.INI.  Otherwise,
1733
     this bit has no effect.  [This option is specific to PE targeted
1734
     ports of the linker]
1735
 
1736
`--major-image-version VALUE'
1737
     Sets the major number of the "image version".  Defaults to 1.
1738
     [This option is specific to the i386 PE targeted port of the
1739
     linker]
1740
 
1741
`--major-os-version VALUE'
1742
     Sets the major number of the "os version".  Defaults to 4.  [This
1743
     option is specific to the i386 PE targeted port of the linker]
1744
 
1745
`--major-subsystem-version VALUE'
1746
     Sets the major number of the "subsystem version".  Defaults to 4.
1747
     [This option is specific to the i386 PE targeted port of the
1748
     linker]
1749
 
1750
`--minor-image-version VALUE'
1751
     Sets the minor number of the "image version".  Defaults to 0.
1752
     [This option is specific to the i386 PE targeted port of the
1753
     linker]
1754
 
1755
`--minor-os-version VALUE'
1756
     Sets the minor number of the "os version".  Defaults to 0.  [This
1757
     option is specific to the i386 PE targeted port of the linker]
1758
 
1759
`--minor-subsystem-version VALUE'
1760
     Sets the minor number of the "subsystem version".  Defaults to 0.
1761
     [This option is specific to the i386 PE targeted port of the
1762
     linker]
1763
 
1764
`--output-def FILE'
1765
     The linker will create the file FILE which will contain a DEF file
1766
     corresponding to the DLL the linker is generating.  This DEF file
1767
     (which should be called `*.def') may be used to create an import
1768
     library with `dlltool' or may be used as a reference to
1769
     automatically or implicitly exported symbols.  [This option is
1770
     specific to the i386 PE targeted port of the linker]
1771
 
1772
`--out-implib FILE'
1773
     The linker will create the file FILE which will contain an import
1774
     lib corresponding to the DLL the linker is generating. This import
1775
     lib (which should be called `*.dll.a' or `*.a' may be used to link
1776
     clients against the generated DLL; this behaviour makes it
1777
     possible to skip a separate `dlltool' import library creation step.
1778
     [This option is specific to the i386 PE targeted port of the
1779
     linker]
1780
 
1781
`--enable-auto-image-base'
1782
     Automatically choose the image base for DLLs, unless one is
1783
     specified using the `--image-base' argument.  By using a hash
1784
     generated from the dllname to create unique image bases for each
1785
     DLL, in-memory collisions and relocations which can delay program
1786
     execution are avoided.  [This option is specific to the i386 PE
1787
     targeted port of the linker]
1788
 
1789
`--disable-auto-image-base'
1790
     Do not automatically generate a unique image base.  If there is no
1791
     user-specified image base (`--image-base') then use the platform
1792
     default.  [This option is specific to the i386 PE targeted port of
1793
     the linker]
1794
 
1795
`--dll-search-prefix STRING'
1796
     When linking dynamically to a dll without an import library,
1797
     search for `.dll' in preference to
1798
     `lib.dll'. This behaviour allows easy distinction
1799
     between DLLs built for the various "subplatforms": native, cygwin,
1800
     uwin, pw, etc.  For instance, cygwin DLLs typically use
1801
     `--dll-search-prefix=cyg'.  [This option is specific to the i386
1802
     PE targeted port of the linker]
1803
 
1804
`--enable-auto-import'
1805
     Do sophisticated linking of `_symbol' to `__imp__symbol' for DATA
1806
     imports from DLLs, and create the necessary thunking symbols when
1807
     building the import libraries with those DATA exports. Note: Use
1808
     of the 'auto-import' extension will cause the text section of the
1809
     image file to be made writable. This does not conform to the
1810
     PE-COFF format specification published by Microsoft.
1811
 
1812
     Note - use of the 'auto-import' extension will also cause read only
1813
     data which would normally be placed into the .rdata section to be
1814
     placed into the .data section instead.  This is in order to work
1815
     around a problem with consts that is described here:
1816
     http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
1817
 
1818
     Using 'auto-import' generally will 'just work' - but sometimes you
1819
     may see this message:
1820
 
1821
     "variable '' can't be auto-imported. Please read the
1822
     documentation for ld's `--enable-auto-import' for details."
1823
 
1824
     This message occurs when some (sub)expression accesses an address
1825
     ultimately given by the sum of two constants (Win32 import tables
1826
     only allow one).  Instances where this may occur include accesses
1827
     to member fields of struct variables imported from a DLL, as well
1828
     as using a constant index into an array variable imported from a
1829
     DLL.  Any multiword variable (arrays, structs, long long, etc) may
1830
     trigger this error condition.  However, regardless of the exact
1831
     data type of the offending exported variable, ld will always
1832
     detect it, issue the warning, and exit.
1833
 
1834
     There are several ways to address this difficulty, regardless of
1835
     the data type of the exported variable:
1836
 
1837
     One way is to use -enable-runtime-pseudo-reloc switch. This leaves
1838
     the task of adjusting references in your client code for runtime
1839
     environment, so this method works only when runtime environment
1840
     supports this feature.
1841
 
1842
     A second solution is to force one of the 'constants' to be a
1843
     variable - that is, unknown and un-optimizable at compile time.
1844
     For arrays, there are two possibilities: a) make the indexee (the
1845
     array's address) a variable, or b) make the 'constant' index a
1846
     variable.  Thus:
1847
 
1848
          extern type extern_array[];
1849
          extern_array[1] -->
1850
             { volatile type *t=extern_array; t[1] }
1851
 
1852
     or
1853
 
1854
          extern type extern_array[];
1855
          extern_array[1] -->
1856
             { volatile int t=1; extern_array[t] }
1857
 
1858
     For structs (and most other multiword data types) the only option
1859
     is to make the struct itself (or the long long, or the ...)
1860
     variable:
1861
 
1862
          extern struct s extern_struct;
1863
          extern_struct.field -->
1864
             { volatile struct s *t=&extern_struct; t->field }
1865
 
1866
     or
1867
 
1868
          extern long long extern_ll;
1869
          extern_ll -->
1870
            { volatile long long * local_ll=&extern_ll; *local_ll }
1871
 
1872
     A third method of dealing with this difficulty is to abandon
1873
     'auto-import' for the offending symbol and mark it with
1874
     `__declspec(dllimport)'.  However, in practise that requires using
1875
     compile-time #defines to indicate whether you are building a DLL,
1876
     building client code that will link to the DLL, or merely
1877
     building/linking to a static library.   In making the choice
1878
     between the various methods of resolving the 'direct address with
1879
     constant offset' problem, you should consider typical real-world
1880
     usage:
1881
 
1882
     Original:
1883
          --foo.h
1884
          extern int arr[];
1885
          --foo.c
1886
          #include "foo.h"
1887
          void main(int argc, char **argv){
1888
            printf("%d\n",arr[1]);
1889
          }
1890
 
1891
     Solution 1:
1892
          --foo.h
1893
          extern int arr[];
1894
          --foo.c
1895
          #include "foo.h"
1896
          void main(int argc, char **argv){
1897
            /* This workaround is for win32 and cygwin; do not "optimize" */
1898
            volatile int *parr = arr;
1899
            printf("%d\n",parr[1]);
1900
          }
1901
 
1902
     Solution 2:
1903
          --foo.h
1904
          /* Note: auto-export is assumed (no __declspec(dllexport)) */
1905
          #if (defined(_WIN32) || defined(__CYGWIN__)) && \
1906
            !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
1907
          #define FOO_IMPORT __declspec(dllimport)
1908
          #else
1909
          #define FOO_IMPORT
1910
          #endif
1911
          extern FOO_IMPORT int arr[];
1912
          --foo.c
1913
          #include "foo.h"
1914
          void main(int argc, char **argv){
1915
            printf("%d\n",arr[1]);
1916
          }
1917
 
1918
     A fourth way to avoid this problem is to re-code your library to
1919
     use a functional interface rather than a data interface for the
1920
     offending variables (e.g. set_foo() and get_foo() accessor
1921
     functions).  [This option is specific to the i386 PE targeted port
1922
     of the linker]
1923
 
1924
`--disable-auto-import'
1925
     Do not attempt to do sophisticated linking of `_symbol' to
1926
     `__imp__symbol' for DATA imports from DLLs.  [This option is
1927
     specific to the i386 PE targeted port of the linker]
1928
 
1929
`--enable-runtime-pseudo-reloc'
1930
     If your code contains expressions described in -enable-auto-import
1931
     section, that is, DATA imports from DLL with non-zero offset, this
1932
     switch will create a vector of 'runtime pseudo relocations' which
1933
     can be used by runtime environment to adjust references to such
1934
     data in your client code.  [This option is specific to the i386 PE
1935
     targeted port of the linker]
1936
 
1937
`--disable-runtime-pseudo-reloc'
1938
     Do not create pseudo relocations for non-zero offset DATA imports
1939
     from DLLs.  This is the default.  [This option is specific to the
1940
     i386 PE targeted port of the linker]
1941
 
1942
`--enable-extra-pe-debug'
1943
     Show additional debug info related to auto-import symbol thunking.
1944
     [This option is specific to the i386 PE targeted port of the
1945
     linker]
1946
 
1947
`--section-alignment'
1948
     Sets the section alignment.  Sections in memory will always begin
1949
     at addresses which are a multiple of this number.  Defaults to
1950
     0x1000.  [This option is specific to the i386 PE targeted port of
1951
     the linker]
1952
 
1953
`--stack RESERVE'
1954
`--stack RESERVE,COMMIT'
1955
     Specify the number of bytes of memory to reserve (and optionally
1956
     commit) to be used as stack for this program.  The default is 2Mb
1957
     reserved, 4K committed.  [This option is specific to the i386 PE
1958
     targeted port of the linker]
1959
 
1960
`--subsystem WHICH'
1961
`--subsystem WHICH:MAJOR'
1962
`--subsystem WHICH:MAJOR.MINOR'
1963
     Specifies the subsystem under which your program will execute.  The
1964
     legal values for WHICH are `native', `windows', `console',
1965
     `posix', and `xbox'.  You may optionally set the subsystem version
1966
     also.  Numeric values are also accepted for WHICH.  [This option
1967
     is specific to the i386 PE targeted port of the linker]
1968
 
1969
     The following options set flags in the `DllCharacteristics' field
1970
     of the PE file header: [These options are specific to PE targeted
1971
     ports of the linker]
1972
 
1973
`--dynamicbase'
1974
     The image base address may be relocated using address space layout
1975
     randomization (ASLR).  This feature was introduced with MS Windows
1976
     Vista for i386 PE targets.
1977
 
1978
`--forceinteg'
1979
     Code integrity checks are enforced.
1980
 
1981
`--nxcompat'
1982
     The image is compatible with the Data Execution Prevention.  This
1983
     feature was introduced with MS Windows XP SP2 for i386 PE targets.
1984
 
1985
`--no-isolation'
1986
     Although the image understands isolation, do not isolate the image.
1987
 
1988
`--no-seh'
1989
     The image does not use SEH. No SE handler may be called from this
1990
     image.
1991
 
1992
`--no-bind'
1993
     Do not bind this image.
1994
 
1995
`--wdmdriver'
1996
     The driver uses the MS Windows Driver Model.
1997
 
1998
`--tsaware'
1999
     The image is Terminal Server aware.
2000
 
2001
 
2002
2.1.2 Options specific to Motorola 68HC11 and 68HC12 targets
2003
------------------------------------------------------------
2004
 
2005
The 68HC11 and 68HC12 linkers support specific options to control the
2006
memory bank switching mapping and trampoline code generation.
2007
 
2008
`--no-trampoline'
2009
     This option disables the generation of trampoline. By default a
2010
     trampoline is generated for each far function which is called
2011
     using a `jsr' instruction (this happens when a pointer to a far
2012
     function is taken).
2013
 
2014
`--bank-window NAME'
2015
     This option indicates to the linker the name of the memory region
2016
     in the `MEMORY' specification that describes the memory bank
2017
     window.  The definition of such region is then used by the linker
2018
     to compute paging and addresses within the memory window.
2019
 
2020
 
2021
2.1.3 Options specific to Motorola 68K target
2022
---------------------------------------------
2023
 
2024
The following options are supported to control handling of GOT
2025
generation when linking for 68K targets.
2026
 
2027
`--got=TYPE'
2028
     This option tells the linker which GOT generation scheme to use.
2029
     TYPE should be one of `single', `negative', `multigot' or
2030
     `target'.  For more information refer to the Info entry for `ld'.
2031
 
2032
 
2033

2034
File: ld.info,  Node: Environment,  Prev: Options,  Up: Invocation
2035
 
2036
2.2 Environment Variables
2037
=========================
2038
 
2039
You can change the behaviour of `ld' with the environment variables
2040
`GNUTARGET', `LDEMULATION' and `COLLECT_NO_DEMANGLE'.
2041
 
2042
   `GNUTARGET' determines the input-file object format if you don't use
2043
`-b' (or its synonym `--format').  Its value should be one of the BFD
2044
names for an input format (*note BFD::).  If there is no `GNUTARGET' in
2045
the environment, `ld' uses the natural format of the target. If
2046
`GNUTARGET' is set to `default' then BFD attempts to discover the input
2047
format by examining binary input files; this method often succeeds, but
2048
there are potential ambiguities, since there is no method of ensuring
2049
that the magic number used to specify object-file formats is unique.
2050
However, the configuration procedure for BFD on each system places the
2051
conventional format for that system first in the search-list, so
2052
ambiguities are resolved in favor of convention.
2053
 
2054
   `LDEMULATION' determines the default emulation if you don't use the
2055
`-m' option.  The emulation can affect various aspects of linker
2056
behaviour, particularly the default linker script.  You can list the
2057
available emulations with the `--verbose' or `-V' options.  If the `-m'
2058
option is not used, and the `LDEMULATION' environment variable is not
2059
defined, the default emulation depends upon how the linker was
2060
configured.
2061
 
2062
   Normally, the linker will default to demangling symbols.  However, if
2063
`COLLECT_NO_DEMANGLE' is set in the environment, then it will default
2064
to not demangling symbols.  This environment variable is used in a
2065
similar fashion by the `gcc' linker wrapper program.  The default may
2066
be overridden by the `--demangle' and `--no-demangle' options.
2067
 
2068

2069
File: ld.info,  Node: Scripts,  Next: Machine Dependent,  Prev: Invocation,  Up: Top
2070
 
2071
3 Linker Scripts
2072
****************
2073
 
2074
Every link is controlled by a "linker script".  This script is written
2075
in the linker command language.
2076
 
2077
   The main purpose of the linker script is to describe how the
2078
sections in the input files should be mapped into the output file, and
2079
to control the memory layout of the output file.  Most linker scripts
2080
do nothing more than this.  However, when necessary, the linker script
2081
can also direct the linker to perform many other operations, using the
2082
commands described below.
2083
 
2084
   The linker always uses a linker script.  If you do not supply one
2085
yourself, the linker will use a default script that is compiled into the
2086
linker executable.  You can use the `--verbose' command line option to
2087
display the default linker script.  Certain command line options, such
2088
as `-r' or `-N', will affect the default linker script.
2089
 
2090
   You may supply your own linker script by using the `-T' command line
2091
option.  When you do this, your linker script will replace the default
2092
linker script.
2093
 
2094
   You may also use linker scripts implicitly by naming them as input
2095
files to the linker, as though they were files to be linked.  *Note
2096
Implicit Linker Scripts::.
2097
 
2098
* Menu:
2099
 
2100
* Basic Script Concepts::       Basic Linker Script Concepts
2101
* Script Format::               Linker Script Format
2102
* Simple Example::              Simple Linker Script Example
2103
* Simple Commands::             Simple Linker Script Commands
2104
* Assignments::                 Assigning Values to Symbols
2105
* SECTIONS::                    SECTIONS Command
2106
* MEMORY::                      MEMORY Command
2107
* PHDRS::                       PHDRS Command
2108
* VERSION::                     VERSION Command
2109
* Expressions::                 Expressions in Linker Scripts
2110
* Implicit Linker Scripts::     Implicit Linker Scripts
2111
 
2112

2113
File: ld.info,  Node: Basic Script Concepts,  Next: Script Format,  Up: Scripts
2114
 
2115
3.1 Basic Linker Script Concepts
2116
================================
2117
 
2118
We need to define some basic concepts and vocabulary in order to
2119
describe the linker script language.
2120
 
2121
   The linker combines input files into a single output file.  The
2122
output file and each input file are in a special data format known as an
2123
"object file format".  Each file is called an "object file".  The
2124
output file is often called an "executable", but for our purposes we
2125
will also call it an object file.  Each object file has, among other
2126
things, a list of "sections".  We sometimes refer to a section in an
2127
input file as an "input section"; similarly, a section in the output
2128
file is an "output section".
2129
 
2130
   Each section in an object file has a name and a size.  Most sections
2131
also have an associated block of data, known as the "section contents".
2132
A section may be marked as "loadable", which mean that the contents
2133
should be loaded into memory when the output file is run.  A section
2134
with no contents may be "allocatable", which means that an area in
2135
memory should be set aside, but nothing in particular should be loaded
2136
there (in some cases this memory must be zeroed out).  A section which
2137
is neither loadable nor allocatable typically contains some sort of
2138
debugging information.
2139
 
2140
   Every loadable or allocatable output section has two addresses.  The
2141
first is the "VMA", or virtual memory address.  This is the address the
2142
section will have when the output file is run.  The second is the
2143
"LMA", or load memory address.  This is the address at which the
2144
section will be loaded.  In most cases the two addresses will be the
2145
same.  An example of when they might be different is when a data section
2146
is loaded into ROM, and then copied into RAM when the program starts up
2147
(this technique is often used to initialize global variables in a ROM
2148
based system).  In this case the ROM address would be the LMA, and the
2149
RAM address would be the VMA.
2150
 
2151
   You can see the sections in an object file by using the `objdump'
2152
program with the `-h' option.
2153
 
2154
   Every object file also has a list of "symbols", known as the "symbol
2155
table".  A symbol may be defined or undefined.  Each symbol has a name,
2156
and each defined symbol has an address, among other information.  If
2157
you compile a C or C++ program into an object file, you will get a
2158
defined symbol for every defined function and global or static
2159
variable.  Every undefined function or global variable which is
2160
referenced in the input file will become an undefined symbol.
2161
 
2162
   You can see the symbols in an object file by using the `nm' program,
2163
or by using the `objdump' program with the `-t' option.
2164
 
2165

2166
File: ld.info,  Node: Script Format,  Next: Simple Example,  Prev: Basic Script Concepts,  Up: Scripts
2167
 
2168
3.2 Linker Script Format
2169
========================
2170
 
2171
Linker scripts are text files.
2172
 
2173
   You write a linker script as a series of commands.  Each command is
2174
either a keyword, possibly followed by arguments, or an assignment to a
2175
symbol.  You may separate commands using semicolons.  Whitespace is
2176
generally ignored.
2177
 
2178
   Strings such as file or format names can normally be entered
2179
directly.  If the file name contains a character such as a comma which
2180
would otherwise serve to separate file names, you may put the file name
2181
in double quotes.  There is no way to use a double quote character in a
2182
file name.
2183
 
2184
   You may include comments in linker scripts just as in C, delimited by
2185
`/*' and `*/'.  As in C, comments are syntactically equivalent to
2186
whitespace.
2187
 
2188

2189
File: ld.info,  Node: Simple Example,  Next: Simple Commands,  Prev: Script Format,  Up: Scripts
2190
 
2191
3.3 Simple Linker Script Example
2192
================================
2193
 
2194
Many linker scripts are fairly simple.
2195
 
2196
   The simplest possible linker script has just one command:
2197
`SECTIONS'.  You use the `SECTIONS' command to describe the memory
2198
layout of the output file.
2199
 
2200
   The `SECTIONS' command is a powerful command.  Here we will describe
2201
a simple use of it.  Let's assume your program consists only of code,
2202
initialized data, and uninitialized data.  These will be in the
2203
`.text', `.data', and `.bss' sections, respectively.  Let's assume
2204
further that these are the only sections which appear in your input
2205
files.
2206
 
2207
   For this example, let's say that the code should be loaded at address
2208
0x10000, and that the data should start at address 0x8000000.  Here is a
2209
linker script which will do that:
2210
     SECTIONS
2211
     {
2212
       . = 0x10000;
2213
       .text : { *(.text) }
2214
       . = 0x8000000;
2215
       .data : { *(.data) }
2216
       .bss : { *(.bss) }
2217
     }
2218
 
2219
   You write the `SECTIONS' command as the keyword `SECTIONS', followed
2220
by a series of symbol assignments and output section descriptions
2221
enclosed in curly braces.
2222
 
2223
   The first line inside the `SECTIONS' command of the above example
2224
sets the value of the special symbol `.', which is the location
2225
counter.  If you do not specify the address of an output section in some
2226
other way (other ways are described later), the address is set from the
2227
current value of the location counter.  The location counter is then
2228
incremented by the size of the output section.  At the start of the
2229
`SECTIONS' command, the location counter has the value `0'.
2230
 
2231
   The second line defines an output section, `.text'.  The colon is
2232
required syntax which may be ignored for now.  Within the curly braces
2233
after the output section name, you list the names of the input sections
2234
which should be placed into this output section.  The `*' is a wildcard
2235
which matches any file name.  The expression `*(.text)' means all
2236
`.text' input sections in all input files.
2237
 
2238
   Since the location counter is `0x10000' when the output section
2239
`.text' is defined, the linker will set the address of the `.text'
2240
section in the output file to be `0x10000'.
2241
 
2242
   The remaining lines define the `.data' and `.bss' sections in the
2243
output file.  The linker will place the `.data' output section at
2244
address `0x8000000'.  After the linker places the `.data' output
2245
section, the value of the location counter will be `0x8000000' plus the
2246
size of the `.data' output section.  The effect is that the linker will
2247
place the `.bss' output section immediately after the `.data' output
2248
section in memory.
2249
 
2250
   The linker will ensure that each output section has the required
2251
alignment, by increasing the location counter if necessary.  In this
2252
example, the specified addresses for the `.text' and `.data' sections
2253
will probably satisfy any alignment constraints, but the linker may
2254
have to create a small gap between the `.data' and `.bss' sections.
2255
 
2256
   That's it!  That's a simple and complete linker script.
2257
 
2258

2259
File: ld.info,  Node: Simple Commands,  Next: Assignments,  Prev: Simple Example,  Up: Scripts
2260
 
2261
3.4 Simple Linker Script Commands
2262
=================================
2263
 
2264
In this section we describe the simple linker script commands.
2265
 
2266
* Menu:
2267
 
2268
* Entry Point::                 Setting the entry point
2269
* File Commands::               Commands dealing with files
2270
 
2271
* Format Commands::             Commands dealing with object file formats
2272
 
2273
* REGION_ALIAS::                Assign alias names to memory regions
2274
* Miscellaneous Commands::      Other linker script commands
2275
 
2276

2277
File: ld.info,  Node: Entry Point,  Next: File Commands,  Up: Simple Commands
2278
 
2279
3.4.1 Setting the Entry Point
2280
-----------------------------
2281
 
2282
The first instruction to execute in a program is called the "entry
2283
point".  You can use the `ENTRY' linker script command to set the entry
2284
point.  The argument is a symbol name:
2285
     ENTRY(SYMBOL)
2286
 
2287
   There are several ways to set the entry point.  The linker will set
2288
the entry point by trying each of the following methods in order, and
2289
stopping when one of them succeeds:
2290
   * the `-e' ENTRY command-line option;
2291
 
2292
   * the `ENTRY(SYMBOL)' command in a linker script;
2293
 
2294
   * the value of the symbol `start', if defined;
2295
 
2296
   * the address of the first byte of the `.text' section, if present;
2297
 
2298
   * The address `0'.
2299
 
2300

2301
File: ld.info,  Node: File Commands,  Next: Format Commands,  Prev: Entry Point,  Up: Simple Commands
2302
 
2303
3.4.2 Commands Dealing with Files
2304
---------------------------------
2305
 
2306
Several linker script commands deal with files.
2307
 
2308
`INCLUDE FILENAME'
2309
     Include the linker script FILENAME at this point.  The file will
2310
     be searched for in the current directory, and in any directory
2311
     specified with the `-L' option.  You can nest calls to `INCLUDE'
2312
     up to 10 levels deep.
2313
 
2314
     You can place `INCLUDE' directives at the top level, in `MEMORY' or
2315
     `SECTIONS' commands, or in output section descriptions.
2316
 
2317
`INPUT(FILE, FILE, ...)'
2318
`INPUT(FILE FILE ...)'
2319
     The `INPUT' command directs the linker to include the named files
2320
     in the link, as though they were named on the command line.
2321
 
2322
     For example, if you always want to include `subr.o' any time you do
2323
     a link, but you can't be bothered to put it on every link command
2324
     line, then you can put `INPUT (subr.o)' in your linker script.
2325
 
2326
     In fact, if you like, you can list all of your input files in the
2327
     linker script, and then invoke the linker with nothing but a `-T'
2328
     option.
2329
 
2330
     In case a "sysroot prefix" is configured, and the filename starts
2331
     with the `/' character, and the script being processed was located
2332
     inside the "sysroot prefix", the filename will be looked for in
2333
     the "sysroot prefix".  Otherwise, the linker will try to open the
2334
     file in the current directory.  If it is not found, the linker
2335
     will search through the archive library search path.  See the
2336
     description of `-L' in *Note Command Line Options: Options.
2337
 
2338
     If you use `INPUT (-lFILE)', `ld' will transform the name to
2339
     `libFILE.a', as with the command line argument `-l'.
2340
 
2341
     When you use the `INPUT' command in an implicit linker script, the
2342
     files will be included in the link at the point at which the linker
2343
     script file is included.  This can affect archive searching.
2344
 
2345
`GROUP(FILE, FILE, ...)'
2346
`GROUP(FILE FILE ...)'
2347
     The `GROUP' command is like `INPUT', except that the named files
2348
     should all be archives, and they are searched repeatedly until no
2349
     new undefined references are created.  See the description of `-('
2350
     in *Note Command Line Options: Options.
2351
 
2352
`AS_NEEDED(FILE, FILE, ...)'
2353
`AS_NEEDED(FILE FILE ...)'
2354
     This construct can appear only inside of the `INPUT' or `GROUP'
2355
     commands, among other filenames.  The files listed will be handled
2356
     as if they appear directly in the `INPUT' or `GROUP' commands,
2357
     with the exception of ELF shared libraries, that will be added only
2358
     when they are actually needed.  This construct essentially enables
2359
     `--as-needed' option for all the files listed inside of it and
2360
     restores previous `--as-needed' resp. `--no-as-needed' setting
2361
     afterwards.
2362
 
2363
`OUTPUT(FILENAME)'
2364
     The `OUTPUT' command names the output file.  Using
2365
     `OUTPUT(FILENAME)' in the linker script is exactly like using `-o
2366
     FILENAME' on the command line (*note Command Line Options:
2367
     Options.).  If both are used, the command line option takes
2368
     precedence.
2369
 
2370
     You can use the `OUTPUT' command to define a default name for the
2371
     output file other than the usual default of `a.out'.
2372
 
2373
`SEARCH_DIR(PATH)'
2374
     The `SEARCH_DIR' command adds PATH to the list of paths where `ld'
2375
     looks for archive libraries.  Using `SEARCH_DIR(PATH)' is exactly
2376
     like using `-L PATH' on the command line (*note Command Line
2377
     Options: Options.).  If both are used, then the linker will search
2378
     both paths.  Paths specified using the command line option are
2379
     searched first.
2380
 
2381
`STARTUP(FILENAME)'
2382
     The `STARTUP' command is just like the `INPUT' command, except
2383
     that FILENAME will become the first input file to be linked, as
2384
     though it were specified first on the command line.  This may be
2385
     useful when using a system in which the entry point is always the
2386
     start of the first file.
2387
 
2388

2389
File: ld.info,  Node: Format Commands,  Next: REGION_ALIAS,  Prev: File Commands,  Up: Simple Commands
2390
 
2391
3.4.3 Commands Dealing with Object File Formats
2392
-----------------------------------------------
2393
 
2394
A couple of linker script commands deal with object file formats.
2395
 
2396
`OUTPUT_FORMAT(BFDNAME)'
2397
`OUTPUT_FORMAT(DEFAULT, BIG, LITTLE)'
2398
     The `OUTPUT_FORMAT' command names the BFD format to use for the
2399
     output file (*note BFD::).  Using `OUTPUT_FORMAT(BFDNAME)' is
2400
     exactly like using `--oformat BFDNAME' on the command line (*note
2401
     Command Line Options: Options.).  If both are used, the command
2402
     line option takes precedence.
2403
 
2404
     You can use `OUTPUT_FORMAT' with three arguments to use different
2405
     formats based on the `-EB' and `-EL' command line options.  This
2406
     permits the linker script to set the output format based on the
2407
     desired endianness.
2408
 
2409
     If neither `-EB' nor `-EL' are used, then the output format will
2410
     be the first argument, DEFAULT.  If `-EB' is used, the output
2411
     format will be the second argument, BIG.  If `-EL' is used, the
2412
     output format will be the third argument, LITTLE.
2413
 
2414
     For example, the default linker script for the MIPS ELF target
2415
     uses this command:
2416
          OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
2417
     This says that the default format for the output file is
2418
     `elf32-bigmips', but if the user uses the `-EL' command line
2419
     option, the output file will be created in the `elf32-littlemips'
2420
     format.
2421
 
2422
`TARGET(BFDNAME)'
2423
     The `TARGET' command names the BFD format to use when reading input
2424
     files.  It affects subsequent `INPUT' and `GROUP' commands.  This
2425
     command is like using `-b BFDNAME' on the command line (*note
2426
     Command Line Options: Options.).  If the `TARGET' command is used
2427
     but `OUTPUT_FORMAT' is not, then the last `TARGET' command is also
2428
     used to set the format for the output file.  *Note BFD::.
2429
 
2430

2431
File: ld.info,  Node: REGION_ALIAS,  Next: Miscellaneous Commands,  Prev: Format Commands,  Up: Simple Commands
2432
 
2433
3.4.4 Assign alias names to memory regions
2434
------------------------------------------
2435
 
2436
Alias names can be added to existing memory regions created with the
2437
*Note MEMORY:: command.  Each name corresponds to at most one memory
2438
region.
2439
 
2440
     REGION_ALIAS(ALIAS, REGION)
2441
 
2442
   The `REGION_ALIAS' function creates an alias name ALIAS for the
2443
memory region REGION.  This allows a flexible mapping of output sections
2444
to memory regions.  An example follows.
2445
 
2446
   Suppose we have an application for embedded systems which come with
2447
various memory storage devices.  All have a general purpose, volatile
2448
memory `RAM' that allows code execution or data storage.  Some may have
2449
a read-only, non-volatile memory `ROM' that allows code execution and
2450
read-only data access.  The last variant is a read-only, non-volatile
2451
memory `ROM2' with read-only data access and no code execution
2452
capability.  We have four output sections:
2453
 
2454
   * `.text' program code;
2455
 
2456
   * `.rodata' read-only data;
2457
 
2458
   * `.data' read-write initialized data;
2459
 
2460
   * `.bss' read-write zero initialized data.
2461
 
2462
   The goal is to provide a linker command file that contains a system
2463
independent part defining the output sections and a system dependent
2464
part mapping the output sections to the memory regions available on the
2465
system.  Our embedded systems come with three different memory setups
2466
`A', `B' and `C':
2467
Section            Variant A          Variant B          Variant C
2468
.text              RAM                ROM                ROM
2469
.rodata            RAM                ROM                ROM2
2470
.data              RAM                RAM/ROM            RAM/ROM2
2471
.bss               RAM                RAM                RAM
2472
   The notation `RAM/ROM' or `RAM/ROM2' means that this section is
2473
loaded into region `ROM' or `ROM2' respectively.  Please note that the
2474
load address of the `.data' section starts in all three variants at the
2475
end of the `.rodata' section.
2476
 
2477
   The base linker script that deals with the output sections follows.
2478
It includes the system dependent `linkcmds.memory' file that describes
2479
the memory layout:
2480
     INCLUDE linkcmds.memory
2481
 
2482
     SECTIONS
2483
       {
2484
         .text :
2485
           {
2486
             *(.text)
2487
           } > REGION_TEXT
2488
         .rodata :
2489
           {
2490
             *(.rodata)
2491
             rodata_end = .;
2492
           } > REGION_RODATA
2493
         .data : AT (rodata_end)
2494
           {
2495
             data_start = .;
2496
             *(.data)
2497
           } > REGION_DATA
2498
         data_size = SIZEOF(.data);
2499
         data_load_start = LOADADDR(.data);
2500
         .bss :
2501
           {
2502
             *(.bss)
2503
           } > REGION_BSS
2504
       }
2505
 
2506
   Now we need three different `linkcmds.memory' files to define memory
2507
regions and alias names.  The content of `linkcmds.memory' for the three
2508
variants `A', `B' and `C':
2509
`A'
2510
     Here everything goes into the `RAM'.
2511
          MEMORY
2512
            {
2513
              RAM : ORIGIN = 0, LENGTH = 4M
2514
            }
2515
 
2516
          REGION_ALIAS("REGION_TEXT", RAM);
2517
          REGION_ALIAS("REGION_RODATA", RAM);
2518
          REGION_ALIAS("REGION_DATA", RAM);
2519
          REGION_ALIAS("REGION_BSS", RAM);
2520
 
2521
`B'
2522
     Program code and read-only data go into the `ROM'.  Read-write
2523
     data goes into the `RAM'.  An image of the initialized data is
2524
     loaded into the `ROM' and will be copied during system start into
2525
     the `RAM'.
2526
          MEMORY
2527
            {
2528
              ROM : ORIGIN = 0, LENGTH = 3M
2529
              RAM : ORIGIN = 0x10000000, LENGTH = 1M
2530
            }
2531
 
2532
          REGION_ALIAS("REGION_TEXT", ROM);
2533
          REGION_ALIAS("REGION_RODATA", ROM);
2534
          REGION_ALIAS("REGION_DATA", RAM);
2535
          REGION_ALIAS("REGION_BSS", RAM);
2536
 
2537
`C'
2538
     Program code goes into the `ROM'.  Read-only data goes into the
2539
     `ROM2'.  Read-write data goes into the `RAM'.  An image of the
2540
     initialized data is loaded into the `ROM2' and will be copied
2541
     during system start into the `RAM'.
2542
          MEMORY
2543
            {
2544
              ROM : ORIGIN = 0, LENGTH = 2M
2545
              ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
2546
              RAM : ORIGIN = 0x20000000, LENGTH = 1M
2547
            }
2548
 
2549
          REGION_ALIAS("REGION_TEXT", ROM);
2550
          REGION_ALIAS("REGION_RODATA", ROM2);
2551
          REGION_ALIAS("REGION_DATA", RAM);
2552
          REGION_ALIAS("REGION_BSS", RAM);
2553
 
2554
   It is possible to write a common system initialization routine to
2555
copy the `.data' section from `ROM' or `ROM2' into the `RAM' if
2556
necessary:
2557
     #include 
2558
 
2559
     extern char data_start [];
2560
     extern char data_size [];
2561
     extern char data_load_start [];
2562
 
2563
     void copy_data(void)
2564
     {
2565
       if (data_start != data_load_start)
2566
         {
2567
           memcpy(data_start, data_load_start, (size_t) data_size);
2568
         }
2569
     }
2570
 
2571

2572
File: ld.info,  Node: Miscellaneous Commands,  Prev: REGION_ALIAS,  Up: Simple Commands
2573
 
2574
3.4.5 Other Linker Script Commands
2575
----------------------------------
2576
 
2577
There are a few other linker scripts commands.
2578
 
2579
`ASSERT(EXP, MESSAGE)'
2580
     Ensure that EXP is non-zero.  If it is zero, then exit the linker
2581
     with an error code, and print MESSAGE.
2582
 
2583
`EXTERN(SYMBOL SYMBOL ...)'
2584
     Force SYMBOL to be entered in the output file as an undefined
2585
     symbol.  Doing this may, for example, trigger linking of additional
2586
     modules from standard libraries.  You may list several SYMBOLs for
2587
     each `EXTERN', and you may use `EXTERN' multiple times.  This
2588
     command has the same effect as the `-u' command-line option.
2589
 
2590
`FORCE_COMMON_ALLOCATION'
2591
     This command has the same effect as the `-d' command-line option:
2592
     to make `ld' assign space to common symbols even if a relocatable
2593
     output file is specified (`-r').
2594
 
2595
`INHIBIT_COMMON_ALLOCATION'
2596
     This command has the same effect as the `--no-define-common'
2597
     command-line option: to make `ld' omit the assignment of addresses
2598
     to common symbols even for a non-relocatable output file.
2599
 
2600
`INSERT [ AFTER | BEFORE ] OUTPUT_SECTION'
2601
     This command is typically used in a script specified by `-T' to
2602
     augment the default `SECTIONS' with, for example, overlays.  It
2603
     inserts all prior linker script statements after (or before)
2604
     OUTPUT_SECTION, and also causes `-T' to not override the default
2605
     linker script.  The exact insertion point is as for orphan
2606
     sections.  *Note Location Counter::.  The insertion happens after
2607
     the linker has mapped input sections to output sections.  Prior to
2608
     the insertion, since `-T' scripts are parsed before the default
2609
     linker script, statements in the `-T' script occur before the
2610
     default linker script statements in the internal linker
2611
     representation of the script.  In particular, input section
2612
     assignments will be made to `-T' output sections before those in
2613
     the default script.  Here is an example of how a `-T' script using
2614
     `INSERT' might look:
2615
 
2616
          SECTIONS
2617
          {
2618
            OVERLAY :
2619
            {
2620
              .ov1 { ov1*(.text) }
2621
              .ov2 { ov2*(.text) }
2622
            }
2623
          }
2624
          INSERT AFTER .text;
2625
 
2626
`NOCROSSREFS(SECTION SECTION ...)'
2627
     This command may be used to tell `ld' to issue an error about any
2628
     references among certain output sections.
2629
 
2630
     In certain types of programs, particularly on embedded systems when
2631
     using overlays, when one section is loaded into memory, another
2632
     section will not be.  Any direct references between the two
2633
     sections would be errors.  For example, it would be an error if
2634
     code in one section called a function defined in the other section.
2635
 
2636
     The `NOCROSSREFS' command takes a list of output section names.  If
2637
     `ld' detects any cross references between the sections, it reports
2638
     an error and returns a non-zero exit status.  Note that the
2639
     `NOCROSSREFS' command uses output section names, not input section
2640
     names.
2641
 
2642
`OUTPUT_ARCH(BFDARCH)'
2643
     Specify a particular output machine architecture.  The argument is
2644
     one of the names used by the BFD library (*note BFD::).  You can
2645
     see the architecture of an object file by using the `objdump'
2646
     program with the `-f' option.
2647
 
2648

2649
File: ld.info,  Node: Assignments,  Next: SECTIONS,  Prev: Simple Commands,  Up: Scripts
2650
 
2651
3.5 Assigning Values to Symbols
2652
===============================
2653
 
2654
You may assign a value to a symbol in a linker script.  This will define
2655
the symbol and place it into the symbol table with a global scope.
2656
 
2657
* Menu:
2658
 
2659
* Simple Assignments::          Simple Assignments
2660
* PROVIDE::                     PROVIDE
2661
* PROVIDE_HIDDEN::              PROVIDE_HIDDEN
2662
* Source Code Reference::       How to use a linker script defined symbol in source code
2663
 
2664

2665
File: ld.info,  Node: Simple Assignments,  Next: PROVIDE,  Up: Assignments
2666
 
2667
3.5.1 Simple Assignments
2668
------------------------
2669
 
2670
You may assign to a symbol using any of the C assignment operators:
2671
 
2672
`SYMBOL = EXPRESSION ;'
2673
`SYMBOL += EXPRESSION ;'
2674
`SYMBOL -= EXPRESSION ;'
2675
`SYMBOL *= EXPRESSION ;'
2676
`SYMBOL /= EXPRESSION ;'
2677
`SYMBOL <<= EXPRESSION ;'
2678
`SYMBOL >>= EXPRESSION ;'
2679
`SYMBOL &= EXPRESSION ;'
2680
`SYMBOL |= EXPRESSION ;'
2681
 
2682
   The first case will define SYMBOL to the value of EXPRESSION.  In
2683
the other cases, SYMBOL must already be defined, and the value will be
2684
adjusted accordingly.
2685
 
2686
   The special symbol name `.' indicates the location counter.  You may
2687
only use this within a `SECTIONS' command.  *Note Location Counter::.
2688
 
2689
   The semicolon after EXPRESSION is required.
2690
 
2691
   Expressions are defined below; see *Note Expressions::.
2692
 
2693
   You may write symbol assignments as commands in their own right, or
2694
as statements within a `SECTIONS' command, or as part of an output
2695
section description in a `SECTIONS' command.
2696
 
2697
   The section of the symbol will be set from the section of the
2698
expression; for more information, see *Note Expression Section::.
2699
 
2700
   Here is an example showing the three different places that symbol
2701
assignments may be used:
2702
 
2703
     floating_point = 0;
2704
     SECTIONS
2705
     {
2706
       .text :
2707
         {
2708
           *(.text)
2709
           _etext = .;
2710
         }
2711
       _bdata = (. + 3) & ~ 3;
2712
       .data : { *(.data) }
2713
     }
2714
   In this example, the symbol `floating_point' will be defined as
2715
zero.  The symbol `_etext' will be defined as the address following the
2716
last `.text' input section.  The symbol `_bdata' will be defined as the
2717
address following the `.text' output section aligned upward to a 4 byte
2718
boundary.
2719
 
2720

2721
File: ld.info,  Node: PROVIDE,  Next: PROVIDE_HIDDEN,  Prev: Simple Assignments,  Up: Assignments
2722
 
2723
3.5.2 PROVIDE
2724
-------------
2725
 
2726
In some cases, it is desirable for a linker script to define a symbol
2727
only if it is referenced and is not defined by any object included in
2728
the link.  For example, traditional linkers defined the symbol `etext'.
2729
However, ANSI C requires that the user be able to use `etext' as a
2730
function name without encountering an error.  The `PROVIDE' keyword may
2731
be used to define a symbol, such as `etext', only if it is referenced
2732
but not defined.  The syntax is `PROVIDE(SYMBOL = EXPRESSION)'.
2733
 
2734
   Here is an example of using `PROVIDE' to define `etext':
2735
     SECTIONS
2736
     {
2737
       .text :
2738
         {
2739
           *(.text)
2740
           _etext = .;
2741
           PROVIDE(etext = .);
2742
         }
2743
     }
2744
 
2745
   In this example, if the program defines `_etext' (with a leading
2746
underscore), the linker will give a multiple definition error.  If, on
2747
the other hand, the program defines `etext' (with no leading
2748
underscore), the linker will silently use the definition in the program.
2749
If the program references `etext' but does not define it, the linker
2750
will use the definition in the linker script.
2751
 
2752

2753
File: ld.info,  Node: PROVIDE_HIDDEN,  Next: Source Code Reference,  Prev: PROVIDE,  Up: Assignments
2754
 
2755
3.5.3 PROVIDE_HIDDEN
2756
--------------------
2757
 
2758
Similar to `PROVIDE'.  For ELF targeted ports, the symbol will be
2759
hidden and won't be exported.
2760
 
2761

2762
File: ld.info,  Node: Source Code Reference,  Prev: PROVIDE_HIDDEN,  Up: Assignments
2763
 
2764
3.5.4 Source Code Reference
2765
---------------------------
2766
 
2767
Accessing a linker script defined variable from source code is not
2768
intuitive.  In particular a linker script symbol is not equivalent to a
2769
variable declaration in a high level language, it is instead a symbol
2770
that does not have a value.
2771
 
2772
   Before going further, it is important to note that compilers often
2773
transform names in the source code into different names when they are
2774
stored in the symbol table.  For example, Fortran compilers commonly
2775
prepend or append an underscore, and C++ performs extensive `name
2776
mangling'.  Therefore there might be a discrepancy between the name of
2777
a variable as it is used in source code and the name of the same
2778
variable as it is defined in a linker script.  For example in C a
2779
linker script variable might be referred to as:
2780
 
2781
       extern int foo;
2782
 
2783
   But in the linker script it might be defined as:
2784
 
2785
       _foo = 1000;
2786
 
2787
   In the remaining examples however it is assumed that no name
2788
transformation has taken place.
2789
 
2790
   When a symbol is declared in a high level language such as C, two
2791
things happen.  The first is that the compiler reserves enough space in
2792
the program's memory to hold the _value_ of the symbol.  The second is
2793
that the compiler creates an entry in the program's symbol table which
2794
holds the symbol's _address_.  ie the symbol table contains the address
2795
of the block of memory holding the symbol's value.  So for example the
2796
following C declaration, at file scope:
2797
 
2798
       int foo = 1000;
2799
 
2800
   creates a entry called `foo' in the symbol table.  This entry holds
2801
the address of an `int' sized block of memory where the number 1000 is
2802
initially stored.
2803
 
2804
   When a program references a symbol the compiler generates code that
2805
first accesses the symbol table to find the address of the symbol's
2806
memory block and then code to read the value from that memory block.
2807
So:
2808
 
2809
       foo = 1;
2810
 
2811
   looks up the symbol `foo' in the symbol table, gets the address
2812
associated with this symbol and then writes the value 1 into that
2813
address.  Whereas:
2814
 
2815
       int * a = & foo;
2816
 
2817
   looks up the symbol `foo' in the symbol table, gets it address and
2818
then copies this address into the block of memory associated with the
2819
variable `a'.
2820
 
2821
   Linker scripts symbol declarations, by contrast, create an entry in
2822
the symbol table but do not assign any memory to them.  Thus they are
2823
an address without a value.  So for example the linker script
2824
definition:
2825
 
2826
       foo = 1000;
2827
 
2828
   creates an entry in the symbol table called `foo' which holds the
2829
address of memory location 1000, but nothing special is stored at
2830
address 1000.  This means that you cannot access the _value_ of a
2831
linker script defined symbol - it has no value - all you can do is
2832
access the _address_ of a linker script defined symbol.
2833
 
2834
   Hence when you are using a linker script defined symbol in source
2835
code you should always take the address of the symbol, and never
2836
attempt to use its value.  For example suppose you want to copy the
2837
contents of a section of memory called .ROM into a section called
2838
.FLASH and the linker script contains these declarations:
2839
 
2840
       start_of_ROM   = .ROM;
2841
       end_of_ROM     = .ROM + sizeof (.ROM) - 1;
2842
       start_of_FLASH = .FLASH;
2843
 
2844
   Then the C source code to perform the copy would be:
2845
 
2846
       extern char start_of_ROM, end_of_ROM, start_of_FLASH;
2847
 
2848
       memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
2849
 
2850
   Note the use of the `&' operators.  These are correct.
2851
 
2852

2853
File: ld.info,  Node: SECTIONS,  Next: MEMORY,  Prev: Assignments,  Up: Scripts
2854
 
2855
3.6 SECTIONS Command
2856
====================
2857
 
2858
The `SECTIONS' command tells the linker how to map input sections into
2859
output sections, and how to place the output sections in memory.
2860
 
2861
   The format of the `SECTIONS' command is:
2862
     SECTIONS
2863
     {
2864
       SECTIONS-COMMAND
2865
       SECTIONS-COMMAND
2866
       ...
2867
     }
2868
 
2869
   Each SECTIONS-COMMAND may of be one of the following:
2870
 
2871
   * an `ENTRY' command (*note Entry command: Entry Point.)
2872
 
2873
   * a symbol assignment (*note Assignments::)
2874
 
2875
   * an output section description
2876
 
2877
   * an overlay description
2878
 
2879
   The `ENTRY' command and symbol assignments are permitted inside the
2880
`SECTIONS' command for convenience in using the location counter in
2881
those commands.  This can also make the linker script easier to
2882
understand because you can use those commands at meaningful points in
2883
the layout of the output file.
2884
 
2885
   Output section descriptions and overlay descriptions are described
2886
below.
2887
 
2888
   If you do not use a `SECTIONS' command in your linker script, the
2889
linker will place each input section into an identically named output
2890
section in the order that the sections are first encountered in the
2891
input files.  If all input sections are present in the first file, for
2892
example, the order of sections in the output file will match the order
2893
in the first input file.  The first section will be at address zero.
2894
 
2895
* Menu:
2896
 
2897
* Output Section Description::  Output section description
2898
* Output Section Name::         Output section name
2899
* Output Section Address::      Output section address
2900
* Input Section::               Input section description
2901
* Output Section Data::         Output section data
2902
* Output Section Keywords::     Output section keywords
2903
* Output Section Discarding::   Output section discarding
2904
* Output Section Attributes::   Output section attributes
2905
* Overlay Description::         Overlay description
2906
 
2907

2908
File: ld.info,  Node: Output Section Description,  Next: Output Section Name,  Up: SECTIONS
2909
 
2910
3.6.1 Output Section Description
2911
--------------------------------
2912
 
2913
The full description of an output section looks like this:
2914
     SECTION [ADDRESS] [(TYPE)] :
2915
       [AT(LMA)]
2916
       [ALIGN(SECTION_ALIGN)]
2917
       [SUBALIGN(SUBSECTION_ALIGN)]
2918
       [CONSTRAINT]
2919
       {
2920
         OUTPUT-SECTION-COMMAND
2921
         OUTPUT-SECTION-COMMAND
2922
         ...
2923
       } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
2924
 
2925
   Most output sections do not use most of the optional section
2926
attributes.
2927
 
2928
   The whitespace around SECTION is required, so that the section name
2929
is unambiguous.  The colon and the curly braces are also required.  The
2930
line breaks and other white space are optional.
2931
 
2932
   Each OUTPUT-SECTION-COMMAND may be one of the following:
2933
 
2934
   * a symbol assignment (*note Assignments::)
2935
 
2936
   * an input section description (*note Input Section::)
2937
 
2938
   * data values to include directly (*note Output Section Data::)
2939
 
2940
   * a special output section keyword (*note Output Section Keywords::)
2941
 
2942

2943
File: ld.info,  Node: Output Section Name,  Next: Output Section Address,  Prev: Output Section Description,  Up: SECTIONS
2944
 
2945
3.6.2 Output Section Name
2946
-------------------------
2947
 
2948
The name of the output section is SECTION.  SECTION must meet the
2949
constraints of your output format.  In formats which only support a
2950
limited number of sections, such as `a.out', the name must be one of
2951
the names supported by the format (`a.out', for example, allows only
2952
`.text', `.data' or `.bss'). If the output format supports any number
2953
of sections, but with numbers and not names (as is the case for Oasys),
2954
the name should be supplied as a quoted numeric string.  A section name
2955
may consist of any sequence of characters, but a name which contains
2956
any unusual characters such as commas must be quoted.
2957
 
2958
   The output section name `/DISCARD/' is special; *Note Output Section
2959
Discarding::.
2960
 
2961

2962
File: ld.info,  Node: Output Section Address,  Next: Input Section,  Prev: Output Section Name,  Up: SECTIONS
2963
 
2964
3.6.3 Output Section Address
2965
----------------------------
2966
 
2967
The ADDRESS is an expression for the VMA (the virtual memory address)
2968
of the output section.  If you do not provide ADDRESS, the linker will
2969
set it based on REGION if present, or otherwise based on the current
2970
value of the location counter.
2971
 
2972
   If you provide ADDRESS, the address of the output section will be
2973
set to precisely that.  If you provide neither ADDRESS nor REGION, then
2974
the address of the output section will be set to the current value of
2975
the location counter aligned to the alignment requirements of the
2976
output section.  The alignment requirement of the output section is the
2977
strictest alignment of any input section contained within the output
2978
section.
2979
 
2980
   For example,
2981
     .text . : { *(.text) }
2982
   and
2983
     .text : { *(.text) }
2984
   are subtly different.  The first will set the address of the `.text'
2985
output section to the current value of the location counter.  The
2986
second will set it to the current value of the location counter aligned
2987
to the strictest alignment of a `.text' input section.
2988
 
2989
   The ADDRESS may be an arbitrary expression; *Note Expressions::.
2990
For example, if you want to align the section on a 0x10 byte boundary,
2991
so that the lowest four bits of the section address are zero, you could
2992
do something like this:
2993
     .text ALIGN(0x10) : { *(.text) }
2994
   This works because `ALIGN' returns the current location counter
2995
aligned upward to the specified value.
2996
 
2997
   Specifying ADDRESS for a section will change the value of the
2998
location counter, provided that the section is non-empty.  (Empty
2999
sections are ignored).
3000
 
3001

3002
File: ld.info,  Node: Input Section,  Next: Output Section Data,  Prev: Output Section Address,  Up: SECTIONS
3003
 
3004
3.6.4 Input Section Description
3005
-------------------------------
3006
 
3007
The most common output section command is an input section description.
3008
 
3009
   The input section description is the most basic linker script
3010
operation.  You use output sections to tell the linker how to lay out
3011
your program in memory.  You use input section descriptions to tell the
3012
linker how to map the input files into your memory layout.
3013
 
3014
* Menu:
3015
 
3016
* Input Section Basics::        Input section basics
3017
* Input Section Wildcards::     Input section wildcard patterns
3018
* Input Section Common::        Input section for common symbols
3019
* Input Section Keep::          Input section and garbage collection
3020
* Input Section Example::       Input section example
3021
 
3022

3023
File: ld.info,  Node: Input Section Basics,  Next: Input Section Wildcards,  Up: Input Section
3024
 
3025
3.6.4.1 Input Section Basics
3026
............................
3027
 
3028
An input section description consists of a file name optionally followed
3029
by a list of section names in parentheses.
3030
 
3031
   The file name and the section name may be wildcard patterns, which we
3032
describe further below (*note Input Section Wildcards::).
3033
 
3034
   The most common input section description is to include all input
3035
sections with a particular name in the output section.  For example, to
3036
include all input `.text' sections, you would write:
3037
     *(.text)
3038
   Here the `*' is a wildcard which matches any file name.  To exclude
3039
a list of files from matching the file name wildcard, EXCLUDE_FILE may
3040
be used to match all files except the ones specified in the
3041
EXCLUDE_FILE list.  For example:
3042
     *(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
3043
   will cause all .ctors sections from all files except `crtend.o' and
3044
`otherfile.o' to be included.
3045
 
3046
   There are two ways to include more than one section:
3047
     *(.text .rdata)
3048
     *(.text) *(.rdata)
3049
   The difference between these is the order in which the `.text' and
3050
`.rdata' input sections will appear in the output section.  In the
3051
first example, they will be intermingled, appearing in the same order as
3052
they are found in the linker input.  In the second example, all `.text'
3053
input sections will appear first, followed by all `.rdata' input
3054
sections.
3055
 
3056
   You can specify a file name to include sections from a particular
3057
file.  You would do this if one or more of your files contain special
3058
data that needs to be at a particular location in memory.  For example:
3059
     data.o(.data)
3060
 
3061
   You can also specify files within archives by writing a pattern
3062
matching the archive, a colon, then the pattern matching the file, with
3063
no whitespace around the colon.
3064
 
3065
`archive:file'
3066
     matches file within archive
3067
 
3068
`archive:'
3069
     matches the whole archive
3070
 
3071
`:file'
3072
     matches file but not one in an archive
3073
 
3074
   Either one or both of `archive' and `file' can contain shell
3075
wildcards.  On DOS based file systems, the linker will assume that a
3076
single letter followed by a colon is a drive specifier, so `c:myfile.o'
3077
is a simple file specification, not `myfile.o' within an archive called
3078
`c'.  `archive:file' filespecs may also be used within an
3079
`EXCLUDE_FILE' list, but may not appear in other linker script
3080
contexts.  For instance, you cannot extract a file from an archive by
3081
using `archive:file' in an `INPUT' command.
3082
 
3083
   If you use a file name without a list of sections, then all sections
3084
in the input file will be included in the output section.  This is not
3085
commonly done, but it may by useful on occasion.  For example:
3086
     data.o
3087
 
3088
   When you use a file name which is not an `archive:file' specifier
3089
and does not contain any wild card characters, the linker will first
3090
see if you also specified the file name on the linker command line or
3091
in an `INPUT' command.  If you did not, the linker will attempt to open
3092
the file as an input file, as though it appeared on the command line.
3093
Note that this differs from an `INPUT' command, because the linker will
3094
not search for the file in the archive search path.
3095
 
3096

3097
File: ld.info,  Node: Input Section Wildcards,  Next: Input Section Common,  Prev: Input Section Basics,  Up: Input Section
3098
 
3099
3.6.4.2 Input Section Wildcard Patterns
3100
.......................................
3101
 
3102
In an input section description, either the file name or the section
3103
name or both may be wildcard patterns.
3104
 
3105
   The file name of `*' seen in many examples is a simple wildcard
3106
pattern for the file name.
3107
 
3108
   The wildcard patterns are like those used by the Unix shell.
3109
 
3110
`*'
3111
     matches any number of characters
3112
 
3113
`?'
3114
     matches any single character
3115
 
3116
`[CHARS]'
3117
     matches a single instance of any of the CHARS; the `-' character
3118
     may be used to specify a range of characters, as in `[a-z]' to
3119
     match any lower case letter
3120
 
3121
`\'
3122
     quotes the following character
3123
 
3124
   When a file name is matched with a wildcard, the wildcard characters
3125
will not match a `/' character (used to separate directory names on
3126
Unix).  A pattern consisting of a single `*' character is an exception;
3127
it will always match any file name, whether it contains a `/' or not.
3128
In a section name, the wildcard characters will match a `/' character.
3129
 
3130
   File name wildcard patterns only match files which are explicitly
3131
specified on the command line or in an `INPUT' command.  The linker
3132
does not search directories to expand wildcards.
3133
 
3134
   If a file name matches more than one wildcard pattern, or if a file
3135
name appears explicitly and is also matched by a wildcard pattern, the
3136
linker will use the first match in the linker script.  For example, this
3137
sequence of input section descriptions is probably in error, because the
3138
`data.o' rule will not be used:
3139
     .data : { *(.data) }
3140
     .data1 : { data.o(.data) }
3141
 
3142
   Normally, the linker will place files and sections matched by
3143
wildcards in the order in which they are seen during the link.  You can
3144
change this by using the `SORT_BY_NAME' keyword, which appears before a
3145
wildcard pattern in parentheses (e.g., `SORT_BY_NAME(.text*)').  When
3146
the `SORT_BY_NAME' keyword is used, the linker will sort the files or
3147
sections into ascending order by name before placing them in the output
3148
file.
3149
 
3150
   `SORT_BY_ALIGNMENT' is very similar to `SORT_BY_NAME'. The
3151
difference is `SORT_BY_ALIGNMENT' will sort sections into ascending
3152
order by alignment before placing them in the output file.
3153
 
3154
   `SORT' is an alias for `SORT_BY_NAME'.
3155
 
3156
   When there are nested section sorting commands in linker script,
3157
there can be at most 1 level of nesting for section sorting commands.
3158
 
3159
  1. `SORT_BY_NAME' (`SORT_BY_ALIGNMENT' (wildcard section pattern)).
3160
     It will sort the input sections by name first, then by alignment
3161
     if 2 sections have the same name.
3162
 
3163
  2. `SORT_BY_ALIGNMENT' (`SORT_BY_NAME' (wildcard section pattern)).
3164
     It will sort the input sections by alignment first, then by name
3165
     if 2 sections have the same alignment.
3166
 
3167
  3. `SORT_BY_NAME' (`SORT_BY_NAME' (wildcard section pattern)) is
3168
     treated the same as `SORT_BY_NAME' (wildcard section pattern).
3169
 
3170
  4. `SORT_BY_ALIGNMENT' (`SORT_BY_ALIGNMENT' (wildcard section
3171
     pattern)) is treated the same as `SORT_BY_ALIGNMENT' (wildcard
3172
     section pattern).
3173
 
3174
  5. All other nested section sorting commands are invalid.
3175
 
3176
   When both command line section sorting option and linker script
3177
section sorting command are used, section sorting command always takes
3178
precedence over the command line option.
3179
 
3180
   If the section sorting command in linker script isn't nested, the
3181
command line option will make the section sorting command to be treated
3182
as nested sorting command.
3183
 
3184
  1. `SORT_BY_NAME' (wildcard section pattern ) with `--sort-sections
3185
     alignment' is equivalent to `SORT_BY_NAME' (`SORT_BY_ALIGNMENT'
3186
     (wildcard section pattern)).
3187
 
3188
  2. `SORT_BY_ALIGNMENT' (wildcard section pattern) with
3189
     `--sort-section name' is equivalent to `SORT_BY_ALIGNMENT'
3190
     (`SORT_BY_NAME' (wildcard section pattern)).
3191
 
3192
   If the section sorting command in linker script is nested, the
3193
command line option will be ignored.
3194
 
3195
   If you ever get confused about where input sections are going, use
3196
the `-M' linker option to generate a map file.  The map file shows
3197
precisely how input sections are mapped to output sections.
3198
 
3199
   This example shows how wildcard patterns might be used to partition
3200
files.  This linker script directs the linker to place all `.text'
3201
sections in `.text' and all `.bss' sections in `.bss'.  The linker will
3202
place the `.data' section from all files beginning with an upper case
3203
character in `.DATA'; for all other files, the linker will place the
3204
`.data' section in `.data'.
3205
     SECTIONS {
3206
       .text : { *(.text) }
3207
       .DATA : { [A-Z]*(.data) }
3208
       .data : { *(.data) }
3209
       .bss : { *(.bss) }
3210
     }
3211
 
3212

3213
File: ld.info,  Node: Input Section Common,  Next: Input Section Keep,  Prev: Input Section Wildcards,  Up: Input Section
3214
 
3215
3.6.4.3 Input Section for Common Symbols
3216
........................................
3217
 
3218
A special notation is needed for common symbols, because in many object
3219
file formats common symbols do not have a particular input section.  The
3220
linker treats common symbols as though they are in an input section
3221
named `COMMON'.
3222
 
3223
   You may use file names with the `COMMON' section just as with any
3224
other input sections.  You can use this to place common symbols from a
3225
particular input file in one section while common symbols from other
3226
input files are placed in another section.
3227
 
3228
   In most cases, common symbols in input files will be placed in the
3229
`.bss' section in the output file.  For example:
3230
     .bss { *(.bss) *(COMMON) }
3231
 
3232
   Some object file formats have more than one type of common symbol.
3233
For example, the MIPS ELF object file format distinguishes standard
3234
common symbols and small common symbols.  In this case, the linker will
3235
use a different special section name for other types of common symbols.
3236
In the case of MIPS ELF, the linker uses `COMMON' for standard common
3237
symbols and `.scommon' for small common symbols.  This permits you to
3238
map the different types of common symbols into memory at different
3239
locations.
3240
 
3241
   You will sometimes see `[COMMON]' in old linker scripts.  This
3242
notation is now considered obsolete.  It is equivalent to `*(COMMON)'.
3243
 
3244

3245
File: ld.info,  Node: Input Section Keep,  Next: Input Section Example,  Prev: Input Section Common,  Up: Input Section
3246
 
3247
3.6.4.4 Input Section and Garbage Collection
3248
............................................
3249
 
3250
When link-time garbage collection is in use (`--gc-sections'), it is
3251
often useful to mark sections that should not be eliminated.  This is
3252
accomplished by surrounding an input section's wildcard entry with
3253
`KEEP()', as in `KEEP(*(.init))' or `KEEP(SORT_BY_NAME(*)(.ctors))'.
3254
 
3255

3256
File: ld.info,  Node: Input Section Example,  Prev: Input Section Keep,  Up: Input Section
3257
 
3258
3.6.4.5 Input Section Example
3259
.............................
3260
 
3261
The following example is a complete linker script.  It tells the linker
3262
to read all of the sections from file `all.o' and place them at the
3263
start of output section `outputa' which starts at location `0x10000'.
3264
All of section `.input1' from file `foo.o' follows immediately, in the
3265
same output section.  All of section `.input2' from `foo.o' goes into
3266
output section `outputb', followed by section `.input1' from `foo1.o'.
3267
All of the remaining `.input1' and `.input2' sections from any files
3268
are written to output section `outputc'.
3269
 
3270
     SECTIONS {
3271
       outputa 0x10000 :
3272
         {
3273
         all.o
3274
         foo.o (.input1)
3275
         }
3276
       outputb :
3277
         {
3278
         foo.o (.input2)
3279
         foo1.o (.input1)
3280
         }
3281
       outputc :
3282
         {
3283
         *(.input1)
3284
         *(.input2)
3285
         }
3286
     }
3287
 
3288

3289
File: ld.info,  Node: Output Section Data,  Next: Output Section Keywords,  Prev: Input Section,  Up: SECTIONS
3290
 
3291
3.6.5 Output Section Data
3292
-------------------------
3293
 
3294
You can include explicit bytes of data in an output section by using
3295
`BYTE', `SHORT', `LONG', `QUAD', or `SQUAD' as an output section
3296
command.  Each keyword is followed by an expression in parentheses
3297
providing the value to store (*note Expressions::).  The value of the
3298
expression is stored at the current value of the location counter.
3299
 
3300
   The `BYTE', `SHORT', `LONG', and `QUAD' commands store one, two,
3301
four, and eight bytes (respectively).  After storing the bytes, the
3302
location counter is incremented by the number of bytes stored.
3303
 
3304
   For example, this will store the byte 1 followed by the four byte
3305
value of the symbol `addr':
3306
     BYTE(1)
3307
     LONG(addr)
3308
 
3309
   When using a 64 bit host or target, `QUAD' and `SQUAD' are the same;
3310
they both store an 8 byte, or 64 bit, value.  When both host and target
3311
are 32 bits, an expression is computed as 32 bits.  In this case `QUAD'
3312
stores a 32 bit value zero extended to 64 bits, and `SQUAD' stores a 32
3313
bit value sign extended to 64 bits.
3314
 
3315
   If the object file format of the output file has an explicit
3316
endianness, which is the normal case, the value will be stored in that
3317
endianness.  When the object file format does not have an explicit
3318
endianness, as is true of, for example, S-records, the value will be
3319
stored in the endianness of the first input object file.
3320
 
3321
   Note--these commands only work inside a section description and not
3322
between them, so the following will produce an error from the linker:
3323
     SECTIONS { .text : { *(.text) } LONG(1) .data : { *(.data) } }
3324
   whereas this will work:
3325
     SECTIONS { .text : { *(.text) ; LONG(1) } .data : { *(.data) } }
3326
 
3327
   You may use the `FILL' command to set the fill pattern for the
3328
current section.  It is followed by an expression in parentheses.  Any
3329
otherwise unspecified regions of memory within the section (for example,
3330
gaps left due to the required alignment of input sections) are filled
3331
with the value of the expression, repeated as necessary.  A `FILL'
3332
statement covers memory locations after the point at which it occurs in
3333
the section definition; by including more than one `FILL' statement,
3334
you can have different fill patterns in different parts of an output
3335
section.
3336
 
3337
   This example shows how to fill unspecified regions of memory with the
3338
value `0x90':
3339
     FILL(0x90909090)
3340
 
3341
   The `FILL' command is similar to the `=FILLEXP' output section
3342
attribute, but it only affects the part of the section following the
3343
`FILL' command, rather than the entire section.  If both are used, the
3344
`FILL' command takes precedence.  *Note Output Section Fill::, for
3345
details on the fill expression.
3346
 
3347

3348
File: ld.info,  Node: Output Section Keywords,  Next: Output Section Discarding,  Prev: Output Section Data,  Up: SECTIONS
3349
 
3350
3.6.6 Output Section Keywords
3351
-----------------------------
3352
 
3353
There are a couple of keywords which can appear as output section
3354
commands.
3355
 
3356
`CREATE_OBJECT_SYMBOLS'
3357
     The command tells the linker to create a symbol for each input
3358
     file.  The name of each symbol will be the name of the
3359
     corresponding input file.  The section of each symbol will be the
3360
     output section in which the `CREATE_OBJECT_SYMBOLS' command
3361
     appears.
3362
 
3363
     This is conventional for the a.out object file format.  It is not
3364
     normally used for any other object file format.
3365
 
3366
`CONSTRUCTORS'
3367
     When linking using the a.out object file format, the linker uses an
3368
     unusual set construct to support C++ global constructors and
3369
     destructors.  When linking object file formats which do not support
3370
     arbitrary sections, such as ECOFF and XCOFF, the linker will
3371
     automatically recognize C++ global constructors and destructors by
3372
     name.  For these object file formats, the `CONSTRUCTORS' command
3373
     tells the linker to place constructor information in the output
3374
     section where the `CONSTRUCTORS' command appears.  The
3375
     `CONSTRUCTORS' command is ignored for other object file formats.
3376
 
3377
     The symbol `__CTOR_LIST__' marks the start of the global
3378
     constructors, and the symbol `__CTOR_END__' marks the end.
3379
     Similarly, `__DTOR_LIST__' and `__DTOR_END__' mark the start and
3380
     end of the global destructors.  The first word in the list is the
3381
     number of entries, followed by the address of each constructor or
3382
     destructor, followed by a zero word.  The compiler must arrange to
3383
     actually run the code.  For these object file formats GNU C++
3384
     normally calls constructors from a subroutine `__main'; a call to
3385
     `__main' is automatically inserted into the startup code for
3386
     `main'.  GNU C++ normally runs destructors either by using
3387
     `atexit', or directly from the function `exit'.
3388
 
3389
     For object file formats such as `COFF' or `ELF' which support
3390
     arbitrary section names, GNU C++ will normally arrange to put the
3391
     addresses of global constructors and destructors into the `.ctors'
3392
     and `.dtors' sections.  Placing the following sequence into your
3393
     linker script will build the sort of table which the GNU C++
3394
     runtime code expects to see.
3395
 
3396
                __CTOR_LIST__ = .;
3397
                LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
3398
                *(.ctors)
3399
                LONG(0)
3400
                __CTOR_END__ = .;
3401
                __DTOR_LIST__ = .;
3402
                LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
3403
                *(.dtors)
3404
                LONG(0)
3405
                __DTOR_END__ = .;
3406
 
3407
     If you are using the GNU C++ support for initialization priority,
3408
     which provides some control over the order in which global
3409
     constructors are run, you must sort the constructors at link time
3410
     to ensure that they are executed in the correct order.  When using
3411
     the `CONSTRUCTORS' command, use `SORT_BY_NAME(CONSTRUCTORS)'
3412
     instead.  When using the `.ctors' and `.dtors' sections, use
3413
     `*(SORT_BY_NAME(.ctors))' and `*(SORT_BY_NAME(.dtors))' instead of
3414
     just `*(.ctors)' and `*(.dtors)'.
3415
 
3416
     Normally the compiler and linker will handle these issues
3417
     automatically, and you will not need to concern yourself with
3418
     them.  However, you may need to consider this if you are using C++
3419
     and writing your own linker scripts.
3420
 
3421
 
3422

3423
File: ld.info,  Node: Output Section Discarding,  Next: Output Section Attributes,  Prev: Output Section Keywords,  Up: SECTIONS
3424
 
3425
3.6.7 Output Section Discarding
3426
-------------------------------
3427
 
3428
The linker will not create output sections with no contents.  This is
3429
for convenience when referring to input sections that may or may not be
3430
present in any of the input files.  For example:
3431
     .foo : { *(.foo) }
3432
   will only create a `.foo' section in the output file if there is a
3433
`.foo' section in at least one input file, and if the input sections
3434
are not all empty.  Other link script directives that allocate space in
3435
an output section will also create the output section.
3436
 
3437
   The linker will ignore address assignments (*note Output Section
3438
Address::) on discarded output sections, except when the linker script
3439
defines symbols in the output section.  In that case the linker will
3440
obey the address assignments, possibly advancing dot even though the
3441
section is discarded.
3442
 
3443
   The special output section name `/DISCARD/' may be used to discard
3444
input sections.  Any input sections which are assigned to an output
3445
section named `/DISCARD/' are not included in the output file.
3446
 
3447

3448
File: ld.info,  Node: Output Section Attributes,  Next: Overlay Description,  Prev: Output Section Discarding,  Up: SECTIONS
3449
 
3450
3.6.8 Output Section Attributes
3451
-------------------------------
3452
 
3453
We showed above that the full description of an output section looked
3454
like this:
3455
 
3456
     SECTION [ADDRESS] [(TYPE)] :
3457
       [AT(LMA)]
3458
       [ALIGN(SECTION_ALIGN)]
3459
       [SUBALIGN(SUBSECTION_ALIGN)]
3460
       [CONSTRAINT]
3461
       {
3462
         OUTPUT-SECTION-COMMAND
3463
         OUTPUT-SECTION-COMMAND
3464
         ...
3465
       } [>REGION] [AT>LMA_REGION] [:PHDR :PHDR ...] [=FILLEXP]
3466
 
3467
   We've already described SECTION, ADDRESS, and
3468
OUTPUT-SECTION-COMMAND.  In this section we will describe the remaining
3469
section attributes.
3470
 
3471
* Menu:
3472
 
3473
* Output Section Type::         Output section type
3474
* Output Section LMA::          Output section LMA
3475
* Forced Output Alignment::     Forced Output Alignment
3476
* Forced Input Alignment::      Forced Input Alignment
3477
* Output Section Constraint::   Output section constraint
3478
* Output Section Region::       Output section region
3479
* Output Section Phdr::         Output section phdr
3480
* Output Section Fill::         Output section fill
3481
 
3482

3483
File: ld.info,  Node: Output Section Type,  Next: Output Section LMA,  Up: Output Section Attributes
3484
 
3485
3.6.8.1 Output Section Type
3486
...........................
3487
 
3488
Each output section may have a type.  The type is a keyword in
3489
parentheses.  The following types are defined:
3490
 
3491
`NOLOAD'
3492
     The section should be marked as not loadable, so that it will not
3493
     be loaded into memory when the program is run.
3494
 
3495
`DSECT'
3496
`COPY'
3497
`INFO'
3498
`OVERLAY'
3499
     These type names are supported for backward compatibility, and are
3500
     rarely used.  They all have the same effect: the section should be
3501
     marked as not allocatable, so that no memory is allocated for the
3502
     section when the program is run.
3503
 
3504
   The linker normally sets the attributes of an output section based on
3505
the input sections which map into it.  You can override this by using
3506
the section type.  For example, in the script sample below, the `ROM'
3507
section is addressed at memory location `0' and does not need to be
3508
loaded when the program is run.  The contents of the `ROM' section will
3509
appear in the linker output file as usual.
3510
     SECTIONS {
3511
       ROM 0 (NOLOAD) : { ... }
3512
       ...
3513
     }
3514
 
3515

3516
File: ld.info,  Node: Output Section LMA,  Next: Forced Output Alignment,  Prev: Output Section Type,  Up: Output Section Attributes
3517
 
3518
3.6.8.2 Output Section LMA
3519
..........................
3520
 
3521
Every section has a virtual address (VMA) and a load address (LMA); see
3522
*Note Basic Script Concepts::.  The address expression which may appear
3523
in an output section description sets the VMA (*note Output Section
3524
Address::).
3525
 
3526
   The expression LMA that follows the `AT' keyword specifies the load
3527
address of the section.
3528
 
3529
   Alternatively, with `AT>LMA_REGION' expression, you may specify a
3530
memory region for the section's load address. *Note MEMORY::.  Note
3531
that if the section has not had a VMA assigned to it then the linker
3532
will use the LMA_REGION as the VMA region as well.
3533
 
3534
   If neither `AT' nor `AT>' is specified for an allocatable section,
3535
the linker will set the LMA such that the difference between VMA and
3536
LMA for the section is the same as the preceding output section in the
3537
same region.  If there is no preceding output section or the section is
3538
not allocatable, the linker will set the LMA equal to the VMA.  *Note
3539
Output Section Region::.
3540
 
3541
   This feature is designed to make it easy to build a ROM image.  For
3542
example, the following linker script creates three output sections: one
3543
called `.text', which starts at `0x1000', one called `.mdata', which is
3544
loaded at the end of the `.text' section even though its VMA is
3545
`0x2000', and one called `.bss' to hold uninitialized data at address
3546
`0x3000'.  The symbol `_data' is defined with the value `0x2000', which
3547
shows that the location counter holds the VMA value, not the LMA value.
3548
 
3549
     SECTIONS
3550
       {
3551
       .text 0x1000 : { *(.text) _etext = . ; }
3552
       .mdata 0x2000 :
3553
         AT ( ADDR (.text) + SIZEOF (.text) )
3554
         { _data = . ; *(.data); _edata = . ;  }
3555
       .bss 0x3000 :
3556
         { _bstart = . ;  *(.bss) *(COMMON) ; _bend = . ;}
3557
     }
3558
 
3559
   The run-time initialization code for use with a program generated
3560
with this linker script would include something like the following, to
3561
copy the initialized data from the ROM image to its runtime address.
3562
Notice how this code takes advantage of the symbols defined by the
3563
linker script.
3564
 
3565
     extern char _etext, _data, _edata, _bstart, _bend;
3566
     char *src = &_etext;
3567
     char *dst = &_data;
3568
 
3569
     /* ROM has data at end of text; copy it. */
3570
     while (dst < &_edata) {
3571
       *dst++ = *src++;
3572
     }
3573
 
3574
     /* Zero bss */
3575
     for (dst = &_bstart; dst< &_bend; dst++)
3576
       *dst = 0;
3577
 
3578

3579
File: ld.info,  Node: Forced Output Alignment,  Next: Forced Input Alignment,  Prev: Output Section LMA,  Up: Output Section Attributes
3580
 
3581
3.6.8.3 Forced Output Alignment
3582
...............................
3583
 
3584
You can increase an output section's alignment by using ALIGN.
3585
 
3586

3587
File: ld.info,  Node: Forced Input Alignment,  Next: Output Section Constraint,  Prev: Forced Output Alignment,  Up: Output Section Attributes
3588
 
3589
3.6.8.4 Forced Input Alignment
3590
..............................
3591
 
3592
You can force input section alignment within an output section by using
3593
SUBALIGN.  The value specified overrides any alignment given by input
3594
sections, whether larger or smaller.
3595
 
3596

3597
File: ld.info,  Node: Output Section Constraint,  Next: Output Section Region,  Prev: Forced Input Alignment,  Up: Output Section Attributes
3598
 
3599
3.6.8.5 Output Section Constraint
3600
.................................
3601
 
3602
You can specify that an output section should only be created if all of
3603
its input sections are read-only or all of its input sections are
3604
read-write by using the keyword `ONLY_IF_RO' and `ONLY_IF_RW'
3605
respectively.
3606
 
3607

3608
File: ld.info,  Node: Output Section Region,  Next: Output Section Phdr,  Prev: Output Section Constraint,  Up: Output Section Attributes
3609
 
3610
3.6.8.6 Output Section Region
3611
.............................
3612
 
3613
You can assign a section to a previously defined region of memory by
3614
using `>REGION'.  *Note MEMORY::.
3615
 
3616
   Here is a simple example:
3617
     MEMORY { rom : ORIGIN = 0x1000, LENGTH = 0x1000 }
3618
     SECTIONS { ROM : { *(.text) } >rom }
3619
 
3620

3621
File: ld.info,  Node: Output Section Phdr,  Next: Output Section Fill,  Prev: Output Section Region,  Up: Output Section Attributes
3622
 
3623
3.6.8.7 Output Section Phdr
3624
...........................
3625
 
3626
You can assign a section to a previously defined program segment by
3627
using `:PHDR'.  *Note PHDRS::.  If a section is assigned to one or more
3628
segments, then all subsequent allocated sections will be assigned to
3629
those segments as well, unless they use an explicitly `:PHDR' modifier.
3630
You can use `:NONE' to tell the linker to not put the section in any
3631
segment at all.
3632
 
3633
   Here is a simple example:
3634
     PHDRS { text PT_LOAD ; }
3635
     SECTIONS { .text : { *(.text) } :text }
3636
 
3637

3638
File: ld.info,  Node: Output Section Fill,  Prev: Output Section Phdr,  Up: Output Section Attributes
3639
 
3640
3.6.8.8 Output Section Fill
3641
...........................
3642
 
3643
You can set the fill pattern for an entire section by using `=FILLEXP'.
3644
FILLEXP is an expression (*note Expressions::).  Any otherwise
3645
unspecified regions of memory within the output section (for example,
3646
gaps left due to the required alignment of input sections) will be
3647
filled with the value, repeated as necessary.  If the fill expression
3648
is a simple hex number, ie. a string of hex digit starting with `0x'
3649
and without a trailing `k' or `M', then an arbitrarily long sequence of
3650
hex digits can be used to specify the fill pattern;  Leading zeros
3651
become part of the pattern too.  For all other cases, including extra
3652
parentheses or a unary `+', the fill pattern is the four least
3653
significant bytes of the value of the expression.  In all cases, the
3654
number is big-endian.
3655
 
3656
   You can also change the fill value with a `FILL' command in the
3657
output section commands; (*note Output Section Data::).
3658
 
3659
   Here is a simple example:
3660
     SECTIONS { .text : { *(.text) } =0x90909090 }
3661
 
3662

3663
File: ld.info,  Node: Overlay Description,  Prev: Output Section Attributes,  Up: SECTIONS
3664
 
3665
3.6.9 Overlay Description
3666
-------------------------
3667
 
3668
An overlay description provides an easy way to describe sections which
3669
are to be loaded as part of a single memory image but are to be run at
3670
the same memory address.  At run time, some sort of overlay manager will
3671
copy the overlaid sections in and out of the runtime memory address as
3672
required, perhaps by simply manipulating addressing bits.  This approach
3673
can be useful, for example, when a certain region of memory is faster
3674
than another.
3675
 
3676
   Overlays are described using the `OVERLAY' command.  The `OVERLAY'
3677
command is used within a `SECTIONS' command, like an output section
3678
description.  The full syntax of the `OVERLAY' command is as follows:
3679
     OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )]
3680
       {
3681
         SECNAME1
3682
           {
3683
             OUTPUT-SECTION-COMMAND
3684
             OUTPUT-SECTION-COMMAND
3685
             ...
3686
           } [:PHDR...] [=FILL]
3687
         SECNAME2
3688
           {
3689
             OUTPUT-SECTION-COMMAND
3690
             OUTPUT-SECTION-COMMAND
3691
             ...
3692
           } [:PHDR...] [=FILL]
3693
         ...
3694
       } [>REGION] [:PHDR...] [=FILL]
3695
 
3696
   Everything is optional except `OVERLAY' (a keyword), and each
3697
section must have a name (SECNAME1 and SECNAME2 above).  The section
3698
definitions within the `OVERLAY' construct are identical to those
3699
within the general `SECTIONS' contruct (*note SECTIONS::), except that
3700
no addresses and no memory regions may be defined for sections within
3701
an `OVERLAY'.
3702
 
3703
   The sections are all defined with the same starting address.  The
3704
load addresses of the sections are arranged such that they are
3705
consecutive in memory starting at the load address used for the
3706
`OVERLAY' as a whole (as with normal section definitions, the load
3707
address is optional, and defaults to the start address; the start
3708
address is also optional, and defaults to the current value of the
3709
location counter).
3710
 
3711
   If the `NOCROSSREFS' keyword is used, and there any references among
3712
the sections, the linker will report an error.  Since the sections all
3713
run at the same address, it normally does not make sense for one
3714
section to refer directly to another.  *Note NOCROSSREFS: Miscellaneous
3715
Commands.
3716
 
3717
   For each section within the `OVERLAY', the linker automatically
3718
provides two symbols.  The symbol `__load_start_SECNAME' is defined as
3719
the starting load address of the section.  The symbol
3720
`__load_stop_SECNAME' is defined as the final load address of the
3721
section.  Any characters within SECNAME which are not legal within C
3722
identifiers are removed.  C (or assembler) code may use these symbols
3723
to move the overlaid sections around as necessary.
3724
 
3725
   At the end of the overlay, the value of the location counter is set
3726
to the start address of the overlay plus the size of the largest
3727
section.
3728
 
3729
   Here is an example.  Remember that this would appear inside a
3730
`SECTIONS' construct.
3731
       OVERLAY 0x1000 : AT (0x4000)
3732
        {
3733
          .text0 { o1/*.o(.text) }
3734
          .text1 { o2/*.o(.text) }
3735
        }
3736
This will define both `.text0' and `.text1' to start at address
3737
0x1000.  `.text0' will be loaded at address 0x4000, and `.text1' will
3738
be loaded immediately after `.text0'.  The following symbols will be
3739
defined if referenced: `__load_start_text0', `__load_stop_text0',
3740
`__load_start_text1', `__load_stop_text1'.
3741
 
3742
   C code to copy overlay `.text1' into the overlay area might look
3743
like the following.
3744
 
3745
       extern char __load_start_text1, __load_stop_text1;
3746
       memcpy ((char *) 0x1000, &__load_start_text1,
3747
               &__load_stop_text1 - &__load_start_text1);
3748
 
3749
   Note that the `OVERLAY' command is just syntactic sugar, since
3750
everything it does can be done using the more basic commands.  The above
3751
example could have been written identically as follows.
3752
 
3753
       .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
3754
       PROVIDE (__load_start_text0 = LOADADDR (.text0));
3755
       PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
3756
       .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
3757
       PROVIDE (__load_start_text1 = LOADADDR (.text1));
3758
       PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
3759
       . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
3760
 
3761

3762
File: ld.info,  Node: MEMORY,  Next: PHDRS,  Prev: SECTIONS,  Up: Scripts
3763
 
3764
3.7 MEMORY Command
3765
==================
3766
 
3767
The linker's default configuration permits allocation of all available
3768
memory.  You can override this by using the `MEMORY' command.
3769
 
3770
   The `MEMORY' command describes the location and size of blocks of
3771
memory in the target.  You can use it to describe which memory regions
3772
may be used by the linker, and which memory regions it must avoid.  You
3773
can then assign sections to particular memory regions.  The linker will
3774
set section addresses based on the memory regions, and will warn about
3775
regions that become too full.  The linker will not shuffle sections
3776
around to fit into the available regions.
3777
 
3778
   A linker script may contain at most one use of the `MEMORY' command.
3779
However, you can define as many blocks of memory within it as you
3780
wish.  The syntax is:
3781
     MEMORY
3782
       {
3783
         NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
3784
         ...
3785
       }
3786
 
3787
   The NAME is a name used in the linker script to refer to the region.
3788
The region name has no meaning outside of the linker script.  Region
3789
names are stored in a separate name space, and will not conflict with
3790
symbol names, file names, or section names.  Each memory region must
3791
have a distinct name within the `MEMORY' command.  However you can add
3792
later alias names to existing memory regions with the *Note
3793
REGION_ALIAS:: command.
3794
 
3795
   The ATTR string is an optional list of attributes that specify
3796
whether to use a particular memory region for an input section which is
3797
not explicitly mapped in the linker script.  As described in *Note
3798
SECTIONS::, if you do not specify an output section for some input
3799
section, the linker will create an output section with the same name as
3800
the input section.  If you define region attributes, the linker will use
3801
them to select the memory region for the output section that it creates.
3802
 
3803
   The ATTR string must consist only of the following characters:
3804
`R'
3805
     Read-only section
3806
 
3807
`W'
3808
     Read/write section
3809
 
3810
`X'
3811
     Executable section
3812
 
3813
`A'
3814
     Allocatable section
3815
 
3816
`I'
3817
     Initialized section
3818
 
3819
`L'
3820
     Same as `I'
3821
 
3822
`!'
3823
     Invert the sense of any of the preceding attributes
3824
 
3825
   If a unmapped section matches any of the listed attributes other than
3826
`!', it will be placed in the memory region.  The `!' attribute
3827
reverses this test, so that an unmapped section will be placed in the
3828
memory region only if it does not match any of the listed attributes.
3829
 
3830
   The ORIGIN is an numerical expression for the start address of the
3831
memory region.  The expression must evaluate to a constant and it
3832
cannot involve any symbols.  The keyword `ORIGIN' may be abbreviated to
3833
`org' or `o' (but not, for example, `ORG').
3834
 
3835
   The LEN is an expression for the size in bytes of the memory region.
3836
As with the ORIGIN expression, the expression must be numerical only
3837
and must evaluate to a constant.  The keyword `LENGTH' may be
3838
abbreviated to `len' or `l'.
3839
 
3840
   In the following example, we specify that there are two memory
3841
regions available for allocation: one starting at `0' for 256 kilobytes,
3842
and the other starting at `0x40000000' for four megabytes.  The linker
3843
will place into the `rom' memory region every section which is not
3844
explicitly mapped into a memory region, and is either read-only or
3845
executable.  The linker will place other sections which are not
3846
explicitly mapped into a memory region into the `ram' memory region.
3847
 
3848
     MEMORY
3849
       {
3850
         rom (rx)  : ORIGIN = 0, LENGTH = 256K
3851
         ram (!rx) : org = 0x40000000, l = 4M
3852
       }
3853
 
3854
   Once you define a memory region, you can direct the linker to place
3855
specific output sections into that memory region by using the `>REGION'
3856
output section attribute.  For example, if you have a memory region
3857
named `mem', you would use `>mem' in the output section definition.
3858
*Note Output Section Region::.  If no address was specified for the
3859
output section, the linker will set the address to the next available
3860
address within the memory region.  If the combined output sections
3861
directed to a memory region are too large for the region, the linker
3862
will issue an error message.
3863
 
3864
   It is possible to access the origin and length of a memory in an
3865
expression via the `ORIGIN(MEMORY)' and `LENGTH(MEMORY)' functions:
3866
 
3867
       _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
3868
 
3869

3870
File: ld.info,  Node: PHDRS,  Next: VERSION,  Prev: MEMORY,  Up: Scripts
3871
 
3872
3.8 PHDRS Command
3873
=================
3874
 
3875
The ELF object file format uses "program headers", also knows as
3876
"segments".  The program headers describe how the program should be
3877
loaded into memory.  You can print them out by using the `objdump'
3878
program with the `-p' option.
3879
 
3880
   When you run an ELF program on a native ELF system, the system loader
3881
reads the program headers in order to figure out how to load the
3882
program.  This will only work if the program headers are set correctly.
3883
This manual does not describe the details of how the system loader
3884
interprets program headers; for more information, see the ELF ABI.
3885
 
3886
   The linker will create reasonable program headers by default.
3887
However, in some cases, you may need to specify the program headers more
3888
precisely.  You may use the `PHDRS' command for this purpose.  When the
3889
linker sees the `PHDRS' command in the linker script, it will not
3890
create any program headers other than the ones specified.
3891
 
3892
   The linker only pays attention to the `PHDRS' command when
3893
generating an ELF output file.  In other cases, the linker will simply
3894
ignore `PHDRS'.
3895
 
3896
   This is the syntax of the `PHDRS' command.  The words `PHDRS',
3897
`FILEHDR', `AT', and `FLAGS' are keywords.
3898
 
3899
     PHDRS
3900
     {
3901
       NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ]
3902
             [ FLAGS ( FLAGS ) ] ;
3903
     }
3904
 
3905
   The NAME is used only for reference in the `SECTIONS' command of the
3906
linker script.  It is not put into the output file.  Program header
3907
names are stored in a separate name space, and will not conflict with
3908
symbol names, file names, or section names.  Each program header must
3909
have a distinct name.
3910
 
3911
   Certain program header types describe segments of memory which the
3912
system loader will load from the file.  In the linker script, you
3913
specify the contents of these segments by placing allocatable output
3914
sections in the segments.  You use the `:PHDR' output section attribute
3915
to place a section in a particular segment.  *Note Output Section
3916
Phdr::.
3917
 
3918
   It is normal to put certain sections in more than one segment.  This
3919
merely implies that one segment of memory contains another.  You may
3920
repeat `:PHDR', using it once for each segment which should contain the
3921
section.
3922
 
3923
   If you place a section in one or more segments using `:PHDR', then
3924
the linker will place all subsequent allocatable sections which do not
3925
specify `:PHDR' in the same segments.  This is for convenience, since
3926
generally a whole set of contiguous sections will be placed in a single
3927
segment.  You can use `:NONE' to override the default segment and tell
3928
the linker to not put the section in any segment at all.
3929
 
3930
   You may use the `FILEHDR' and `PHDRS' keywords appear after the
3931
program header type to further describe the contents of the segment.
3932
The `FILEHDR' keyword means that the segment should include the ELF
3933
file header.  The `PHDRS' keyword means that the segment should include
3934
the ELF program headers themselves.
3935
 
3936
   The TYPE may be one of the following.  The numbers indicate the
3937
value of the keyword.
3938
 
3939
`PT_NULL' (0)
3940
     Indicates an unused program header.
3941
 
3942
`PT_LOAD' (1)
3943
     Indicates that this program header describes a segment to be
3944
     loaded from the file.
3945
 
3946
`PT_DYNAMIC' (2)
3947
     Indicates a segment where dynamic linking information can be found.
3948
 
3949
`PT_INTERP' (3)
3950
     Indicates a segment where the name of the program interpreter may
3951
     be found.
3952
 
3953
`PT_NOTE' (4)
3954
     Indicates a segment holding note information.
3955
 
3956
`PT_SHLIB' (5)
3957
     A reserved program header type, defined but not specified by the
3958
     ELF ABI.
3959
 
3960
`PT_PHDR' (6)
3961
     Indicates a segment where the program headers may be found.
3962
 
3963
EXPRESSION
3964
     An expression giving the numeric type of the program header.  This
3965
     may be used for types not defined above.
3966
 
3967
   You can specify that a segment should be loaded at a particular
3968
address in memory by using an `AT' expression.  This is identical to the
3969
`AT' command used as an output section attribute (*note Output Section
3970
LMA::).  The `AT' command for a program header overrides the output
3971
section attribute.
3972
 
3973
   The linker will normally set the segment flags based on the sections
3974
which comprise the segment.  You may use the `FLAGS' keyword to
3975
explicitly specify the segment flags.  The value of FLAGS must be an
3976
integer.  It is used to set the `p_flags' field of the program header.
3977
 
3978
   Here is an example of `PHDRS'.  This shows a typical set of program
3979
headers used on a native ELF system.
3980
 
3981
     PHDRS
3982
     {
3983
       headers PT_PHDR PHDRS ;
3984
       interp PT_INTERP ;
3985
       text PT_LOAD FILEHDR PHDRS ;
3986
       data PT_LOAD ;
3987
       dynamic PT_DYNAMIC ;
3988
     }
3989
 
3990
     SECTIONS
3991
     {
3992
       . = SIZEOF_HEADERS;
3993
       .interp : { *(.interp) } :text :interp
3994
       .text : { *(.text) } :text
3995
       .rodata : { *(.rodata) } /* defaults to :text */
3996
       ...
3997
       . = . + 0x1000; /* move to a new page in memory */
3998
       .data : { *(.data) } :data
3999
       .dynamic : { *(.dynamic) } :data :dynamic
4000
       ...
4001
     }
4002
 
4003

4004
File: ld.info,  Node: VERSION,  Next: Expressions,  Prev: PHDRS,  Up: Scripts
4005
 
4006
3.9 VERSION Command
4007
===================
4008
 
4009
The linker supports symbol versions when using ELF.  Symbol versions are
4010
only useful when using shared libraries.  The dynamic linker can use
4011
symbol versions to select a specific version of a function when it runs
4012
a program that may have been linked against an earlier version of the
4013
shared library.
4014
 
4015
   You can include a version script directly in the main linker script,
4016
or you can supply the version script as an implicit linker script.  You
4017
can also use the `--version-script' linker option.
4018
 
4019
   The syntax of the `VERSION' command is simply
4020
     VERSION { version-script-commands }
4021
 
4022
   The format of the version script commands is identical to that used
4023
by Sun's linker in Solaris 2.5.  The version script defines a tree of
4024
version nodes.  You specify the node names and interdependencies in the
4025
version script.  You can specify which symbols are bound to which
4026
version nodes, and you can reduce a specified set of symbols to local
4027
scope so that they are not globally visible outside of the shared
4028
library.
4029
 
4030
   The easiest way to demonstrate the version script language is with a
4031
few examples.
4032
 
4033
     VERS_1.1 {
4034
         global:
4035
                 foo1;
4036
         local:
4037
                 old*;
4038
                 original*;
4039
                 new*;
4040
     };
4041
 
4042
     VERS_1.2 {
4043
                 foo2;
4044
     } VERS_1.1;
4045
 
4046
     VERS_2.0 {
4047
                 bar1; bar2;
4048
         extern "C++" {
4049
                 ns::*;
4050
                 "int f(int, double)";
4051
              }
4052
     } VERS_1.2;
4053
 
4054
   This example version script defines three version nodes.  The first
4055
version node defined is `VERS_1.1'; it has no other dependencies.  The
4056
script binds the symbol `foo1' to `VERS_1.1'.  It reduces a number of
4057
symbols to local scope so that they are not visible outside of the
4058
shared library; this is done using wildcard patterns, so that any
4059
symbol whose name begins with `old', `original', or `new' is matched.
4060
The wildcard patterns available are the same as those used in the shell
4061
when matching filenames (also known as "globbing").  However, if you
4062
specify the symbol name inside double quotes, then the name is treated
4063
as literal, rather than as a glob pattern.
4064
 
4065
   Next, the version script defines node `VERS_1.2'.  This node depends
4066
upon `VERS_1.1'.  The script binds the symbol `foo2' to the version
4067
node `VERS_1.2'.
4068
 
4069
   Finally, the version script defines node `VERS_2.0'.  This node
4070
depends upon `VERS_1.2'.  The scripts binds the symbols `bar1' and
4071
`bar2' are bound to the version node `VERS_2.0'.
4072
 
4073
   When the linker finds a symbol defined in a library which is not
4074
specifically bound to a version node, it will effectively bind it to an
4075
unspecified base version of the library.  You can bind all otherwise
4076
unspecified symbols to a given version node by using `global: *;'
4077
somewhere in the version script.  Note that it's slightly crazy to use
4078
wildcards in a global spec except on the last version node.  Global
4079
wildcards elsewhere run the risk of accidentally adding symbols to the
4080
set exported for an old version.  That's wrong since older versions
4081
ought to have a fixed set of symbols.
4082
 
4083
   The names of the version nodes have no specific meaning other than
4084
what they might suggest to the person reading them.  The `2.0' version
4085
could just as well have appeared in between `1.1' and `1.2'.  However,
4086
this would be a confusing way to write a version script.
4087
 
4088
   Node name can be omitted, provided it is the only version node in
4089
the version script.  Such version script doesn't assign any versions to
4090
symbols, only selects which symbols will be globally visible out and
4091
which won't.
4092
 
4093
     { global: foo; bar; local: *; };
4094
 
4095
   When you link an application against a shared library that has
4096
versioned symbols, the application itself knows which version of each
4097
symbol it requires, and it also knows which version nodes it needs from
4098
each shared library it is linked against.  Thus at runtime, the dynamic
4099
loader can make a quick check to make sure that the libraries you have
4100
linked against do in fact supply all of the version nodes that the
4101
application will need to resolve all of the dynamic symbols.  In this
4102
way it is possible for the dynamic linker to know with certainty that
4103
all external symbols that it needs will be resolvable without having to
4104
search for each symbol reference.
4105
 
4106
   The symbol versioning is in effect a much more sophisticated way of
4107
doing minor version checking that SunOS does.  The fundamental problem
4108
that is being addressed here is that typically references to external
4109
functions are bound on an as-needed basis, and are not all bound when
4110
the application starts up.  If a shared library is out of date, a
4111
required interface may be missing; when the application tries to use
4112
that interface, it may suddenly and unexpectedly fail.  With symbol
4113
versioning, the user will get a warning when they start their program if
4114
the libraries being used with the application are too old.
4115
 
4116
   There are several GNU extensions to Sun's versioning approach.  The
4117
first of these is the ability to bind a symbol to a version node in the
4118
source file where the symbol is defined instead of in the versioning
4119
script.  This was done mainly to reduce the burden on the library
4120
maintainer.  You can do this by putting something like:
4121
     __asm__(".symver original_foo,foo@VERS_1.1");
4122
   in the C source file.  This renames the function `original_foo' to
4123
be an alias for `foo' bound to the version node `VERS_1.1'.  The
4124
`local:' directive can be used to prevent the symbol `original_foo'
4125
from being exported. A `.symver' directive takes precedence over a
4126
version script.
4127
 
4128
   The second GNU extension is to allow multiple versions of the same
4129
function to appear in a given shared library.  In this way you can make
4130
an incompatible change to an interface without increasing the major
4131
version number of the shared library, while still allowing applications
4132
linked against the old interface to continue to function.
4133
 
4134
   To do this, you must use multiple `.symver' directives in the source
4135
file.  Here is an example:
4136
 
4137
     __asm__(".symver original_foo,foo@");
4138
     __asm__(".symver old_foo,foo@VERS_1.1");
4139
     __asm__(".symver old_foo1,foo@VERS_1.2");
4140
     __asm__(".symver new_foo,foo@@VERS_2.0");
4141
 
4142
   In this example, `foo@' represents the symbol `foo' bound to the
4143
unspecified base version of the symbol.  The source file that contains
4144
this example would define 4 C functions: `original_foo', `old_foo',
4145
`old_foo1', and `new_foo'.
4146
 
4147
   When you have multiple definitions of a given symbol, there needs to
4148
be some way to specify a default version to which external references to
4149
this symbol will be bound.  You can do this with the `foo@@VERS_2.0'
4150
type of `.symver' directive.  You can only declare one version of a
4151
symbol as the default in this manner; otherwise you would effectively
4152
have multiple definitions of the same symbol.
4153
 
4154
   If you wish to bind a reference to a specific version of the symbol
4155
within the shared library, you can use the aliases of convenience
4156
(i.e., `old_foo'), or you can use the `.symver' directive to
4157
specifically bind to an external version of the function in question.
4158
 
4159
   You can also specify the language in the version script:
4160
 
4161
     VERSION extern "lang" { version-script-commands }
4162
 
4163
   The supported `lang's are `C', `C++', and `Java'.  The linker will
4164
iterate over the list of symbols at the link time and demangle them
4165
according to `lang' before matching them to the patterns specified in
4166
`version-script-commands'.
4167
 
4168
   Demangled names may contains spaces and other special characters.  As
4169
described above, you can use a glob pattern to match demangled names,
4170
or you can use a double-quoted string to match the string exactly.  In
4171
the latter case, be aware that minor differences (such as differing
4172
whitespace) between the version script and the demangler output will
4173
cause a mismatch.  As the exact string generated by the demangler might
4174
change in the future, even if the mangled name does not, you should
4175
check that all of your version directives are behaving as you expect
4176
when you upgrade.
4177
 
4178

4179
File: ld.info,  Node: Expressions,  Next: Implicit Linker Scripts,  Prev: VERSION,  Up: Scripts
4180
 
4181
3.10 Expressions in Linker Scripts
4182
==================================
4183
 
4184
The syntax for expressions in the linker script language is identical to
4185
that of C expressions.  All expressions are evaluated as integers.  All
4186
expressions are evaluated in the same size, which is 32 bits if both the
4187
host and target are 32 bits, and is otherwise 64 bits.
4188
 
4189
   You can use and set symbol values in expressions.
4190
 
4191
   The linker defines several special purpose builtin functions for use
4192
in expressions.
4193
 
4194
* Menu:
4195
 
4196
* Constants::                   Constants
4197
* Symbolic Constants::          Symbolic constants
4198
* Symbols::                     Symbol Names
4199
* Orphan Sections::             Orphan Sections
4200
* Location Counter::            The Location Counter
4201
* Operators::                   Operators
4202
* Evaluation::                  Evaluation
4203
* Expression Section::          The Section of an Expression
4204
* Builtin Functions::           Builtin Functions
4205
 
4206

4207
File: ld.info,  Node: Constants,  Next: Symbolic Constants,  Up: Expressions
4208
 
4209
3.10.1 Constants
4210
----------------
4211
 
4212
All constants are integers.
4213
 
4214
   As in C, the linker considers an integer beginning with `0' to be
4215
octal, and an integer beginning with `0x' or `0X' to be hexadecimal.
4216
Alternatively the linker accepts suffixes of `h' or `H' for
4217
hexadeciaml, `o' or `O' for octal, `b' or `B' for binary and `d' or `D'
4218
for decimal.  Any integer value without a prefix or a suffix is
4219
considered to be decimal.
4220
 
4221
   In addition, you can use the suffixes `K' and `M' to scale a
4222
constant by `1024' or `1024*1024' respectively.  For example, the
4223
following all refer to the same quantity:
4224
 
4225
     _fourk_1 = 4K;
4226
     _fourk_2 = 4096;
4227
     _fourk_3 = 0x1000;
4228
     _fourk_4 = 10000o;
4229
 
4230
   Note - the `K' and `M' suffixes cannot be used in conjunction with
4231
the base suffixes mentioned above.
4232
 
4233

4234
File: ld.info,  Node: Symbolic Constants,  Next: Symbols,  Prev: Constants,  Up: Expressions
4235
 
4236
3.10.2 Symbolic Constants
4237
-------------------------
4238
 
4239
It is possible to refer to target specific constants via the use of the
4240
`CONSTANT(NAME)' operator, where NAME is one of:
4241
 
4242
`MAXPAGESIZE'
4243
     The target's maximum page size.
4244
 
4245
`COMMONPAGESIZE'
4246
     The target's default page size.
4247
 
4248
   So for example:
4249
 
4250
       .text ALIGN (CONSTANT (MAXPAGESIZE)) : { *(.text) }
4251
 
4252
   will create a text section aligned to the largest page boundary
4253
supported by the target.
4254
 
4255

4256
File: ld.info,  Node: Symbols,  Next: Orphan Sections,  Prev: Symbolic Constants,  Up: Expressions
4257
 
4258
3.10.3 Symbol Names
4259
-------------------
4260
 
4261
Unless quoted, symbol names start with a letter, underscore, or period
4262
and may include letters, digits, underscores, periods, and hyphens.
4263
Unquoted symbol names must not conflict with any keywords.  You can
4264
specify a symbol which contains odd characters or has the same name as a
4265
keyword by surrounding the symbol name in double quotes:
4266
     "SECTION" = 9;
4267
     "with a space" = "also with a space" + 10;
4268
 
4269
   Since symbols can contain many non-alphabetic characters, it is
4270
safest to delimit symbols with spaces.  For example, `A-B' is one
4271
symbol, whereas `A - B' is an expression involving subtraction.
4272
 
4273

4274
File: ld.info,  Node: Orphan Sections,  Next: Location Counter,  Prev: Symbols,  Up: Expressions
4275
 
4276
3.10.4 Orphan Sections
4277
----------------------
4278
 
4279
Orphan sections are sections present in the input files which are not
4280
explicitly placed into the output file by the linker script.  The
4281
linker will still copy these sections into the output file, but it has
4282
to guess as to where they should be placed.  The linker uses a simple
4283
heuristic to do this.  It attempts to place orphan sections after
4284
non-orphan sections of the same attribute, such as code vs data,
4285
loadable vs non-loadable, etc.  If there is not enough room to do this
4286
then it places at the end of the file.
4287
 
4288
   For ELF targets, the attribute of the section includes section type
4289
as well as section flag.
4290
 
4291
   If an orphaned section's name is representable as a C identifier then
4292
the linker will automatically *note PROVIDE:: two symbols:
4293
__start_SECNAME and __end_SECNAME, where SECNAME is the name of the
4294
section.  These indicate the start address and end address of the
4295
orphaned section respectively.  Note: most section names are not
4296
representable as C identifiers because they contain a `.' character.
4297
 
4298

4299
File: ld.info,  Node: Location Counter,  Next: Operators,  Prev: Orphan Sections,  Up: Expressions
4300
 
4301
3.10.5 The Location Counter
4302
---------------------------
4303
 
4304
The special linker variable "dot" `.' always contains the current
4305
output location counter.  Since the `.' always refers to a location in
4306
an output section, it may only appear in an expression within a
4307
`SECTIONS' command.  The `.' symbol may appear anywhere that an
4308
ordinary symbol is allowed in an expression.
4309
 
4310
   Assigning a value to `.' will cause the location counter to be
4311
moved.  This may be used to create holes in the output section.  The
4312
location counter may not be moved backwards inside an output section,
4313
and may not be moved backwards outside of an output section if so doing
4314
creates areas with overlapping LMAs.
4315
 
4316
     SECTIONS
4317
     {
4318
       output :
4319
         {
4320
           file1(.text)
4321
           . = . + 1000;
4322
           file2(.text)
4323
           . += 1000;
4324
           file3(.text)
4325
         } = 0x12345678;
4326
     }
4327
   In the previous example, the `.text' section from `file1' is located
4328
at the beginning of the output section `output'.  It is followed by a
4329
1000 byte gap.  Then the `.text' section from `file2' appears, also
4330
with a 1000 byte gap following before the `.text' section from `file3'.
4331
The notation `= 0x12345678' specifies what data to write in the gaps
4332
(*note Output Section Fill::).
4333
 
4334
   Note: `.' actually refers to the byte offset from the start of the
4335
current containing object.  Normally this is the `SECTIONS' statement,
4336
whose start address is 0, hence `.' can be used as an absolute address.
4337
If `.' is used inside a section description however, it refers to the
4338
byte offset from the start of that section, not an absolute address.
4339
Thus in a script like this:
4340
 
4341
     SECTIONS
4342
     {
4343
         . = 0x100
4344
         .text: {
4345
           *(.text)
4346
           . = 0x200
4347
         }
4348
         . = 0x500
4349
         .data: {
4350
           *(.data)
4351
           . += 0x600
4352
         }
4353
     }
4354
 
4355
   The `.text' section will be assigned a starting address of 0x100 and
4356
a size of exactly 0x200 bytes, even if there is not enough data in the
4357
`.text' input sections to fill this area.  (If there is too much data,
4358
an error will be produced because this would be an attempt to move `.'
4359
backwards).  The `.data' section will start at 0x500 and it will have
4360
an extra 0x600 bytes worth of space after the end of the values from
4361
the `.data' input sections and before the end of the `.data' output
4362
section itself.
4363
 
4364
   Setting symbols to the value of the location counter outside of an
4365
output section statement can result in unexpected values if the linker
4366
needs to place orphan sections.  For example, given the following:
4367
 
4368
     SECTIONS
4369
     {
4370
         start_of_text = . ;
4371
         .text: { *(.text) }
4372
         end_of_text = . ;
4373
 
4374
         start_of_data = . ;
4375
         .data: { *(.data) }
4376
         end_of_data = . ;
4377
     }
4378
 
4379
   If the linker needs to place some input section, e.g. `.rodata', not
4380
mentioned in the script, it might choose to place that section between
4381
`.text' and `.data'.  You might think the linker should place `.rodata'
4382
on the blank line in the above script, but blank lines are of no
4383
particular significance to the linker.  As well, the linker doesn't
4384
associate the above symbol names with their sections.  Instead, it
4385
assumes that all assignments or other statements belong to the previous
4386
output section, except for the special case of an assignment to `.'.
4387
I.e., the linker will place the orphan `.rodata' section as if the
4388
script was written as follows:
4389
 
4390
     SECTIONS
4391
     {
4392
         start_of_text = . ;
4393
         .text: { *(.text) }
4394
         end_of_text = . ;
4395
 
4396
         start_of_data = . ;
4397
         .rodata: { *(.rodata) }
4398
         .data: { *(.data) }
4399
         end_of_data = . ;
4400
     }
4401
 
4402
   This may or may not be the script author's intention for the value of
4403
`start_of_data'.  One way to influence the orphan section placement is
4404
to assign the location counter to itself, as the linker assumes that an
4405
assignment to `.' is setting the start address of a following output
4406
section and thus should be grouped with that section.  So you could
4407
write:
4408
 
4409
     SECTIONS
4410
     {
4411
         start_of_text = . ;
4412
         .text: { *(.text) }
4413
         end_of_text = . ;
4414
 
4415
         . = . ;
4416
         start_of_data = . ;
4417
         .data: { *(.data) }
4418
         end_of_data = . ;
4419
     }
4420
 
4421
   Now, the orphan `.rodata' section will be placed between
4422
`end_of_text' and `start_of_data'.
4423
 
4424

4425
File: ld.info,  Node: Operators,  Next: Evaluation,  Prev: Location Counter,  Up: Expressions
4426
 
4427
3.10.6 Operators
4428
----------------
4429
 
4430
The linker recognizes the standard C set of arithmetic operators, with
4431
the standard bindings and precedence levels:
4432
     precedence      associativity   Operators                Notes
4433
     (highest)
4434
     1               left            !  -  ~                  (1)
4435
     2               left            *  /  %
4436
     3               left            +  -
4437
     4               left            >>  <<
4438
     5               left            ==  !=  >  <  <=  >=
4439
     6               left            &
4440
     7               left            |
4441
     8               left            &&
4442
     9               left            ||
4443
     10              right           ? :
4444
     11              right           &=  +=  -=  *=  /=       (2)
4445
     (lowest)
4446
   Notes: (1) Prefix operators (2) *Note Assignments::.
4447
 
4448

4449
File: ld.info,  Node: Evaluation,  Next: Expression Section,  Prev: Operators,  Up: Expressions
4450
 
4451
3.10.7 Evaluation
4452
-----------------
4453
 
4454
The linker evaluates expressions lazily.  It only computes the value of
4455
an expression when absolutely necessary.
4456
 
4457
   The linker needs some information, such as the value of the start
4458
address of the first section, and the origins and lengths of memory
4459
regions, in order to do any linking at all.  These values are computed
4460
as soon as possible when the linker reads in the linker script.
4461
 
4462
   However, other values (such as symbol values) are not known or needed
4463
until after storage allocation.  Such values are evaluated later, when
4464
other information (such as the sizes of output sections) is available
4465
for use in the symbol assignment expression.
4466
 
4467
   The sizes of sections cannot be known until after allocation, so
4468
assignments dependent upon these are not performed until after
4469
allocation.
4470
 
4471
   Some expressions, such as those depending upon the location counter
4472
`.', must be evaluated during section allocation.
4473
 
4474
   If the result of an expression is required, but the value is not
4475
available, then an error results.  For example, a script like the
4476
following
4477
     SECTIONS
4478
       {
4479
         .text 9+this_isnt_constant :
4480
           { *(.text) }
4481
       }
4482
will cause the error message `non constant expression for initial
4483
address'.
4484
 
4485

4486
File: ld.info,  Node: Expression Section,  Next: Builtin Functions,  Prev: Evaluation,  Up: Expressions
4487
 
4488
3.10.8 The Section of an Expression
4489
-----------------------------------
4490
 
4491
When the linker evaluates an expression, the result is either absolute
4492
or relative to some section.  A relative expression is expressed as a
4493
fixed offset from the base of a section.
4494
 
4495
   The position of the expression within the linker script determines
4496
whether it is absolute or relative.  An expression which appears within
4497
an output section definition is relative to the base of the output
4498
section.  An expression which appears elsewhere will be absolute.
4499
 
4500
   A symbol set to a relative expression will be relocatable if you
4501
request relocatable output using the `-r' option.  That means that a
4502
further link operation may change the value of the symbol.  The symbol's
4503
section will be the section of the relative expression.
4504
 
4505
   A symbol set to an absolute expression will retain the same value
4506
through any further link operation.  The symbol will be absolute, and
4507
will not have any particular associated section.
4508
 
4509
   You can use the builtin function `ABSOLUTE' to force an expression
4510
to be absolute when it would otherwise be relative.  For example, to
4511
create an absolute symbol set to the address of the end of the output
4512
section `.data':
4513
     SECTIONS
4514
       {
4515
         .data : { *(.data) _edata = ABSOLUTE(.); }
4516
       }
4517
   If `ABSOLUTE' were not used, `_edata' would be relative to the
4518
`.data' section.
4519
 
4520

4521
File: ld.info,  Node: Builtin Functions,  Prev: Expression Section,  Up: Expressions
4522
 
4523
3.10.9 Builtin Functions
4524
------------------------
4525
 
4526
The linker script language includes a number of builtin functions for
4527
use in linker script expressions.
4528
 
4529
`ABSOLUTE(EXP)'
4530
     Return the absolute (non-relocatable, as opposed to non-negative)
4531
     value of the expression EXP.  Primarily useful to assign an
4532
     absolute value to a symbol within a section definition, where
4533
     symbol values are normally section relative.  *Note Expression
4534
     Section::.
4535
 
4536
`ADDR(SECTION)'
4537
     Return the absolute address (the VMA) of the named SECTION.  Your
4538
     script must previously have defined the location of that section.
4539
     In the following example, `symbol_1' and `symbol_2' are assigned
4540
     identical values:
4541
          SECTIONS { ...
4542
            .output1 :
4543
              {
4544
              start_of_output_1 = ABSOLUTE(.);
4545
              ...
4546
              }
4547
            .output :
4548
              {
4549
              symbol_1 = ADDR(.output1);
4550
              symbol_2 = start_of_output_1;
4551
              }
4552
          ... }
4553
 
4554
`ALIGN(ALIGN)'
4555
`ALIGN(EXP,ALIGN)'
4556
     Return the location counter (`.') or arbitrary expression aligned
4557
     to the next ALIGN boundary.  The single operand `ALIGN' doesn't
4558
     change the value of the location counter--it just does arithmetic
4559
     on it.  The two operand `ALIGN' allows an arbitrary expression to
4560
     be aligned upwards (`ALIGN(ALIGN)' is equivalent to `ALIGN(.,
4561
     ALIGN)').
4562
 
4563
     Here is an example which aligns the output `.data' section to the
4564
     next `0x2000' byte boundary after the preceding section and sets a
4565
     variable within the section to the next `0x8000' boundary after the
4566
     input sections:
4567
          SECTIONS { ...
4568
            .data ALIGN(0x2000): {
4569
              *(.data)
4570
              variable = ALIGN(0x8000);
4571
            }
4572
          ... }
4573
     The first use of `ALIGN' in this example specifies the
4574
     location of a section because it is used as the optional ADDRESS
4575
     attribute of a section definition (*note Output Section
4576
     Address::).  The second use of `ALIGN' is used to defines the
4577
     value of a symbol.
4578
 
4579
     The builtin function `NEXT' is closely related to `ALIGN'.
4580
 
4581
`ALIGNOF(SECTION)'
4582
     Return the alignment in bytes of the named SECTION, if that
4583
     section has been allocated.  If the section has not been allocated
4584
     when this is evaluated, the linker will report an error. In the
4585
     following example, the alignment of the `.output' section is
4586
     stored as the first value in that section.
4587
          SECTIONS{ ...
4588
            .output {
4589
              LONG (ALIGNOF (.output))
4590
              ...
4591
              }
4592
          ... }
4593
 
4594
`BLOCK(EXP)'
4595
     This is a synonym for `ALIGN', for compatibility with older linker
4596
     scripts.  It is most often seen when setting the address of an
4597
     output section.
4598
 
4599
`DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)'
4600
     This is equivalent to either
4601
          (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1)))
4602
     or
4603
          (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - COMMONPAGESIZE)))
4604
     depending on whether the latter uses fewer COMMONPAGESIZE sized
4605
     pages for the data segment (area between the result of this
4606
     expression and `DATA_SEGMENT_END') than the former or not.  If the
4607
     latter form is used, it means COMMONPAGESIZE bytes of runtime
4608
     memory will be saved at the expense of up to COMMONPAGESIZE wasted
4609
     bytes in the on-disk file.
4610
 
4611
     This expression can only be used directly in `SECTIONS' commands,
4612
     not in any output section descriptions and only once in the linker
4613
     script.  COMMONPAGESIZE should be less or equal to MAXPAGESIZE and
4614
     should be the system page size the object wants to be optimized
4615
     for (while still working on system page sizes up to MAXPAGESIZE).
4616
 
4617
     Example:
4618
            . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
4619
 
4620
`DATA_SEGMENT_END(EXP)'
4621
     This defines the end of data segment for `DATA_SEGMENT_ALIGN'
4622
     evaluation purposes.
4623
 
4624
            . = DATA_SEGMENT_END(.);
4625
 
4626
`DATA_SEGMENT_RELRO_END(OFFSET, EXP)'
4627
     This defines the end of the `PT_GNU_RELRO' segment when `-z relro'
4628
     option is used.  Second argument is returned.  When `-z relro'
4629
     option is not present, `DATA_SEGMENT_RELRO_END' does nothing,
4630
     otherwise `DATA_SEGMENT_ALIGN' is padded so that EXP + OFFSET is
4631
     aligned to the most commonly used page boundary for particular
4632
     target.  If present in the linker script, it must always come in
4633
     between `DATA_SEGMENT_ALIGN' and `DATA_SEGMENT_END'.
4634
 
4635
            . = DATA_SEGMENT_RELRO_END(24, .);
4636
 
4637
`DEFINED(SYMBOL)'
4638
     Return 1 if SYMBOL is in the linker global symbol table and is
4639
     defined before the statement using DEFINED in the script, otherwise
4640
     return 0.  You can use this function to provide default values for
4641
     symbols.  For example, the following script fragment shows how to
4642
     set a global symbol `begin' to the first location in the `.text'
4643
     section--but if a symbol called `begin' already existed, its value
4644
     is preserved:
4645
 
4646
          SECTIONS { ...
4647
            .text : {
4648
              begin = DEFINED(begin) ? begin : . ;
4649
              ...
4650
            }
4651
            ...
4652
          }
4653
 
4654
`LENGTH(MEMORY)'
4655
     Return the length of the memory region named MEMORY.
4656
 
4657
`LOADADDR(SECTION)'
4658
     Return the absolute LMA of the named SECTION.  This is normally
4659
     the same as `ADDR', but it may be different if the `AT' attribute
4660
     is used in the output section definition (*note Output Section
4661
     LMA::).
4662
 
4663
`MAX(EXP1, EXP2)'
4664
     Returns the maximum of EXP1 and EXP2.
4665
 
4666
`MIN(EXP1, EXP2)'
4667
     Returns the minimum of EXP1 and EXP2.
4668
 
4669
`NEXT(EXP)'
4670
     Return the next unallocated address that is a multiple of EXP.
4671
     This function is closely related to `ALIGN(EXP)'; unless you use
4672
     the `MEMORY' command to define discontinuous memory for the output
4673
     file, the two functions are equivalent.
4674
 
4675
`ORIGIN(MEMORY)'
4676
     Return the origin of the memory region named MEMORY.
4677
 
4678
`SEGMENT_START(SEGMENT, DEFAULT)'
4679
     Return the base address of the named SEGMENT.  If an explicit
4680
     value has been given for this segment (with a command-line `-T'
4681
     option) that value will be returned; otherwise the value will be
4682
     DEFAULT.  At present, the `-T' command-line option can only be
4683
     used to set the base address for the "text", "data", and "bss"
4684
     sections, but you use `SEGMENT_START' with any segment name.
4685
 
4686
`SIZEOF(SECTION)'
4687
     Return the size in bytes of the named SECTION, if that section has
4688
     been allocated.  If the section has not been allocated when this is
4689
     evaluated, the linker will report an error.  In the following
4690
     example, `symbol_1' and `symbol_2' are assigned identical values:
4691
          SECTIONS{ ...
4692
            .output {
4693
              .start = . ;
4694
              ...
4695
              .end = . ;
4696
              }
4697
            symbol_1 = .end - .start ;
4698
            symbol_2 = SIZEOF(.output);
4699
          ... }
4700
 
4701
`SIZEOF_HEADERS'
4702
`sizeof_headers'
4703
     Return the size in bytes of the output file's headers.  This is
4704
     information which appears at the start of the output file.  You
4705
     can use this number when setting the start address of the first
4706
     section, if you choose, to facilitate paging.
4707
 
4708
     When producing an ELF output file, if the linker script uses the
4709
     `SIZEOF_HEADERS' builtin function, the linker must compute the
4710
     number of program headers before it has determined all the section
4711
     addresses and sizes.  If the linker later discovers that it needs
4712
     additional program headers, it will report an error `not enough
4713
     room for program headers'.  To avoid this error, you must avoid
4714
     using the `SIZEOF_HEADERS' function, or you must rework your linker
4715
     script to avoid forcing the linker to use additional program
4716
     headers, or you must define the program headers yourself using the
4717
     `PHDRS' command (*note PHDRS::).
4718
 
4719

4720
File: ld.info,  Node: Implicit Linker Scripts,  Prev: Expressions,  Up: Scripts
4721
 
4722
3.11 Implicit Linker Scripts
4723
============================
4724
 
4725
If you specify a linker input file which the linker can not recognize as
4726
an object file or an archive file, it will try to read the file as a
4727
linker script.  If the file can not be parsed as a linker script, the
4728
linker will report an error.
4729
 
4730
   An implicit linker script will not replace the default linker script.
4731
 
4732
   Typically an implicit linker script would contain only symbol
4733
assignments, or the `INPUT', `GROUP', or `VERSION' commands.
4734
 
4735
   Any input files read because of an implicit linker script will be
4736
read at the position in the command line where the implicit linker
4737
script was read.  This can affect archive searching.
4738
 
4739

4740
File: ld.info,  Node: Machine Dependent,  Next: BFD,  Prev: Scripts,  Up: Top
4741
 
4742
4 Machine Dependent Features
4743
****************************
4744
 
4745
`ld' has additional features on some platforms; the following sections
4746
describe them.  Machines where `ld' has no additional functionality are
4747
not listed.
4748
 
4749
* Menu:
4750
 
4751
 
4752
* H8/300::                      `ld' and the H8/300
4753
 
4754
* i960::                        `ld' and the Intel 960 family
4755
 
4756
* ARM::                         `ld' and the ARM family
4757
 
4758
* HPPA ELF32::                  `ld' and HPPA 32-bit ELF
4759
 
4760
* M68K::                        `ld' and the Motorola 68K family
4761
 
4762
* MMIX::                        `ld' and MMIX
4763
 
4764
* MSP430::                      `ld' and MSP430
4765
 
4766
* M68HC11/68HC12::              `ld' and the Motorola 68HC11 and 68HC12 families
4767
 
4768
* PowerPC ELF32::               `ld' and PowerPC 32-bit ELF Support
4769
 
4770
* PowerPC64 ELF64::             `ld' and PowerPC64 64-bit ELF Support
4771
 
4772
* SPU ELF::                     `ld' and SPU ELF Support
4773
 
4774
* TI COFF::                     `ld' and TI COFF
4775
 
4776
* WIN32::                       `ld' and WIN32 (cygwin/mingw)
4777
 
4778
* Xtensa::                      `ld' and Xtensa Processors
4779
 
4780

4781
File: ld.info,  Node: H8/300,  Next: i960,  Up: Machine Dependent
4782
 
4783
4.1 `ld' and the H8/300
4784
=======================
4785
 
4786
For the H8/300, `ld' can perform these global optimizations when you
4787
specify the `--relax' command-line option.
4788
 
4789
_relaxing address modes_
4790
     `ld' finds all `jsr' and `jmp' instructions whose targets are
4791
     within eight bits, and turns them into eight-bit program-counter
4792
     relative `bsr' and `bra' instructions, respectively.
4793
 
4794
_synthesizing instructions_
4795
     `ld' finds all `mov.b' instructions which use the sixteen-bit
4796
     absolute address form, but refer to the top page of memory, and
4797
     changes them to use the eight-bit address form.  (That is: the
4798
     linker turns `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the
4799
     address AA is in the top page of memory).
4800
 
4801
_bit manipulation instructions_
4802
     `ld' finds all bit manipulation instructions like `band, bclr,
4803
     biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst,
4804
     bxor' which use 32 bit and 16 bit absolute address form, but refer
4805
     to the top page of memory, and changes them to use the 8 bit
4806
     address form.  (That is: the linker turns `bset #xx:3,`@'AA:32'
4807
     into `bset #xx:3,`@'AA:8' whenever the address AA is in the top
4808
     page of memory).
4809
 
4810
_system control instructions_
4811
     `ld' finds all `ldc.w, stc.w' instructions which use the 32 bit
4812
     absolute address form, but refer to the top page of memory, and
4813
     changes them to use 16 bit address form.  (That is: the linker
4814
     turns `ldc.w `@'AA:32,ccr' into `ldc.w `@'AA:16,ccr' whenever the
4815
     address AA is in the top page of memory).
4816
 
4817

4818
File: ld.info,  Node: i960,  Next: ARM,  Prev: H8/300,  Up: Machine Dependent
4819
 
4820
4.2 `ld' and the Intel 960 Family
4821
=================================
4822
 
4823
You can use the `-AARCHITECTURE' command line option to specify one of
4824
the two-letter names identifying members of the 960 family; the option
4825
specifies the desired output target, and warns of any incompatible
4826
instructions in the input files.  It also modifies the linker's search
4827
strategy for archive libraries, to support the use of libraries
4828
specific to each particular architecture, by including in the search
4829
loop names suffixed with the string identifying the architecture.
4830
 
4831
   For example, if your `ld' command line included `-ACA' as well as
4832
`-ltry', the linker would look (in its built-in search paths, and in
4833
any paths you specify with `-L') for a library with the names
4834
 
4835
     try
4836
     libtry.a
4837
     tryca
4838
     libtryca.a
4839
 
4840
The first two possibilities would be considered in any event; the last
4841
two are due to the use of `-ACA'.
4842
 
4843
   You can meaningfully use `-A' more than once on a command line, since
4844
the 960 architecture family allows combination of target architectures;
4845
each use will add another pair of name variants to search for when `-l'
4846
specifies a library.
4847
 
4848
   `ld' supports the `--relax' option for the i960 family.  If you
4849
specify `--relax', `ld' finds all `balx' and `calx' instructions whose
4850
targets are within 24 bits, and turns them into 24-bit program-counter
4851
relative `bal' and `cal' instructions, respectively.  `ld' also turns
4852
`cal' instructions into `bal' instructions when it determines that the
4853
target subroutine is a leaf routine (that is, the target subroutine does
4854
not itself call any subroutines).
4855
 
4856
   The `--fix-cortex-a8' switch enables a link-time workaround for an
4857
erratum in certain Cortex-A8 processors.  The workaround is enabled by
4858
default if you are targeting the ARM v7-A architecture profile.  It can
4859
be enabled otherwise by specifying `--fix-cortex-a8', or disabled
4860
unconditionally by specifying `--no-fix-cortex-a8'.
4861
 
4862
   The erratum only affects Thumb-2 code.  Please contact ARM for
4863
further details.
4864
 
4865

4866
File: ld.info,  Node: M68HC11/68HC12,  Next: PowerPC ELF32,  Prev: MSP430,  Up: Machine Dependent
4867
 
4868
4.3 `ld' and the Motorola 68HC11 and 68HC12 families
4869
====================================================
4870
 
4871
4.3.1 Linker Relaxation
4872
-----------------------
4873
 
4874
For the Motorola 68HC11, `ld' can perform these global optimizations
4875
when you specify the `--relax' command-line option.
4876
 
4877
_relaxing address modes_
4878
     `ld' finds all `jsr' and `jmp' instructions whose targets are
4879
     within eight bits, and turns them into eight-bit program-counter
4880
     relative `bsr' and `bra' instructions, respectively.
4881
 
4882
     `ld' also looks at all 16-bit extended addressing modes and
4883
     transforms them in a direct addressing mode when the address is in
4884
     page 0 (between 0 and 0x0ff).
4885
 
4886
_relaxing gcc instruction group_
4887
     When `gcc' is called with `-mrelax', it can emit group of
4888
     instructions that the linker can optimize to use a 68HC11 direct
4889
     addressing mode. These instructions consists of `bclr' or `bset'
4890
     instructions.
4891
 
4892
 
4893
4.3.2 Trampoline Generation
4894
---------------------------
4895
 
4896
For 68HC11 and 68HC12, `ld' can generate trampoline code to call a far
4897
function using a normal `jsr' instruction. The linker will also change
4898
the relocation to some far function to use the trampoline address
4899
instead of the function address. This is typically the case when a
4900
pointer to a function is taken. The pointer will in fact point to the
4901
function trampoline.
4902
 
4903

4904
File: ld.info,  Node: ARM,  Next: HPPA ELF32,  Prev: i960,  Up: Machine Dependent
4905
 
4906
4.4 `ld' and the ARM family
4907
===========================
4908
 
4909
For the ARM, `ld' will generate code stubs to allow functions calls
4910
between ARM and Thumb code.  These stubs only work with code that has
4911
been compiled and assembled with the `-mthumb-interwork' command line
4912
option.  If it is necessary to link with old ARM object files or
4913
libraries, which have not been compiled with the -mthumb-interwork
4914
option then the `--support-old-code' command line switch should be
4915
given to the linker.  This will make it generate larger stub functions
4916
which will work with non-interworking aware ARM code.  Note, however,
4917
the linker does not support generating stubs for function calls to
4918
non-interworking aware Thumb code.
4919
 
4920
   The `--thumb-entry' switch is a duplicate of the generic `--entry'
4921
switch, in that it sets the program's starting address.  But it also
4922
sets the bottom bit of the address, so that it can be branched to using
4923
a BX instruction, and the program will start executing in Thumb mode
4924
straight away.
4925
 
4926
   The `--use-nul-prefixed-import-tables' switch is specifying, that
4927
the import tables idata4 and idata5 have to be generated with a zero
4928
elememt prefix for import libraries. This is the old style to generate
4929
import tables. By default this option is turned off.
4930
 
4931
   The `--be8' switch instructs `ld' to generate BE8 format
4932
executables.  This option is only valid when linking big-endian objects.
4933
The resulting image will contain big-endian data and little-endian code.
4934
 
4935
   The `R_ARM_TARGET1' relocation is typically used for entries in the
4936
`.init_array' section.  It is interpreted as either `R_ARM_REL32' or
4937
`R_ARM_ABS32', depending on the target.  The `--target1-rel' and
4938
`--target1-abs' switches override the default.
4939
 
4940
   The `--target2=type' switch overrides the default definition of the
4941
`R_ARM_TARGET2' relocation.  Valid values for `type', their meanings,
4942
and target defaults are as follows:
4943
`rel'
4944
     `R_ARM_REL32' (arm*-*-elf, arm*-*-eabi)
4945
 
4946
`abs'
4947
     `R_ARM_ABS32' (arm*-*-symbianelf)
4948
 
4949
`got-rel'
4950
     `R_ARM_GOT_PREL' (arm*-*-linux, arm*-*-*bsd)
4951
 
4952
   The `R_ARM_V4BX' relocation (defined by the ARM AAELF specification)
4953
enables objects compiled for the ARMv4 architecture to be
4954
interworking-safe when linked with other objects compiled for ARMv4t,
4955
but also allows pure ARMv4 binaries to be built from the same ARMv4
4956
objects.
4957
 
4958
   In the latter case, the switch `--fix-v4bx' must be passed to the
4959
linker, which causes v4t `BX rM' instructions to be rewritten as `MOV
4960
PC,rM', since v4 processors do not have a `BX' instruction.
4961
 
4962
   In the former case, the switch should not be used, and `R_ARM_V4BX'
4963
relocations are ignored.
4964
 
4965
   Replace `BX rM' instructions identified by `R_ARM_V4BX' relocations
4966
with a branch to the following veneer:
4967
 
4968
     TST rM, #1
4969
     MOVEQ PC, rM
4970
     BX Rn
4971
 
4972
   This allows generation of libraries/applications that work on ARMv4
4973
cores and are still interworking safe.  Note that the above veneer
4974
clobbers the condition flags, so may cause incorrect progrm behavior in
4975
rare cases.
4976
 
4977
   The `--use-blx' switch enables the linker to use ARM/Thumb BLX
4978
instructions (available on ARMv5t and above) in various situations.
4979
Currently it is used to perform calls via the PLT from Thumb code using
4980
BLX rather than using BX and a mode-switching stub before each PLT
4981
entry. This should lead to such calls executing slightly faster.
4982
 
4983
   This option is enabled implicitly for SymbianOS, so there is no need
4984
to specify it if you are using that target.
4985
 
4986
   The `--vfp11-denorm-fix' switch enables a link-time workaround for a
4987
bug in certain VFP11 coprocessor hardware, which sometimes allows
4988
instructions with denorm operands (which must be handled by support
4989
code) to have those operands overwritten by subsequent instructions
4990
before the support code can read the intended values.
4991
 
4992
   The bug may be avoided in scalar mode if you allow at least one
4993
intervening instruction between a VFP11 instruction which uses a
4994
register and another instruction which writes to the same register, or
4995
at least two intervening instructions if vector mode is in use. The bug
4996
only affects full-compliance floating-point mode: you do not need this
4997
workaround if you are using "runfast" mode. Please contact ARM for
4998
further details.
4999
 
5000
   If you know you are using buggy VFP11 hardware, you can enable this
5001
workaround by specifying the linker option `--vfp-denorm-fix=scalar' if
5002
you are using the VFP11 scalar mode only, or `--vfp-denorm-fix=vector'
5003
if you are using vector mode (the latter also works for scalar code).
5004
The default is `--vfp-denorm-fix=none'.
5005
 
5006
   If the workaround is enabled, instructions are scanned for
5007
potentially-troublesome sequences, and a veneer is created for each
5008
such sequence which may trigger the erratum. The veneer consists of the
5009
first instruction of the sequence and a branch back to the subsequent
5010
instruction. The original instruction is then replaced with a branch to
5011
the veneer. The extra cycles required to call and return from the veneer
5012
are sufficient to avoid the erratum in both the scalar and vector cases.
5013
 
5014
   The `--no-enum-size-warning' switch prevents the linker from warning
5015
when linking object files that specify incompatible EABI enumeration
5016
size attributes.  For example, with this switch enabled, linking of an
5017
object file using 32-bit enumeration values with another using
5018
enumeration values fitted into the smallest possible space will not be
5019
diagnosed.
5020
 
5021
   The `--no-wchar-size-warning' switch prevents the linker from
5022
warning when linking object files that specify incompatible EABI
5023
`wchar_t' size attributes.  For example, with this switch enabled,
5024
linking of an object file using 32-bit `wchar_t' values with another
5025
using 16-bit `wchar_t' values will not be diagnosed.
5026
 
5027
   The `--pic-veneer' switch makes the linker use PIC sequences for
5028
ARM/Thumb interworking veneers, even if the rest of the binary is not
5029
PIC.  This avoids problems on uClinux targets where `--emit-relocs' is
5030
used to generate relocatable binaries.
5031
 
5032
   The linker will automatically generate and insert small sequences of
5033
code into a linked ARM ELF executable whenever an attempt is made to
5034
perform a function call to a symbol that is too far away.  The
5035
placement of these sequences of instructions - called stubs - is
5036
controlled by the command line option `--stub-group-size=N'.  The
5037
placement is important because a poor choice can create a need for
5038
duplicate stubs, increasing the code sizw.  The linker will try to
5039
group stubs together in order to reduce interruptions to the flow of
5040
code, but it needs guidance as to how big these groups should be and
5041
where they should be placed.
5042
 
5043
   The value of `N', the parameter to the `--stub-group-size=' option
5044
controls where the stub groups are placed.  If it is negative then all
5045
stubs are placed after the first branch that needs them.  If it is
5046
positive then the stubs can be placed either before or after the
5047
branches that need them.  If the value of `N' is 1 (either +1 or -1)
5048
then the linker will choose exactly where to place groups of stubs,
5049
using its built in heuristics.  A value of `N' greater than 1 (or
5050
smaller than -1) tells the linker that a single group of stubs can
5051
service at most `N' bytes from the input sections.
5052
 
5053
   The default, if `--stub-group-size=' is not specified, is `N = +1'.
5054
 
5055
   Farcalls stubs insertion is fully supported for the ARM-EABI target
5056
only, because it relies on object files properties not present
5057
otherwise.
5058
 
5059

5060
File: ld.info,  Node: HPPA ELF32,  Next: M68K,  Prev: ARM,  Up: Machine Dependent
5061
 
5062
4.5 `ld' and HPPA 32-bit ELF Support
5063
====================================
5064
 
5065
When generating a shared library, `ld' will by default generate import
5066
stubs suitable for use with a single sub-space application.  The
5067
`--multi-subspace' switch causes `ld' to generate export stubs, and
5068
different (larger) import stubs suitable for use with multiple
5069
sub-spaces.
5070
 
5071
   Long branch stubs and import/export stubs are placed by `ld' in stub
5072
sections located between groups of input sections.  `--stub-group-size'
5073
specifies the maximum size of a group of input sections handled by one
5074
stub section.  Since branch offsets are signed, a stub section may
5075
serve two groups of input sections, one group before the stub section,
5076
and one group after it.  However, when using conditional branches that
5077
require stubs, it may be better (for branch prediction) that stub
5078
sections only serve one group of input sections.  A negative value for
5079
`N' chooses this scheme, ensuring that branches to stubs always use a
5080
negative offset.  Two special values of `N' are recognized, `1' and
5081
`-1'.  These both instruct `ld' to automatically size input section
5082
groups for the branch types detected, with the same behaviour regarding
5083
stub placement as other positive or negative values of `N' respectively.
5084
 
5085
   Note that `--stub-group-size' does not split input sections.  A
5086
single input section larger than the group size specified will of course
5087
create a larger group (of one section).  If input sections are too
5088
large, it may not be possible for a branch to reach its stub.
5089
 
5090

5091
File: ld.info,  Node: M68K,  Next: MMIX,  Prev: HPPA ELF32,  Up: Machine Dependent
5092
 
5093
4.6 `ld' and the Motorola 68K family
5094
====================================
5095
 
5096
The `--got=TYPE' option lets you choose the GOT generation scheme.  The
5097
choices are `single', `negative', `multigot' and `target'.  When
5098
`target' is selected the linker chooses the default GOT generation
5099
scheme for the current target.  `single' tells the linker to generate a
5100
single GOT with entries only at non-negative offsets.  `negative'
5101
instructs the linker to generate a single GOT with entries at both
5102
negative and positive offsets.  Not all environments support such GOTs.
5103
`multigot' allows the linker to generate several GOTs in the output
5104
file.  All GOT references from a single input object file access the
5105
same GOT, but references from different input object files might access
5106
different GOTs.  Not all environments support such GOTs.
5107
 
5108

5109
File: ld.info,  Node: MMIX,  Next: MSP430,  Prev: M68K,  Up: Machine Dependent
5110
 
5111
4.7 `ld' and MMIX
5112
=================
5113
 
5114
For MMIX, there is a choice of generating `ELF' object files or `mmo'
5115
object files when linking.  The simulator `mmix' understands the `mmo'
5116
format.  The binutils `objcopy' utility can translate between the two
5117
formats.
5118
 
5119
   There is one special section, the `.MMIX.reg_contents' section.
5120
Contents in this section is assumed to correspond to that of global
5121
registers, and symbols referring to it are translated to special
5122
symbols, equal to registers.  In a final link, the start address of the
5123
`.MMIX.reg_contents' section corresponds to the first allocated global
5124
register multiplied by 8.  Register `$255' is not included in this
5125
section; it is always set to the program entry, which is at the symbol
5126
`Main' for `mmo' files.
5127
 
5128
   Global symbols with the prefix `__.MMIX.start.', for example
5129
`__.MMIX.start..text' and `__.MMIX.start..data' are special.  The
5130
default linker script uses these to set the default start address of a
5131
section.
5132
 
5133
   Initial and trailing multiples of zero-valued 32-bit words in a
5134
section, are left out from an mmo file.
5135
 
5136

5137
File: ld.info,  Node: MSP430,  Next: M68HC11/68HC12,  Prev: MMIX,  Up: Machine Dependent
5138
 
5139
4.8 `ld' and MSP430
5140
===================
5141
 
5142
For the MSP430 it is possible to select the MPU architecture.  The flag
5143
`-m [mpu type]' will select an appropriate linker script for selected
5144
MPU type.  (To get a list of known MPUs just pass `-m help' option to
5145
the linker).
5146
 
5147
   The linker will recognize some extra sections which are MSP430
5148
specific:
5149
 
5150
``.vectors''
5151
     Defines a portion of ROM where interrupt vectors located.
5152
 
5153
``.bootloader''
5154
     Defines the bootloader portion of the ROM (if applicable).  Any
5155
     code in this section will be uploaded to the MPU.
5156
 
5157
``.infomem''
5158
     Defines an information memory section (if applicable).  Any code in
5159
     this section will be uploaded to the MPU.
5160
 
5161
``.infomemnobits''
5162
     This is the same as the `.infomem' section except that any code in
5163
     this section will not be uploaded to the MPU.
5164
 
5165
``.noinit''
5166
     Denotes a portion of RAM located above `.bss' section.
5167
 
5168
     The last two sections are used by gcc.
5169
 
5170

5171
File: ld.info,  Node: PowerPC ELF32,  Next: PowerPC64 ELF64,  Prev: M68HC11/68HC12,  Up: Machine Dependent
5172
 
5173
4.9 `ld' and PowerPC 32-bit ELF Support
5174
=======================================
5175
 
5176
Branches on PowerPC processors are limited to a signed 26-bit
5177
displacement, which may result in `ld' giving `relocation truncated to
5178
fit' errors with very large programs.  `--relax' enables the generation
5179
of trampolines that can access the entire 32-bit address space.  These
5180
trampolines are inserted at section boundaries, so may not themselves
5181
be reachable if an input section exceeds 33M in size.  You may combine
5182
`-r' and `--relax' to add trampolines in a partial link.  In that case
5183
both branches to undefined symbols and inter-section branches are also
5184
considered potentially out of range, and trampolines inserted.
5185
 
5186
`--bss-plt'
5187
     Current PowerPC GCC accepts a `-msecure-plt' option that generates
5188
     code capable of using a newer PLT and GOT layout that has the
5189
     security advantage of no executable section ever needing to be
5190
     writable and no writable section ever being executable.  PowerPC
5191
     `ld' will generate this layout, including stubs to access the PLT,
5192
     if all input files (including startup and static libraries) were
5193
     compiled with `-msecure-plt'.  `--bss-plt' forces the old BSS PLT
5194
     (and GOT layout) which can give slightly better performance.
5195
 
5196
`--secure-plt'
5197
     `ld' will use the new PLT and GOT layout if it is linking new
5198
     `-fpic' or `-fPIC' code, but does not do so automatically when
5199
     linking non-PIC code.  This option requests the new PLT and GOT
5200
     layout.  A warning will be given if some object file requires the
5201
     old style BSS PLT.
5202
 
5203
`--sdata-got'
5204
     The new secure PLT and GOT are placed differently relative to other
5205
     sections compared to older BSS PLT and GOT placement.  The
5206
     location of `.plt' must change because the new secure PLT is an
5207
     initialized section while the old PLT is uninitialized.  The
5208
     reason for the `.got' change is more subtle:  The new placement
5209
     allows `.got' to be read-only in applications linked with `-z
5210
     relro -z now'.  However, this placement means that `.sdata' cannot
5211
     always be used in shared libraries, because the PowerPC ABI
5212
     accesses `.sdata' in shared libraries from the GOT pointer.
5213
     `--sdata-got' forces the old GOT placement.  PowerPC GCC doesn't
5214
     use `.sdata' in shared libraries, so this option is really only
5215
     useful for other compilers that may do so.
5216
 
5217
`--emit-stub-syms'
5218
     This option causes `ld' to label linker stubs with a local symbol
5219
     that encodes the stub type and destination.
5220
 
5221
`--no-tls-optimize'
5222
     PowerPC `ld' normally performs some optimization of code sequences
5223
     used to access Thread-Local Storage.  Use this option to disable
5224
     the optimization.
5225
 
5226

5227
File: ld.info,  Node: PowerPC64 ELF64,  Next: SPU ELF,  Prev: PowerPC ELF32,  Up: Machine Dependent
5228
 
5229
4.10 `ld' and PowerPC64 64-bit ELF Support
5230
==========================================
5231
 
5232
`--stub-group-size'
5233
     Long branch stubs, PLT call stubs  and TOC adjusting stubs are
5234
     placed by `ld' in stub sections located between groups of input
5235
     sections.  `--stub-group-size' specifies the maximum size of a
5236
     group of input sections handled by one stub section.  Since branch
5237
     offsets are signed, a stub section may serve two groups of input
5238
     sections, one group before the stub section, and one group after
5239
     it.  However, when using conditional branches that require stubs,
5240
     it may be better (for branch prediction) that stub sections only
5241
     serve one group of input sections.  A negative value for `N'
5242
     chooses this scheme, ensuring that branches to stubs always use a
5243
     negative offset.  Two special values of `N' are recognized, `1'
5244
     and `-1'.  These both instruct `ld' to automatically size input
5245
     section groups for the branch types detected, with the same
5246
     behaviour regarding stub placement as other positive or negative
5247
     values of `N' respectively.
5248
 
5249
     Note that `--stub-group-size' does not split input sections.  A
5250
     single input section larger than the group size specified will of
5251
     course create a larger group (of one section).  If input sections
5252
     are too large, it may not be possible for a branch to reach its
5253
     stub.
5254
 
5255
`--emit-stub-syms'
5256
     This option causes `ld' to label linker stubs with a local symbol
5257
     that encodes the stub type and destination.
5258
 
5259
`--dotsyms, --no-dotsyms'
5260
     These two options control how `ld' interprets version patterns in
5261
     a version script.  Older PowerPC64 compilers emitted both a
5262
     function descriptor symbol with the same name as the function, and
5263
     a code entry symbol with the name prefixed by a dot (`.').  To
5264
     properly version a function `foo', the version script thus needs
5265
     to control both `foo' and `.foo'.  The option `--dotsyms', on by
5266
     default, automatically adds the required dot-prefixed patterns.
5267
     Use `--no-dotsyms' to disable this feature.
5268
 
5269
`--no-tls-optimize'
5270
     PowerPC64 `ld' normally performs some optimization of code
5271
     sequences used to access Thread-Local Storage.  Use this option to
5272
     disable the optimization.
5273
 
5274
`--no-opd-optimize'
5275
     PowerPC64 `ld' normally removes `.opd' section entries
5276
     corresponding to deleted link-once functions, or functions removed
5277
     by the action of `--gc-sections' or linker script `/DISCARD/'.
5278
     Use this option to disable `.opd' optimization.
5279
 
5280
`--non-overlapping-opd'
5281
     Some PowerPC64 compilers have an option to generate compressed
5282
     `.opd' entries spaced 16 bytes apart, overlapping the third word,
5283
     the static chain pointer (unused in C) with the first word of the
5284
     next entry.  This option expands such entries to the full 24 bytes.
5285
 
5286
`--no-toc-optimize'
5287
     PowerPC64 `ld' normally removes unused `.toc' section entries.
5288
     Such entries are detected by examining relocations that reference
5289
     the TOC in code sections.  A reloc in a deleted code section marks
5290
     a TOC word as unneeded, while a reloc in a kept code section marks
5291
     a TOC word as needed.  Since the TOC may reference itself, TOC
5292
     relocs are also examined.  TOC words marked as both needed and
5293
     unneeded will of course be kept.  TOC words without any referencing
5294
     reloc are assumed to be part of a multi-word entry, and are kept or
5295
     discarded as per the nearest marked preceding word.  This works
5296
     reliably for compiler generated code, but may be incorrect if
5297
     assembly code is used to insert TOC entries.  Use this option to
5298
     disable the optimization.
5299
 
5300
`--no-multi-toc'
5301
     By default, PowerPC64 GCC generates code for a TOC model where TOC
5302
     entries are accessed with a 16-bit offset from r2.  This limits the
5303
     total TOC size to 64K.  PowerPC64 `ld' extends this limit by
5304
     grouping code sections such that each group uses less than 64K for
5305
     its TOC entries, then inserts r2 adjusting stubs between
5306
     inter-group calls.  `ld' does not split apart input sections, so
5307
     cannot help if a single input file has a `.toc' section that
5308
     exceeds 64K, most likely from linking multiple files with `ld -r'.
5309
     Use this option to turn off this feature.
5310
 
5311

5312
File: ld.info,  Node: SPU ELF,  Next: TI COFF,  Prev: PowerPC64 ELF64,  Up: Machine Dependent
5313
 
5314
4.11 `ld' and SPU ELF Support
5315
=============================
5316
 
5317
`--plugin'
5318
     This option marks an executable as a PIC plugin module.
5319
 
5320
`--no-overlays'
5321
     Normally, `ld' recognizes calls to functions within overlay
5322
     regions, and redirects such calls to an overlay manager via a stub.
5323
     `ld' also provides a built-in overlay manager.  This option turns
5324
     off all this special overlay handling.
5325
 
5326
`--emit-stub-syms'
5327
     This option causes `ld' to label overlay stubs with a local symbol
5328
     that encodes the stub type and destination.
5329
 
5330
`--extra-overlay-stubs'
5331
     This option causes `ld' to add overlay call stubs on all function
5332
     calls out of overlay regions.  Normally stubs are not added on
5333
     calls to non-overlay regions.
5334
 
5335
`--local-store=lo:hi'
5336
     `ld' usually checks that a final executable for SPU fits in the
5337
     address range 0 to 256k.  This option may be used to change the
5338
     range.  Disable the check entirely with `--local-store=0:0'.
5339
 
5340
`--stack-analysis'
5341
     SPU local store space is limited.  Over-allocation of stack space
5342
     unnecessarily limits space available for code and data, while
5343
     under-allocation results in runtime failures.  If given this
5344
     option, `ld' will provide an estimate of maximum stack usage.
5345
     `ld' does this by examining symbols in code sections to determine
5346
     the extents of functions, and looking at function prologues for
5347
     stack adjusting instructions.  A call-graph is created by looking
5348
     for relocations on branch instructions.  The graph is then searched
5349
     for the maximum stack usage path.  Note that this analysis does not
5350
     find calls made via function pointers, and does not handle
5351
     recursion and other cycles in the call graph.  Stack usage may be
5352
     under-estimated if your code makes such calls.  Also, stack usage
5353
     for dynamic allocation, e.g. alloca, will not be detected.  If a
5354
     link map is requested, detailed information about each function's
5355
     stack usage and calls will be given.
5356
 
5357
`--emit-stack-syms'
5358
     This option, if given along with `--stack-analysis' will result in
5359
     `ld' emitting stack sizing symbols for each function.  These take
5360
     the form `__stack_' for global functions, and
5361
     `__stack__' for static functions.
5362
     `' is the section id in hex.  The value of such symbols is
5363
     the stack requirement for the corresponding function.  The symbol
5364
     size will be zero, type `STT_NOTYPE', binding `STB_LOCAL', and
5365
     section `SHN_ABS'.
5366
 
5367

5368
File: ld.info,  Node: TI COFF,  Next: WIN32,  Prev: SPU ELF,  Up: Machine Dependent
5369
 
5370
4.12 `ld''s Support for Various TI COFF Versions
5371
================================================
5372
 
5373
The `--format' switch allows selection of one of the various TI COFF
5374
versions.  The latest of this writing is 2; versions 0 and 1 are also
5375
supported.  The TI COFF versions also vary in header byte-order format;
5376
`ld' will read any version or byte order, but the output header format
5377
depends on the default specified by the specific target.
5378
 
5379

5380
File: ld.info,  Node: WIN32,  Next: Xtensa,  Prev: TI COFF,  Up: Machine Dependent
5381
 
5382
4.13 `ld' and WIN32 (cygwin/mingw)
5383
==================================
5384
 
5385
This section describes some of the win32 specific `ld' issues.  See
5386
*Note Command Line Options: Options. for detailed description of the
5387
command line options mentioned here.
5388
 
5389
_import libraries_
5390
     The standard Windows linker creates and uses so-called import
5391
     libraries, which contains information for linking to dll's.  They
5392
     are regular static archives and are handled as any other static
5393
     archive.  The cygwin and mingw ports of `ld' have specific support
5394
     for creating such libraries provided with the `--out-implib'
5395
     command line option.
5396
 
5397
_exporting DLL symbols_
5398
     The cygwin/mingw `ld' has several ways to export symbols for dll's.
5399
 
5400
    _using auto-export functionality_
5401
          By default `ld' exports symbols with the auto-export
5402
          functionality, which is controlled by the following command
5403
          line options:
5404
 
5405
             * -export-all-symbols   [This is the default]
5406
 
5407
             * -exclude-symbols
5408
 
5409
             * -exclude-libs
5410
 
5411
             * -exclude-modules-for-implib
5412
 
5413
             * -version-script
5414
 
5415
          When auto-export is in operation, `ld' will export all the
5416
          non-local (global and common) symbols it finds in a DLL, with
5417
          the exception of a few symbols known to belong to the
5418
          system's runtime and libraries.  As it will often not be
5419
          desirable to export all of a DLL's symbols, which may include
5420
          private functions that are not part of any public interface,
5421
          the command-line options listed above may be used to filter
5422
          symbols out from the list for exporting.  The `--output-def'
5423
          option can be used in order to see the final list of exported
5424
          symbols with all exclusions taken into effect.
5425
 
5426
          If `--export-all-symbols' is not given explicitly on the
5427
          command line, then the default auto-export behavior will be
5428
          _disabled_ if either of the following are true:
5429
 
5430
             * A DEF file is used.
5431
 
5432
             * Any symbol in any object file was marked with the
5433
               __declspec(dllexport) attribute.
5434
 
5435
    _using a DEF file_
5436
          Another way of exporting symbols is using a DEF file.  A DEF
5437
          file is an ASCII file containing definitions of symbols which
5438
          should be exported when a dll is created.  Usually it is
5439
          named `.def' and is added as any other object file
5440
          to the linker's command line.  The file's name must end in
5441
          `.def' or `.DEF'.
5442
 
5443
               gcc -o   .def
5444
 
5445
          Using a DEF file turns off the normal auto-export behavior,
5446
          unless the `--export-all-symbols' option is also used.
5447
 
5448
          Here is an example of a DEF file for a shared library called
5449
          `xyz.dll':
5450
 
5451
               LIBRARY "xyz.dll" BASE=0x20000000
5452
 
5453
               EXPORTS
5454
               foo
5455
               bar
5456
               _bar = bar
5457
               another_foo = abc.dll.afoo
5458
               var1 DATA
5459
 
5460
          This example defines a DLL with a non-default base address
5461
          and five symbols in the export table. The third exported
5462
          symbol `_bar' is an alias for the second. The fourth symbol,
5463
          `another_foo' is resolved by "forwarding" to another module
5464
          and treating it as an alias for `afoo' exported from the DLL
5465
          `abc.dll'. The final symbol `var1' is declared to be a data
5466
          object.
5467
 
5468
          The optional `LIBRARY ' command indicates the _internal_
5469
          name of the output DLL. If `' does not include a suffix,
5470
          the default library suffix, `.DLL' is appended.
5471
 
5472
          When the .DEF file is used to build an application, rather
5473
          than a library, the `NAME ' command should be used
5474
          instead of `LIBRARY'. If `' does not include a suffix,
5475
          the default executable suffix, `.EXE' is appended.
5476
 
5477
          With either `LIBRARY ' or `NAME ' the optional
5478
          specification `BASE = ' may be used to specify a
5479
          non-default base address for the image.
5480
 
5481
          If neither `LIBRARY ' nor  `NAME ' is specified,
5482
          or they specify an empty string, the internal name is the
5483
          same as the filename specified on the command line.
5484
 
5485
          The complete specification of an export symbol is:
5486
 
5487
               EXPORTS
5488
                 ( (  (  [ =  ] )
5489
                    | (  =  . ))
5490
                 [ @  ] [NONAME] [DATA] [CONSTANT] [PRIVATE] ) *
5491
 
5492
          Declares `' as an exported symbol from the DLL, or
5493
          declares `' as an exported alias for `'; or
5494
          declares `' as a "forward" alias for the symbol
5495
          `' in the DLL `'.  Optionally,
5496
          the symbol may be exported by the specified ordinal
5497
          `' alias.
5498
 
5499
          The optional keywords that follow the declaration indicate:
5500
 
5501
          `NONAME': Do not put the symbol name in the DLL's export
5502
          table.  It will still be exported by its ordinal alias
5503
          (either the value specified by the .def specification or,
5504
          otherwise, the value assigned by the linker). The symbol
5505
          name, however, does remain visible in the import library (if
5506
          any), unless `PRIVATE' is also specified.
5507
 
5508
          `DATA': The symbol is a variable or object, rather than a
5509
          function.  The import lib will export only an indirect
5510
          reference to `foo' as the symbol `_imp__foo' (ie, `foo' must
5511
          be resolved as `*_imp__foo').
5512
 
5513
          `CONSTANT': Like `DATA', but put the undecorated `foo' as
5514
          well as `_imp__foo' into the import library. Both refer to the
5515
          read-only import address table's pointer to the variable, not
5516
          to the variable itself. This can be dangerous. If the user
5517
          code fails to add the `dllimport' attribute and also fails to
5518
          explicitly add the extra indirection that the use of the
5519
          attribute enforces, the application will behave unexpectedly.
5520
 
5521
          `PRIVATE': Put the symbol in the DLL's export table, but do
5522
          not put it into the static import library used to resolve
5523
          imports at link time. The symbol can still be imported using
5524
          the `LoadLibrary/GetProcAddress' API at runtime or by by
5525
          using the GNU ld extension of linking directly to the DLL
5526
          without an import library.
5527
 
5528
          See ld/deffilep.y in the binutils sources for the full
5529
          specification of other DEF file statements
5530
 
5531
          While linking a shared dll, `ld' is able to create a DEF file
5532
          with the `--output-def ' command line option.
5533
 
5534
    _Using decorations_
5535
          Another way of marking symbols for export is to modify the
5536
          source code itself, so that when building the DLL each symbol
5537
          to be exported is declared as:
5538
 
5539
               __declspec(dllexport) int a_variable
5540
               __declspec(dllexport) void a_function(int with_args)
5541
 
5542
          All such symbols will be exported from the DLL.  If, however,
5543
          any of the object files in the DLL contain symbols decorated
5544
          in this way, then the normal auto-export behavior is
5545
          disabled, unless the `--export-all-symbols' option is also
5546
          used.
5547
 
5548
          Note that object files that wish to access these symbols must
5549
          _not_ decorate them with dllexport.  Instead, they should use
5550
          dllimport, instead:
5551
 
5552
               __declspec(dllimport) int a_variable
5553
               __declspec(dllimport) void a_function(int with_args)
5554
 
5555
          This complicates the structure of library header files,
5556
          because when included by the library itself the header must
5557
          declare the variables and functions as dllexport, but when
5558
          included by client code the header must declare them as
5559
          dllimport.  There are a number of idioms that are typically
5560
          used to do this; often client code can omit the __declspec()
5561
          declaration completely.  See `--enable-auto-import' and
5562
          `automatic data imports' for more information.
5563
 
5564
_automatic data imports_
5565
     The standard Windows dll format supports data imports from dlls
5566
     only by adding special decorations (dllimport/dllexport), which
5567
     let the compiler produce specific assembler instructions to deal
5568
     with this issue.  This increases the effort necessary to port
5569
     existing Un*x code to these platforms, especially for large c++
5570
     libraries and applications.  The auto-import feature, which was
5571
     initially provided by Paul Sokolovsky, allows one to omit the
5572
     decorations to achieve a behavior that conforms to that on
5573
     POSIX/Un*x platforms. This feature is enabled with the
5574
     `--enable-auto-import' command-line option, although it is enabled
5575
     by default on cygwin/mingw.  The `--enable-auto-import' option
5576
     itself now serves mainly to suppress any warnings that are
5577
     ordinarily emitted when linked objects trigger the feature's use.
5578
 
5579
     auto-import of variables does not always work flawlessly without
5580
     additional assistance.  Sometimes, you will see this message
5581
 
5582
     "variable '' can't be auto-imported. Please read the
5583
     documentation for ld's `--enable-auto-import' for details."
5584
 
5585
     The `--enable-auto-import' documentation explains why this error
5586
     occurs, and several methods that can be used to overcome this
5587
     difficulty.  One of these methods is the _runtime pseudo-relocs_
5588
     feature, described below.
5589
 
5590
     For complex variables imported from DLLs (such as structs or
5591
     classes), object files typically contain a base address for the
5592
     variable and an offset (_addend_) within the variable-to specify a
5593
     particular field or public member, for instance.  Unfortunately,
5594
     the runtime loader used in win32 environments is incapable of
5595
     fixing these references at runtime without the additional
5596
     information supplied by dllimport/dllexport decorations.  The
5597
     standard auto-import feature described above is unable to resolve
5598
     these references.
5599
 
5600
     The `--enable-runtime-pseudo-relocs' switch allows these
5601
     references to be resolved without error, while leaving the task of
5602
     adjusting the references themselves (with their non-zero addends)
5603
     to specialized code provided by the runtime environment.  Recent
5604
     versions of the cygwin and mingw environments and compilers
5605
     provide this runtime support; older versions do not.  However, the
5606
     support is only necessary on the developer's platform; the
5607
     compiled result will run without error on an older system.
5608
 
5609
     `--enable-runtime-pseudo-relocs' is not the default; it must be
5610
     explicitly enabled as needed.
5611
 
5612
_direct linking to a dll_
5613
     The cygwin/mingw ports of `ld' support the direct linking,
5614
     including data symbols, to a dll without the usage of any import
5615
     libraries.  This is much faster and uses much less memory than
5616
     does the traditional import library method, especially when
5617
     linking large libraries or applications.  When `ld' creates an
5618
     import lib, each function or variable exported from the dll is
5619
     stored in its own bfd, even though a single bfd could contain many
5620
     exports.  The overhead involved in storing, loading, and
5621
     processing so many bfd's is quite large, and explains the
5622
     tremendous time, memory, and storage needed to link against
5623
     particularly large or complex libraries when using import libs.
5624
 
5625
     Linking directly to a dll uses no extra command-line switches
5626
     other than `-L' and `-l', because `ld' already searches for a
5627
     number of names to match each library.  All that is needed from
5628
     the developer's perspective is an understanding of this search, in
5629
     order to force ld to select the dll instead of an import library.
5630
 
5631
     For instance, when ld is called with the argument `-lxxx' it will
5632
     attempt to find, in the first directory of its search path,
5633
 
5634
          libxxx.dll.a
5635
          xxx.dll.a
5636
          libxxx.a
5637
          xxx.lib
5638
          cygxxx.dll (*)
5639
          libxxx.dll
5640
          xxx.dll
5641
 
5642
     before moving on to the next directory in the search path.
5643
 
5644
     (*) Actually, this is not `cygxxx.dll' but in fact is
5645
     `xxx.dll', where `' is set by the `ld' option
5646
     `--dll-search-prefix='. In the case of cygwin, the
5647
     standard gcc spec file includes `--dll-search-prefix=cyg', so in
5648
     effect we actually search for `cygxxx.dll'.
5649
 
5650
     Other win32-based unix environments, such as mingw or pw32, may
5651
     use other `'es, although at present only cygwin makes use
5652
     of this feature.  It was originally intended to help avoid name
5653
     conflicts among dll's built for the various win32/un*x
5654
     environments, so that (for example) two versions of a zlib dll
5655
     could coexist on the same machine.
5656
 
5657
     The generic cygwin/mingw path layout uses a `bin' directory for
5658
     applications and dll's and a `lib' directory for the import
5659
     libraries (using cygwin nomenclature):
5660
 
5661
          bin/
5662
                cygxxx.dll
5663
          lib/
5664
                libxxx.dll.a   (in case of dll's)
5665
                libxxx.a       (in case of static archive)
5666
 
5667
     Linking directly to a dll without using the import library can be
5668
     done two ways:
5669
 
5670
     1. Use the dll directly by adding the `bin' path to the link line
5671
          gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx
5672
 
5673
     However, as the dll's often have version numbers appended to their
5674
     names (`cygncurses-5.dll') this will often fail, unless one
5675
     specifies `-L../bin -lncurses-5' to include the version.  Import
5676
     libs are generally not versioned, and do not have this difficulty.
5677
 
5678
     2. Create a symbolic link from the dll to a file in the `lib'
5679
     directory according to the above mentioned search pattern.  This
5680
     should be used to avoid unwanted changes in the tools needed for
5681
     making the app/dll.
5682
 
5683
          ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
5684
 
5685
     Then you can link without any make environment changes.
5686
 
5687
          gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx
5688
 
5689
     This technique also avoids the version number problems, because
5690
     the following is perfectly legal
5691
 
5692
          bin/
5693
                cygxxx-5.dll
5694
          lib/
5695
                libxxx.dll.a -> ../bin/cygxxx-5.dll
5696
 
5697
     Linking directly to a dll without using an import lib will work
5698
     even when auto-import features are exercised, and even when
5699
     `--enable-runtime-pseudo-relocs' is used.
5700
 
5701
     Given the improvements in speed and memory usage, one might
5702
     justifiably wonder why import libraries are used at all.  There
5703
     are three reasons:
5704
 
5705
     1. Until recently, the link-directly-to-dll functionality did _not_
5706
     work with auto-imported data.
5707
 
5708
     2. Sometimes it is necessary to include pure static objects within
5709
     the import library (which otherwise contains only bfd's for
5710
     indirection symbols that point to the exports of a dll).  Again,
5711
     the import lib for the cygwin kernel makes use of this ability,
5712
     and it is not possible to do this without an import lib.
5713
 
5714
     3. Symbol aliases can only be resolved using an import lib.  This
5715
     is critical when linking against OS-supplied dll's (eg, the win32
5716
     API) in which symbols are usually exported as undecorated aliases
5717
     of their stdcall-decorated assembly names.
5718
 
5719
     So, import libs are not going away.  But the ability to replace
5720
     true import libs with a simple symbolic link to (or a copy of) a
5721
     dll, in many cases, is a useful addition to the suite of tools
5722
     binutils makes available to the win32 developer.  Given the
5723
     massive improvements in memory requirements during linking, storage
5724
     requirements, and linking speed, we expect that many developers
5725
     will soon begin to use this feature whenever possible.
5726
 
5727
_symbol aliasing_
5728
 
5729
    _adding additional names_
5730
          Sometimes, it is useful to export symbols with additional
5731
          names.  A symbol `foo' will be exported as `foo', but it can
5732
          also be exported as `_foo' by using special directives in the
5733
          DEF file when creating the dll.  This will affect also the
5734
          optional created import library.  Consider the following DEF
5735
          file:
5736
 
5737
               LIBRARY "xyz.dll" BASE=0x61000000
5738
 
5739
               EXPORTS
5740
               foo
5741
               _foo = foo
5742
 
5743
          The line `_foo = foo' maps the symbol `foo' to `_foo'.
5744
 
5745
          Another method for creating a symbol alias is to create it in
5746
          the source code using the "weak" attribute:
5747
 
5748
               void foo () { /* Do something.  */; }
5749
               void _foo () __attribute__ ((weak, alias ("foo")));
5750
 
5751
          See the gcc manual for more information about attributes and
5752
          weak symbols.
5753
 
5754
    _renaming symbols_
5755
          Sometimes it is useful to rename exports.  For instance, the
5756
          cygwin kernel does this regularly.  A symbol `_foo' can be
5757
          exported as `foo' but not as `_foo' by using special
5758
          directives in the DEF file. (This will also affect the import
5759
          library, if it is created).  In the following example:
5760
 
5761
               LIBRARY "xyz.dll" BASE=0x61000000
5762
 
5763
               EXPORTS
5764
               _foo = foo
5765
 
5766
          The line `_foo = foo' maps the exported symbol `foo' to
5767
          `_foo'.
5768
 
5769
     Note: using a DEF file disables the default auto-export behavior,
5770
     unless the `--export-all-symbols' command line option is used.
5771
     If, however, you are trying to rename symbols, then you should list
5772
     _all_ desired exports in the DEF file, including the symbols that
5773
     are not being renamed, and do _not_ use the `--export-all-symbols'
5774
     option.  If you list only the renamed symbols in the DEF file, and
5775
     use `--export-all-symbols' to handle the other symbols, then the
5776
     both the new names _and_ the original names for the renamed
5777
     symbols will be exported.  In effect, you'd be aliasing those
5778
     symbols, not renaming them, which is probably not what you wanted.
5779
 
5780
_weak externals_
5781
     The Windows object format, PE, specifies a form of weak symbols
5782
     called weak externals.  When a weak symbol is linked and the
5783
     symbol is not defined, the weak symbol becomes an alias for some
5784
     other symbol.  There are three variants of weak externals:
5785
        * Definition is searched for in objects and libraries,
5786
          historically called lazy externals.
5787
 
5788
        * Definition is searched for only in other objects, not in
5789
          libraries.  This form is not presently implemented.
5790
 
5791
        * No search; the symbol is an alias.  This form is not presently
5792
          implemented.
5793
     As a GNU extension, weak symbols that do not specify an alternate
5794
     symbol are supported.  If the symbol is undefined when linking,
5795
     the symbol uses a default value.
5796
 
5797
_aligned common symbols_
5798
     As a GNU extension to the PE file format, it is possible to
5799
     specify the desired alignment for a common symbol.  This
5800
     information is conveyed from the assembler or compiler to the
5801
     linker by means of GNU-specific commands carried in the object
5802
     file's `.drectve' section, which are recognized by `ld' and
5803
     respected when laying out the common symbols.  Native tools will
5804
     be able to process object files employing this GNU extension, but
5805
     will fail to respect the alignment instructions, and may issue
5806
     noisy warnings about unknown linker directives.
5807
 
5808

5809
File: ld.info,  Node: Xtensa,  Prev: WIN32,  Up: Machine Dependent
5810
 
5811
4.14 `ld' and Xtensa Processors
5812
===============================
5813
 
5814
The default `ld' behavior for Xtensa processors is to interpret
5815
`SECTIONS' commands so that lists of explicitly named sections in a
5816
specification with a wildcard file will be interleaved when necessary to
5817
keep literal pools within the range of PC-relative load offsets.  For
5818
example, with the command:
5819
 
5820
     SECTIONS
5821
     {
5822
       .text : {
5823
         *(.literal .text)
5824
       }
5825
     }
5826
 
5827
`ld' may interleave some of the `.literal' and `.text' sections from
5828
different object files to ensure that the literal pools are within the
5829
range of PC-relative load offsets.  A valid interleaving might place
5830
the `.literal' sections from an initial group of files followed by the
5831
`.text' sections of that group of files.  Then, the `.literal' sections
5832
from the rest of the files and the `.text' sections from the rest of
5833
the files would follow.
5834
 
5835
   Relaxation is enabled by default for the Xtensa version of `ld' and
5836
provides two important link-time optimizations.  The first optimization
5837
is to combine identical literal values to reduce code size.  A redundant
5838
literal will be removed and all the `L32R' instructions that use it
5839
will be changed to reference an identical literal, as long as the
5840
location of the replacement literal is within the offset range of all
5841
the `L32R' instructions.  The second optimization is to remove
5842
unnecessary overhead from assembler-generated "longcall" sequences of
5843
`L32R'/`CALLXN' when the target functions are within range of direct
5844
`CALLN' instructions.
5845
 
5846
   For each of these cases where an indirect call sequence can be
5847
optimized to a direct call, the linker will change the `CALLXN'
5848
instruction to a `CALLN' instruction, remove the `L32R' instruction,
5849
and remove the literal referenced by the `L32R' instruction if it is
5850
not used for anything else.  Removing the `L32R' instruction always
5851
reduces code size but can potentially hurt performance by changing the
5852
alignment of subsequent branch targets.  By default, the linker will
5853
always preserve alignments, either by switching some instructions
5854
between 24-bit encodings and the equivalent density instructions or by
5855
inserting a no-op in place of the `L32R' instruction that was removed.
5856
If code size is more important than performance, the `--size-opt'
5857
option can be used to prevent the linker from widening density
5858
instructions or inserting no-ops, except in a few cases where no-ops
5859
are required for correctness.
5860
 
5861
   The following Xtensa-specific command-line options can be used to
5862
control the linker:
5863
 
5864
`--no-relax'
5865
     Since the Xtensa version of `ld' enables the `--relax' option by
5866
     default, the `--no-relax' option is provided to disable relaxation.
5867
 
5868
`--size-opt'
5869
     When optimizing indirect calls to direct calls, optimize for code
5870
     size more than performance.  With this option, the linker will not
5871
     insert no-ops or widen density instructions to preserve branch
5872
     target alignment.  There may still be some cases where no-ops are
5873
     required to preserve the correctness of the code.
5874
 
5875

5876
File: ld.info,  Node: BFD,  Next: Reporting Bugs,  Prev: Machine Dependent,  Up: Top
5877
 
5878
5 BFD
5879
*****
5880
 
5881
The linker accesses object and archive files using the BFD libraries.
5882
These libraries allow the linker to use the same routines to operate on
5883
object files whatever the object file format.  A different object file
5884
format can be supported simply by creating a new BFD back end and adding
5885
it to the library.  To conserve runtime memory, however, the linker and
5886
associated tools are usually configured to support only a subset of the
5887
object file formats available.  You can use `objdump -i' (*note
5888
objdump: (binutils.info)objdump.) to list all the formats available for
5889
your configuration.
5890
 
5891
   As with most implementations, BFD is a compromise between several
5892
conflicting requirements. The major factor influencing BFD design was
5893
efficiency: any time used converting between formats is time which
5894
would not have been spent had BFD not been involved. This is partly
5895
offset by abstraction payback; since BFD simplifies applications and
5896
back ends, more time and care may be spent optimizing algorithms for a
5897
greater speed.
5898
 
5899
   One minor artifact of the BFD solution which you should bear in mind
5900
is the potential for information loss.  There are two places where
5901
useful information can be lost using the BFD mechanism: during
5902
conversion and during output. *Note BFD information loss::.
5903
 
5904
* Menu:
5905
 
5906
* BFD outline::                 How it works: an outline of BFD
5907
 
5908

5909
File: ld.info,  Node: BFD outline,  Up: BFD
5910
 
5911
5.1 How It Works: An Outline of BFD
5912
===================================
5913
 
5914
When an object file is opened, BFD subroutines automatically determine
5915
the format of the input object file.  They then build a descriptor in
5916
memory with pointers to routines that will be used to access elements of
5917
the object file's data structures.
5918
 
5919
   As different information from the object files is required, BFD
5920
reads from different sections of the file and processes them.  For
5921
example, a very common operation for the linker is processing symbol
5922
tables.  Each BFD back end provides a routine for converting between
5923
the object file's representation of symbols and an internal canonical
5924
format. When the linker asks for the symbol table of an object file, it
5925
calls through a memory pointer to the routine from the relevant BFD
5926
back end which reads and converts the table into a canonical form.  The
5927
linker then operates upon the canonical form. When the link is finished
5928
and the linker writes the output file's symbol table, another BFD back
5929
end routine is called to take the newly created symbol table and
5930
convert it into the chosen output format.
5931
 
5932
* Menu:
5933
 
5934
* BFD information loss::        Information Loss
5935
* Canonical format::            The BFD canonical object-file format
5936
 
5937

5938
File: ld.info,  Node: BFD information loss,  Next: Canonical format,  Up: BFD outline
5939
 
5940
5.1.1 Information Loss
5941
----------------------
5942
 
5943
_Information can be lost during output._ The output formats supported
5944
by BFD do not provide identical facilities, and information which can
5945
be described in one form has nowhere to go in another format. One
5946
example of this is alignment information in `b.out'. There is nowhere
5947
in an `a.out' format file to store alignment information on the
5948
contained data, so when a file is linked from `b.out' and an `a.out'
5949
image is produced, alignment information will not propagate to the
5950
output file. (The linker will still use the alignment information
5951
internally, so the link is performed correctly).
5952
 
5953
   Another example is COFF section names. COFF files may contain an
5954
unlimited number of sections, each one with a textual section name. If
5955
the target of the link is a format which does not have many sections
5956
(e.g., `a.out') or has sections without names (e.g., the Oasys format),
5957
the link cannot be done simply. You can circumvent this problem by
5958
describing the desired input-to-output section mapping with the linker
5959
command language.
5960
 
5961
   _Information can be lost during canonicalization._ The BFD internal
5962
canonical form of the external formats is not exhaustive; there are
5963
structures in input formats for which there is no direct representation
5964
internally.  This means that the BFD back ends cannot maintain all
5965
possible data richness through the transformation between external to
5966
internal and back to external formats.
5967
 
5968
   This limitation is only a problem when an application reads one
5969
format and writes another.  Each BFD back end is responsible for
5970
maintaining as much data as possible, and the internal BFD canonical
5971
form has structures which are opaque to the BFD core, and exported only
5972
to the back ends. When a file is read in one format, the canonical form
5973
is generated for BFD and the application. At the same time, the back
5974
end saves away any information which may otherwise be lost. If the data
5975
is then written back in the same format, the back end routine will be
5976
able to use the canonical form provided by the BFD core as well as the
5977
information it prepared earlier.  Since there is a great deal of
5978
commonality between back ends, there is no information lost when
5979
linking or copying big endian COFF to little endian COFF, or `a.out' to
5980
`b.out'.  When a mixture of formats is linked, the information is only
5981
lost from the files whose format differs from the destination.
5982
 
5983

5984
File: ld.info,  Node: Canonical format,  Prev: BFD information loss,  Up: BFD outline
5985
 
5986
5.1.2 The BFD canonical object-file format
5987
------------------------------------------
5988
 
5989
The greatest potential for loss of information occurs when there is the
5990
least overlap between the information provided by the source format,
5991
that stored by the canonical format, and that needed by the destination
5992
format. A brief description of the canonical form may help you
5993
understand which kinds of data you can count on preserving across
5994
conversions.
5995
 
5996
_files_
5997
     Information stored on a per-file basis includes target machine
5998
     architecture, particular implementation format type, a demand
5999
     pageable bit, and a write protected bit.  Information like Unix
6000
     magic numbers is not stored here--only the magic numbers' meaning,
6001
     so a `ZMAGIC' file would have both the demand pageable bit and the
6002
     write protected text bit set.  The byte order of the target is
6003
     stored on a per-file basis, so that big- and little-endian object
6004
     files may be used with one another.
6005
 
6006
_sections_
6007
     Each section in the input file contains the name of the section,
6008
     the section's original address in the object file, size and
6009
     alignment information, various flags, and pointers into other BFD
6010
     data structures.
6011
 
6012
_symbols_
6013
     Each symbol contains a pointer to the information for the object
6014
     file which originally defined it, its name, its value, and various
6015
     flag bits.  When a BFD back end reads in a symbol table, it
6016
     relocates all symbols to make them relative to the base of the
6017
     section where they were defined.  Doing this ensures that each
6018
     symbol points to its containing section.  Each symbol also has a
6019
     varying amount of hidden private data for the BFD back end.  Since
6020
     the symbol points to the original file, the private data format
6021
     for that symbol is accessible.  `ld' can operate on a collection
6022
     of symbols of wildly different formats without problems.
6023
 
6024
     Normal global and simple local symbols are maintained on output,
6025
     so an output file (no matter its format) will retain symbols
6026
     pointing to functions and to global, static, and common variables.
6027
     Some symbol information is not worth retaining; in `a.out', type
6028
     information is stored in the symbol table as long symbol names.
6029
     This information would be useless to most COFF debuggers; the
6030
     linker has command line switches to allow users to throw it away.
6031
 
6032
     There is one word of type information within the symbol, so if the
6033
     format supports symbol type information within symbols (for
6034
     example, COFF, IEEE, Oasys) and the type is simple enough to fit
6035
     within one word (nearly everything but aggregates), the
6036
     information will be preserved.
6037
 
6038
_relocation level_
6039
     Each canonical BFD relocation record contains a pointer to the
6040
     symbol to relocate to, the offset of the data to relocate, the
6041
     section the data is in, and a pointer to a relocation type
6042
     descriptor. Relocation is performed by passing messages through
6043
     the relocation type descriptor and the symbol pointer. Therefore,
6044
     relocations can be performed on output data using a relocation
6045
     method that is only available in one of the input formats. For
6046
     instance, Oasys provides a byte relocation format.  A relocation
6047
     record requesting this relocation type would point indirectly to a
6048
     routine to perform this, so the relocation may be performed on a
6049
     byte being written to a 68k COFF file, even though 68k COFF has no
6050
     such relocation type.
6051
 
6052
_line numbers_
6053
     Object formats can contain, for debugging purposes, some form of
6054
     mapping between symbols, source line numbers, and addresses in the
6055
     output file.  These addresses have to be relocated along with the
6056
     symbol information.  Each symbol with an associated list of line
6057
     number records points to the first record of the list.  The head
6058
     of a line number list consists of a pointer to the symbol, which
6059
     allows finding out the address of the function whose line number
6060
     is being described. The rest of the list is made up of pairs:
6061
     offsets into the section and line numbers. Any format which can
6062
     simply derive this information can pass it successfully between
6063
     formats (COFF, IEEE and Oasys).
6064
 
6065

6066
File: ld.info,  Node: Reporting Bugs,  Next: MRI,  Prev: BFD,  Up: Top
6067
 
6068
6 Reporting Bugs
6069
****************
6070
 
6071
Your bug reports play an essential role in making `ld' reliable.
6072
 
6073
   Reporting a bug may help you by bringing a solution to your problem,
6074
or it may not.  But in any case the principal function of a bug report
6075
is to help the entire community by making the next version of `ld' work
6076
better.  Bug reports are your contribution to the maintenance of `ld'.
6077
 
6078
   In order for a bug report to serve its purpose, you must include the
6079
information that enables us to fix the bug.
6080
 
6081
* Menu:
6082
 
6083
* Bug Criteria::                Have you found a bug?
6084
* Bug Reporting::               How to report bugs
6085
 
6086

6087
File: ld.info,  Node: Bug Criteria,  Next: Bug Reporting,  Up: Reporting Bugs
6088
 
6089
6.1 Have You Found a Bug?
6090
=========================
6091
 
6092
If you are not sure whether you have found a bug, here are some
6093
guidelines:
6094
 
6095
   * If the linker gets a fatal signal, for any input whatever, that is
6096
     a `ld' bug.  Reliable linkers never crash.
6097
 
6098
   * If `ld' produces an error message for valid input, that is a bug.
6099
 
6100
   * If `ld' does not produce an error message for invalid input, that
6101
     may be a bug.  In the general case, the linker can not verify that
6102
     object files are correct.
6103
 
6104
   * If you are an experienced user of linkers, your suggestions for
6105
     improvement of `ld' are welcome in any case.
6106
 
6107

6108
File: ld.info,  Node: Bug Reporting,  Prev: Bug Criteria,  Up: Reporting Bugs
6109
 
6110
6.2 How to Report Bugs
6111
======================
6112
 
6113
A number of companies and individuals offer support for GNU products.
6114
If you obtained `ld' from a support organization, we recommend you
6115
contact that organization first.
6116
 
6117
   You can find contact information for many support companies and
6118
individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
6119
 
6120
   Otherwise, send bug reports for `ld' to
6121
`http://www.sourceware.org/bugzilla/'.
6122
 
6123
   The fundamental principle of reporting bugs usefully is this:
6124
*report all the facts*.  If you are not sure whether to state a fact or
6125
leave it out, state it!
6126
 
6127
   Often people omit facts because they think they know what causes the
6128
problem and assume that some details do not matter.  Thus, you might
6129
assume that the name of a symbol you use in an example does not matter.
6130
Well, probably it does not, but one cannot be sure.  Perhaps the bug
6131
is a stray memory reference which happens to fetch from the location
6132
where that name is stored in memory; perhaps, if the name were
6133
different, the contents of that location would fool the linker into
6134
doing the right thing despite the bug.  Play it safe and give a
6135
specific, complete example.  That is the easiest thing for you to do,
6136
and the most helpful.
6137
 
6138
   Keep in mind that the purpose of a bug report is to enable us to fix
6139
the bug if it is new to us.  Therefore, always write your bug reports
6140
on the assumption that the bug has not been reported previously.
6141
 
6142
   Sometimes people give a few sketchy facts and ask, "Does this ring a
6143
bell?"  This cannot help us fix a bug, so it is basically useless.  We
6144
respond by asking for enough details to enable us to investigate.  You
6145
might as well expedite matters by sending them to begin with.
6146
 
6147
   To enable us to fix the bug, you should include all these things:
6148
 
6149
   * The version of `ld'.  `ld' announces it if you start it with the
6150
     `--version' argument.
6151
 
6152
     Without this, we will not know whether there is any point in
6153
     looking for the bug in the current version of `ld'.
6154
 
6155
   * Any patches you may have applied to the `ld' source, including any
6156
     patches made to the `BFD' library.
6157
 
6158
   * The type of machine you are using, and the operating system name
6159
     and version number.
6160
 
6161
   * What compiler (and its version) was used to compile `ld'--e.g.
6162
     "`gcc-2.7'".
6163
 
6164
   * The command arguments you gave the linker to link your example and
6165
     observe the bug.  To guarantee you will not omit something
6166
     important, list them all.  A copy of the Makefile (or the output
6167
     from make) is sufficient.
6168
 
6169
     If we were to try to guess the arguments, we would probably guess
6170
     wrong and then we might not encounter the bug.
6171
 
6172
   * A complete input file, or set of input files, that will reproduce
6173
     the bug.  It is generally most helpful to send the actual object
6174
     files provided that they are reasonably small.  Say no more than
6175
     10K.  For bigger files you can either make them available by FTP
6176
     or HTTP or else state that you are willing to send the object
6177
     file(s) to whomever requests them.  (Note - your email will be
6178
     going to a mailing list, so we do not want to clog it up with
6179
     large attachments).  But small attachments are best.
6180
 
6181
     If the source files were assembled using `gas' or compiled using
6182
     `gcc', then it may be OK to send the source files rather than the
6183
     object files.  In this case, be sure to say exactly what version of
6184
     `gas' or `gcc' was used to produce the object files.  Also say how
6185
     `gas' or `gcc' were configured.
6186
 
6187
   * A description of what behavior you observe that you believe is
6188
     incorrect.  For example, "It gets a fatal signal."
6189
 
6190
     Of course, if the bug is that `ld' gets a fatal signal, then we
6191
     will certainly notice it.  But if the bug is incorrect output, we
6192
     might not notice unless it is glaringly wrong.  You might as well
6193
     not give us a chance to make a mistake.
6194
 
6195
     Even if the problem you experience is a fatal signal, you should
6196
     still say so explicitly.  Suppose something strange is going on,
6197
     such as, your copy of `ld' is out of sync, or you have encountered
6198
     a bug in the C library on your system.  (This has happened!)  Your
6199
     copy might crash and ours would not.  If you told us to expect a
6200
     crash, then when ours fails to crash, we would know that the bug
6201
     was not happening for us.  If you had not told us to expect a
6202
     crash, then we would not be able to draw any conclusion from our
6203
     observations.
6204
 
6205
   * If you wish to suggest changes to the `ld' source, send us context
6206
     diffs, as generated by `diff' with the `-u', `-c', or `-p' option.
6207
     Always send diffs from the old file to the new file.  If you even
6208
     discuss something in the `ld' source, refer to it by context, not
6209
     by line number.
6210
 
6211
     The line numbers in our development sources will not match those
6212
     in your sources.  Your line numbers would convey no useful
6213
     information to us.
6214
 
6215
   Here are some things that are not necessary:
6216
 
6217
   * A description of the envelope of the bug.
6218
 
6219
     Often people who encounter a bug spend a lot of time investigating
6220
     which changes to the input file will make the bug go away and which
6221
     changes will not affect it.
6222
 
6223
     This is often time consuming and not very useful, because the way
6224
     we will find the bug is by running a single example under the
6225
     debugger with breakpoints, not by pure deduction from a series of
6226
     examples.  We recommend that you save your time for something else.
6227
 
6228
     Of course, if you can find a simpler example to report _instead_
6229
     of the original one, that is a convenience for us.  Errors in the
6230
     output will be easier to spot, running under the debugger will take
6231
     less time, and so on.
6232
 
6233
     However, simplification is not vital; if you do not want to do
6234
     this, report the bug anyway and send us the entire test case you
6235
     used.
6236
 
6237
   * A patch for the bug.
6238
 
6239
     A patch for the bug does help us if it is a good one.  But do not
6240
     omit the necessary information, such as the test case, on the
6241
     assumption that a patch is all we need.  We might see problems
6242
     with your patch and decide to fix the problem another way, or we
6243
     might not understand it at all.
6244
 
6245
     Sometimes with a program as complicated as `ld' it is very hard to
6246
     construct an example that will make the program follow a certain
6247
     path through the code.  If you do not send us the example, we will
6248
     not be able to construct one, so we will not be able to verify
6249
     that the bug is fixed.
6250
 
6251
     And if we cannot understand what bug you are trying to fix, or why
6252
     your patch should be an improvement, we will not install it.  A
6253
     test case will help us to understand.
6254
 
6255
   * A guess about what the bug is or what it depends on.
6256
 
6257
     Such guesses are usually wrong.  Even we cannot guess right about
6258
     such things without first using the debugger to find the facts.
6259
 
6260

6261
File: ld.info,  Node: MRI,  Next: GNU Free Documentation License,  Prev: Reporting Bugs,  Up: Top
6262
 
6263
Appendix A MRI Compatible Script Files
6264
**************************************
6265
 
6266
To aid users making the transition to GNU `ld' from the MRI linker,
6267
`ld' can use MRI compatible linker scripts as an alternative to the
6268
more general-purpose linker scripting language described in *Note
6269
Scripts::.  MRI compatible linker scripts have a much simpler command
6270
set than the scripting language otherwise used with `ld'.  GNU `ld'
6271
supports the most commonly used MRI linker commands; these commands are
6272
described here.
6273
 
6274
   In general, MRI scripts aren't of much use with the `a.out' object
6275
file format, since it only has three sections and MRI scripts lack some
6276
features to make use of them.
6277
 
6278
   You can specify a file containing an MRI-compatible script using the
6279
`-c' command-line option.
6280
 
6281
   Each command in an MRI-compatible script occupies its own line; each
6282
command line starts with the keyword that identifies the command (though
6283
blank lines are also allowed for punctuation).  If a line of an
6284
MRI-compatible script begins with an unrecognized keyword, `ld' issues
6285
a warning message, but continues processing the script.
6286
 
6287
   Lines beginning with `*' are comments.
6288
 
6289
   You can write these commands using all upper-case letters, or all
6290
lower case; for example, `chip' is the same as `CHIP'.  The following
6291
list shows only the upper-case form of each command.
6292
 
6293
`ABSOLUTE SECNAME'
6294
`ABSOLUTE SECNAME, SECNAME, ... SECNAME'
6295
     Normally, `ld' includes in the output file all sections from all
6296
     the input files.  However, in an MRI-compatible script, you can
6297
     use the `ABSOLUTE' command to restrict the sections that will be
6298
     present in your output program.  If the `ABSOLUTE' command is used
6299
     at all in a script, then only the sections named explicitly in
6300
     `ABSOLUTE' commands will appear in the linker output.  You can
6301
     still use other input sections (whatever you select on the command
6302
     line, or using `LOAD') to resolve addresses in the output file.
6303
 
6304
`ALIAS OUT-SECNAME, IN-SECNAME'
6305
     Use this command to place the data from input section IN-SECNAME
6306
     in a section called OUT-SECNAME in the linker output file.
6307
 
6308
     IN-SECNAME may be an integer.
6309
 
6310
`ALIGN SECNAME = EXPRESSION'
6311
     Align the section called SECNAME to EXPRESSION.  The EXPRESSION
6312
     should be a power of two.
6313
 
6314
`BASE EXPRESSION'
6315
     Use the value of EXPRESSION as the lowest address (other than
6316
     absolute addresses) in the output file.
6317
 
6318
`CHIP EXPRESSION'
6319
`CHIP EXPRESSION, EXPRESSION'
6320
     This command does nothing; it is accepted only for compatibility.
6321
 
6322
`END'
6323
     This command does nothing whatever; it's only accepted for
6324
     compatibility.
6325
 
6326
`FORMAT OUTPUT-FORMAT'
6327
     Similar to the `OUTPUT_FORMAT' command in the more general linker
6328
     language, but restricted to one of these output formats:
6329
 
6330
       1. S-records, if OUTPUT-FORMAT is `S'
6331
 
6332
       2. IEEE, if OUTPUT-FORMAT is `IEEE'
6333
 
6334
       3. COFF (the `coff-m68k' variant in BFD), if OUTPUT-FORMAT is
6335
          `COFF'
6336
 
6337
`LIST ANYTHING...'
6338
     Print (to the standard output file) a link map, as produced by the
6339
     `ld' command-line option `-M'.
6340
 
6341
     The keyword `LIST' may be followed by anything on the same line,
6342
     with no change in its effect.
6343
 
6344
`LOAD FILENAME'
6345
`LOAD FILENAME, FILENAME, ... FILENAME'
6346
     Include one or more object file FILENAME in the link; this has the
6347
     same effect as specifying FILENAME directly on the `ld' command
6348
     line.
6349
 
6350
`NAME OUTPUT-NAME'
6351
     OUTPUT-NAME is the name for the program produced by `ld'; the
6352
     MRI-compatible command `NAME' is equivalent to the command-line
6353
     option `-o' or the general script language command `OUTPUT'.
6354
 
6355
`ORDER SECNAME, SECNAME, ... SECNAME'
6356
`ORDER SECNAME SECNAME SECNAME'
6357
     Normally, `ld' orders the sections in its output file in the order
6358
     in which they first appear in the input files.  In an
6359
     MRI-compatible script, you can override this ordering with the
6360
     `ORDER' command.  The sections you list with `ORDER' will appear
6361
     first in your output file, in the order specified.
6362
 
6363
`PUBLIC NAME=EXPRESSION'
6364
`PUBLIC NAME,EXPRESSION'
6365
`PUBLIC NAME EXPRESSION'
6366
     Supply a value (EXPRESSION) for external symbol NAME used in the
6367
     linker input files.
6368
 
6369
`SECT SECNAME, EXPRESSION'
6370
`SECT SECNAME=EXPRESSION'
6371
`SECT SECNAME EXPRESSION'
6372
     You can use any of these three forms of the `SECT' command to
6373
     specify the start address (EXPRESSION) for section SECNAME.  If
6374
     you have more than one `SECT' statement for the same SECNAME, only
6375
     the _first_ sets the start address.
6376
 
6377

6378
File: ld.info,  Node: GNU Free Documentation License,  Next: LD Index,  Prev: MRI,  Up: Top
6379
 
6380
Appendix B GNU Free Documentation License
6381
*****************************************
6382
 
6383
                        Version 1.1, March 2000
6384
 
6385
     Copyright (C) 2000, 2003 Free Software Foundation, Inc.
6386
     51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
6387
 
6388
     Everyone is permitted to copy and distribute verbatim copies
6389
     of this license document, but changing it is not allowed.
6390
 
6391
 
6392
  0. PREAMBLE
6393
 
6394
     The purpose of this License is to make a manual, textbook, or other
6395
     written document "free" in the sense of freedom: to assure everyone
6396
     the effective freedom to copy and redistribute it, with or without
6397
     modifying it, either commercially or noncommercially.  Secondarily,
6398
     this License preserves for the author and publisher a way to get
6399
     credit for their work, while not being considered responsible for
6400
     modifications made by others.
6401
 
6402
     This License is a kind of "copyleft", which means that derivative
6403
     works of the document must themselves be free in the same sense.
6404
     It complements the GNU General Public License, which is a copyleft
6405
     license designed for free software.
6406
 
6407
     We have designed this License in order to use it for manuals for
6408
     free software, because free software needs free documentation: a
6409
     free program should come with manuals providing the same freedoms
6410
     that the software does.  But this License is not limited to
6411
     software manuals; it can be used for any textual work, regardless
6412
     of subject matter or whether it is published as a printed book.
6413
     We recommend this License principally for works whose purpose is
6414
     instruction or reference.
6415
 
6416
 
6417
  1. APPLICABILITY AND DEFINITIONS
6418
 
6419
     This License applies to any manual or other work that contains a
6420
     notice placed by the copyright holder saying it can be distributed
6421
     under the terms of this License.  The "Document", below, refers to
6422
     any such manual or work.  Any member of the public is a licensee,
6423
     and is addressed as "you."
6424
 
6425
     A "Modified Version" of the Document means any work containing the
6426
     Document or a portion of it, either copied verbatim, or with
6427
     modifications and/or translated into another language.
6428
 
6429
     A "Secondary Section" is a named appendix or a front-matter
6430
     section of the Document that deals exclusively with the
6431
     relationship of the publishers or authors of the Document to the
6432
     Document's overall subject (or to related matters) and contains
6433
     nothing that could fall directly within that overall subject.
6434
     (For example, if the Document is in part a textbook of
6435
     mathematics, a Secondary Section may not explain any mathematics.)
6436
     The relationship could be a matter of historical connection with
6437
     the subject or with related matters, or of legal, commercial,
6438
     philosophical, ethical or political position regarding them.
6439
 
6440
     The "Invariant Sections" are certain Secondary Sections whose
6441
     titles are designated, as being those of Invariant Sections, in
6442
     the notice that says that the Document is released under this
6443
     License.
6444
 
6445
     The "Cover Texts" are certain short passages of text that are
6446
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
6447
     that says that the Document is released under this License.
6448
 
6449
     A "Transparent" copy of the Document means a machine-readable copy,
6450
     represented in a format whose specification is available to the
6451
     general public, whose contents can be viewed and edited directly
6452
     and straightforwardly with generic text editors or (for images
6453
     composed of pixels) generic paint programs or (for drawings) some
6454
     widely available drawing editor, and that is suitable for input to
6455
     text formatters or for automatic translation to a variety of
6456
     formats suitable for input to text formatters.  A copy made in an
6457
     otherwise Transparent file format whose markup has been designed
6458
     to thwart or discourage subsequent modification by readers is not
6459
     Transparent.  A copy that is not "Transparent" is called "Opaque."
6460
 
6461
     Examples of suitable formats for Transparent copies include plain
6462
     ASCII without markup, Texinfo input format, LaTeX input format,
6463
     SGML or XML using a publicly available DTD, and
6464
     standard-conforming simple HTML designed for human modification.
6465
     Opaque formats include PostScript, PDF, proprietary formats that
6466
     can be read and edited only by proprietary word processors, SGML
6467
     or XML for which the DTD and/or processing tools are not generally
6468
     available, and the machine-generated HTML produced by some word
6469
     processors for output purposes only.
6470
 
6471
     The "Title Page" means, for a printed book, the title page itself,
6472
     plus such following pages as are needed to hold, legibly, the
6473
     material this License requires to appear in the title page.  For
6474
     works in formats which do not have any title page as such, "Title
6475
     Page" means the text near the most prominent appearance of the
6476
     work's title, preceding the beginning of the body of the text.
6477
 
6478
  2. VERBATIM COPYING
6479
 
6480
     You may copy and distribute the Document in any medium, either
6481
     commercially or noncommercially, provided that this License, the
6482
     copyright notices, and the license notice saying this License
6483
     applies to the Document are reproduced in all copies, and that you
6484
     add no other conditions whatsoever to those of this License.  You
6485
     may not use technical measures to obstruct or control the reading
6486
     or further copying of the copies you make or distribute.  However,
6487
     you may accept compensation in exchange for copies.  If you
6488
     distribute a large enough number of copies you must also follow
6489
     the conditions in section 3.
6490
 
6491
     You may also lend copies, under the same conditions stated above,
6492
     and you may publicly display copies.
6493
 
6494
  3. COPYING IN QUANTITY
6495
 
6496
     If you publish printed copies of the Document numbering more than
6497
     100, and the Document's license notice requires Cover Texts, you
6498
     must enclose the copies in covers that carry, clearly and legibly,
6499
     all these Cover Texts: Front-Cover Texts on the front cover, and
6500
     Back-Cover Texts on the back cover.  Both covers must also clearly
6501
     and legibly identify you as the publisher of these copies.  The
6502
     front cover must present the full title with all words of the
6503
     title equally prominent and visible.  You may add other material
6504
     on the covers in addition.  Copying with changes limited to the
6505
     covers, as long as they preserve the title of the Document and
6506
     satisfy these conditions, can be treated as verbatim copying in
6507
     other respects.
6508
 
6509
     If the required texts for either cover are too voluminous to fit
6510
     legibly, you should put the first ones listed (as many as fit
6511
     reasonably) on the actual cover, and continue the rest onto
6512
     adjacent pages.
6513
 
6514
     If you publish or distribute Opaque copies of the Document
6515
     numbering more than 100, you must either include a
6516
     machine-readable Transparent copy along with each Opaque copy, or
6517
     state in or with each Opaque copy a publicly-accessible
6518
     computer-network location containing a complete Transparent copy
6519
     of the Document, free of added material, which the general
6520
     network-using public has access to download anonymously at no
6521
     charge using public-standard network protocols.  If you use the
6522
     latter option, you must take reasonably prudent steps, when you
6523
     begin distribution of Opaque copies in quantity, to ensure that
6524
     this Transparent copy will remain thus accessible at the stated
6525
     location until at least one year after the last time you
6526
     distribute an Opaque copy (directly or through your agents or
6527
     retailers) of that edition to the public.
6528
 
6529
     It is requested, but not required, that you contact the authors of
6530
     the Document well before redistributing any large number of
6531
     copies, to give them a chance to provide you with an updated
6532
     version of the Document.
6533
 
6534
  4. MODIFICATIONS
6535
 
6536
     You may copy and distribute a Modified Version of the Document
6537
     under the conditions of sections 2 and 3 above, provided that you
6538
     release the Modified Version under precisely this License, with
6539
     the Modified Version filling the role of the Document, thus
6540
     licensing distribution and modification of the Modified Version to
6541
     whoever possesses a copy of it.  In addition, you must do these
6542
     things in the Modified Version:
6543
 
6544
     A. Use in the Title Page (and on the covers, if any) a title
6545
     distinct    from that of the Document, and from those of previous
6546
     versions    (which should, if there were any, be listed in the
6547
     History section    of the Document).  You may use the same title
6548
     as a previous version    if the original publisher of that version
6549
     gives permission.
6550
     B. List on the Title Page, as authors, one or more persons or
6551
     entities    responsible for authorship of the modifications in the
6552
     Modified    Version, together with at least five of the principal
6553
     authors of the    Document (all of its principal authors, if it
6554
     has less than five).
6555
     C. State on the Title page the name of the publisher of the
6556
     Modified Version, as the publisher.
6557
     D. Preserve all the copyright notices of the Document.
6558
     E. Add an appropriate copyright notice for your modifications
6559
     adjacent to the other copyright notices.
6560
     F. Include, immediately after the copyright notices, a license
6561
     notice    giving the public permission to use the Modified Version
6562
     under the    terms of this License, in the form shown in the
6563
     Addendum below.
6564
     G. Preserve in that license notice the full lists of Invariant
6565
     Sections    and required Cover Texts given in the Document's
6566
     license notice.
6567
     H. Include an unaltered copy of this License.
6568
     I. Preserve the section entitled "History", and its title, and add
6569
     to    it an item stating at least the title, year, new authors, and
6570
       publisher of the Modified Version as given on the Title Page.
6571
     If    there is no section entitled "History" in the Document,
6572
     create one    stating the title, year, authors, and publisher of
6573
     the Document as    given on its Title Page, then add an item
6574
     describing the Modified    Version as stated in the previous
6575
     sentence.
6576
     J. Preserve the network location, if any, given in the Document for
6577
       public access to a Transparent copy of the Document, and
6578
     likewise    the network locations given in the Document for
6579
     previous versions    it was based on.  These may be placed in the
6580
     "History" section.     You may omit a network location for a work
6581
     that was published at    least four years before the Document
6582
     itself, or if the original    publisher of the version it refers
6583
     to gives permission.
6584
     K. In any section entitled "Acknowledgements" or "Dedications",
6585
     preserve the section's title, and preserve in the section all the
6586
      substance and tone of each of the contributor acknowledgements
6587
     and/or dedications given therein.
6588
     L. Preserve all the Invariant Sections of the Document,
6589
     unaltered in their text and in their titles.  Section numbers
6590
     or the equivalent are not considered part of the section titles.
6591
     M. Delete any section entitled "Endorsements."  Such a section
6592
     may not be included in the Modified Version.
6593
     N. Do not retitle any existing section as "Endorsements"    or to
6594
     conflict in title with any Invariant Section.
6595
 
6596
     If the Modified Version includes new front-matter sections or
6597
     appendices that qualify as Secondary Sections and contain no
6598
     material copied from the Document, you may at your option
6599
     designate some or all of these sections as invariant.  To do this,
6600
     add their titles to the list of Invariant Sections in the Modified
6601
     Version's license notice.  These titles must be distinct from any
6602
     other section titles.
6603
 
6604
     You may add a section entitled "Endorsements", provided it contains
6605
     nothing but endorsements of your Modified Version by various
6606
     parties-for example, statements of peer review or that the text has
6607
     been approved by an organization as the authoritative definition
6608
     of a standard.
6609
 
6610
     You may add a passage of up to five words as a Front-Cover Text,
6611
     and a passage of up to 25 words as a Back-Cover Text, to the end
6612
     of the list of Cover Texts in the Modified Version.  Only one
6613
     passage of Front-Cover Text and one of Back-Cover Text may be
6614
     added by (or through arrangements made by) any one entity.  If the
6615
     Document already includes a cover text for the same cover,
6616
     previously added by you or by arrangement made by the same entity
6617
     you are acting on behalf of, you may not add another; but you may
6618
     replace the old one, on explicit permission from the previous
6619
     publisher that added the old one.
6620
 
6621
     The author(s) and publisher(s) of the Document do not by this
6622
     License give permission to use their names for publicity for or to
6623
     assert or imply endorsement of any Modified Version.
6624
 
6625
  5. COMBINING DOCUMENTS
6626
 
6627
     You may combine the Document with other documents released under
6628
     this License, under the terms defined in section 4 above for
6629
     modified versions, provided that you include in the combination
6630
     all of the Invariant Sections of all of the original documents,
6631
     unmodified, and list them all as Invariant Sections of your
6632
     combined work in its license notice.
6633
 
6634
     The combined work need only contain one copy of this License, and
6635
     multiple identical Invariant Sections may be replaced with a single
6636
     copy.  If there are multiple Invariant Sections with the same name
6637
     but different contents, make the title of each such section unique
6638
     by adding at the end of it, in parentheses, the name of the
6639
     original author or publisher of that section if known, or else a
6640
     unique number.  Make the same adjustment to the section titles in
6641
     the list of Invariant Sections in the license notice of the
6642
     combined work.
6643
 
6644
     In the combination, you must combine any sections entitled
6645
     "History" in the various original documents, forming one section
6646
     entitled "History"; likewise combine any sections entitled
6647
     "Acknowledgements", and any sections entitled "Dedications."  You
6648
     must delete all sections entitled "Endorsements."
6649
 
6650
  6. COLLECTIONS OF DOCUMENTS
6651
 
6652
     You may make a collection consisting of the Document and other
6653
     documents released under this License, and replace the individual
6654
     copies of this License in the various documents with a single copy
6655
     that is included in the collection, provided that you follow the
6656
     rules of this License for verbatim copying of each of the
6657
     documents in all other respects.
6658
 
6659
     You may extract a single document from such a collection, and
6660
     distribute it individually under this License, provided you insert
6661
     a copy of this License into the extracted document, and follow
6662
     this License in all other respects regarding verbatim copying of
6663
     that document.
6664
 
6665
  7. AGGREGATION WITH INDEPENDENT WORKS
6666
 
6667
     A compilation of the Document or its derivatives with other
6668
     separate and independent documents or works, in or on a volume of
6669
     a storage or distribution medium, does not as a whole count as a
6670
     Modified Version of the Document, provided no compilation
6671
     copyright is claimed for the compilation.  Such a compilation is
6672
     called an "aggregate", and this License does not apply to the
6673
     other self-contained works thus compiled with the Document, on
6674
     account of their being thus compiled, if they are not themselves
6675
     derivative works of the Document.
6676
 
6677
     If the Cover Text requirement of section 3 is applicable to these
6678
     copies of the Document, then if the Document is less than one
6679
     quarter of the entire aggregate, the Document's Cover Texts may be
6680
     placed on covers that surround only the Document within the
6681
     aggregate.  Otherwise they must appear on covers around the whole
6682
     aggregate.
6683
 
6684
  8. TRANSLATION
6685
 
6686
     Translation is considered a kind of modification, so you may
6687
     distribute translations of the Document under the terms of section
6688
     4.  Replacing Invariant Sections with translations requires special
6689
     permission from their copyright holders, but you may include
6690
     translations of some or all Invariant Sections in addition to the
6691
     original versions of these Invariant Sections.  You may include a
6692
     translation of this License provided that you also include the
6693
     original English version of this License.  In case of a
6694
     disagreement between the translation and the original English
6695
     version of this License, the original English version will prevail.
6696
 
6697
  9. TERMINATION
6698
 
6699
     You may not copy, modify, sublicense, or distribute the Document
6700
     except as expressly provided for under this License.  Any other
6701
     attempt to copy, modify, sublicense or distribute the Document is
6702
     void, and will automatically terminate your rights under this
6703
     License.  However, parties who have received copies, or rights,
6704
     from you under this License will not have their licenses
6705
     terminated so long as such parties remain in full compliance.
6706
 
6707
 10. FUTURE REVISIONS OF THIS LICENSE
6708
 
6709
     The Free Software Foundation may publish new, revised versions of
6710
     the GNU Free Documentation License from time to time.  Such new
6711
     versions will be similar in spirit to the present version, but may
6712
     differ in detail to address new problems or concerns.  See
6713
     http://www.gnu.org/copyleft/.
6714
 
6715
     Each version of the License is given a distinguishing version
6716
     number.  If the Document specifies that a particular numbered
6717
     version of this License "or any later version" applies to it, you
6718
     have the option of following the terms and conditions either of
6719
     that specified version or of any later version that has been
6720
     published (not as a draft) by the Free Software Foundation.  If
6721
     the Document does not specify a version number of this License,
6722
     you may choose any version ever published (not as a draft) by the
6723
     Free Software Foundation.
6724
 
6725
 
6726
ADDENDUM: How to use this License for your documents
6727
====================================================
6728
 
6729
To use this License in a document you have written, include a copy of
6730
the License in the document and put the following copyright and license
6731
notices just after the title page:
6732
 
6733
     Copyright (C)  YEAR  YOUR NAME.
6734
     Permission is granted to copy, distribute and/or modify this document
6735
     under the terms of the GNU Free Documentation License, Version 1.1
6736
     or any later version published by the Free Software Foundation;
6737
     with the Invariant Sections being LIST THEIR TITLES, with the
6738
     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
6739
     A copy of the license is included in the section entitled "GNU
6740
     Free Documentation License."
6741
 
6742
   If you have no Invariant Sections, write "with no Invariant Sections"
6743
instead of saying which ones are invariant.  If you have no Front-Cover
6744
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
6745
LIST"; likewise for Back-Cover Texts.
6746
 
6747
   If your document contains nontrivial examples of program code, we
6748
recommend releasing these examples in parallel under your choice of
6749
free software license, such as the GNU General Public License, to
6750
permit their use in free software.
6751
 
6752

6753
File: ld.info,  Node: LD Index,  Prev: GNU Free Documentation License,  Up: Top
6754
 
6755
LD Index
6756
********
6757
 
6758
 
6759
* Menu:
6760
6761
* ":                                     Symbols.            (line    6)
6762
* -(:                                    Options.            (line  675)
6763
* --accept-unknown-input-arch:           Options.            (line  693)
6764
* --add-needed:                          Options.            (line  717)
6765
* --add-stdcall-alias:                   Options.            (line 1527)
6766
* --allow-multiple-definition:           Options.            (line  945)
6767
* --allow-shlib-undefined:               Options.            (line  951)
6768
* --architecture=ARCH:                   Options.            (line  113)
6769
* --as-needed:                           Options.            (line  703)
6770
* --auxiliary=NAME:                      Options.            (line  235)
6771
* --bank-window:                         Options.            (line 1926)
6772
* --base-file:                           Options.            (line 1532)
6773
* --be8:                                 ARM.                (line   28)
6774
* --bss-plt:                             PowerPC ELF32.      (line   16)
6775
* --build-id:                            Options.            (line 1489)
6776
* --build-id=STYLE:                      Options.            (line 1489)
6777
* --check-sections:                      Options.            (line  799)
6778
* --cref:                                Options.            (line  811)
6779
* --default-imported-symver:             Options.            (line  988)
6780
* --default-script=SCRIPT:               Options.            (line  520)
6781
* --default-symver:                      Options.            (line  984)
6782
* --defsym=SYMBOL=EXP:                   Options.            (line  839)
6783
* --demangle[=STYLE]:                    Options.            (line  852)
6784
* --disable-auto-image-base:             Options.            (line 1701)
6785
* --disable-auto-import:                 Options.            (line 1836)
6786
* --disable-long-section-names:          Options.            (line 1542)
6787
* --disable-new-dtags:                   Options.            (line 1452)
6788
* --disable-runtime-pseudo-reloc:        Options.            (line 1849)
6789
* --disable-stdcall-fixup:               Options.            (line 1564)
6790
* --discard-all:                         Options.            (line  566)
6791
* --discard-locals:                      Options.            (line  570)
6792
* --dll:                                 Options.            (line 1537)
6793
* --dll-search-prefix:                   Options.            (line 1707)
6794
* --dotsyms:                             PowerPC64 ELF64.    (line   33)
6795
* --dynamic-linker=FILE:                 Options.            (line  865)
6796
* --dynamic-list-cpp-new:                Options.            (line  791)
6797
* --dynamic-list-cpp-typeinfo:           Options.            (line  795)
6798
* --dynamic-list-data:                   Options.            (line  788)
6799
* --dynamic-list=DYNAMIC-LIST-FILE:      Options.            (line  775)
6800
* --dynamicbase:                         Options.            (line 1885)
6801
* --eh-frame-hdr:                        Options.            (line 1448)
6802
* --emit-relocs:                         Options.            (line  455)
6803
* --emit-stack-syms:                     SPU ELF.            (line   46)
6804
* --emit-stub-syms <1>:                  PowerPC ELF32.      (line   47)
6805
* --emit-stub-syms <2>:                  SPU ELF.            (line   15)
6806
* --emit-stub-syms:                      PowerPC64 ELF64.    (line   29)
6807
* --enable-auto-image-base:              Options.            (line 1693)
6808
* --enable-auto-import:                  Options.            (line 1716)
6809
* --enable-extra-pe-debug:               Options.            (line 1854)
6810
* --enable-long-section-names:           Options.            (line 1542)
6811
* --enable-new-dtags:                    Options.            (line 1452)
6812
* --enable-runtime-pseudo-reloc:         Options.            (line 1841)
6813
* --enable-stdcall-fixup:                Options.            (line 1564)
6814
* --entry=ENTRY:                         Options.            (line  167)
6815
* --error-unresolved-symbols:            Options.            (line 1401)
6816
* --exclude-libs:                        Options.            (line  177)
6817
* --exclude-modules-for-implib:          Options.            (line  188)
6818
* --exclude-symbols:                     Options.            (line 1606)
6819
* --export-all-symbols:                  Options.            (line 1582)
6820
* --export-dynamic:                      Options.            (line  201)
6821
* --extra-overlay-stubs:                 SPU ELF.            (line   19)
6822
* --fatal-warnings:                      Options.            (line  872)
6823
* --file-alignment:                      Options.            (line 1612)
6824
* --filter=NAME:                         Options.            (line  256)
6825
* --fix-cortex-a8:                       i960.               (line   39)
6826
* --fix-v4bx:                            ARM.                (line   49)
6827
* --fix-v4bx-interworking:               ARM.                (line   62)
6828
* --force-dynamic:                       Options.            (line  464)
6829
* --force-exe-suffix:                    Options.            (line  877)
6830
* --forceinteg:                          Options.            (line 1890)
6831
* --format=FORMAT:                       Options.            (line  124)
6832
* --format=VERSION:                      TI COFF.            (line    6)
6833
* --gc-sections:                         Options.            (line  887)
6834
* --got:                                 Options.            (line 1939)
6835
* --got=TYPE:                            M68K.               (line    6)
6836
* --gpsize=VALUE:                        Options.            (line  289)
6837
* --hash-size=NUMBER:                    Options.            (line 1461)
6838
* --hash-style=STYLE:                    Options.            (line 1469)
6839
* --heap:                                Options.            (line 1618)
6840
* --help:                                Options.            (line  918)
6841
* --image-base:                          Options.            (line 1625)
6842
* --just-symbols=FILE:                   Options.            (line  487)
6843
* --kill-at:                             Options.            (line 1634)
6844
* --large-address-aware:                 Options.            (line 1639)
6845
* --library-path=DIR:                    Options.            (line  348)
6846
* --library=NAMESPEC:                    Options.            (line  315)
6847
* --local-store=lo:hi:                   SPU ELF.            (line   24)
6848
* --major-image-version:                 Options.            (line 1648)
6849
* --major-os-version:                    Options.            (line 1653)
6850
* --major-subsystem-version:             Options.            (line 1657)
6851
* --minor-image-version:                 Options.            (line 1662)
6852
* --minor-os-version:                    Options.            (line 1667)
6853
* --minor-subsystem-version:             Options.            (line 1671)
6854
* --mri-script=MRI-CMDFILE:              Options.            (line  148)
6855
* --multi-subspace:                      HPPA ELF32.         (line    6)
6856
* --nmagic:                              Options.            (line  419)
6857
* --no-accept-unknown-input-arch:        Options.            (line  693)
6858
* --no-add-needed:                       Options.            (line  717)
6859
* --no-allow-shlib-undefined:            Options.            (line  951)
6860
* --no-as-needed:                        Options.            (line  703)
6861
* --no-bind:                             Options.            (line 1904)
6862
* --no-check-sections:                   Options.            (line  799)
6863
* --no-define-common:                    Options.            (line  823)
6864
* --no-demangle:                         Options.            (line  852)
6865
* --no-dotsyms:                          PowerPC64 ELF64.    (line   33)
6866
* --no-enum-size-warning:                ARM.                (line  111)
6867
* --no-export-dynamic:                   Options.            (line  201)
6868
* --no-fatal-warnings:                   Options.            (line  872)
6869
* --no-fix-cortex-a8:                    i960.               (line   39)
6870
* --no-gc-sections:                      Options.            (line  887)
6871
* --no-isolation:                        Options.            (line 1897)
6872
* --no-keep-memory:                      Options.            (line  930)
6873
* --no-multi-toc:                        PowerPC64 ELF64.    (line   74)
6874
* --no-omagic:                           Options.            (line  433)
6875
* --no-opd-optimize:                     PowerPC64 ELF64.    (line   48)
6876
* --no-overlays:                         SPU ELF.            (line    9)
6877
* --no-print-gc-sections:                Options.            (line  909)
6878
* --no-relax:                            Xtensa.             (line   56)
6879
* --no-seh:                              Options.            (line 1900)
6880
* --no-tls-optimize <1>:                 PowerPC ELF32.      (line   51)
6881
* --no-tls-optimize:                     PowerPC64 ELF64.    (line   43)
6882
* --no-toc-optimize:                     PowerPC64 ELF64.    (line   60)
6883
* --no-trampoline:                       Options.            (line 1920)
6884
* --no-undefined:                        Options.            (line  937)
6885
* --no-undefined-version:                Options.            (line  979)
6886
* --no-warn-mismatch:                    Options.            (line  992)
6887
* --no-warn-search-mismatch:             Options.            (line 1001)
6888
* --no-wchar-size-warning:               ARM.                (line  118)
6889
* --no-whole-archive:                    Options.            (line 1005)
6890
* --noinhibit-exec:                      Options.            (line 1009)
6891
* --non-overlapping-opd:                 PowerPC64 ELF64.    (line   54)
6892
* --nxcompat:                            Options.            (line 1893)
6893
* --oformat=OUTPUT-FORMAT:               Options.            (line 1021)
6894
* --omagic:                              Options.            (line  424)
6895
* --out-implib:                          Options.            (line 1684)
6896
* --output-def:                          Options.            (line 1676)
6897
* --output=OUTPUT:                       Options.            (line  439)
6898
* --pic-executable:                      Options.            (line 1034)
6899
* --pic-veneer:                          ARM.                (line  124)
6900
* --plugin:                              SPU ELF.            (line    6)
6901
* --print-gc-sections:                   Options.            (line  909)
6902
* --print-map:                           Options.            (line  382)
6903
* --reduce-memory-overheads:             Options.            (line 1475)
6904
* --relax:                               Options.            (line 1050)
6905
* --relax on i960:                       i960.               (line   31)
6906
* --relax on PowerPC:                    PowerPC ELF32.      (line    6)
6907
* --relax on Xtensa:                     Xtensa.             (line   27)
6908
* --relocatable:                         Options.            (line  468)
6909
* --retain-symbols-file=FILENAME:        Options.            (line 1071)
6910
* --script=SCRIPT:                       Options.            (line  511)
6911
* --sdata-got:                           PowerPC ELF32.      (line   33)
6912
* --section-alignment:                   Options.            (line 1859)
6913
* --section-start=SECTIONNAME=ORG:       Options.            (line 1227)
6914
* --secure-plt:                          PowerPC ELF32.      (line   26)
6915
* --sort-common:                         Options.            (line 1169)
6916
* --sort-section=alignment:              Options.            (line 1184)
6917
* --sort-section=name:                   Options.            (line 1180)
6918
* --split-by-file:                       Options.            (line 1188)
6919
* --split-by-reloc:                      Options.            (line 1193)
6920
* --stack:                               Options.            (line 1865)
6921
* --stack-analysis:                      SPU ELF.            (line   29)
6922
* --stats:                               Options.            (line 1206)
6923
* --strip-all:                           Options.            (line  498)
6924
* --strip-debug:                         Options.            (line  502)
6925
* --stub-group-size:                     PowerPC64 ELF64.    (line    6)
6926
* --stub-group-size=N <1>:               ARM.                (line  129)
6927
* --stub-group-size=N:                   HPPA ELF32.         (line   12)
6928
* --subsystem:                           Options.            (line 1872)
6929
* --support-old-code:                    ARM.                (line    6)
6930
* --sysroot=DIRECTORY:                   Options.            (line 1210)
6931
* --target-help:                         Options.            (line  922)
6932
* --target1-abs:                         ARM.                (line   32)
6933
* --target1-rel:                         ARM.                (line   32)
6934
* --target2=TYPE:                        ARM.                (line   37)
6935
* --thumb-entry=ENTRY:                   ARM.                (line   17)
6936
* --trace:                               Options.            (line  507)
6937
* --trace-symbol=SYMBOL:                 Options.            (line  576)
6938
* --traditional-format:                  Options.            (line 1215)
6939
* --tsaware:                             Options.            (line 1910)
6940
* --undefined=SYMBOL:                    Options.            (line  533)
6941
* --unique[=SECTION]:                    Options.            (line  551)
6942
* --unresolved-symbols:                  Options.            (line 1246)
6943
* --use-blx:                             ARM.                (line   74)
6944
* --use-nul-prefixed-import-tables:      ARM.                (line   23)
6945
* --verbose:                             Options.            (line 1275)
6946
* --version:                             Options.            (line  560)
6947
* --version-script=VERSION-SCRIPTFILE:   Options.            (line 1281)
6948
* --vfp11-denorm-fix:                    ARM.                (line   83)
6949
* --warn-alternate-em:                   Options.            (line 1393)
6950
* --warn-common:                         Options.            (line 1292)
6951
* --warn-constructors:                   Options.            (line 1360)
6952
* --warn-multiple-gp:                    Options.            (line 1365)
6953
* --warn-once:                           Options.            (line 1379)
6954
* --warn-section-align:                  Options.            (line 1383)
6955
* --warn-shared-textrel:                 Options.            (line 1390)
6956
* --warn-unresolved-symbols:             Options.            (line 1396)
6957
* --wdmdriver:                           Options.            (line 1907)
6958
* --whole-archive:                       Options.            (line 1405)
6959
* --wrap=SYMBOL:                         Options.            (line 1419)
6960
* -A ARCH:                               Options.            (line  112)
6961
* -a KEYWORD:                            Options.            (line  105)
6962
* -assert KEYWORD:                       Options.            (line  727)
6963
* -b FORMAT:                             Options.            (line  124)
6964
* -Bdynamic:                             Options.            (line  730)
6965
* -Bgroup:                               Options.            (line  740)
6966
* -Bshareable:                           Options.            (line 1162)
6967
* -Bstatic:                              Options.            (line  747)
6968
* -Bsymbolic:                            Options.            (line  762)
6969
* -Bsymbolic-functions:                  Options.            (line  769)
6970
* -c MRI-CMDFILE:                        Options.            (line  148)
6971
* -call_shared:                          Options.            (line  730)
6972
* -d:                                    Options.            (line  158)
6973
* -dc:                                   Options.            (line  158)
6974
* -dn:                                   Options.            (line  747)
6975
* -dp:                                   Options.            (line  158)
6976
* -dT SCRIPT:                            Options.            (line  520)
6977
* -dy:                                   Options.            (line  730)
6978
* -E:                                    Options.            (line  201)
6979
* -e ENTRY:                              Options.            (line  167)
6980
* -EB:                                   Options.            (line  228)
6981
* -EL:                                   Options.            (line  231)
6982
* -F NAME:                               Options.            (line  256)
6983
* -f NAME:                               Options.            (line  235)
6984
* -fini=NAME:                            Options.            (line  280)
6985
* -g:                                    Options.            (line  286)
6986
* -G VALUE:                              Options.            (line  289)
6987
* -h NAME:                               Options.            (line  297)
6988
* -i:                                    Options.            (line  306)
6989
* -IFILE:                                Options.            (line  865)
6990
* -init=NAME:                            Options.            (line  309)
6991
* -L DIR:                                Options.            (line  348)
6992
* -l NAMESPEC:                           Options.            (line  315)
6993
* -M:                                    Options.            (line  382)
6994
* -m EMULATION:                          Options.            (line  372)
6995
* -Map=MAPFILE:                          Options.            (line  926)
6996
* -N:                                    Options.            (line  424)
6997
* -n:                                    Options.            (line  419)
6998
* -non_shared:                           Options.            (line  747)
6999
* -nostdlib:                             Options.            (line 1015)
7000
* -O LEVEL:                              Options.            (line  445)
7001
* -o OUTPUT:                             Options.            (line  439)
7002
* -pie:                                  Options.            (line 1034)
7003
* -q:                                    Options.            (line  455)
7004
* -qmagic:                               Options.            (line 1044)
7005
* -Qy:                                   Options.            (line 1047)
7006
* -r:                                    Options.            (line  468)
7007
* -R FILE:                               Options.            (line  487)
7008
* -rpath-link=DIR:                       Options.            (line 1107)
7009
* -rpath=DIR:                            Options.            (line 1085)
7010
* -s:                                    Options.            (line  498)
7011
* -S:                                    Options.            (line  502)
7012
* -shared:                               Options.            (line 1162)
7013
* -soname=NAME:                          Options.            (line  297)
7014
* -static:                               Options.            (line  747)
7015
* -t:                                    Options.            (line  507)
7016
* -T SCRIPT:                             Options.            (line  511)
7017
* -Tbss=ORG:                             Options.            (line 1236)
7018
* -Tdata=ORG:                            Options.            (line 1236)
7019
* -Ttext-segment=ORG:                    Options.            (line 1242)
7020
* -Ttext=ORG:                            Options.            (line 1236)
7021
* -u SYMBOL:                             Options.            (line  533)
7022
* -Ur:                                   Options.            (line  541)
7023
* -V:                                    Options.            (line  560)
7024
* -v:                                    Options.            (line  560)
7025
* -X:                                    Options.            (line  570)
7026
* -x:                                    Options.            (line  566)
7027
* -Y PATH:                               Options.            (line  585)
7028
* -y SYMBOL:                             Options.            (line  576)
7029
* -z defs:                               Options.            (line  937)
7030
* -z KEYWORD:                            Options.            (line  589)
7031
* -z muldefs:                            Options.            (line  945)
7032
* .:                                     Location Counter.   (line    6)
7033
* /DISCARD/:                             Output Section Discarding.
7034
                                                             (line   21)
7035
* :PHDR:                                 Output Section Phdr.
7036
                                                             (line    6)
7037
* =FILLEXP:                              Output Section Fill.
7038
                                                             (line    6)
7039
* >REGION:                               Output Section Region.
7040
                                                             (line    6)
7041
* [COMMON]:                              Input Section Common.
7042
                                                             (line   29)
7043
* ABSOLUTE (MRI):                        MRI.                (line   33)
7044
* absolute and relocatable symbols:      Expression Section. (line    6)
7045
* absolute expressions:                  Expression Section. (line    6)
7046
* ABSOLUTE(EXP):                         Builtin Functions.  (line   10)
7047
* ADDR(SECTION):                         Builtin Functions.  (line   17)
7048
* address, section:                      Output Section Address.
7049
                                                             (line    6)
7050
* ALIAS (MRI):                           MRI.                (line   44)
7051
* ALIGN (MRI):                           MRI.                (line   50)
7052
* align expression:                      Builtin Functions.  (line   36)
7053
* align location counter:                Builtin Functions.  (line   36)
7054
* ALIGN(ALIGN):                          Builtin Functions.  (line   36)
7055
* ALIGN(EXP,ALIGN):                      Builtin Functions.  (line   36)
7056
* ALIGN(SECTION_ALIGN):                  Forced Output Alignment.
7057
                                                             (line    6)
7058
* aligned common symbols:                WIN32.              (line  418)
7059
* ALIGNOF(SECTION):                      Builtin Functions.  (line   62)
7060
* allocating memory:                     MEMORY.             (line    6)
7061
* architecture:                          Miscellaneous Commands.
7062
                                                             (line   72)
7063
* architectures:                         Options.            (line  112)
7064
* archive files, from cmd line:          Options.            (line  315)
7065
* archive search path in linker script:  File Commands.      (line   74)
7066
* arithmetic:                            Expressions.        (line    6)
7067
* arithmetic operators:                  Operators.          (line    6)
7068
* ARM interworking support:              ARM.                (line    6)
7069
* AS_NEEDED(FILES):                      File Commands.      (line   54)
7070
* ASSERT:                                Miscellaneous Commands.
7071
                                                             (line    9)
7072
* assertion in linker script:            Miscellaneous Commands.
7073
                                                             (line    9)
7074
* assignment in scripts:                 Assignments.        (line    6)
7075
* AT(LMA):                               Output Section LMA. (line    6)
7076
* AT>LMA_REGION:                         Output Section LMA. (line    6)
7077
* automatic data imports:                WIN32.              (line  185)
7078
* back end:                              BFD.                (line    6)
7079
* BASE (MRI):                            MRI.                (line   54)
7080
* BE8:                                   ARM.                (line   28)
7081
* BFD canonical format:                  Canonical format.   (line   11)
7082
* BFD requirements:                      BFD.                (line   16)
7083
* big-endian objects:                    Options.            (line  228)
7084
* binary input format:                   Options.            (line  124)
7085
* BLOCK(EXP):                            Builtin Functions.  (line   75)
7086
* bug criteria:                          Bug Criteria.       (line    6)
7087
* bug reports:                           Bug Reporting.      (line    6)
7088
* bugs in ld:                            Reporting Bugs.     (line    6)
7089
* BYTE(EXPRESSION):                      Output Section Data.
7090
                                                             (line    6)
7091
* C++ constructors, arranging in link:   Output Section Keywords.
7092
                                                             (line   19)
7093
* CHIP (MRI):                            MRI.                (line   58)
7094
* COLLECT_NO_DEMANGLE:                   Environment.        (line   29)
7095
* combining symbols, warnings on:        Options.            (line 1292)
7096
* command files:                         Scripts.            (line    6)
7097
* command line:                          Options.            (line    6)
7098
* common allocation:                     Options.            (line  158)
7099
* common allocation in linker script:    Miscellaneous Commands.
7100
                                                             (line   20)
7101
* common symbol placement:               Input Section Common.
7102
                                                             (line    6)
7103
* COMMONPAGESIZE:                        Symbolic Constants. (line   13)
7104
* compatibility, MRI:                    Options.            (line  148)
7105
* CONSTANT:                              Symbolic Constants. (line    6)
7106
* constants in linker scripts:           Constants.          (line    6)
7107
* constraints on output sections:        Output Section Constraint.
7108
                                                             (line    6)
7109
* CONSTRUCTORS:                          Output Section Keywords.
7110
                                                             (line   19)
7111
* constructors:                          Options.            (line  541)
7112
* constructors, arranging in link:       Output Section Keywords.
7113
                                                             (line   19)
7114
* Cortex-A8 erratum workaround:          i960.               (line   39)
7115
* crash of linker:                       Bug Criteria.       (line    9)
7116
* CREATE_OBJECT_SYMBOLS:                 Output Section Keywords.
7117
                                                             (line    9)
7118
* creating a DEF file:                   WIN32.              (line  152)
7119
* cross reference table:                 Options.            (line  811)
7120
* cross references:                      Miscellaneous Commands.
7121
                                                             (line   56)
7122
* current output location:               Location Counter.   (line    6)
7123
* data:                                  Output Section Data.
7124
                                                             (line    6)
7125
* DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE): Builtin Functions.
7126
                                                             (line   80)
7127
* DATA_SEGMENT_END(EXP):                 Builtin Functions.  (line  101)
7128
* DATA_SEGMENT_RELRO_END(OFFSET, EXP):   Builtin Functions.  (line  107)
7129
* dbx:                                   Options.            (line 1220)
7130
* DEF files, creating:                   Options.            (line 1676)
7131
* default emulation:                     Environment.        (line   21)
7132
* default input format:                  Environment.        (line    9)
7133
* DEFINED(SYMBOL):                       Builtin Functions.  (line  118)
7134
* deleting local symbols:                Options.            (line  566)
7135
* demangling, default:                   Environment.        (line   29)
7136
* demangling, from command line:         Options.            (line  852)
7137
* direct linking to a dll:               WIN32.              (line  233)
7138
* discarding sections:                   Output Section Discarding.
7139
                                                             (line    6)
7140
* discontinuous memory:                  MEMORY.             (line    6)
7141
* DLLs, creating:                        Options.            (line 1676)
7142
* DLLs, linking to:                      Options.            (line 1707)
7143
* dot:                                   Location Counter.   (line    6)
7144
* dot inside sections:                   Location Counter.   (line   36)
7145
* dot outside sections:                  Location Counter.   (line   66)
7146
* dynamic linker, from command line:     Options.            (line  865)
7147
* dynamic symbol table:                  Options.            (line  201)
7148
* ELF program headers:                   PHDRS.              (line    6)
7149
* emulation:                             Options.            (line  372)
7150
* emulation, default:                    Environment.        (line   21)
7151
* END (MRI):                             MRI.                (line   62)
7152
* endianness:                            Options.            (line  228)
7153
* entry point:                           Entry Point.        (line    6)
7154
* entry point, from command line:        Options.            (line  167)
7155
* entry point, thumb:                    ARM.                (line   17)
7156
* ENTRY(SYMBOL):                         Entry Point.        (line    6)
7157
* error on valid input:                  Bug Criteria.       (line   12)
7158
* example of linker script:              Simple Example.     (line    6)
7159
* exporting DLL symbols:                 WIN32.              (line   19)
7160
* expression evaluation order:           Evaluation.         (line    6)
7161
* expression sections:                   Expression Section. (line    6)
7162
* expression, absolute:                  Builtin Functions.  (line   10)
7163
* expressions:                           Expressions.        (line    6)
7164
* EXTERN:                                Miscellaneous Commands.
7165
                                                             (line   13)
7166
* fatal signal:                          Bug Criteria.       (line    9)
7167
* file name wildcard patterns:           Input Section Wildcards.
7168
                                                             (line    6)
7169
* FILEHDR:                               PHDRS.              (line   61)
7170
* filename symbols:                      Output Section Keywords.
7171
                                                             (line    9)
7172
* fill pattern, entire section:          Output Section Fill.
7173
                                                             (line    6)
7174
* FILL(EXPRESSION):                      Output Section Data.
7175
                                                             (line   39)
7176
* finalization function:                 Options.            (line  280)
7177
* first input file:                      File Commands.      (line   82)
7178
* first instruction:                     Entry Point.        (line    6)
7179
* FIX_V4BX:                              ARM.                (line   49)
7180
* FIX_V4BX_INTERWORKING:                 ARM.                (line   62)
7181
* FORCE_COMMON_ALLOCATION:               Miscellaneous Commands.
7182
                                                             (line   20)
7183
* forcing input section alignment:       Forced Input Alignment.
7184
                                                             (line    6)
7185
* forcing output section alignment:      Forced Output Alignment.
7186
                                                             (line    6)
7187
* forcing the creation of dynamic sections: Options.         (line  464)
7188
* FORMAT (MRI):                          MRI.                (line   66)
7189
* functions in expressions:              Builtin Functions.  (line    6)
7190
* garbage collection <1>:                Options.            (line  909)
7191
* garbage collection <2>:                Input Section Keep. (line    6)
7192
* garbage collection:                    Options.            (line  887)
7193
* generating optimized output:           Options.            (line  445)
7194
* GNU linker:                            Overview.           (line    6)
7195
* GNUTARGET:                             Environment.        (line    9)
7196
* GROUP(FILES):                          File Commands.      (line   47)
7197
* grouping input files:                  File Commands.      (line   47)
7198
* groups of archives:                    Options.            (line  675)
7199
* H8/300 support:                        H8/300.             (line    6)
7200
* header size:                           Builtin Functions.  (line  183)
7201
* heap size:                             Options.            (line 1618)
7202
* help:                                  Options.            (line  918)
7203
* holes:                                 Location Counter.   (line   12)
7204
* holes, filling:                        Output Section Data.
7205
                                                             (line   39)
7206
* HPPA multiple sub-space stubs:         HPPA ELF32.         (line    6)
7207
* HPPA stub grouping:                    HPPA ELF32.         (line   12)
7208
* i960 support:                          i960.               (line    6)
7209
* image base:                            Options.            (line 1625)
7210
* implicit linker scripts:               Implicit Linker Scripts.
7211
                                                             (line    6)
7212
* import libraries:                      WIN32.              (line   10)
7213
* INCLUDE FILENAME:                      File Commands.      (line    9)
7214
* including a linker script:             File Commands.      (line    9)
7215
* including an entire archive:           Options.            (line 1405)
7216
* incremental link:                      Options.            (line  306)
7217
* INHIBIT_COMMON_ALLOCATION:             Miscellaneous Commands.
7218
                                                             (line   25)
7219
* initialization function:               Options.            (line  309)
7220
* initialized data in ROM:               Output Section LMA. (line   26)
7221
* input file format in linker script:    Format Commands.    (line   35)
7222
* input filename symbols:                Output Section Keywords.
7223
                                                             (line    9)
7224
* input files in linker scripts:         File Commands.      (line   19)
7225
* input files, displaying:               Options.            (line  507)
7226
* input format:                          Options.            (line  124)
7227
* input object files in linker scripts:  File Commands.      (line   19)
7228
* input section alignment:               Forced Input Alignment.
7229
                                                             (line    6)
7230
* input section basics:                  Input Section Basics.
7231
                                                             (line    6)
7232
* input section wildcards:               Input Section Wildcards.
7233
                                                             (line    6)
7234
* input sections:                        Input Section.      (line    6)
7235
* INPUT(FILES):                          File Commands.      (line   19)
7236
* INSERT:                                Miscellaneous Commands.
7237
                                                             (line   30)
7238
* insert user script into default script: Miscellaneous Commands.
7239
                                                             (line   30)
7240
* integer notation:                      Constants.          (line    6)
7241
* integer suffixes:                      Constants.          (line   15)
7242
* internal object-file format:           Canonical format.   (line   11)
7243
* invalid input:                         Bug Criteria.       (line   14)
7244
* K and M integer suffixes:              Constants.          (line   15)
7245
* KEEP:                                  Input Section Keep. (line    6)
7246
* l =:                                   MEMORY.             (line   74)
7247
* lazy evaluation:                       Evaluation.         (line    6)
7248
* ld bugs, reporting:                    Bug Reporting.      (line    6)
7249
* LDEMULATION:                           Environment.        (line   21)
7250
* len =:                                 MEMORY.             (line   74)
7251
* LENGTH =:                              MEMORY.             (line   74)
7252
* LENGTH(MEMORY):                        Builtin Functions.  (line  135)
7253
* library search path in linker script:  File Commands.      (line   74)
7254
* link map:                              Options.            (line  382)
7255
* link-time runtime library search path: Options.            (line 1107)
7256
* linker crash:                          Bug Criteria.       (line    9)
7257
* linker script concepts:                Basic Script Concepts.
7258
                                                             (line    6)
7259
* linker script example:                 Simple Example.     (line    6)
7260
* linker script file commands:           File Commands.      (line    6)
7261
* linker script format:                  Script Format.      (line    6)
7262
* linker script input object files:      File Commands.      (line   19)
7263
* linker script simple commands:         Simple Commands.    (line    6)
7264
* linker scripts:                        Scripts.            (line    6)
7265
* LIST (MRI):                            MRI.                (line   77)
7266
* little-endian objects:                 Options.            (line  231)
7267
* LOAD (MRI):                            MRI.                (line   84)
7268
* load address:                          Output Section LMA. (line    6)
7269
* LOADADDR(SECTION):                     Builtin Functions.  (line  138)
7270
* loading, preventing:                   Output Section Type.
7271
                                                             (line   22)
7272
* local symbols, deleting:               Options.            (line  570)
7273
* location counter:                      Location Counter.   (line    6)
7274
* LONG(EXPRESSION):                      Output Section Data.
7275
                                                             (line    6)
7276
* M and K integer suffixes:              Constants.          (line   15)
7277
* M68HC11 and 68HC12 support:            M68HC11/68HC12.     (line    6)
7278
* machine architecture:                  Miscellaneous Commands.
7279
                                                             (line   72)
7280
* machine dependencies:                  Machine Dependent.  (line    6)
7281
* mapping input sections to output sections: Input Section.  (line    6)
7282
* MAX:                                   Builtin Functions.  (line  143)
7283
* MAXPAGESIZE:                           Symbolic Constants. (line   10)
7284
* MEMORY:                                MEMORY.             (line    6)
7285
* memory region attributes:              MEMORY.             (line   34)
7286
* memory regions:                        MEMORY.             (line    6)
7287
* memory regions and sections:           Output Section Region.
7288
                                                             (line    6)
7289
* memory usage:                          Options.            (line  930)
7290
* MIN:                                   Builtin Functions.  (line  146)
7291
* Motorola 68K GOT generation:           M68K.               (line    6)
7292
* MRI compatibility:                     MRI.                (line    6)
7293
* MSP430 extra sections:                 MSP430.             (line   11)
7294
* NAME (MRI):                            MRI.                (line   90)
7295
* name, section:                         Output Section Name.
7296
                                                             (line    6)
7297
* names:                                 Symbols.            (line    6)
7298
* naming the output file:                Options.            (line  439)
7299
* NEXT(EXP):                             Builtin Functions.  (line  150)
7300
* NMAGIC:                                Options.            (line  419)
7301
* NO_ENUM_SIZE_WARNING:                  ARM.                (line  111)
7302
* NO_WCHAR_SIZE_WARNING:                 ARM.                (line  118)
7303
* NOCROSSREFS(SECTIONS):                 Miscellaneous Commands.
7304
                                                             (line   56)
7305
* NOLOAD:                                Output Section Type.
7306
                                                             (line   22)
7307
* not enough room for program headers:   Builtin Functions.  (line  188)
7308
* o =:                                   MEMORY.             (line   69)
7309
* objdump -i:                            BFD.                (line    6)
7310
* object file management:                BFD.                (line    6)
7311
* object files:                          Options.            (line   29)
7312
* object formats available:              BFD.                (line    6)
7313
* object size:                           Options.            (line  289)
7314
* OMAGIC:                                Options.            (line  424)
7315
* ONLY_IF_RO:                            Output Section Constraint.
7316
                                                             (line    6)
7317
* ONLY_IF_RW:                            Output Section Constraint.
7318
                                                             (line    6)
7319
* opening object files:                  BFD outline.        (line    6)
7320
* operators for arithmetic:              Operators.          (line    6)
7321
* options:                               Options.            (line    6)
7322
* ORDER (MRI):                           MRI.                (line   95)
7323
* org =:                                 MEMORY.             (line   69)
7324
* ORIGIN =:                              MEMORY.             (line   69)
7325
* ORIGIN(MEMORY):                        Builtin Functions.  (line  156)
7326
* orphan:                                Orphan Sections.    (line    6)
7327
* output file after errors:              Options.            (line 1009)
7328
* output file format in linker script:   Format Commands.    (line   10)
7329
* output file name in linker script:     File Commands.      (line   64)
7330
* output section alignment:              Forced Output Alignment.
7331
                                                             (line    6)
7332
* output section attributes:             Output Section Attributes.
7333
                                                             (line    6)
7334
* output section data:                   Output Section Data.
7335
                                                             (line    6)
7336
* OUTPUT(FILENAME):                      File Commands.      (line   64)
7337
* OUTPUT_ARCH(BFDARCH):                  Miscellaneous Commands.
7338
                                                             (line   72)
7339
* OUTPUT_FORMAT(BFDNAME):                Format Commands.    (line   10)
7340
* OVERLAY:                               Overlay Description.
7341
                                                             (line    6)
7342
* overlays:                              Overlay Description.
7343
                                                             (line    6)
7344
* partial link:                          Options.            (line  468)
7345
* PE import table prefixing:             ARM.                (line   23)
7346
* PHDRS:                                 PHDRS.              (line   61)
7347
* PIC_VENEER:                            ARM.                (line  124)
7348
* position independent executables:      Options.            (line 1036)
7349
* PowerPC ELF32 options:                 PowerPC ELF32.      (line   16)
7350
* PowerPC GOT:                           PowerPC ELF32.      (line   33)
7351
* PowerPC long branches:                 PowerPC ELF32.      (line    6)
7352
* PowerPC PLT:                           PowerPC ELF32.      (line   16)
7353
* PowerPC stub symbols:                  PowerPC ELF32.      (line   47)
7354
* PowerPC TLS optimization:              PowerPC ELF32.      (line   51)
7355
* PowerPC64 dot symbols:                 PowerPC64 ELF64.    (line   33)
7356
* PowerPC64 ELF64 options:               PowerPC64 ELF64.    (line    6)
7357
* PowerPC64 multi-TOC:                   PowerPC64 ELF64.    (line   74)
7358
* PowerPC64 OPD optimization:            PowerPC64 ELF64.    (line   48)
7359
* PowerPC64 OPD spacing:                 PowerPC64 ELF64.    (line   54)
7360
* PowerPC64 stub grouping:               PowerPC64 ELF64.    (line    6)
7361
* PowerPC64 stub symbols:                PowerPC64 ELF64.    (line   29)
7362
* PowerPC64 TLS optimization:            PowerPC64 ELF64.    (line   43)
7363
* PowerPC64 TOC optimization:            PowerPC64 ELF64.    (line   60)
7364
* precedence in expressions:             Operators.          (line    6)
7365
* prevent unnecessary loading:           Output Section Type.
7366
                                                             (line   22)
7367
* program headers:                       PHDRS.              (line    6)
7368
* program headers and sections:          Output Section Phdr.
7369
                                                             (line    6)
7370
* program headers, not enough room:      Builtin Functions.  (line  188)
7371
* program segments:                      PHDRS.              (line    6)
7372
* PROVIDE:                               PROVIDE.            (line    6)
7373
* PROVIDE_HIDDEN:                        PROVIDE_HIDDEN.     (line    6)
7374
* PUBLIC (MRI):                          MRI.                (line  103)
7375
* QUAD(EXPRESSION):                      Output Section Data.
7376
                                                             (line    6)
7377
* quoted symbol names:                   Symbols.            (line    6)
7378
* read-only text:                        Options.            (line  419)
7379
* read/write from cmd line:              Options.            (line  424)
7380
* region alias:                          REGION_ALIAS.       (line    6)
7381
* region names:                          REGION_ALIAS.       (line    6)
7382
* REGION_ALIAS(ALIAS, REGION):           REGION_ALIAS.       (line    6)
7383
* regions of memory:                     MEMORY.             (line    6)
7384
* relative expressions:                  Expression Section. (line    6)
7385
* relaxing addressing modes:             Options.            (line 1050)
7386
* relaxing on H8/300:                    H8/300.             (line    9)
7387
* relaxing on i960:                      i960.               (line   31)
7388
* relaxing on M68HC11:                   M68HC11/68HC12.     (line   12)
7389
* relaxing on Xtensa:                    Xtensa.             (line   27)
7390
* relocatable and absolute symbols:      Expression Section. (line    6)
7391
* relocatable output:                    Options.            (line  468)
7392
* removing sections:                     Output Section Discarding.
7393
                                                             (line    6)
7394
* reporting bugs in ld:                  Reporting Bugs.     (line    6)
7395
* requirements for BFD:                  BFD.                (line   16)
7396
* retain relocations in final executable: Options.           (line  455)
7397
* retaining specified symbols:           Options.            (line 1071)
7398
* ROM initialized data:                  Output Section LMA. (line   26)
7399
* round up expression:                   Builtin Functions.  (line   36)
7400
* round up location counter:             Builtin Functions.  (line   36)
7401
* runtime library name:                  Options.            (line  297)
7402
* runtime library search path:           Options.            (line 1085)
7403
* runtime pseudo-relocation:             WIN32.              (line  211)
7404
* scaled integers:                       Constants.          (line   15)
7405
* scommon section:                       Input Section Common.
7406
                                                             (line   20)
7407
* script files:                          Options.            (line  520)
7408
* scripts:                               Scripts.            (line    6)
7409
* search directory, from cmd line:       Options.            (line  348)
7410
* search path in linker script:          File Commands.      (line   74)
7411
* SEARCH_DIR(PATH):                      File Commands.      (line   74)
7412
* SECT (MRI):                            MRI.                (line  109)
7413
* section address:                       Output Section Address.
7414
                                                             (line    6)
7415
* section address in expression:         Builtin Functions.  (line   17)
7416
* section alignment:                     Builtin Functions.  (line   62)
7417
* section alignment, warnings on:        Options.            (line 1383)
7418
* section data:                          Output Section Data.
7419
                                                             (line    6)
7420
* section fill pattern:                  Output Section Fill.
7421
                                                             (line    6)
7422
* section load address:                  Output Section LMA. (line    6)
7423
* section load address in expression:    Builtin Functions.  (line  138)
7424
* section name:                          Output Section Name.
7425
                                                             (line    6)
7426
* section name wildcard patterns:        Input Section Wildcards.
7427
                                                             (line    6)
7428
* section size:                          Builtin Functions.  (line  167)
7429
* section, assigning to memory region:   Output Section Region.
7430
                                                             (line    6)
7431
* section, assigning to program header:  Output Section Phdr.
7432
                                                             (line    6)
7433
* SECTIONS:                              SECTIONS.           (line    6)
7434
* sections, discarding:                  Output Section Discarding.
7435
                                                             (line    6)
7436
* segment origins, cmd line:             Options.            (line 1236)
7437
* SEGMENT_START(SEGMENT, DEFAULT):       Builtin Functions.  (line  159)
7438
* segments, ELF:                         PHDRS.              (line    6)
7439
* shared libraries:                      Options.            (line 1164)
7440
* SHORT(EXPRESSION):                     Output Section Data.
7441
                                                             (line    6)
7442
* SIZEOF(SECTION):                       Builtin Functions.  (line  167)
7443
* SIZEOF_HEADERS:                        Builtin Functions.  (line  183)
7444
* small common symbols:                  Input Section Common.
7445
                                                             (line   20)
7446
* SORT:                                  Input Section Wildcards.
7447
                                                             (line   58)
7448
* SORT_BY_ALIGNMENT:                     Input Section Wildcards.
7449
                                                             (line   54)
7450
* SORT_BY_NAME:                          Input Section Wildcards.
7451
                                                             (line   46)
7452
* SPU:                                   SPU ELF.            (line   29)
7453
* SPU ELF options:                       SPU ELF.            (line    6)
7454
* SPU extra overlay stubs:               SPU ELF.            (line   19)
7455
* SPU local store size:                  SPU ELF.            (line   24)
7456
* SPU overlay stub symbols:              SPU ELF.            (line   15)
7457
* SPU overlays:                          SPU ELF.            (line    9)
7458
* SPU plugins:                           SPU ELF.            (line    6)
7459
* SQUAD(EXPRESSION):                     Output Section Data.
7460
                                                             (line    6)
7461
* stack size:                            Options.            (line 1865)
7462
* standard Unix system:                  Options.            (line    7)
7463
* start of execution:                    Entry Point.        (line    6)
7464
* STARTUP(FILENAME):                     File Commands.      (line   82)
7465
* strip all symbols:                     Options.            (line  498)
7466
* strip debugger symbols:                Options.            (line  502)
7467
* stripping all but some symbols:        Options.            (line 1071)
7468
* STUB_GROUP_SIZE:                       ARM.                (line  129)
7469
* SUBALIGN(SUBSECTION_ALIGN):            Forced Input Alignment.
7470
                                                             (line    6)
7471
* suffixes for integers:                 Constants.          (line   15)
7472
* symbol defaults:                       Builtin Functions.  (line  118)
7473
* symbol definition, scripts:            Assignments.        (line    6)
7474
* symbol names:                          Symbols.            (line    6)
7475
* symbol tracing:                        Options.            (line  576)
7476
* symbol versions:                       VERSION.            (line    6)
7477
* symbol-only input:                     Options.            (line  487)
7478
* symbolic constants:                    Symbolic Constants. (line    6)
7479
* symbols, from command line:            Options.            (line  839)
7480
* symbols, relocatable and absolute:     Expression Section. (line    6)
7481
* symbols, retaining selectively:        Options.            (line 1071)
7482
* synthesizing linker:                   Options.            (line 1050)
7483
* synthesizing on H8/300:                H8/300.             (line   14)
7484
* TARGET(BFDNAME):                       Format Commands.    (line   35)
7485
* TARGET1:                               ARM.                (line   32)
7486
* TARGET2:                               ARM.                (line   37)
7487
* text segment origin, cmd line:         Options.            (line 1243)
7488
* thumb entry point:                     ARM.                (line   17)
7489
* TI COFF versions:                      TI COFF.            (line    6)
7490
* traditional format:                    Options.            (line 1215)
7491
* trampoline generation on M68HC11:      M68HC11/68HC12.     (line   31)
7492
* trampoline generation on M68HC12:      M68HC11/68HC12.     (line   31)
7493
* unallocated address, next:             Builtin Functions.  (line  150)
7494
* undefined symbol:                      Options.            (line  533)
7495
* undefined symbol in linker script:     Miscellaneous Commands.
7496
                                                             (line   13)
7497
* undefined symbols, warnings on:        Options.            (line 1379)
7498
* uninitialized data placement:          Input Section Common.
7499
                                                             (line    6)
7500
* unspecified memory:                    Output Section Data.
7501
                                                             (line   39)
7502
* usage:                                 Options.            (line  918)
7503
* USE_BLX:                               ARM.                (line   74)
7504
* using a DEF file:                      WIN32.              (line   57)
7505
* using auto-export functionality:       WIN32.              (line   22)
7506
* Using decorations:                     WIN32.              (line  156)
7507
* variables, defining:                   Assignments.        (line    6)
7508
* verbose:                               Options.            (line 1275)
7509
* version:                               Options.            (line  560)
7510
* version script:                        VERSION.            (line    6)
7511
* version script, symbol versions:       Options.            (line 1281)
7512
* VERSION {script text}:                 VERSION.            (line    6)
7513
* versions of symbols:                   VERSION.            (line    6)
7514
* VFP11_DENORM_FIX:                      ARM.                (line   83)
7515
* warnings, on combining symbols:        Options.            (line 1292)
7516
* warnings, on section alignment:        Options.            (line 1383)
7517
* warnings, on undefined symbols:        Options.            (line 1379)
7518
* weak externals:                        WIN32.              (line  401)
7519
* what is this?:                         Overview.           (line    6)
7520
* wildcard file name patterns:           Input Section Wildcards.
7521
 
7522
 
7523
* Xtensa processors:                     Xtensa.             (line    6)
7524
7525
7526

7527
Tag Table:
7528
Node: Top759
7529
Node: Overview1542
7530
Node: Invocation2656
7531
Node: Options3064
7532
Node: Environment90607
7533
Node: Scripts92367
7534
Node: Basic Script Concepts94101
7535
Node: Script Format96808
7536
Node: Simple Example97671
7537
Node: Simple Commands100767
7538
Node: Entry Point101273
7539
Node: File Commands102032
7540
Node: Format Commands106033
7541
Node: REGION_ALIAS107989
7542
Node: Miscellaneous Commands112821
7543
Node: Assignments116197
7544
Node: Simple Assignments116688
7545
Node: PROVIDE118424
7546
Node: PROVIDE_HIDDEN119629
7547
Node: Source Code Reference119873
7548
Node: SECTIONS123453
7549
Node: Output Section Description125344
7550
Node: Output Section Name126431
7551
Node: Output Section Address127307
7552
Node: Input Section129027
7553
Node: Input Section Basics129828
7554
Node: Input Section Wildcards133046
7555
Node: Input Section Common137779
7556
Node: Input Section Keep139261
7557
Node: Input Section Example139751
7558
Node: Output Section Data140719
7559
Node: Output Section Keywords143496
7560
Node: Output Section Discarding147065
7561
Node: Output Section Attributes148246
7562
Node: Output Section Type149347
7563
Node: Output Section LMA150501
7564
Node: Forced Output Alignment153014
7565
Node: Forced Input Alignment153282
7566
Node: Output Section Constraint153671
7567
Node: Output Section Region154099
7568
Node: Output Section Phdr154532
7569
Node: Output Section Fill155196
7570
Node: Overlay Description156338
7571
Node: MEMORY160641
7572
Node: PHDRS164974
7573
Node: VERSION170013
7574
Node: Expressions178088
7575
Node: Constants179017
7576
Node: Symbolic Constants179892
7577
Node: Symbols180443
7578
Node: Orphan Sections181190
7579
Node: Location Counter182354
7580
Node: Operators186790
7581
Node: Evaluation187712
7582
Node: Expression Section189076
7583
Node: Builtin Functions190565
7584
Node: Implicit Linker Scripts198532
7585
Node: Machine Dependent199307
7586
Node: H8/300200323
7587
Node: i960201948
7588
Node: M68HC11/68HC12204049
7589
Node: ARM205503
7590
Node: HPPA ELF32213015
7591
Node: M68K214638
7592
Node: MMIX215547
7593
Node: MSP430216712
7594
Node: PowerPC ELF32217761
7595
Node: PowerPC64 ELF64220597
7596
Node: SPU ELF225013
7597
Node: TI COFF227645
7598
Node: WIN32228171
7599
Node: Xtensa247895
7600
Node: BFD251017
7601
Node: BFD outline252472
7602
Node: BFD information loss253758
7603
Node: Canonical format256275
7604
Node: Reporting Bugs260632
7605
Node: Bug Criteria261326
7606
Node: Bug Reporting262025
7607
Node: MRI269064
7608
Node: GNU Free Documentation License273707

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.