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