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

Subversion Repositories open8_urisc

[/] [open8_urisc/] [trunk/] [gnu/] [binutils/] [ld/] [ld.texinfo] - Blame information for rev 145

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 145 khays
\input texinfo
2
@setfilename ld.info
3
@c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
4
@c 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011
5
@c Free Software Foundation, Inc.
6
@syncodeindex ky cp
7
@c man begin INCLUDE
8
@include configdoc.texi
9
@c (configdoc.texi is generated by the Makefile)
10
@include bfdver.texi
11
@c man end
12
 
13
@c @smallbook
14
 
15
@macro gcctabopt{body}
16
@code{\body\}
17
@end macro
18
 
19
@c man begin NAME
20
@ifset man
21
@c Configure for the generation of man pages
22
@set UsesEnvVars
23
@set GENERIC
24
@set ARM
25
@set C6X
26
@set H8300
27
@set HPPA
28
@set I960
29
@set M68HC11
30
@set M68K
31
@set MMIX
32
@set MSP430
33
@set POWERPC
34
@set POWERPC64
35
@set Renesas
36
@set SPU
37
@set TICOFF
38
@set WIN32
39
@set XTENSA
40
@end ifset
41
@c man end
42
 
43
@ifnottex
44
@dircategory Software development
45
@direntry
46
* Ld: (ld).                       The GNU linker.
47
@end direntry
48
@end ifnottex
49
 
50
@copying
51
This file documents the @sc{gnu} linker LD
52
@ifset VERSION_PACKAGE
53
@value{VERSION_PACKAGE}
54
@end ifset
55
version @value{VERSION}.
56
 
57
Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
58
2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
59
 
60
Permission is granted to copy, distribute and/or modify this document
61
under the terms of the GNU Free Documentation License, Version 1.3
62
or any later version published by the Free Software Foundation;
63
with no Invariant Sections, with no Front-Cover Texts, and with no
64
Back-Cover Texts.  A copy of the license is included in the
65
section entitled ``GNU Free Documentation License''.
66
@end copying
67
@iftex
68
@finalout
69
@setchapternewpage odd
70
@settitle The GNU linker
71
@titlepage
72
@title The GNU linker
73
@sp 1
74
@subtitle @code{ld}
75
@ifset VERSION_PACKAGE
76
@subtitle @value{VERSION_PACKAGE}
77
@end ifset
78
@subtitle Version @value{VERSION}
79
@author Steve Chamberlain
80
@author Ian Lance Taylor
81
@page
82
 
83
@tex
84
{\parskip=0pt
85
\hfill Red Hat Inc\par
86
\hfill nickc\@credhat.com, doc\@redhat.com\par
87
\hfill {\it The GNU linker}\par
88
\hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
89
}
90
\global\parindent=0pt % Steve likes it this way.
91
@end tex
92
 
93
@vskip 0pt plus 1filll
94
@c man begin COPYRIGHT
95
Copyright @copyright{} 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998,
96
1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free
97
Software Foundation, Inc.
98
 
99
Permission is granted to copy, distribute and/or modify this document
100
under the terms of the GNU Free Documentation License, Version 1.3
101
or any later version published by the Free Software Foundation;
102
with no Invariant Sections, with no Front-Cover Texts, and with no
103
Back-Cover Texts.  A copy of the license is included in the
104
section entitled ``GNU Free Documentation License''.
105
@c man end
106
 
107
@end titlepage
108
@end iftex
109
@contents
110
@c FIXME: Talk about importance of *order* of args, cmds to linker!
111
 
112
@ifnottex
113
@node Top
114
@top LD
115
This file documents the @sc{gnu} linker ld
116
@ifset VERSION_PACKAGE
117
@value{VERSION_PACKAGE}
118
@end ifset
119
version @value{VERSION}.
120
 
121
This document is distributed under the terms of the GNU Free
122
Documentation License version 1.3.  A copy of the license is included
123
in the section entitled ``GNU Free Documentation License''.
124
 
125
@menu
126
* Overview::                    Overview
127
* Invocation::                  Invocation
128
* Scripts::                     Linker Scripts
129
@ifset GENERIC
130
* Machine Dependent::           Machine Dependent Features
131
@end ifset
132
@ifclear GENERIC
133
@ifset H8300
134
* H8/300::                      ld and the H8/300
135
@end ifset
136
@ifset Renesas
137
* Renesas::                     ld and other Renesas micros
138
@end ifset
139
@ifset I960
140
* i960::                        ld and the Intel 960 family
141
@end ifset
142
@ifset ARM
143
* ARM::                         ld and the ARM family
144
@end ifset
145
@ifset HPPA
146
* HPPA ELF32::                  ld and HPPA 32-bit ELF
147
@end ifset
148
@ifset M68HC11
149
* M68HC11/68HC12::              ld and the Motorola 68HC11 and 68HC12 families
150
@end ifset
151
@ifset M68K
152
* M68K::                        ld and Motorola 68K family
153
@end ifset
154
@ifset POWERPC
155
* PowerPC ELF32::               ld and PowerPC 32-bit ELF Support
156
@end ifset
157
@ifset POWERPC64
158
* PowerPC64 ELF64::             ld and PowerPC64 64-bit ELF Support
159
@end ifset
160
@ifset SPU
161
* SPU ELF::                     ld and SPU ELF Support
162
@end ifset
163
@ifset TICOFF
164
* TI COFF::                     ld and the TI COFF
165
@end ifset
166
@ifset WIN32
167
* Win32::                       ld and WIN32 (cygwin/mingw)
168
@end ifset
169
@ifset XTENSA
170
* Xtensa::                      ld and Xtensa Processors
171
@end ifset
172
@end ifclear
173
@ifclear SingleFormat
174
* BFD::                         BFD
175
@end ifclear
176
@c Following blank line required for remaining bug in makeinfo conds/menus
177
 
178
* Reporting Bugs::              Reporting Bugs
179
* MRI::                         MRI Compatible Script Files
180
* GNU Free Documentation License::  GNU Free Documentation License
181
* LD Index::                       LD Index
182
@end menu
183
@end ifnottex
184
 
185
@node Overview
186
@chapter Overview
187
 
188
@cindex @sc{gnu} linker
189
@cindex what is this?
190
 
191
@ifset man
192
@c man begin SYNOPSIS
193
ld [@b{options}] @var{objfile} @dots{}
194
@c man end
195
 
196
@c man begin SEEALSO
197
ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
198
the Info entries for @file{binutils} and
199
@file{ld}.
200
@c man end
201
@end ifset
202
 
203
@c man begin DESCRIPTION
204
 
205
@command{ld} combines a number of object and archive files, relocates
206
their data and ties up symbol references. Usually the last step in
207
compiling a program is to run @command{ld}.
208
 
209
@command{ld} accepts Linker Command Language files written in
210
a superset of AT&T's Link Editor Command Language syntax,
211
to provide explicit and total control over the linking process.
212
 
213
@ifset man
214
@c For the man only
215
This man page does not describe the command language; see the
216
@command{ld} entry in @code{info} for full details on the command
217
language and on other aspects of the GNU linker.
218
@end ifset
219
 
220
@ifclear SingleFormat
221
This version of @command{ld} uses the general purpose BFD libraries
222
to operate on object files. This allows @command{ld} to read, combine, and
223
write object files in many different formats---for example, COFF or
224
@code{a.out}.  Different formats may be linked together to produce any
225
available kind of object file.  @xref{BFD}, for more information.
226
@end ifclear
227
 
228
Aside from its flexibility, the @sc{gnu} linker is more helpful than other
229
linkers in providing diagnostic information.  Many linkers abandon
230
execution immediately upon encountering an error; whenever possible,
231
@command{ld} continues executing, allowing you to identify other errors
232
(or, in some cases, to get an output file in spite of the error).
233
 
234
@c man end
235
 
236
@node Invocation
237
@chapter Invocation
238
 
239
@c man begin DESCRIPTION
240
 
241
The @sc{gnu} linker @command{ld} is meant to cover a broad range of situations,
242
and to be as compatible as possible with other linkers.  As a result,
243
you have many choices to control its behavior.
244
 
245
@c man end
246
 
247
@ifset UsesEnvVars
248
@menu
249
* Options::                     Command Line Options
250
* Environment::                 Environment Variables
251
@end menu
252
 
253
@node Options
254
@section Command Line Options
255
@end ifset
256
 
257
@cindex command line
258
@cindex options
259
 
260
@c man begin OPTIONS
261
 
262
The linker supports a plethora of command-line options, but in actual
263
practice few of them are used in any particular context.
264
@cindex standard Unix system
265
For instance, a frequent use of @command{ld} is to link standard Unix
266
object files on a standard, supported Unix system.  On such a system, to
267
link a file @code{hello.o}:
268
 
269
@smallexample
270
ld -o @var{output} /lib/crt0.o hello.o -lc
271
@end smallexample
272
 
273
This tells @command{ld} to produce a file called @var{output} as the
274
result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
275
the library @code{libc.a}, which will come from the standard search
276
directories.  (See the discussion of the @samp{-l} option below.)
277
 
278
Some of the command-line options to @command{ld} may be specified at any
279
point in the command line.  However, options which refer to files, such
280
as @samp{-l} or @samp{-T}, cause the file to be read at the point at
281
which the option appears in the command line, relative to the object
282
files and other file options.  Repeating non-file options with a
283
different argument will either have no further effect, or override prior
284
occurrences (those further to the left on the command line) of that
285
option.  Options which may be meaningfully specified more than once are
286
noted in the descriptions below.
287
 
288
@cindex object files
289
Non-option arguments are object files or archives which are to be linked
290
together.  They may follow, precede, or be mixed in with command-line
291
options, except that an object file argument may not be placed between
292
an option and its argument.
293
 
294
Usually the linker is invoked with at least one object file, but you can
295
specify other forms of binary input files using @samp{-l}, @samp{-R},
296
and the script command language.  If @emph{no} binary input files at all
297
are specified, the linker does not produce any output, and issues the
298
message @samp{No input files}.
299
 
300
If the linker cannot recognize the format of an object file, it will
301
assume that it is a linker script.  A script specified in this way
302
augments the main linker script used for the link (either the default
303
linker script or the one specified by using @samp{-T}).  This feature
304
permits the linker to link against a file which appears to be an object
305
or an archive, but actually merely defines some symbol values, or uses
306
@code{INPUT} or @code{GROUP} to load other objects.  Specifying a
307
script in this way merely augments the main linker script, with the
308
extra commands placed after the main script; use the @samp{-T} option
309
to replace the default linker script entirely, but note the effect of
310
the @code{INSERT} command.  @xref{Scripts}.
311
 
312
For options whose names are a single letter,
313
option arguments must either follow the option letter without intervening
314
whitespace, or be given as separate arguments immediately following the
315
option that requires them.
316
 
317
For options whose names are multiple letters, either one dash or two can
318
precede the option name; for example, @samp{-trace-symbol} and
319
@samp{--trace-symbol} are equivalent.  Note---there is one exception to
320
this rule.  Multiple letter options that start with a lower case 'o' can
321
only be preceded by two dashes.  This is to reduce confusion with the
322
@samp{-o} option.  So for example @samp{-omagic} sets the output file
323
name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
324
output.
325
 
326
Arguments to multiple-letter options must either be separated from the
327
option name by an equals sign, or be given as separate arguments
328
immediately following the option that requires them.  For example,
329
@samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent.
330
Unique abbreviations of the names of multiple-letter options are
331
accepted.
332
 
333
Note---if the linker is being invoked indirectly, via a compiler driver
334
(e.g. @samp{gcc}) then all the linker command line options should be
335
prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
336
compiler driver) like this:
337
 
338
@smallexample
339
  gcc -Wl,--start-group foo.o bar.o -Wl,--end-group
340
@end smallexample
341
 
342
This is important, because otherwise the compiler driver program may
343
silently drop the linker options, resulting in a bad link.  Confusion
344
may also arise when passing options that require values through a
345
driver, as the use of a space between option and argument acts as
346
a separator, and causes the driver to pass only the option to the linker
347
and the argument to the compiler.  In this case, it is simplest to use
348
the joined forms of both single- and multiple-letter options, such as:
349
 
350
@smallexample
351
  gcc foo.o bar.o -Wl,-eENTRY -Wl,-Map=a.map
352
@end smallexample
353
 
354
Here is a table of the generic command line switches accepted by the GNU
355
linker:
356
 
357
@table @gcctabopt
358
@include at-file.texi
359
 
360
@kindex -a @var{keyword}
361
@item -a @var{keyword}
362
This option is supported for HP/UX compatibility.  The @var{keyword}
363
argument must be one of the strings @samp{archive}, @samp{shared}, or
364
@samp{default}.  @samp{-aarchive} is functionally equivalent to
365
@samp{-Bstatic}, and the other two keywords are functionally equivalent
366
to @samp{-Bdynamic}.  This option may be used any number of times.
367
 
368
@kindex --audit @var{AUDITLIB}
369
@item --audit @var{AUDITLIB}
370
Adds @var{AUDITLIB} to the @code{DT_AUDIT} entry of the dynamic section.
371
@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
372
specified in the library.  If specified multiple times @code{DT_AUDIT}
373
will contain a colon separated list of audit interfaces to use. If the linker
374
finds an object with an audit entry while searching for shared libraries,
375
it will add a corresponding @code{DT_DEPAUDIT} entry in the output file.
376
This option is only meaningful on ELF platforms supporting the rtld-audit
377
interface.
378
 
379
@ifset I960
380
@cindex architectures
381
@kindex -A @var{arch}
382
@item -A @var{architecture}
383
@kindex --architecture=@var{arch}
384
@itemx --architecture=@var{architecture}
385
In the current release of @command{ld}, this option is useful only for the
386
Intel 960 family of architectures.  In that @command{ld} configuration, the
387
@var{architecture} argument identifies the particular architecture in
388
the 960 family, enabling some safeguards and modifying the
389
archive-library search path.  @xref{i960,,@command{ld} and the Intel 960
390
family}, for details.
391
 
392
Future releases of @command{ld} may support similar functionality for
393
other architecture families.
394
@end ifset
395
 
396
@ifclear SingleFormat
397
@cindex binary input format
398
@kindex -b @var{format}
399
@kindex --format=@var{format}
400
@cindex input format
401
@cindex input format
402
@item -b @var{input-format}
403
@itemx --format=@var{input-format}
404
@command{ld} may be configured to support more than one kind of object
405
file.  If your @command{ld} is configured this way, you can use the
406
@samp{-b} option to specify the binary format for input object files
407
that follow this option on the command line.  Even when @command{ld} is
408
configured to support alternative object formats, you don't usually need
409
to specify this, as @command{ld} should be configured to expect as a
410
default input format the most usual format on each machine.
411
@var{input-format} is a text string, the name of a particular format
412
supported by the BFD libraries.  (You can list the available binary
413
formats with @samp{objdump -i}.)
414
@xref{BFD}.
415
 
416
You may want to use this option if you are linking files with an unusual
417
binary format.  You can also use @samp{-b} to switch formats explicitly (when
418
linking object files of different formats), by including
419
@samp{-b @var{input-format}} before each group of object files in a
420
particular format.
421
 
422
The default format is taken from the environment variable
423
@code{GNUTARGET}.
424
@ifset UsesEnvVars
425
@xref{Environment}.
426
@end ifset
427
You can also define the input format from a script, using the command
428
@code{TARGET};
429
@ifclear man
430
see @ref{Format Commands}.
431
@end ifclear
432
@end ifclear
433
 
434
@kindex -c @var{MRI-cmdfile}
435
@kindex --mri-script=@var{MRI-cmdfile}
436
@cindex compatibility, MRI
437
@item -c @var{MRI-commandfile}
438
@itemx --mri-script=@var{MRI-commandfile}
439
For compatibility with linkers produced by MRI, @command{ld} accepts script
440
files written in an alternate, restricted command language, described in
441
@ifclear man
442
@ref{MRI,,MRI Compatible Script Files}.
443
@end ifclear
444
@ifset man
445
the MRI Compatible Script Files section of GNU ld documentation.
446
@end ifset
447
Introduce MRI script files with
448
the option @samp{-c}; use the @samp{-T} option to run linker
449
scripts written in the general-purpose @command{ld} scripting language.
450
If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
451
specified by any @samp{-L} options.
452
 
453
@cindex common allocation
454
@kindex -d
455
@kindex -dc
456
@kindex -dp
457
@item -d
458
@itemx -dc
459
@itemx -dp
460
These three options are equivalent; multiple forms are supported for
461
compatibility with other linkers.  They assign space to common symbols
462
even if a relocatable output file is specified (with @samp{-r}).  The
463
script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
464
@xref{Miscellaneous Commands}.
465
 
466
@kindex --depaudit @var{AUDITLIB}
467
@kindex -P @var{AUDITLIB}
468
@item --depaudit @var{AUDITLIB}
469
@itemx -P @var{AUDITLIB}
470
Adds @var{AUDITLIB} to the @code{DT_DEPAUDIT} entry of the dynamic section.
471
@var{AUDITLIB} is not checked for existence, nor will it use the DT_SONAME
472
specified in the library.  If specified multiple times @code{DT_DEPAUDIT}
473
will contain a colon separated list of audit interfaces to use.  This
474
option is only meaningful on ELF platforms supporting the rtld-audit interface.
475
The -P option is provided for Solaris compatibility.
476
 
477
@cindex entry point, from command line
478
@kindex -e @var{entry}
479
@kindex --entry=@var{entry}
480
@item -e @var{entry}
481
@itemx --entry=@var{entry}
482
Use @var{entry} as the explicit symbol for beginning execution of your
483
program, rather than the default entry point.  If there is no symbol
484
named @var{entry}, the linker will try to parse @var{entry} as a number,
485
and use that as the entry address (the number will be interpreted in
486
base 10; you may use a leading @samp{0x} for base 16, or a leading
487
@samp{0} for base 8).  @xref{Entry Point}, for a discussion of defaults
488
and other ways of specifying the entry point.
489
 
490
@kindex --exclude-libs
491
@item --exclude-libs @var{lib},@var{lib},...
492
Specifies a list of archive libraries from which symbols should not be automatically
493
exported.  The library names may be delimited by commas or colons.  Specifying
494
@code{--exclude-libs ALL} excludes symbols in all archive libraries from
495
automatic export.  This option is available only for the i386 PE targeted
496
port of the linker and for ELF targeted ports.  For i386 PE, symbols
497
explicitly listed in a .def file are still exported, regardless of this
498
option.  For ELF targeted ports, symbols affected by this option will
499
be treated as hidden.
500
 
501
@kindex --exclude-modules-for-implib
502
@item --exclude-modules-for-implib @var{module},@var{module},...
503
Specifies a list of object files or archive members, from which symbols
504
should not be automatically exported, but which should be copied wholesale
505
into the import library being generated during the link.  The module names
506
may be delimited by commas or colons, and must match exactly the filenames
507
used by @command{ld} to open the files; for archive members, this is simply
508
the member name, but for object files the name listed must include and
509
match precisely any path used to specify the input file on the linker's
510
command-line.  This option is available only for the i386 PE targeted port
511
of the linker.  Symbols explicitly listed in a .def file are still exported,
512
regardless of this option.
513
 
514
@cindex dynamic symbol table
515
@kindex -E
516
@kindex --export-dynamic
517
@kindex --no-export-dynamic
518
@item -E
519
@itemx --export-dynamic
520
@itemx --no-export-dynamic
521
When creating a dynamically linked executable, using the @option{-E}
522
option or the @option{--export-dynamic} option causes the linker to add
523
all symbols to the dynamic symbol table.  The dynamic symbol table is the
524
set of symbols which are visible from dynamic objects at run time.
525
 
526
If you do not use either of these options (or use the
527
@option{--no-export-dynamic} option to restore the default behavior), the
528
dynamic symbol table will normally contain only those symbols which are
529
referenced by some dynamic object mentioned in the link.
530
 
531
If you use @code{dlopen} to load a dynamic object which needs to refer
532
back to the symbols defined by the program, rather than some other
533
dynamic object, then you will probably need to use this option when
534
linking the program itself.
535
 
536
You can also use the dynamic list to control what symbols should
537
be added to the dynamic symbol table if the output format supports it.
538
See the description of @samp{--dynamic-list}.
539
 
540
Note that this option is specific to ELF targeted ports.  PE targets
541
support a similar function to export all symbols from a DLL or EXE; see
542
the description of @samp{--export-all-symbols} below.
543
 
544
@ifclear SingleFormat
545
@cindex big-endian objects
546
@cindex endianness
547
@kindex -EB
548
@item -EB
549
Link big-endian objects.  This affects the default output format.
550
 
551
@cindex little-endian objects
552
@kindex -EL
553
@item -EL
554
Link little-endian objects.  This affects the default output format.
555
@end ifclear
556
 
557
@kindex -f @var{name}
558
@kindex --auxiliary=@var{name}
559
@item -f @var{name}
560
@itemx --auxiliary=@var{name}
561
When creating an ELF shared object, set the internal DT_AUXILIARY field
562
to the specified name.  This tells the dynamic linker that the symbol
563
table of the shared object should be used as an auxiliary filter on the
564
symbol table of the shared object @var{name}.
565
 
566
If you later link a program against this filter object, then, when you
567
run the program, the dynamic linker will see the DT_AUXILIARY field.  If
568
the dynamic linker resolves any symbols from the filter object, it will
569
first check whether there is a definition in the shared object
570
@var{name}.  If there is one, it will be used instead of the definition
571
in the filter object.  The shared object @var{name} need not exist.
572
Thus the shared object @var{name} may be used to provide an alternative
573
implementation of certain functions, perhaps for debugging or for
574
machine specific performance.
575
 
576
This option may be specified more than once.  The DT_AUXILIARY entries
577
will be created in the order in which they appear on the command line.
578
 
579
@kindex -F @var{name}
580
@kindex --filter=@var{name}
581
@item -F @var{name}
582
@itemx --filter=@var{name}
583
When creating an ELF shared object, set the internal DT_FILTER field to
584
the specified name.  This tells the dynamic linker that the symbol table
585
of the shared object which is being created should be used as a filter
586
on the symbol table of the shared object @var{name}.
587
 
588
If you later link a program against this filter object, then, when you
589
run the program, the dynamic linker will see the DT_FILTER field.  The
590
dynamic linker will resolve symbols according to the symbol table of the
591
filter object as usual, but it will actually link to the definitions
592
found in the shared object @var{name}.  Thus the filter object can be
593
used to select a subset of the symbols provided by the object
594
@var{name}.
595
 
596
Some older linkers used the @option{-F} option throughout a compilation
597
toolchain for specifying object-file format for both input and output
598
object files.
599
@ifclear SingleFormat
600
The @sc{gnu} linker uses other mechanisms for this purpose: the
601
@option{-b}, @option{--format}, @option{--oformat} options, the
602
@code{TARGET} command in linker scripts, and the @code{GNUTARGET}
603
environment variable.
604
@end ifclear
605
The @sc{gnu} linker will ignore the @option{-F} option when not
606
creating an ELF shared object.
607
 
608
@cindex finalization function
609
@kindex -fini=@var{name}
610
@item -fini=@var{name}
611
When creating an ELF executable or shared object, call NAME when the
612
executable or shared object is unloaded, by setting DT_FINI to the
613
address of the function.  By default, the linker uses @code{_fini} as
614
the function to call.
615
 
616
@kindex -g
617
@item -g
618
Ignored.  Provided for compatibility with other tools.
619
 
620
@kindex -G @var{value}
621
@kindex --gpsize=@var{value}
622
@cindex object size
623
@item -G @var{value}
624
@itemx --gpsize=@var{value}
625
Set the maximum size of objects to be optimized using the GP register to
626
@var{size}.  This is only meaningful for object file formats such as
627
MIPS ECOFF which supports putting large and small objects into different
628
sections.  This is ignored for other object file formats.
629
 
630
@cindex runtime library name
631
@kindex -h @var{name}
632
@kindex -soname=@var{name}
633
@item -h @var{name}
634
@itemx -soname=@var{name}
635
When creating an ELF shared object, set the internal DT_SONAME field to
636
the specified name.  When an executable is linked with a shared object
637
which has a DT_SONAME field, then when the executable is run the dynamic
638
linker will attempt to load the shared object specified by the DT_SONAME
639
field rather than the using the file name given to the linker.
640
 
641
@kindex -i
642
@cindex incremental link
643
@item -i
644
Perform an incremental link (same as option @samp{-r}).
645
 
646
@cindex initialization function
647
@kindex -init=@var{name}
648
@item -init=@var{name}
649
When creating an ELF executable or shared object, call NAME when the
650
executable or shared object is loaded, by setting DT_INIT to the address
651
of the function.  By default, the linker uses @code{_init} as the
652
function to call.
653
 
654
@cindex archive files, from cmd line
655
@kindex -l @var{namespec}
656
@kindex --library=@var{namespec}
657
@item -l @var{namespec}
658
@itemx --library=@var{namespec}
659
Add the archive or object file specified by @var{namespec} to the
660
list of files to link.  This option may be used any number of times.
661
If @var{namespec} is of the form @file{:@var{filename}}, @command{ld}
662
will search the library path for a file called @var{filename}, otherwise it
663
will search the library path for a file called @file{lib@var{namespec}.a}.
664
 
665
On systems which support shared libraries, @command{ld} may also search for
666
files other than @file{lib@var{namespec}.a}.  Specifically, on ELF
667
and SunOS systems, @command{ld} will search a directory for a library
668
called @file{lib@var{namespec}.so} before searching for one called
669
@file{lib@var{namespec}.a}.  (By convention, a @code{.so} extension
670
indicates a shared library.)  Note that this behavior does not apply
671
to @file{:@var{filename}}, which always specifies a file called
672
@var{filename}.
673
 
674
The linker will search an archive only once, at the location where it is
675
specified on the command line.  If the archive defines a symbol which
676
was undefined in some object which appeared before the archive on the
677
command line, the linker will include the appropriate file(s) from the
678
archive.  However, an undefined symbol in an object appearing later on
679
the command line will not cause the linker to search the archive again.
680
 
681
See the @option{-(} option for a way to force the linker to search
682
archives multiple times.
683
 
684
You may list the same archive multiple times on the command line.
685
 
686
@ifset GENERIC
687
This type of archive searching is standard for Unix linkers.  However,
688
if you are using @command{ld} on AIX, note that it is different from the
689
behaviour of the AIX linker.
690
@end ifset
691
 
692
@cindex search directory, from cmd line
693
@kindex -L @var{dir}
694
@kindex --library-path=@var{dir}
695
@item -L @var{searchdir}
696
@itemx --library-path=@var{searchdir}
697
Add path @var{searchdir} to the list of paths that @command{ld} will search
698
for archive libraries and @command{ld} control scripts.  You may use this
699
option any number of times.  The directories are searched in the order
700
in which they are specified on the command line.  Directories specified
701
on the command line are searched before the default directories.  All
702
@option{-L} options apply to all @option{-l} options, regardless of the
703
order in which the options appear.  @option{-L} options do not affect
704
how @command{ld} searches for a linker script unless @option{-T}
705
option is specified.
706
 
707
If @var{searchdir} begins with @code{=}, then the @code{=} will be replaced
708
by the @dfn{sysroot prefix}, a path specified when the linker is configured.
709
 
710
@ifset UsesEnvVars
711
The default set of paths searched (without being specified with
712
@samp{-L}) depends on which emulation mode @command{ld} is using, and in
713
some cases also on how it was configured.  @xref{Environment}.
714
@end ifset
715
 
716
The paths can also be specified in a link script with the
717
@code{SEARCH_DIR} command.  Directories specified this way are searched
718
at the point in which the linker script appears in the command line.
719
 
720
@cindex emulation
721
@kindex -m @var{emulation}
722
@item -m @var{emulation}
723
Emulate the @var{emulation} linker.  You can list the available
724
emulations with the @samp{--verbose} or @samp{-V} options.
725
 
726
If the @samp{-m} option is not used, the emulation is taken from the
727
@code{LDEMULATION} environment variable, if that is defined.
728
 
729
Otherwise, the default emulation depends upon how the linker was
730
configured.
731
 
732
@cindex link map
733
@kindex -M
734
@kindex --print-map
735
@item -M
736
@itemx --print-map
737
Print a link map to the standard output.  A link map provides
738
information about the link, including the following:
739
 
740
@itemize @bullet
741
@item
742
Where object files are mapped into memory.
743
@item
744
How common symbols are allocated.
745
@item
746
All archive members included in the link, with a mention of the symbol
747
which caused the archive member to be brought in.
748
@item
749
The values assigned to symbols.
750
 
751
Note - symbols whose values are computed by an expression which
752
involves a reference to a previous value of the same symbol may not
753
have correct result displayed in the link map.  This is because the
754
linker discards intermediate results and only retains the final value
755
of an expression.  Under such circumstances the linker will display
756
the final value enclosed by square brackets.  Thus for example a
757
linker script containing:
758
 
759
@smallexample
760
   foo = 1
761
   foo = foo * 4
762
   foo = foo + 8
763
@end smallexample
764
 
765
will produce the following output in the link map if the @option{-M}
766
option is used:
767
 
768
@smallexample
769
   0x00000001                foo = 0x1
770
   [0x0000000c]                foo = (foo * 0x4)
771
   [0x0000000c]                foo = (foo + 0x8)
772
@end smallexample
773
 
774
See @ref{Expressions} for more information about expressions in linker
775
scripts.
776
@end itemize
777
 
778
@kindex -n
779
@cindex read-only text
780
@cindex NMAGIC
781
@kindex --nmagic
782
@item -n
783
@itemx --nmagic
784
Turn off page alignment of sections, and disable linking against shared
785
libraries.  If the output format supports Unix style magic numbers,
786
mark the output as @code{NMAGIC}.
787
 
788
@kindex -N
789
@kindex --omagic
790
@cindex read/write from cmd line
791
@cindex OMAGIC
792
@item -N
793
@itemx --omagic
794
Set the text and data sections to be readable and writable.  Also, do
795
not page-align the data segment, and disable linking against shared
796
libraries.  If the output format supports Unix style magic numbers,
797
mark the output as @code{OMAGIC}. Note: Although a writable text section
798
is allowed for PE-COFF targets, it does not conform to the format
799
specification published by Microsoft.
800
 
801
@kindex --no-omagic
802
@cindex OMAGIC
803
@item --no-omagic
804
This option negates most of the effects of the @option{-N} option.  It
805
sets the text section to be read-only, and forces the data segment to
806
be page-aligned.  Note - this option does not enable linking against
807
shared libraries.  Use @option{-Bdynamic} for this.
808
 
809
@kindex -o @var{output}
810
@kindex --output=@var{output}
811
@cindex naming the output file
812
@item -o @var{output}
813
@itemx --output=@var{output}
814
Use @var{output} as the name for the program produced by @command{ld}; if this
815
option is not specified, the name @file{a.out} is used by default.  The
816
script command @code{OUTPUT} can also specify the output file name.
817
 
818
@kindex -O @var{level}
819
@cindex generating optimized output
820
@item -O @var{level}
821
If @var{level} is a numeric values greater than zero @command{ld} optimizes
822
the output.  This might take significantly longer and therefore probably
823
should only be enabled for the final binary.  At the moment this
824
option only affects ELF shared library generation.  Future releases of
825
the linker may make more use of this option.  Also currently there is
826
no difference in the linker's behaviour for different non-zero values
827
of this option.  Again this may change with future releases.
828
 
829
@kindex -q
830
@kindex --emit-relocs
831
@cindex retain relocations in final executable
832
@item -q
833
@itemx --emit-relocs
834
Leave relocation sections and contents in fully linked executables.
835
Post link analysis and optimization tools may need this information in
836
order to perform correct modifications of executables.  This results
837
in larger executables.
838
 
839
This option is currently only supported on ELF platforms.
840
 
841
@kindex --force-dynamic
842
@cindex forcing the creation of dynamic sections
843
@item --force-dynamic
844
Force the output file to have dynamic sections.  This option is specific
845
to VxWorks targets.
846
 
847
@cindex partial link
848
@cindex relocatable output
849
@kindex -r
850
@kindex --relocatable
851
@item -r
852
@itemx --relocatable
853
Generate relocatable output---i.e., generate an output file that can in
854
turn serve as input to @command{ld}.  This is often called @dfn{partial
855
linking}.  As a side effect, in environments that support standard Unix
856
magic numbers, this option also sets the output file's magic number to
857
@code{OMAGIC}.
858
@c ; see @option{-N}.
859
If this option is not specified, an absolute file is produced.  When
860
linking C++ programs, this option @emph{will not} resolve references to
861
constructors; to do that, use @samp{-Ur}.
862
 
863
When an input file does not have the same format as the output file,
864
partial linking is only supported if that input file does not contain any
865
relocations.  Different output formats can have further restrictions; for
866
example some @code{a.out}-based formats do not support partial linking
867
with input files in other formats at all.
868
 
869
This option does the same thing as @samp{-i}.
870
 
871
@kindex -R @var{file}
872
@kindex --just-symbols=@var{file}
873
@cindex symbol-only input
874
@item -R @var{filename}
875
@itemx --just-symbols=@var{filename}
876
Read symbol names and their addresses from @var{filename}, but do not
877
relocate it or include it in the output.  This allows your output file
878
to refer symbolically to absolute locations of memory defined in other
879
programs.  You may use this option more than once.
880
 
881
For compatibility with other ELF linkers, if the @option{-R} option is
882
followed by a directory name, rather than a file name, it is treated as
883
the @option{-rpath} option.
884
 
885
@kindex -s
886
@kindex --strip-all
887
@cindex strip all symbols
888
@item -s
889
@itemx --strip-all
890
Omit all symbol information from the output file.
891
 
892
@kindex -S
893
@kindex --strip-debug
894
@cindex strip debugger symbols
895
@item -S
896
@itemx --strip-debug
897
Omit debugger symbol information (but not all symbols) from the output file.
898
 
899
@kindex -t
900
@kindex --trace
901
@cindex input files, displaying
902
@item -t
903
@itemx --trace
904
Print the names of the input files as @command{ld} processes them.
905
 
906
@kindex -T @var{script}
907
@kindex --script=@var{script}
908
@cindex script files
909
@item -T @var{scriptfile}
910
@itemx --script=@var{scriptfile}
911
Use @var{scriptfile} as the linker script.  This script replaces
912
@command{ld}'s default linker script (rather than adding to it), so
913
@var{commandfile} must specify everything necessary to describe the
914
output file.  @xref{Scripts}.  If @var{scriptfile} does not exist in
915
the current directory, @code{ld} looks for it in the directories
916
specified by any preceding @samp{-L} options.  Multiple @samp{-T}
917
options accumulate.
918
 
919
@kindex -dT @var{script}
920
@kindex --default-script=@var{script}
921
@cindex script files
922
@item -dT @var{scriptfile}
923
@itemx --default-script=@var{scriptfile}
924
Use @var{scriptfile} as the default linker script.  @xref{Scripts}.
925
 
926
This option is similar to the @option{--script} option except that
927
processing of the script is delayed until after the rest of the
928
command line has been processed.  This allows options placed after the
929
@option{--default-script} option on the command line to affect the
930
behaviour of the linker script, which can be important when the linker
931
command line cannot be directly controlled by the user.  (eg because
932
the command line is being constructed by another tool, such as
933
@samp{gcc}).
934
 
935
@kindex -u @var{symbol}
936
@kindex --undefined=@var{symbol}
937
@cindex undefined symbol
938
@item -u @var{symbol}
939
@itemx --undefined=@var{symbol}
940
Force @var{symbol} to be entered in the output file as an undefined
941
symbol.  Doing this may, for example, trigger linking of additional
942
modules from standard libraries.  @samp{-u} may be repeated with
943
different option arguments to enter additional undefined symbols.  This
944
option is equivalent to the @code{EXTERN} linker script command.
945
 
946
@kindex -Ur
947
@cindex constructors
948
@item -Ur
949
For anything other than C++ programs, this option is equivalent to
950
@samp{-r}: it generates relocatable output---i.e., an output file that can in
951
turn serve as input to @command{ld}.  When linking C++ programs, @samp{-Ur}
952
@emph{does} resolve references to constructors, unlike @samp{-r}.
953
It does not work to use @samp{-Ur} on files that were themselves linked
954
with @samp{-Ur}; once the constructor table has been built, it cannot
955
be added to.  Use @samp{-Ur} only for the last partial link, and
956
@samp{-r} for the others.
957
 
958
@kindex --unique[=@var{SECTION}]
959
@item --unique[=@var{SECTION}]
960
Creates a separate output section for every input section matching
961
@var{SECTION}, or if the optional wildcard @var{SECTION} argument is
962
missing, for every orphan input section.  An orphan section is one not
963
specifically mentioned in a linker script.  You may use this option
964
multiple times on the command line;  It prevents the normal merging of
965
input sections with the same name, overriding output section assignments
966
in a linker script.
967
 
968
@kindex -v
969
@kindex -V
970
@kindex --version
971
@cindex version
972
@item -v
973
@itemx --version
974
@itemx -V
975
Display the version number for @command{ld}.  The @option{-V} option also
976
lists the supported emulations.
977
 
978
@kindex -x
979
@kindex --discard-all
980
@cindex deleting local symbols
981
@item -x
982
@itemx --discard-all
983
Delete all local symbols.
984
 
985
@kindex -X
986
@kindex --discard-locals
987
@cindex local symbols, deleting
988
@item -X
989
@itemx --discard-locals
990
Delete all temporary local symbols.  (These symbols start with
991
system-specific local label prefixes, typically @samp{.L} for ELF systems
992
or @samp{L} for traditional a.out systems.)
993
 
994
@kindex -y @var{symbol}
995
@kindex --trace-symbol=@var{symbol}
996
@cindex symbol tracing
997
@item -y @var{symbol}
998
@itemx --trace-symbol=@var{symbol}
999
Print the name of each linked file in which @var{symbol} appears.  This
1000
option may be given any number of times.  On many systems it is necessary
1001
to prepend an underscore.
1002
 
1003
This option is useful when you have an undefined symbol in your link but
1004
don't know where the reference is coming from.
1005
 
1006
@kindex -Y @var{path}
1007
@item -Y @var{path}
1008
Add @var{path} to the default library search path.  This option exists
1009
for Solaris compatibility.
1010
 
1011
@kindex -z @var{keyword}
1012
@item -z @var{keyword}
1013
The recognized keywords are:
1014
@table @samp
1015
 
1016
@item combreloc
1017
Combines multiple reloc sections and sorts them to make dynamic symbol
1018
lookup caching possible.
1019
 
1020
@item defs
1021
Disallows undefined symbols in object files.  Undefined symbols in
1022
shared libraries are still allowed.
1023
 
1024
@item execstack
1025
Marks the object as requiring executable stack.
1026
 
1027
@item initfirst
1028
This option is only meaningful when building a shared object.
1029
It marks the object so that its runtime initialization will occur
1030
before the runtime initialization of any other objects brought into
1031
the process at the same time.  Similarly the runtime finalization of
1032
the object will occur after the runtime finalization of any other
1033
objects.
1034
 
1035
@item interpose
1036
Marks the object that its symbol table interposes before all symbols
1037
but the primary executable.
1038
 
1039
@item lazy
1040
When generating an executable or shared library, mark it to tell the
1041
dynamic linker to defer function call resolution to the point when
1042
the function is called (lazy binding), rather than at load time.
1043
Lazy binding is the default.
1044
 
1045
@item loadfltr
1046
Marks  the object that its filters be processed immediately at
1047
runtime.
1048
 
1049
@item muldefs
1050
Allows multiple definitions.
1051
 
1052
@item nocombreloc
1053
Disables multiple reloc sections combining.
1054
 
1055
@item nocopyreloc
1056
Disables production of copy relocs.
1057
 
1058
@item nodefaultlib
1059
Marks the object that the search for dependencies of this object will
1060
ignore any default library search paths.
1061
 
1062
@item nodelete
1063
Marks the object shouldn't be unloaded at runtime.
1064
 
1065
@item nodlopen
1066
Marks the object not available to @code{dlopen}.
1067
 
1068
@item nodump
1069
Marks the object can not be dumped by @code{dldump}.
1070
 
1071
@item noexecstack
1072
Marks the object as not requiring executable stack.
1073
 
1074
@item norelro
1075
Don't create an ELF @code{PT_GNU_RELRO} segment header in the object.
1076
 
1077
@item now
1078
When generating an executable or shared library, mark it to tell the
1079
dynamic linker to resolve all symbols when the program is started, or
1080
when the shared library is linked to using dlopen, instead of
1081
deferring function call resolution to the point when the function is
1082
first called.
1083
 
1084
@item origin
1085
Marks the object may contain $ORIGIN.
1086
 
1087
@item relro
1088
Create an ELF @code{PT_GNU_RELRO} segment header in the object.
1089
 
1090
@item max-page-size=@var{value}
1091
Set the emulation maximum page size to @var{value}.
1092
 
1093
@item common-page-size=@var{value}
1094
Set the emulation common page size to @var{value}.
1095
 
1096
@end table
1097
 
1098
Other keywords are ignored for Solaris compatibility.
1099
 
1100
@kindex -(
1101
@cindex groups of archives
1102
@item -( @var{archives} -)
1103
@itemx --start-group @var{archives} --end-group
1104
The @var{archives} should be a list of archive files.  They may be
1105
either explicit file names, or @samp{-l} options.
1106
 
1107
The specified archives are searched repeatedly until no new undefined
1108
references are created.  Normally, an archive is searched only once in
1109
the order that it is specified on the command line.  If a symbol in that
1110
archive is needed to resolve an undefined symbol referred to by an
1111
object in an archive that appears later on the command line, the linker
1112
would not be able to resolve that reference.  By grouping the archives,
1113
they all be searched repeatedly until all possible references are
1114
resolved.
1115
 
1116
Using this option has a significant performance cost.  It is best to use
1117
it only when there are unavoidable circular references between two or
1118
more archives.
1119
 
1120
@kindex --accept-unknown-input-arch
1121
@kindex --no-accept-unknown-input-arch
1122
@item --accept-unknown-input-arch
1123
@itemx --no-accept-unknown-input-arch
1124
Tells the linker to accept input files whose architecture cannot be
1125
recognised.  The assumption is that the user knows what they are doing
1126
and deliberately wants to link in these unknown input files.  This was
1127
the default behaviour of the linker, before release 2.14.  The default
1128
behaviour from release 2.14 onwards is to reject such input files, and
1129
so the @samp{--accept-unknown-input-arch} option has been added to
1130
restore the old behaviour.
1131
 
1132
@kindex --as-needed
1133
@kindex --no-as-needed
1134
@item --as-needed
1135
@itemx --no-as-needed
1136
This option affects ELF DT_NEEDED tags for dynamic libraries mentioned
1137
on the command line after the @option{--as-needed} option.  Normally
1138
the linker will add a DT_NEEDED tag for each dynamic library mentioned
1139
on the command line, regardless of whether the library is actually
1140
needed or not.  @option{--as-needed} causes a DT_NEEDED tag to only be
1141
emitted for a library that satisfies an undefined symbol reference
1142
from a regular object file or, if the library is not found in the
1143
DT_NEEDED lists of other libraries linked up to that point, an
1144
undefined symbol reference from another dynamic library.
1145
@option{--no-as-needed} restores the default behaviour.
1146
 
1147
@kindex --add-needed
1148
@kindex --no-add-needed
1149
@item --add-needed
1150
@itemx --no-add-needed
1151
These two options have been deprecated because of the similarity of
1152
their names to the @option{--as-needed} and @option{--no-as-needed}
1153
options.  They have been replaced by @option{--copy-dt-needed-entries}
1154
and @option{--no-copy-dt-needed-entries}.
1155
 
1156
@kindex -assert @var{keyword}
1157
@item -assert @var{keyword}
1158
This option is ignored for SunOS compatibility.
1159
 
1160
@kindex -Bdynamic
1161
@kindex -dy
1162
@kindex -call_shared
1163
@item -Bdynamic
1164
@itemx -dy
1165
@itemx -call_shared
1166
Link against dynamic libraries.  This is only meaningful on platforms
1167
for which shared libraries are supported.  This option is normally the
1168
default on such platforms.  The different variants of this option are
1169
for compatibility with various systems.  You may use this option
1170
multiple times on the command line: it affects library searching for
1171
@option{-l} options which follow it.
1172
 
1173
@kindex -Bgroup
1174
@item -Bgroup
1175
Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} entry in the dynamic
1176
section.  This causes the runtime linker to handle lookups in this
1177
object and its dependencies to be performed only inside the group.
1178
@option{--unresolved-symbols=report-all} is implied.  This option is
1179
only meaningful on ELF platforms which support shared libraries.
1180
 
1181
@kindex -Bstatic
1182
@kindex -dn
1183
@kindex -non_shared
1184
@kindex -static
1185
@item -Bstatic
1186
@itemx -dn
1187
@itemx -non_shared
1188
@itemx -static
1189
Do not link against shared libraries.  This is only meaningful on
1190
platforms for which shared libraries are supported.  The different
1191
variants of this option are for compatibility with various systems.  You
1192
may use this option multiple times on the command line: it affects
1193
library searching for @option{-l} options which follow it.  This
1194
option also implies @option{--unresolved-symbols=report-all}.  This
1195
option can be used with @option{-shared}.  Doing so means that a
1196
shared library is being created but that all of the library's external
1197
references must be resolved by pulling in entries from static
1198
libraries.
1199
 
1200
@kindex -Bsymbolic
1201
@item -Bsymbolic
1202
When creating a shared library, bind references to global symbols to the
1203
definition within the shared library, if any.  Normally, it is possible
1204
for a program linked against a shared library to override the definition
1205
within the shared library.  This option is only meaningful on ELF
1206
platforms which support shared libraries.
1207
 
1208
@kindex -Bsymbolic-functions
1209
@item -Bsymbolic-functions
1210
When creating a shared library, bind references to global function
1211
symbols to the definition within the shared library, if any.
1212
This option is only meaningful on ELF platforms which support shared
1213
libraries.
1214
 
1215
@kindex --dynamic-list=@var{dynamic-list-file}
1216
@item --dynamic-list=@var{dynamic-list-file}
1217
Specify the name of a dynamic list file to the linker.  This is
1218
typically used when creating shared libraries to specify a list of
1219
global symbols whose references shouldn't be bound to the definition
1220
within the shared library, or creating dynamically linked executables
1221
to specify a list of symbols which should be added to the symbol table
1222
in the executable.  This option is only meaningful on ELF platforms
1223
which support shared libraries.
1224
 
1225
The format of the dynamic list is the same as the version node without
1226
scope and node name.  See @ref{VERSION} for more information.
1227
 
1228
@kindex --dynamic-list-data
1229
@item --dynamic-list-data
1230
Include all global data symbols to the dynamic list.
1231
 
1232
@kindex --dynamic-list-cpp-new
1233
@item --dynamic-list-cpp-new
1234
Provide the builtin dynamic list for C++ operator new and delete.  It
1235
is mainly useful for building shared libstdc++.
1236
 
1237
@kindex --dynamic-list-cpp-typeinfo
1238
@item --dynamic-list-cpp-typeinfo
1239
Provide the builtin dynamic list for C++ runtime type identification.
1240
 
1241
@kindex --check-sections
1242
@kindex --no-check-sections
1243
@item --check-sections
1244
@itemx --no-check-sections
1245
Asks the linker @emph{not} to check section addresses after they have
1246
been assigned to see if there are any overlaps.  Normally the linker will
1247
perform this check, and if it finds any overlaps it will produce
1248
suitable error messages.  The linker does know about, and does make
1249
allowances for sections in overlays.  The default behaviour can be
1250
restored by using the command line switch @option{--check-sections}.
1251
Section overlap is not usually checked for relocatable links.  You can
1252
force checking in that case by using the @option{--check-sections}
1253
option.
1254
 
1255
@kindex --copy-dt-needed-entries
1256
@kindex --no-copy-dt-needed-entries
1257
@item --copy-dt-needed-entries
1258
@itemx --no-copy-dt-needed-entries
1259
This option affects the treatment of dynamic libraries referred to
1260
by DT_NEEDED tags @emph{inside} ELF dynamic libraries mentioned on the
1261
command line.  Normally the linker will add a DT_NEEDED tag to the
1262
output binary for each library mentioned in a DT_NEEDED tag in an
1263
input dynamic library.  With @option{--no-copy-dt-needed-entries}
1264
specified on the command line however any dynamic libraries that
1265
follow it will have their DT_NEEDED entries ignored.  The default
1266
behaviour can be restored with @option{--copy-dt-needed-entries}.
1267
 
1268
This option also has an effect on the resolution of symbols in dynamic
1269
libraries.  With the default setting dynamic libraries mentioned on
1270
the command line will be recursively searched, following their
1271
DT_NEEDED tags to other libraries, in order to resolve symbols
1272
required by the output binary.  With
1273
@option{--no-copy-dt-needed-entries} specified however the searching
1274
of dynamic libraries that follow it will stop with the dynamic
1275
library itself.  No DT_NEEDED links will be traversed to resolve
1276
symbols.
1277
 
1278
@cindex cross reference table
1279
@kindex --cref
1280
@item --cref
1281
Output a cross reference table.  If a linker map file is being
1282
generated, the cross reference table is printed to the map file.
1283
Otherwise, it is printed on the standard output.
1284
 
1285
The format of the table is intentionally simple, so that it may be
1286
easily processed by a script if necessary.  The symbols are printed out,
1287
sorted by name.  For each symbol, a list of file names is given.  If the
1288
symbol is defined, the first file listed is the location of the
1289
definition.  The remaining files contain references to the symbol.
1290
 
1291
@cindex common allocation
1292
@kindex --no-define-common
1293
@item --no-define-common
1294
This option inhibits the assignment of addresses to common symbols.
1295
The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
1296
@xref{Miscellaneous Commands}.
1297
 
1298
The @samp{--no-define-common} option allows decoupling
1299
the decision to assign addresses to Common symbols from the choice
1300
of the output file type; otherwise a non-Relocatable output type
1301
forces assigning addresses to Common symbols.
1302
Using @samp{--no-define-common} allows Common symbols that are referenced
1303
from a shared library to be assigned addresses only in the main program.
1304
This eliminates the unused duplicate space in the shared library,
1305
and also prevents any possible confusion over resolving to the wrong
1306
duplicate when there are many dynamic modules with specialized search
1307
paths for runtime symbol resolution.
1308
 
1309
@cindex symbols, from command line
1310
@kindex --defsym=@var{symbol}=@var{exp}
1311
@item --defsym=@var{symbol}=@var{expression}
1312
Create a global symbol in the output file, containing the absolute
1313
address given by @var{expression}.  You may use this option as many
1314
times as necessary to define multiple symbols in the command line.  A
1315
limited form of arithmetic is supported for the @var{expression} in this
1316
context: you may give a hexadecimal constant or the name of an existing
1317
symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
1318
constants or symbols.  If you need more elaborate expressions, consider
1319
using the linker command language from a script (@pxref{Assignments,,
1320
Assignment: Symbol Definitions}).  @emph{Note:} there should be no white
1321
space between @var{symbol}, the equals sign (``@key{=}''), and
1322
@var{expression}.
1323
 
1324
@cindex demangling, from command line
1325
@kindex --demangle[=@var{style}]
1326
@kindex --no-demangle
1327
@item --demangle[=@var{style}]
1328
@itemx --no-demangle
1329
These options control whether to demangle symbol names in error messages
1330
and other output.  When the linker is told to demangle, it tries to
1331
present symbol names in a readable fashion: it strips leading
1332
underscores if they are used by the object file format, and converts C++
1333
mangled symbol names into user readable names.  Different compilers have
1334
different mangling styles.  The optional demangling style argument can be used
1335
to choose an appropriate demangling style for your compiler.  The linker will
1336
demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE}
1337
is set.  These options may be used to override the default.
1338
 
1339
@cindex dynamic linker, from command line
1340
@kindex -I@var{file}
1341
@kindex --dynamic-linker=@var{file}
1342
@item -I@var{file}
1343
@itemx --dynamic-linker=@var{file}
1344
Set the name of the dynamic linker.  This is only meaningful when
1345
generating dynamically linked ELF executables.  The default dynamic
1346
linker is normally correct; don't use this unless you know what you are
1347
doing.
1348
 
1349
@kindex --fatal-warnings
1350
@kindex --no-fatal-warnings
1351
@item --fatal-warnings
1352
@itemx --no-fatal-warnings
1353
Treat all warnings as errors.  The default behaviour can be restored
1354
with the option @option{--no-fatal-warnings}.
1355
 
1356
@kindex --force-exe-suffix
1357
@item  --force-exe-suffix
1358
Make sure that an output file has a .exe suffix.
1359
 
1360
If a successfully built fully linked output file does not have a
1361
@code{.exe} or @code{.dll} suffix, this option forces the linker to copy
1362
the output file to one of the same name with a @code{.exe} suffix. This
1363
option is useful when using unmodified Unix makefiles on a Microsoft
1364
Windows host, since some versions of Windows won't run an image unless
1365
it ends in a @code{.exe} suffix.
1366
 
1367
@kindex --gc-sections
1368
@kindex --no-gc-sections
1369
@cindex garbage collection
1370
@item --gc-sections
1371
@itemx --no-gc-sections
1372
Enable garbage collection of unused input sections.  It is ignored on
1373
targets that do not support this option.  The default behaviour (of not
1374
performing this garbage collection) can be restored by specifying
1375
@samp{--no-gc-sections} on the command line.
1376
 
1377
@samp{--gc-sections} decides which input sections are used by
1378
examining symbols and relocations.  The section containing the entry
1379
symbol and all sections containing symbols undefined on the
1380
command-line will be kept, as will sections containing symbols
1381
referenced by dynamic objects.  Note that when building shared
1382
libraries, the linker must assume that any visible symbol is
1383
referenced.  Once this initial set of sections has been determined,
1384
the linker recursively marks as used any section referenced by their
1385
relocations.  See @samp{--entry} and @samp{--undefined}.
1386
 
1387
This option can be set when doing a partial link (enabled with option
1388
@samp{-r}).  In this case the root of symbols kept must be explicitly
1389
specified either by an @samp{--entry} or @samp{--undefined} option or by
1390
a @code{ENTRY} command in the linker script.
1391
 
1392
@kindex --print-gc-sections
1393
@kindex --no-print-gc-sections
1394
@cindex garbage collection
1395
@item --print-gc-sections
1396
@itemx --no-print-gc-sections
1397
List all sections removed by garbage collection.  The listing is
1398
printed on stderr.  This option is only effective if garbage
1399
collection has been enabled via the @samp{--gc-sections}) option.  The
1400
default behaviour (of not listing the sections that are removed) can
1401
be restored by specifying @samp{--no-print-gc-sections} on the command
1402
line.
1403
 
1404
@cindex help
1405
@cindex usage
1406
@kindex --help
1407
@item --help
1408
Print a summary of the command-line options on the standard output and exit.
1409
 
1410
@kindex --target-help
1411
@item --target-help
1412
Print a summary of all target specific options on the standard output and exit.
1413
 
1414
@kindex -Map=@var{mapfile}
1415
@item -Map=@var{mapfile}
1416
Print a link map to the file @var{mapfile}.  See the description of the
1417
@option{-M} option, above.
1418
 
1419
@cindex memory usage
1420
@kindex --no-keep-memory
1421
@item --no-keep-memory
1422
@command{ld} normally optimizes for speed over memory usage by caching the
1423
symbol tables of input files in memory.  This option tells @command{ld} to
1424
instead optimize for memory usage, by rereading the symbol tables as
1425
necessary.  This may be required if @command{ld} runs out of memory space
1426
while linking a large executable.
1427
 
1428
@kindex --no-undefined
1429
@kindex -z defs
1430
@item --no-undefined
1431
@itemx -z defs
1432
Report unresolved symbol references from regular object files.  This
1433
is done even if the linker is creating a non-symbolic shared library.
1434
The switch @option{--[no-]allow-shlib-undefined} controls the
1435
behaviour for reporting unresolved references found in shared
1436
libraries being linked in.
1437
 
1438
@kindex --allow-multiple-definition
1439
@kindex -z muldefs
1440
@item --allow-multiple-definition
1441
@itemx -z muldefs
1442
Normally when a symbol is defined multiple times, the linker will
1443
report a fatal error. These options allow multiple definitions and the
1444
first definition will be used.
1445
 
1446
@kindex --allow-shlib-undefined
1447
@kindex --no-allow-shlib-undefined
1448
@item --allow-shlib-undefined
1449
@itemx --no-allow-shlib-undefined
1450
Allows or disallows undefined symbols in shared libraries.
1451
This switch is similar to @option{--no-undefined} except that it
1452
determines the behaviour when the undefined symbols are in a
1453
shared library rather than a regular object file.  It does not affect
1454
how undefined symbols in regular object files are handled.
1455
 
1456
The default behaviour is to report errors for any undefined symbols
1457
referenced in shared libraries if the linker is being used to create
1458
an executable, but to allow them if the linker is being used to create
1459
a shared library.
1460
 
1461
The reasons for allowing undefined symbol references in shared
1462
libraries specified at link time are that:
1463
 
1464
@itemize @bullet
1465
@item
1466
A shared library specified at link time may not be the same as the one
1467
that is available at load time, so the symbol might actually be
1468
resolvable at load time.
1469
@item
1470
There are some operating systems, eg BeOS and HPPA, where undefined
1471
symbols in shared libraries are normal.
1472
 
1473
The BeOS kernel for example patches shared libraries at load time to
1474
select whichever function is most appropriate for the current
1475
architecture.  This is used, for example, to dynamically select an
1476
appropriate memset function.
1477
@end itemize
1478
 
1479
@kindex --no-undefined-version
1480
@item --no-undefined-version
1481
Normally when a symbol has an undefined version, the linker will ignore
1482
it. This option disallows symbols with undefined version and a fatal error
1483
will be issued instead.
1484
 
1485
@kindex --default-symver
1486
@item --default-symver
1487
Create and use a default symbol version (the soname) for unversioned
1488
exported symbols.
1489
 
1490
@kindex --default-imported-symver
1491
@item --default-imported-symver
1492
Create and use a default symbol version (the soname) for unversioned
1493
imported symbols.
1494
 
1495
@kindex --no-warn-mismatch
1496
@item --no-warn-mismatch
1497
Normally @command{ld} will give an error if you try to link together input
1498
files that are mismatched for some reason, perhaps because they have
1499
been compiled for different processors or for different endiannesses.
1500
This option tells @command{ld} that it should silently permit such possible
1501
errors.  This option should only be used with care, in cases when you
1502
have taken some special action that ensures that the linker errors are
1503
inappropriate.
1504
 
1505
@kindex --no-warn-search-mismatch
1506
@item --no-warn-search-mismatch
1507
Normally @command{ld} will give a warning if it finds an incompatible
1508
library during a library search.  This option silences the warning.
1509
 
1510
@kindex --no-whole-archive
1511
@item --no-whole-archive
1512
Turn off the effect of the @option{--whole-archive} option for subsequent
1513
archive files.
1514
 
1515
@cindex output file after errors
1516
@kindex --noinhibit-exec
1517
@item --noinhibit-exec
1518
Retain the executable output file whenever it is still usable.
1519
Normally, the linker will not produce an output file if it encounters
1520
errors during the link process; it exits without writing an output file
1521
when it issues any error whatsoever.
1522
 
1523
@kindex -nostdlib
1524
@item -nostdlib
1525
Only search library directories explicitly specified on the
1526
command line.  Library directories specified in linker scripts
1527
(including linker scripts specified on the command line) are ignored.
1528
 
1529
@ifclear SingleFormat
1530
@kindex --oformat=@var{output-format}
1531
@item --oformat=@var{output-format}
1532
@command{ld} may be configured to support more than one kind of object
1533
file.  If your @command{ld} is configured this way, you can use the
1534
@samp{--oformat} option to specify the binary format for the output
1535
object file.  Even when @command{ld} is configured to support alternative
1536
object formats, you don't usually need to specify this, as @command{ld}
1537
should be configured to produce as a default output format the most
1538
usual format on each machine.  @var{output-format} is a text string, the
1539
name of a particular format supported by the BFD libraries.  (You can
1540
list the available binary formats with @samp{objdump -i}.)  The script
1541
command @code{OUTPUT_FORMAT} can also specify the output format, but
1542
this option overrides it.  @xref{BFD}.
1543
@end ifclear
1544
 
1545
@kindex -pie
1546
@kindex --pic-executable
1547
@item -pie
1548
@itemx --pic-executable
1549
@cindex position independent executables
1550
Create a position independent executable.  This is currently only supported on
1551
ELF platforms.  Position independent executables are similar to shared
1552
libraries in that they are relocated by the dynamic linker to the virtual
1553
address the OS chooses for them (which can vary between invocations).  Like
1554
normal dynamically linked executables they can be executed and symbols
1555
defined in the executable cannot be overridden by shared libraries.
1556
 
1557
@kindex -qmagic
1558
@item -qmagic
1559
This option is ignored for Linux compatibility.
1560
 
1561
@kindex -Qy
1562
@item -Qy
1563
This option is ignored for SVR4 compatibility.
1564
 
1565
@kindex --relax
1566
@cindex synthesizing linker
1567
@cindex relaxing addressing modes
1568
@cindex --no-relax
1569
@item --relax
1570
@itemx --no-relax
1571
An option with machine dependent effects.
1572
@ifset GENERIC
1573
This option is only supported on a few targets.
1574
@end ifset
1575
@ifset H8300
1576
@xref{H8/300,,@command{ld} and the H8/300}.
1577
@end ifset
1578
@ifset I960
1579
@xref{i960,, @command{ld} and the Intel 960 family}.
1580
@end ifset
1581
@ifset XTENSA
1582
@xref{Xtensa,, @command{ld} and Xtensa Processors}.
1583
@end ifset
1584
@ifset M68HC11
1585
@xref{M68HC11/68HC12,,@command{ld} and the 68HC11 and 68HC12}.
1586
@end ifset
1587
@ifset POWERPC
1588
@xref{PowerPC ELF32,,@command{ld} and PowerPC 32-bit ELF Support}.
1589
@end ifset
1590
 
1591
On some platforms the @samp{--relax} option performs target specific,
1592
global optimizations that become possible when the linker resolves
1593
addressing in the program, such as relaxing address modes,
1594
synthesizing new instructions, selecting shorter version of current
1595
instructions, and combinig constant values.
1596
 
1597
On some platforms these link time global optimizations may make symbolic
1598
debugging of the resulting executable impossible.
1599
@ifset GENERIC
1600
This is known to be the case for the Matsushita MN10200 and MN10300
1601
family of processors.
1602
@end ifset
1603
 
1604
@ifset GENERIC
1605
On platforms where this is not supported, @samp{--relax} is accepted,
1606
but ignored.
1607
@end ifset
1608
 
1609
On platforms where @samp{--relax} is accepted the option
1610
@samp{--no-relax} can be used to disable the feature.
1611
 
1612
@cindex retaining specified symbols
1613
@cindex stripping all but some symbols
1614
@cindex symbols, retaining selectively
1615
@kindex --retain-symbols-file=@var{filename}
1616
@item --retain-symbols-file=@var{filename}
1617
Retain @emph{only} the symbols listed in the file @var{filename},
1618
discarding all others.  @var{filename} is simply a flat file, with one
1619
symbol name per line.  This option is especially useful in environments
1620
@ifset GENERIC
1621
(such as VxWorks)
1622
@end ifset
1623
where a large global symbol table is accumulated gradually, to conserve
1624
run-time memory.
1625
 
1626
@samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
1627
or symbols needed for relocations.
1628
 
1629
You may only specify @samp{--retain-symbols-file} once in the command
1630
line.  It overrides @samp{-s} and @samp{-S}.
1631
 
1632
@ifset GENERIC
1633
@item -rpath=@var{dir}
1634
@cindex runtime library search path
1635
@kindex -rpath=@var{dir}
1636
Add a directory to the runtime library search path.  This is used when
1637
linking an ELF executable with shared objects.  All @option{-rpath}
1638
arguments are concatenated and passed to the runtime linker, which uses
1639
them to locate shared objects at runtime.  The @option{-rpath} option is
1640
also used when locating shared objects which are needed by shared
1641
objects explicitly included in the link; see the description of the
1642
@option{-rpath-link} option.  If @option{-rpath} is not used when linking an
1643
ELF executable, the contents of the environment variable
1644
@code{LD_RUN_PATH} will be used if it is defined.
1645
 
1646
The @option{-rpath} option may also be used on SunOS.  By default, on
1647
SunOS, the linker will form a runtime search patch out of all the
1648
@option{-L} options it is given.  If a @option{-rpath} option is used, the
1649
runtime search path will be formed exclusively using the @option{-rpath}
1650
options, ignoring the @option{-L} options.  This can be useful when using
1651
gcc, which adds many @option{-L} options which may be on NFS mounted
1652
file systems.
1653
 
1654
For compatibility with other ELF linkers, if the @option{-R} option is
1655
followed by a directory name, rather than a file name, it is treated as
1656
the @option{-rpath} option.
1657
@end ifset
1658
 
1659
@ifset GENERIC
1660
@cindex link-time runtime library search path
1661
@kindex -rpath-link=@var{dir}
1662
@item -rpath-link=@var{dir}
1663
When using ELF or SunOS, one shared library may require another.  This
1664
happens when an @code{ld -shared} link includes a shared library as one
1665
of the input files.
1666
 
1667
When the linker encounters such a dependency when doing a non-shared,
1668
non-relocatable link, it will automatically try to locate the required
1669
shared library and include it in the link, if it is not included
1670
explicitly.  In such a case, the @option{-rpath-link} option
1671
specifies the first set of directories to search.  The
1672
@option{-rpath-link} option may specify a sequence of directory names
1673
either by specifying a list of names separated by colons, or by
1674
appearing multiple times.
1675
 
1676
This option should be used with caution as it overrides the search path
1677
that may have been hard compiled into a shared library. In such a case it
1678
is possible to use unintentionally a different search path than the
1679
runtime linker would do.
1680
 
1681
The linker uses the following search paths to locate required shared
1682
libraries:
1683
@enumerate
1684
@item
1685
Any directories specified by @option{-rpath-link} options.
1686
@item
1687
Any directories specified by @option{-rpath} options.  The difference
1688
between @option{-rpath} and @option{-rpath-link} is that directories
1689
specified by @option{-rpath} options are included in the executable and
1690
used at runtime, whereas the @option{-rpath-link} option is only effective
1691
at link time. Searching @option{-rpath} in this way is only supported
1692
by native linkers and cross linkers which have been configured with
1693
the @option{--with-sysroot} option.
1694
@item
1695
On an ELF system, for native linkers, if the @option{-rpath} and
1696
@option{-rpath-link} options were not used, search the contents of the
1697
environment variable @code{LD_RUN_PATH}.
1698
@item
1699
On SunOS, if the @option{-rpath} option was not used, search any
1700
directories specified using @option{-L} options.
1701
@item
1702
For a native linker, the search the contents of the environment
1703
variable @code{LD_LIBRARY_PATH}.
1704
@item
1705
For a native ELF linker, the directories in @code{DT_RUNPATH} or
1706
@code{DT_RPATH} of a shared library are searched for shared
1707
libraries needed by it. The @code{DT_RPATH} entries are ignored if
1708
@code{DT_RUNPATH} entries exist.
1709
@item
1710
The default directories, normally @file{/lib} and @file{/usr/lib}.
1711
@item
1712
For a native linker on an ELF system, if the file @file{/etc/ld.so.conf}
1713
exists, the list of directories found in that file.
1714
@end enumerate
1715
 
1716
If the required shared library is not found, the linker will issue a
1717
warning and continue with the link.
1718
@end ifset
1719
 
1720
@kindex -shared
1721
@kindex -Bshareable
1722
@item -shared
1723
@itemx -Bshareable
1724
@cindex shared libraries
1725
Create a shared library.  This is currently only supported on ELF, XCOFF
1726
and SunOS platforms.  On SunOS, the linker will automatically create a
1727
shared library if the @option{-e} option is not used and there are
1728
undefined symbols in the link.
1729
 
1730
@kindex --sort-common
1731
@item --sort-common
1732
@itemx --sort-common=ascending
1733
@itemx --sort-common=descending
1734
This option tells @command{ld} to sort the common symbols by alignment in
1735
ascending or descending order when it places them in the appropriate output
1736
sections.  The symbol alignments considered are sixteen-byte or larger,
1737
eight-byte, four-byte, two-byte, and one-byte. This is to prevent gaps
1738
between symbols due to alignment constraints.  If no sorting order is
1739
specified, then descending order is assumed.
1740
 
1741
@kindex --sort-section=name
1742
@item --sort-section=name
1743
This option will apply @code{SORT_BY_NAME} to all wildcard section
1744
patterns in the linker script.
1745
 
1746
@kindex --sort-section=alignment
1747
@item --sort-section=alignment
1748
This option will apply @code{SORT_BY_ALIGNMENT} to all wildcard section
1749
patterns in the linker script.
1750
 
1751
@kindex --split-by-file
1752
@item --split-by-file[=@var{size}]
1753
Similar to @option{--split-by-reloc} but creates a new output section for
1754
each input file when @var{size} is reached.  @var{size} defaults to a
1755
size of 1 if not given.
1756
 
1757
@kindex --split-by-reloc
1758
@item --split-by-reloc[=@var{count}]
1759
Tries to creates extra sections in the output file so that no single
1760
output section in the file contains more than @var{count} relocations.
1761
This is useful when generating huge relocatable files for downloading into
1762
certain real time kernels with the COFF object file format; since COFF
1763
cannot represent more than 65535 relocations in a single section.  Note
1764
that this will fail to work with object file formats which do not
1765
support arbitrary sections.  The linker will not split up individual
1766
input sections for redistribution, so if a single input section contains
1767
more than @var{count} relocations one output section will contain that
1768
many relocations.  @var{count} defaults to a value of 32768.
1769
 
1770
@kindex --stats
1771
@item --stats
1772
Compute and display statistics about the operation of the linker, such
1773
as execution time and memory usage.
1774
 
1775
@kindex --sysroot=@var{directory}
1776
@item --sysroot=@var{directory}
1777
Use @var{directory} as the location of the sysroot, overriding the
1778
configure-time default.  This option is only supported by linkers
1779
that were configured using @option{--with-sysroot}.
1780
 
1781
@kindex --traditional-format
1782
@cindex traditional format
1783
@item --traditional-format
1784
For some targets, the output of @command{ld} is different in some ways from
1785
the output of some existing linker.  This switch requests @command{ld} to
1786
use the traditional format instead.
1787
 
1788
@cindex dbx
1789
For example, on SunOS, @command{ld} combines duplicate entries in the
1790
symbol string table.  This can reduce the size of an output file with
1791
full debugging information by over 30 percent.  Unfortunately, the SunOS
1792
@code{dbx} program can not read the resulting program (@code{gdb} has no
1793
trouble).  The @samp{--traditional-format} switch tells @command{ld} to not
1794
combine duplicate entries.
1795
 
1796
@kindex --section-start=@var{sectionname}=@var{org}
1797
@item --section-start=@var{sectionname}=@var{org}
1798
Locate a section in the output file at the absolute
1799
address given by @var{org}.  You may use this option as many
1800
times as necessary to locate multiple sections in the command
1801
line.
1802
@var{org} must be a single hexadecimal integer;
1803
for compatibility with other linkers, you may omit the leading
1804
@samp{0x} usually associated with hexadecimal values.  @emph{Note:} there
1805
should be no white space between @var{sectionname}, the equals
1806
sign (``@key{=}''), and @var{org}.
1807
 
1808
@kindex -Tbss=@var{org}
1809
@kindex -Tdata=@var{org}
1810
@kindex -Ttext=@var{org}
1811
@cindex segment origins, cmd line
1812
@item -Tbss=@var{org}
1813
@itemx -Tdata=@var{org}
1814
@itemx -Ttext=@var{org}
1815
Same as @option{--section-start}, with @code{.bss}, @code{.data} or
1816
@code{.text} as the @var{sectionname}.
1817
 
1818
@kindex -Ttext-segment=@var{org}
1819
@item -Ttext-segment=@var{org}
1820
@cindex text segment origin, cmd line
1821
When creating an ELF executable or shared object, it will set the address
1822
of the first byte of the text segment.
1823
 
1824
@kindex --unresolved-symbols
1825
@item --unresolved-symbols=@var{method}
1826
Determine how to handle unresolved symbols.  There are four possible
1827
values for @samp{method}:
1828
 
1829
@table @samp
1830
@item ignore-all
1831
Do not report any unresolved symbols.
1832
 
1833
@item report-all
1834
Report all unresolved symbols.  This is the default.
1835
 
1836
@item ignore-in-object-files
1837
Report unresolved symbols that are contained in shared libraries, but
1838
ignore them if they come from regular object files.
1839
 
1840
@item ignore-in-shared-libs
1841
Report unresolved symbols that come from regular object files, but
1842
ignore them if they come from shared libraries.  This can be useful
1843
when creating a dynamic binary and it is known that all the shared
1844
libraries that it should be referencing are included on the linker's
1845
command line.
1846
@end table
1847
 
1848
The behaviour for shared libraries on their own can also be controlled
1849
by the @option{--[no-]allow-shlib-undefined} option.
1850
 
1851
Normally the linker will generate an error message for each reported
1852
unresolved symbol but the option @option{--warn-unresolved-symbols}
1853
can change this to a warning.
1854
 
1855
@kindex --verbose[=@var{NUMBER}]
1856
@cindex verbose[=@var{NUMBER}]
1857
@item --dll-verbose
1858
@itemx --verbose[=@var{NUMBER}]
1859
Display the version number for @command{ld} and list the linker emulations
1860
supported.  Display which input files can and cannot be opened.  Display
1861
the linker script being used by the linker. If the optional @var{NUMBER}
1862
argument > 1, plugin symbol status will also be displayed.
1863
 
1864
@kindex --version-script=@var{version-scriptfile}
1865
@cindex version script, symbol versions
1866
@item --version-script=@var{version-scriptfile}
1867
Specify the name of a version script to the linker.  This is typically
1868
used when creating shared libraries to specify additional information
1869
about the version hierarchy for the library being created.  This option
1870
is only fully supported on ELF platforms which support shared libraries;
1871
see @ref{VERSION}.  It is partially supported on PE platforms, which can
1872
use version scripts to filter symbol visibility in auto-export mode: any
1873
symbols marked @samp{local} in the version script will not be exported.
1874
@xref{WIN32}.
1875
 
1876
@kindex --warn-common
1877
@cindex warnings, on combining symbols
1878
@cindex combining symbols, warnings on
1879
@item --warn-common
1880
Warn when a common symbol is combined with another common symbol or with
1881
a symbol definition.  Unix linkers allow this somewhat sloppy practise,
1882
but linkers on some other operating systems do not.  This option allows
1883
you to find potential problems from combining global symbols.
1884
Unfortunately, some C libraries use this practise, so you may get some
1885
warnings about symbols in the libraries as well as in your programs.
1886
 
1887
There are three kinds of global symbols, illustrated here by C examples:
1888
 
1889
@table @samp
1890
@item int i = 1;
1891
A definition, which goes in the initialized data section of the output
1892
file.
1893
 
1894
@item extern int i;
1895
An undefined reference, which does not allocate space.
1896
There must be either a definition or a common symbol for the
1897
variable somewhere.
1898
 
1899
@item int i;
1900
A common symbol.  If there are only (one or more) common symbols for a
1901
variable, it goes in the uninitialized data area of the output file.
1902
The linker merges multiple common symbols for the same variable into a
1903
single symbol.  If they are of different sizes, it picks the largest
1904
size.  The linker turns a common symbol into a declaration, if there is
1905
a definition of the same variable.
1906
@end table
1907
 
1908
The @samp{--warn-common} option can produce five kinds of warnings.
1909
Each warning consists of a pair of lines: the first describes the symbol
1910
just encountered, and the second describes the previous symbol
1911
encountered with the same name.  One or both of the two symbols will be
1912
a common symbol.
1913
 
1914
@enumerate
1915
@item
1916
Turning a common symbol into a reference, because there is already a
1917
definition for the symbol.
1918
@smallexample
1919
@var{file}(@var{section}): warning: common of `@var{symbol}'
1920
   overridden by definition
1921
@var{file}(@var{section}): warning: defined here
1922
@end smallexample
1923
 
1924
@item
1925
Turning a common symbol into a reference, because a later definition for
1926
the symbol is encountered.  This is the same as the previous case,
1927
except that the symbols are encountered in a different order.
1928
@smallexample
1929
@var{file}(@var{section}): warning: definition of `@var{symbol}'
1930
   overriding common
1931
@var{file}(@var{section}): warning: common is here
1932
@end smallexample
1933
 
1934
@item
1935
Merging a common symbol with a previous same-sized common symbol.
1936
@smallexample
1937
@var{file}(@var{section}): warning: multiple common
1938
   of `@var{symbol}'
1939
@var{file}(@var{section}): warning: previous common is here
1940
@end smallexample
1941
 
1942
@item
1943
Merging a common symbol with a previous larger common symbol.
1944
@smallexample
1945
@var{file}(@var{section}): warning: common of `@var{symbol}'
1946
   overridden by larger common
1947
@var{file}(@var{section}): warning: larger common is here
1948
@end smallexample
1949
 
1950
@item
1951
Merging a common symbol with a previous smaller common symbol.  This is
1952
the same as the previous case, except that the symbols are
1953
encountered in a different order.
1954
@smallexample
1955
@var{file}(@var{section}): warning: common of `@var{symbol}'
1956
   overriding smaller common
1957
@var{file}(@var{section}): warning: smaller common is here
1958
@end smallexample
1959
@end enumerate
1960
 
1961
@kindex --warn-constructors
1962
@item --warn-constructors
1963
Warn if any global constructors are used.  This is only useful for a few
1964
object file formats.  For formats like COFF or ELF, the linker can not
1965
detect the use of global constructors.
1966
 
1967
@kindex --warn-multiple-gp
1968
@item --warn-multiple-gp
1969
Warn if multiple global pointer values are required in the output file.
1970
This is only meaningful for certain processors, such as the Alpha.
1971
Specifically, some processors put large-valued constants in a special
1972
section.  A special register (the global pointer) points into the middle
1973
of this section, so that constants can be loaded efficiently via a
1974
base-register relative addressing mode.  Since the offset in
1975
base-register relative mode is fixed and relatively small (e.g., 16
1976
bits), this limits the maximum size of the constant pool.  Thus, in
1977
large programs, it is often necessary to use multiple global pointer
1978
values in order to be able to address all possible constants.  This
1979
option causes a warning to be issued whenever this case occurs.
1980
 
1981
@kindex --warn-once
1982
@cindex warnings, on undefined symbols
1983
@cindex undefined symbols, warnings on
1984
@item --warn-once
1985
Only warn once for each undefined symbol, rather than once per module
1986
which refers to it.
1987
 
1988
@kindex --warn-section-align
1989
@cindex warnings, on section alignment
1990
@cindex section alignment, warnings on
1991
@item --warn-section-align
1992
Warn if the address of an output section is changed because of
1993
alignment.  Typically, the alignment will be set by an input section.
1994
The address will only be changed if it not explicitly specified; that
1995
is, if the @code{SECTIONS} command does not specify a start address for
1996
the section (@pxref{SECTIONS}).
1997
 
1998
@kindex --warn-shared-textrel
1999
@item --warn-shared-textrel
2000
Warn if the linker adds a DT_TEXTREL to a shared object.
2001
 
2002
@kindex --warn-alternate-em
2003
@item --warn-alternate-em
2004
Warn if an object has alternate ELF machine code.
2005
 
2006
@kindex --warn-unresolved-symbols
2007
@item --warn-unresolved-symbols
2008
If the linker is going to report an unresolved symbol (see the option
2009
@option{--unresolved-symbols}) it will normally generate an error.
2010
This option makes it generate a warning instead.
2011
 
2012
@kindex --error-unresolved-symbols
2013
@item --error-unresolved-symbols
2014
This restores the linker's default behaviour of generating errors when
2015
it is reporting unresolved symbols.
2016
 
2017
@kindex --whole-archive
2018
@cindex including an entire archive
2019
@item --whole-archive
2020
For each archive mentioned on the command line after the
2021
@option{--whole-archive} option, include every object file in the archive
2022
in the link, rather than searching the archive for the required object
2023
files.  This is normally used to turn an archive file into a shared
2024
library, forcing every object to be included in the resulting shared
2025
library.  This option may be used more than once.
2026
 
2027
Two notes when using this option from gcc: First, gcc doesn't know
2028
about this option, so you have to use @option{-Wl,-whole-archive}.
2029
Second, don't forget to use @option{-Wl,-no-whole-archive} after your
2030
list of archives, because gcc will add its own list of archives to
2031
your link and you may not want this flag to affect those as well.
2032
 
2033
@kindex --wrap=@var{symbol}
2034
@item --wrap=@var{symbol}
2035
Use a wrapper function for @var{symbol}.  Any undefined reference to
2036
@var{symbol} will be resolved to @code{__wrap_@var{symbol}}.  Any
2037
undefined reference to @code{__real_@var{symbol}} will be resolved to
2038
@var{symbol}.
2039
 
2040
This can be used to provide a wrapper for a system function.  The
2041
wrapper function should be called @code{__wrap_@var{symbol}}.  If it
2042
wishes to call the system function, it should call
2043
@code{__real_@var{symbol}}.
2044
 
2045
Here is a trivial example:
2046
 
2047
@smallexample
2048
void *
2049
__wrap_malloc (size_t c)
2050
@{
2051
  printf ("malloc called with %zu\n", c);
2052
  return __real_malloc (c);
2053
@}
2054
@end smallexample
2055
 
2056
If you link other code with this file using @option{--wrap malloc}, then
2057
all calls to @code{malloc} will call the function @code{__wrap_malloc}
2058
instead.  The call to @code{__real_malloc} in @code{__wrap_malloc} will
2059
call the real @code{malloc} function.
2060
 
2061
You may wish to provide a @code{__real_malloc} function as well, so that
2062
links without the @option{--wrap} option will succeed.  If you do this,
2063
you should not put the definition of @code{__real_malloc} in the same
2064
file as @code{__wrap_malloc}; if you do, the assembler may resolve the
2065
call before the linker has a chance to wrap it to @code{malloc}.
2066
 
2067
@kindex --eh-frame-hdr
2068
@item --eh-frame-hdr
2069
Request creation of @code{.eh_frame_hdr} section and ELF
2070
@code{PT_GNU_EH_FRAME} segment header.
2071
 
2072
@kindex --enable-new-dtags
2073
@kindex --disable-new-dtags
2074
@item --enable-new-dtags
2075
@itemx --disable-new-dtags
2076
This linker can create the new dynamic tags in ELF. But the older ELF
2077
systems may not understand them. If you specify
2078
@option{--enable-new-dtags}, the dynamic tags will be created as needed.
2079
If you specify @option{--disable-new-dtags}, no new dynamic tags will be
2080
created. By default, the new dynamic tags are not created. Note that
2081
those options are only available for ELF systems.
2082
 
2083
@kindex --hash-size=@var{number}
2084
@item --hash-size=@var{number}
2085
Set the default size of the linker's hash tables to a prime number
2086
close to @var{number}.  Increasing this value can reduce the length of
2087
time it takes the linker to perform its tasks, at the expense of
2088
increasing the linker's memory requirements.  Similarly reducing this
2089
value can reduce the memory requirements at the expense of speed.
2090
 
2091
@kindex --hash-style=@var{style}
2092
@item --hash-style=@var{style}
2093
Set the type of linker's hash table(s).  @var{style} can be either
2094
@code{sysv} for classic ELF @code{.hash} section, @code{gnu} for
2095
new style GNU @code{.gnu.hash} section or @code{both} for both
2096
the classic ELF @code{.hash} and new style GNU @code{.gnu.hash}
2097
hash tables.  The default is @code{sysv}.
2098
 
2099
@kindex --reduce-memory-overheads
2100
@item --reduce-memory-overheads
2101
This option reduces memory requirements at ld runtime, at the expense of
2102
linking speed.  This was introduced to select the old O(n^2) algorithm
2103
for link map file generation, rather than the new O(n) algorithm which uses
2104
about 40% more memory for symbol storage.
2105
 
2106
Another effect of the switch is to set the default hash table size to
2107
1021, which again saves memory at the cost of lengthening the linker's
2108
run time.  This is not done however if the @option{--hash-size} switch
2109
has been used.
2110
 
2111
The @option{--reduce-memory-overheads} switch may be also be used to
2112
enable other tradeoffs in future versions of the linker.
2113
 
2114
@kindex --build-id
2115
@kindex --build-id=@var{style}
2116
@item --build-id
2117
@itemx --build-id=@var{style}
2118
Request creation of @code{.note.gnu.build-id} ELF note section.
2119
The contents of the note are unique bits identifying this linked
2120
file.  @var{style} can be @code{uuid} to use 128 random bits,
2121
@code{sha1} to use a 160-bit @sc{SHA1} hash on the normative
2122
parts of the output contents, @code{md5} to use a 128-bit
2123
@sc{MD5} hash on the normative parts of the output contents, or
2124
@code{0x@var{hexstring}} to use a chosen bit string specified as
2125
an even number of hexadecimal digits (@code{-} and @code{:}
2126
characters between digit pairs are ignored).  If @var{style} is
2127
omitted, @code{sha1} is used.
2128
 
2129
The @code{md5} and @code{sha1} styles produces an identifier
2130
that is always the same in an identical output file, but will be
2131
unique among all nonidentical output files.  It is not intended
2132
to be compared as a checksum for the file's contents.  A linked
2133
file may be changed later by other tools, but the build ID bit
2134
string identifying the original linked file does not change.
2135
 
2136
Passing @code{none} for @var{style} disables the setting from any
2137
@code{--build-id} options earlier on the command line.
2138
@end table
2139
 
2140
@c man end
2141
 
2142
@subsection Options Specific to i386 PE Targets
2143
 
2144
@c man begin OPTIONS
2145
 
2146
The i386 PE linker supports the @option{-shared} option, which causes
2147
the output to be a dynamically linked library (DLL) instead of a
2148
normal executable.  You should name the output @code{*.dll} when you
2149
use this option.  In addition, the linker fully supports the standard
2150
@code{*.def} files, which may be specified on the linker command line
2151
like an object file (in fact, it should precede archives it exports
2152
symbols from, to ensure that they get linked in, just like a normal
2153
object file).
2154
 
2155
In addition to the options common to all targets, the i386 PE linker
2156
support additional command line options that are specific to the i386
2157
PE target.  Options that take values may be separated from their
2158
values by either a space or an equals sign.
2159
 
2160
@table @gcctabopt
2161
 
2162
@kindex --add-stdcall-alias
2163
@item --add-stdcall-alias
2164
If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
2165
as-is and also with the suffix stripped.
2166
[This option is specific to the i386 PE targeted port of the linker]
2167
 
2168
@kindex --base-file
2169
@item --base-file @var{file}
2170
Use @var{file} as the name of a file in which to save the base
2171
addresses of all the relocations needed for generating DLLs with
2172
@file{dlltool}.
2173
[This is an i386 PE specific option]
2174
 
2175
@kindex --dll
2176
@item --dll
2177
Create a DLL instead of a regular executable.  You may also use
2178
@option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
2179
file.
2180
[This option is specific to the i386 PE targeted port of the linker]
2181
 
2182
@kindex --enable-long-section-names
2183
@kindex --disable-long-section-names
2184
@item --enable-long-section-names
2185
@itemx --disable-long-section-names
2186
The PE variants of the Coff object format add an extension that permits
2187
the use of section names longer than eight characters, the normal limit
2188
for Coff.  By default, these names are only allowed in object files, as
2189
fully-linked executable images do not carry the Coff string table required
2190
to support the longer names.  As a GNU extension, it is possible to
2191
allow their use in executable images as well, or to (probably pointlessly!)
2192
disallow it in object files, by using these two options.  Executable images
2193
generated with these long section names are slightly non-standard, carrying
2194
as they do a string table, and may generate confusing output when examined
2195
with non-GNU PE-aware tools, such as file viewers and dumpers.  However,
2196
GDB relies on the use of PE long section names to find Dwarf-2 debug
2197
information sections in an executable image at runtime, and so if neither
2198
option is specified on the command-line, @command{ld} will enable long
2199
section names, overriding the default and technically correct behaviour,
2200
when it finds the presence of debug information while linking an executable
2201
image and not stripping symbols.
2202
[This option is valid for all PE targeted ports of the linker]
2203
 
2204
@kindex --enable-stdcall-fixup
2205
@kindex --disable-stdcall-fixup
2206
@item --enable-stdcall-fixup
2207
@itemx --disable-stdcall-fixup
2208
If the link finds a symbol that it cannot resolve, it will attempt to
2209
do ``fuzzy linking'' by looking for another defined symbol that differs
2210
only in the format of the symbol name (cdecl vs stdcall) and will
2211
resolve that symbol by linking to the match.  For example, the
2212
undefined symbol @code{_foo} might be linked to the function
2213
@code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
2214
to the function @code{_bar}.  When the linker does this, it prints a
2215
warning, since it normally should have failed to link, but sometimes
2216
import libraries generated from third-party dlls may need this feature
2217
to be usable.  If you specify @option{--enable-stdcall-fixup}, this
2218
feature is fully enabled and warnings are not printed.  If you specify
2219
@option{--disable-stdcall-fixup}, this feature is disabled and such
2220
mismatches are considered to be errors.
2221
[This option is specific to the i386 PE targeted port of the linker]
2222
 
2223
@kindex --leading-underscore
2224
@kindex --no-leading-underscore
2225
@item --leading-underscore
2226
@itemx --no-leading-underscore
2227
For most targets default symbol-prefix is an underscore and is defined
2228
in target's description. By this option it is possible to
2229
disable/enable the default underscore symbol-prefix.
2230
 
2231
@cindex DLLs, creating
2232
@kindex --export-all-symbols
2233
@item --export-all-symbols
2234
If given, all global symbols in the objects used to build a DLL will
2235
be exported by the DLL.  Note that this is the default if there
2236
otherwise wouldn't be any exported symbols.  When symbols are
2237
explicitly exported via DEF files or implicitly exported via function
2238
attributes, the default is to not export anything else unless this
2239
option is given.  Note that the symbols @code{DllMain@@12},
2240
@code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and
2241
@code{impure_ptr} will not be automatically
2242
exported.  Also, symbols imported from other DLLs will not be
2243
re-exported, nor will symbols specifying the DLL's internal layout
2244
such as those beginning with @code{_head_} or ending with
2245
@code{_iname}.  In addition, no symbols from @code{libgcc},
2246
@code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
2247
Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
2248
not be exported, to help with C++ DLLs.  Finally, there is an
2249
extensive list of cygwin-private symbols that are not exported
2250
(obviously, this applies on when building DLLs for cygwin targets).
2251
These cygwin-excludes are: @code{_cygwin_dll_entry@@12},
2252
@code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
2253
@code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll},
2254
@code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
2255
@code{cygwin_premain3}, and @code{environ}.
2256
[This option is specific to the i386 PE targeted port of the linker]
2257
 
2258
@kindex --exclude-symbols
2259
@item --exclude-symbols @var{symbol},@var{symbol},...
2260
Specifies a list of symbols which should not be automatically
2261
exported.  The symbol names may be delimited by commas or colons.
2262
[This option is specific to the i386 PE targeted port of the linker]
2263
 
2264
@kindex --exclude-all-symbols
2265
@item --exclude-all-symbols
2266
Specifies no symbols should be automatically exported.
2267
[This option is specific to the i386 PE targeted port of the linker]
2268
 
2269
@kindex --file-alignment
2270
@item --file-alignment
2271
Specify the file alignment.  Sections in the file will always begin at
2272
file offsets which are multiples of this number.  This defaults to
2273
512.
2274
[This option is specific to the i386 PE targeted port of the linker]
2275
 
2276
@cindex heap size
2277
@kindex --heap
2278
@item --heap @var{reserve}
2279
@itemx --heap @var{reserve},@var{commit}
2280
Specify the number of bytes of memory to reserve (and optionally commit)
2281
to be used as heap for this program.  The default is 1Mb reserved, 4K
2282
committed.
2283
[This option is specific to the i386 PE targeted port of the linker]
2284
 
2285
@cindex image base
2286
@kindex --image-base
2287
@item --image-base @var{value}
2288
Use @var{value} as the base address of your program or dll.  This is
2289
the lowest memory location that will be used when your program or dll
2290
is loaded.  To reduce the need to relocate and improve performance of
2291
your dlls, each should have a unique base address and not overlap any
2292
other dlls.  The default is 0x400000 for executables, and 0x10000000
2293
for dlls.
2294
[This option is specific to the i386 PE targeted port of the linker]
2295
 
2296
@kindex --kill-at
2297
@item --kill-at
2298
If given, the stdcall suffixes (@@@var{nn}) will be stripped from
2299
symbols before they are exported.
2300
[This option is specific to the i386 PE targeted port of the linker]
2301
 
2302
@kindex --large-address-aware
2303
@item --large-address-aware
2304
If given, the appropriate bit in the ``Characteristics'' field of the COFF
2305
header is set to indicate that this executable supports virtual addresses
2306
greater than 2 gigabytes.  This should be used in conjunction with the /3GB
2307
or /USERVA=@var{value} megabytes switch in the ``[operating systems]''
2308
section of the BOOT.INI.  Otherwise, this bit has no effect.
2309
[This option is specific to PE targeted ports of the linker]
2310
 
2311
@kindex --major-image-version
2312
@item --major-image-version @var{value}
2313
Sets the major number of the ``image version''.  Defaults to 1.
2314
[This option is specific to the i386 PE targeted port of the linker]
2315
 
2316
@kindex --major-os-version
2317
@item --major-os-version @var{value}
2318
Sets the major number of the ``os version''.  Defaults to 4.
2319
[This option is specific to the i386 PE targeted port of the linker]
2320
 
2321
@kindex --major-subsystem-version
2322
@item --major-subsystem-version @var{value}
2323
Sets the major number of the ``subsystem version''.  Defaults to 4.
2324
[This option is specific to the i386 PE targeted port of the linker]
2325
 
2326
@kindex --minor-image-version
2327
@item --minor-image-version @var{value}
2328
Sets the minor number of the ``image version''.  Defaults to 0.
2329
[This option is specific to the i386 PE targeted port of the linker]
2330
 
2331
@kindex --minor-os-version
2332
@item --minor-os-version @var{value}
2333
Sets the minor number of the ``os version''.  Defaults to 0.
2334
[This option is specific to the i386 PE targeted port of the linker]
2335
 
2336
@kindex --minor-subsystem-version
2337
@item --minor-subsystem-version @var{value}
2338
Sets the minor number of the ``subsystem version''.  Defaults to 0.
2339
[This option is specific to the i386 PE targeted port of the linker]
2340
 
2341
@cindex DEF files, creating
2342
@cindex DLLs, creating
2343
@kindex --output-def
2344
@item --output-def @var{file}
2345
The linker will create the file @var{file} which will contain a DEF
2346
file corresponding to the DLL the linker is generating.  This DEF file
2347
(which should be called @code{*.def}) may be used to create an import
2348
library with @code{dlltool} or may be used as a reference to
2349
automatically or implicitly exported symbols.
2350
[This option is specific to the i386 PE targeted port of the linker]
2351
 
2352
@cindex DLLs, creating
2353
@kindex --out-implib
2354
@item --out-implib @var{file}
2355
The linker will create the file @var{file} which will contain an
2356
import lib corresponding to the DLL the linker is generating. This
2357
import lib (which should be called @code{*.dll.a} or @code{*.a}
2358
may be used to link clients against the generated DLL; this behaviour
2359
makes it possible to skip a separate @code{dlltool} import library
2360
creation step.
2361
[This option is specific to the i386 PE targeted port of the linker]
2362
 
2363
@kindex --enable-auto-image-base
2364
@item --enable-auto-image-base
2365
Automatically choose the image base for DLLs, unless one is specified
2366
using the @code{--image-base} argument.  By using a hash generated
2367
from the dllname to create unique image bases for each DLL, in-memory
2368
collisions and relocations which can delay program execution are
2369
avoided.
2370
[This option is specific to the i386 PE targeted port of the linker]
2371
 
2372
@kindex --disable-auto-image-base
2373
@item --disable-auto-image-base
2374
Do not automatically generate a unique image base.  If there is no
2375
user-specified image base (@code{--image-base}) then use the platform
2376
default.
2377
[This option is specific to the i386 PE targeted port of the linker]
2378
 
2379
@cindex DLLs, linking to
2380
@kindex --dll-search-prefix
2381
@item --dll-search-prefix @var{string}
2382
When linking dynamically to a dll without an import library,
2383
search for @code{<string><basename>.dll} in preference to
2384
@code{lib<basename>.dll}. This behaviour allows easy distinction
2385
between DLLs built for the various "subplatforms": native, cygwin,
2386
uwin, pw, etc.  For instance, cygwin DLLs typically use
2387
@code{--dll-search-prefix=cyg}.
2388
[This option is specific to the i386 PE targeted port of the linker]
2389
 
2390
@kindex --enable-auto-import
2391
@item --enable-auto-import
2392
Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for
2393
DATA imports from DLLs, and create the necessary thunking symbols when
2394
building the import libraries with those DATA exports. Note: Use of the
2395
'auto-import' extension will cause the text section of the image file
2396
to be made writable. This does not conform to the PE-COFF format
2397
specification published by Microsoft.
2398
 
2399
Note - use of the 'auto-import' extension will also cause read only
2400
data which would normally be placed into the .rdata section to be
2401
placed into the .data section instead.  This is in order to work
2402
around a problem with consts that is described here:
2403
http://www.cygwin.com/ml/cygwin/2004-09/msg01101.html
2404
 
2405
Using 'auto-import' generally will 'just work' -- but sometimes you may
2406
see this message:
2407
 
2408
"variable '<var>' can't be auto-imported. Please read the
2409
documentation for ld's @code{--enable-auto-import} for details."
2410
 
2411
This message occurs when some (sub)expression accesses an address
2412
ultimately given by the sum of two constants (Win32 import tables only
2413
allow one).  Instances where this may occur include accesses to member
2414
fields of struct variables imported from a DLL, as well as using a
2415
constant index into an array variable imported from a DLL.  Any
2416
multiword variable (arrays, structs, long long, etc) may trigger
2417
this error condition.  However, regardless of the exact data type
2418
of the offending exported variable, ld will always detect it, issue
2419
the warning, and exit.
2420
 
2421
There are several ways to address this difficulty, regardless of the
2422
data type of the exported variable:
2423
 
2424
One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
2425
of adjusting references in your client code for runtime environment, so
2426
this method works only when runtime environment supports this feature.
2427
 
2428
A second solution is to force one of the 'constants' to be a variable --
2429
that is, unknown and un-optimizable at compile time.  For arrays,
2430
there are two possibilities: a) make the indexee (the array's address)
2431
a variable, or b) make the 'constant' index a variable.  Thus:
2432
 
2433
@example
2434
extern type extern_array[];
2435
extern_array[1] -->
2436
   @{ volatile type *t=extern_array; t[1] @}
2437
@end example
2438
 
2439
or
2440
 
2441
@example
2442
extern type extern_array[];
2443
extern_array[1] -->
2444
   @{ volatile int t=1; extern_array[t] @}
2445
@end example
2446
 
2447
For structs (and most other multiword data types) the only option
2448
is to make the struct itself (or the long long, or the ...) variable:
2449
 
2450
@example
2451
extern struct s extern_struct;
2452
extern_struct.field -->
2453
   @{ volatile struct s *t=&extern_struct; t->field @}
2454
@end example
2455
 
2456
or
2457
 
2458
@example
2459
extern long long extern_ll;
2460
extern_ll -->
2461
  @{ volatile long long * local_ll=&extern_ll; *local_ll @}
2462
@end example
2463
 
2464
A third method of dealing with this difficulty is to abandon
2465
'auto-import' for the offending symbol and mark it with
2466
@code{__declspec(dllimport)}.  However, in practise that
2467
requires using compile-time #defines to indicate whether you are
2468
building a DLL, building client code that will link to the DLL, or
2469
merely building/linking to a static library.   In making the choice
2470
between the various methods of resolving the 'direct address with
2471
constant offset' problem, you should consider typical real-world usage:
2472
 
2473
Original:
2474
@example
2475
--foo.h
2476
extern int arr[];
2477
--foo.c
2478
#include "foo.h"
2479
void main(int argc, char **argv)@{
2480
  printf("%d\n",arr[1]);
2481
@}
2482
@end example
2483
 
2484
Solution 1:
2485
@example
2486
--foo.h
2487
extern int arr[];
2488
--foo.c
2489
#include "foo.h"
2490
void main(int argc, char **argv)@{
2491
  /* This workaround is for win32 and cygwin; do not "optimize" */
2492
  volatile int *parr = arr;
2493
  printf("%d\n",parr[1]);
2494
@}
2495
@end example
2496
 
2497
Solution 2:
2498
@example
2499
--foo.h
2500
/* Note: auto-export is assumed (no __declspec(dllexport)) */
2501
#if (defined(_WIN32) || defined(__CYGWIN__)) && \
2502
  !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
2503
#define FOO_IMPORT __declspec(dllimport)
2504
#else
2505
#define FOO_IMPORT
2506
#endif
2507
extern FOO_IMPORT int arr[];
2508
--foo.c
2509
#include "foo.h"
2510
void main(int argc, char **argv)@{
2511
  printf("%d\n",arr[1]);
2512
@}
2513
@end example
2514
 
2515
A fourth way to avoid this problem is to re-code your
2516
library to use a functional interface rather than a data interface
2517
for the offending variables (e.g. set_foo() and get_foo() accessor
2518
functions).
2519
[This option is specific to the i386 PE targeted port of the linker]
2520
 
2521
@kindex --disable-auto-import
2522
@item --disable-auto-import
2523
Do not attempt to do sophisticated linking of @code{_symbol} to
2524
@code{__imp__symbol} for DATA imports from DLLs.
2525
[This option is specific to the i386 PE targeted port of the linker]
2526
 
2527
@kindex --enable-runtime-pseudo-reloc
2528
@item --enable-runtime-pseudo-reloc
2529
If your code contains expressions described in --enable-auto-import section,
2530
that is, DATA imports from DLL with non-zero offset, this switch will create
2531
a vector of 'runtime pseudo relocations' which can be used by runtime
2532
environment to adjust references to such data in your client code.
2533
[This option is specific to the i386 PE targeted port of the linker]
2534
 
2535
@kindex --disable-runtime-pseudo-reloc
2536
@item --disable-runtime-pseudo-reloc
2537
Do not create pseudo relocations for non-zero offset DATA imports from
2538
DLLs.  This is the default.
2539
[This option is specific to the i386 PE targeted port of the linker]
2540
 
2541
@kindex --enable-extra-pe-debug
2542
@item --enable-extra-pe-debug
2543
Show additional debug info related to auto-import symbol thunking.
2544
[This option is specific to the i386 PE targeted port of the linker]
2545
 
2546
@kindex --section-alignment
2547
@item --section-alignment
2548
Sets the section alignment.  Sections in memory will always begin at
2549
addresses which are a multiple of this number.  Defaults to 0x1000.
2550
[This option is specific to the i386 PE targeted port of the linker]
2551
 
2552
@cindex stack size
2553
@kindex --stack
2554
@item --stack @var{reserve}
2555
@itemx --stack @var{reserve},@var{commit}
2556
Specify the number of bytes of memory to reserve (and optionally commit)
2557
to be used as stack for this program.  The default is 2Mb reserved, 4K
2558
committed.
2559
[This option is specific to the i386 PE targeted port of the linker]
2560
 
2561
@kindex --subsystem
2562
@item --subsystem @var{which}
2563
@itemx --subsystem @var{which}:@var{major}
2564
@itemx --subsystem @var{which}:@var{major}.@var{minor}
2565
Specifies the subsystem under which your program will execute.  The
2566
legal values for @var{which} are @code{native}, @code{windows},
2567
@code{console}, @code{posix}, and @code{xbox}.  You may optionally set
2568
the subsystem version also.  Numeric values are also accepted for
2569
@var{which}.
2570
[This option is specific to the i386 PE targeted port of the linker]
2571
 
2572
The following options set flags in the @code{DllCharacteristics} field
2573
of the PE file header:
2574
[These options are specific to PE targeted ports of the linker]
2575
 
2576
@kindex --dynamicbase
2577
@item --dynamicbase
2578
The image base address may be relocated using address space layout
2579
randomization (ASLR).  This feature was introduced with MS Windows
2580
Vista for i386 PE targets.
2581
 
2582
@kindex --forceinteg
2583
@item --forceinteg
2584
Code integrity checks are enforced.
2585
 
2586
@kindex --nxcompat
2587
@item --nxcompat
2588
The image is compatible with the Data Execution Prevention.
2589
This feature was introduced with MS Windows XP SP2 for i386 PE targets.
2590
 
2591
@kindex --no-isolation
2592
@item --no-isolation
2593
Although the image understands isolation, do not isolate the image.
2594
 
2595
@kindex --no-seh
2596
@item --no-seh
2597
The image does not use SEH. No SE handler may be called from
2598
this image.
2599
 
2600
@kindex --no-bind
2601
@item --no-bind
2602
Do not bind this image.
2603
 
2604
@kindex --wdmdriver
2605
@item --wdmdriver
2606
The driver uses the MS Windows Driver Model.
2607
 
2608
@kindex --tsaware
2609
@item --tsaware
2610
The image is Terminal Server aware.
2611
 
2612
@end table
2613
 
2614
@c man end
2615
 
2616
@ifset C6X
2617
@subsection Options specific to C6X uClinux targets
2618
 
2619
@c man begin OPTIONS
2620
 
2621
The C6X uClinux target uses a binary format called DSBT to support shared
2622
libraries.  Each shared library in the system needs to have a unique index;
2623
all executables use an index of 0.
2624
 
2625
@table @gcctabopt
2626
 
2627
@kindex --dsbt-size
2628
@item --dsbt-size @var{size}
2629
This option sets the number of entires in the DSBT of the current executable
2630
or shared library to @var{size}.  The default is to create a table with 64
2631
entries.
2632
 
2633
@kindex --dsbt-index
2634
@item --dsbt-index @var{index}
2635
This option sets the DSBT index of the current executable or shared library
2636
to @var{index}.  The default is 0, which is appropriate for generating
2637
executables.  If a shared library is generated with a DSBT index of 0, the
2638
@code{R_C6000_DSBT_INDEX} relocs are copied into the output file.
2639
 
2640
@kindex --no-merge-exidx-entries
2641
The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent
2642
exidx entries in frame unwind info.
2643
 
2644
@end table
2645
 
2646
@c man end
2647
@end ifset
2648
 
2649
@ifset M68HC11
2650
@subsection Options specific to Motorola 68HC11 and 68HC12 targets
2651
 
2652
@c man begin OPTIONS
2653
 
2654
The 68HC11 and 68HC12 linkers support specific options to control the
2655
memory bank switching mapping and trampoline code generation.
2656
 
2657
@table @gcctabopt
2658
 
2659
@kindex --no-trampoline
2660
@item --no-trampoline
2661
This option disables the generation of trampoline. By default a trampoline
2662
is generated for each far function which is called using a @code{jsr}
2663
instruction (this happens when a pointer to a far function is taken).
2664
 
2665
@kindex --bank-window
2666
@item --bank-window @var{name}
2667
This option indicates to the linker the name of the memory region in
2668
the @samp{MEMORY} specification that describes the memory bank window.
2669
The definition of such region is then used by the linker to compute
2670
paging and addresses within the memory window.
2671
 
2672
@end table
2673
 
2674
@c man end
2675
@end ifset
2676
 
2677
@ifset M68K
2678
@subsection Options specific to Motorola 68K target
2679
 
2680
@c man begin OPTIONS
2681
 
2682
The following options are supported to control handling of GOT generation
2683
when linking for 68K targets.
2684
 
2685
@table @gcctabopt
2686
 
2687
@kindex --got
2688
@item --got=@var{type}
2689
This option tells the linker which GOT generation scheme to use.
2690
@var{type} should be one of @samp{single}, @samp{negative},
2691
@samp{multigot} or @samp{target}.  For more information refer to the
2692
Info entry for @file{ld}.
2693
 
2694
@end table
2695
 
2696
@c man end
2697
@end ifset
2698
 
2699
@ifset UsesEnvVars
2700
@node Environment
2701
@section Environment Variables
2702
 
2703
@c man begin ENVIRONMENT
2704
 
2705
You can change the behaviour of @command{ld} with the environment variables
2706
@ifclear SingleFormat
2707
@code{GNUTARGET},
2708
@end ifclear
2709
@code{LDEMULATION} and @code{COLLECT_NO_DEMANGLE}.
2710
 
2711
@ifclear SingleFormat
2712
@kindex GNUTARGET
2713
@cindex default input format
2714
@code{GNUTARGET} determines the input-file object format if you don't
2715
use @samp{-b} (or its synonym @samp{--format}).  Its value should be one
2716
of the BFD names for an input format (@pxref{BFD}).  If there is no
2717
@code{GNUTARGET} in the environment, @command{ld} uses the natural format
2718
of the target. If @code{GNUTARGET} is set to @code{default} then BFD
2719
attempts to discover the input format by examining binary input files;
2720
this method often succeeds, but there are potential ambiguities, since
2721
there is no method of ensuring that the magic number used to specify
2722
object-file formats is unique.  However, the configuration procedure for
2723
BFD on each system places the conventional format for that system first
2724
in the search-list, so ambiguities are resolved in favor of convention.
2725
@end ifclear
2726
 
2727
@kindex LDEMULATION
2728
@cindex default emulation
2729
@cindex emulation, default
2730
@code{LDEMULATION} determines the default emulation if you don't use the
2731
@samp{-m} option.  The emulation can affect various aspects of linker
2732
behaviour, particularly the default linker script.  You can list the
2733
available emulations with the @samp{--verbose} or @samp{-V} options.  If
2734
the @samp{-m} option is not used, and the @code{LDEMULATION} environment
2735
variable is not defined, the default emulation depends upon how the
2736
linker was configured.
2737
 
2738
@kindex COLLECT_NO_DEMANGLE
2739
@cindex demangling, default
2740
Normally, the linker will default to demangling symbols.  However, if
2741
@code{COLLECT_NO_DEMANGLE} is set in the environment, then it will
2742
default to not demangling symbols.  This environment variable is used in
2743
a similar fashion by the @code{gcc} linker wrapper program.  The default
2744
may be overridden by the @samp{--demangle} and @samp{--no-demangle}
2745
options.
2746
 
2747
@c man end
2748
@end ifset
2749
 
2750
@node Scripts
2751
@chapter Linker Scripts
2752
 
2753
@cindex scripts
2754
@cindex linker scripts
2755
@cindex command files
2756
Every link is controlled by a @dfn{linker script}.  This script is
2757
written in the linker command language.
2758
 
2759
The main purpose of the linker script is to describe how the sections in
2760
the input files should be mapped into the output file, and to control
2761
the memory layout of the output file.  Most linker scripts do nothing
2762
more than this.  However, when necessary, the linker script can also
2763
direct the linker to perform many other operations, using the commands
2764
described below.
2765
 
2766
The linker always uses a linker script.  If you do not supply one
2767
yourself, the linker will use a default script that is compiled into the
2768
linker executable.  You can use the @samp{--verbose} command line option
2769
to display the default linker script.  Certain command line options,
2770
such as @samp{-r} or @samp{-N}, will affect the default linker script.
2771
 
2772
You may supply your own linker script by using the @samp{-T} command
2773
line option.  When you do this, your linker script will replace the
2774
default linker script.
2775
 
2776
You may also use linker scripts implicitly by naming them as input files
2777
to the linker, as though they were files to be linked.  @xref{Implicit
2778
Linker Scripts}.
2779
 
2780
@menu
2781
* Basic Script Concepts::       Basic Linker Script Concepts
2782
* Script Format::               Linker Script Format
2783
* Simple Example::              Simple Linker Script Example
2784
* Simple Commands::             Simple Linker Script Commands
2785
* Assignments::                 Assigning Values to Symbols
2786
* SECTIONS::                    SECTIONS Command
2787
* MEMORY::                      MEMORY Command
2788
* PHDRS::                       PHDRS Command
2789
* VERSION::                     VERSION Command
2790
* Expressions::                 Expressions in Linker Scripts
2791
* Implicit Linker Scripts::     Implicit Linker Scripts
2792
@end menu
2793
 
2794
@node Basic Script Concepts
2795
@section Basic Linker Script Concepts
2796
@cindex linker script concepts
2797
We need to define some basic concepts and vocabulary in order to
2798
describe the linker script language.
2799
 
2800
The linker combines input files into a single output file.  The output
2801
file and each input file are in a special data format known as an
2802
@dfn{object file format}.  Each file is called an @dfn{object file}.
2803
The output file is often called an @dfn{executable}, but for our
2804
purposes we will also call it an object file.  Each object file has,
2805
among other things, a list of @dfn{sections}.  We sometimes refer to a
2806
section in an input file as an @dfn{input section}; similarly, a section
2807
in the output file is an @dfn{output section}.
2808
 
2809
Each section in an object file has a name and a size.  Most sections
2810
also have an associated block of data, known as the @dfn{section
2811
contents}.  A section may be marked as @dfn{loadable}, which mean that
2812
the contents should be loaded into memory when the output file is run.
2813
A section with no contents may be @dfn{allocatable}, which means that an
2814
area in memory should be set aside, but nothing in particular should be
2815
loaded there (in some cases this memory must be zeroed out).  A section
2816
which is neither loadable nor allocatable typically contains some sort
2817
of debugging information.
2818
 
2819
Every loadable or allocatable output section has two addresses.  The
2820
first is the @dfn{VMA}, or virtual memory address.  This is the address
2821
the section will have when the output file is run.  The second is the
2822
@dfn{LMA}, or load memory address.  This is the address at which the
2823
section will be loaded.  In most cases the two addresses will be the
2824
same.  An example of when they might be different is when a data section
2825
is loaded into ROM, and then copied into RAM when the program starts up
2826
(this technique is often used to initialize global variables in a ROM
2827
based system).  In this case the ROM address would be the LMA, and the
2828
RAM address would be the VMA.
2829
 
2830
You can see the sections in an object file by using the @code{objdump}
2831
program with the @samp{-h} option.
2832
 
2833
Every object file also has a list of @dfn{symbols}, known as the
2834
@dfn{symbol table}.  A symbol may be defined or undefined.  Each symbol
2835
has a name, and each defined symbol has an address, among other
2836
information.  If you compile a C or C++ program into an object file, you
2837
will get a defined symbol for every defined function and global or
2838
static variable.  Every undefined function or global variable which is
2839
referenced in the input file will become an undefined symbol.
2840
 
2841
You can see the symbols in an object file by using the @code{nm}
2842
program, or by using the @code{objdump} program with the @samp{-t}
2843
option.
2844
 
2845
@node Script Format
2846
@section Linker Script Format
2847
@cindex linker script format
2848
Linker scripts are text files.
2849
 
2850
You write a linker script as a series of commands.  Each command is
2851
either a keyword, possibly followed by arguments, or an assignment to a
2852
symbol.  You may separate commands using semicolons.  Whitespace is
2853
generally ignored.
2854
 
2855
Strings such as file or format names can normally be entered directly.
2856
If the file name contains a character such as a comma which would
2857
otherwise serve to separate file names, you may put the file name in
2858
double quotes.  There is no way to use a double quote character in a
2859
file name.
2860
 
2861
You may include comments in linker scripts just as in C, delimited by
2862
@samp{/*} and @samp{*/}.  As in C, comments are syntactically equivalent
2863
to whitespace.
2864
 
2865
@node Simple Example
2866
@section Simple Linker Script Example
2867
@cindex linker script example
2868
@cindex example of linker script
2869
Many linker scripts are fairly simple.
2870
 
2871
The simplest possible linker script has just one command:
2872
@samp{SECTIONS}.  You use the @samp{SECTIONS} command to describe the
2873
memory layout of the output file.
2874
 
2875
The @samp{SECTIONS} command is a powerful command.  Here we will
2876
describe a simple use of it.  Let's assume your program consists only of
2877
code, initialized data, and uninitialized data.  These will be in the
2878
@samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
2879
Let's assume further that these are the only sections which appear in
2880
your input files.
2881
 
2882
For this example, let's say that the code should be loaded at address
2883
0x10000, and that the data should start at address 0x8000000.  Here is a
2884
linker script which will do that:
2885
@smallexample
2886
SECTIONS
2887
@{
2888
  . = 0x10000;
2889
  .text : @{ *(.text) @}
2890
  . = 0x8000000;
2891
  .data : @{ *(.data) @}
2892
  .bss : @{ *(.bss) @}
2893
@}
2894
@end smallexample
2895
 
2896
You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
2897
followed by a series of symbol assignments and output section
2898
descriptions enclosed in curly braces.
2899
 
2900
The first line inside the @samp{SECTIONS} command of the above example
2901
sets the value of the special symbol @samp{.}, which is the location
2902
counter.  If you do not specify the address of an output section in some
2903
other way (other ways are described later), the address is set from the
2904
current value of the location counter.  The location counter is then
2905
incremented by the size of the output section.  At the start of the
2906
@samp{SECTIONS} command, the location counter has the value @samp{0}.
2907
 
2908
The second line defines an output section, @samp{.text}.  The colon is
2909
required syntax which may be ignored for now.  Within the curly braces
2910
after the output section name, you list the names of the input sections
2911
which should be placed into this output section.  The @samp{*} is a
2912
wildcard which matches any file name.  The expression @samp{*(.text)}
2913
means all @samp{.text} input sections in all input files.
2914
 
2915
Since the location counter is @samp{0x10000} when the output section
2916
@samp{.text} is defined, the linker will set the address of the
2917
@samp{.text} section in the output file to be @samp{0x10000}.
2918
 
2919
The remaining lines define the @samp{.data} and @samp{.bss} sections in
2920
the output file.  The linker will place the @samp{.data} output section
2921
at address @samp{0x8000000}.  After the linker places the @samp{.data}
2922
output section, the value of the location counter will be
2923
@samp{0x8000000} plus the size of the @samp{.data} output section.  The
2924
effect is that the linker will place the @samp{.bss} output section
2925
immediately after the @samp{.data} output section in memory.
2926
 
2927
The linker will ensure that each output section has the required
2928
alignment, by increasing the location counter if necessary.  In this
2929
example, the specified addresses for the @samp{.text} and @samp{.data}
2930
sections will probably satisfy any alignment constraints, but the linker
2931
may have to create a small gap between the @samp{.data} and @samp{.bss}
2932
sections.
2933
 
2934
That's it!  That's a simple and complete linker script.
2935
 
2936
@node Simple Commands
2937
@section Simple Linker Script Commands
2938
@cindex linker script simple commands
2939
In this section we describe the simple linker script commands.
2940
 
2941
@menu
2942
* Entry Point::                 Setting the entry point
2943
* File Commands::               Commands dealing with files
2944
@ifclear SingleFormat
2945
* Format Commands::             Commands dealing with object file formats
2946
@end ifclear
2947
 
2948
* REGION_ALIAS::                Assign alias names to memory regions
2949
* Miscellaneous Commands::      Other linker script commands
2950
@end menu
2951
 
2952
@node Entry Point
2953
@subsection Setting the Entry Point
2954
@kindex ENTRY(@var{symbol})
2955
@cindex start of execution
2956
@cindex first instruction
2957
@cindex entry point
2958
The first instruction to execute in a program is called the @dfn{entry
2959
point}.  You can use the @code{ENTRY} linker script command to set the
2960
entry point.  The argument is a symbol name:
2961
@smallexample
2962
ENTRY(@var{symbol})
2963
@end smallexample
2964
 
2965
There are several ways to set the entry point.  The linker will set the
2966
entry point by trying each of the following methods in order, and
2967
stopping when one of them succeeds:
2968
@itemize @bullet
2969
@item
2970
the @samp{-e} @var{entry} command-line option;
2971
@item
2972
the @code{ENTRY(@var{symbol})} command in a linker script;
2973
@item
2974
the value of a target specific symbol, if it is defined;  For many
2975
targets this is @code{start}, but PE and BeOS based systems for example
2976
check a list of possible entry symbols, matching the first one found.
2977
@item
2978
the address of the first byte of the @samp{.text} section, if present;
2979
@item
2980
The address @code{0}.
2981
@end itemize
2982
 
2983
@node File Commands
2984
@subsection Commands Dealing with Files
2985
@cindex linker script file commands
2986
Several linker script commands deal with files.
2987
 
2988
@table @code
2989
@item INCLUDE @var{filename}
2990
@kindex INCLUDE @var{filename}
2991
@cindex including a linker script
2992
Include the linker script @var{filename} at this point.  The file will
2993
be searched for in the current directory, and in any directory specified
2994
with the @option{-L} option.  You can nest calls to @code{INCLUDE} up to
2995
10 levels deep.
2996
 
2997
You can place @code{INCLUDE} directives at the top level, in @code{MEMORY} or
2998
@code{SECTIONS} commands, or in output section descriptions.
2999
 
3000
@item INPUT(@var{file}, @var{file}, @dots{})
3001
@itemx INPUT(@var{file} @var{file} @dots{})
3002
@kindex INPUT(@var{files})
3003
@cindex input files in linker scripts
3004
@cindex input object files in linker scripts
3005
@cindex linker script input object files
3006
The @code{INPUT} command directs the linker to include the named files
3007
in the link, as though they were named on the command line.
3008
 
3009
For example, if you always want to include @file{subr.o} any time you do
3010
a link, but you can't be bothered to put it on every link command line,
3011
then you can put @samp{INPUT (subr.o)} in your linker script.
3012
 
3013
In fact, if you like, you can list all of your input files in the linker
3014
script, and then invoke the linker with nothing but a @samp{-T} option.
3015
 
3016
In case a @dfn{sysroot prefix} is configured, and the filename starts
3017
with the @samp{/} character, and the script being processed was
3018
located inside the @dfn{sysroot prefix}, the filename will be looked
3019
for in the @dfn{sysroot prefix}.  Otherwise, the linker will try to
3020
open the file in the current directory.  If it is not found, the
3021
linker will search through the archive library search path.  See the
3022
description of @samp{-L} in @ref{Options,,Command Line Options}.
3023
 
3024
If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
3025
name to @code{lib@var{file}.a}, as with the command line argument
3026
@samp{-l}.
3027
 
3028
When you use the @code{INPUT} command in an implicit linker script, the
3029
files will be included in the link at the point at which the linker
3030
script file is included.  This can affect archive searching.
3031
 
3032
@item GROUP(@var{file}, @var{file}, @dots{})
3033
@itemx GROUP(@var{file} @var{file} @dots{})
3034
@kindex GROUP(@var{files})
3035
@cindex grouping input files
3036
The @code{GROUP} command is like @code{INPUT}, except that the named
3037
files should all be archives, and they are searched repeatedly until no
3038
new undefined references are created.  See the description of @samp{-(}
3039
in @ref{Options,,Command Line Options}.
3040
 
3041
@item AS_NEEDED(@var{file}, @var{file}, @dots{})
3042
@itemx AS_NEEDED(@var{file} @var{file} @dots{})
3043
@kindex AS_NEEDED(@var{files})
3044
This construct can appear only inside of the @code{INPUT} or @code{GROUP}
3045
commands, among other filenames.  The files listed will be handled
3046
as if they appear directly in the @code{INPUT} or @code{GROUP} commands,
3047
with the exception of ELF shared libraries, that will be added only
3048
when they are actually needed.  This construct essentially enables
3049
@option{--as-needed} option for all the files listed inside of it
3050
and restores previous @option{--as-needed} resp. @option{--no-as-needed}
3051
setting afterwards.
3052
 
3053
@item OUTPUT(@var{filename})
3054
@kindex OUTPUT(@var{filename})
3055
@cindex output file name in linker script
3056
The @code{OUTPUT} command names the output file.  Using
3057
@code{OUTPUT(@var{filename})} in the linker script is exactly like using
3058
@samp{-o @var{filename}} on the command line (@pxref{Options,,Command
3059
Line Options}).  If both are used, the command line option takes
3060
precedence.
3061
 
3062
You can use the @code{OUTPUT} command to define a default name for the
3063
output file other than the usual default of @file{a.out}.
3064
 
3065
@item SEARCH_DIR(@var{path})
3066
@kindex SEARCH_DIR(@var{path})
3067
@cindex library search path in linker script
3068
@cindex archive search path in linker script
3069
@cindex search path in linker script
3070
The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
3071
@command{ld} looks for archive libraries.  Using
3072
@code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
3073
on the command line (@pxref{Options,,Command Line Options}).  If both
3074
are used, then the linker will search both paths.  Paths specified using
3075
the command line option are searched first.
3076
 
3077
@item STARTUP(@var{filename})
3078
@kindex STARTUP(@var{filename})
3079
@cindex first input file
3080
The @code{STARTUP} command is just like the @code{INPUT} command, except
3081
that @var{filename} will become the first input file to be linked, as
3082
though it were specified first on the command line.  This may be useful
3083
when using a system in which the entry point is always the start of the
3084
first file.
3085
@end table
3086
 
3087
@ifclear SingleFormat
3088
@node Format Commands
3089
@subsection Commands Dealing with Object File Formats
3090
A couple of linker script commands deal with object file formats.
3091
 
3092
@table @code
3093
@item OUTPUT_FORMAT(@var{bfdname})
3094
@itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
3095
@kindex OUTPUT_FORMAT(@var{bfdname})
3096
@cindex output file format in linker script
3097
The @code{OUTPUT_FORMAT} command names the BFD format to use for the
3098
output file (@pxref{BFD}).  Using @code{OUTPUT_FORMAT(@var{bfdname})} is
3099
exactly like using @samp{--oformat @var{bfdname}} on the command line
3100
(@pxref{Options,,Command Line Options}).  If both are used, the command
3101
line option takes precedence.
3102
 
3103
You can use @code{OUTPUT_FORMAT} with three arguments to use different
3104
formats based on the @samp{-EB} and @samp{-EL} command line options.
3105
This permits the linker script to set the output format based on the
3106
desired endianness.
3107
 
3108
If neither @samp{-EB} nor @samp{-EL} are used, then the output format
3109
will be the first argument, @var{default}.  If @samp{-EB} is used, the
3110
output format will be the second argument, @var{big}.  If @samp{-EL} is
3111
used, the output format will be the third argument, @var{little}.
3112
 
3113
For example, the default linker script for the MIPS ELF target uses this
3114
command:
3115
@smallexample
3116
OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
3117
@end smallexample
3118
This says that the default format for the output file is
3119
@samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line
3120
option, the output file will be created in the @samp{elf32-littlemips}
3121
format.
3122
 
3123
@item TARGET(@var{bfdname})
3124
@kindex TARGET(@var{bfdname})
3125
@cindex input file format in linker script
3126
The @code{TARGET} command names the BFD format to use when reading input
3127
files.  It affects subsequent @code{INPUT} and @code{GROUP} commands.
3128
This command is like using @samp{-b @var{bfdname}} on the command line
3129
(@pxref{Options,,Command Line Options}).  If the @code{TARGET} command
3130
is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
3131
command is also used to set the format for the output file.  @xref{BFD}.
3132
@end table
3133
@end ifclear
3134
 
3135
@node REGION_ALIAS
3136
@subsection Assign alias names to memory regions
3137
@kindex REGION_ALIAS(@var{alias}, @var{region})
3138
@cindex region alias
3139
@cindex region names
3140
 
3141
Alias names can be added to existing memory regions created with the
3142
@ref{MEMORY} command.  Each name corresponds to at most one memory region.
3143
 
3144
@smallexample
3145
REGION_ALIAS(@var{alias}, @var{region})
3146
@end smallexample
3147
 
3148
The @code{REGION_ALIAS} function creates an alias name @var{alias} for the
3149
memory region @var{region}.  This allows a flexible mapping of output sections
3150
to memory regions.  An example follows.
3151
 
3152
Suppose we have an application for embedded systems which come with various
3153
memory storage devices.  All have a general purpose, volatile memory @code{RAM}
3154
that allows code execution or data storage.  Some may have a read-only,
3155
non-volatile memory @code{ROM} that allows code execution and read-only data
3156
access.  The last variant is a read-only, non-volatile memory @code{ROM2} with
3157
read-only data access and no code execution capability.  We have four output
3158
sections:
3159
 
3160
@itemize @bullet
3161
@item
3162
@code{.text} program code;
3163
@item
3164
@code{.rodata} read-only data;
3165
@item
3166
@code{.data} read-write initialized data;
3167
@item
3168
@code{.bss} read-write zero initialized data.
3169
@end itemize
3170
 
3171
The goal is to provide a linker command file that contains a system independent
3172
part defining the output sections and a system dependent part mapping the
3173
output sections to the memory regions available on the system.  Our embedded
3174
systems come with three different memory setups @code{A}, @code{B} and
3175
@code{C}:
3176
@multitable @columnfractions .25 .25 .25 .25
3177
@item Section @tab Variant A @tab Variant B @tab Variant C
3178
@item .text @tab RAM @tab ROM @tab ROM
3179
@item .rodata @tab RAM @tab ROM @tab ROM2
3180
@item .data @tab RAM @tab RAM/ROM @tab RAM/ROM2
3181
@item .bss @tab RAM @tab RAM @tab RAM
3182
@end multitable
3183
The notation @code{RAM/ROM} or @code{RAM/ROM2} means that this section is
3184
loaded into region @code{ROM} or @code{ROM2} respectively.  Please note that
3185
the load address of the @code{.data} section starts in all three variants at
3186
the end of the @code{.rodata} section.
3187
 
3188
The base linker script that deals with the output sections follows.  It
3189
includes the system dependent @code{linkcmds.memory} file that describes the
3190
memory layout:
3191
@smallexample
3192
INCLUDE linkcmds.memory
3193
 
3194
SECTIONS
3195
  @{
3196
    .text :
3197
      @{
3198
        *(.text)
3199
      @} > REGION_TEXT
3200
    .rodata :
3201
      @{
3202
        *(.rodata)
3203
        rodata_end = .;
3204
      @} > REGION_RODATA
3205
    .data : AT (rodata_end)
3206
      @{
3207
        data_start = .;
3208
        *(.data)
3209
      @} > REGION_DATA
3210
    data_size = SIZEOF(.data);
3211
    data_load_start = LOADADDR(.data);
3212
    .bss :
3213
      @{
3214
        *(.bss)
3215
      @} > REGION_BSS
3216
  @}
3217
@end smallexample
3218
 
3219
Now we need three different @code{linkcmds.memory} files to define memory
3220
regions and alias names.  The content of @code{linkcmds.memory} for the three
3221
variants @code{A}, @code{B} and @code{C}:
3222
@table @code
3223
@item A
3224
Here everything goes into the @code{RAM}.
3225
@smallexample
3226
MEMORY
3227
  @{
3228
    RAM : ORIGIN = 0, LENGTH = 4M
3229
  @}
3230
 
3231
REGION_ALIAS("REGION_TEXT", RAM);
3232
REGION_ALIAS("REGION_RODATA", RAM);
3233
REGION_ALIAS("REGION_DATA", RAM);
3234
REGION_ALIAS("REGION_BSS", RAM);
3235
@end smallexample
3236
@item B
3237
Program code and read-only data go into the @code{ROM}.  Read-write data goes
3238
into the @code{RAM}.  An image of the initialized data is loaded into the
3239
@code{ROM} and will be copied during system start into the @code{RAM}.
3240
@smallexample
3241
MEMORY
3242
  @{
3243
    ROM : ORIGIN = 0, LENGTH = 3M
3244
    RAM : ORIGIN = 0x10000000, LENGTH = 1M
3245
  @}
3246
 
3247
REGION_ALIAS("REGION_TEXT", ROM);
3248
REGION_ALIAS("REGION_RODATA", ROM);
3249
REGION_ALIAS("REGION_DATA", RAM);
3250
REGION_ALIAS("REGION_BSS", RAM);
3251
@end smallexample
3252
@item C
3253
Program code goes into the @code{ROM}.  Read-only data goes into the
3254
@code{ROM2}.  Read-write data goes into the @code{RAM}.  An image of the
3255
initialized data is loaded into the @code{ROM2} and will be copied during
3256
system start into the @code{RAM}.
3257
@smallexample
3258
MEMORY
3259
  @{
3260
    ROM : ORIGIN = 0, LENGTH = 2M
3261
    ROM2 : ORIGIN = 0x10000000, LENGTH = 1M
3262
    RAM : ORIGIN = 0x20000000, LENGTH = 1M
3263
  @}
3264
 
3265
REGION_ALIAS("REGION_TEXT", ROM);
3266
REGION_ALIAS("REGION_RODATA", ROM2);
3267
REGION_ALIAS("REGION_DATA", RAM);
3268
REGION_ALIAS("REGION_BSS", RAM);
3269
@end smallexample
3270
@end table
3271
 
3272
It is possible to write a common system initialization routine to copy the
3273
@code{.data} section from @code{ROM} or @code{ROM2} into the @code{RAM} if
3274
necessary:
3275
@smallexample
3276
#include <string.h>
3277
 
3278
extern char data_start [];
3279
extern char data_size [];
3280
extern char data_load_start [];
3281
 
3282
void copy_data(void)
3283
@{
3284
  if (data_start != data_load_start)
3285
    @{
3286
      memcpy(data_start, data_load_start, (size_t) data_size);
3287
    @}
3288
@}
3289
@end smallexample
3290
 
3291
@node Miscellaneous Commands
3292
@subsection Other Linker Script Commands
3293
There are a few other linker scripts commands.
3294
 
3295
@table @code
3296
@item ASSERT(@var{exp}, @var{message})
3297
@kindex ASSERT
3298
@cindex assertion in linker script
3299
Ensure that @var{exp} is non-zero.  If it is zero, then exit the linker
3300
with an error code, and print @var{message}.
3301
 
3302
@item EXTERN(@var{symbol} @var{symbol} @dots{})
3303
@kindex EXTERN
3304
@cindex undefined symbol in linker script
3305
Force @var{symbol} to be entered in the output file as an undefined
3306
symbol.  Doing this may, for example, trigger linking of additional
3307
modules from standard libraries.  You may list several @var{symbol}s for
3308
each @code{EXTERN}, and you may use @code{EXTERN} multiple times.  This
3309
command has the same effect as the @samp{-u} command-line option.
3310
 
3311
@item FORCE_COMMON_ALLOCATION
3312
@kindex FORCE_COMMON_ALLOCATION
3313
@cindex common allocation in linker script
3314
This command has the same effect as the @samp{-d} command-line option:
3315
to make @command{ld} assign space to common symbols even if a relocatable
3316
output file is specified (@samp{-r}).
3317
 
3318
@item INHIBIT_COMMON_ALLOCATION
3319
@kindex INHIBIT_COMMON_ALLOCATION
3320
@cindex common allocation in linker script
3321
This command has the same effect as the @samp{--no-define-common}
3322
command-line option: to make @code{ld} omit the assignment of addresses
3323
to common symbols even for a non-relocatable output file.
3324
 
3325
@item INSERT [ AFTER | BEFORE ] @var{output_section}
3326
@kindex INSERT
3327
@cindex insert user script into default script
3328
This command is typically used in a script specified by @samp{-T} to
3329
augment the default @code{SECTIONS} with, for example, overlays.  It
3330
inserts all prior linker script statements after (or before)
3331
@var{output_section}, and also causes @samp{-T} to not override the
3332
default linker script.  The exact insertion point is as for orphan
3333
sections.  @xref{Location Counter}.  The insertion happens after the
3334
linker has mapped input sections to output sections.  Prior to the
3335
insertion, since @samp{-T} scripts are parsed before the default
3336
linker script, statements in the @samp{-T} script occur before the
3337
default linker script statements in the internal linker representation
3338
of the script.  In particular, input section assignments will be made
3339
to @samp{-T} output sections before those in the default script.  Here
3340
is an example of how a @samp{-T} script using @code{INSERT} might look:
3341
 
3342
@smallexample
3343
SECTIONS
3344
@{
3345
  OVERLAY :
3346
  @{
3347
    .ov1 @{ ov1*(.text) @}
3348
    .ov2 @{ ov2*(.text) @}
3349
  @}
3350
@}
3351
INSERT AFTER .text;
3352
@end smallexample
3353
 
3354
@item NOCROSSREFS(@var{section} @var{section} @dots{})
3355
@kindex NOCROSSREFS(@var{sections})
3356
@cindex cross references
3357
This command may be used to tell @command{ld} to issue an error about any
3358
references among certain output sections.
3359
 
3360
In certain types of programs, particularly on embedded systems when
3361
using overlays, when one section is loaded into memory, another section
3362
will not be.  Any direct references between the two sections would be
3363
errors.  For example, it would be an error if code in one section called
3364
a function defined in the other section.
3365
 
3366
The @code{NOCROSSREFS} command takes a list of output section names.  If
3367
@command{ld} detects any cross references between the sections, it reports
3368
an error and returns a non-zero exit status.  Note that the
3369
@code{NOCROSSREFS} command uses output section names, not input section
3370
names.
3371
 
3372
@ifclear SingleFormat
3373
@item OUTPUT_ARCH(@var{bfdarch})
3374
@kindex OUTPUT_ARCH(@var{bfdarch})
3375
@cindex machine architecture
3376
@cindex architecture
3377
Specify a particular output machine architecture.  The argument is one
3378
of the names used by the BFD library (@pxref{BFD}).  You can see the
3379
architecture of an object file by using the @code{objdump} program with
3380
the @samp{-f} option.
3381
@end ifclear
3382
 
3383
@item LD_FEATURE(@var{string})
3384
@kindex LD_FEATURE(@var{string})
3385
This command may be used to modify @command{ld} behavior.  If
3386
@var{string} is @code{"SANE_EXPR"} then absolute symbols and numbers
3387
in a script are simply treated as numbers everywhere.
3388
@xref{Expression Section}.
3389
@end table
3390
 
3391
@node Assignments
3392
@section Assigning Values to Symbols
3393
@cindex assignment in scripts
3394
@cindex symbol definition, scripts
3395
@cindex variables, defining
3396
You may assign a value to a symbol in a linker script.  This will define
3397
the symbol and place it into the symbol table with a global scope.
3398
 
3399
@menu
3400
* Simple Assignments::          Simple Assignments
3401
* PROVIDE::                     PROVIDE
3402
* PROVIDE_HIDDEN::              PROVIDE_HIDDEN
3403
* Source Code Reference::       How to use a linker script defined symbol in source code
3404
@end menu
3405
 
3406
@node Simple Assignments
3407
@subsection Simple Assignments
3408
 
3409
You may assign to a symbol using any of the C assignment operators:
3410
 
3411
@table @code
3412
@item @var{symbol} = @var{expression} ;
3413
@itemx @var{symbol} += @var{expression} ;
3414
@itemx @var{symbol} -= @var{expression} ;
3415
@itemx @var{symbol} *= @var{expression} ;
3416
@itemx @var{symbol} /= @var{expression} ;
3417
@itemx @var{symbol} <<= @var{expression} ;
3418
@itemx @var{symbol} >>= @var{expression} ;
3419
@itemx @var{symbol} &= @var{expression} ;
3420
@itemx @var{symbol} |= @var{expression} ;
3421
@end table
3422
 
3423
The first case will define @var{symbol} to the value of
3424
@var{expression}.  In the other cases, @var{symbol} must already be
3425
defined, and the value will be adjusted accordingly.
3426
 
3427
The special symbol name @samp{.} indicates the location counter.  You
3428
may only use this within a @code{SECTIONS} command.  @xref{Location Counter}.
3429
 
3430
The semicolon after @var{expression} is required.
3431
 
3432
Expressions are defined below; see @ref{Expressions}.
3433
 
3434
You may write symbol assignments as commands in their own right, or as
3435
statements within a @code{SECTIONS} command, or as part of an output
3436
section description in a @code{SECTIONS} command.
3437
 
3438
The section of the symbol will be set from the section of the
3439
expression; for more information, see @ref{Expression Section}.
3440
 
3441
Here is an example showing the three different places that symbol
3442
assignments may be used:
3443
 
3444
@smallexample
3445
floating_point = 0;
3446
SECTIONS
3447
@{
3448
  .text :
3449
    @{
3450
      *(.text)
3451
      _etext = .;
3452
    @}
3453
  _bdata = (. + 3) & ~ 3;
3454
  .data : @{ *(.data) @}
3455
@}
3456
@end smallexample
3457
@noindent
3458
In this example, the symbol @samp{floating_point} will be defined as
3459
zero.  The symbol @samp{_etext} will be defined as the address following
3460
the last @samp{.text} input section.  The symbol @samp{_bdata} will be
3461
defined as the address following the @samp{.text} output section aligned
3462
upward to a 4 byte boundary.
3463
 
3464
@node PROVIDE
3465
@subsection PROVIDE
3466
@cindex PROVIDE
3467
In some cases, it is desirable for a linker script to define a symbol
3468
only if it is referenced and is not defined by any object included in
3469
the link.  For example, traditional linkers defined the symbol
3470
@samp{etext}.  However, ANSI C requires that the user be able to use
3471
@samp{etext} as a function name without encountering an error.  The
3472
@code{PROVIDE} keyword may be used to define a symbol, such as
3473
@samp{etext}, only if it is referenced but not defined.  The syntax is
3474
@code{PROVIDE(@var{symbol} = @var{expression})}.
3475
 
3476
Here is an example of using @code{PROVIDE} to define @samp{etext}:
3477
@smallexample
3478
SECTIONS
3479
@{
3480
  .text :
3481
    @{
3482
      *(.text)
3483
      _etext = .;
3484
      PROVIDE(etext = .);
3485
    @}
3486
@}
3487
@end smallexample
3488
 
3489
In this example, if the program defines @samp{_etext} (with a leading
3490
underscore), the linker will give a multiple definition error.  If, on
3491
the other hand, the program defines @samp{etext} (with no leading
3492
underscore), the linker will silently use the definition in the program.
3493
If the program references @samp{etext} but does not define it, the
3494
linker will use the definition in the linker script.
3495
 
3496
@node PROVIDE_HIDDEN
3497
@subsection PROVIDE_HIDDEN
3498
@cindex PROVIDE_HIDDEN
3499
Similar to @code{PROVIDE}.  For ELF targeted ports, the symbol will be
3500
hidden and won't be exported.
3501
 
3502
@node Source Code Reference
3503
@subsection Source Code Reference
3504
 
3505
Accessing a linker script defined variable from source code is not
3506
intuitive.  In particular a linker script symbol is not equivalent to
3507
a variable declaration in a high level language, it is instead a
3508
symbol that does not have a value.
3509
 
3510
Before going further, it is important to note that compilers often
3511
transform names in the source code into different names when they are
3512
stored in the symbol table.  For example, Fortran compilers commonly
3513
prepend or append an underscore, and C++ performs extensive @samp{name
3514
mangling}.  Therefore there might be a discrepancy between the name
3515
of a variable as it is used in source code and the name of the same
3516
variable as it is defined in a linker script.  For example in C a
3517
linker script variable might be referred to as:
3518
 
3519
@smallexample
3520
  extern int foo;
3521
@end smallexample
3522
 
3523
But in the linker script it might be defined as:
3524
 
3525
@smallexample
3526
  _foo = 1000;
3527
@end smallexample
3528
 
3529
In the remaining examples however it is assumed that no name
3530
transformation has taken place.
3531
 
3532
When a symbol is declared in a high level language such as C, two
3533
things happen.  The first is that the compiler reserves enough space
3534
in the program's memory to hold the @emph{value} of the symbol.  The
3535
second is that the compiler creates an entry in the program's symbol
3536
table which holds the symbol's @emph{address}.  ie the symbol table
3537
contains the address of the block of memory holding the symbol's
3538
value.  So for example the following C declaration, at file scope:
3539
 
3540
@smallexample
3541
  int foo = 1000;
3542
@end smallexample
3543
 
3544
creates a entry called @samp{foo} in the symbol table.  This entry
3545
holds the address of an @samp{int} sized block of memory where the
3546
number 1000 is initially stored.
3547
 
3548
When a program references a symbol the compiler generates code that
3549
first accesses the symbol table to find the address of the symbol's
3550
memory block and then code to read the value from that memory block.
3551
So:
3552
 
3553
@smallexample
3554
  foo = 1;
3555
@end smallexample
3556
 
3557
looks up the symbol @samp{foo} in the symbol table, gets the address
3558
associated with this symbol and then writes the value 1 into that
3559
address.  Whereas:
3560
 
3561
@smallexample
3562
  int * a = & foo;
3563
@end smallexample
3564
 
3565
looks up the symbol @samp{foo} in the symbol table, gets it address
3566
and then copies this address into the block of memory associated with
3567
the variable @samp{a}.
3568
 
3569
Linker scripts symbol declarations, by contrast, create an entry in
3570
the symbol table but do not assign any memory to them.  Thus they are
3571
an address without a value.  So for example the linker script definition:
3572
 
3573
@smallexample
3574
  foo = 1000;
3575
@end smallexample
3576
 
3577
creates an entry in the symbol table called @samp{foo} which holds
3578
the address of memory location 1000, but nothing special is stored at
3579
address 1000.  This means that you cannot access the @emph{value} of a
3580
linker script defined symbol - it has no value - all you can do is
3581
access the @emph{address} of a linker script defined symbol.
3582
 
3583
Hence when you are using a linker script defined symbol in source code
3584
you should always take the address of the symbol, and never attempt to
3585
use its value.  For example suppose you want to copy the contents of a
3586
section of memory called .ROM into a section called .FLASH and the
3587
linker script contains these declarations:
3588
 
3589
@smallexample
3590
@group
3591
  start_of_ROM   = .ROM;
3592
  end_of_ROM     = .ROM + sizeof (.ROM) - 1;
3593
  start_of_FLASH = .FLASH;
3594
@end group
3595
@end smallexample
3596
 
3597
Then the C source code to perform the copy would be:
3598
 
3599
@smallexample
3600
@group
3601
  extern char start_of_ROM, end_of_ROM, start_of_FLASH;
3602
 
3603
  memcpy (& start_of_FLASH, & start_of_ROM, & end_of_ROM - & start_of_ROM);
3604
@end group
3605
@end smallexample
3606
 
3607
Note the use of the @samp{&} operators.  These are correct.
3608
 
3609
@node SECTIONS
3610
@section SECTIONS Command
3611
@kindex SECTIONS
3612
The @code{SECTIONS} command tells the linker how to map input sections
3613
into output sections, and how to place the output sections in memory.
3614
 
3615
The format of the @code{SECTIONS} command is:
3616
@smallexample
3617
SECTIONS
3618
@{
3619
  @var{sections-command}
3620
  @var{sections-command}
3621
  @dots{}
3622
@}
3623
@end smallexample
3624
 
3625
Each @var{sections-command} may of be one of the following:
3626
 
3627
@itemize @bullet
3628
@item
3629
an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
3630
@item
3631
a symbol assignment (@pxref{Assignments})
3632
@item
3633
an output section description
3634
@item
3635
an overlay description
3636
@end itemize
3637
 
3638
The @code{ENTRY} command and symbol assignments are permitted inside the
3639
@code{SECTIONS} command for convenience in using the location counter in
3640
those commands.  This can also make the linker script easier to
3641
understand because you can use those commands at meaningful points in
3642
the layout of the output file.
3643
 
3644
Output section descriptions and overlay descriptions are described
3645
below.
3646
 
3647
If you do not use a @code{SECTIONS} command in your linker script, the
3648
linker will place each input section into an identically named output
3649
section in the order that the sections are first encountered in the
3650
input files.  If all input sections are present in the first file, for
3651
example, the order of sections in the output file will match the order
3652
in the first input file.  The first section will be at address zero.
3653
 
3654
@menu
3655
* Output Section Description::  Output section description
3656
* Output Section Name::         Output section name
3657
* Output Section Address::      Output section address
3658
* Input Section::               Input section description
3659
* Output Section Data::         Output section data
3660
* Output Section Keywords::     Output section keywords
3661
* Output Section Discarding::   Output section discarding
3662
* Output Section Attributes::   Output section attributes
3663
* Overlay Description::         Overlay description
3664
@end menu
3665
 
3666
@node Output Section Description
3667
@subsection Output Section Description
3668
The full description of an output section looks like this:
3669
@smallexample
3670
@group
3671
@var{section} [@var{address}] [(@var{type})] :
3672
  [AT(@var{lma})]
3673
  [ALIGN(@var{section_align})]
3674
  [SUBALIGN(@var{subsection_align})]
3675
  [@var{constraint}]
3676
  @{
3677
    @var{output-section-command}
3678
    @var{output-section-command}
3679
    @dots{}
3680
  @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
3681
@end group
3682
@end smallexample
3683
 
3684
Most output sections do not use most of the optional section attributes.
3685
 
3686
The whitespace around @var{section} is required, so that the section
3687
name is unambiguous.  The colon and the curly braces are also required.
3688
The line breaks and other white space are optional.
3689
 
3690
Each @var{output-section-command} may be one of the following:
3691
 
3692
@itemize @bullet
3693
@item
3694
a symbol assignment (@pxref{Assignments})
3695
@item
3696
an input section description (@pxref{Input Section})
3697
@item
3698
data values to include directly (@pxref{Output Section Data})
3699
@item
3700
a special output section keyword (@pxref{Output Section Keywords})
3701
@end itemize
3702
 
3703
@node Output Section Name
3704
@subsection Output Section Name
3705
@cindex name, section
3706
@cindex section name
3707
The name of the output section is @var{section}.  @var{section} must
3708
meet the constraints of your output format.  In formats which only
3709
support a limited number of sections, such as @code{a.out}, the name
3710
must be one of the names supported by the format (@code{a.out}, for
3711
example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
3712
output format supports any number of sections, but with numbers and not
3713
names (as is the case for Oasys), the name should be supplied as a
3714
quoted numeric string.  A section name may consist of any sequence of
3715
characters, but a name which contains any unusual characters such as
3716
commas must be quoted.
3717
 
3718
The output section name @samp{/DISCARD/} is special; @ref{Output Section
3719
Discarding}.
3720
 
3721
@node Output Section Address
3722
@subsection Output Section Address
3723
@cindex address, section
3724
@cindex section address
3725
The @var{address} is an expression for the VMA (the virtual memory
3726
address) of the output section.  This address is optional, but if it
3727
is provided then the output address will be set exactly as specified.
3728
 
3729
If the output address is not specified then one will be chosen for the
3730
section, based on the heuristic below.  This address will be adjusted
3731
to fit the alignment requirement of the output section.  The
3732
alignment requirement is the strictest alignment of any input section
3733
contained within the output section.
3734
 
3735
The output section address heuristic is as follows:
3736
 
3737
@itemize @bullet
3738
@item
3739
If an output memory @var{region} is set for the section then it
3740
is added to this region and its address will be the next free address
3741
in that region.
3742
 
3743
@item
3744
If the MEMORY command has been used to create a list of memory
3745
regions then the first region which has attributes compatible with the
3746
section is selected to contain it.  The section's output address will
3747
be the next free address in that region; @ref{MEMORY}.
3748
 
3749
@item
3750
If no memory regions were specified, or none match the section then
3751
the output address will be based on the current value of the location
3752
counter.
3753
@end itemize
3754
 
3755
@noindent
3756
For example:
3757
 
3758
@smallexample
3759
.text . : @{ *(.text) @}
3760
@end smallexample
3761
 
3762
@noindent
3763
and
3764
 
3765
@smallexample
3766
.text : @{ *(.text) @}
3767
@end smallexample
3768
 
3769
@noindent
3770
are subtly different.  The first will set the address of the
3771
@samp{.text} output section to the current value of the location
3772
counter.  The second will set it to the current value of the location
3773
counter aligned to the strictest alignment of any of the @samp{.text}
3774
input sections.
3775
 
3776
The @var{address} may be an arbitrary expression; @ref{Expressions}.
3777
For example, if you want to align the section on a 0x10 byte boundary,
3778
so that the lowest four bits of the section address are zero, you could
3779
do something like this:
3780
@smallexample
3781
.text ALIGN(0x10) : @{ *(.text) @}
3782
@end smallexample
3783
@noindent
3784
This works because @code{ALIGN} returns the current location counter
3785
aligned upward to the specified value.
3786
 
3787
Specifying @var{address} for a section will change the value of the
3788
location counter, provided that the section is non-empty.  (Empty
3789
sections are ignored).
3790
 
3791
@node Input Section
3792
@subsection Input Section Description
3793
@cindex input sections
3794
@cindex mapping input sections to output sections
3795
The most common output section command is an input section description.
3796
 
3797
The input section description is the most basic linker script operation.
3798
You use output sections to tell the linker how to lay out your program
3799
in memory.  You use input section descriptions to tell the linker how to
3800
map the input files into your memory layout.
3801
 
3802
@menu
3803
* Input Section Basics::        Input section basics
3804
* Input Section Wildcards::     Input section wildcard patterns
3805
* Input Section Common::        Input section for common symbols
3806
* Input Section Keep::          Input section and garbage collection
3807
* Input Section Example::       Input section example
3808
@end menu
3809
 
3810
@node Input Section Basics
3811
@subsubsection Input Section Basics
3812
@cindex input section basics
3813
An input section description consists of a file name optionally followed
3814
by a list of section names in parentheses.
3815
 
3816
The file name and the section name may be wildcard patterns, which we
3817
describe further below (@pxref{Input Section Wildcards}).
3818
 
3819
The most common input section description is to include all input
3820
sections with a particular name in the output section.  For example, to
3821
include all input @samp{.text} sections, you would write:
3822
@smallexample
3823
*(.text)
3824
@end smallexample
3825
@noindent
3826
Here the @samp{*} is a wildcard which matches any file name.  To exclude a list
3827
of files from matching the file name wildcard, EXCLUDE_FILE may be used to
3828
match all files except the ones specified in the EXCLUDE_FILE list.  For
3829
example:
3830
@smallexample
3831
*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors)
3832
@end smallexample
3833
will cause all .ctors sections from all files except @file{crtend.o} and
3834
@file{otherfile.o} to be included.
3835
 
3836
There are two ways to include more than one section:
3837
@smallexample
3838
*(.text .rdata)
3839
*(.text) *(.rdata)
3840
@end smallexample
3841
@noindent
3842
The difference between these is the order in which the @samp{.text} and
3843
@samp{.rdata} input sections will appear in the output section.  In the
3844
first example, they will be intermingled, appearing in the same order as
3845
they are found in the linker input.  In the second example, all
3846
@samp{.text} input sections will appear first, followed by all
3847
@samp{.rdata} input sections.
3848
 
3849
You can specify a file name to include sections from a particular file.
3850
You would do this if one or more of your files contain special data that
3851
needs to be at a particular location in memory.  For example:
3852
@smallexample
3853
data.o(.data)
3854
@end smallexample
3855
 
3856
You can also specify files within archives by writing a pattern
3857
matching the archive, a colon, then the pattern matching the file,
3858
with no whitespace around the colon.
3859
 
3860
@table @samp
3861
@item archive:file
3862
matches file within archive
3863
@item archive:
3864
matches the whole archive
3865
@item :file
3866
matches file but not one in an archive
3867
@end table
3868
 
3869
Either one or both of @samp{archive} and @samp{file} can contain shell
3870
wildcards.  On DOS based file systems, the linker will assume that a
3871
single letter followed by a colon is a drive specifier, so
3872
@samp{c:myfile.o} is a simple file specification, not @samp{myfile.o}
3873
within an archive called @samp{c}.  @samp{archive:file} filespecs may
3874
also be used within an @code{EXCLUDE_FILE} list, but may not appear in
3875
other linker script contexts.  For instance, you cannot extract a file
3876
from an archive by using @samp{archive:file} in an @code{INPUT}
3877
command.
3878
 
3879
If you use a file name without a list of sections, then all sections in
3880
the input file will be included in the output section.  This is not
3881
commonly done, but it may by useful on occasion.  For example:
3882
@smallexample
3883
data.o
3884
@end smallexample
3885
 
3886
When you use a file name which is not an @samp{archive:file} specifier
3887
and does not contain any wild card
3888
characters, the linker will first see if you also specified the file
3889
name on the linker command line or in an @code{INPUT} command.  If you
3890
did not, the linker will attempt to open the file as an input file, as
3891
though it appeared on the command line.  Note that this differs from an
3892
@code{INPUT} command, because the linker will not search for the file in
3893
the archive search path.
3894
 
3895
@node Input Section Wildcards
3896
@subsubsection Input Section Wildcard Patterns
3897
@cindex input section wildcards
3898
@cindex wildcard file name patterns
3899
@cindex file name wildcard patterns
3900
@cindex section name wildcard patterns
3901
In an input section description, either the file name or the section
3902
name or both may be wildcard patterns.
3903
 
3904
The file name of @samp{*} seen in many examples is a simple wildcard
3905
pattern for the file name.
3906
 
3907
The wildcard patterns are like those used by the Unix shell.
3908
 
3909
@table @samp
3910
@item *
3911
matches any number of characters
3912
@item ?
3913
matches any single character
3914
@item [@var{chars}]
3915
matches a single instance of any of the @var{chars}; the @samp{-}
3916
character may be used to specify a range of characters, as in
3917
@samp{[a-z]} to match any lower case letter
3918
@item \
3919
quotes the following character
3920
@end table
3921
 
3922
When a file name is matched with a wildcard, the wildcard characters
3923
will not match a @samp{/} character (used to separate directory names on
3924
Unix).  A pattern consisting of a single @samp{*} character is an
3925
exception; it will always match any file name, whether it contains a
3926
@samp{/} or not.  In a section name, the wildcard characters will match
3927
a @samp{/} character.
3928
 
3929
File name wildcard patterns only match files which are explicitly
3930
specified on the command line or in an @code{INPUT} command.  The linker
3931
does not search directories to expand wildcards.
3932
 
3933
If a file name matches more than one wildcard pattern, or if a file name
3934
appears explicitly and is also matched by a wildcard pattern, the linker
3935
will use the first match in the linker script.  For example, this
3936
sequence of input section descriptions is probably in error, because the
3937
@file{data.o} rule will not be used:
3938
@smallexample
3939
.data : @{ *(.data) @}
3940
.data1 : @{ data.o(.data) @}
3941
@end smallexample
3942
 
3943
@cindex SORT_BY_NAME
3944
Normally, the linker will place files and sections matched by wildcards
3945
in the order in which they are seen during the link.  You can change
3946
this by using the @code{SORT_BY_NAME} keyword, which appears before a wildcard
3947
pattern in parentheses (e.g., @code{SORT_BY_NAME(.text*)}).  When the
3948
@code{SORT_BY_NAME} keyword is used, the linker will sort the files or sections
3949
into ascending order by name before placing them in the output file.
3950
 
3951
@cindex SORT_BY_ALIGNMENT
3952
@code{SORT_BY_ALIGNMENT} is very similar to @code{SORT_BY_NAME}. The
3953
difference is @code{SORT_BY_ALIGNMENT} will sort sections into
3954
ascending order by alignment before placing them in the output file.
3955
 
3956
@cindex SORT_BY_INIT_PRIORITY
3957
@code{SORT_BY_INIT_PRIORITY} is very similar to @code{SORT_BY_NAME}. The
3958
difference is @code{SORT_BY_INIT_PRIORITY} will sort sections into
3959
ascending order by numerical value of the GCC init_priority attribute
3960
encoded in the section name before placing them in the output file.
3961
 
3962
@cindex SORT
3963
@code{SORT} is an alias for @code{SORT_BY_NAME}.
3964
 
3965
When there are nested section sorting commands in linker script, there
3966
can be at most 1 level of nesting for section sorting commands.
3967
 
3968
@enumerate
3969
@item
3970
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
3971
It will sort the input sections by name first, then by alignment if 2
3972
sections have the same name.
3973
@item
3974
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
3975
It will sort the input sections by alignment first, then by name if 2
3976
sections have the same alignment.
3977
@item
3978
@code{SORT_BY_NAME} (@code{SORT_BY_NAME} (wildcard section pattern)) is
3979
treated the same as @code{SORT_BY_NAME} (wildcard section pattern).
3980
@item
3981
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern))
3982
is treated the same as @code{SORT_BY_ALIGNMENT} (wildcard section pattern).
3983
@item
3984
All other nested section sorting commands are invalid.
3985
@end enumerate
3986
 
3987
When both command line section sorting option and linker script
3988
section sorting command are used, section sorting command always
3989
takes precedence over the command line option.
3990
 
3991
If the section sorting command in linker script isn't nested, the
3992
command line option will make the section sorting command to be
3993
treated as nested sorting command.
3994
 
3995
@enumerate
3996
@item
3997
@code{SORT_BY_NAME} (wildcard section pattern ) with
3998
@option{--sort-sections alignment} is equivalent to
3999
@code{SORT_BY_NAME} (@code{SORT_BY_ALIGNMENT} (wildcard section pattern)).
4000
@item
4001
@code{SORT_BY_ALIGNMENT} (wildcard section pattern) with
4002
@option{--sort-section name} is equivalent to
4003
@code{SORT_BY_ALIGNMENT} (@code{SORT_BY_NAME} (wildcard section pattern)).
4004
@end enumerate
4005
 
4006
If the section sorting command in linker script is nested, the
4007
command line option will be ignored.
4008
 
4009
If you ever get confused about where input sections are going, use the
4010
@samp{-M} linker option to generate a map file.  The map file shows
4011
precisely how input sections are mapped to output sections.
4012
 
4013
This example shows how wildcard patterns might be used to partition
4014
files.  This linker script directs the linker to place all @samp{.text}
4015
sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
4016
The linker will place the @samp{.data} section from all files beginning
4017
with an upper case character in @samp{.DATA}; for all other files, the
4018
linker will place the @samp{.data} section in @samp{.data}.
4019
@smallexample
4020
@group
4021
SECTIONS @{
4022
  .text : @{ *(.text) @}
4023
  .DATA : @{ [A-Z]*(.data) @}
4024
  .data : @{ *(.data) @}
4025
  .bss : @{ *(.bss) @}
4026
@}
4027
@end group
4028
@end smallexample
4029
 
4030
@node Input Section Common
4031
@subsubsection Input Section for Common Symbols
4032
@cindex common symbol placement
4033
@cindex uninitialized data placement
4034
A special notation is needed for common symbols, because in many object
4035
file formats common symbols do not have a particular input section.  The
4036
linker treats common symbols as though they are in an input section
4037
named @samp{COMMON}.
4038
 
4039
You may use file names with the @samp{COMMON} section just as with any
4040
other input sections.  You can use this to place common symbols from a
4041
particular input file in one section while common symbols from other
4042
input files are placed in another section.
4043
 
4044
In most cases, common symbols in input files will be placed in the
4045
@samp{.bss} section in the output file.  For example:
4046
@smallexample
4047
.bss @{ *(.bss) *(COMMON) @}
4048
@end smallexample
4049
 
4050
@cindex scommon section
4051
@cindex small common symbols
4052
Some object file formats have more than one type of common symbol.  For
4053
example, the MIPS ELF object file format distinguishes standard common
4054
symbols and small common symbols.  In this case, the linker will use a
4055
different special section name for other types of common symbols.  In
4056
the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
4057
symbols and @samp{.scommon} for small common symbols.  This permits you
4058
to map the different types of common symbols into memory at different
4059
locations.
4060
 
4061
@cindex [COMMON]
4062
You will sometimes see @samp{[COMMON]} in old linker scripts.  This
4063
notation is now considered obsolete.  It is equivalent to
4064
@samp{*(COMMON)}.
4065
 
4066
@node Input Section Keep
4067
@subsubsection Input Section and Garbage Collection
4068
@cindex KEEP
4069
@cindex garbage collection
4070
When link-time garbage collection is in use (@samp{--gc-sections}),
4071
it is often useful to mark sections that should not be eliminated.
4072
This is accomplished by surrounding an input section's wildcard entry
4073
with @code{KEEP()}, as in @code{KEEP(*(.init))} or
4074
@code{KEEP(SORT_BY_NAME(*)(.ctors))}.
4075
 
4076
@node Input Section Example
4077
@subsubsection Input Section Example
4078
The following example is a complete linker script.  It tells the linker
4079
to read all of the sections from file @file{all.o} and place them at the
4080
start of output section @samp{outputa} which starts at location
4081
@samp{0x10000}.  All of section @samp{.input1} from file @file{foo.o}
4082
follows immediately, in the same output section.  All of section
4083
@samp{.input2} from @file{foo.o} goes into output section
4084
@samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
4085
All of the remaining @samp{.input1} and @samp{.input2} sections from any
4086
files are written to output section @samp{outputc}.
4087
 
4088
@smallexample
4089
@group
4090
SECTIONS @{
4091
  outputa 0x10000 :
4092
    @{
4093
    all.o
4094
    foo.o (.input1)
4095
    @}
4096
@end group
4097
@group
4098
  outputb :
4099
    @{
4100
    foo.o (.input2)
4101
    foo1.o (.input1)
4102
    @}
4103
@end group
4104
@group
4105
  outputc :
4106
    @{
4107
    *(.input1)
4108
    *(.input2)
4109
    @}
4110
@}
4111
@end group
4112
@end smallexample
4113
 
4114
@node Output Section Data
4115
@subsection Output Section Data
4116
@cindex data
4117
@cindex section data
4118
@cindex output section data
4119
@kindex BYTE(@var{expression})
4120
@kindex SHORT(@var{expression})
4121
@kindex LONG(@var{expression})
4122
@kindex QUAD(@var{expression})
4123
@kindex SQUAD(@var{expression})
4124
You can include explicit bytes of data in an output section by using
4125
@code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
4126
an output section command.  Each keyword is followed by an expression in
4127
parentheses providing the value to store (@pxref{Expressions}).  The
4128
value of the expression is stored at the current value of the location
4129
counter.
4130
 
4131
The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
4132
store one, two, four, and eight bytes (respectively).  After storing the
4133
bytes, the location counter is incremented by the number of bytes
4134
stored.
4135
 
4136
For example, this will store the byte 1 followed by the four byte value
4137
of the symbol @samp{addr}:
4138
@smallexample
4139
BYTE(1)
4140
LONG(addr)
4141
@end smallexample
4142
 
4143
When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
4144
same; they both store an 8 byte, or 64 bit, value.  When both host and
4145
target are 32 bits, an expression is computed as 32 bits.  In this case
4146
@code{QUAD} stores a 32 bit value zero extended to 64 bits, and
4147
@code{SQUAD} stores a 32 bit value sign extended to 64 bits.
4148
 
4149
If the object file format of the output file has an explicit endianness,
4150
which is the normal case, the value will be stored in that endianness.
4151
When the object file format does not have an explicit endianness, as is
4152
true of, for example, S-records, the value will be stored in the
4153
endianness of the first input object file.
4154
 
4155
Note---these commands only work inside a section description and not
4156
between them, so the following will produce an error from the linker:
4157
@smallexample
4158
SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
4159
@end smallexample
4160
whereas this will work:
4161
@smallexample
4162
SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
4163
@end smallexample
4164
 
4165
@kindex FILL(@var{expression})
4166
@cindex holes, filling
4167
@cindex unspecified memory
4168
You may use the @code{FILL} command to set the fill pattern for the
4169
current section.  It is followed by an expression in parentheses.  Any
4170
otherwise unspecified regions of memory within the section (for example,
4171
gaps left due to the required alignment of input sections) are filled
4172
with the value of the expression, repeated as
4173
necessary.  A @code{FILL} statement covers memory locations after the
4174
point at which it occurs in the section definition; by including more
4175
than one @code{FILL} statement, you can have different fill patterns in
4176
different parts of an output section.
4177
 
4178
This example shows how to fill unspecified regions of memory with the
4179
value @samp{0x90}:
4180
@smallexample
4181
FILL(0x90909090)
4182
@end smallexample
4183
 
4184
The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
4185
section attribute, but it only affects the
4186
part of the section following the @code{FILL} command, rather than the
4187
entire section.  If both are used, the @code{FILL} command takes
4188
precedence.  @xref{Output Section Fill}, for details on the fill
4189
expression.
4190
 
4191
@node Output Section Keywords
4192
@subsection Output Section Keywords
4193
There are a couple of keywords which can appear as output section
4194
commands.
4195
 
4196
@table @code
4197
@kindex CREATE_OBJECT_SYMBOLS
4198
@cindex input filename symbols
4199
@cindex filename symbols
4200
@item CREATE_OBJECT_SYMBOLS
4201
The command tells the linker to create a symbol for each input file.
4202
The name of each symbol will be the name of the corresponding input
4203
file.  The section of each symbol will be the output section in which
4204
the @code{CREATE_OBJECT_SYMBOLS} command appears.
4205
 
4206
This is conventional for the a.out object file format.  It is not
4207
normally used for any other object file format.
4208
 
4209
@kindex CONSTRUCTORS
4210
@cindex C++ constructors, arranging in link
4211
@cindex constructors, arranging in link
4212
@item CONSTRUCTORS
4213
When linking using the a.out object file format, the linker uses an
4214
unusual set construct to support C++ global constructors and
4215
destructors.  When linking object file formats which do not support
4216
arbitrary sections, such as ECOFF and XCOFF, the linker will
4217
automatically recognize C++ global constructors and destructors by name.
4218
For these object file formats, the @code{CONSTRUCTORS} command tells the
4219
linker to place constructor information in the output section where the
4220
@code{CONSTRUCTORS} command appears.  The @code{CONSTRUCTORS} command is
4221
ignored for other object file formats.
4222
 
4223
The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
4224
constructors, and the symbol @w{@code{__CTOR_END__}} marks the end.
4225
Similarly, @w{@code{__DTOR_LIST__}} and @w{@code{__DTOR_END__}} mark
4226
the start and end of the global destructors.  The
4227
first word in the list is the number of entries, followed by the address
4228
of each constructor or destructor, followed by a zero word.  The
4229
compiler must arrange to actually run the code.  For these object file
4230
formats @sc{gnu} C++ normally calls constructors from a subroutine
4231
@code{__main}; a call to @code{__main} is automatically inserted into
4232
the startup code for @code{main}.  @sc{gnu} C++ normally runs
4233
destructors either by using @code{atexit}, or directly from the function
4234
@code{exit}.
4235
 
4236
For object file formats such as @code{COFF} or @code{ELF} which support
4237
arbitrary section names, @sc{gnu} C++ will normally arrange to put the
4238
addresses of global constructors and destructors into the @code{.ctors}
4239
and @code{.dtors} sections.  Placing the following sequence into your
4240
linker script will build the sort of table which the @sc{gnu} C++
4241
runtime code expects to see.
4242
 
4243
@smallexample
4244
      __CTOR_LIST__ = .;
4245
      LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
4246
      *(.ctors)
4247
      LONG(0)
4248
      __CTOR_END__ = .;
4249
      __DTOR_LIST__ = .;
4250
      LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
4251
      *(.dtors)
4252
      LONG(0)
4253
      __DTOR_END__ = .;
4254
@end smallexample
4255
 
4256
If you are using the @sc{gnu} C++ support for initialization priority,
4257
which provides some control over the order in which global constructors
4258
are run, you must sort the constructors at link time to ensure that they
4259
are executed in the correct order.  When using the @code{CONSTRUCTORS}
4260
command, use @samp{SORT_BY_NAME(CONSTRUCTORS)} instead.  When using the
4261
@code{.ctors} and @code{.dtors} sections, use @samp{*(SORT_BY_NAME(.ctors))} and
4262
@samp{*(SORT_BY_NAME(.dtors))} instead of just @samp{*(.ctors)} and
4263
@samp{*(.dtors)}.
4264
 
4265
Normally the compiler and linker will handle these issues automatically,
4266
and you will not need to concern yourself with them.  However, you may
4267
need to consider this if you are using C++ and writing your own linker
4268
scripts.
4269
 
4270
@end table
4271
 
4272
@node Output Section Discarding
4273
@subsection Output Section Discarding
4274
@cindex discarding sections
4275
@cindex sections, discarding
4276
@cindex removing sections
4277
The linker will not create output sections with no contents.  This is
4278
for convenience when referring to input sections that may or may not
4279
be present in any of the input files.  For example:
4280
@smallexample
4281
.foo : @{ *(.foo) @}
4282
@end smallexample
4283
@noindent
4284
will only create a @samp{.foo} section in the output file if there is a
4285
@samp{.foo} section in at least one input file, and if the input
4286
sections are not all empty.  Other link script directives that allocate
4287
space in an output section will also create the output section.
4288
 
4289
The linker will ignore address assignments (@pxref{Output Section Address})
4290
on discarded output sections, except when the linker script defines
4291
symbols in the output section.  In that case the linker will obey
4292
the address assignments, possibly advancing dot even though the
4293
section is discarded.
4294
 
4295
@cindex /DISCARD/
4296
The special output section name @samp{/DISCARD/} may be used to discard
4297
input sections.  Any input sections which are assigned to an output
4298
section named @samp{/DISCARD/} are not included in the output file.
4299
 
4300
@node Output Section Attributes
4301
@subsection Output Section Attributes
4302
@cindex output section attributes
4303
We showed above that the full description of an output section looked
4304
like this:
4305
 
4306
@smallexample
4307
@group
4308
@var{section} [@var{address}] [(@var{type})] :
4309
  [AT(@var{lma})]
4310
  [ALIGN(@var{section_align})]
4311
  [SUBALIGN(@var{subsection_align})]
4312
  [@var{constraint}]
4313
  @{
4314
    @var{output-section-command}
4315
    @var{output-section-command}
4316
    @dots{}
4317
  @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
4318
@end group
4319
@end smallexample
4320
 
4321
We've already described @var{section}, @var{address}, and
4322
@var{output-section-command}.  In this section we will describe the
4323
remaining section attributes.
4324
 
4325
@menu
4326
* Output Section Type::         Output section type
4327
* Output Section LMA::          Output section LMA
4328
* Forced Output Alignment::     Forced Output Alignment
4329
* Forced Input Alignment::      Forced Input Alignment
4330
* Output Section Constraint::   Output section constraint
4331
* Output Section Region::       Output section region
4332
* Output Section Phdr::         Output section phdr
4333
* Output Section Fill::         Output section fill
4334
@end menu
4335
 
4336
@node Output Section Type
4337
@subsubsection Output Section Type
4338
Each output section may have a type.  The type is a keyword in
4339
parentheses.  The following types are defined:
4340
 
4341
@table @code
4342
@item NOLOAD
4343
The section should be marked as not loadable, so that it will not be
4344
loaded into memory when the program is run.
4345
@item DSECT
4346
@itemx COPY
4347
@itemx INFO
4348
@itemx OVERLAY
4349
These type names are supported for backward compatibility, and are
4350
rarely used.  They all have the same effect: the section should be
4351
marked as not allocatable, so that no memory is allocated for the
4352
section when the program is run.
4353
@end table
4354
 
4355
@kindex NOLOAD
4356
@cindex prevent unnecessary loading
4357
@cindex loading, preventing
4358
The linker normally sets the attributes of an output section based on
4359
the input sections which map into it.  You can override this by using
4360
the section type.  For example, in the script sample below, the
4361
@samp{ROM} section is addressed at memory location @samp{0} and does not
4362
need to be loaded when the program is run.
4363
@smallexample
4364
@group
4365
SECTIONS @{
4366
  ROM 0 (NOLOAD) : @{ @dots{} @}
4367
  @dots{}
4368
@}
4369
@end group
4370
@end smallexample
4371
 
4372
@node Output Section LMA
4373
@subsubsection Output Section LMA
4374
@kindex AT>@var{lma_region}
4375
@kindex AT(@var{lma})
4376
@cindex load address
4377
@cindex section load address
4378
Every section has a virtual address (VMA) and a load address (LMA); see
4379
@ref{Basic Script Concepts}.  The virtual address is specified by the
4380
@pxref{Output Section Address} described earlier.  The load address is
4381
specified by the @code{AT} or @code{AT>} keywords.  Specifying a load
4382
address is optional.
4383
 
4384
The @code{AT} keyword takes an expression as an argument.  This
4385
specifies the exact load address of the section.  The @code{AT>} keyword
4386
takes the name of a memory region as an argument.  @xref{MEMORY}.  The
4387
load address of the section is set to the next free address in the
4388
region, aligned to the section's alignment requirements.
4389
 
4390
If neither @code{AT} nor @code{AT>} is specified for an allocatable
4391
section, the linker will use the following heuristic to determine the
4392
load address:
4393
 
4394
@itemize @bullet
4395
@item
4396
If the section has a specific VMA address, then this is used as
4397
the LMA address as well.
4398
 
4399
@item
4400
If the section is not allocatable then its LMA is set to its VMA.
4401
 
4402
@item
4403
Otherwise if a memory region can be found that is compatible
4404
with the current section, and this region contains at least one
4405
section, then the LMA is set so the difference between the
4406
VMA and LMA is the same as the difference between the VMA and LMA of
4407
the last section in the located region.
4408
 
4409
@item
4410
If no memory regions have been declared then a default region
4411
that covers the entire address space is used in the previous step.
4412
 
4413
@item
4414
If no suitable region could be found, or there was no previous
4415
section then the LMA is set equal to the VMA.
4416
@end itemize
4417
 
4418
@cindex ROM initialized data
4419
@cindex initialized data in ROM
4420
This feature is designed to make it easy to build a ROM image.  For
4421
example, the following linker script creates three output sections: one
4422
called @samp{.text}, which starts at @code{0x1000}, one called
4423
@samp{.mdata}, which is loaded at the end of the @samp{.text} section
4424
even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
4425
uninitialized data at address @code{0x3000}.  The symbol @code{_data} is
4426
defined with the value @code{0x2000}, which shows that the location
4427
counter holds the VMA value, not the LMA value.
4428
 
4429
@smallexample
4430
@group
4431
SECTIONS
4432
  @{
4433
  .text 0x1000 : @{ *(.text) _etext = . ; @}
4434
  .mdata 0x2000 :
4435
    AT ( ADDR (.text) + SIZEOF (.text) )
4436
    @{ _data = . ; *(.data); _edata = . ;  @}
4437
  .bss 0x3000 :
4438
    @{ _bstart = . ;  *(.bss) *(COMMON) ; _bend = . ;@}
4439
@}
4440
@end group
4441
@end smallexample
4442
 
4443
The run-time initialization code for use with a program generated with
4444
this linker script would include something like the following, to copy
4445
the initialized data from the ROM image to its runtime address.  Notice
4446
how this code takes advantage of the symbols defined by the linker
4447
script.
4448
 
4449
@smallexample
4450
@group
4451
extern char _etext, _data, _edata, _bstart, _bend;
4452
char *src = &_etext;
4453
char *dst = &_data;
4454
 
4455
/* ROM has data at end of text; copy it.  */
4456
while (dst < &_edata)
4457
  *dst++ = *src++;
4458
 
4459
/* Zero bss.  */
4460
for (dst = &_bstart; dst< &_bend; dst++)
4461
  *dst = 0;
4462
@end group
4463
@end smallexample
4464
 
4465
@node Forced Output Alignment
4466
@subsubsection Forced Output Alignment
4467
@kindex ALIGN(@var{section_align})
4468
@cindex forcing output section alignment
4469
@cindex output section alignment
4470
You can increase an output section's alignment by using ALIGN.
4471
 
4472
@node Forced Input Alignment
4473
@subsubsection Forced Input Alignment
4474
@kindex SUBALIGN(@var{subsection_align})
4475
@cindex forcing input section alignment
4476
@cindex input section alignment
4477
You can force input section alignment within an output section by using
4478
SUBALIGN.  The value specified overrides any alignment given by input
4479
sections, whether larger or smaller.
4480
 
4481
@node Output Section Constraint
4482
@subsubsection Output Section Constraint
4483
@kindex ONLY_IF_RO
4484
@kindex ONLY_IF_RW
4485
@cindex constraints on output sections
4486
You can specify that an output section should only be created if all
4487
of its input sections are read-only or all of its input sections are
4488
read-write by using the keyword @code{ONLY_IF_RO} and
4489
@code{ONLY_IF_RW} respectively.
4490
 
4491
@node Output Section Region
4492
@subsubsection Output Section Region
4493
@kindex >@var{region}
4494
@cindex section, assigning to memory region
4495
@cindex memory regions and sections
4496
You can assign a section to a previously defined region of memory by
4497
using @samp{>@var{region}}.  @xref{MEMORY}.
4498
 
4499
Here is a simple example:
4500
@smallexample
4501
@group
4502
MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
4503
SECTIONS @{ ROM : @{ *(.text) @} >rom @}
4504
@end group
4505
@end smallexample
4506
 
4507
@node Output Section Phdr
4508
@subsubsection Output Section Phdr
4509
@kindex :@var{phdr}
4510
@cindex section, assigning to program header
4511
@cindex program headers and sections
4512
You can assign a section to a previously defined program segment by
4513
using @samp{:@var{phdr}}.  @xref{PHDRS}.  If a section is assigned to
4514
one or more segments, then all subsequent allocated sections will be
4515
assigned to those segments as well, unless they use an explicitly
4516
@code{:@var{phdr}} modifier.  You can use @code{:NONE} to tell the
4517
linker to not put the section in any segment at all.
4518
 
4519
Here is a simple example:
4520
@smallexample
4521
@group
4522
PHDRS @{ text PT_LOAD ; @}
4523
SECTIONS @{ .text : @{ *(.text) @} :text @}
4524
@end group
4525
@end smallexample
4526
 
4527
@node Output Section Fill
4528
@subsubsection Output Section Fill
4529
@kindex =@var{fillexp}
4530
@cindex section fill pattern
4531
@cindex fill pattern, entire section
4532
You can set the fill pattern for an entire section by using
4533
@samp{=@var{fillexp}}.  @var{fillexp} is an expression
4534
(@pxref{Expressions}).  Any otherwise unspecified regions of memory
4535
within the output section (for example, gaps left due to the required
4536
alignment of input sections) will be filled with the value, repeated as
4537
necessary.  If the fill expression is a simple hex number, ie. a string
4538
of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
4539
an arbitrarily long sequence of hex digits can be used to specify the
4540
fill pattern;  Leading zeros become part of the pattern too.  For all
4541
other cases, including extra parentheses or a unary @code{+}, the fill
4542
pattern is the four least significant bytes of the value of the
4543
expression.  In all cases, the number is big-endian.
4544
 
4545
You can also change the fill value with a @code{FILL} command in the
4546
output section commands; (@pxref{Output Section Data}).
4547
 
4548
Here is a simple example:
4549
@smallexample
4550
@group
4551
SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
4552
@end group
4553
@end smallexample
4554
 
4555
@node Overlay Description
4556
@subsection Overlay Description
4557
@kindex OVERLAY
4558
@cindex overlays
4559
An overlay description provides an easy way to describe sections which
4560
are to be loaded as part of a single memory image but are to be run at
4561
the same memory address.  At run time, some sort of overlay manager will
4562
copy the overlaid sections in and out of the runtime memory address as
4563
required, perhaps by simply manipulating addressing bits.  This approach
4564
can be useful, for example, when a certain region of memory is faster
4565
than another.
4566
 
4567
Overlays are described using the @code{OVERLAY} command.  The
4568
@code{OVERLAY} command is used within a @code{SECTIONS} command, like an
4569
output section description.  The full syntax of the @code{OVERLAY}
4570
command is as follows:
4571
@smallexample
4572
@group
4573
OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
4574
  @{
4575
    @var{secname1}
4576
      @{
4577
        @var{output-section-command}
4578
        @var{output-section-command}
4579
        @dots{}
4580
      @} [:@var{phdr}@dots{}] [=@var{fill}]
4581
    @var{secname2}
4582
      @{
4583
        @var{output-section-command}
4584
        @var{output-section-command}
4585
        @dots{}
4586
      @} [:@var{phdr}@dots{}] [=@var{fill}]
4587
    @dots{}
4588
  @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}]
4589
@end group
4590
@end smallexample
4591
 
4592
Everything is optional except @code{OVERLAY} (a keyword), and each
4593
section must have a name (@var{secname1} and @var{secname2} above).  The
4594
section definitions within the @code{OVERLAY} construct are identical to
4595
those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}),
4596
except that no addresses and no memory regions may be defined for
4597
sections within an @code{OVERLAY}.
4598
 
4599
The sections are all defined with the same starting address.  The load
4600
addresses of the sections are arranged such that they are consecutive in
4601
memory starting at the load address used for the @code{OVERLAY} as a
4602
whole (as with normal section definitions, the load address is optional,
4603
and defaults to the start address; the start address is also optional,
4604
and defaults to the current value of the location counter).
4605
 
4606
If the @code{NOCROSSREFS} keyword is used, and there any references
4607
among the sections, the linker will report an error.  Since the sections
4608
all run at the same address, it normally does not make sense for one
4609
section to refer directly to another.  @xref{Miscellaneous Commands,
4610
NOCROSSREFS}.
4611
 
4612
For each section within the @code{OVERLAY}, the linker automatically
4613
provides two symbols.  The symbol @code{__load_start_@var{secname}} is
4614
defined as the starting load address of the section.  The symbol
4615
@code{__load_stop_@var{secname}} is defined as the final load address of
4616
the section.  Any characters within @var{secname} which are not legal
4617
within C identifiers are removed.  C (or assembler) code may use these
4618
symbols to move the overlaid sections around as necessary.
4619
 
4620
At the end of the overlay, the value of the location counter is set to
4621
the start address of the overlay plus the size of the largest section.
4622
 
4623
Here is an example.  Remember that this would appear inside a
4624
@code{SECTIONS} construct.
4625
@smallexample
4626
@group
4627
  OVERLAY 0x1000 : AT (0x4000)
4628
   @{
4629
     .text0 @{ o1/*.o(.text) @}
4630
     .text1 @{ o2/*.o(.text) @}
4631
   @}
4632
@end group
4633
@end smallexample
4634
@noindent
4635
This will define both @samp{.text0} and @samp{.text1} to start at
4636
address 0x1000.  @samp{.text0} will be loaded at address 0x4000, and
4637
@samp{.text1} will be loaded immediately after @samp{.text0}.  The
4638
following symbols will be defined if referenced: @code{__load_start_text0},
4639
@code{__load_stop_text0}, @code{__load_start_text1},
4640
@code{__load_stop_text1}.
4641
 
4642
C code to copy overlay @code{.text1} into the overlay area might look
4643
like the following.
4644
 
4645
@smallexample
4646
@group
4647
  extern char __load_start_text1, __load_stop_text1;
4648
  memcpy ((char *) 0x1000, &__load_start_text1,
4649
          &__load_stop_text1 - &__load_start_text1);
4650
@end group
4651
@end smallexample
4652
 
4653
Note that the @code{OVERLAY} command is just syntactic sugar, since
4654
everything it does can be done using the more basic commands.  The above
4655
example could have been written identically as follows.
4656
 
4657
@smallexample
4658
@group
4659
  .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
4660
  PROVIDE (__load_start_text0 = LOADADDR (.text0));
4661
  PROVIDE (__load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0));
4662
  .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
4663
  PROVIDE (__load_start_text1 = LOADADDR (.text1));
4664
  PROVIDE (__load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1));
4665
  . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
4666
@end group
4667
@end smallexample
4668
 
4669
@node MEMORY
4670
@section MEMORY Command
4671
@kindex MEMORY
4672
@cindex memory regions
4673
@cindex regions of memory
4674
@cindex allocating memory
4675
@cindex discontinuous memory
4676
The linker's default configuration permits allocation of all available
4677
memory.  You can override this by using the @code{MEMORY} command.
4678
 
4679
The @code{MEMORY} command describes the location and size of blocks of
4680
memory in the target.  You can use it to describe which memory regions
4681
may be used by the linker, and which memory regions it must avoid.  You
4682
can then assign sections to particular memory regions.  The linker will
4683
set section addresses based on the memory regions, and will warn about
4684
regions that become too full.  The linker will not shuffle sections
4685
around to fit into the available regions.
4686
 
4687
A linker script may contain at most one use of the @code{MEMORY}
4688
command.  However, you can define as many blocks of memory within it as
4689
you wish.  The syntax is:
4690
@smallexample
4691
@group
4692
MEMORY
4693
  @{
4694
    @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
4695
    @dots{}
4696
  @}
4697
@end group
4698
@end smallexample
4699
 
4700
The @var{name} is a name used in the linker script to refer to the
4701
region.  The region name has no meaning outside of the linker script.
4702
Region names are stored in a separate name space, and will not conflict
4703
with symbol names, file names, or section names.  Each memory region
4704
must have a distinct name within the @code{MEMORY} command.  However you can
4705
add later alias names to existing memory regions with the @ref{REGION_ALIAS}
4706
command.
4707
 
4708
@cindex memory region attributes
4709
The @var{attr} string is an optional list of attributes that specify
4710
whether to use a particular memory region for an input section which is
4711
not explicitly mapped in the linker script.  As described in
4712
@ref{SECTIONS}, if you do not specify an output section for some input
4713
section, the linker will create an output section with the same name as
4714
the input section.  If you define region attributes, the linker will use
4715
them to select the memory region for the output section that it creates.
4716
 
4717
The @var{attr} string must consist only of the following characters:
4718
@table @samp
4719
@item R
4720
Read-only section
4721
@item W
4722
Read/write section
4723
@item X
4724
Executable section
4725
@item A
4726
Allocatable section
4727
@item I
4728
Initialized section
4729
@item L
4730
Same as @samp{I}
4731
@item !
4732
Invert the sense of any of the attributes that follow
4733
@end table
4734
 
4735
If a unmapped section matches any of the listed attributes other than
4736
@samp{!}, it will be placed in the memory region.  The @samp{!}
4737
attribute reverses this test, so that an unmapped section will be placed
4738
in the memory region only if it does not match any of the listed
4739
attributes.
4740
 
4741
@kindex ORIGIN =
4742
@kindex o =
4743
@kindex org =
4744
The @var{origin} is an numerical expression for the start address of
4745
the memory region.  The expression must evaluate to a constant and it
4746
cannot involve any symbols.  The keyword @code{ORIGIN} may be
4747
abbreviated to @code{org} or @code{o} (but not, for example,
4748
@code{ORG}).
4749
 
4750
@kindex LENGTH =
4751
@kindex len =
4752
@kindex l =
4753
The @var{len} is an expression for the size in bytes of the memory
4754
region.  As with the @var{origin} expression, the expression must
4755
be numerical only and must evaluate to a constant.  The keyword
4756
@code{LENGTH} may be abbreviated to @code{len} or @code{l}.
4757
 
4758
In the following example, we specify that there are two memory regions
4759
available for allocation: one starting at @samp{0} for 256 kilobytes,
4760
and the other starting at @samp{0x40000000} for four megabytes.  The
4761
linker will place into the @samp{rom} memory region every section which
4762
is not explicitly mapped into a memory region, and is either read-only
4763
or executable.  The linker will place other sections which are not
4764
explicitly mapped into a memory region into the @samp{ram} memory
4765
region.
4766
 
4767
@smallexample
4768
@group
4769
MEMORY
4770
  @{
4771
    rom (rx)  : ORIGIN = 0, LENGTH = 256K
4772
    ram (!rx) : org = 0x40000000, l = 4M
4773
  @}
4774
@end group
4775
@end smallexample
4776
 
4777
Once you define a memory region, you can direct the linker to place
4778
specific output sections into that memory region by using the
4779
@samp{>@var{region}} output section attribute.  For example, if you have
4780
a memory region named @samp{mem}, you would use @samp{>mem} in the
4781
output section definition.  @xref{Output Section Region}.  If no address
4782
was specified for the output section, the linker will set the address to
4783
the next available address within the memory region.  If the combined
4784
output sections directed to a memory region are too large for the
4785
region, the linker will issue an error message.
4786
 
4787
It is possible to access the origin and length of a memory in an
4788
expression via the @code{ORIGIN(@var{memory})} and
4789
@code{LENGTH(@var{memory})} functions:
4790
 
4791
@smallexample
4792
@group
4793
  _fstack = ORIGIN(ram) + LENGTH(ram) - 4;
4794
@end group
4795
@end smallexample
4796
 
4797
@node PHDRS
4798
@section PHDRS Command
4799
@kindex PHDRS
4800
@cindex program headers
4801
@cindex ELF program headers
4802
@cindex program segments
4803
@cindex segments, ELF
4804
The ELF object file format uses @dfn{program headers}, also knows as
4805
@dfn{segments}.  The program headers describe how the program should be
4806
loaded into memory.  You can print them out by using the @code{objdump}
4807
program with the @samp{-p} option.
4808
 
4809
When you run an ELF program on a native ELF system, the system loader
4810
reads the program headers in order to figure out how to load the
4811
program.  This will only work if the program headers are set correctly.
4812
This manual does not describe the details of how the system loader
4813
interprets program headers; for more information, see the ELF ABI.
4814
 
4815
The linker will create reasonable program headers by default.  However,
4816
in some cases, you may need to specify the program headers more
4817
precisely.  You may use the @code{PHDRS} command for this purpose.  When
4818
the linker sees the @code{PHDRS} command in the linker script, it will
4819
not create any program headers other than the ones specified.
4820
 
4821
The linker only pays attention to the @code{PHDRS} command when
4822
generating an ELF output file.  In other cases, the linker will simply
4823
ignore @code{PHDRS}.
4824
 
4825
This is the syntax of the @code{PHDRS} command.  The words @code{PHDRS},
4826
@code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
4827
 
4828
@smallexample
4829
@group
4830
PHDRS
4831
@{
4832
  @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
4833
        [ FLAGS ( @var{flags} ) ] ;
4834
@}
4835
@end group
4836
@end smallexample
4837
 
4838
The @var{name} is used only for reference in the @code{SECTIONS} command
4839
of the linker script.  It is not put into the output file.  Program
4840
header names are stored in a separate name space, and will not conflict
4841
with symbol names, file names, or section names.  Each program header
4842
must have a distinct name.  The headers are processed in order and it
4843
is usual for them to map to sections in ascending load address order.
4844
 
4845
Certain program header types describe segments of memory which the
4846
system loader will load from the file.  In the linker script, you
4847
specify the contents of these segments by placing allocatable output
4848
sections in the segments.  You use the @samp{:@var{phdr}} output section
4849
attribute to place a section in a particular segment.  @xref{Output
4850
Section Phdr}.
4851
 
4852
It is normal to put certain sections in more than one segment.  This
4853
merely implies that one segment of memory contains another.  You may
4854
repeat @samp{:@var{phdr}}, using it once for each segment which should
4855
contain the section.
4856
 
4857
If you place a section in one or more segments using @samp{:@var{phdr}},
4858
then the linker will place all subsequent allocatable sections which do
4859
not specify @samp{:@var{phdr}} in the same segments.  This is for
4860
convenience, since generally a whole set of contiguous sections will be
4861
placed in a single segment.  You can use @code{:NONE} to override the
4862
default segment and tell the linker to not put the section in any
4863
segment at all.
4864
 
4865
@kindex FILEHDR
4866
@kindex PHDRS
4867
You may use the @code{FILEHDR} and @code{PHDRS} keywords after
4868
the program header type to further describe the contents of the segment.
4869
The @code{FILEHDR} keyword means that the segment should include the ELF
4870
file header.  The @code{PHDRS} keyword means that the segment should
4871
include the ELF program headers themselves.  If applied to a loadable
4872
segment (@code{PT_LOAD}), all prior loadable segments must have one of
4873
these keywords.
4874
 
4875
The @var{type} may be one of the following.  The numbers indicate the
4876
value of the keyword.
4877
 
4878
@table @asis
4879
@item @code{PT_NULL} (0)
4880
Indicates an unused program header.
4881
 
4882
@item @code{PT_LOAD} (1)
4883
Indicates that this program header describes a segment to be loaded from
4884
the file.
4885
 
4886
@item @code{PT_DYNAMIC} (2)
4887
Indicates a segment where dynamic linking information can be found.
4888
 
4889
@item @code{PT_INTERP} (3)
4890
Indicates a segment where the name of the program interpreter may be
4891
found.
4892
 
4893
@item @code{PT_NOTE} (4)
4894
Indicates a segment holding note information.
4895
 
4896
@item @code{PT_SHLIB} (5)
4897
A reserved program header type, defined but not specified by the ELF
4898
ABI.
4899
 
4900
@item @code{PT_PHDR} (6)
4901
Indicates a segment where the program headers may be found.
4902
 
4903
@item @var{expression}
4904
An expression giving the numeric type of the program header.  This may
4905
be used for types not defined above.
4906
@end table
4907
 
4908
You can specify that a segment should be loaded at a particular address
4909
in memory by using an @code{AT} expression.  This is identical to the
4910
@code{AT} command used as an output section attribute (@pxref{Output
4911
Section LMA}).  The @code{AT} command for a program header overrides the
4912
output section attribute.
4913
 
4914
The linker will normally set the segment flags based on the sections
4915
which comprise the segment.  You may use the @code{FLAGS} keyword to
4916
explicitly specify the segment flags.  The value of @var{flags} must be
4917
an integer.  It is used to set the @code{p_flags} field of the program
4918
header.
4919
 
4920
Here is an example of @code{PHDRS}.  This shows a typical set of program
4921
headers used on a native ELF system.
4922
 
4923
@example
4924
@group
4925
PHDRS
4926
@{
4927
  headers PT_PHDR PHDRS ;
4928
  interp PT_INTERP ;
4929
  text PT_LOAD FILEHDR PHDRS ;
4930
  data PT_LOAD ;
4931
  dynamic PT_DYNAMIC ;
4932
@}
4933
 
4934
SECTIONS
4935
@{
4936
  . = SIZEOF_HEADERS;
4937
  .interp : @{ *(.interp) @} :text :interp
4938
  .text : @{ *(.text) @} :text
4939
  .rodata : @{ *(.rodata) @} /* defaults to :text */
4940
  @dots{}
4941
  . = . + 0x1000; /* move to a new page in memory */
4942
  .data : @{ *(.data) @} :data
4943
  .dynamic : @{ *(.dynamic) @} :data :dynamic
4944
  @dots{}
4945
@}
4946
@end group
4947
@end example
4948
 
4949
@node VERSION
4950
@section VERSION Command
4951
@kindex VERSION @{script text@}
4952
@cindex symbol versions
4953
@cindex version script
4954
@cindex versions of symbols
4955
The linker supports symbol versions when using ELF.  Symbol versions are
4956
only useful when using shared libraries.  The dynamic linker can use
4957
symbol versions to select a specific version of a function when it runs
4958
a program that may have been linked against an earlier version of the
4959
shared library.
4960
 
4961
You can include a version script directly in the main linker script, or
4962
you can supply the version script as an implicit linker script.  You can
4963
also use the @samp{--version-script} linker option.
4964
 
4965
The syntax of the @code{VERSION} command is simply
4966
@smallexample
4967
VERSION @{ version-script-commands @}
4968
@end smallexample
4969
 
4970
The format of the version script commands is identical to that used by
4971
Sun's linker in Solaris 2.5.  The version script defines a tree of
4972
version nodes.  You specify the node names and interdependencies in the
4973
version script.  You can specify which symbols are bound to which
4974
version nodes, and you can reduce a specified set of symbols to local
4975
scope so that they are not globally visible outside of the shared
4976
library.
4977
 
4978
The easiest way to demonstrate the version script language is with a few
4979
examples.
4980
 
4981
@smallexample
4982
VERS_1.1 @{
4983
         global:
4984
                 foo1;
4985
         local:
4986
                 old*;
4987
                 original*;
4988
                 new*;
4989
@};
4990
 
4991
VERS_1.2 @{
4992
                 foo2;
4993
@} VERS_1.1;
4994
 
4995
VERS_2.0 @{
4996
                 bar1; bar2;
4997
         extern "C++" @{
4998
                 ns::*;
4999
                 "f(int, double)";
5000
         @};
5001
@} VERS_1.2;
5002
@end smallexample
5003
 
5004
This example version script defines three version nodes.  The first
5005
version node defined is @samp{VERS_1.1}; it has no other dependencies.
5006
The script binds the symbol @samp{foo1} to @samp{VERS_1.1}.  It reduces
5007
a number of symbols to local scope so that they are not visible outside
5008
of the shared library; this is done using wildcard patterns, so that any
5009
symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
5010
is matched.  The wildcard patterns available are the same as those used
5011
in the shell when matching filenames (also known as ``globbing'').
5012
However, if you specify the symbol name inside double quotes, then the
5013
name is treated as literal, rather than as a glob pattern.
5014
 
5015
Next, the version script defines node @samp{VERS_1.2}.  This node
5016
depends upon @samp{VERS_1.1}.  The script binds the symbol @samp{foo2}
5017
to the version node @samp{VERS_1.2}.
5018
 
5019
Finally, the version script defines node @samp{VERS_2.0}.  This node
5020
depends upon @samp{VERS_1.2}.  The scripts binds the symbols @samp{bar1}
5021
and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
5022
 
5023
When the linker finds a symbol defined in a library which is not
5024
specifically bound to a version node, it will effectively bind it to an
5025
unspecified base version of the library.  You can bind all otherwise
5026
unspecified symbols to a given version node by using @samp{global: *;}
5027
somewhere in the version script.  Note that it's slightly crazy to use
5028
wildcards in a global spec except on the last version node.  Global
5029
wildcards elsewhere run the risk of accidentally adding symbols to the
5030
set exported for an old version.  That's wrong since older versions
5031
ought to have a fixed set of symbols.
5032
 
5033
The names of the version nodes have no specific meaning other than what
5034
they might suggest to the person reading them.  The @samp{2.0} version
5035
could just as well have appeared in between @samp{1.1} and @samp{1.2}.
5036
However, this would be a confusing way to write a version script.
5037
 
5038
Node name can be omitted, provided it is the only version node
5039
in the version script.  Such version script doesn't assign any versions to
5040
symbols, only selects which symbols will be globally visible out and which
5041
won't.
5042
 
5043
@smallexample
5044
@{ global: foo; bar; local: *; @};
5045
@end smallexample
5046
 
5047
When you link an application against a shared library that has versioned
5048
symbols, the application itself knows which version of each symbol it
5049
requires, and it also knows which version nodes it needs from each
5050
shared library it is linked against.  Thus at runtime, the dynamic
5051
loader can make a quick check to make sure that the libraries you have
5052
linked against do in fact supply all of the version nodes that the
5053
application will need to resolve all of the dynamic symbols.  In this
5054
way it is possible for the dynamic linker to know with certainty that
5055
all external symbols that it needs will be resolvable without having to
5056
search for each symbol reference.
5057
 
5058
The symbol versioning is in effect a much more sophisticated way of
5059
doing minor version checking that SunOS does.  The fundamental problem
5060
that is being addressed here is that typically references to external
5061
functions are bound on an as-needed basis, and are not all bound when
5062
the application starts up.  If a shared library is out of date, a
5063
required interface may be missing; when the application tries to use
5064
that interface, it may suddenly and unexpectedly fail.  With symbol
5065
versioning, the user will get a warning when they start their program if
5066
the libraries being used with the application are too old.
5067
 
5068
There are several GNU extensions to Sun's versioning approach.  The
5069
first of these is the ability to bind a symbol to a version node in the
5070
source file where the symbol is defined instead of in the versioning
5071
script.  This was done mainly to reduce the burden on the library
5072
maintainer.  You can do this by putting something like:
5073
@smallexample
5074
__asm__(".symver original_foo,foo@@VERS_1.1");
5075
@end smallexample
5076
@noindent
5077
in the C source file.  This renames the function @samp{original_foo} to
5078
be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
5079
The @samp{local:} directive can be used to prevent the symbol
5080
@samp{original_foo} from being exported. A @samp{.symver} directive
5081
takes precedence over a version script.
5082
 
5083
The second GNU extension is to allow multiple versions of the same
5084
function to appear in a given shared library.  In this way you can make
5085
an incompatible change to an interface without increasing the major
5086
version number of the shared library, while still allowing applications
5087
linked against the old interface to continue to function.
5088
 
5089
To do this, you must use multiple @samp{.symver} directives in the
5090
source file.  Here is an example:
5091
 
5092
@smallexample
5093
__asm__(".symver original_foo,foo@@");
5094
__asm__(".symver old_foo,foo@@VERS_1.1");
5095
__asm__(".symver old_foo1,foo@@VERS_1.2");
5096
__asm__(".symver new_foo,foo@@@@VERS_2.0");
5097
@end smallexample
5098
 
5099
In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
5100
unspecified base version of the symbol.  The source file that contains this
5101
example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
5102
@samp{old_foo1}, and @samp{new_foo}.
5103
 
5104
When you have multiple definitions of a given symbol, there needs to be
5105
some way to specify a default version to which external references to
5106
this symbol will be bound.  You can do this with the
5107
@samp{foo@@@@VERS_2.0} type of @samp{.symver} directive.  You can only
5108
declare one version of a symbol as the default in this manner; otherwise
5109
you would effectively have multiple definitions of the same symbol.
5110
 
5111
If you wish to bind a reference to a specific version of the symbol
5112
within the shared library, you can use the aliases of convenience
5113
(i.e., @samp{old_foo}), or you can use the @samp{.symver} directive to
5114
specifically bind to an external version of the function in question.
5115
 
5116
You can also specify the language in the version script:
5117
 
5118
@smallexample
5119
VERSION extern "lang" @{ version-script-commands @}
5120
@end smallexample
5121
 
5122
The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}.
5123
The linker will iterate over the list of symbols at the link time and
5124
demangle them according to @samp{lang} before matching them to the
5125
patterns specified in @samp{version-script-commands}.  The default
5126
@samp{lang} is @samp{C}.
5127
 
5128
Demangled names may contains spaces and other special characters.  As
5129
described above, you can use a glob pattern to match demangled names,
5130
or you can use a double-quoted string to match the string exactly.  In
5131
the latter case, be aware that minor differences (such as differing
5132
whitespace) between the version script and the demangler output will
5133
cause a mismatch.  As the exact string generated by the demangler
5134
might change in the future, even if the mangled name does not, you
5135
should check that all of your version directives are behaving as you
5136
expect when you upgrade.
5137
 
5138
@node Expressions
5139
@section Expressions in Linker Scripts
5140
@cindex expressions
5141
@cindex arithmetic
5142
The syntax for expressions in the linker script language is identical to
5143
that of C expressions.  All expressions are evaluated as integers.  All
5144
expressions are evaluated in the same size, which is 32 bits if both the
5145
host and target are 32 bits, and is otherwise 64 bits.
5146
 
5147
You can use and set symbol values in expressions.
5148
 
5149
The linker defines several special purpose builtin functions for use in
5150
expressions.
5151
 
5152
@menu
5153
* Constants::                   Constants
5154
* Symbolic Constants::          Symbolic constants
5155
* Symbols::                     Symbol Names
5156
* Orphan Sections::             Orphan Sections
5157
* Location Counter::            The Location Counter
5158
* Operators::                   Operators
5159
* Evaluation::                  Evaluation
5160
* Expression Section::          The Section of an Expression
5161
* Builtin Functions::           Builtin Functions
5162
@end menu
5163
 
5164
@node Constants
5165
@subsection Constants
5166
@cindex integer notation
5167
@cindex constants in linker scripts
5168
All constants are integers.
5169
 
5170
As in C, the linker considers an integer beginning with @samp{0} to be
5171
octal, and an integer beginning with @samp{0x} or @samp{0X} to be
5172
hexadecimal.  Alternatively the linker accepts suffixes of @samp{h} or
5173
@samp{H} for hexadeciaml, @samp{o} or @samp{O} for octal, @samp{b} or
5174
@samp{B} for binary and @samp{d} or @samp{D} for decimal.  Any integer
5175
value without a prefix or a suffix is considered to be decimal.
5176
 
5177
@cindex scaled integers
5178
@cindex K and M integer suffixes
5179
@cindex M and K integer suffixes
5180
@cindex suffixes for integers
5181
@cindex integer suffixes
5182
In addition, you can use the suffixes @code{K} and @code{M} to scale a
5183
constant by
5184
@c TEXI2ROFF-KILL
5185
@ifnottex
5186
@c END TEXI2ROFF-KILL
5187
@code{1024} or @code{1024*1024}
5188
@c TEXI2ROFF-KILL
5189
@end ifnottex
5190
@tex
5191
${\rm 1024}$ or ${\rm 1024}^2$
5192
@end tex
5193
@c END TEXI2ROFF-KILL
5194
respectively.  For example, the following
5195
all refer to the same quantity:
5196
 
5197
@smallexample
5198
_fourk_1 = 4K;
5199
_fourk_2 = 4096;
5200
_fourk_3 = 0x1000;
5201
_fourk_4 = 10000o;
5202
@end smallexample
5203
 
5204
Note - the @code{K} and @code{M} suffixes cannot be used in
5205
conjunction with the base suffixes mentioned above.
5206
 
5207
@node Symbolic Constants
5208
@subsection Symbolic Constants
5209
@cindex symbolic constants
5210
@kindex CONSTANT
5211
It is possible to refer to target specific constants via the use of
5212
the @code{CONSTANT(@var{name})} operator, where @var{name} is one of:
5213
 
5214
@table @code
5215
@item MAXPAGESIZE
5216
@kindex MAXPAGESIZE
5217
The target's maximum page size.
5218
 
5219
@item COMMONPAGESIZE
5220
@kindex COMMONPAGESIZE
5221
The target's default page size.
5222
@end table
5223
 
5224
So for example:
5225
 
5226
@smallexample
5227
  .text ALIGN (CONSTANT (MAXPAGESIZE)) : @{ *(.text) @}
5228
@end smallexample
5229
 
5230
will create a text section aligned to the largest page boundary
5231
supported by the target.
5232
 
5233
@node Symbols
5234
@subsection Symbol Names
5235
@cindex symbol names
5236
@cindex names
5237
@cindex quoted symbol names
5238
@kindex "
5239
Unless quoted, symbol names start with a letter, underscore, or period
5240
and may include letters, digits, underscores, periods, and hyphens.
5241
Unquoted symbol names must not conflict with any keywords.  You can
5242
specify a symbol which contains odd characters or has the same name as a
5243
keyword by surrounding the symbol name in double quotes:
5244
@smallexample
5245
"SECTION" = 9;
5246
"with a space" = "also with a space" + 10;
5247
@end smallexample
5248
 
5249
Since symbols can contain many non-alphabetic characters, it is safest
5250
to delimit symbols with spaces.  For example, @samp{A-B} is one symbol,
5251
whereas @samp{A - B} is an expression involving subtraction.
5252
 
5253
@node Orphan Sections
5254
@subsection Orphan Sections
5255
@cindex orphan
5256
Orphan sections are sections present in the input files which
5257
are not explicitly placed into the output file by the linker
5258
script.  The linker will still copy these sections into the
5259
output file, but it has to guess as to where they should be
5260
placed.  The linker uses a simple heuristic to do this.  It
5261
attempts to place orphan sections after non-orphan sections of the
5262
same attribute, such as code vs data, loadable vs non-loadable, etc.
5263
If there is not enough room to do this then it places
5264
at the end of the file.
5265
 
5266
For ELF targets, the attribute of the section includes section type as
5267
well as section flag.
5268
 
5269
If an orphaned section's name is representable as a C identifier then
5270
the linker will automatically @pxref{PROVIDE} two symbols:
5271
__start_SECNAME and __end_SECNAME, where SECNAME is the name of the
5272
section.  These indicate the start address and end address of the
5273
orphaned section respectively.  Note: most section names are not
5274
representable as C identifiers because they contain a @samp{.}
5275
character.
5276
 
5277
@node Location Counter
5278
@subsection The Location Counter
5279
@kindex .
5280
@cindex dot
5281
@cindex location counter
5282
@cindex current output location
5283
The special linker variable @dfn{dot} @samp{.} always contains the
5284
current output location counter.  Since the @code{.} always refers to a
5285
location in an output section, it may only appear in an expression
5286
within a @code{SECTIONS} command.  The @code{.} symbol may appear
5287
anywhere that an ordinary symbol is allowed in an expression.
5288
 
5289
@cindex holes
5290
Assigning a value to @code{.} will cause the location counter to be
5291
moved.  This may be used to create holes in the output section.  The
5292
location counter may not be moved backwards inside an output section,
5293
and may not be moved backwards outside of an output section if so
5294
doing creates areas with overlapping LMAs.
5295
 
5296
@smallexample
5297
SECTIONS
5298
@{
5299
  output :
5300
    @{
5301
      file1(.text)
5302
      . = . + 1000;
5303
      file2(.text)
5304
      . += 1000;
5305
      file3(.text)
5306
    @} = 0x12345678;
5307
@}
5308
@end smallexample
5309
@noindent
5310
In the previous example, the @samp{.text} section from @file{file1} is
5311
located at the beginning of the output section @samp{output}.  It is
5312
followed by a 1000 byte gap.  Then the @samp{.text} section from
5313
@file{file2} appears, also with a 1000 byte gap following before the
5314
@samp{.text} section from @file{file3}.  The notation @samp{= 0x12345678}
5315
specifies what data to write in the gaps (@pxref{Output Section Fill}).
5316
 
5317
@cindex dot inside sections
5318
Note: @code{.} actually refers to the byte offset from the start of the
5319
current containing object.  Normally this is the @code{SECTIONS}
5320
statement, whose start address is 0, hence @code{.} can be used as an
5321
absolute address.  If @code{.} is used inside a section description
5322
however, it refers to the byte offset from the start of that section,
5323
not an absolute address.  Thus in a script like this:
5324
 
5325
@smallexample
5326
SECTIONS
5327
@{
5328
    . = 0x100
5329
    .text: @{
5330
      *(.text)
5331
      . = 0x200
5332
    @}
5333
    . = 0x500
5334
    .data: @{
5335
      *(.data)
5336
      . += 0x600
5337
    @}
5338
@}
5339
@end smallexample
5340
 
5341
The @samp{.text} section will be assigned a starting address of 0x100
5342
and a size of exactly 0x200 bytes, even if there is not enough data in
5343
the @samp{.text} input sections to fill this area.  (If there is too
5344
much data, an error will be produced because this would be an attempt to
5345
move @code{.} backwards).  The @samp{.data} section will start at 0x500
5346
and it will have an extra 0x600 bytes worth of space after the end of
5347
the values from the @samp{.data} input sections and before the end of
5348
the @samp{.data} output section itself.
5349
 
5350
@cindex dot outside sections
5351
Setting symbols to the value of the location counter outside of an
5352
output section statement can result in unexpected values if the linker
5353
needs to place orphan sections.  For example, given the following:
5354
 
5355
@smallexample
5356
SECTIONS
5357
@{
5358
    start_of_text = . ;
5359
    .text: @{ *(.text) @}
5360
    end_of_text = . ;
5361
 
5362
    start_of_data = . ;
5363
    .data: @{ *(.data) @}
5364
    end_of_data = . ;
5365
@}
5366
@end smallexample
5367
 
5368
If the linker needs to place some input section, e.g. @code{.rodata},
5369
not mentioned in the script, it might choose to place that section
5370
between @code{.text} and @code{.data}.  You might think the linker
5371
should place @code{.rodata} on the blank line in the above script, but
5372
blank lines are of no particular significance to the linker.  As well,
5373
the linker doesn't associate the above symbol names with their
5374
sections.  Instead, it assumes that all assignments or other
5375
statements belong to the previous output section, except for the
5376
special case of an assignment to @code{.}.  I.e., the linker will
5377
place the orphan @code{.rodata} section as if the script was written
5378
as follows:
5379
 
5380
@smallexample
5381
SECTIONS
5382
@{
5383
    start_of_text = . ;
5384
    .text: @{ *(.text) @}
5385
    end_of_text = . ;
5386
 
5387
    start_of_data = . ;
5388
    .rodata: @{ *(.rodata) @}
5389
    .data: @{ *(.data) @}
5390
    end_of_data = . ;
5391
@}
5392
@end smallexample
5393
 
5394
This may or may not be the script author's intention for the value of
5395
@code{start_of_data}.  One way to influence the orphan section
5396
placement is to assign the location counter to itself, as the linker
5397
assumes that an assignment to @code{.} is setting the start address of
5398
a following output section and thus should be grouped with that
5399
section.  So you could write:
5400
 
5401
@smallexample
5402
SECTIONS
5403
@{
5404
    start_of_text = . ;
5405
    .text: @{ *(.text) @}
5406
    end_of_text = . ;
5407
 
5408
    . = . ;
5409
    start_of_data = . ;
5410
    .data: @{ *(.data) @}
5411
    end_of_data = . ;
5412
@}
5413
@end smallexample
5414
 
5415
Now, the orphan @code{.rodata} section will be placed between
5416
@code{end_of_text} and @code{start_of_data}.
5417
 
5418
@need 2000
5419
@node Operators
5420
@subsection Operators
5421
@cindex operators for arithmetic
5422
@cindex arithmetic operators
5423
@cindex precedence in expressions
5424
The linker recognizes the standard C set of arithmetic operators, with
5425
the standard bindings and precedence levels:
5426
@c TEXI2ROFF-KILL
5427
@ifnottex
5428
@c END TEXI2ROFF-KILL
5429
@smallexample
5430
precedence      associativity   Operators                Notes
5431
(highest)
5432
1               left            !  -  ~                  (1)
5433
2               left            *  /  %
5434
3               left            +  -
5435
4               left            >>  <<
5436
5               left            ==  !=  >  <  <=  >=
5437
6               left            &
5438
7               left            |
5439
8               left            &&
5440
9               left            ||
5441
10              right           ? :
5442
11              right           &=  +=  -=  *=  /=       (2)
5443
(lowest)
5444
@end smallexample
5445
Notes:
5446
(1) Prefix operators
5447
(2) @xref{Assignments}.
5448
@c TEXI2ROFF-KILL
5449
@end ifnottex
5450
@tex
5451
\vskip \baselineskip
5452
%"lispnarrowing" is the extra indent used generally for smallexample
5453
\hskip\lispnarrowing\vbox{\offinterlineskip
5454
\hrule
5455
\halign
5456
{\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
5457
height2pt&\omit&&\omit&&\omit&\cr
5458
&Precedence&&  Associativity  &&{\rm Operators}&\cr
5459
height2pt&\omit&&\omit&&\omit&\cr
5460
\noalign{\hrule}
5461
height2pt&\omit&&\omit&&\omit&\cr
5462
&highest&&&&&\cr
5463
% '176 is tilde, '~' in tt font
5464
&1&&left&&\qquad-          \char'176\      !\qquad\dag&\cr
5465
&2&&left&&*          /        \%&\cr
5466
&3&&left&&+          -&\cr
5467
&4&&left&&>>         <<&\cr
5468
&5&&left&&==         !=       >      <      <=      >=&\cr
5469
&6&&left&&\&&\cr
5470
&7&&left&&|&\cr
5471
&8&&left&&{\&\&}&\cr
5472
&9&&left&&||&\cr
5473
&10&&right&&?        :&\cr
5474
&11&&right&&\qquad\&=      +=       -=     *=     /=\qquad\ddag&\cr
5475
&lowest&&&&&\cr
5476
height2pt&\omit&&\omit&&\omit&\cr}
5477
\hrule}
5478
@end tex
5479
@iftex
5480
{
5481
@obeylines@parskip=0pt@parindent=0pt
5482
@dag@quad Prefix operators.
5483
@ddag@quad @xref{Assignments}.
5484
}
5485
@end iftex
5486
@c END TEXI2ROFF-KILL
5487
 
5488
@node Evaluation
5489
@subsection Evaluation
5490
@cindex lazy evaluation
5491
@cindex expression evaluation order
5492
The linker evaluates expressions lazily.  It only computes the value of
5493
an expression when absolutely necessary.
5494
 
5495
The linker needs some information, such as the value of the start
5496
address of the first section, and the origins and lengths of memory
5497
regions, in order to do any linking at all.  These values are computed
5498
as soon as possible when the linker reads in the linker script.
5499
 
5500
However, other values (such as symbol values) are not known or needed
5501
until after storage allocation.  Such values are evaluated later, when
5502
other information (such as the sizes of output sections) is available
5503
for use in the symbol assignment expression.
5504
 
5505
The sizes of sections cannot be known until after allocation, so
5506
assignments dependent upon these are not performed until after
5507
allocation.
5508
 
5509
Some expressions, such as those depending upon the location counter
5510
@samp{.}, must be evaluated during section allocation.
5511
 
5512
If the result of an expression is required, but the value is not
5513
available, then an error results.  For example, a script like the
5514
following
5515
@smallexample
5516
@group
5517
SECTIONS
5518
  @{
5519
    .text 9+this_isnt_constant :
5520
      @{ *(.text) @}
5521
  @}
5522
@end group
5523
@end smallexample
5524
@noindent
5525
will cause the error message @samp{non constant expression for initial
5526
address}.
5527
 
5528
@node Expression Section
5529
@subsection The Section of an Expression
5530
@cindex expression sections
5531
@cindex absolute expressions
5532
@cindex relative expressions
5533
@cindex absolute and relocatable symbols
5534
@cindex relocatable and absolute symbols
5535
@cindex symbols, relocatable and absolute
5536
Addresses and symbols may be section relative, or absolute.  A section
5537
relative symbol is relocatable.  If you request relocatable output
5538
using the @samp{-r} option, a further link operation may change the
5539
value of a section relative symbol.  On the other hand, an absolute
5540
symbol will retain the same value throughout any further link
5541
operations.
5542
 
5543
Some terms in linker expressions are addresses.  This is true of
5544
section relative symbols and for builtin functions that return an
5545
address, such as @code{ADDR}, @code{LOADADDR}, @code{ORIGIN} and
5546
@code{SEGMENT_START}.  Other terms are simply numbers, or are builtin
5547
functions that return a non-address value, such as @code{LENGTH}.
5548
One complication is that unless you set @code{LD_FEATURE ("SANE_EXPR")}
5549
(@pxref{Miscellaneous Commands}), numbers and absolute symbols are treated
5550
differently depending on their location, for compatibility with older
5551
versions of @code{ld}.  Expressions appearing outside an output
5552
section definition treat all numbers as absolute addresses.
5553
Expressions appearing inside an output section definition treat
5554
absolute symbols as numbers.  If @code{LD_FEATURE ("SANE_EXPR")} is
5555
given, then absolute symbols and numbers are simply treated as numbers
5556
everywhere.
5557
 
5558
In the following simple example,
5559
 
5560
@smallexample
5561
@group
5562
SECTIONS
5563
  @{
5564
    . = 0x100;
5565
    __executable_start = 0x100;
5566
    .data :
5567
    @{
5568
      . = 0x10;
5569
      __data_start = 0x10;
5570
      *(.data)
5571
    @}
5572
    @dots{}
5573
  @}
5574
@end group
5575
@end smallexample
5576
 
5577
both @code{.} and @code{__executable_start} are set to the absolute
5578
address 0x100 in the first two assignments, then both @code{.} and
5579
@code{__data_start} are set to 0x10 relative to the @code{.data}
5580
section in the second two assignments.
5581
 
5582
For expressions involving numbers, relative addresses and absolute
5583
addresses, ld follows these rules to evaluate terms:
5584
 
5585
@itemize @bullet
5586
@item
5587
Unary operations on a relative address, and binary operations on two
5588
relative addresses in the same section or between one relative address
5589
and a number, apply the operator to the offset part of the address(es).
5590
@item
5591
Unary operations on an absolute address, and binary operations on one
5592
or more absolute addresses or on two relative addresses not in the
5593
same section, first convert any non-absolute term to an absolute
5594
address before applying the operator.
5595
@end itemize
5596
 
5597
The result section of each sub-expression is as follows:
5598
 
5599
@itemize @bullet
5600
@item
5601
An operation involving only numbers results in a number.
5602
@item
5603
The result of comparisons, @samp{&&} and @samp{||} is also a number.
5604
@item
5605
The result of other binary arithmetic and logical operations on two
5606
relative addresses in the same section or two absolute addresess
5607
(after above conversions) is also a number.
5608
@item
5609
The result of other operations on relative addresses or one
5610
relative address and a number, is a relative address in the same
5611
section as the relative operand(s).
5612
@item
5613
The result of other operations on absolute addresses (after above
5614
conversions) is an absolute address.
5615
@end itemize
5616
 
5617
You can use the builtin function @code{ABSOLUTE} to force an expression
5618
to be absolute when it would otherwise be relative.  For example, to
5619
create an absolute symbol set to the address of the end of the output
5620
section @samp{.data}:
5621
@smallexample
5622
SECTIONS
5623
  @{
5624
    .data : @{ *(.data) _edata = ABSOLUTE(.); @}
5625
  @}
5626
@end smallexample
5627
@noindent
5628
If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
5629
@samp{.data} section.
5630
 
5631
Using @code{LOADADDR} also forces an expression absolute, since this
5632
particular builtin function returns an absolute address.
5633
 
5634
@node Builtin Functions
5635
@subsection Builtin Functions
5636
@cindex functions in expressions
5637
The linker script language includes a number of builtin functions for
5638
use in linker script expressions.
5639
 
5640
@table @code
5641
@item ABSOLUTE(@var{exp})
5642
@kindex ABSOLUTE(@var{exp})
5643
@cindex expression, absolute
5644
Return the absolute (non-relocatable, as opposed to non-negative) value
5645
of the expression @var{exp}.  Primarily useful to assign an absolute
5646
value to a symbol within a section definition, where symbol values are
5647
normally section relative.  @xref{Expression Section}.
5648
 
5649
@item ADDR(@var{section})
5650
@kindex ADDR(@var{section})
5651
@cindex section address in expression
5652
Return the address (VMA) of the named @var{section}.  Your
5653
script must previously have defined the location of that section.  In
5654
the following example, @code{start_of_output_1}, @code{symbol_1} and
5655
@code{symbol_2} are assigned equivalent values, except that
5656
@code{symbol_1} will be relative to the @code{.output1} section while
5657
the other two will be absolute:
5658
@smallexample
5659
@group
5660
SECTIONS @{ @dots{}
5661
  .output1 :
5662
    @{
5663
    start_of_output_1 = ABSOLUTE(.);
5664
    @dots{}
5665
    @}
5666
  .output :
5667
    @{
5668
    symbol_1 = ADDR(.output1);
5669
    symbol_2 = start_of_output_1;
5670
    @}
5671
@dots{} @}
5672
@end group
5673
@end smallexample
5674
 
5675
@item ALIGN(@var{align})
5676
@itemx ALIGN(@var{exp},@var{align})
5677
@kindex ALIGN(@var{align})
5678
@kindex ALIGN(@var{exp},@var{align})
5679
@cindex round up location counter
5680
@cindex align location counter
5681
@cindex round up expression
5682
@cindex align expression
5683
Return the location counter (@code{.}) or arbitrary expression aligned
5684
to the next @var{align} boundary.  The single operand @code{ALIGN}
5685
doesn't change the value of the location counter---it just does
5686
arithmetic on it.  The two operand @code{ALIGN} allows an arbitrary
5687
expression to be aligned upwards (@code{ALIGN(@var{align})} is
5688
equivalent to @code{ALIGN(., @var{align})}).
5689
 
5690
Here is an example which aligns the output @code{.data} section to the
5691
next @code{0x2000} byte boundary after the preceding section and sets a
5692
variable within the section to the next @code{0x8000} boundary after the
5693
input sections:
5694
@smallexample
5695
@group
5696
SECTIONS @{ @dots{}
5697
  .data ALIGN(0x2000): @{
5698
    *(.data)
5699
    variable = ALIGN(0x8000);
5700
  @}
5701
@dots{} @}
5702
@end group
5703
@end smallexample
5704
@noindent
5705
The first use of @code{ALIGN} in this example specifies the location of
5706
a section because it is used as the optional @var{address} attribute of
5707
a section definition (@pxref{Output Section Address}).  The second use
5708
of @code{ALIGN} is used to defines the value of a symbol.
5709
 
5710
The builtin function @code{NEXT} is closely related to @code{ALIGN}.
5711
 
5712
@item ALIGNOF(@var{section})
5713
@kindex ALIGNOF(@var{section})
5714
@cindex section alignment
5715
Return the alignment in bytes of the named @var{section}, if that section has
5716
been allocated.  If the section has not been allocated when this is
5717
evaluated, the linker will report an error. In the following example,
5718
the alignment of the @code{.output} section is stored as the first
5719
value in that section.
5720
@smallexample
5721
@group
5722
SECTIONS@{ @dots{}
5723
  .output @{
5724
    LONG (ALIGNOF (.output))
5725
    @dots{}
5726
    @}
5727
@dots{} @}
5728
@end group
5729
@end smallexample
5730
 
5731
@item BLOCK(@var{exp})
5732
@kindex BLOCK(@var{exp})
5733
This is a synonym for @code{ALIGN}, for compatibility with older linker
5734
scripts.  It is most often seen when setting the address of an output
5735
section.
5736
 
5737
@item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
5738
@kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
5739
This is equivalent to either
5740
@smallexample
5741
(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
5742
@end smallexample
5743
or
5744
@smallexample
5745
(ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - @var{commonpagesize})))
5746
@end smallexample
5747
@noindent
5748
depending on whether the latter uses fewer @var{commonpagesize} sized pages
5749
for the data segment (area between the result of this expression and
5750
@code{DATA_SEGMENT_END}) than the former or not.
5751
If the latter form is used, it means @var{commonpagesize} bytes of runtime
5752
memory will be saved at the expense of up to @var{commonpagesize} wasted
5753
bytes in the on-disk file.
5754
 
5755
This expression can only be used directly in @code{SECTIONS} commands, not in
5756
any output section descriptions and only once in the linker script.
5757
@var{commonpagesize} should be less or equal to @var{maxpagesize} and should
5758
be the system page size the object wants to be optimized for (while still
5759
working on system page sizes up to @var{maxpagesize}).
5760
 
5761
@noindent
5762
Example:
5763
@smallexample
5764
  . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
5765
@end smallexample
5766
 
5767
@item DATA_SEGMENT_END(@var{exp})
5768
@kindex DATA_SEGMENT_END(@var{exp})
5769
This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
5770
evaluation purposes.
5771
 
5772
@smallexample
5773
  . = DATA_SEGMENT_END(.);
5774
@end smallexample
5775
 
5776
@item DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
5777
@kindex DATA_SEGMENT_RELRO_END(@var{offset}, @var{exp})
5778
This defines the end of the @code{PT_GNU_RELRO} segment when
5779
@samp{-z relro} option is used.  Second argument is returned.
5780
When @samp{-z relro} option is not present, @code{DATA_SEGMENT_RELRO_END}
5781
does nothing, otherwise @code{DATA_SEGMENT_ALIGN} is padded so that
5782
@var{exp} + @var{offset} is aligned to the most commonly used page
5783
boundary for particular target.  If present in the linker script,
5784
it must always come in between @code{DATA_SEGMENT_ALIGN} and
5785
@code{DATA_SEGMENT_END}.
5786
 
5787
@smallexample
5788
  . = DATA_SEGMENT_RELRO_END(24, .);
5789
@end smallexample
5790
 
5791
@item DEFINED(@var{symbol})
5792
@kindex DEFINED(@var{symbol})
5793
@cindex symbol defaults
5794
Return 1 if @var{symbol} is in the linker global symbol table and is
5795
defined before the statement using DEFINED in the script, otherwise
5796
return 0.  You can use this function to provide
5797
default values for symbols.  For example, the following script fragment
5798
shows how to set a global symbol @samp{begin} to the first location in
5799
the @samp{.text} section---but if a symbol called @samp{begin} already
5800
existed, its value is preserved:
5801
 
5802
@smallexample
5803
@group
5804
SECTIONS @{ @dots{}
5805
  .text : @{
5806
    begin = DEFINED(begin) ? begin : . ;
5807
    @dots{}
5808
  @}
5809
  @dots{}
5810
@}
5811
@end group
5812
@end smallexample
5813
 
5814
@item LENGTH(@var{memory})
5815
@kindex LENGTH(@var{memory})
5816
Return the length of the memory region named @var{memory}.
5817
 
5818
@item LOADADDR(@var{section})
5819
@kindex LOADADDR(@var{section})
5820
@cindex section load address in expression
5821
Return the absolute LMA of the named @var{section}.  (@pxref{Output
5822
Section LMA}).
5823
 
5824
@kindex MAX
5825
@item MAX(@var{exp1}, @var{exp2})
5826
Returns the maximum of @var{exp1} and @var{exp2}.
5827
 
5828
@kindex MIN
5829
@item MIN(@var{exp1}, @var{exp2})
5830
Returns the minimum of @var{exp1} and @var{exp2}.
5831
 
5832
@item NEXT(@var{exp})
5833
@kindex NEXT(@var{exp})
5834
@cindex unallocated address, next
5835
Return the next unallocated address that is a multiple of @var{exp}.
5836
This function is closely related to @code{ALIGN(@var{exp})}; unless you
5837
use the @code{MEMORY} command to define discontinuous memory for the
5838
output file, the two functions are equivalent.
5839
 
5840
@item ORIGIN(@var{memory})
5841
@kindex ORIGIN(@var{memory})
5842
Return the origin of the memory region named @var{memory}.
5843
 
5844
@item SEGMENT_START(@var{segment}, @var{default})
5845
@kindex SEGMENT_START(@var{segment}, @var{default})
5846
Return the base address of the named @var{segment}.  If an explicit
5847
value has been given for this segment (with a command-line @samp{-T}
5848
option) that value will be returned; otherwise the value will be
5849
@var{default}.  At present, the @samp{-T} command-line option can only
5850
be used to set the base address for the ``text'', ``data'', and
5851
``bss'' sections, but you can use @code{SEGMENT_START} with any segment
5852
name.
5853
 
5854
@item SIZEOF(@var{section})
5855
@kindex SIZEOF(@var{section})
5856
@cindex section size
5857
Return the size in bytes of the named @var{section}, if that section has
5858
been allocated.  If the section has not been allocated when this is
5859
evaluated, the linker will report an error.  In the following example,
5860
@code{symbol_1} and @code{symbol_2} are assigned identical values:
5861
@smallexample
5862
@group
5863
SECTIONS@{ @dots{}
5864
  .output @{
5865
    .start = . ;
5866
    @dots{}
5867
    .end = . ;
5868
    @}
5869
  symbol_1 = .end - .start ;
5870
  symbol_2 = SIZEOF(.output);
5871
@dots{} @}
5872
@end group
5873
@end smallexample
5874
 
5875
@item SIZEOF_HEADERS
5876
@itemx sizeof_headers
5877
@kindex SIZEOF_HEADERS
5878
@cindex header size
5879
Return the size in bytes of the output file's headers.  This is
5880
information which appears at the start of the output file.  You can use
5881
this number when setting the start address of the first section, if you
5882
choose, to facilitate paging.
5883
 
5884
@cindex not enough room for program headers
5885
@cindex program headers, not enough room
5886
When producing an ELF output file, if the linker script uses the
5887
@code{SIZEOF_HEADERS} builtin function, the linker must compute the
5888
number of program headers before it has determined all the section
5889
addresses and sizes.  If the linker later discovers that it needs
5890
additional program headers, it will report an error @samp{not enough
5891
room for program headers}.  To avoid this error, you must avoid using
5892
the @code{SIZEOF_HEADERS} function, or you must rework your linker
5893
script to avoid forcing the linker to use additional program headers, or
5894
you must define the program headers yourself using the @code{PHDRS}
5895
command (@pxref{PHDRS}).
5896
@end table
5897
 
5898
@node Implicit Linker Scripts
5899
@section Implicit Linker Scripts
5900
@cindex implicit linker scripts
5901
If you specify a linker input file which the linker can not recognize as
5902
an object file or an archive file, it will try to read the file as a
5903
linker script.  If the file can not be parsed as a linker script, the
5904
linker will report an error.
5905
 
5906
An implicit linker script will not replace the default linker script.
5907
 
5908
Typically an implicit linker script would contain only symbol
5909
assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
5910
commands.
5911
 
5912
Any input files read because of an implicit linker script will be read
5913
at the position in the command line where the implicit linker script was
5914
read.  This can affect archive searching.
5915
 
5916
@ifset GENERIC
5917
@node Machine Dependent
5918
@chapter Machine Dependent Features
5919
 
5920
@cindex machine dependencies
5921
@command{ld} has additional features on some platforms; the following
5922
sections describe them.  Machines where @command{ld} has no additional
5923
functionality are not listed.
5924
 
5925
@menu
5926
@ifset H8300
5927
* H8/300::                      @command{ld} and the H8/300
5928
@end ifset
5929
@ifset I960
5930
* i960::                        @command{ld} and the Intel 960 family
5931
@end ifset
5932
@ifset ARM
5933
* ARM::                         @command{ld} and the ARM family
5934
@end ifset
5935
@ifset HPPA
5936
* HPPA ELF32::                  @command{ld} and HPPA 32-bit ELF
5937
@end ifset
5938
@ifset M68K
5939
* M68K::                        @command{ld} and the Motorola 68K family
5940
@end ifset
5941
@ifset MMIX
5942
* MMIX::                        @command{ld} and MMIX
5943
@end ifset
5944
@ifset MSP430
5945
* MSP430::                      @command{ld} and MSP430
5946
@end ifset
5947
@ifset M68HC11
5948
* M68HC11/68HC12::              @code{ld} and the Motorola 68HC11 and 68HC12 families
5949
@end ifset
5950
@ifset POWERPC
5951
* PowerPC ELF32::               @command{ld} and PowerPC 32-bit ELF Support
5952
@end ifset
5953
@ifset POWERPC64
5954
* PowerPC64 ELF64::             @command{ld} and PowerPC64 64-bit ELF Support
5955
@end ifset
5956
@ifset SPU
5957
* SPU ELF::                     @command{ld} and SPU ELF Support
5958
@end ifset
5959
@ifset TICOFF
5960
* TI COFF::                     @command{ld} and TI COFF
5961
@end ifset
5962
@ifset WIN32
5963
* WIN32::                       @command{ld} and WIN32 (cygwin/mingw)
5964
@end ifset
5965
@ifset XTENSA
5966
* Xtensa::                      @command{ld} and Xtensa Processors
5967
@end ifset
5968
@end menu
5969
@end ifset
5970
 
5971
@ifset H8300
5972
@ifclear GENERIC
5973
@raisesections
5974
@end ifclear
5975
 
5976
@node H8/300
5977
@section @command{ld} and the H8/300
5978
 
5979
@cindex H8/300 support
5980
For the H8/300, @command{ld} can perform these global optimizations when
5981
you specify the @samp{--relax} command-line option.
5982
 
5983
@table @emph
5984
@cindex relaxing on H8/300
5985
@item relaxing address modes
5986
@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
5987
targets are within eight bits, and turns them into eight-bit
5988
program-counter relative @code{bsr} and @code{bra} instructions,
5989
respectively.
5990
 
5991
@cindex synthesizing on H8/300
5992
@item synthesizing instructions
5993
@c FIXME: specifically mov.b, or any mov instructions really?
5994
@command{ld} finds all @code{mov.b} instructions which use the
5995
sixteen-bit absolute address form, but refer to the top
5996
page of memory, and changes them to use the eight-bit address form.
5997
(That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
5998
@samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
5999
top page of memory).
6000
 
6001
@item bit manipulation instructions
6002
@command{ld} finds all bit manipulation instructions like @code{band, bclr,
6003
biand, bild, bior, bist, bixor, bld, bnot, bor, bset, bst, btst, bxor}
6004
which use 32 bit and 16 bit absolute address form, but refer to the top
6005
page of memory, and changes them to use the 8 bit address form.
6006
(That is: the linker turns @samp{bset #xx:3,@code{@@}@var{aa}:32} into
6007
@samp{bset #xx:3,@code{@@}@var{aa}:8} whenever the address @var{aa} is in
6008
the top page of memory).
6009
 
6010
@item system control instructions
6011
@command{ld} finds all @code{ldc.w, stc.w} instructions which use the
6012
32 bit absolute address form, but refer to the top page of memory, and
6013
changes them to use 16 bit address form.
6014
(That is: the linker turns @samp{ldc.w @code{@@}@var{aa}:32,ccr} into
6015
@samp{ldc.w @code{@@}@var{aa}:16,ccr} whenever the address @var{aa} is in
6016
the top page of memory).
6017
@end table
6018
 
6019
@ifclear GENERIC
6020
@lowersections
6021
@end ifclear
6022
@end ifset
6023
 
6024
@ifclear GENERIC
6025
@ifset Renesas
6026
@c This stuff is pointless to say unless you're especially concerned
6027
@c with Renesas chips; don't enable it for generic case, please.
6028
@node Renesas
6029
@chapter @command{ld} and Other Renesas Chips
6030
 
6031
@command{ld} also supports the Renesas (formerly Hitachi) H8/300H,
6032
H8/500, and SH chips.  No special features, commands, or command-line
6033
options are required for these chips.
6034
@end ifset
6035
@end ifclear
6036
 
6037
@ifset I960
6038
@ifclear GENERIC
6039
@raisesections
6040
@end ifclear
6041
 
6042
@node i960
6043
@section @command{ld} and the Intel 960 Family
6044
 
6045
@cindex i960 support
6046
 
6047
You can use the @samp{-A@var{architecture}} command line option to
6048
specify one of the two-letter names identifying members of the 960
6049
family; the option specifies the desired output target, and warns of any
6050
incompatible instructions in the input files.  It also modifies the
6051
linker's search strategy for archive libraries, to support the use of
6052
libraries specific to each particular architecture, by including in the
6053
search loop names suffixed with the string identifying the architecture.
6054
 
6055
For example, if your @command{ld} command line included @w{@samp{-ACA}} as
6056
well as @w{@samp{-ltry}}, the linker would look (in its built-in search
6057
paths, and in any paths you specify with @samp{-L}) for a library with
6058
the names
6059
 
6060
@smallexample
6061
@group
6062
try
6063
libtry.a
6064
tryca
6065
libtryca.a
6066
@end group
6067
@end smallexample
6068
 
6069
@noindent
6070
The first two possibilities would be considered in any event; the last
6071
two are due to the use of @w{@samp{-ACA}}.
6072
 
6073
You can meaningfully use @samp{-A} more than once on a command line, since
6074
the 960 architecture family allows combination of target architectures; each
6075
use will add another pair of name variants to search for when @w{@samp{-l}}
6076
specifies a library.
6077
 
6078
@cindex @option{--relax} on i960
6079
@cindex relaxing on i960
6080
@command{ld} supports the @samp{--relax} option for the i960 family.  If
6081
you specify @samp{--relax}, @command{ld} finds all @code{balx} and
6082
@code{calx} instructions whose targets are within 24 bits, and turns
6083
them into 24-bit program-counter relative @code{bal} and @code{cal}
6084
instructions, respectively.  @command{ld} also turns @code{cal}
6085
instructions into @code{bal} instructions when it determines that the
6086
target subroutine is a leaf routine (that is, the target subroutine does
6087
not itself call any subroutines).
6088
 
6089
@cindex Cortex-A8 erratum workaround
6090
@kindex --fix-cortex-a8
6091
@kindex --no-fix-cortex-a8
6092
The @samp{--fix-cortex-a8} switch enables a link-time workaround for an erratum in certain Cortex-A8 processors.  The workaround is enabled by default if you are targeting the ARM v7-A architecture profile.  It can be enabled otherwise by specifying @samp{--fix-cortex-a8}, or disabled unconditionally by specifying @samp{--no-fix-cortex-a8}.
6093
 
6094
The erratum only affects Thumb-2 code.  Please contact ARM for further details.
6095
 
6096
@kindex --merge-exidx-entries
6097
@kindex --no-merge-exidx-entries
6098
The @samp{--no-merge-exidx-entries} switch disables the merging of adjacent exidx entries in debuginfo.
6099
 
6100
@ifclear GENERIC
6101
@lowersections
6102
@end ifclear
6103
@end ifset
6104
 
6105
@ifset ARM
6106
@ifclear GENERIC
6107
@raisesections
6108
@end ifclear
6109
 
6110
@ifset M68HC11
6111
@ifclear GENERIC
6112
@raisesections
6113
@end ifclear
6114
 
6115
@node M68HC11/68HC12
6116
@section @command{ld} and the Motorola 68HC11 and 68HC12 families
6117
 
6118
@cindex M68HC11 and 68HC12 support
6119
 
6120
@subsection Linker Relaxation
6121
 
6122
For the Motorola 68HC11, @command{ld} can perform these global
6123
optimizations when you specify the @samp{--relax} command-line option.
6124
 
6125
@table @emph
6126
@cindex relaxing on M68HC11
6127
@item relaxing address modes
6128
@command{ld} finds all @code{jsr} and @code{jmp} instructions whose
6129
targets are within eight bits, and turns them into eight-bit
6130
program-counter relative @code{bsr} and @code{bra} instructions,
6131
respectively.
6132
 
6133
@command{ld} also looks at all 16-bit extended addressing modes and
6134
transforms them in a direct addressing mode when the address is in
6135
page 0 (between 0 and 0x0ff).
6136
 
6137
@item relaxing gcc instruction group
6138
When @command{gcc} is called with @option{-mrelax}, it can emit group
6139
of instructions that the linker can optimize to use a 68HC11 direct
6140
addressing mode. These instructions consists of @code{bclr} or
6141
@code{bset} instructions.
6142
 
6143
@end table
6144
 
6145
@subsection Trampoline Generation
6146
 
6147
@cindex trampoline generation on M68HC11
6148
@cindex trampoline generation on M68HC12
6149
For 68HC11 and 68HC12, @command{ld} can generate trampoline code to
6150
call a far function using a normal @code{jsr} instruction. The linker
6151
will also change the relocation to some far function to use the
6152
trampoline address instead of the function address. This is typically the
6153
case when a pointer to a function is taken. The pointer will in fact
6154
point to the function trampoline.
6155
 
6156
@ifclear GENERIC
6157
@lowersections
6158
@end ifclear
6159
@end ifset
6160
 
6161
@node ARM
6162
@section @command{ld} and the ARM family
6163
 
6164
@cindex ARM interworking support
6165
@kindex --support-old-code
6166
For the ARM, @command{ld} will generate code stubs to allow functions calls
6167
between ARM and Thumb code.  These stubs only work with code that has
6168
been compiled and assembled with the @samp{-mthumb-interwork} command
6169
line option.  If it is necessary to link with old ARM object files or
6170
libraries, which have not been compiled with the -mthumb-interwork
6171
option then the @samp{--support-old-code} command line switch should be
6172
given to the linker.  This will make it generate larger stub functions
6173
which will work with non-interworking aware ARM code.  Note, however,
6174
the linker does not support generating stubs for function calls to
6175
non-interworking aware Thumb code.
6176
 
6177
@cindex thumb entry point
6178
@cindex entry point, thumb
6179
@kindex --thumb-entry=@var{entry}
6180
The @samp{--thumb-entry} switch is a duplicate of the generic
6181
@samp{--entry} switch, in that it sets the program's starting address.
6182
But it also sets the bottom bit of the address, so that it can be
6183
branched to using a BX instruction, and the program will start
6184
executing in Thumb mode straight away.
6185
 
6186
@cindex PE import table prefixing
6187
@kindex --use-nul-prefixed-import-tables
6188
The @samp{--use-nul-prefixed-import-tables} switch is specifying, that
6189
the import tables idata4 and idata5 have to be generated with a zero
6190
elememt prefix for import libraries. This is the old style to generate
6191
import tables. By default this option is turned off.
6192
 
6193
@cindex BE8
6194
@kindex --be8
6195
The @samp{--be8} switch instructs @command{ld} to generate BE8 format
6196
executables.  This option is only valid when linking big-endian objects.
6197
The resulting image will contain big-endian data and little-endian code.
6198
 
6199
@cindex TARGET1
6200
@kindex --target1-rel
6201
@kindex --target1-abs
6202
The @samp{R_ARM_TARGET1} relocation is typically used for entries in the
6203
@samp{.init_array} section.  It is interpreted as either @samp{R_ARM_REL32}
6204
or @samp{R_ARM_ABS32}, depending on the target.  The @samp{--target1-rel}
6205
and @samp{--target1-abs} switches override the default.
6206
 
6207
@cindex TARGET2
6208
@kindex --target2=@var{type}
6209
The @samp{--target2=type} switch overrides the default definition of the
6210
@samp{R_ARM_TARGET2} relocation.  Valid values for @samp{type}, their
6211
meanings, and target defaults are as follows:
6212
@table @samp
6213
@item rel
6214
@samp{R_ARM_REL32} (arm*-*-elf, arm*-*-eabi)
6215
@item abs
6216
@samp{R_ARM_ABS32} (arm*-*-symbianelf)
6217
@item got-rel
6218
@samp{R_ARM_GOT_PREL} (arm*-*-linux, arm*-*-*bsd)
6219
@end table
6220
 
6221
@cindex FIX_V4BX
6222
@kindex --fix-v4bx
6223
The @samp{R_ARM_V4BX} relocation (defined by the ARM AAELF
6224
specification) enables objects compiled for the ARMv4 architecture to be
6225
interworking-safe when linked with other objects compiled for ARMv4t, but
6226
also allows pure ARMv4 binaries to be built from the same ARMv4 objects.
6227
 
6228
In the latter case, the switch @option{--fix-v4bx} must be passed to the
6229
linker, which causes v4t @code{BX rM} instructions to be rewritten as
6230
@code{MOV PC,rM}, since v4 processors do not have a @code{BX} instruction.
6231
 
6232
In the former case, the switch should not be used, and @samp{R_ARM_V4BX}
6233
relocations are ignored.
6234
 
6235
@cindex FIX_V4BX_INTERWORKING
6236
@kindex --fix-v4bx-interworking
6237
Replace @code{BX rM} instructions identified by @samp{R_ARM_V4BX}
6238
relocations with a branch to the following veneer:
6239
 
6240
@smallexample
6241
TST rM, #1
6242
MOVEQ PC, rM
6243
BX Rn
6244
@end smallexample
6245
 
6246
This allows generation of libraries/applications that work on ARMv4 cores
6247
and are still interworking safe.  Note that the above veneer clobbers the
6248
condition flags, so may cause incorrect progrm behavior in rare cases.
6249
 
6250
@cindex USE_BLX
6251
@kindex --use-blx
6252
The @samp{--use-blx} switch enables the linker to use ARM/Thumb
6253
BLX instructions (available on ARMv5t and above) in various
6254
situations. Currently it is used to perform calls via the PLT from Thumb
6255
code using BLX rather than using BX and a mode-switching stub before
6256
each PLT entry. This should lead to such calls executing slightly faster.
6257
 
6258
This option is enabled implicitly for SymbianOS, so there is no need to
6259
specify it if you are using that target.
6260
 
6261
@cindex VFP11_DENORM_FIX
6262
@kindex --vfp11-denorm-fix
6263
The @samp{--vfp11-denorm-fix} switch enables a link-time workaround for a
6264
bug in certain VFP11 coprocessor hardware, which sometimes allows
6265
instructions with denorm operands (which must be handled by support code)
6266
to have those operands overwritten by subsequent instructions before
6267
the support code can read the intended values.
6268
 
6269
The bug may be avoided in scalar mode if you allow at least one
6270
intervening instruction between a VFP11 instruction which uses a register
6271
and another instruction which writes to the same register, or at least two
6272
intervening instructions if vector mode is in use. The bug only affects
6273
full-compliance floating-point mode: you do not need this workaround if
6274
you are using "runfast" mode. Please contact ARM for further details.
6275
 
6276
If you know you are using buggy VFP11 hardware, you can
6277
enable this workaround by specifying the linker option
6278
@samp{--vfp-denorm-fix=scalar} if you are using the VFP11 scalar
6279
mode only, or @samp{--vfp-denorm-fix=vector} if you are using
6280
vector mode (the latter also works for scalar code). The default is
6281
@samp{--vfp-denorm-fix=none}.
6282
 
6283
If the workaround is enabled, instructions are scanned for
6284
potentially-troublesome sequences, and a veneer is created for each
6285
such sequence which may trigger the erratum. The veneer consists of the
6286
first instruction of the sequence and a branch back to the subsequent
6287
instruction. The original instruction is then replaced with a branch to
6288
the veneer. The extra cycles required to call and return from the veneer
6289
are sufficient to avoid the erratum in both the scalar and vector cases.
6290
 
6291
@cindex NO_ENUM_SIZE_WARNING
6292
@kindex --no-enum-size-warning
6293
The @option{--no-enum-size-warning} switch prevents the linker from
6294
warning when linking object files that specify incompatible EABI
6295
enumeration size attributes.  For example, with this switch enabled,
6296
linking of an object file using 32-bit enumeration values with another
6297
using enumeration values fitted into the smallest possible space will
6298
not be diagnosed.
6299
 
6300
@cindex NO_WCHAR_SIZE_WARNING
6301
@kindex --no-wchar-size-warning
6302
The @option{--no-wchar-size-warning} switch prevents the linker from
6303
warning when linking object files that specify incompatible EABI
6304
@code{wchar_t} size attributes.  For example, with this switch enabled,
6305
linking of an object file using 32-bit @code{wchar_t} values with another
6306
using 16-bit @code{wchar_t} values will not be diagnosed.
6307
 
6308
@cindex PIC_VENEER
6309
@kindex --pic-veneer
6310
The @samp{--pic-veneer} switch makes the linker use PIC sequences for
6311
ARM/Thumb interworking veneers, even if the rest of the binary
6312
is not PIC.  This avoids problems on uClinux targets where
6313
@samp{--emit-relocs} is used to generate relocatable binaries.
6314
 
6315
@cindex STUB_GROUP_SIZE
6316
@kindex --stub-group-size=@var{N}
6317
The linker will automatically generate and insert small sequences of
6318
code into a linked ARM ELF executable whenever an attempt is made to
6319
perform a function call to a symbol that is too far away.  The
6320
placement of these sequences of instructions - called stubs - is
6321
controlled by the command line option @option{--stub-group-size=N}.
6322
The placement is important because a poor choice can create a need for
6323
duplicate stubs, increasing the code sizw.  The linker will try to
6324
group stubs together in order to reduce interruptions to the flow of
6325
code, but it needs guidance as to how big these groups should be and
6326
where they should be placed.
6327
 
6328
The value of @samp{N}, the parameter to the
6329
@option{--stub-group-size=} option controls where the stub groups are
6330
placed.  If it is negative then all stubs are placed after the first
6331
branch that needs them.  If it is positive then the stubs can be
6332
placed either before or after the branches that need them.  If the
6333
value of @samp{N} is 1 (either +1 or -1) then the linker will choose
6334
exactly where to place groups of stubs, using its built in heuristics.
6335
A value of @samp{N} greater than 1 (or smaller than -1) tells the
6336
linker that a single group of stubs can service at most @samp{N} bytes
6337
from the input sections.
6338
 
6339
The default, if @option{--stub-group-size=} is not specified, is
6340
@samp{N = +1}.
6341
 
6342
Farcalls stubs insertion is fully supported for the ARM-EABI target
6343
only, because it relies on object files properties not present
6344
otherwise.
6345
 
6346
@ifclear GENERIC
6347
@lowersections
6348
@end ifclear
6349
@end ifset
6350
 
6351
@ifset HPPA
6352
@ifclear GENERIC
6353
@raisesections
6354
@end ifclear
6355
 
6356
@node HPPA ELF32
6357
@section @command{ld} and HPPA 32-bit ELF Support
6358
@cindex HPPA multiple sub-space stubs
6359
@kindex --multi-subspace
6360
When generating a shared library, @command{ld} will by default generate
6361
import stubs suitable for use with a single sub-space application.
6362
The @samp{--multi-subspace} switch causes @command{ld} to generate export
6363
stubs, and different (larger) import stubs suitable for use with
6364
multiple sub-spaces.
6365
 
6366
@cindex HPPA stub grouping
6367
@kindex --stub-group-size=@var{N}
6368
Long branch stubs and import/export stubs are placed by @command{ld} in
6369
stub sections located between groups of input sections.
6370
@samp{--stub-group-size} specifies the maximum size of a group of input
6371
sections handled by one stub section.  Since branch offsets are signed,
6372
a stub section may serve two groups of input sections, one group before
6373
the stub section, and one group after it.  However, when using
6374
conditional branches that require stubs, it may be better (for branch
6375
prediction) that stub sections only serve one group of input sections.
6376
A negative value for @samp{N} chooses this scheme, ensuring that
6377
branches to stubs always use a negative offset.  Two special values of
6378
@samp{N} are recognized, @samp{1} and @samp{-1}.  These both instruct
6379
@command{ld} to automatically size input section groups for the branch types
6380
detected, with the same behaviour regarding stub placement as other
6381
positive or negative values of @samp{N} respectively.
6382
 
6383
Note that @samp{--stub-group-size} does not split input sections.  A
6384
single input section larger than the group size specified will of course
6385
create a larger group (of one section).  If input sections are too
6386
large, it may not be possible for a branch to reach its stub.
6387
 
6388
@ifclear GENERIC
6389
@lowersections
6390
@end ifclear
6391
@end ifset
6392
 
6393
@ifset M68K
6394
@ifclear GENERIC
6395
@raisesections
6396
@end ifclear
6397
 
6398
@node M68K
6399
@section @command{ld} and the Motorola 68K family
6400
 
6401
@cindex Motorola 68K GOT generation
6402
@kindex --got=@var{type}
6403
The @samp{--got=@var{type}} option lets you choose the GOT generation scheme.
6404
The choices are @samp{single}, @samp{negative}, @samp{multigot} and
6405
@samp{target}.  When @samp{target} is selected the linker chooses
6406
the default GOT generation scheme for the current target.
6407
@samp{single} tells the linker to generate a single GOT with
6408
entries only at non-negative offsets.
6409
@samp{negative} instructs the linker to generate a single GOT with
6410
entries at both negative and positive offsets.  Not all environments
6411
support such GOTs.
6412
@samp{multigot} allows the linker to generate several GOTs in the
6413
output file.  All GOT references from a single input object
6414
file access the same GOT, but references from different input object
6415
files might access different GOTs.  Not all environments support such GOTs.
6416
 
6417
@ifclear GENERIC
6418
@lowersections
6419
@end ifclear
6420
@end ifset
6421
 
6422
@ifset MMIX
6423
@ifclear GENERIC
6424
@raisesections
6425
@end ifclear
6426
 
6427
@node MMIX
6428
@section @code{ld} and MMIX
6429
For MMIX, there is a choice of generating @code{ELF} object files or
6430
@code{mmo} object files when linking.  The simulator @code{mmix}
6431
understands the @code{mmo} format.  The binutils @code{objcopy} utility
6432
can translate between the two formats.
6433
 
6434
There is one special section, the @samp{.MMIX.reg_contents} section.
6435
Contents in this section is assumed to correspond to that of global
6436
registers, and symbols referring to it are translated to special symbols,
6437
equal to registers.  In a final link, the start address of the
6438
@samp{.MMIX.reg_contents} section corresponds to the first allocated
6439
global register multiplied by 8.  Register @code{$255} is not included in
6440
this section; it is always set to the program entry, which is at the
6441
symbol @code{Main} for @code{mmo} files.
6442
 
6443
Global symbols with the prefix @code{__.MMIX.start.}, for example
6444
@code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special.
6445
The default linker script uses these to set the default start address
6446
of a section.
6447
 
6448
Initial and trailing multiples of zero-valued 32-bit words in a section,
6449
are left out from an mmo file.
6450
 
6451
@ifclear GENERIC
6452
@lowersections
6453
@end ifclear
6454
@end ifset
6455
 
6456
@ifset MSP430
6457
@ifclear GENERIC
6458
@raisesections
6459
@end ifclear
6460
 
6461
@node  MSP430
6462
@section @code{ld} and MSP430
6463
For the MSP430 it is possible to select the MPU architecture.  The flag @samp{-m [mpu type]}
6464
will select an appropriate linker script for selected MPU type.  (To get a list of known MPUs
6465
just pass @samp{-m help} option to the linker).
6466
 
6467
@cindex MSP430 extra sections
6468
The linker will recognize some extra sections which are MSP430 specific:
6469
 
6470
@table @code
6471
@item @samp{.vectors}
6472
Defines a portion of ROM where interrupt vectors located.
6473
 
6474
@item @samp{.bootloader}
6475
Defines the bootloader portion of the ROM (if applicable).  Any code
6476
in this section will be uploaded to the MPU.
6477
 
6478
@item @samp{.infomem}
6479
Defines an information memory section (if applicable).  Any code in
6480
this section will be uploaded to the MPU.
6481
 
6482
@item @samp{.infomemnobits}
6483
This is the same as the @samp{.infomem} section except that any code
6484
in this section will not be uploaded to the MPU.
6485
 
6486
@item @samp{.noinit}
6487
Denotes a portion of RAM located above @samp{.bss} section.
6488
 
6489
The last two sections are used by gcc.
6490
@end table
6491
 
6492
@ifclear GENERIC
6493
@lowersections
6494
@end ifclear
6495
@end ifset
6496
 
6497
@ifset POWERPC
6498
@ifclear GENERIC
6499
@raisesections
6500
@end ifclear
6501
 
6502
@node PowerPC ELF32
6503
@section @command{ld} and PowerPC 32-bit ELF Support
6504
@cindex PowerPC long branches
6505
@kindex --relax on PowerPC
6506
Branches on PowerPC processors are limited to a signed 26-bit
6507
displacement, which may result in @command{ld} giving
6508
@samp{relocation truncated to fit} errors with very large programs.
6509
@samp{--relax} enables the generation of trampolines that can access
6510
the entire 32-bit address space.  These trampolines are inserted at
6511
section boundaries, so may not themselves be reachable if an input
6512
section exceeds 33M in size.  You may combine @samp{-r} and
6513
@samp{--relax} to add trampolines in a partial link.  In that case
6514
both branches to undefined symbols and inter-section branches are also
6515
considered potentially out of range, and trampolines inserted.
6516
 
6517
@cindex PowerPC ELF32 options
6518
@table @option
6519
@cindex PowerPC PLT
6520
@kindex --bss-plt
6521
@item --bss-plt
6522
Current PowerPC GCC accepts a @samp{-msecure-plt} option that
6523
generates code capable of using a newer PLT and GOT layout that has
6524
the security advantage of no executable section ever needing to be
6525
writable and no writable section ever being executable.  PowerPC
6526
@command{ld} will generate this layout, including stubs to access the
6527
PLT, if all input files (including startup and static libraries) were
6528
compiled with @samp{-msecure-plt}.  @samp{--bss-plt} forces the old
6529
BSS PLT (and GOT layout) which can give slightly better performance.
6530
 
6531
@kindex --secure-plt
6532
@item --secure-plt
6533
@command{ld} will use the new PLT and GOT layout if it is linking new
6534
@samp{-fpic} or @samp{-fPIC} code, but does not do so automatically
6535
when linking non-PIC code.  This option requests the new PLT and GOT
6536
layout.  A warning will be given if some object file requires the old
6537
style BSS PLT.
6538
 
6539
@cindex PowerPC GOT
6540
@kindex --sdata-got
6541
@item --sdata-got
6542
The new secure PLT and GOT are placed differently relative to other
6543
sections compared to older BSS PLT and GOT placement.  The location of
6544
@code{.plt} must change because the new secure PLT is an initialized
6545
section while the old PLT is uninitialized.  The reason for the
6546
@code{.got} change is more subtle:  The new placement allows
6547
@code{.got} to be read-only in applications linked with
6548
@samp{-z relro -z now}.  However, this placement means that
6549
@code{.sdata} cannot always be used in shared libraries, because the
6550
PowerPC ABI accesses @code{.sdata} in shared libraries from the GOT
6551
pointer.  @samp{--sdata-got} forces the old GOT placement.  PowerPC
6552
GCC doesn't use @code{.sdata} in shared libraries, so this option is
6553
really only useful for other compilers that may do so.
6554
 
6555
@cindex PowerPC stub symbols
6556
@kindex --emit-stub-syms
6557
@item --emit-stub-syms
6558
This option causes @command{ld} to label linker stubs with a local
6559
symbol that encodes the stub type and destination.
6560
 
6561
@cindex PowerPC TLS optimization
6562
@kindex --no-tls-optimize
6563
@item --no-tls-optimize
6564
PowerPC @command{ld} normally performs some optimization of code
6565
sequences used to access Thread-Local Storage.  Use this option to
6566
disable the optimization.
6567
@end table
6568
 
6569
@ifclear GENERIC
6570
@lowersections
6571
@end ifclear
6572
@end ifset
6573
 
6574
@ifset POWERPC64
6575
@ifclear GENERIC
6576
@raisesections
6577
@end ifclear
6578
 
6579
@node PowerPC64 ELF64
6580
@section @command{ld} and PowerPC64 64-bit ELF Support
6581
 
6582
@cindex PowerPC64 ELF64 options
6583
@table @option
6584
@cindex PowerPC64 stub grouping
6585
@kindex --stub-group-size
6586
@item --stub-group-size
6587
Long branch stubs, PLT call stubs  and TOC adjusting stubs are placed
6588
by @command{ld} in stub sections located between groups of input sections.
6589
@samp{--stub-group-size} specifies the maximum size of a group of input
6590
sections handled by one stub section.  Since branch offsets are signed,
6591
a stub section may serve two groups of input sections, one group before
6592
the stub section, and one group after it.  However, when using
6593
conditional branches that require stubs, it may be better (for branch
6594
prediction) that stub sections only serve one group of input sections.
6595
A negative value for @samp{N} chooses this scheme, ensuring that
6596
branches to stubs always use a negative offset.  Two special values of
6597
@samp{N} are recognized, @samp{1} and @samp{-1}.  These both instruct
6598
@command{ld} to automatically size input section groups for the branch types
6599
detected, with the same behaviour regarding stub placement as other
6600
positive or negative values of @samp{N} respectively.
6601
 
6602
Note that @samp{--stub-group-size} does not split input sections.  A
6603
single input section larger than the group size specified will of course
6604
create a larger group (of one section).  If input sections are too
6605
large, it may not be possible for a branch to reach its stub.
6606
 
6607
@cindex PowerPC64 stub symbols
6608
@kindex --emit-stub-syms
6609
@item --emit-stub-syms
6610
This option causes @command{ld} to label linker stubs with a local
6611
symbol that encodes the stub type and destination.
6612
 
6613
@cindex PowerPC64 dot symbols
6614
@kindex --dotsyms
6615
@kindex --no-dotsyms
6616
@item --dotsyms, --no-dotsyms
6617
These two options control how @command{ld} interprets version patterns
6618
in a version script.  Older PowerPC64 compilers emitted both a
6619
function descriptor symbol with the same name as the function, and a
6620
code entry symbol with the name prefixed by a dot (@samp{.}).  To
6621
properly version a function @samp{foo}, the version script thus needs
6622
to control both @samp{foo} and @samp{.foo}.  The option
6623
@samp{--dotsyms}, on by default, automatically adds the required
6624
dot-prefixed patterns.  Use @samp{--no-dotsyms} to disable this
6625
feature.
6626
 
6627
@cindex PowerPC64 TLS optimization
6628
@kindex --no-tls-optimize
6629
@item --no-tls-optimize
6630
PowerPC64 @command{ld} normally performs some optimization of code
6631
sequences used to access Thread-Local Storage.  Use this option to
6632
disable the optimization.
6633
 
6634
@cindex PowerPC64 OPD optimization
6635
@kindex --no-opd-optimize
6636
@item --no-opd-optimize
6637
PowerPC64 @command{ld} normally removes @code{.opd} section entries
6638
corresponding to deleted link-once functions, or functions removed by
6639
the action of @samp{--gc-sections} or linker script @code{/DISCARD/}.
6640
Use this option to disable @code{.opd} optimization.
6641
 
6642
@cindex PowerPC64 OPD spacing
6643
@kindex --non-overlapping-opd
6644
@item --non-overlapping-opd
6645
Some PowerPC64 compilers have an option to generate compressed
6646
@code{.opd} entries spaced 16 bytes apart, overlapping the third word,
6647
the static chain pointer (unused in C) with the first word of the next
6648
entry.  This option expands such entries to the full 24 bytes.
6649
 
6650
@cindex PowerPC64 TOC optimization
6651
@kindex --no-toc-optimize
6652
@item --no-toc-optimize
6653
PowerPC64 @command{ld} normally removes unused @code{.toc} section
6654
entries.  Such entries are detected by examining relocations that
6655
reference the TOC in code sections.  A reloc in a deleted code section
6656
marks a TOC word as unneeded, while a reloc in a kept code section
6657
marks a TOC word as needed.  Since the TOC may reference itself, TOC
6658
relocs are also examined.  TOC words marked as both needed and
6659
unneeded will of course be kept.  TOC words without any referencing
6660
reloc are assumed to be part of a multi-word entry, and are kept or
6661
discarded as per the nearest marked preceding word.  This works
6662
reliably for compiler generated code, but may be incorrect if assembly
6663
code is used to insert TOC entries.  Use this option to disable the
6664
optimization.
6665
 
6666
@cindex PowerPC64 multi-TOC
6667
@kindex --no-multi-toc
6668
@item --no-multi-toc
6669
By default, PowerPC64 GCC generates code for a TOC model where TOC
6670
entries are accessed with a 16-bit offset from r2.  This limits the
6671
total TOC size to 64K.  PowerPC64 @command{ld} extends this limit by
6672
grouping code sections such that each group uses less than 64K for its
6673
TOC entries, then inserts r2 adjusting stubs between inter-group
6674
calls.  @command{ld} does not split apart input sections, so cannot
6675
help if a single input file has a @code{.toc} section that exceeds
6676
64K, most likely from linking multiple files with @command{ld -r}.
6677
Use this option to turn off this feature.
6678
@end table
6679
 
6680
@ifclear GENERIC
6681
@lowersections
6682
@end ifclear
6683
@end ifset
6684
 
6685
@ifset SPU
6686
@ifclear GENERIC
6687
@raisesections
6688
@end ifclear
6689
 
6690
@node SPU ELF
6691
@section @command{ld} and SPU ELF Support
6692
 
6693
@cindex SPU ELF options
6694
@table @option
6695
 
6696
@cindex SPU plugins
6697
@kindex --plugin
6698
@item --plugin
6699
This option marks an executable as a PIC plugin module.
6700
 
6701
@cindex SPU overlays
6702
@kindex --no-overlays
6703
@item --no-overlays
6704
Normally, @command{ld} recognizes calls to functions within overlay
6705
regions, and redirects such calls to an overlay manager via a stub.
6706
@command{ld} also provides a built-in overlay manager.  This option
6707
turns off all this special overlay handling.
6708
 
6709
@cindex SPU overlay stub symbols
6710
@kindex --emit-stub-syms
6711
@item --emit-stub-syms
6712
This option causes @command{ld} to label overlay stubs with a local
6713
symbol that encodes the stub type and destination.
6714
 
6715
@cindex SPU extra overlay stubs
6716
@kindex --extra-overlay-stubs
6717
@item --extra-overlay-stubs
6718
This option causes @command{ld} to add overlay call stubs on all
6719
function calls out of overlay regions.  Normally stubs are not added
6720
on calls to non-overlay regions.
6721
 
6722
@cindex SPU local store size
6723
@kindex --local-store=lo:hi
6724
@item --local-store=lo:hi
6725
@command{ld} usually checks that a final executable for SPU fits in
6726
the address range 0 to 256k.  This option may be used to change the
6727
range.  Disable the check entirely with @option{--local-store=0:0}.
6728
 
6729
@cindex SPU
6730
@kindex --stack-analysis
6731
@item --stack-analysis
6732
SPU local store space is limited.  Over-allocation of stack space
6733
unnecessarily limits space available for code and data, while
6734
under-allocation results in runtime failures.  If given this option,
6735
@command{ld} will provide an estimate of maximum stack usage.
6736
@command{ld} does this by examining symbols in code sections to
6737
determine the extents of functions, and looking at function prologues
6738
for stack adjusting instructions.  A call-graph is created by looking
6739
for relocations on branch instructions.  The graph is then searched
6740
for the maximum stack usage path.  Note that this analysis does not
6741
find calls made via function pointers, and does not handle recursion
6742
and other cycles in the call graph.  Stack usage may be
6743
under-estimated if your code makes such calls.  Also, stack usage for
6744
dynamic allocation, e.g. alloca, will not be detected.  If a link map
6745
is requested, detailed information about each function's stack usage
6746
and calls will be given.
6747
 
6748
@cindex SPU
6749
@kindex --emit-stack-syms
6750
@item --emit-stack-syms
6751
This option, if given along with @option{--stack-analysis} will result
6752
in @command{ld} emitting stack sizing symbols for each function.
6753
These take the form @code{__stack_<function_name>} for global
6754
functions, and @code{__stack_<number>_<function_name>} for static
6755
functions.  @code{<number>} is the section id in hex.  The value of
6756
such symbols is the stack requirement for the corresponding function.
6757
The symbol size will be zero, type @code{STT_NOTYPE}, binding
6758
@code{STB_LOCAL}, and section @code{SHN_ABS}.
6759
@end table
6760
 
6761
@ifclear GENERIC
6762
@lowersections
6763
@end ifclear
6764
@end ifset
6765
 
6766
@ifset TICOFF
6767
@ifclear GENERIC
6768
@raisesections
6769
@end ifclear
6770
 
6771
@node TI COFF
6772
@section @command{ld}'s Support for Various TI COFF Versions
6773
@cindex TI COFF versions
6774
@kindex --format=@var{version}
6775
The @samp{--format} switch allows selection of one of the various
6776
TI COFF versions.  The latest of this writing is 2; versions 0 and 1 are
6777
also supported.  The TI COFF versions also vary in header byte-order
6778
format; @command{ld} will read any version or byte order, but the output
6779
header format depends on the default specified by the specific target.
6780
 
6781
@ifclear GENERIC
6782
@lowersections
6783
@end ifclear
6784
@end ifset
6785
 
6786
@ifset WIN32
6787
@ifclear GENERIC
6788
@raisesections
6789
@end ifclear
6790
 
6791
@node WIN32
6792
@section @command{ld} and WIN32 (cygwin/mingw)
6793
 
6794
This section describes some of the win32 specific @command{ld} issues.
6795
See @ref{Options,,Command Line Options} for detailed description of the
6796
command line options mentioned here.
6797
 
6798
@table @emph
6799
@cindex import libraries
6800
@item import libraries
6801
The standard Windows linker creates and uses so-called import
6802
libraries, which contains information for linking to dll's.  They are
6803
regular static archives and are handled as any other static
6804
archive.  The cygwin and mingw ports of @command{ld} have specific
6805
support for creating such libraries provided with the
6806
@samp{--out-implib} command line option.
6807
 
6808
@item   exporting DLL symbols
6809
@cindex exporting DLL symbols
6810
The cygwin/mingw @command{ld} has several ways to export symbols for dll's.
6811
 
6812
@table @emph
6813
@item   using auto-export functionality
6814
@cindex using auto-export functionality
6815
By default @command{ld} exports symbols with the auto-export functionality,
6816
which is controlled by the following command line options:
6817
 
6818
@itemize
6819
@item --export-all-symbols   [This is the default]
6820
@item --exclude-symbols
6821
@item --exclude-libs
6822
@item --exclude-modules-for-implib
6823
@item --version-script
6824
@end itemize
6825
 
6826
When auto-export is in operation, @command{ld} will export all the non-local
6827
(global and common) symbols it finds in a DLL, with the exception of a few
6828
symbols known to belong to the system's runtime and libraries.  As it will
6829
often not be desirable to export all of a DLL's symbols, which may include
6830
private functions that are not part of any public interface, the command-line
6831
options listed above may be used to filter symbols out from the list for
6832
exporting.  The @samp{--output-def} option can be used in order to see the
6833
final list of exported symbols with all exclusions taken into effect.
6834
 
6835
If @samp{--export-all-symbols} is not given explicitly on the
6836
command line, then the default auto-export behavior will be @emph{disabled}
6837
if either of the following are true:
6838
 
6839
@itemize
6840
@item A DEF file is used.
6841
@item Any symbol in any object file was marked with the __declspec(dllexport) attribute.
6842
@end itemize
6843
 
6844
@item   using a DEF file
6845
@cindex using a DEF file
6846
Another way of exporting symbols is using a DEF file.  A DEF file is
6847
an ASCII file containing definitions of symbols which should be
6848
exported when a dll is created.  Usually it is named @samp{<dll
6849
name>.def} and is added as any other object file to the linker's
6850
command line.  The file's name must end in @samp{.def} or @samp{.DEF}.
6851
 
6852
@example
6853
gcc -o <output> <objectfiles> <dll name>.def
6854
@end example
6855
 
6856
Using a DEF file turns off the normal auto-export behavior, unless the
6857
@samp{--export-all-symbols} option is also used.
6858
 
6859
Here is an example of a DEF file for a shared library called @samp{xyz.dll}:
6860
 
6861
@example
6862
LIBRARY "xyz.dll" BASE=0x20000000
6863
 
6864
EXPORTS
6865
foo
6866
bar
6867
_bar = bar
6868
another_foo = abc.dll.afoo
6869
var1 DATA
6870
doo = foo == foo2
6871
eoo DATA == var1
6872
@end example
6873
 
6874
This example defines a DLL with a non-default base address and seven
6875
symbols in the export table. The third exported symbol @code{_bar} is an
6876
alias for the second. The fourth symbol, @code{another_foo} is resolved
6877
by "forwarding" to another module and treating it as an alias for
6878
@code{afoo} exported from the DLL @samp{abc.dll}. The final symbol
6879
@code{var1} is declared to be a data object. The @samp{doo} symbol in
6880
export library is an alias of @samp{foo}, which gets the string name
6881
in export table @samp{foo2}. The @samp{eoo} symbol is an data export
6882
symbol, which gets in export table the name @samp{var1}.
6883
 
6884
The optional @code{LIBRARY <name>} command indicates the @emph{internal}
6885
name of the output DLL. If @samp{<name>} does not include a suffix,
6886
the default library suffix, @samp{.DLL} is appended.
6887
 
6888
When the .DEF file is used to build an application, rather than a
6889
library, the @code{NAME <name>} command should be used instead of
6890
@code{LIBRARY}. If @samp{<name>} does not include a suffix, the default
6891
executable suffix, @samp{.EXE} is appended.
6892
 
6893
With either @code{LIBRARY <name>} or @code{NAME <name>} the optional
6894
specification @code{BASE = <number>} may be used to specify a
6895
non-default base address for the image.
6896
 
6897
If neither @code{LIBRARY <name>} nor  @code{NAME <name>} is specified,
6898
or they specify an empty string, the internal name is the same as the
6899
filename specified on the command line.
6900
 
6901
The complete specification of an export symbol is:
6902
 
6903
@example
6904
EXPORTS
6905
  ( (  ( <name1> [ = <name2> ] )
6906
     | ( <name1> = <module-name> . <external-name>))
6907
  [ @@ <integer> ] [NONAME] [DATA] [CONSTANT] [PRIVATE] [== <name3>] ) *
6908
@end example
6909
 
6910
Declares @samp{<name1>} as an exported symbol from the DLL, or declares
6911
@samp{<name1>} as an exported alias for @samp{<name2>}; or declares
6912
@samp{<name1>} as a "forward" alias for the symbol
6913
@samp{<external-name>} in the DLL @samp{<module-name>}.
6914
Optionally, the symbol may be exported by the specified ordinal
6915
@samp{<integer>} alias. The optional @samp{<name3>} is the to be used
6916
string in import/export table for the symbol.
6917
 
6918
The optional keywords that follow the declaration indicate:
6919
 
6920
@code{NONAME}: Do not put the symbol name in the DLL's export table.  It
6921
will still be exported by its ordinal alias (either the value specified
6922
by the .def specification or, otherwise, the value assigned by the
6923
linker). The symbol name, however, does remain visible in the import
6924
library (if any), unless @code{PRIVATE} is also specified.
6925
 
6926
@code{DATA}: The symbol is a variable or object, rather than a function.
6927
The import lib will export only an indirect reference to @code{foo} as
6928
the symbol @code{_imp__foo} (ie, @code{foo} must be resolved as
6929
@code{*_imp__foo}).
6930
 
6931
@code{CONSTANT}: Like @code{DATA}, but put the undecorated @code{foo} as
6932
well as @code{_imp__foo} into the import library. Both refer to the
6933
read-only import address table's pointer to the variable, not to the
6934
variable itself. This can be dangerous. If the user code fails to add
6935
the @code{dllimport} attribute and also fails to explicitly add the
6936
extra indirection that the use of the attribute enforces, the
6937
application will behave unexpectedly.
6938
 
6939
@code{PRIVATE}: Put the symbol in the DLL's export table, but do not put
6940
it into the static import library used to resolve imports at link time. The
6941
symbol can still be imported using the @code{LoadLibrary/GetProcAddress}
6942
API at runtime or by by using the GNU ld extension of linking directly to
6943
the DLL without an import library.
6944
 
6945
See ld/deffilep.y in the binutils sources for the full specification of
6946
other DEF file statements
6947
 
6948
@cindex creating a DEF file
6949
While linking a shared dll, @command{ld} is able to create a DEF file
6950
with the @samp{--output-def <file>} command line option.
6951
 
6952
@item   Using decorations
6953
@cindex Using decorations
6954
Another way of marking symbols for export is to modify the source code
6955
itself, so that when building the DLL each symbol to be exported is
6956
declared as:
6957
 
6958
@example
6959
__declspec(dllexport) int a_variable
6960
__declspec(dllexport) void a_function(int with_args)
6961
@end example
6962
 
6963
All such symbols will be exported from the DLL.  If, however,
6964
any of the object files in the DLL contain symbols decorated in
6965
this way, then the normal auto-export behavior is disabled, unless
6966
the @samp{--export-all-symbols} option is also used.
6967
 
6968
Note that object files that wish to access these symbols must @emph{not}
6969
decorate them with dllexport.  Instead, they should use dllimport,
6970
instead:
6971
 
6972
@example
6973
__declspec(dllimport) int a_variable
6974
__declspec(dllimport) void a_function(int with_args)
6975
@end example
6976
 
6977
This complicates the structure of library header files, because
6978
when included by the library itself the header must declare the
6979
variables and functions as dllexport, but when included by client
6980
code the header must declare them as dllimport.  There are a number
6981
of idioms that are typically used to do this; often client code can
6982
omit the __declspec() declaration completely.  See
6983
@samp{--enable-auto-import} and @samp{automatic data imports} for more
6984
information.
6985
@end table
6986
 
6987
@cindex automatic data imports
6988
@item automatic data imports
6989
The standard Windows dll format supports data imports from dlls only
6990
by adding special decorations (dllimport/dllexport), which let the
6991
compiler produce specific assembler instructions to deal with this
6992
issue.  This increases the effort necessary to port existing Un*x
6993
code to these platforms, especially for large
6994
c++ libraries and applications.  The auto-import feature, which was
6995
initially provided by Paul Sokolovsky, allows one to omit the
6996
decorations to achieve a behavior that conforms to that on POSIX/Un*x
6997
platforms. This feature is enabled with the @samp{--enable-auto-import}
6998
command-line option, although it is enabled by default on cygwin/mingw.
6999
The @samp{--enable-auto-import} option itself now serves mainly to
7000
suppress any warnings that are ordinarily emitted when linked objects
7001
trigger the feature's use.
7002
 
7003
auto-import of variables does not always work flawlessly without
7004
additional assistance.  Sometimes, you will see this message
7005
 
7006
"variable '<var>' can't be auto-imported. Please read the
7007
documentation for ld's @code{--enable-auto-import} for details."
7008
 
7009
The @samp{--enable-auto-import} documentation explains why this error
7010
occurs, and several methods that can be used to overcome this difficulty.
7011
One of these methods is the @emph{runtime pseudo-relocs} feature, described
7012
below.
7013
 
7014
@cindex runtime pseudo-relocation
7015
For complex variables imported from DLLs (such as structs or classes),
7016
object files typically contain a base address for the variable and an
7017
offset (@emph{addend}) within the variable--to specify a particular
7018
field or public member, for instance.  Unfortunately, the runtime loader used
7019
in win32 environments is incapable of fixing these references at runtime
7020
without the additional information supplied by dllimport/dllexport decorations.
7021
The standard auto-import feature described above is unable to resolve these
7022
references.
7023
 
7024
The @samp{--enable-runtime-pseudo-relocs} switch allows these references to
7025
be resolved without error, while leaving the task of adjusting the references
7026
themselves (with their non-zero addends) to specialized code provided by the
7027
runtime environment.  Recent versions of the cygwin and mingw environments and
7028
compilers provide this runtime support; older versions do not.  However, the
7029
support is only necessary on the developer's platform; the compiled result will
7030
run without error on an older system.
7031
 
7032
@samp{--enable-runtime-pseudo-relocs} is not the default; it must be explicitly
7033
enabled as needed.
7034
 
7035
@cindex direct linking to a dll
7036
@item direct linking to a dll
7037
The cygwin/mingw ports of @command{ld} support the direct linking,
7038
including data symbols, to a dll without the usage of any import
7039
libraries.  This is much faster and uses much less memory than does the
7040
traditional import library method, especially when linking large
7041
libraries or applications.  When @command{ld} creates an import lib, each
7042
function or variable exported from the dll is stored in its own bfd, even
7043
though a single bfd could contain many exports.  The overhead involved in
7044
storing, loading, and processing so many bfd's is quite large, and explains the
7045
tremendous time, memory, and storage needed to link against particularly
7046
large or complex libraries when using import libs.
7047
 
7048
Linking directly to a dll uses no extra command-line switches other than
7049
@samp{-L} and @samp{-l}, because @command{ld} already searches for a number
7050
of names to match each library.  All that is needed from the developer's
7051
perspective is an understanding of this search, in order to force ld to
7052
select the dll instead of an import library.
7053
 
7054
 
7055
For instance, when ld is called with the argument @samp{-lxxx} it will attempt
7056
to find, in the first directory of its search path,
7057
 
7058
@example
7059
libxxx.dll.a
7060
xxx.dll.a
7061
libxxx.a
7062
xxx.lib
7063
cygxxx.dll (*)
7064
libxxx.dll
7065
xxx.dll
7066
@end example
7067
 
7068
before moving on to the next directory in the search path.
7069
 
7070
(*) Actually, this is not @samp{cygxxx.dll} but in fact is @samp{<prefix>xxx.dll},
7071
where @samp{<prefix>} is set by the @command{ld} option
7072
@samp{--dll-search-prefix=<prefix>}. In the case of cygwin, the standard gcc spec
7073
file includes @samp{--dll-search-prefix=cyg}, so in effect we actually search for
7074
@samp{cygxxx.dll}.
7075
 
7076
Other win32-based unix environments, such as mingw or pw32, may use other
7077
@samp{<prefix>}es, although at present only cygwin makes use of this feature.  It
7078
was originally intended to help avoid name conflicts among dll's built for the
7079
various win32/un*x environments, so that (for example) two versions of a zlib dll
7080
could coexist on the same machine.
7081
 
7082
The generic cygwin/mingw path layout uses a @samp{bin} directory for
7083
applications and dll's and a @samp{lib} directory for the import
7084
libraries (using cygwin nomenclature):
7085
 
7086
@example
7087
bin/
7088
        cygxxx.dll
7089
lib/
7090
        libxxx.dll.a   (in case of dll's)
7091
        libxxx.a       (in case of static archive)
7092
@end example
7093
 
7094
Linking directly to a dll without using the import library can be
7095
done two ways:
7096
 
7097
1. Use the dll directly by adding the @samp{bin} path to the link line
7098
@example
7099
gcc -Wl,-verbose  -o a.exe -L../bin/ -lxxx
7100
@end example
7101
 
7102
However, as the dll's often have version numbers appended to their names
7103
(@samp{cygncurses-5.dll}) this will often fail, unless one specifies
7104
@samp{-L../bin -lncurses-5} to include the version.  Import libs are generally
7105
not versioned, and do not have this difficulty.
7106
 
7107
2. Create a symbolic link from the dll to a file in the @samp{lib}
7108
directory according to the above mentioned search pattern.  This
7109
should be used to avoid unwanted changes in the tools needed for
7110
making the app/dll.
7111
 
7112
@example
7113
ln -s bin/cygxxx.dll lib/[cyg|lib|]xxx.dll[.a]
7114
@end example
7115
 
7116
Then you can link without any make environment changes.
7117
 
7118
@example
7119
gcc -Wl,-verbose  -o a.exe -L../lib/ -lxxx
7120
@end example
7121
 
7122
This technique also avoids the version number problems, because the following is
7123
perfectly legal
7124
 
7125
@example
7126
bin/
7127
        cygxxx-5.dll
7128
lib/
7129
        libxxx.dll.a -> ../bin/cygxxx-5.dll
7130
@end example
7131
 
7132
Linking directly to a dll without using an import lib will work
7133
even when auto-import features are exercised, and even when
7134
@samp{--enable-runtime-pseudo-relocs} is used.
7135
 
7136
Given the improvements in speed and memory usage, one might justifiably
7137
wonder why import libraries are used at all.  There are three reasons:
7138
 
7139
1. Until recently, the link-directly-to-dll functionality did @emph{not}
7140
work with auto-imported data.
7141
 
7142
2. Sometimes it is necessary to include pure static objects within the
7143
import library (which otherwise contains only bfd's for indirection
7144
symbols that point to the exports of a dll).  Again, the import lib
7145
for the cygwin kernel makes use of this ability, and it is not
7146
possible to do this without an import lib.
7147
 
7148
3. Symbol aliases can only be resolved using an import lib.  This is
7149
critical when linking against OS-supplied dll's (eg, the win32 API)
7150
in which symbols are usually exported as undecorated aliases of their
7151
stdcall-decorated assembly names.
7152
 
7153
So, import libs are not going away.  But the ability to replace
7154
true import libs with a simple symbolic link to (or a copy of)
7155
a dll, in many cases, is a useful addition to the suite of tools
7156
binutils makes available to the win32 developer.  Given the
7157
massive improvements in memory requirements during linking, storage
7158
requirements, and linking speed, we expect that many developers
7159
will soon begin to use this feature whenever possible.
7160
 
7161
@item symbol aliasing
7162
@table @emph
7163
@item adding additional names
7164
Sometimes, it is useful to export symbols with additional names.
7165
A symbol @samp{foo} will be exported as @samp{foo}, but it can also be
7166
exported as @samp{_foo} by using special directives in the DEF file
7167
when creating the dll.  This will affect also the optional created
7168
import library.  Consider the following DEF file:
7169
 
7170
@example
7171
LIBRARY "xyz.dll" BASE=0x61000000
7172
 
7173
EXPORTS
7174
foo
7175
_foo = foo
7176
@end example
7177
 
7178
The line @samp{_foo = foo} maps the symbol @samp{foo} to @samp{_foo}.
7179
 
7180
Another method for creating a symbol alias is to create it in the
7181
source code using the "weak" attribute:
7182
 
7183
@example
7184
void foo () @{ /* Do something.  */; @}
7185
void _foo () __attribute__ ((weak, alias ("foo")));
7186
@end example
7187
 
7188
See the gcc manual for more information about attributes and weak
7189
symbols.
7190
 
7191
@item renaming symbols
7192
Sometimes it is useful to rename exports.  For instance, the cygwin
7193
kernel does this regularly.  A symbol @samp{_foo} can be exported as
7194
@samp{foo} but not as @samp{_foo} by using special directives in the
7195
DEF file. (This will also affect the import library, if it is
7196
created).  In the following example:
7197
 
7198
@example
7199
LIBRARY "xyz.dll" BASE=0x61000000
7200
 
7201
EXPORTS
7202
_foo = foo
7203
@end example
7204
 
7205
The line @samp{_foo = foo} maps the exported symbol @samp{foo} to
7206
@samp{_foo}.
7207
@end table
7208
 
7209
Note: using a DEF file disables the default auto-export behavior,
7210
unless the @samp{--export-all-symbols} command line option is used.
7211
If, however, you are trying to rename symbols, then you should list
7212
@emph{all} desired exports in the DEF file, including the symbols
7213
that are not being renamed, and do @emph{not} use the
7214
@samp{--export-all-symbols} option.  If you list only the
7215
renamed symbols in the DEF file, and use @samp{--export-all-symbols}
7216
to handle the other symbols, then the both the new names @emph{and}
7217
the original names for the renamed symbols will be exported.
7218
In effect, you'd be aliasing those symbols, not renaming them,
7219
which is probably not what you wanted.
7220
 
7221
@cindex weak externals
7222
@item weak externals
7223
The Windows object format, PE, specifies a form of weak symbols called
7224
weak externals.  When a weak symbol is linked and the symbol is not
7225
defined, the weak symbol becomes an alias for some other symbol.  There
7226
are three variants of weak externals:
7227
@itemize
7228
@item Definition is searched for in objects and libraries, historically
7229
called lazy externals.
7230
@item Definition is searched for only in other objects, not in libraries.
7231
This form is not presently implemented.
7232
@item No search; the symbol is an alias.  This form is not presently
7233
implemented.
7234
@end itemize
7235
As a GNU extension, weak symbols that do not specify an alternate symbol
7236
are supported.  If the symbol is undefined when linking, the symbol
7237
uses a default value.
7238
 
7239
@cindex aligned common symbols
7240
@item aligned common symbols
7241
As a GNU extension to the PE file format, it is possible to specify the
7242
desired alignment for a common symbol.  This information is conveyed from
7243
the assembler or compiler to the linker by means of GNU-specific commands
7244
carried in the object file's @samp{.drectve} section, which are recognized
7245
by @command{ld} and respected when laying out the common symbols.  Native
7246
tools will be able to process object files employing this GNU extension,
7247
but will fail to respect the alignment instructions, and may issue noisy
7248
warnings about unknown linker directives.
7249
@end table
7250
 
7251
@ifclear GENERIC
7252
@lowersections
7253
@end ifclear
7254
@end ifset
7255
 
7256
@ifset XTENSA
7257
@ifclear GENERIC
7258
@raisesections
7259
@end ifclear
7260
 
7261
@node Xtensa
7262
@section @code{ld} and Xtensa Processors
7263
 
7264
@cindex Xtensa processors
7265
The default @command{ld} behavior for Xtensa processors is to interpret
7266
@code{SECTIONS} commands so that lists of explicitly named sections in a
7267
specification with a wildcard file will be interleaved when necessary to
7268
keep literal pools within the range of PC-relative load offsets.  For
7269
example, with the command:
7270
 
7271
@smallexample
7272
SECTIONS
7273
@{
7274
  .text : @{
7275
    *(.literal .text)
7276
  @}
7277
@}
7278
@end smallexample
7279
 
7280
@noindent
7281
@command{ld} may interleave some of the @code{.literal}
7282
and @code{.text} sections from different object files to ensure that the
7283
literal pools are within the range of PC-relative load offsets.  A valid
7284
interleaving might place the @code{.literal} sections from an initial
7285
group of files followed by the @code{.text} sections of that group of
7286
files.  Then, the @code{.literal} sections from the rest of the files
7287
and the @code{.text} sections from the rest of the files would follow.
7288
 
7289
@cindex @option{--relax} on Xtensa
7290
@cindex relaxing on Xtensa
7291
Relaxation is enabled by default for the Xtensa version of @command{ld} and
7292
provides two important link-time optimizations.  The first optimization
7293
is to combine identical literal values to reduce code size.  A redundant
7294
literal will be removed and all the @code{L32R} instructions that use it
7295
will be changed to reference an identical literal, as long as the
7296
location of the replacement literal is within the offset range of all
7297
the @code{L32R} instructions.  The second optimization is to remove
7298
unnecessary overhead from assembler-generated ``longcall'' sequences of
7299
@code{L32R}/@code{CALLX@var{n}} when the target functions are within
7300
range of direct @code{CALL@var{n}} instructions.
7301
 
7302
For each of these cases where an indirect call sequence can be optimized
7303
to a direct call, the linker will change the @code{CALLX@var{n}}
7304
instruction to a @code{CALL@var{n}} instruction, remove the @code{L32R}
7305
instruction, and remove the literal referenced by the @code{L32R}
7306
instruction if it is not used for anything else.  Removing the
7307
@code{L32R} instruction always reduces code size but can potentially
7308
hurt performance by changing the alignment of subsequent branch targets.
7309
By default, the linker will always preserve alignments, either by
7310
switching some instructions between 24-bit encodings and the equivalent
7311
density instructions or by inserting a no-op in place of the @code{L32R}
7312
instruction that was removed.  If code size is more important than
7313
performance, the @option{--size-opt} option can be used to prevent the
7314
linker from widening density instructions or inserting no-ops, except in
7315
a few cases where no-ops are required for correctness.
7316
 
7317
The following Xtensa-specific command-line options can be used to
7318
control the linker:
7319
 
7320
@cindex Xtensa options
7321
@table @option
7322
@item --size-opt
7323
When optimizing indirect calls to direct calls, optimize for code size
7324
more than performance.  With this option, the linker will not insert
7325
no-ops or widen density instructions to preserve branch target
7326
alignment.  There may still be some cases where no-ops are required to
7327
preserve the correctness of the code.
7328
@end table
7329
 
7330
@ifclear GENERIC
7331
@lowersections
7332
@end ifclear
7333
@end ifset
7334
 
7335
@ifclear SingleFormat
7336
@node BFD
7337
@chapter BFD
7338
 
7339
@cindex back end
7340
@cindex object file management
7341
@cindex object formats available
7342
@kindex objdump -i
7343
The linker accesses object and archive files using the BFD libraries.
7344
These libraries allow the linker to use the same routines to operate on
7345
object files whatever the object file format.  A different object file
7346
format can be supported simply by creating a new BFD back end and adding
7347
it to the library.  To conserve runtime memory, however, the linker and
7348
associated tools are usually configured to support only a subset of the
7349
object file formats available.  You can use @code{objdump -i}
7350
(@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
7351
list all the formats available for your configuration.
7352
 
7353
@cindex BFD requirements
7354
@cindex requirements for BFD
7355
As with most implementations, BFD is a compromise between
7356
several conflicting requirements. The major factor influencing
7357
BFD design was efficiency: any time used converting between
7358
formats is time which would not have been spent had BFD not
7359
been involved. This is partly offset by abstraction payback; since
7360
BFD simplifies applications and back ends, more time and care
7361
may be spent optimizing algorithms for a greater speed.
7362
 
7363
One minor artifact of the BFD solution which you should bear in
7364
mind is the potential for information loss.  There are two places where
7365
useful information can be lost using the BFD mechanism: during
7366
conversion and during output. @xref{BFD information loss}.
7367
 
7368
@menu
7369
* BFD outline::                 How it works: an outline of BFD
7370
@end menu
7371
 
7372
@node BFD outline
7373
@section How It Works: An Outline of BFD
7374
@cindex opening object files
7375
@include bfdsumm.texi
7376
@end ifclear
7377
 
7378
@node Reporting Bugs
7379
@chapter Reporting Bugs
7380
@cindex bugs in @command{ld}
7381
@cindex reporting bugs in @command{ld}
7382
 
7383
Your bug reports play an essential role in making @command{ld} reliable.
7384
 
7385
Reporting a bug may help you by bringing a solution to your problem, or
7386
it may not.  But in any case the principal function of a bug report is
7387
to help the entire community by making the next version of @command{ld}
7388
work better.  Bug reports are your contribution to the maintenance of
7389
@command{ld}.
7390
 
7391
In order for a bug report to serve its purpose, you must include the
7392
information that enables us to fix the bug.
7393
 
7394
@menu
7395
* Bug Criteria::                Have you found a bug?
7396
* Bug Reporting::               How to report bugs
7397
@end menu
7398
 
7399
@node Bug Criteria
7400
@section Have You Found a Bug?
7401
@cindex bug criteria
7402
 
7403
If you are not sure whether you have found a bug, here are some guidelines:
7404
 
7405
@itemize @bullet
7406
@cindex fatal signal
7407
@cindex linker crash
7408
@cindex crash of linker
7409
@item
7410
If the linker gets a fatal signal, for any input whatever, that is a
7411
@command{ld} bug.  Reliable linkers never crash.
7412
 
7413
@cindex error on valid input
7414
@item
7415
If @command{ld} produces an error message for valid input, that is a bug.
7416
 
7417
@cindex invalid input
7418
@item
7419
If @command{ld} does not produce an error message for invalid input, that
7420
may be a bug.  In the general case, the linker can not verify that
7421
object files are correct.
7422
 
7423
@item
7424
If you are an experienced user of linkers, your suggestions for
7425
improvement of @command{ld} are welcome in any case.
7426
@end itemize
7427
 
7428
@node Bug Reporting
7429
@section How to Report Bugs
7430
@cindex bug reports
7431
@cindex @command{ld} bugs, reporting
7432
 
7433
A number of companies and individuals offer support for @sc{gnu}
7434
products.  If you obtained @command{ld} from a support organization, we
7435
recommend you contact that organization first.
7436
 
7437
You can find contact information for many support companies and
7438
individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
7439
distribution.
7440
 
7441
@ifset BUGURL
7442
Otherwise, send bug reports for @command{ld} to
7443
@value{BUGURL}.
7444
@end ifset
7445
 
7446
The fundamental principle of reporting bugs usefully is this:
7447
@strong{report all the facts}.  If you are not sure whether to state a
7448
fact or leave it out, state it!
7449
 
7450
Often people omit facts because they think they know what causes the
7451
problem and assume that some details do not matter.  Thus, you might
7452
assume that the name of a symbol you use in an example does not
7453
matter.  Well, probably it does not, but one cannot be sure.  Perhaps
7454
the bug is a stray memory reference which happens to fetch from the
7455
location where that name is stored in memory; perhaps, if the name
7456
were different, the contents of that location would fool the linker
7457
into doing the right thing despite the bug.  Play it safe and give a
7458
specific, complete example.  That is the easiest thing for you to do,
7459
and the most helpful.
7460
 
7461
Keep in mind that the purpose of a bug report is to enable us to fix
7462
the bug if it is new to us.  Therefore, always write your bug reports
7463
on the assumption that the bug has not been reported previously.
7464
 
7465
Sometimes people give a few sketchy facts and ask, ``Does this ring a
7466
bell?''  This cannot help us fix a bug, so it is basically useless.  We
7467
respond by asking for enough details to enable us to investigate.
7468
You might as well expedite matters by sending them to begin with.
7469
 
7470
To enable us to fix the bug, you should include all these things:
7471
 
7472
@itemize @bullet
7473
@item
7474
The version of @command{ld}.  @command{ld} announces it if you start it with
7475
the @samp{--version} argument.
7476
 
7477
Without this, we will not know whether there is any point in looking for
7478
the bug in the current version of @command{ld}.
7479
 
7480
@item
7481
Any patches you may have applied to the @command{ld} source, including any
7482
patches made to the @code{BFD} library.
7483
 
7484
@item
7485
The type of machine you are using, and the operating system name and
7486
version number.
7487
 
7488
@item
7489
What compiler (and its version) was used to compile @command{ld}---e.g.
7490
``@code{gcc-2.7}''.
7491
 
7492
@item
7493
The command arguments you gave the linker to link your example and
7494
observe the bug.  To guarantee you will not omit something important,
7495
list them all.  A copy of the Makefile (or the output from make) is
7496
sufficient.
7497
 
7498
If we were to try to guess the arguments, we would probably guess wrong
7499
and then we might not encounter the bug.
7500
 
7501
@item
7502
A complete input file, or set of input files, that will reproduce the
7503
bug.  It is generally most helpful to send the actual object files
7504
provided that they are reasonably small.  Say no more than 10K.  For
7505
bigger files you can either make them available by FTP or HTTP or else
7506
state that you are willing to send the object file(s) to whomever
7507
requests them.  (Note - your email will be going to a mailing list, so
7508
we do not want to clog it up with large attachments).  But small
7509
attachments are best.
7510
 
7511
If the source files were assembled using @code{gas} or compiled using
7512
@code{gcc}, then it may be OK to send the source files rather than the
7513
object files.  In this case, be sure to say exactly what version of
7514
@code{gas} or @code{gcc} was used to produce the object files.  Also say
7515
how @code{gas} or @code{gcc} were configured.
7516
 
7517
@item
7518
A description of what behavior you observe that you believe is
7519
incorrect.  For example, ``It gets a fatal signal.''
7520
 
7521
Of course, if the bug is that @command{ld} gets a fatal signal, then we
7522
will certainly notice it.  But if the bug is incorrect output, we might
7523
not notice unless it is glaringly wrong.  You might as well not give us
7524
a chance to make a mistake.
7525
 
7526
Even if the problem you experience is a fatal signal, you should still
7527
say so explicitly.  Suppose something strange is going on, such as, your
7528
copy of @command{ld} is out of sync, or you have encountered a bug in the
7529
C library on your system.  (This has happened!)  Your copy might crash
7530
and ours would not.  If you told us to expect a crash, then when ours
7531
fails to crash, we would know that the bug was not happening for us.  If
7532
you had not told us to expect a crash, then we would not be able to draw
7533
any conclusion from our observations.
7534
 
7535
@item
7536
If you wish to suggest changes to the @command{ld} source, send us context
7537
diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
7538
@samp{-p} option.  Always send diffs from the old file to the new file.
7539
If you even discuss something in the @command{ld} source, refer to it by
7540
context, not by line number.
7541
 
7542
The line numbers in our development sources will not match those in your
7543
sources.  Your line numbers would convey no useful information to us.
7544
@end itemize
7545
 
7546
Here are some things that are not necessary:
7547
 
7548
@itemize @bullet
7549
@item
7550
A description of the envelope of the bug.
7551
 
7552
Often people who encounter a bug spend a lot of time investigating
7553
which changes to the input file will make the bug go away and which
7554
changes will not affect it.
7555
 
7556
This is often time consuming and not very useful, because the way we
7557
will find the bug is by running a single example under the debugger
7558
with breakpoints, not by pure deduction from a series of examples.
7559
We recommend that you save your time for something else.
7560
 
7561
Of course, if you can find a simpler example to report @emph{instead}
7562
of the original one, that is a convenience for us.  Errors in the
7563
output will be easier to spot, running under the debugger will take
7564
less time, and so on.
7565
 
7566
However, simplification is not vital; if you do not want to do this,
7567
report the bug anyway and send us the entire test case you used.
7568
 
7569
@item
7570
A patch for the bug.
7571
 
7572
A patch for the bug does help us if it is a good one.  But do not omit
7573
the necessary information, such as the test case, on the assumption that
7574
a patch is all we need.  We might see problems with your patch and decide
7575
to fix the problem another way, or we might not understand it at all.
7576
 
7577
Sometimes with a program as complicated as @command{ld} it is very hard to
7578
construct an example that will make the program follow a certain path
7579
through the code.  If you do not send us the example, we will not be
7580
able to construct one, so we will not be able to verify that the bug is
7581
fixed.
7582
 
7583
And if we cannot understand what bug you are trying to fix, or why your
7584
patch should be an improvement, we will not install it.  A test case will
7585
help us to understand.
7586
 
7587
@item
7588
A guess about what the bug is or what it depends on.
7589
 
7590
Such guesses are usually wrong.  Even we cannot guess right about such
7591
things without first using the debugger to find the facts.
7592
@end itemize
7593
 
7594
@node MRI
7595
@appendix MRI Compatible Script Files
7596
@cindex MRI compatibility
7597
To aid users making the transition to @sc{gnu} @command{ld} from the MRI
7598
linker, @command{ld} can use MRI compatible linker scripts as an
7599
alternative to the more general-purpose linker scripting language
7600
described in @ref{Scripts}.  MRI compatible linker scripts have a much
7601
simpler command set than the scripting language otherwise used with
7602
@command{ld}.  @sc{gnu} @command{ld} supports the most commonly used MRI
7603
linker commands; these commands are described here.
7604
 
7605
In general, MRI scripts aren't of much use with the @code{a.out} object
7606
file format, since it only has three sections and MRI scripts lack some
7607
features to make use of them.
7608
 
7609
You can specify a file containing an MRI-compatible script using the
7610
@samp{-c} command-line option.
7611
 
7612
Each command in an MRI-compatible script occupies its own line; each
7613
command line starts with the keyword that identifies the command (though
7614
blank lines are also allowed for punctuation).  If a line of an
7615
MRI-compatible script begins with an unrecognized keyword, @command{ld}
7616
issues a warning message, but continues processing the script.
7617
 
7618
Lines beginning with @samp{*} are comments.
7619
 
7620
You can write these commands using all upper-case letters, or all
7621
lower case; for example, @samp{chip} is the same as @samp{CHIP}.
7622
The following list shows only the upper-case form of each command.
7623
 
7624
@table @code
7625
@cindex @code{ABSOLUTE} (MRI)
7626
@item ABSOLUTE @var{secname}
7627
@itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
7628
Normally, @command{ld} includes in the output file all sections from all
7629
the input files.  However, in an MRI-compatible script, you can use the
7630
@code{ABSOLUTE} command to restrict the sections that will be present in
7631
your output program.  If the @code{ABSOLUTE} command is used at all in a
7632
script, then only the sections named explicitly in @code{ABSOLUTE}
7633
commands will appear in the linker output.  You can still use other
7634
input sections (whatever you select on the command line, or using
7635
@code{LOAD}) to resolve addresses in the output file.
7636
 
7637
@cindex @code{ALIAS} (MRI)
7638
@item ALIAS @var{out-secname}, @var{in-secname}
7639
Use this command to place the data from input section @var{in-secname}
7640
in a section called @var{out-secname} in the linker output file.
7641
 
7642
@var{in-secname} may be an integer.
7643
 
7644
@cindex @code{ALIGN} (MRI)
7645
@item ALIGN @var{secname} = @var{expression}
7646
Align the section called @var{secname} to @var{expression}.  The
7647
@var{expression} should be a power of two.
7648
 
7649
@cindex @code{BASE} (MRI)
7650
@item BASE @var{expression}
7651
Use the value of @var{expression} as the lowest address (other than
7652
absolute addresses) in the output file.
7653
 
7654
@cindex @code{CHIP} (MRI)
7655
@item CHIP @var{expression}
7656
@itemx CHIP @var{expression}, @var{expression}
7657
This command does nothing; it is accepted only for compatibility.
7658
 
7659
@cindex @code{END} (MRI)
7660
@item END
7661
This command does nothing whatever; it's only accepted for compatibility.
7662
 
7663
@cindex @code{FORMAT} (MRI)
7664
@item FORMAT @var{output-format}
7665
Similar to the @code{OUTPUT_FORMAT} command in the more general linker
7666
language, but restricted to one of these output formats:
7667
 
7668
@enumerate
7669
@item
7670
S-records, if @var{output-format} is @samp{S}
7671
 
7672
@item
7673
IEEE, if @var{output-format} is @samp{IEEE}
7674
 
7675
@item
7676
COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
7677
@samp{COFF}
7678
@end enumerate
7679
 
7680
@cindex @code{LIST} (MRI)
7681
@item LIST @var{anything}@dots{}
7682
Print (to the standard output file) a link map, as produced by the
7683
@command{ld} command-line option @samp{-M}.
7684
 
7685
The keyword @code{LIST} may be followed by anything on the
7686
same line, with no change in its effect.
7687
 
7688
@cindex @code{LOAD} (MRI)
7689
@item LOAD @var{filename}
7690
@itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
7691
Include one or more object file @var{filename} in the link; this has the
7692
same effect as specifying @var{filename} directly on the @command{ld}
7693
command line.
7694
 
7695
@cindex @code{NAME} (MRI)
7696
@item NAME @var{output-name}
7697
@var{output-name} is the name for the program produced by @command{ld}; the
7698
MRI-compatible command @code{NAME} is equivalent to the command-line
7699
option @samp{-o} or the general script language command @code{OUTPUT}.
7700
 
7701
@cindex @code{ORDER} (MRI)
7702
@item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
7703
@itemx ORDER @var{secname} @var{secname} @var{secname}
7704
Normally, @command{ld} orders the sections in its output file in the
7705
order in which they first appear in the input files.  In an MRI-compatible
7706
script, you can override this ordering with the @code{ORDER} command.  The
7707
sections you list with @code{ORDER} will appear first in your output
7708
file, in the order specified.
7709
 
7710
@cindex @code{PUBLIC} (MRI)
7711
@item PUBLIC @var{name}=@var{expression}
7712
@itemx PUBLIC @var{name},@var{expression}
7713
@itemx PUBLIC @var{name} @var{expression}
7714
Supply a value (@var{expression}) for external symbol
7715
@var{name} used in the linker input files.
7716
 
7717
@cindex @code{SECT} (MRI)
7718
@item SECT @var{secname}, @var{expression}
7719
@itemx SECT @var{secname}=@var{expression}
7720
@itemx SECT @var{secname} @var{expression}
7721
You can use any of these three forms of the @code{SECT} command to
7722
specify the start address (@var{expression}) for section @var{secname}.
7723
If you have more than one @code{SECT} statement for the same
7724
@var{secname}, only the @emph{first} sets the start address.
7725
@end table
7726
 
7727
@node GNU Free Documentation License
7728
@appendix GNU Free Documentation License
7729
@include fdl.texi
7730
 
7731
@node LD Index
7732
@unnumbered LD Index
7733
 
7734
@printindex cp
7735
 
7736
@tex
7737
% I think something like @colophon should be in texinfo.  In the
7738
% meantime:
7739
\long\def\colophon{\hbox to0pt{}\vfill
7740
\centerline{The body of this manual is set in}
7741
\centerline{\fontname\tenrm,}
7742
\centerline{with headings in {\bf\fontname\tenbf}}
7743
\centerline{and examples in {\tt\fontname\tentt}.}
7744
\centerline{{\it\fontname\tenit\/} and}
7745
\centerline{{\sl\fontname\tensl\/}}
7746
\centerline{are used for emphasis.}\vfill}
7747
\page\colophon
7748
% Blame: doc@cygnus.com, 28mar91.
7749
@end tex
7750
 
7751
@bye

powered by: WebSVN 2.1.0

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