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