* bfd.c (bfd_preserve_save): Don't zero BFD_IN_MEMORY.
[binutils.git] / ld / ld.texinfo
blob03702dc6c7b9346b6788f8ca90ea73900d63bdaa
1 \input texinfo
2 @setfilename ld.info
3 @c Copyright 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000,
4 @c 2001, 2002 Free Software Foundation, Inc.
5 @syncodeindex ky cp
6 @include configdoc.texi
7 @c (configdoc.texi is generated by the Makefile)
8 @include ldver.texi
10 @c @smallbook
12 @macro gcctabopt{body}
13 @code{\body\}
14 @end macro
16 @c man begin NAME
17 @ifset man
18 @c Configure for the generation of man pages
19 @set UsesEnvVars
20 @set GENERIC
21 @set A29K
22 @set ARC
23 @set ARM
24 @set D10V
25 @set D30V
26 @set H8/300
27 @set H8/500
28 @set HPPA
29 @set I370
30 @set I80386
31 @set I860
32 @set I960
33 @set M32R
34 @set M68HC11
35 @set M680X0
36 @set MCORE
37 @set MIPS
38 @set MMIX
39 @set PDP11
40 @set PJ
41 @set SH
42 @set SPARC
43 @set C54X
44 @set V850
45 @set VAX
46 @end ifset
47 @c man end
49 @ifinfo
50 @format
51 START-INFO-DIR-ENTRY
52 * Ld: (ld).                       The GNU linker.
53 END-INFO-DIR-ENTRY
54 @end format
55 @end ifinfo
57 @ifinfo
58 This file documents the @sc{gnu} linker LD version @value{VERSION}.
60 Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000,
61 2001, 2002 Free Software Foundation, Inc.
63 @ignore
65 Permission is granted to copy, distribute and/or modify this document
66 under the terms of the GNU Free Documentation License, Version 1.1
67 or any later version published by the Free Software Foundation;
68 with no Invariant Sections, with no Front-Cover Texts, and with no
69 Back-Cover Texts.  A copy of the license is included in the
70 section entitled "GNU Free Documentation License".
72 Permission is granted to process this file through Tex and print the
73 results, provided the printed document carries copying permission
74 notice identical to this one except for the removal of this paragraph
75 (this paragraph not being relevant to the printed manual).
77 @end ignore
78 @end ifinfo
79 @iftex
80 @finalout
81 @setchapternewpage odd
82 @settitle Using LD, the GNU linker
83 @titlepage
84 @title Using ld
85 @subtitle The GNU linker
86 @sp 1
87 @subtitle @code{ld} version 2
88 @subtitle Version @value{VERSION}
89 @author Steve Chamberlain
90 @author Ian Lance Taylor
91 @page
93 @tex
94 {\parskip=0pt
95 \hfill Red Hat Inc\par
96 \hfill nickc\@credhat.com, doc\@redhat.com\par
97 \hfill {\it Using LD, the GNU linker}\par
98 \hfill Edited by Jeffrey Osier (jeffrey\@cygnus.com)\par
100 \global\parindent=0pt % Steve likes it this way.
101 @end tex
103 @vskip 0pt plus 1filll
104 @c man begin COPYRIGHT
105 Copyright @copyright{} 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000, 2001 Free Software Foundation, Inc.
107 Permission is granted to copy, distribute and/or modify this document
108 under the terms of the GNU Free Documentation License, Version 1.1
109 or any later version published by the Free Software Foundation;
110 with no Invariant Sections, with no Front-Cover Texts, and with no
111 Back-Cover Texts.  A copy of the license is included in the
112 section entitled "GNU Free Documentation License".
113 @c man end
115 @end titlepage
116 @end iftex
117 @c FIXME: Talk about importance of *order* of args, cmds to linker!
119 @ifnottex
120 @node Top
121 @top Using ld
122 This file documents the @sc{gnu} linker ld version @value{VERSION}.
124 This document is distributed under the terms of the GNU Free
125 Documentation License.  A copy of the license is included in the
126 section entitled "GNU Free Documentation License".
128 @menu
129 * Overview::                    Overview
130 * Invocation::                  Invocation
131 * Scripts::                     Linker Scripts
132 @ifset GENERIC
133 * Machine Dependent::           Machine Dependent Features
134 @end ifset
135 @ifclear GENERIC
136 @ifset H8300
137 * H8/300::                      ld and the H8/300
138 @end ifset
139 @ifset Hitachi
140 * Hitachi::                     ld and other Hitachi micros
141 @end ifset
142 @ifset I960
143 * i960::                        ld and the Intel 960 family
144 @end ifset
145 @ifset TICOFF
146 * TI COFF::                     ld and the TI COFF
147 @end ifset
148 @end ifclear
149 @ifclear SingleFormat
150 * BFD::                         BFD
151 @end ifclear
152 @c Following blank line required for remaining bug in makeinfo conds/menus
154 * Reporting Bugs::              Reporting Bugs
155 * MRI::                         MRI Compatible Script Files
156 * GNU Free Documentation License::  GNU Free Documentation License
157 * Index::                       Index
158 @end menu
159 @end ifnottex
161 @node Overview
162 @chapter Overview
164 @cindex @sc{gnu} linker
165 @cindex what is this?
167 @ifset man
168 @c man begin SYNOPSIS
169 ld [@b{options}] @var{objfile} @dots{}
170 @c man end
172 @c man begin SEEALSO
173 ar(1), nm(1), objcopy(1), objdump(1), readelf(1) and
174 the Info entries for @file{binutils} and
175 @file{ld}.
176 @c man end
177 @end ifset
179 @c man begin DESCRIPTION
181 @command{ld} combines a number of object and archive files, relocates
182 their data and ties up symbol references. Usually the last step in
183 compiling a program is to run @command{ld}.
185 @command{ld} accepts Linker Command Language files written in
186 a superset of AT&T's Link Editor Command Language syntax,
187 to provide explicit and total control over the linking process.
189 @ifset man
190 @c For the man only
191 This man page does not describe the command language; see the 
192 @command{ld} entry in @code{info}, or the manual
193 ld: the GNU linker, for full details on the command language and 
194 on other aspects of the GNU linker. 
195 @end ifset
197 @ifclear SingleFormat
198 This version of @command{ld} uses the general purpose BFD libraries
199 to operate on object files. This allows @command{ld} to read, combine, and
200 write object files in many different formats---for example, COFF or
201 @code{a.out}.  Different formats may be linked together to produce any
202 available kind of object file.  @xref{BFD}, for more information.
203 @end ifclear
205 Aside from its flexibility, the @sc{gnu} linker is more helpful than other
206 linkers in providing diagnostic information.  Many linkers abandon
207 execution immediately upon encountering an error; whenever possible,
208 @command{ld} continues executing, allowing you to identify other errors
209 (or, in some cases, to get an output file in spite of the error).
211 @c man end
213 @node Invocation
214 @chapter Invocation
216 @c man begin DESCRIPTION
218 The @sc{gnu} linker @command{ld} is meant to cover a broad range of situations,
219 and to be as compatible as possible with other linkers.  As a result,
220 you have many choices to control its behavior.
222 @c man end
224 @ifset UsesEnvVars
225 @menu
226 * Options::                     Command Line Options
227 * Environment::                 Environment Variables
228 @end menu
230 @node Options
231 @section Command Line Options
232 @end ifset
234 @cindex command line
235 @cindex options
237 @c man begin OPTIONS
239 The linker supports a plethora of command-line options, but in actual
240 practice few of them are used in any particular context.
241 @cindex standard Unix system
242 For instance, a frequent use of @command{ld} is to link standard Unix
243 object files on a standard, supported Unix system.  On such a system, to
244 link a file @code{hello.o}:
246 @smallexample
247 ld -o @var{output} /lib/crt0.o hello.o -lc
248 @end smallexample
250 This tells @command{ld} to produce a file called @var{output} as the
251 result of linking the file @code{/lib/crt0.o} with @code{hello.o} and
252 the library @code{libc.a}, which will come from the standard search
253 directories.  (See the discussion of the @samp{-l} option below.)
255 Some of the command-line options to @command{ld} may be specified at any
256 point in the command line.  However, options which refer to files, such
257 as @samp{-l} or @samp{-T}, cause the file to be read at the point at
258 which the option appears in the command line, relative to the object
259 files and other file options.  Repeating non-file options with a
260 different argument will either have no further effect, or override prior
261 occurrences (those further to the left on the command line) of that
262 option.  Options which may be meaningfully specified more than once are
263 noted in the descriptions below.
265 @cindex object files
266 Non-option arguments are object files or archives which are to be linked
267 together.  They may follow, precede, or be mixed in with command-line
268 options, except that an object file argument may not be placed between
269 an option and its argument.
271 Usually the linker is invoked with at least one object file, but you can
272 specify other forms of binary input files using @samp{-l}, @samp{-R},
273 and the script command language.  If @emph{no} binary input files at all
274 are specified, the linker does not produce any output, and issues the
275 message @samp{No input files}.
277 If the linker can not recognize the format of an object file, it will
278 assume that it is a linker script.  A script specified in this way
279 augments the main linker script used for the link (either the default
280 linker script or the one specified by using @samp{-T}).  This feature
281 permits the linker to link against a file which appears to be an object
282 or an archive, but actually merely defines some symbol values, or uses
283 @code{INPUT} or @code{GROUP} to load other objects.  Note that
284 specifying a script in this way merely augments the main linker script;
285 use the @samp{-T} option to replace the default linker script entirely.
286 @xref{Scripts}.
288 For options whose names are a single letter,
289 option arguments must either follow the option letter without intervening
290 whitespace, or be given as separate arguments immediately following the
291 option that requires them.
293 For options whose names are multiple letters, either one dash or two can
294 precede the option name; for example, @samp{-trace-symbol} and
295 @samp{--trace-symbol} are equivalent.  Note - there is one exception to
296 this rule.  Multiple letter options that start with a lower case 'o' can
297 only be preceeded by two dashes.  This is to reduce confusion with the
298 @samp{-o} option.  So for example @samp{-omagic} sets the output file
299 name to @samp{magic} whereas @samp{--omagic} sets the NMAGIC flag on the
300 output.
302 Arguments to multiple-letter options must either be separated from the
303 option name by an equals sign, or be given as separate arguments
304 immediately following the option that requires them.  For example,
305 @samp{--trace-symbol foo} and @samp{--trace-symbol=foo} are equivalent.
306 Unique abbreviations of the names of multiple-letter options are
307 accepted.
309 Note - if the linker is being invoked indirectly, via a compiler driver
310 (eg @samp{gcc}) then all the linker command line options should be
311 prefixed by @samp{-Wl,} (or whatever is appropriate for the particular
312 compiler driver) like this:
314 @smallexample
315   gcc -Wl,--startgroup foo.o bar.o -Wl,--endgroup
316 @end smallexample
318 This is important, because otherwise the compiler driver program may
319 silently drop the linker options, resulting in a bad link.
321 Here is a table of the generic command line switches accepted by the GNU
322 linker:
324 @table @gcctabopt
325 @kindex -a@var{keyword}
326 @item -a@var{keyword}
327 This option is supported for HP/UX compatibility.  The @var{keyword}
328 argument must be one of the strings @samp{archive}, @samp{shared}, or
329 @samp{default}.  @samp{-aarchive} is functionally equivalent to
330 @samp{-Bstatic}, and the other two keywords are functionally equivalent
331 to @samp{-Bdynamic}.  This option may be used any number of times.
333 @ifset I960
334 @cindex architectures
335 @kindex -A@var{arch}
336 @item -A@var{architecture}
337 @kindex --architecture=@var{arch}
338 @itemx --architecture=@var{architecture}
339 In the current release of @command{ld}, this option is useful only for the
340 Intel 960 family of architectures.  In that @command{ld} configuration, the
341 @var{architecture} argument identifies the particular architecture in
342 the 960 family, enabling some safeguards and modifying the
343 archive-library search path.  @xref{i960,,@command{ld} and the Intel 960
344 family}, for details.
346 Future releases of @command{ld} may support similar functionality for
347 other architecture families.
348 @end ifset
350 @ifclear SingleFormat
351 @cindex binary input format
352 @kindex -b @var{format}
353 @kindex --format=@var{format}
354 @cindex input format
355 @cindex input format
356 @item -b @var{input-format}
357 @itemx --format=@var{input-format}
358 @command{ld} may be configured to support more than one kind of object
359 file.  If your @command{ld} is configured this way, you can use the
360 @samp{-b} option to specify the binary format for input object files
361 that follow this option on the command line.  Even when @command{ld} is
362 configured to support alternative object formats, you don't usually need
363 to specify this, as @command{ld} should be configured to expect as a
364 default input format the most usual format on each machine.
365 @var{input-format} is a text string, the name of a particular format
366 supported by the BFD libraries.  (You can list the available binary
367 formats with @samp{objdump -i}.)
368 @xref{BFD}.
370 You may want to use this option if you are linking files with an unusual
371 binary format.  You can also use @samp{-b} to switch formats explicitly (when
372 linking object files of different formats), by including
373 @samp{-b @var{input-format}} before each group of object files in a
374 particular format.
376 The default format is taken from the environment variable
377 @code{GNUTARGET}.
378 @ifset UsesEnvVars
379 @xref{Environment}.
380 @end ifset
381 You can also define the input format from a script, using the command
382 @code{TARGET};
383 @ifclear man
384 see @ref{Format Commands}.
385 @end ifclear
386 @end ifclear
388 @kindex -c @var{MRI-cmdfile}
389 @kindex --mri-script=@var{MRI-cmdfile}
390 @cindex compatibility, MRI
391 @item -c @var{MRI-commandfile}
392 @itemx --mri-script=@var{MRI-commandfile}
393 For compatibility with linkers produced by MRI, @command{ld} accepts script
394 files written in an alternate, restricted command language, described in
395 @ifclear man
396 @ref{MRI,,MRI Compatible Script Files}.
397 @end ifclear
398 @ifset man
399 the MRI Compatible Script Files section of GNU ld documentation.
400 @end ifset
401 Introduce MRI script files with
402 the option @samp{-c}; use the @samp{-T} option to run linker
403 scripts written in the general-purpose @command{ld} scripting language.
404 If @var{MRI-cmdfile} does not exist, @command{ld} looks for it in the directories
405 specified by any @samp{-L} options.
407 @cindex common allocation
408 @kindex -d
409 @kindex -dc
410 @kindex -dp
411 @item -d
412 @itemx -dc
413 @itemx -dp
414 These three options are equivalent; multiple forms are supported for
415 compatibility with other linkers.  They assign space to common symbols
416 even if a relocatable output file is specified (with @samp{-r}).  The
417 script command @code{FORCE_COMMON_ALLOCATION} has the same effect.
418 @xref{Miscellaneous Commands}.
420 @cindex entry point, from command line
421 @kindex -e @var{entry}
422 @kindex --entry=@var{entry}
423 @item -e @var{entry}
424 @itemx --entry=@var{entry}
425 Use @var{entry} as the explicit symbol for beginning execution of your
426 program, rather than the default entry point.  If there is no symbol
427 named @var{entry}, the linker will try to parse @var{entry} as a number,
428 and use that as the entry address (the number will be interpreted in
429 base 10; you may use a leading @samp{0x} for base 16, or a leading
430 @samp{0} for base 8).  @xref{Entry Point}, for a discussion of defaults
431 and other ways of specifying the entry point.
433 @cindex dynamic symbol table
434 @kindex -E
435 @kindex --export-dynamic
436 @item -E
437 @itemx --export-dynamic
438 When creating a dynamically linked executable, add all symbols to the
439 dynamic symbol table.  The dynamic symbol table is the set of symbols
440 which are visible from dynamic objects at run time.
442 If you do not use this option, the dynamic symbol table will normally
443 contain only those symbols which are referenced by some dynamic object
444 mentioned in the link.
446 If you use @code{dlopen} to load a dynamic object which needs to refer
447 back to the symbols defined by the program, rather than some other
448 dynamic object, then you will probably need to use this option when
449 linking the program itself.
451 You can also use the version script to control what symbols should
452 be added to the dynamic symbol table if the output format supports it.
453 See the description of @samp{--version-script} in @ref{VERSION}.
455 @cindex big-endian objects
456 @cindex endianness
457 @kindex -EB
458 @item -EB
459 Link big-endian objects.  This affects the default output format.
461 @cindex little-endian objects
462 @kindex -EL
463 @item -EL
464 Link little-endian objects.  This affects the default output format.
466 @kindex -f
467 @kindex --auxiliary
468 @item -f
469 @itemx --auxiliary @var{name}
470 When creating an ELF shared object, set the internal DT_AUXILIARY field
471 to the specified name.  This tells the dynamic linker that the symbol
472 table of the shared object should be used as an auxiliary filter on the
473 symbol table of the shared object @var{name}.
475 If you later link a program against this filter object, then, when you
476 run the program, the dynamic linker will see the DT_AUXILIARY field.  If
477 the dynamic linker resolves any symbols from the filter object, it will
478 first check whether there is a definition in the shared object
479 @var{name}.  If there is one, it will be used instead of the definition
480 in the filter object.  The shared object @var{name} need not exist.
481 Thus the shared object @var{name} may be used to provide an alternative
482 implementation of certain functions, perhaps for debugging or for
483 machine specific performance.
485 This option may be specified more than once.  The DT_AUXILIARY entries
486 will be created in the order in which they appear on the command line.
488 @kindex -F
489 @kindex --filter
490 @item -F @var{name}
491 @itemx --filter @var{name}
492 When creating an ELF shared object, set the internal DT_FILTER field to
493 the specified name.  This tells the dynamic linker that the symbol table
494 of the shared object which is being created should be used as a filter
495 on the symbol table of the shared object @var{name}.
497 If you later link a program against this filter object, then, when you
498 run the program, the dynamic linker will see the DT_FILTER field.  The
499 dynamic linker will resolve symbols according to the symbol table of the
500 filter object as usual, but it will actually link to the definitions
501 found in the shared object @var{name}.  Thus the filter object can be
502 used to select a subset of the symbols provided by the object
503 @var{name}.
505 Some older linkers used the @option{-F} option throughout a compilation
506 toolchain for specifying object-file format for both input and output
507 object files.  The @sc{gnu} linker uses other mechanisms for this
508 purpose: the @option{-b}, @option{--format}, @option{--oformat} options, the
509 @code{TARGET} command in linker scripts, and the @code{GNUTARGET}
510 environment variable.  The @sc{gnu} linker will ignore the @option{-F}
511 option when not creating an ELF shared object.
513 @cindex finalization function
514 @kindex -fini
515 @item -fini @var{name}
516 When creating an ELF executable or shared object, call NAME when the
517 executable or shared object is unloaded, by setting DT_FINI to the
518 address of the function.  By default, the linker uses @code{_fini} as
519 the function to call.
521 @kindex -g
522 @item -g
523 Ignored.  Provided for compatibility with other tools.
525 @kindex -G
526 @kindex --gpsize
527 @cindex object size
528 @item -G@var{value}
529 @itemx --gpsize=@var{value}
530 Set the maximum size of objects to be optimized using the GP register to
531 @var{size}.  This is only meaningful for object file formats such as
532 MIPS ECOFF which supports putting large and small objects into different
533 sections.  This is ignored for other object file formats.
535 @cindex runtime library name
536 @kindex -h@var{name}
537 @kindex -soname=@var{name}
538 @item -h@var{name}
539 @itemx -soname=@var{name}
540 When creating an ELF shared object, set the internal DT_SONAME field to
541 the specified name.  When an executable is linked with a shared object
542 which has a DT_SONAME field, then when the executable is run the dynamic
543 linker will attempt to load the shared object specified by the DT_SONAME
544 field rather than the using the file name given to the linker.
546 @kindex -i
547 @cindex incremental link
548 @item -i
549 Perform an incremental link (same as option @samp{-r}).
551 @cindex initialization function
552 @kindex -init
553 @item -init @var{name}
554 When creating an ELF executable or shared object, call NAME when the
555 executable or shared object is loaded, by setting DT_INIT to the address
556 of the function.  By default, the linker uses @code{_init} as the
557 function to call.
559 @cindex archive files, from cmd line
560 @kindex -l@var{archive}
561 @kindex --library=@var{archive}
562 @item -l@var{archive}
563 @itemx --library=@var{archive}
564 Add archive file @var{archive} to the list of files to link.  This
565 option may be used any number of times.  @command{ld} will search its
566 path-list for occurrences of @code{lib@var{archive}.a} for every
567 @var{archive} specified.
569 On systems which support shared libraries, @command{ld} may also search for
570 libraries with extensions other than @code{.a}.  Specifically, on ELF
571 and SunOS systems, @command{ld} will search a directory for a library with
572 an extension of @code{.so} before searching for one with an extension of
573 @code{.a}.  By convention, a @code{.so} extension indicates a shared
574 library.
576 The linker will search an archive only once, at the location where it is
577 specified on the command line.  If the archive defines a symbol which
578 was undefined in some object which appeared before the archive on the
579 command line, the linker will include the appropriate file(s) from the
580 archive.  However, an undefined symbol in an object appearing later on
581 the command line will not cause the linker to search the archive again.
583 See the @option{-(} option for a way to force the linker to search
584 archives multiple times.
586 You may list the same archive multiple times on the command line.
588 @ifset GENERIC
589 This type of archive searching is standard for Unix linkers.  However,
590 if you are using @command{ld} on AIX, note that it is different from the
591 behaviour of the AIX linker.
592 @end ifset
594 @cindex search directory, from cmd line
595 @kindex -L@var{dir}
596 @kindex --library-path=@var{dir}
597 @item -L@var{searchdir}
598 @itemx --library-path=@var{searchdir}
599 Add path @var{searchdir} to the list of paths that @command{ld} will search
600 for archive libraries and @command{ld} control scripts.  You may use this
601 option any number of times.  The directories are searched in the order
602 in which they are specified on the command line.  Directories specified
603 on the command line are searched before the default directories.  All
604 @option{-L} options apply to all @option{-l} options, regardless of the
605 order in which the options appear.
607 @ifset UsesEnvVars
608 The default set of paths searched (without being specified with
609 @samp{-L}) depends on which emulation mode @command{ld} is using, and in
610 some cases also on how it was configured.  @xref{Environment}.
611 @end ifset
613 The paths can also be specified in a link script with the
614 @code{SEARCH_DIR} command.  Directories specified this way are searched
615 at the point in which the linker script appears in the command line.
617 @cindex emulation
618 @kindex -m @var{emulation}
619 @item -m@var{emulation}
620 Emulate the @var{emulation} linker.  You can list the available
621 emulations with the @samp{--verbose} or @samp{-V} options.
623 If the @samp{-m} option is not used, the emulation is taken from the
624 @code{LDEMULATION} environment variable, if that is defined.
626 Otherwise, the default emulation depends upon how the linker was
627 configured.
629 @cindex link map
630 @kindex -M
631 @kindex --print-map
632 @item -M
633 @itemx --print-map
634 Print a link map to the standard output.  A link map provides
635 information about the link, including the following:
637 @itemize @bullet
638 @item
639 Where object files and symbols are mapped into memory.
640 @item
641 How common symbols are allocated.
642 @item
643 All archive members included in the link, with a mention of the symbol
644 which caused the archive member to be brought in.
645 @end itemize
647 @kindex -n
648 @cindex read-only text
649 @cindex NMAGIC
650 @kindex --nmagic
651 @item -n
652 @itemx --nmagic
653 Turn off page alignment of sections, and mark the output as
654 @code{NMAGIC} if possible.
656 @kindex -N
657 @kindex --omagic
658 @cindex read/write from cmd line
659 @cindex OMAGIC
660 @item -N
661 @itemx --omagic
662 Set the text and data sections to be readable and writable.  Also, do
663 not page-align the data segment, and disable linking against shared
664 libraries.  If the output format supports Unix style magic numbers,
665 mark the output as @code{OMAGIC}.
667 @kindex --no-omagic
668 @cindex OMAGIC
669 @item --no-omagic
670 This option negates most of the effects of the @option{-N} option.  It
671 sets the text section to be read-only, and forces the data segment to
672 be page-aligned.  Note - this option does not enable linking against
673 shared libraries.  Use @option{-Bdynamic} for this.
675 @kindex -o @var{output}
676 @kindex --output=@var{output}
677 @cindex naming the output file
678 @item -o @var{output}
679 @itemx --output=@var{output}
680 Use @var{output} as the name for the program produced by @command{ld}; if this
681 option is not specified, the name @file{a.out} is used by default.  The
682 script command @code{OUTPUT} can also specify the output file name.
684 @kindex -O @var{level}
685 @cindex generating optimized output
686 @item -O @var{level}
687 If @var{level} is a numeric values greater than zero @command{ld} optimizes
688 the output.  This might take significantly longer and therefore probably
689 should only be enabled for the final binary.
691 @kindex -q
692 @kindex --emit-relocs
693 @cindex retain relocations in final executable
694 @item -q
695 @itemx --emit-relocs
696 Leave relocation sections and contents in fully linked exececutables.
697 Post link analysis and optimization tools may need this information in
698 order to perform correct modifications of executables.  This results
699 in larger executables.
701 This option is currently only supported on ELF platforms.
703 @cindex partial link
704 @cindex relocatable output
705 @kindex -r
706 @kindex --relocateable
707 @item -r
708 @itemx --relocateable
709 Generate relocatable output---i.e., generate an output file that can in
710 turn serve as input to @command{ld}.  This is often called @dfn{partial
711 linking}.  As a side effect, in environments that support standard Unix
712 magic numbers, this option also sets the output file's magic number to
713 @code{OMAGIC}.
714 @c ; see @option{-N}.
715 If this option is not specified, an absolute file is produced.  When
716 linking C++ programs, this option @emph{will not} resolve references to
717 constructors; to do that, use @samp{-Ur}.
719 When an input file does not have the same format as the output file,
720 partial linking is only supported if that input file does not contain any
721 relocations.  Different output formats can have further restrictions; for
722 example some @code{a.out}-based formats do not support partial linking
723 with input files in other formats at all.
725 This option does the same thing as @samp{-i}.
727 @kindex -R @var{file}
728 @kindex --just-symbols=@var{file}
729 @cindex symbol-only input
730 @item -R @var{filename}
731 @itemx --just-symbols=@var{filename}
732 Read symbol names and their addresses from @var{filename}, but do not
733 relocate it or include it in the output.  This allows your output file
734 to refer symbolically to absolute locations of memory defined in other
735 programs.  You may use this option more than once.
737 For compatibility with other ELF linkers, if the @option{-R} option is
738 followed by a directory name, rather than a file name, it is treated as
739 the @option{-rpath} option.
741 @kindex -s
742 @kindex --strip-all
743 @cindex strip all symbols
744 @item -s
745 @itemx --strip-all
746 Omit all symbol information from the output file.
748 @kindex -S
749 @kindex --strip-debug
750 @cindex strip debugger symbols
751 @item -S
752 @itemx --strip-debug
753 Omit debugger symbol information (but not all symbols) from the output file.
755 @kindex -t
756 @kindex --trace
757 @cindex input files, displaying
758 @item -t
759 @itemx --trace
760 Print the names of the input files as @command{ld} processes them.
762 @kindex -T @var{script}
763 @kindex --script=@var{script}
764 @cindex script files
765 @item -T @var{scriptfile}
766 @itemx --script=@var{scriptfile}
767 Use @var{scriptfile} as the linker script.  This script replaces
768 @command{ld}'s default linker script (rather than adding to it), so
769 @var{commandfile} must specify everything necessary to describe the
770 output file.  @xref{Scripts}.  If @var{scriptfile} does not exist in
771 the current directory, @code{ld} looks for it in the directories
772 specified by any preceding @samp{-L} options.  Multiple @samp{-T}
773 options accumulate.
775 @kindex -u @var{symbol}
776 @kindex --undefined=@var{symbol}
777 @cindex undefined symbol
778 @item -u @var{symbol}
779 @itemx --undefined=@var{symbol}
780 Force @var{symbol} to be entered in the output file as an undefined
781 symbol.  Doing this may, for example, trigger linking of additional
782 modules from standard libraries.  @samp{-u} may be repeated with
783 different option arguments to enter additional undefined symbols.  This
784 option is equivalent to the @code{EXTERN} linker script command.
786 @kindex -Ur
787 @cindex constructors
788 @item -Ur
789 For anything other than C++ programs, this option is equivalent to
790 @samp{-r}: it generates relocatable output---i.e., an output file that can in
791 turn serve as input to @command{ld}.  When linking C++ programs, @samp{-Ur}
792 @emph{does} resolve references to constructors, unlike @samp{-r}.
793 It does not work to use @samp{-Ur} on files that were themselves linked
794 with @samp{-Ur}; once the constructor table has been built, it cannot
795 be added to.  Use @samp{-Ur} only for the last partial link, and
796 @samp{-r} for the others.
798 @kindex --unique[=@var{SECTION}]
799 @item --unique[=@var{SECTION}]
800 Creates a separate output section for every input section matching
801 @var{SECTION}, or if the optional wildcard @var{SECTION} argument is
802 missing, for every orphan input section.  An orphan section is one not
803 specifically mentioned in a linker script.  You may use this option
804 multiple times on the command line;  It prevents the normal merging of
805 input sections with the same name, overriding output section assignments
806 in a linker script.
808 @kindex -v
809 @kindex -V
810 @kindex --version
811 @cindex version
812 @item -v
813 @itemx --version
814 @itemx -V
815 Display the version number for @command{ld}.  The @option{-V} option also
816 lists the supported emulations.
818 @kindex -x
819 @kindex --discard-all
820 @cindex deleting local symbols
821 @item -x
822 @itemx --discard-all
823 Delete all local symbols.
825 @kindex -X
826 @kindex --discard-locals
827 @cindex local symbols, deleting
828 @cindex L, deleting symbols beginning
829 @item -X
830 @itemx --discard-locals
831 Delete all temporary local symbols.  For most targets, this is all local
832 symbols whose names begin with @samp{L}.
834 @kindex -y @var{symbol}
835 @kindex --trace-symbol=@var{symbol}
836 @cindex symbol tracing
837 @item -y @var{symbol}
838 @itemx --trace-symbol=@var{symbol}
839 Print the name of each linked file in which @var{symbol} appears.  This
840 option may be given any number of times.  On many systems it is necessary
841 to prepend an underscore.
843 This option is useful when you have an undefined symbol in your link but
844 don't know where the reference is coming from.
846 @kindex -Y @var{path}
847 @item -Y @var{path}
848 Add @var{path} to the default library search path.  This option exists
849 for Solaris compatibility.
851 @kindex -z @var{keyword}
852 @item -z @var{keyword}
853 The recognized keywords are @code{initfirst}, @code{interpose},
854 @code{loadfltr}, @code{nodefaultlib}, @code{nodelete}, @code{nodlopen},
855 @code{nodump}, @code{now}, @code{origin}, @code{combreloc}, @code{nocombreloc} 
856 and @code{nocopyreloc}.
857 The other keywords are
858 ignored for Solaris compatibility. @code{initfirst} marks the object
859 to be initialized first at runtime before any other objects.
860 @code{interpose} marks the object that its symbol table interposes
861 before all symbols but the primary executable. @code{loadfltr} marks
862 the object that its filtees be processed immediately at runtime.
863 @code{nodefaultlib} marks the object that the search for dependencies
864 of this object will ignore any default library search paths.
865 @code{nodelete} marks the object shouldn't be unloaded at runtime.
866 @code{nodlopen} marks the object not available to @code{dlopen}.
867 @code{nodump} marks the object can not be dumped by @code{dldump}.
868 @code{now} marks the object with the non-lazy runtime binding.
869 @code{origin} marks the object may contain $ORIGIN.
870 @code{defs} disallows undefined symbols.
871 @code{muldefs} allows multiple definitions.
872 @code{combreloc} combines multiple reloc sections and sorts them
873 to make dynamic symbol lookup caching possible.
874 @code{nocombreloc} disables multiple reloc sections combining.
875 @code{nocopyreloc} disables production of copy relocs.
877 @kindex -(
878 @cindex groups of archives
879 @item -( @var{archives} -)
880 @itemx --start-group @var{archives} --end-group
881 The @var{archives} should be a list of archive files.  They may be
882 either explicit file names, or @samp{-l} options.
884 The specified archives are searched repeatedly until no new undefined
885 references are created.  Normally, an archive is searched only once in
886 the order that it is specified on the command line.  If a symbol in that
887 archive is needed to resolve an undefined symbol referred to by an
888 object in an archive that appears later on the command line, the linker
889 would not be able to resolve that reference.  By grouping the archives,
890 they all be searched repeatedly until all possible references are
891 resolved.
893 Using this option has a significant performance cost.  It is best to use
894 it only when there are unavoidable circular references between two or
895 more archives.
897 @kindex -assert @var{keyword}
898 @item -assert @var{keyword}
899 This option is ignored for SunOS compatibility.
901 @kindex -Bdynamic
902 @kindex -dy
903 @kindex -call_shared
904 @item -Bdynamic
905 @itemx -dy
906 @itemx -call_shared
907 Link against dynamic libraries.  This is only meaningful on platforms
908 for which shared libraries are supported.  This option is normally the
909 default on such platforms.  The different variants of this option are
910 for compatibility with various systems.  You may use this option
911 multiple times on the command line: it affects library searching for
912 @option{-l} options which follow it.
914 @kindex -Bgroup
915 @item -Bgroup
916 Set the @code{DF_1_GROUP} flag in the @code{DT_FLAGS_1} entry in the dynamic
917 section.  This causes the runtime linker to handle lookups in this
918 object and its dependencies to be performed only inside the group.
919 @option{--no-undefined} is implied.  This option is only meaningful on ELF
920 platforms which support shared libraries.
922 @kindex -Bstatic
923 @kindex -dn
924 @kindex -non_shared
925 @kindex -static
926 @item -Bstatic
927 @itemx -dn
928 @itemx -non_shared
929 @itemx -static
930 Do not link against shared libraries.  This is only meaningful on
931 platforms for which shared libraries are supported.  The different
932 variants of this option are for compatibility with various systems.  You
933 may use this option multiple times on the command line: it affects
934 library searching for @option{-l} options which follow it.
936 @kindex -Bsymbolic
937 @item -Bsymbolic
938 When creating a shared library, bind references to global symbols to the
939 definition within the shared library, if any.  Normally, it is possible
940 for a program linked against a shared library to override the definition
941 within the shared library.  This option is only meaningful on ELF
942 platforms which support shared libraries.
944 @kindex --check-sections
945 @kindex --no-check-sections
946 @item --check-sections
947 @itemx --no-check-sections
948 Asks the linker @emph{not} to check section addresses after they have
949 been assigned to see if there any overlaps.  Normally the linker will
950 perform this check, and if it finds any overlaps it will produce
951 suitable error messages.  The linker does know about, and does make
952 allowances for sections in overlays.  The default behaviour can be
953 restored by using the command line switch @samp{--check-sections}.
955 @cindex cross reference table
956 @kindex --cref
957 @item --cref
958 Output a cross reference table.  If a linker map file is being
959 generated, the cross reference table is printed to the map file.
960 Otherwise, it is printed on the standard output.
962 The format of the table is intentionally simple, so that it may be
963 easily processed by a script if necessary.  The symbols are printed out,
964 sorted by name.  For each symbol, a list of file names is given.  If the
965 symbol is defined, the first file listed is the location of the
966 definition.  The remaining files contain references to the symbol.
968 @cindex common allocation
969 @kindex --no-define-common
970 @item --no-define-common
971 This option inhibits the assignment of addresses to common symbols.
972 The script command @code{INHIBIT_COMMON_ALLOCATION} has the same effect.
973 @xref{Miscellaneous Commands}.
975 The @samp{--no-define-common} option allows decoupling
976 the decision to assign addresses to Common symbols from the choice
977 of the output file type; otherwise a non-Relocatable output type
978 forces assigning addresses to Common symbols.
979 Using @samp{--no-define-common} allows Common symbols that are referenced
980 from a shared library to be assigned addresses only in the main program.
981 This eliminates the unused duplicate space in the shared library,
982 and also prevents any possible confusion over resolving to the wrong
983 duplicate when there are many dynamic modules with specialized search
984 paths for runtime symbol resolution.
986 @cindex symbols, from command line
987 @kindex --defsym @var{symbol}=@var{exp}
988 @item --defsym @var{symbol}=@var{expression}
989 Create a global symbol in the output file, containing the absolute
990 address given by @var{expression}.  You may use this option as many
991 times as necessary to define multiple symbols in the command line.  A
992 limited form of arithmetic is supported for the @var{expression} in this
993 context: you may give a hexadecimal constant or the name of an existing
994 symbol, or use @code{+} and @code{-} to add or subtract hexadecimal
995 constants or symbols.  If you need more elaborate expressions, consider
996 using the linker command language from a script (@pxref{Assignments,,
997 Assignment: Symbol Definitions}).  @emph{Note:} there should be no white
998 space between @var{symbol}, the equals sign (``@key{=}''), and
999 @var{expression}.
1001 @cindex demangling, from command line
1002 @kindex --demangle[=@var{style}]
1003 @kindex --no-demangle
1004 @item --demangle[=@var{style}]
1005 @itemx --no-demangle
1006 These options control whether to demangle symbol names in error messages
1007 and other output.  When the linker is told to demangle, it tries to
1008 present symbol names in a readable fashion: it strips leading
1009 underscores if they are used by the object file format, and converts C++
1010 mangled symbol names into user readable names.  Different compilers have
1011 different mangling styles.  The optional demangling style argument can be used
1012 to choose an appropriate demangling style for your compiler.  The linker will
1013 demangle by default unless the environment variable @samp{COLLECT_NO_DEMANGLE}
1014 is set.  These options may be used to override the default.
1016 @cindex dynamic linker, from command line
1017 @kindex -I@var{file}
1018 @kindex --dynamic-linker @var{file}
1019 @item --dynamic-linker @var{file}
1020 Set the name of the dynamic linker.  This is only meaningful when
1021 generating dynamically linked ELF executables.  The default dynamic
1022 linker is normally correct; don't use this unless you know what you are
1023 doing.
1025 @cindex MIPS embedded PIC code
1026 @kindex --embedded-relocs
1027 @item --embedded-relocs
1028 This option is only meaningful when linking MIPS embedded PIC code,
1029 generated by the -membedded-pic option to the @sc{gnu} compiler and
1030 assembler.  It causes the linker to create a table which may be used at
1031 runtime to relocate any data which was statically initialized to pointer
1032 values.  See the code in testsuite/ld-empic for details.
1035 @kindex --fatal-warnings
1036 @item --fatal-warnings
1037 Treat all warnings as errors.
1039 @kindex --force-exe-suffix
1040 @item  --force-exe-suffix
1041 Make sure that an output file has a .exe suffix.
1043 If a successfully built fully linked output file does not have a
1044 @code{.exe} or @code{.dll} suffix, this option forces the linker to copy
1045 the output file to one of the same name with a @code{.exe} suffix. This
1046 option is useful when using unmodified Unix makefiles on a Microsoft
1047 Windows host, since some versions of Windows won't run an image unless
1048 it ends in a @code{.exe} suffix.
1050 @kindex --gc-sections
1051 @kindex --no-gc-sections
1052 @cindex garbage collection
1053 @item --no-gc-sections
1054 @itemx --gc-sections
1055 Enable garbage collection of unused input sections.  It is ignored on
1056 targets that do not support this option.  This option is not compatible
1057 with @samp{-r}, nor should it be used with dynamic linking.  The default
1058 behaviour (of not performing this garbage collection) can be restored by
1059 specifying @samp{--no-gc-sections} on the command line.
1061 @cindex help
1062 @cindex usage
1063 @kindex --help
1064 @item --help
1065 Print a summary of the command-line options on the standard output and exit.
1067 @kindex --target-help
1068 @item --target-help
1069 Print a summary of all target specific options on the standard output and exit.
1071 @kindex -Map
1072 @item -Map @var{mapfile}
1073 Print a link map to the file @var{mapfile}.  See the description of the
1074 @samp{-M} option, above.
1076 @cindex memory usage
1077 @kindex --no-keep-memory
1078 @item --no-keep-memory
1079 @command{ld} normally optimizes for speed over memory usage by caching the
1080 symbol tables of input files in memory.  This option tells @command{ld} to
1081 instead optimize for memory usage, by rereading the symbol tables as
1082 necessary.  This may be required if @command{ld} runs out of memory space
1083 while linking a large executable.
1085 @kindex --no-undefined
1086 @kindex -z defs
1087 @item --no-undefined
1088 @itemx -z defs
1089 Normally when creating a non-symbolic shared library, undefined symbols
1090 are allowed and left to be resolved by the runtime loader.  These options
1091 disallows such undefined symbols.
1093 @kindex --allow-multiple-definition
1094 @kindex -z muldefs
1095 @item --allow-multiple-definition
1096 @itemx -z muldefs
1097 Normally when a symbol is defined multiple times, the linker will
1098 report a fatal error. These options allow multiple definitions and the
1099 first definition will be used.
1101 @kindex --allow-shlib-undefined
1102 @item --allow-shlib-undefined
1103 Allow undefined symbols in shared objects even  when --no-undefined is
1104 set. The net result will be that undefined symbols in regular objects
1105 will still trigger an error, but undefined symbols in shared objects
1106 will be ignored.  The implementation of no_undefined makes the
1107 assumption that the runtime linker will choke on undefined symbols.
1108 However there is at least one system (BeOS) where undefined symbols in
1109 shared libraries is normal since the kernel patches them at load time to
1110 select which function is most appropriate for the current architecture.
1111 I.E. dynamically select an appropriate memset function.  Apparently it
1112 is also normal for HPPA shared libraries to have undefined symbols.
1114 @kindex --no-undefined-version
1115 @item --no-undefined-version
1116 Normally when a symbol has an undefined version, the linker will ignore
1117 it. This option disallows symbols with undefined version and a fatal error
1118 will be issued instead.
1120 @kindex --no-warn-mismatch
1121 @item --no-warn-mismatch
1122 Normally @command{ld} will give an error if you try to link together input
1123 files that are mismatched for some reason, perhaps because they have
1124 been compiled for different processors or for different endiannesses.
1125 This option tells @command{ld} that it should silently permit such possible
1126 errors.  This option should only be used with care, in cases when you
1127 have taken some special action that ensures that the linker errors are
1128 inappropriate.
1130 @kindex --no-whole-archive
1131 @item --no-whole-archive
1132 Turn off the effect of the @option{--whole-archive} option for subsequent
1133 archive files.
1135 @cindex output file after errors
1136 @kindex --noinhibit-exec
1137 @item --noinhibit-exec
1138 Retain the executable output file whenever it is still usable.
1139 Normally, the linker will not produce an output file if it encounters
1140 errors during the link process; it exits without writing an output file
1141 when it issues any error whatsoever.
1143 @kindex -nostdlib
1144 @item -nostdlib
1145 Only search library directories explicitly specified on the
1146 command line.  Library directories specified in linker scripts
1147 (including linker scripts specified on the command line) are ignored.
1149 @ifclear SingleFormat
1150 @kindex --oformat
1151 @item --oformat @var{output-format}
1152 @command{ld} may be configured to support more than one kind of object
1153 file.  If your @command{ld} is configured this way, you can use the
1154 @samp{--oformat} option to specify the binary format for the output
1155 object file.  Even when @command{ld} is configured to support alternative
1156 object formats, you don't usually need to specify this, as @command{ld}
1157 should be configured to produce as a default output format the most
1158 usual format on each machine.  @var{output-format} is a text string, the
1159 name of a particular format supported by the BFD libraries.  (You can
1160 list the available binary formats with @samp{objdump -i}.)  The script
1161 command @code{OUTPUT_FORMAT} can also specify the output format, but
1162 this option overrides it.  @xref{BFD}.
1163 @end ifclear
1165 @kindex -qmagic
1166 @item -qmagic
1167 This option is ignored for Linux compatibility.
1169 @kindex -Qy
1170 @item -Qy
1171 This option is ignored for SVR4 compatibility.
1173 @kindex --relax
1174 @cindex synthesizing linker
1175 @cindex relaxing addressing modes
1176 @item --relax
1177 An option with machine dependent effects.
1178 @ifset GENERIC
1179 This option is only supported on a few targets.
1180 @end ifset
1181 @ifset H8300
1182 @xref{H8/300,,@command{ld} and the H8/300}.
1183 @end ifset
1184 @ifset I960
1185 @xref{i960,, @command{ld} and the Intel 960 family}.
1186 @end ifset
1189 On some platforms, the @samp{--relax} option performs global
1190 optimizations that become possible when the linker resolves addressing
1191 in the program, such as relaxing address modes and synthesizing new
1192 instructions in the output object file.
1194 On some platforms these link time global optimizations may make symbolic
1195 debugging of the resulting executable impossible.
1196 @ifset GENERIC
1197 This is known to be
1198 the case for the Matsushita MN10200 and MN10300 family of processors.
1199 @end ifset
1201 @ifset GENERIC
1202 On platforms where this is not supported, @samp{--relax} is accepted,
1203 but ignored.
1204 @end ifset
1206 @cindex retaining specified symbols
1207 @cindex stripping all but some symbols
1208 @cindex symbols, retaining selectively
1209 @item --retain-symbols-file @var{filename}
1210 Retain @emph{only} the symbols listed in the file @var{filename},
1211 discarding all others.  @var{filename} is simply a flat file, with one
1212 symbol name per line.  This option is especially useful in environments
1213 @ifset GENERIC
1214 (such as VxWorks)
1215 @end ifset
1216 where a large global symbol table is accumulated gradually, to conserve
1217 run-time memory.
1219 @samp{--retain-symbols-file} does @emph{not} discard undefined symbols,
1220 or symbols needed for relocations.
1222 You may only specify @samp{--retain-symbols-file} once in the command
1223 line.  It overrides @samp{-s} and @samp{-S}.
1225 @ifset GENERIC
1226 @item -rpath @var{dir}
1227 @cindex runtime library search path
1228 @kindex -rpath
1229 Add a directory to the runtime library search path.  This is used when
1230 linking an ELF executable with shared objects.  All @option{-rpath}
1231 arguments are concatenated and passed to the runtime linker, which uses
1232 them to locate shared objects at runtime.  The @option{-rpath} option is
1233 also used when locating shared objects which are needed by shared
1234 objects explicitly included in the link; see the description of the
1235 @option{-rpath-link} option.  If @option{-rpath} is not used when linking an
1236 ELF executable, the contents of the environment variable
1237 @code{LD_RUN_PATH} will be used if it is defined.
1239 The @option{-rpath} option may also be used on SunOS.  By default, on
1240 SunOS, the linker will form a runtime search patch out of all the
1241 @option{-L} options it is given.  If a @option{-rpath} option is used, the
1242 runtime search path will be formed exclusively using the @option{-rpath}
1243 options, ignoring the @option{-L} options.  This can be useful when using
1244 gcc, which adds many @option{-L} options which may be on NFS mounted
1245 filesystems.
1247 For compatibility with other ELF linkers, if the @option{-R} option is
1248 followed by a directory name, rather than a file name, it is treated as
1249 the @option{-rpath} option.
1250 @end ifset
1252 @ifset GENERIC
1253 @cindex link-time runtime library search path
1254 @kindex -rpath-link
1255 @item -rpath-link @var{DIR}
1256 When using ELF or SunOS, one shared library may require another.  This
1257 happens when an @code{ld -shared} link includes a shared library as one
1258 of the input files.
1260 When the linker encounters such a dependency when doing a non-shared,
1261 non-relocatable link, it will automatically try to locate the required
1262 shared library and include it in the link, if it is not included
1263 explicitly.  In such a case, the @option{-rpath-link} option
1264 specifies the first set of directories to search.  The
1265 @option{-rpath-link} option may specify a sequence of directory names
1266 either by specifying a list of names separated by colons, or by
1267 appearing multiple times.
1269 This option should be used with caution as it overrides the search path
1270 that may have been hard compiled into a shared library. In such a case it
1271 is possible to use unintentionally a different search path than the
1272 runtime linker would do.
1274 The linker uses the following search paths to locate required shared
1275 libraries.
1276 @enumerate
1277 @item
1278 Any directories specified by @option{-rpath-link} options.
1279 @item
1280 Any directories specified by @option{-rpath} options.  The difference
1281 between @option{-rpath} and @option{-rpath-link} is that directories
1282 specified by @option{-rpath} options are included in the executable and
1283 used at runtime, whereas the @option{-rpath-link} option is only effective
1284 at link time. It is for the native linker only.
1285 @item
1286 On an ELF system, if the @option{-rpath} and @code{rpath-link} options
1287 were not used, search the contents of the environment variable
1288 @code{LD_RUN_PATH}. It is for the native linker only.
1289 @item
1290 On SunOS, if the @option{-rpath} option was not used, search any
1291 directories specified using @option{-L} options.
1292 @item
1293 For a native linker, the contents of the environment variable
1294 @code{LD_LIBRARY_PATH}.
1295 @item
1296 For a native ELF linker, the directories in @code{DT_RUNPATH} or
1297 @code{DT_RPATH} of a shared library are searched for shared
1298 libraries needed by it. The @code{DT_RPATH} entries are ignored if
1299 @code{DT_RUNPATH} entries exist.
1300 @item
1301 The default directories, normally @file{/lib} and @file{/usr/lib}.
1302 @item
1303 For a native linker on an ELF system, if the file @file{/etc/ld.so.conf}
1304 exists, the list of directories found in that file.
1305 @end enumerate
1307 If the required shared library is not found, the linker will issue a
1308 warning and continue with the link.
1309 @end ifset
1311 @kindex -shared
1312 @kindex -Bshareable
1313 @item -shared
1314 @itemx -Bshareable
1315 @cindex shared libraries
1316 Create a shared library.  This is currently only supported on ELF, XCOFF
1317 and SunOS platforms.  On SunOS, the linker will automatically create a
1318 shared library if the @option{-e} option is not used and there are
1319 undefined symbols in the link.
1321 @item --sort-common
1322 @kindex --sort-common
1323 This option tells @command{ld} to sort the common symbols by size when it
1324 places them in the appropriate output sections.  First come all the one
1325 byte symbols, then all the two byte, then all the four byte, and then
1326 everything else.  This is to prevent gaps between symbols due to
1327 alignment constraints.
1329 @kindex --split-by-file
1330 @item --split-by-file [@var{size}]
1331 Similar to @option{--split-by-reloc} but creates a new output section for
1332 each input file when @var{size} is reached.  @var{size} defaults to a
1333 size of 1 if not given.
1335 @kindex --split-by-reloc
1336 @item --split-by-reloc [@var{count}]
1337 Tries to creates extra sections in the output file so that no single
1338 output section in the file contains more than @var{count} relocations.
1339 This is useful when generating huge relocatable files for downloading into
1340 certain real time kernels with the COFF object file format; since COFF
1341 cannot represent more than 65535 relocations in a single section.  Note
1342 that this will fail to work with object file formats which do not
1343 support arbitrary sections.  The linker will not split up individual
1344 input sections for redistribution, so if a single input section contains
1345 more than @var{count} relocations one output section will contain that
1346 many relocations.  @var{count} defaults to a value of 32768.
1348 @kindex --stats
1349 @item --stats
1350 Compute and display statistics about the operation of the linker, such
1351 as execution time and memory usage.
1353 @kindex --traditional-format
1354 @cindex traditional format
1355 @item --traditional-format
1356 For some targets, the output of @command{ld} is different in some ways from
1357 the output of some existing linker.  This switch requests @command{ld} to
1358 use the traditional format instead.
1360 @cindex dbx
1361 For example, on SunOS, @command{ld} combines duplicate entries in the
1362 symbol string table.  This can reduce the size of an output file with
1363 full debugging information by over 30 percent.  Unfortunately, the SunOS
1364 @code{dbx} program can not read the resulting program (@code{gdb} has no
1365 trouble).  The @samp{--traditional-format} switch tells @command{ld} to not
1366 combine duplicate entries.
1368 @kindex --section-start @var{sectionname}=@var{org}
1369 @item --section-start @var{sectionname}=@var{org}
1370 Locate a section in the output file at the absolute
1371 address given by @var{org}.  You may use this option as many
1372 times as necessary to locate multiple sections in the command
1373 line.
1374 @var{org} must be a single hexadecimal integer;
1375 for compatibility with other linkers, you may omit the leading
1376 @samp{0x} usually associated with hexadecimal values.  @emph{Note:} there
1377 should be no white space between @var{sectionname}, the equals
1378 sign (``@key{=}''), and @var{org}.
1380 @kindex -Tbss @var{org}
1381 @kindex -Tdata @var{org}
1382 @kindex -Ttext @var{org}
1383 @cindex segment origins, cmd line
1384 @item -Tbss @var{org}
1385 @itemx -Tdata @var{org}
1386 @itemx -Ttext @var{org}
1387 Use @var{org} as the starting address for---respectively---the
1388 @code{bss}, @code{data}, or the @code{text} segment of the output file.
1389 @var{org} must be a single hexadecimal integer;
1390 for compatibility with other linkers, you may omit the leading
1391 @samp{0x} usually associated with hexadecimal values.
1393 @kindex --verbose
1394 @cindex verbose
1395 @item --dll-verbose
1396 @itemx --verbose
1397 Display the version number for @command{ld} and list the linker emulations
1398 supported.  Display which input files can and cannot be opened.  Display
1399 the linker script being used by the linker.
1401 @kindex --version-script=@var{version-scriptfile}
1402 @cindex version script, symbol versions
1403 @itemx --version-script=@var{version-scriptfile}
1404 Specify the name of a version script to the linker.  This is typically
1405 used when creating shared libraries to specify additional information
1406 about the version heirarchy for the library being created.  This option
1407 is only meaningful on ELF platforms which support shared libraries.
1408 @xref{VERSION}.
1410 @kindex --warn-common
1411 @cindex warnings, on combining symbols
1412 @cindex combining symbols, warnings on
1413 @item --warn-common
1414 Warn when a common symbol is combined with another common symbol or with
1415 a symbol definition.  Unix linkers allow this somewhat sloppy practice,
1416 but linkers on some other operating systems do not.  This option allows
1417 you to find potential problems from combining global symbols.
1418 Unfortunately, some C libraries use this practice, so you may get some
1419 warnings about symbols in the libraries as well as in your programs.
1421 There are three kinds of global symbols, illustrated here by C examples:
1423 @table @samp
1424 @item int i = 1;
1425 A definition, which goes in the initialized data section of the output
1426 file.
1428 @item extern int i;
1429 An undefined reference, which does not allocate space.
1430 There must be either a definition or a common symbol for the
1431 variable somewhere.
1433 @item int i;
1434 A common symbol.  If there are only (one or more) common symbols for a
1435 variable, it goes in the uninitialized data area of the output file.
1436 The linker merges multiple common symbols for the same variable into a
1437 single symbol.  If they are of different sizes, it picks the largest
1438 size.  The linker turns a common symbol into a declaration, if there is
1439 a definition of the same variable.
1440 @end table
1442 The @samp{--warn-common} option can produce five kinds of warnings.
1443 Each warning consists of a pair of lines: the first describes the symbol
1444 just encountered, and the second describes the previous symbol
1445 encountered with the same name.  One or both of the two symbols will be
1446 a common symbol.
1448 @enumerate
1449 @item
1450 Turning a common symbol into a reference, because there is already a
1451 definition for the symbol.
1452 @smallexample
1453 @var{file}(@var{section}): warning: common of `@var{symbol}'
1454    overridden by definition
1455 @var{file}(@var{section}): warning: defined here
1456 @end smallexample
1458 @item
1459 Turning a common symbol into a reference, because a later definition for
1460 the symbol is encountered.  This is the same as the previous case,
1461 except that the symbols are encountered in a different order.
1462 @smallexample
1463 @var{file}(@var{section}): warning: definition of `@var{symbol}'
1464    overriding common
1465 @var{file}(@var{section}): warning: common is here
1466 @end smallexample
1468 @item
1469 Merging a common symbol with a previous same-sized common symbol.
1470 @smallexample
1471 @var{file}(@var{section}): warning: multiple common
1472    of `@var{symbol}'
1473 @var{file}(@var{section}): warning: previous common is here
1474 @end smallexample
1476 @item
1477 Merging a common symbol with a previous larger common symbol.
1478 @smallexample
1479 @var{file}(@var{section}): warning: common of `@var{symbol}'
1480    overridden by larger common
1481 @var{file}(@var{section}): warning: larger common is here
1482 @end smallexample
1484 @item
1485 Merging a common symbol with a previous smaller common symbol.  This is
1486 the same as the previous case, except that the symbols are
1487 encountered in a different order.
1488 @smallexample
1489 @var{file}(@var{section}): warning: common of `@var{symbol}'
1490    overriding smaller common
1491 @var{file}(@var{section}): warning: smaller common is here
1492 @end smallexample
1493 @end enumerate
1495 @kindex --warn-constructors
1496 @item --warn-constructors
1497 Warn if any global constructors are used.  This is only useful for a few
1498 object file formats.  For formats like COFF or ELF, the linker can not
1499 detect the use of global constructors.
1501 @kindex --warn-multiple-gp
1502 @item --warn-multiple-gp
1503 Warn if multiple global pointer values are required in the output file.
1504 This is only meaningful for certain processors, such as the Alpha.
1505 Specifically, some processors put large-valued constants in a special
1506 section.  A special register (the global pointer) points into the middle
1507 of this section, so that constants can be loaded efficiently via a
1508 base-register relative addressing mode.  Since the offset in
1509 base-register relative mode is fixed and relatively small (e.g., 16
1510 bits), this limits the maximum size of the constant pool.  Thus, in
1511 large programs, it is often necessary to use multiple global pointer
1512 values in order to be able to address all possible constants.  This
1513 option causes a warning to be issued whenever this case occurs.
1515 @kindex --warn-once
1516 @cindex warnings, on undefined symbols
1517 @cindex undefined symbols, warnings on
1518 @item --warn-once
1519 Only warn once for each undefined symbol, rather than once per module
1520 which refers to it.
1522 @kindex --warn-section-align
1523 @cindex warnings, on section alignment
1524 @cindex section alignment, warnings on
1525 @item --warn-section-align
1526 Warn if the address of an output section is changed because of
1527 alignment.  Typically, the alignment will be set by an input section.
1528 The address will only be changed if it not explicitly specified; that
1529 is, if the @code{SECTIONS} command does not specify a start address for
1530 the section (@pxref{SECTIONS}).
1532 @kindex --whole-archive
1533 @cindex including an entire archive
1534 @item --whole-archive
1535 For each archive mentioned on the command line after the
1536 @option{--whole-archive} option, include every object file in the archive
1537 in the link, rather than searching the archive for the required object
1538 files.  This is normally used to turn an archive file into a shared
1539 library, forcing every object to be included in the resulting shared
1540 library.  This option may be used more than once.
1542 Two notes when using this option from gcc: First, gcc doesn't know
1543 about this option, so you have to use @option{-Wl,-whole-archive}.
1544 Second, don't forget to use @option{-Wl,-no-whole-archive} after your
1545 list of archives, because gcc will add its own list of archives to
1546 your link and you may not want this flag to affect those as well.
1548 @kindex --wrap
1549 @item --wrap @var{symbol}
1550 Use a wrapper function for @var{symbol}.  Any undefined reference to
1551 @var{symbol} will be resolved to @code{__wrap_@var{symbol}}.  Any
1552 undefined reference to @code{__real_@var{symbol}} will be resolved to
1553 @var{symbol}.
1555 This can be used to provide a wrapper for a system function.  The
1556 wrapper function should be called @code{__wrap_@var{symbol}}.  If it
1557 wishes to call the system function, it should call
1558 @code{__real_@var{symbol}}.
1560 Here is a trivial example:
1562 @smallexample
1563 void *
1564 __wrap_malloc (int c)
1566   printf ("malloc called with %ld\n", c);
1567   return __real_malloc (c);
1569 @end smallexample
1571 If you link other code with this file using @option{--wrap malloc}, then
1572 all calls to @code{malloc} will call the function @code{__wrap_malloc}
1573 instead.  The call to @code{__real_malloc} in @code{__wrap_malloc} will
1574 call the real @code{malloc} function.
1576 You may wish to provide a @code{__real_malloc} function as well, so that
1577 links without the @option{--wrap} option will succeed.  If you do this,
1578 you should not put the definition of @code{__real_malloc} in the same
1579 file as @code{__wrap_malloc}; if you do, the assembler may resolve the
1580 call before the linker has a chance to wrap it to @code{malloc}.
1582 @kindex --enable-new-dtags
1583 @kindex --disable-new-dtags
1584 @item --enable-new-dtags
1585 @itemx --disable-new-dtags
1586 This linker can create the new dynamic tags in ELF. But the older ELF
1587 systems may not understand them. If you specify
1588 @option{--enable-new-dtags}, the dynamic tags will be created as needed.
1589 If you specify @option{--disable-new-dtags}, no new dynamic tags will be
1590 created. By default, the new dynamic tags are not created. Note that
1591 those options are only available for ELF systems.
1593 @end table
1595 @c man end
1597 @subsection Options specific to i386 PE targets
1599 @c man begin OPTIONS
1601 The i386 PE linker supports the @option{-shared} option, which causes
1602 the output to be a dynamically linked library (DLL) instead of a
1603 normal executable.  You should name the output @code{*.dll} when you
1604 use this option.  In addition, the linker fully supports the standard
1605 @code{*.def} files, which may be specified on the linker command line
1606 like an object file (in fact, it should precede archives it exports
1607 symbols from, to ensure that they get linked in, just like a normal
1608 object file).
1610 In addition to the options common to all targets, the i386 PE linker
1611 support additional command line options that are specific to the i386
1612 PE target.  Options that take values may be separated from their
1613 values by either a space or an equals sign.
1615 @table @gcctabopt
1617 @kindex --add-stdcall-alias
1618 @item --add-stdcall-alias
1619 If given, symbols with a stdcall suffix (@@@var{nn}) will be exported
1620 as-is and also with the suffix stripped.
1622 @kindex --base-file
1623 @item --base-file @var{file}
1624 Use @var{file} as the name of a file in which to save the base
1625 addresses of all the relocations needed for generating DLLs with
1626 @file{dlltool}.
1628 @kindex --dll
1629 @item --dll
1630 Create a DLL instead of a regular executable.  You may also use
1631 @option{-shared} or specify a @code{LIBRARY} in a given @code{.def}
1632 file.
1634 @kindex --enable-stdcall-fixup
1635 @kindex --disable-stdcall-fixup
1636 @item --enable-stdcall-fixup
1637 @itemx --disable-stdcall-fixup
1638 If the link finds a symbol that it cannot resolve, it will attempt to
1639 do "fuzzy linking" by looking for another defined symbol that differs
1640 only in the format of the symbol name (cdecl vs stdcall) and will
1641 resolve that symbol by linking to the match.  For example, the
1642 undefined symbol @code{_foo} might be linked to the function
1643 @code{_foo@@12}, or the undefined symbol @code{_bar@@16} might be linked
1644 to the function @code{_bar}.  When the linker does this, it prints a
1645 warning, since it normally should have failed to link, but sometimes
1646 import libraries generated from third-party dlls may need this feature
1647 to be usable.  If you specify @option{--enable-stdcall-fixup}, this
1648 feature is fully enabled and warnings are not printed.  If you specify
1649 @option{--disable-stdcall-fixup}, this feature is disabled and such
1650 mismatches are considered to be errors.
1652 @cindex DLLs, creating
1653 @kindex --export-all-symbols
1654 @item --export-all-symbols
1655 If given, all global symbols in the objects used to build a DLL will
1656 be exported by the DLL.  Note that this is the default if there
1657 otherwise wouldn't be any exported symbols.  When symbols are
1658 explicitly exported via DEF files or implicitly exported via function
1659 attributes, the default is to not export anything else unless this
1660 option is given.  Note that the symbols @code{DllMain@@12},
1661 @code{DllEntryPoint@@0}, @code{DllMainCRTStartup@@12}, and 
1662 @code{impure_ptr} will not be automatically
1663 exported.  Also, symbols imported from other DLLs will not be 
1664 re-exported, nor will symbols specifying the DLL's internal layout 
1665 such as those beginning with @code{_head_} or ending with 
1666 @code{_iname}.  In addition, no symbols from @code{libgcc}, 
1667 @code{libstd++}, @code{libmingw32}, or @code{crtX.o} will be exported.
1668 Symbols whose names begin with @code{__rtti_} or @code{__builtin_} will
1669 not be exported, to help with C++ DLLs.  Finally, there is an
1670 extensive list of cygwin-private symbols that are not exported 
1671 (obviously, this applies on when building DLLs for cygwin targets).
1672 These cygwin-excludes are: @code{_cygwin_dll_entry@@12}, 
1673 @code{_cygwin_crt0_common@@8}, @code{_cygwin_noncygwin_dll_entry@@12},
1674 @code{_fmode}, @code{_impure_ptr}, @code{cygwin_attach_dll}, 
1675 @code{cygwin_premain0}, @code{cygwin_premain1}, @code{cygwin_premain2},
1676 @code{cygwin_premain3}, and @code{environ}. 
1678 @kindex --exclude-symbols
1679 @item --exclude-symbols @var{symbol},@var{symbol},...
1680 Specifies a list of symbols which should not be automatically
1681 exported.  The symbol names may be delimited by commas or colons.
1683 @kindex --exclude-libs
1684 @item --exclude-libs @var{lib},@var{lib},...
1685 Specifies a list of archive libraries from which symbols should not be automatically
1686 exported. The library names may be delimited by commas or colons.  Specifying
1687 @code{--exclude-libs ALL} excludes symbols in all archive libraries from
1688 automatic export. Symbols explicitly listed in a .def file are still exported,
1689 regardless of this option. 
1691 @kindex --file-alignment
1692 @item --file-alignment
1693 Specify the file alignment.  Sections in the file will always begin at
1694 file offsets which are multiples of this number.  This defaults to
1695 512.
1697 @cindex heap size
1698 @kindex --heap
1699 @item --heap @var{reserve}
1700 @itemx --heap @var{reserve},@var{commit}
1701 Specify the amount of memory to reserve (and optionally commit) to be
1702 used as heap for this program.  The default is 1Mb reserved, 4K
1703 committed.
1705 @cindex image base
1706 @kindex --image-base
1707 @item --image-base @var{value}
1708 Use @var{value} as the base address of your program or dll.  This is
1709 the lowest memory location that will be used when your program or dll
1710 is loaded.  To reduce the need to relocate and improve performance of
1711 your dlls, each should have a unique base address and not overlap any
1712 other dlls.  The default is 0x400000 for executables, and 0x10000000
1713 for dlls.
1715 @kindex --kill-at
1716 @item --kill-at
1717 If given, the stdcall suffixes (@@@var{nn}) will be stripped from
1718 symbols before they are exported.
1720 @kindex --major-image-version
1721 @item --major-image-version @var{value}
1722 Sets the major number of the "image version".  Defaults to 1.
1724 @kindex --major-os-version
1725 @item --major-os-version @var{value}
1726 Sets the major number of the "os version".  Defaults to 4.
1728 @kindex --major-subsystem-version
1729 @item --major-subsystem-version @var{value}
1730 Sets the major number of the "subsystem version".  Defaults to 4.
1732 @kindex --minor-image-version
1733 @item --minor-image-version @var{value}
1734 Sets the minor number of the "image version".  Defaults to 0.
1736 @kindex --minor-os-version
1737 @item --minor-os-version @var{value}
1738 Sets the minor number of the "os version".  Defaults to 0.
1740 @kindex --minor-subsystem-version
1741 @item --minor-subsystem-version @var{value}
1742 Sets the minor number of the "subsystem version".  Defaults to 0.
1744 @cindex DEF files, creating
1745 @cindex DLLs, creating
1746 @kindex --output-def
1747 @item --output-def @var{file}
1748 The linker will create the file @var{file} which will contain a DEF
1749 file corresponding to the DLL the linker is generating.  This DEF file
1750 (which should be called @code{*.def}) may be used to create an import
1751 library with @code{dlltool} or may be used as a reference to
1752 automatically or implicitly exported symbols.
1754 @cindex DLLs, creating
1755 @kindex --out-implib
1756 @item --out-implib @var{file}
1757 The linker will create the file @var{file} which will contain an
1758 import lib corresponding to the DLL the linker is generating. This
1759 import lib (which should be called @code{*.dll.a} or @code{*.a}
1760 may be used to link clients against the generated DLL; this behavior
1761 makes it possible to skip a separate @code{dlltool} import library
1762 creation step.
1764 @kindex --enable-auto-image-base
1765 @item --enable-auto-image-base
1766 Automatically choose the image base for DLLs, unless one is specified
1767 using the @code{--image-base} argument.  By using a hash generated
1768 from the dllname to create unique image bases for each DLL, in-memory
1769 collisions and relocations which can delay program execution are
1770 avoided.
1772 @kindex --disable-auto-image-base
1773 @item --disable-auto-image-base
1774 Do not automatically generate a unique image base.  If there is no
1775 user-specified image base (@code{--image-base}) then use the platform
1776 default.
1778 @cindex DLLs, linking to
1779 @kindex --dll-search-prefix
1780 @item --dll-search-prefix @var{string}
1781 When linking dynamically to a dll without an import library, i
1782 search for @code{<string><basename>.dll} in preference to 
1783 @code{lib<basename>.dll}. This behavior allows easy distinction
1784 between DLLs built for the various "subplatforms": native, cygwin,
1785 uwin, pw, etc.  For instance, cygwin DLLs typically use
1786 @code{--dll-search-prefix=cyg}. 
1788 @kindex --enable-auto-import
1789 @item --enable-auto-import
1790 Do sophisticated linking of @code{_symbol} to @code{__imp__symbol} for 
1791 DATA imports from DLLs, and create the necessary thunking symbols when 
1792 building the DLLs with those DATA exports.  This generally will 'just 
1793 work' -- but sometimes you may see this message:
1795 "variable '<var>' can't be auto-imported. Please read the 
1796 documentation for ld's @code{--enable-auto-import} for details."
1798 This message occurs when some (sub)expression accesses an address 
1799 ultimately given by the sum of two constants (Win32 import tables only 
1800 allow one).  Instances where this may occur include accesses to member 
1801 fields of struct variables imported from a DLL, as well as using a 
1802 constant index into an array variable imported from a DLL.  Any 
1803 multiword variable (arrays, structs, long long, etc) may trigger
1804 this error condition.  However, regardless of the exact data type
1805 of the offending exported variable, ld will always detect it, issue
1806 the warning, and exit.
1808 There are several ways to address this difficulty, regardless of the
1809 data type of the exported variable:
1811 One way is to use --enable-runtime-pseudo-reloc switch. This leaves the task
1812 of adjusting references in your client code for runtime environment, so
1813 this method works only when runtime environtment supports this feature.
1815 A second solution is to force one of the 'constants' to be a variable -- 
1816 that is, unknown and un-optimizable at compile time.  For arrays, 
1817 there are two possibilities: a) make the indexee (the array's address) 
1818 a variable, or b) make the 'constant' index a variable.  Thus:
1820 @example
1821 extern type extern_array[];
1822 extern_array[1] --> 
1823    @{ volatile type *t=extern_array; t[1] @}
1824 @end example
1828 @example
1829 extern type extern_array[];
1830 extern_array[1] --> 
1831    @{ volatile int t=1; extern_array[t] @}
1832 @end example
1834 For structs (and most other multiword data types) the only option 
1835 is to make the struct itself (or the long long, or the ...) variable:
1837 @example
1838 extern struct s extern_struct;
1839 extern_struct.field --> 
1840    @{ volatile struct s *t=&extern_struct; t->field @}
1841 @end example
1845 @example
1846 extern long long extern_ll;
1847 extern_ll -->
1848   @{ volatile long long * local_ll=&extern_ll; *local_ll @}
1849 @end example
1851 A third method of dealing with this difficulty is to abandon
1852 'auto-import' for the offending symbol and mark it with 
1853 @code{__declspec(dllimport)}.  However, in practice that
1854 requires using compile-time #defines to indicate whether you are
1855 building a DLL, building client code that will link to the DLL, or 
1856 merely building/linking to a static library.   In making the choice 
1857 between the various methods of resolving the 'direct address with 
1858 constant offset' problem, you should consider typical real-world usage:
1860 Original:
1861 @example
1862 --foo.h
1863 extern int arr[];
1864 --foo.c
1865 #include "foo.h"
1866 void main(int argc, char **argv)@{
1867   printf("%d\n",arr[1]);
1869 @end example
1871 Solution 1:
1872 @example
1873 --foo.h
1874 extern int arr[];
1875 --foo.c
1876 #include "foo.h"
1877 void main(int argc, char **argv)@{
1878   /* This workaround is for win32 and cygwin; do not "optimize" */
1879   volatile int *parr = arr;
1880   printf("%d\n",parr[1]);
1882 @end example
1884 Solution 2:
1885 @example
1886 --foo.h
1887 /* Note: auto-export is assumed (no __declspec(dllexport)) */
1888 #if (defined(_WIN32) || defined(__CYGWIN__)) && \
1889   !(defined(FOO_BUILD_DLL) || defined(FOO_STATIC))
1890 #define FOO_IMPORT __declspec(dllimport)
1891 #else
1892 #define FOO_IMPORT
1893 #endif
1894 extern FOO_IMPORT int arr[];
1895 --foo.c
1896 #include "foo.h"
1897 void main(int argc, char **argv)@{
1898   printf("%d\n",arr[1]);
1900 @end example
1902 A fourth way to avoid this problem is to re-code your 
1903 library to use a functional interface rather than a data interface
1904 for the offending variables (e.g. set_foo() and get_foo() accessor
1905 functions).
1907 @kindex --disable-auto-import
1908 @item --disable-auto-import
1909 Do not attempt to do sophisticalted linking of @code{_symbol} to 
1910 @code{__imp__symbol} for DATA imports from DLLs.
1912 @kindex --enable-runtime-pseudo-reloc
1913 @item --enable-runtime-pseudo-reloc
1914 If your code contains expressions described in --enable-auto-import section,
1915 that is, DATA imports from DLL with non-zero offset, this switch will create
1916 a vector of 'runtime pseudo relocations' which can be used by runtime
1917 environment to adjust references to such data in your client code. 
1919 @kindex --disable-runtime-pseudo-reloc
1920 @item --disable-runtime-pseudo-reloc
1921 Do not create pseudo relocations for non-zero offset DATA imports from
1922 DLLs.  This is the default.
1924 @kindex --enable-extra-pe-debug
1925 @item --enable-extra-pe-debug
1926 Show additional debug info related to auto-import symbol thunking.
1928 @kindex --section-alignment
1929 @item --section-alignment
1930 Sets the section alignment.  Sections in memory will always begin at
1931 addresses which are a multiple of this number.  Defaults to 0x1000.
1933 @cindex stack size
1934 @kindex --stack
1935 @item --stack @var{reserve}
1936 @itemx --stack @var{reserve},@var{commit}
1937 Specify the amount of memory to reserve (and optionally commit) to be
1938 used as stack for this program.  The default is 2Mb reserved, 4K
1939 committed.
1941 @kindex --subsystem
1942 @item --subsystem @var{which}
1943 @itemx --subsystem @var{which}:@var{major}
1944 @itemx --subsystem @var{which}:@var{major}.@var{minor}
1945 Specifies the subsystem under which your program will execute.  The
1946 legal values for @var{which} are @code{native}, @code{windows},
1947 @code{console}, and @code{posix}.  You may optionally set the
1948 subsystem version also.
1950 @end table
1952 @c man end
1954 @ifset UsesEnvVars
1955 @node Environment
1956 @section Environment Variables
1958 @c man begin ENVIRONMENT
1960 You can change the behavior of @command{ld} with the environment variables
1961 @code{GNUTARGET}, @code{LDEMULATION}, and @code{COLLECT_NO_DEMANGLE}.
1963 @kindex GNUTARGET
1964 @cindex default input format
1965 @code{GNUTARGET} determines the input-file object format if you don't
1966 use @samp{-b} (or its synonym @samp{--format}).  Its value should be one
1967 of the BFD names for an input format (@pxref{BFD}).  If there is no
1968 @code{GNUTARGET} in the environment, @command{ld} uses the natural format
1969 of the target. If @code{GNUTARGET} is set to @code{default} then BFD
1970 attempts to discover the input format by examining binary input files;
1971 this method often succeeds, but there are potential ambiguities, since
1972 there is no method of ensuring that the magic number used to specify
1973 object-file formats is unique.  However, the configuration procedure for
1974 BFD on each system places the conventional format for that system first
1975 in the search-list, so ambiguities are resolved in favor of convention.
1977 @kindex LDEMULATION
1978 @cindex default emulation
1979 @cindex emulation, default
1980 @code{LDEMULATION} determines the default emulation if you don't use the
1981 @samp{-m} option.  The emulation can affect various aspects of linker
1982 behaviour, particularly the default linker script.  You can list the
1983 available emulations with the @samp{--verbose} or @samp{-V} options.  If
1984 the @samp{-m} option is not used, and the @code{LDEMULATION} environment
1985 variable is not defined, the default emulation depends upon how the
1986 linker was configured.
1988 @kindex COLLECT_NO_DEMANGLE
1989 @cindex demangling, default
1990 Normally, the linker will default to demangling symbols.  However, if
1991 @code{COLLECT_NO_DEMANGLE} is set in the environment, then it will
1992 default to not demangling symbols.  This environment variable is used in
1993 a similar fashion by the @code{gcc} linker wrapper program.  The default
1994 may be overridden by the @samp{--demangle} and @samp{--no-demangle}
1995 options.
1997 @c man end
1998 @end ifset
2000 @node Scripts
2001 @chapter Linker Scripts
2003 @cindex scripts
2004 @cindex linker scripts
2005 @cindex command files
2006 Every link is controlled by a @dfn{linker script}.  This script is
2007 written in the linker command language.
2009 The main purpose of the linker script is to describe how the sections in
2010 the input files should be mapped into the output file, and to control
2011 the memory layout of the output file.  Most linker scripts do nothing
2012 more than this.  However, when necessary, the linker script can also
2013 direct the linker to perform many other operations, using the commands
2014 described below.
2016 The linker always uses a linker script.  If you do not supply one
2017 yourself, the linker will use a default script that is compiled into the
2018 linker executable.  You can use the @samp{--verbose} command line option
2019 to display the default linker script.  Certain command line options,
2020 such as @samp{-r} or @samp{-N}, will affect the default linker script.
2022 You may supply your own linker script by using the @samp{-T} command
2023 line option.  When you do this, your linker script will replace the
2024 default linker script.
2026 You may also use linker scripts implicitly by naming them as input files
2027 to the linker, as though they were files to be linked.  @xref{Implicit
2028 Linker Scripts}.
2030 @menu
2031 * Basic Script Concepts::       Basic Linker Script Concepts
2032 * Script Format::               Linker Script Format
2033 * Simple Example::              Simple Linker Script Example
2034 * Simple Commands::             Simple Linker Script Commands
2035 * Assignments::                 Assigning Values to Symbols
2036 * SECTIONS::                    SECTIONS Command
2037 * MEMORY::                      MEMORY Command
2038 * PHDRS::                       PHDRS Command
2039 * VERSION::                     VERSION Command
2040 * Expressions::                 Expressions in Linker Scripts
2041 * Implicit Linker Scripts::     Implicit Linker Scripts
2042 @end menu
2044 @node Basic Script Concepts
2045 @section Basic Linker Script Concepts
2046 @cindex linker script concepts
2047 We need to define some basic concepts and vocabulary in order to
2048 describe the linker script language.
2050 The linker combines input files into a single output file.  The output
2051 file and each input file are in a special data format known as an
2052 @dfn{object file format}.  Each file is called an @dfn{object file}.
2053 The output file is often called an @dfn{executable}, but for our
2054 purposes we will also call it an object file.  Each object file has,
2055 among other things, a list of @dfn{sections}.  We sometimes refer to a
2056 section in an input file as an @dfn{input section}; similarly, a section
2057 in the output file is an @dfn{output section}.
2059 Each section in an object file has a name and a size.  Most sections
2060 also have an associated block of data, known as the @dfn{section
2061 contents}.  A section may be marked as @dfn{loadable}, which mean that
2062 the contents should be loaded into memory when the output file is run.
2063 A section with no contents may be @dfn{allocatable}, which means that an
2064 area in memory should be set aside, but nothing in particular should be
2065 loaded there (in some cases this memory must be zeroed out).  A section
2066 which is neither loadable nor allocatable typically contains some sort
2067 of debugging information.
2069 Every loadable or allocatable output section has two addresses.  The
2070 first is the @dfn{VMA}, or virtual memory address.  This is the address
2071 the section will have when the output file is run.  The second is the
2072 @dfn{LMA}, or load memory address.  This is the address at which the
2073 section will be loaded.  In most cases the two addresses will be the
2074 same.  An example of when they might be different is when a data section
2075 is loaded into ROM, and then copied into RAM when the program starts up
2076 (this technique is often used to initialize global variables in a ROM
2077 based system).  In this case the ROM address would be the LMA, and the
2078 RAM address would be the VMA.
2080 You can see the sections in an object file by using the @code{objdump}
2081 program with the @samp{-h} option.
2083 Every object file also has a list of @dfn{symbols}, known as the
2084 @dfn{symbol table}.  A symbol may be defined or undefined.  Each symbol
2085 has a name, and each defined symbol has an address, among other
2086 information.  If you compile a C or C++ program into an object file, you
2087 will get a defined symbol for every defined function and global or
2088 static variable.  Every undefined function or global variable which is
2089 referenced in the input file will become an undefined symbol.
2091 You can see the symbols in an object file by using the @code{nm}
2092 program, or by using the @code{objdump} program with the @samp{-t}
2093 option.
2095 @node Script Format
2096 @section Linker Script Format
2097 @cindex linker script format
2098 Linker scripts are text files.
2100 You write a linker script as a series of commands.  Each command is
2101 either a keyword, possibly followed by arguments, or an assignment to a
2102 symbol.  You may separate commands using semicolons.  Whitespace is
2103 generally ignored.
2105 Strings such as file or format names can normally be entered directly.
2106 If the file name contains a character such as a comma which would
2107 otherwise serve to separate file names, you may put the file name in
2108 double quotes.  There is no way to use a double quote character in a
2109 file name.
2111 You may include comments in linker scripts just as in C, delimited by
2112 @samp{/*} and @samp{*/}.  As in C, comments are syntactically equivalent
2113 to whitespace.
2115 @node Simple Example
2116 @section Simple Linker Script Example
2117 @cindex linker script example
2118 @cindex example of linker script
2119 Many linker scripts are fairly simple.
2121 The simplest possible linker script has just one command:
2122 @samp{SECTIONS}.  You use the @samp{SECTIONS} command to describe the
2123 memory layout of the output file.
2125 The @samp{SECTIONS} command is a powerful command.  Here we will
2126 describe a simple use of it.  Let's assume your program consists only of
2127 code, initialized data, and uninitialized data.  These will be in the
2128 @samp{.text}, @samp{.data}, and @samp{.bss} sections, respectively.
2129 Let's assume further that these are the only sections which appear in
2130 your input files.
2132 For this example, let's say that the code should be loaded at address
2133 0x10000, and that the data should start at address 0x8000000.  Here is a
2134 linker script which will do that:
2135 @smallexample
2136 SECTIONS
2138   . = 0x10000;
2139   .text : @{ *(.text) @}
2140   . = 0x8000000;
2141   .data : @{ *(.data) @}
2142   .bss : @{ *(.bss) @}
2144 @end smallexample
2146 You write the @samp{SECTIONS} command as the keyword @samp{SECTIONS},
2147 followed by a series of symbol assignments and output section
2148 descriptions enclosed in curly braces.
2150 The first line inside the @samp{SECTIONS} command of the above example
2151 sets the value of the special symbol @samp{.}, which is the location
2152 counter.  If you do not specify the address of an output section in some
2153 other way (other ways are described later), the address is set from the
2154 current value of the location counter.  The location counter is then
2155 incremented by the size of the output section.  At the start of the
2156 @samp{SECTIONS} command, the location counter has the value @samp{0}.
2158 The second line defines an output section, @samp{.text}.  The colon is
2159 required syntax which may be ignored for now.  Within the curly braces
2160 after the output section name, you list the names of the input sections
2161 which should be placed into this output section.  The @samp{*} is a
2162 wildcard which matches any file name.  The expression @samp{*(.text)}
2163 means all @samp{.text} input sections in all input files.
2165 Since the location counter is @samp{0x10000} when the output section
2166 @samp{.text} is defined, the linker will set the address of the
2167 @samp{.text} section in the output file to be @samp{0x10000}.
2169 The remaining lines define the @samp{.data} and @samp{.bss} sections in
2170 the output file.  The linker will place the @samp{.data} output section
2171 at address @samp{0x8000000}.  After the linker places the @samp{.data}
2172 output section, the value of the location counter will be
2173 @samp{0x8000000} plus the size of the @samp{.data} output section.  The
2174 effect is that the linker will place the @samp{.bss} output section
2175 immediately after the @samp{.data} output section in memory
2177 The linker will ensure that each output section has the required
2178 alignment, by increasing the location counter if necessary.  In this
2179 example, the specified addresses for the @samp{.text} and @samp{.data}
2180 sections will probably satisfy any alignment constraints, but the linker
2181 may have to create a small gap between the @samp{.data} and @samp{.bss}
2182 sections.
2184 That's it!  That's a simple and complete linker script.
2186 @node Simple Commands
2187 @section Simple Linker Script Commands
2188 @cindex linker script simple commands
2189 In this section we describe the simple linker script commands.
2191 @menu
2192 * Entry Point::                 Setting the entry point
2193 * File Commands::               Commands dealing with files
2194 @ifclear SingleFormat
2195 * Format Commands::             Commands dealing with object file formats
2196 @end ifclear
2198 * Miscellaneous Commands::      Other linker script commands
2199 @end menu
2201 @node Entry Point
2202 @subsection Setting the entry point
2203 @kindex ENTRY(@var{symbol})
2204 @cindex start of execution
2205 @cindex first instruction
2206 @cindex entry point
2207 The first instruction to execute in a program is called the @dfn{entry
2208 point}.  You can use the @code{ENTRY} linker script command to set the
2209 entry point.  The argument is a symbol name:
2210 @smallexample
2211 ENTRY(@var{symbol})
2212 @end smallexample
2214 There are several ways to set the entry point.  The linker will set the
2215 entry point by trying each of the following methods in order, and
2216 stopping when one of them succeeds:
2217 @itemize @bullet
2218 @item
2219 the @samp{-e} @var{entry} command-line option;
2220 @item
2221 the @code{ENTRY(@var{symbol})} command in a linker script;
2222 @item
2223 the value of the symbol @code{start}, if defined;
2224 @item
2225 the address of the first byte of the @samp{.text} section, if present;
2226 @item
2227 The address @code{0}.
2228 @end itemize
2230 @node File Commands
2231 @subsection Commands dealing with files
2232 @cindex linker script file commands
2233 Several linker script commands deal with files.
2235 @table @code
2236 @item INCLUDE @var{filename}
2237 @kindex INCLUDE @var{filename}
2238 @cindex including a linker script
2239 Include the linker script @var{filename} at this point.  The file will
2240 be searched for in the current directory, and in any directory specified
2241 with the @option{-L} option.  You can nest calls to @code{INCLUDE} up to
2242 10 levels deep.
2244 @item INPUT(@var{file}, @var{file}, @dots{})
2245 @itemx INPUT(@var{file} @var{file} @dots{})
2246 @kindex INPUT(@var{files})
2247 @cindex input files in linker scripts
2248 @cindex input object files in linker scripts
2249 @cindex linker script input object files
2250 The @code{INPUT} command directs the linker to include the named files
2251 in the link, as though they were named on the command line.
2253 For example, if you always want to include @file{subr.o} any time you do
2254 a link, but you can't be bothered to put it on every link command line,
2255 then you can put @samp{INPUT (subr.o)} in your linker script.
2257 In fact, if you like, you can list all of your input files in the linker
2258 script, and then invoke the linker with nothing but a @samp{-T} option.
2260 The linker will first try to open the file in the current directory.  If
2261 it is not found, the linker will search through the archive library
2262 search path.  See the description of @samp{-L} in @ref{Options,,Command
2263 Line Options}.
2265 If you use @samp{INPUT (-l@var{file})}, @command{ld} will transform the
2266 name to @code{lib@var{file}.a}, as with the command line argument
2267 @samp{-l}.
2269 When you use the @code{INPUT} command in an implicit linker script, the
2270 files will be included in the link at the point at which the linker
2271 script file is included.  This can affect archive searching.
2273 @item GROUP(@var{file}, @var{file}, @dots{})
2274 @itemx GROUP(@var{file} @var{file} @dots{})
2275 @kindex GROUP(@var{files})
2276 @cindex grouping input files
2277 The @code{GROUP} command is like @code{INPUT}, except that the named
2278 files should all be archives, and they are searched repeatedly until no
2279 new undefined references are created.  See the description of @samp{-(}
2280 in @ref{Options,,Command Line Options}.
2282 @item OUTPUT(@var{filename})
2283 @kindex OUTPUT(@var{filename})
2284 @cindex output file name in linker scripot
2285 The @code{OUTPUT} command names the output file.  Using
2286 @code{OUTPUT(@var{filename})} in the linker script is exactly like using
2287 @samp{-o @var{filename}} on the command line (@pxref{Options,,Command
2288 Line Options}).  If both are used, the command line option takes
2289 precedence.
2291 You can use the @code{OUTPUT} command to define a default name for the
2292 output file other than the usual default of @file{a.out}.
2294 @item SEARCH_DIR(@var{path})
2295 @kindex SEARCH_DIR(@var{path})
2296 @cindex library search path in linker script
2297 @cindex archive search path in linker script
2298 @cindex search path in linker script
2299 The @code{SEARCH_DIR} command adds @var{path} to the list of paths where
2300 @command{ld} looks for archive libraries.  Using
2301 @code{SEARCH_DIR(@var{path})} is exactly like using @samp{-L @var{path}}
2302 on the command line (@pxref{Options,,Command Line Options}).  If both
2303 are used, then the linker will search both paths.  Paths specified using
2304 the command line option are searched first.
2306 @item STARTUP(@var{filename})
2307 @kindex STARTUP(@var{filename})
2308 @cindex first input file
2309 The @code{STARTUP} command is just like the @code{INPUT} command, except
2310 that @var{filename} will become the first input file to be linked, as
2311 though it were specified first on the command line.  This may be useful
2312 when using a system in which the entry point is always the start of the
2313 first file.
2314 @end table
2316 @ifclear SingleFormat
2317 @node Format Commands
2318 @subsection Commands dealing with object file formats
2319 A couple of linker script commands deal with object file formats.
2321 @table @code
2322 @item OUTPUT_FORMAT(@var{bfdname})
2323 @itemx OUTPUT_FORMAT(@var{default}, @var{big}, @var{little})
2324 @kindex OUTPUT_FORMAT(@var{bfdname})
2325 @cindex output file format in linker script
2326 The @code{OUTPUT_FORMAT} command names the BFD format to use for the
2327 output file (@pxref{BFD}).  Using @code{OUTPUT_FORMAT(@var{bfdname})} is
2328 exactly like using @samp{--oformat @var{bfdname}} on the command line
2329 (@pxref{Options,,Command Line Options}).  If both are used, the command
2330 line option takes precedence.
2332 You can use @code{OUTPUT_FORMAT} with three arguments to use different
2333 formats based on the @samp{-EB} and @samp{-EL} command line options.
2334 This permits the linker script to set the output format based on the
2335 desired endianness.
2337 If neither @samp{-EB} nor @samp{-EL} are used, then the output format
2338 will be the first argument, @var{default}.  If @samp{-EB} is used, the
2339 output format will be the second argument, @var{big}.  If @samp{-EL} is
2340 used, the output format will be the third argument, @var{little}.
2342 For example, the default linker script for the MIPS ELF target uses this
2343 command:
2344 @smallexample
2345 OUTPUT_FORMAT(elf32-bigmips, elf32-bigmips, elf32-littlemips)
2346 @end smallexample
2347 This says that the default format for the output file is
2348 @samp{elf32-bigmips}, but if the user uses the @samp{-EL} command line
2349 option, the output file will be created in the @samp{elf32-littlemips}
2350 format.
2352 @item TARGET(@var{bfdname})
2353 @kindex TARGET(@var{bfdname})
2354 @cindex input file format in linker script
2355 The @code{TARGET} command names the BFD format to use when reading input
2356 files.  It affects subsequent @code{INPUT} and @code{GROUP} commands.
2357 This command is like using @samp{-b @var{bfdname}} on the command line
2358 (@pxref{Options,,Command Line Options}).  If the @code{TARGET} command
2359 is used but @code{OUTPUT_FORMAT} is not, then the last @code{TARGET}
2360 command is also used to set the format for the output file.  @xref{BFD}.
2361 @end table
2362 @end ifclear
2364 @node Miscellaneous Commands
2365 @subsection Other linker script commands
2366 There are a few other linker scripts commands.
2368 @table @code
2369 @item ASSERT(@var{exp}, @var{message})
2370 @kindex ASSERT
2371 @cindex assertion in linker script
2372 Ensure that @var{exp} is non-zero.  If it is zero, then exit the linker
2373 with an error code, and print @var{message}.
2375 @item EXTERN(@var{symbol} @var{symbol} @dots{})
2376 @kindex EXTERN
2377 @cindex undefined symbol in linker script
2378 Force @var{symbol} to be entered in the output file as an undefined
2379 symbol.  Doing this may, for example, trigger linking of additional
2380 modules from standard libraries.  You may list several @var{symbol}s for
2381 each @code{EXTERN}, and you may use @code{EXTERN} multiple times.  This
2382 command has the same effect as the @samp{-u} command-line option.
2384 @item FORCE_COMMON_ALLOCATION
2385 @kindex FORCE_COMMON_ALLOCATION
2386 @cindex common allocation in linker script
2387 This command has the same effect as the @samp{-d} command-line option:
2388 to make @command{ld} assign space to common symbols even if a relocatable
2389 output file is specified (@samp{-r}).
2391 @item INHIBIT_COMMON_ALLOCATION
2392 @kindex INHIBIT_COMMON_ALLOCATION
2393 @cindex common allocation in linker script
2394 This command has the same effect as the @samp{--no-define-common}
2395 command-line option: to make @code{ld} omit the assignment of addresses
2396 to common symbols even for a non-relocatable output file.
2398 @item NOCROSSREFS(@var{section} @var{section} @dots{})
2399 @kindex NOCROSSREFS(@var{sections})
2400 @cindex cross references
2401 This command may be used to tell @command{ld} to issue an error about any
2402 references among certain output sections.
2404 In certain types of programs, particularly on embedded systems when
2405 using overlays, when one section is loaded into memory, another section
2406 will not be.  Any direct references between the two sections would be
2407 errors.  For example, it would be an error if code in one section called
2408 a function defined in the other section.
2410 The @code{NOCROSSREFS} command takes a list of output section names.  If
2411 @command{ld} detects any cross references between the sections, it reports
2412 an error and returns a non-zero exit status.  Note that the
2413 @code{NOCROSSREFS} command uses output section names, not input section
2414 names.
2416 @ifclear SingleFormat
2417 @item OUTPUT_ARCH(@var{bfdarch})
2418 @kindex OUTPUT_ARCH(@var{bfdarch})
2419 @cindex machine architecture
2420 @cindex architecture
2421 Specify a particular output machine architecture.  The argument is one
2422 of the names used by the BFD library (@pxref{BFD}).  You can see the
2423 architecture of an object file by using the @code{objdump} program with
2424 the @samp{-f} option.
2425 @end ifclear
2426 @end table
2428 @node Assignments
2429 @section Assigning Values to Symbols
2430 @cindex assignment in scripts
2431 @cindex symbol definition, scripts
2432 @cindex variables, defining
2433 You may assign a value to a symbol in a linker script.  This will define
2434 the symbol as a global symbol.
2436 @menu
2437 * Simple Assignments::          Simple Assignments
2438 * PROVIDE::                     PROVIDE
2439 @end menu
2441 @node Simple Assignments
2442 @subsection Simple Assignments
2444 You may assign to a symbol using any of the C assignment operators:
2446 @table @code
2447 @item @var{symbol} = @var{expression} ;
2448 @itemx @var{symbol} += @var{expression} ;
2449 @itemx @var{symbol} -= @var{expression} ;
2450 @itemx @var{symbol} *= @var{expression} ;
2451 @itemx @var{symbol} /= @var{expression} ;
2452 @itemx @var{symbol} <<= @var{expression} ;
2453 @itemx @var{symbol} >>= @var{expression} ;
2454 @itemx @var{symbol} &= @var{expression} ;
2455 @itemx @var{symbol} |= @var{expression} ;
2456 @end table
2458 The first case will define @var{symbol} to the value of
2459 @var{expression}.  In the other cases, @var{symbol} must already be
2460 defined, and the value will be adjusted accordingly.
2462 The special symbol name @samp{.} indicates the location counter.  You
2463 may only use this within a @code{SECTIONS} command.
2465 The semicolon after @var{expression} is required.
2467 Expressions are defined below; see @ref{Expressions}.
2469 You may write symbol assignments as commands in their own right, or as
2470 statements within a @code{SECTIONS} command, or as part of an output
2471 section description in a @code{SECTIONS} command.
2473 The section of the symbol will be set from the section of the
2474 expression; for more information, see @ref{Expression Section}.
2476 Here is an example showing the three different places that symbol
2477 assignments may be used:
2479 @smallexample
2480 floating_point = 0;
2481 SECTIONS
2483   .text :
2484     @{
2485       *(.text)
2486       _etext = .;
2487     @}
2488   _bdata = (. + 3) & ~ 3;
2489   .data : @{ *(.data) @}
2491 @end smallexample
2492 @noindent
2493 In this example, the symbol @samp{floating_point} will be defined as
2494 zero.  The symbol @samp{_etext} will be defined as the address following
2495 the last @samp{.text} input section.  The symbol @samp{_bdata} will be
2496 defined as the address following the @samp{.text} output section aligned
2497 upward to a 4 byte boundary.
2499 @node PROVIDE
2500 @subsection PROVIDE
2501 @cindex PROVIDE
2502 In some cases, it is desirable for a linker script to define a symbol
2503 only if it is referenced and is not defined by any object included in
2504 the link.  For example, traditional linkers defined the symbol
2505 @samp{etext}.  However, ANSI C requires that the user be able to use
2506 @samp{etext} as a function name without encountering an error.  The
2507 @code{PROVIDE} keyword may be used to define a symbol, such as
2508 @samp{etext}, only if it is referenced but not defined.  The syntax is
2509 @code{PROVIDE(@var{symbol} = @var{expression})}.
2511 Here is an example of using @code{PROVIDE} to define @samp{etext}:
2512 @smallexample
2513 SECTIONS
2515   .text :
2516     @{
2517       *(.text)
2518       _etext = .;
2519       PROVIDE(etext = .);
2520     @}
2522 @end smallexample
2524 In this example, if the program defines @samp{_etext} (with a leading
2525 underscore), the linker will give a multiple definition error.  If, on
2526 the other hand, the program defines @samp{etext} (with no leading
2527 underscore), the linker will silently use the definition in the program.
2528 If the program references @samp{etext} but does not define it, the
2529 linker will use the definition in the linker script.
2531 @node SECTIONS
2532 @section SECTIONS command
2533 @kindex SECTIONS
2534 The @code{SECTIONS} command tells the linker how to map input sections
2535 into output sections, and how to place the output sections in memory.
2537 The format of the @code{SECTIONS} command is:
2538 @smallexample
2539 SECTIONS
2541   @var{sections-command}
2542   @var{sections-command}
2543   @dots{}
2545 @end smallexample
2547 Each @var{sections-command} may of be one of the following:
2549 @itemize @bullet
2550 @item
2551 an @code{ENTRY} command (@pxref{Entry Point,,Entry command})
2552 @item
2553 a symbol assignment (@pxref{Assignments})
2554 @item
2555 an output section description
2556 @item
2557 an overlay description
2558 @end itemize
2560 The @code{ENTRY} command and symbol assignments are permitted inside the
2561 @code{SECTIONS} command for convenience in using the location counter in
2562 those commands.  This can also make the linker script easier to
2563 understand because you can use those commands at meaningful points in
2564 the layout of the output file.
2566 Output section descriptions and overlay descriptions are described
2567 below.
2569 If you do not use a @code{SECTIONS} command in your linker script, the
2570 linker will place each input section into an identically named output
2571 section in the order that the sections are first encountered in the
2572 input files.  If all input sections are present in the first file, for
2573 example, the order of sections in the output file will match the order
2574 in the first input file.  The first section will be at address zero.
2576 @menu
2577 * Output Section Description::  Output section description
2578 * Output Section Name::         Output section name
2579 * Output Section Address::      Output section address
2580 * Input Section::               Input section description
2581 * Output Section Data::         Output section data
2582 * Output Section Keywords::     Output section keywords
2583 * Output Section Discarding::   Output section discarding
2584 * Output Section Attributes::   Output section attributes
2585 * Overlay Description::         Overlay description
2586 @end menu
2588 @node Output Section Description
2589 @subsection Output section description
2590 The full description of an output section looks like this:
2591 @smallexample
2592 @group
2593 @var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})]
2594   @{
2595     @var{output-section-command}
2596     @var{output-section-command}
2597     @dots{}
2598   @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
2599 @end group
2600 @end smallexample
2602 Most output sections do not use most of the optional section attributes.
2604 The whitespace around @var{section} is required, so that the section
2605 name is unambiguous.  The colon and the curly braces are also required.
2606 The line breaks and other white space are optional.
2608 Each @var{output-section-command} may be one of the following:
2610 @itemize @bullet
2611 @item
2612 a symbol assignment (@pxref{Assignments})
2613 @item
2614 an input section description (@pxref{Input Section})
2615 @item
2616 data values to include directly (@pxref{Output Section Data})
2617 @item
2618 a special output section keyword (@pxref{Output Section Keywords})
2619 @end itemize
2621 @node Output Section Name
2622 @subsection Output section name
2623 @cindex name, section
2624 @cindex section name
2625 The name of the output section is @var{section}.  @var{section} must
2626 meet the constraints of your output format.  In formats which only
2627 support a limited number of sections, such as @code{a.out}, the name
2628 must be one of the names supported by the format (@code{a.out}, for
2629 example, allows only @samp{.text}, @samp{.data} or @samp{.bss}). If the
2630 output format supports any number of sections, but with numbers and not
2631 names (as is the case for Oasys), the name should be supplied as a
2632 quoted numeric string.  A section name may consist of any sequence of
2633 characters, but a name which contains any unusual characters such as
2634 commas must be quoted.
2636 The output section name @samp{/DISCARD/} is special; @ref{Output Section
2637 Discarding}.
2639 @node Output Section Address
2640 @subsection Output section address
2641 @cindex address, section
2642 @cindex section address
2643 The @var{address} is an expression for the VMA (the virtual memory
2644 address) of the output section.  If you do not provide @var{address},
2645 the linker will set it based on @var{region} if present, or otherwise
2646 based on the current value of the location counter.
2648 If you provide @var{address}, the address of the output section will be
2649 set to precisely that.  If you provide neither @var{address} nor
2650 @var{region}, then the address of the output section will be set to the
2651 current value of the location counter aligned to the alignment
2652 requirements of the output section.  The alignment requirement of the
2653 output section is the strictest alignment of any input section contained
2654 within the output section.
2656 For example,
2657 @smallexample
2658 .text . : @{ *(.text) @}
2659 @end smallexample
2660 @noindent
2662 @smallexample
2663 .text : @{ *(.text) @}
2664 @end smallexample
2665 @noindent
2666 are subtly different.  The first will set the address of the
2667 @samp{.text} output section to the current value of the location
2668 counter.  The second will set it to the current value of the location
2669 counter aligned to the strictest alignment of a @samp{.text} input
2670 section.
2672 The @var{address} may be an arbitrary expression; @ref{Expressions}.
2673 For example, if you want to align the section on a 0x10 byte boundary,
2674 so that the lowest four bits of the section address are zero, you could
2675 do something like this:
2676 @smallexample
2677 .text ALIGN(0x10) : @{ *(.text) @}
2678 @end smallexample
2679 @noindent
2680 This works because @code{ALIGN} returns the current location counter
2681 aligned upward to the specified value.
2683 Specifying @var{address} for a section will change the value of the
2684 location counter.
2686 @node Input Section
2687 @subsection Input section description
2688 @cindex input sections
2689 @cindex mapping input sections to output sections
2690 The most common output section command is an input section description.
2692 The input section description is the most basic linker script operation.
2693 You use output sections to tell the linker how to lay out your program
2694 in memory.  You use input section descriptions to tell the linker how to
2695 map the input files into your memory layout.
2697 @menu
2698 * Input Section Basics::        Input section basics
2699 * Input Section Wildcards::     Input section wildcard patterns
2700 * Input Section Common::        Input section for common symbols
2701 * Input Section Keep::          Input section and garbage collection
2702 * Input Section Example::       Input section example
2703 @end menu
2705 @node Input Section Basics
2706 @subsubsection Input section basics
2707 @cindex input section basics
2708 An input section description consists of a file name optionally followed
2709 by a list of section names in parentheses.
2711 The file name and the section name may be wildcard patterns, which we
2712 describe further below (@pxref{Input Section Wildcards}).
2714 The most common input section description is to include all input
2715 sections with a particular name in the output section.  For example, to
2716 include all input @samp{.text} sections, you would write:
2717 @smallexample
2718 *(.text)
2719 @end smallexample
2720 @noindent
2721 Here the @samp{*} is a wildcard which matches any file name.  To exclude a list
2722 of files from matching the file name wildcard, EXCLUDE_FILE may be used to
2723 match all files except the ones specified in the EXCLUDE_FILE list.  For
2724 example:
2725 @smallexample
2726 (*(EXCLUDE_FILE (*crtend.o *otherfile.o) .ctors))
2727 @end smallexample
2728 will cause all .ctors sections from all files except @file{crtend.o} and
2729 @file{otherfile.o} to be included.
2731 There are two ways to include more than one section:
2732 @smallexample
2733 *(.text .rdata)
2734 *(.text) *(.rdata)
2735 @end smallexample
2736 @noindent
2737 The difference between these is the order in which the @samp{.text} and
2738 @samp{.rdata} input sections will appear in the output section.  In the
2739 first example, they will be intermingled, appearing in the same order as
2740 they are found in the linker input.  In the second example, all
2741 @samp{.text} input sections will appear first, followed by all
2742 @samp{.rdata} input sections.
2744 You can specify a file name to include sections from a particular file.
2745 You would do this if one or more of your files contain special data that
2746 needs to be at a particular location in memory.  For example:
2747 @smallexample
2748 data.o(.data)
2749 @end smallexample
2751 If you use a file name without a list of sections, then all sections in
2752 the input file will be included in the output section.  This is not
2753 commonly done, but it may by useful on occasion.  For example:
2754 @smallexample
2755 data.o
2756 @end smallexample
2758 When you use a file name which does not contain any wild card
2759 characters, the linker will first see if you also specified the file
2760 name on the linker command line or in an @code{INPUT} command.  If you
2761 did not, the linker will attempt to open the file as an input file, as
2762 though it appeared on the command line.  Note that this differs from an
2763 @code{INPUT} command, because the linker will not search for the file in
2764 the archive search path.
2766 @node Input Section Wildcards
2767 @subsubsection Input section wildcard patterns
2768 @cindex input section wildcards
2769 @cindex wildcard file name patterns
2770 @cindex file name wildcard patterns
2771 @cindex section name wildcard patterns
2772 In an input section description, either the file name or the section
2773 name or both may be wildcard patterns.
2775 The file name of @samp{*} seen in many examples is a simple wildcard
2776 pattern for the file name.
2778 The wildcard patterns are like those used by the Unix shell.
2780 @table @samp
2781 @item *
2782 matches any number of characters
2783 @item ?
2784 matches any single character
2785 @item [@var{chars}]
2786 matches a single instance of any of the @var{chars}; the @samp{-}
2787 character may be used to specify a range of characters, as in
2788 @samp{[a-z]} to match any lower case letter
2789 @item \
2790 quotes the following character
2791 @end table
2793 When a file name is matched with a wildcard, the wildcard characters
2794 will not match a @samp{/} character (used to separate directory names on
2795 Unix).  A pattern consisting of a single @samp{*} character is an
2796 exception; it will always match any file name, whether it contains a
2797 @samp{/} or not.  In a section name, the wildcard characters will match
2798 a @samp{/} character.
2800 File name wildcard patterns only match files which are explicitly
2801 specified on the command line or in an @code{INPUT} command.  The linker
2802 does not search directories to expand wildcards.
2804 If a file name matches more than one wildcard pattern, or if a file name
2805 appears explicitly and is also matched by a wildcard pattern, the linker
2806 will use the first match in the linker script.  For example, this
2807 sequence of input section descriptions is probably in error, because the
2808 @file{data.o} rule will not be used:
2809 @smallexample
2810 .data : @{ *(.data) @}
2811 .data1 : @{ data.o(.data) @}
2812 @end smallexample
2814 @cindex SORT
2815 Normally, the linker will place files and sections matched by wildcards
2816 in the order in which they are seen during the link.  You can change
2817 this by using the @code{SORT} keyword, which appears before a wildcard
2818 pattern in parentheses (e.g., @code{SORT(.text*)}).  When the
2819 @code{SORT} keyword is used, the linker will sort the files or sections
2820 into ascending order by name before placing them in the output file.
2822 If you ever get confused about where input sections are going, use the
2823 @samp{-M} linker option to generate a map file.  The map file shows
2824 precisely how input sections are mapped to output sections.
2826 This example shows how wildcard patterns might be used to partition
2827 files.  This linker script directs the linker to place all @samp{.text}
2828 sections in @samp{.text} and all @samp{.bss} sections in @samp{.bss}.
2829 The linker will place the @samp{.data} section from all files beginning
2830 with an upper case character in @samp{.DATA}; for all other files, the
2831 linker will place the @samp{.data} section in @samp{.data}.
2832 @smallexample
2833 @group
2834 SECTIONS @{
2835   .text : @{ *(.text) @}
2836   .DATA : @{ [A-Z]*(.data) @}
2837   .data : @{ *(.data) @}
2838   .bss : @{ *(.bss) @}
2840 @end group
2841 @end smallexample
2843 @node Input Section Common
2844 @subsubsection Input section for common symbols
2845 @cindex common symbol placement
2846 @cindex uninitialized data placement
2847 A special notation is needed for common symbols, because in many object
2848 file formats common symbols do not have a particular input section.  The
2849 linker treats common symbols as though they are in an input section
2850 named @samp{COMMON}.
2852 You may use file names with the @samp{COMMON} section just as with any
2853 other input sections.  You can use this to place common symbols from a
2854 particular input file in one section while common symbols from other
2855 input files are placed in another section.
2857 In most cases, common symbols in input files will be placed in the
2858 @samp{.bss} section in the output file.  For example:
2859 @smallexample
2860 .bss @{ *(.bss) *(COMMON) @}
2861 @end smallexample
2863 @cindex scommon section
2864 @cindex small common symbols
2865 Some object file formats have more than one type of common symbol.  For
2866 example, the MIPS ELF object file format distinguishes standard common
2867 symbols and small common symbols.  In this case, the linker will use a
2868 different special section name for other types of common symbols.  In
2869 the case of MIPS ELF, the linker uses @samp{COMMON} for standard common
2870 symbols and @samp{.scommon} for small common symbols.  This permits you
2871 to map the different types of common symbols into memory at different
2872 locations.
2874 @cindex [COMMON]
2875 You will sometimes see @samp{[COMMON]} in old linker scripts.  This
2876 notation is now considered obsolete.  It is equivalent to
2877 @samp{*(COMMON)}.
2879 @node Input Section Keep
2880 @subsubsection Input section and garbage collection
2881 @cindex KEEP
2882 @cindex garbage collection
2883 When link-time garbage collection is in use (@samp{--gc-sections}),
2884 it is often useful to mark sections that should not be eliminated.
2885 This is accomplished by surrounding an input section's wildcard entry
2886 with @code{KEEP()}, as in @code{KEEP(*(.init))} or
2887 @code{KEEP(SORT(*)(.ctors))}.
2889 @node Input Section Example
2890 @subsubsection Input section example
2891 The following example is a complete linker script.  It tells the linker
2892 to read all of the sections from file @file{all.o} and place them at the
2893 start of output section @samp{outputa} which starts at location
2894 @samp{0x10000}.  All of section @samp{.input1} from file @file{foo.o}
2895 follows immediately, in the same output section.  All of section
2896 @samp{.input2} from @file{foo.o} goes into output section
2897 @samp{outputb}, followed by section @samp{.input1} from @file{foo1.o}.
2898 All of the remaining @samp{.input1} and @samp{.input2} sections from any
2899 files are written to output section @samp{outputc}.
2901 @smallexample
2902 @group
2903 SECTIONS @{
2904   outputa 0x10000 :
2905     @{
2906     all.o
2907     foo.o (.input1)
2908     @}
2909   outputb :
2910     @{
2911     foo.o (.input2)
2912     foo1.o (.input1)
2913     @}
2914   outputc :
2915     @{
2916     *(.input1)
2917     *(.input2)
2918     @}
2920 @end group
2921 @end smallexample
2923 @node Output Section Data
2924 @subsection Output section data
2925 @cindex data
2926 @cindex section data
2927 @cindex output section data
2928 @kindex BYTE(@var{expression})
2929 @kindex SHORT(@var{expression})
2930 @kindex LONG(@var{expression})
2931 @kindex QUAD(@var{expression})
2932 @kindex SQUAD(@var{expression})
2933 You can include explicit bytes of data in an output section by using
2934 @code{BYTE}, @code{SHORT}, @code{LONG}, @code{QUAD}, or @code{SQUAD} as
2935 an output section command.  Each keyword is followed by an expression in
2936 parentheses providing the value to store (@pxref{Expressions}).  The
2937 value of the expression is stored at the current value of the location
2938 counter.
2940 The @code{BYTE}, @code{SHORT}, @code{LONG}, and @code{QUAD} commands
2941 store one, two, four, and eight bytes (respectively).  After storing the
2942 bytes, the location counter is incremented by the number of bytes
2943 stored.
2945 For example, this will store the byte 1 followed by the four byte value
2946 of the symbol @samp{addr}:
2947 @smallexample
2948 BYTE(1)
2949 LONG(addr)
2950 @end smallexample
2952 When using a 64 bit host or target, @code{QUAD} and @code{SQUAD} are the
2953 same; they both store an 8 byte, or 64 bit, value.  When both host and
2954 target are 32 bits, an expression is computed as 32 bits.  In this case
2955 @code{QUAD} stores a 32 bit value zero extended to 64 bits, and
2956 @code{SQUAD} stores a 32 bit value sign extended to 64 bits.
2958 If the object file format of the output file has an explicit endianness,
2959 which is the normal case, the value will be stored in that endianness.
2960 When the object file format does not have an explicit endianness, as is
2961 true of, for example, S-records, the value will be stored in the
2962 endianness of the first input object file.
2964 Note - these commands only work inside a section description and not
2965 between them, so the following will produce an error from the linker:
2966 @smallexample
2967 SECTIONS @{@ .text : @{@ *(.text) @}@ LONG(1) .data : @{@ *(.data) @}@ @}@
2968 @end smallexample
2969 whereas this will work:
2970 @smallexample
2971 SECTIONS @{@ .text : @{@ *(.text) ; LONG(1) @}@ .data : @{@ *(.data) @}@ @}@
2972 @end smallexample
2974 @kindex FILL(@var{expression})
2975 @cindex holes, filling
2976 @cindex unspecified memory
2977 You may use the @code{FILL} command to set the fill pattern for the
2978 current section.  It is followed by an expression in parentheses.  Any
2979 otherwise unspecified regions of memory within the section (for example,
2980 gaps left due to the required alignment of input sections) are filled
2981 with the value of the expression, repeated as
2982 necessary.  A @code{FILL} statement covers memory locations after the
2983 point at which it occurs in the section definition; by including more
2984 than one @code{FILL} statement, you can have different fill patterns in
2985 different parts of an output section.
2987 This example shows how to fill unspecified regions of memory with the
2988 value @samp{0x90}:
2989 @smallexample
2990 FILL(0x90909090)
2991 @end smallexample
2993 The @code{FILL} command is similar to the @samp{=@var{fillexp}} output
2994 section attribute, but it only affects the
2995 part of the section following the @code{FILL} command, rather than the
2996 entire section.  If both are used, the @code{FILL} command takes
2997 precedence.  @xref{Output Section Fill}, for details on the fill
2998 expression.
3000 @node Output Section Keywords
3001 @subsection Output section keywords
3002 There are a couple of keywords which can appear as output section
3003 commands.
3005 @table @code
3006 @kindex CREATE_OBJECT_SYMBOLS
3007 @cindex input filename symbols
3008 @cindex filename symbols
3009 @item CREATE_OBJECT_SYMBOLS
3010 The command tells the linker to create a symbol for each input file.
3011 The name of each symbol will be the name of the corresponding input
3012 file.  The section of each symbol will be the output section in which
3013 the @code{CREATE_OBJECT_SYMBOLS} command appears.
3015 This is conventional for the a.out object file format.  It is not
3016 normally used for any other object file format.
3018 @kindex CONSTRUCTORS
3019 @cindex C++ constructors, arranging in link
3020 @cindex constructors, arranging in link
3021 @item CONSTRUCTORS
3022 When linking using the a.out object file format, the linker uses an
3023 unusual set construct to support C++ global constructors and
3024 destructors.  When linking object file formats which do not support
3025 arbitrary sections, such as ECOFF and XCOFF, the linker will
3026 automatically recognize C++ global constructors and destructors by name.
3027 For these object file formats, the @code{CONSTRUCTORS} command tells the
3028 linker to place constructor information in the output section where the
3029 @code{CONSTRUCTORS} command appears.  The @code{CONSTRUCTORS} command is
3030 ignored for other object file formats.
3032 The symbol @w{@code{__CTOR_LIST__}} marks the start of the global
3033 constructors, and the symbol @w{@code{__DTOR_LIST}} marks the end.  The
3034 first word in the list is the number of entries, followed by the address
3035 of each constructor or destructor, followed by a zero word.  The
3036 compiler must arrange to actually run the code.  For these object file
3037 formats @sc{gnu} C++ normally calls constructors from a subroutine
3038 @code{__main}; a call to @code{__main} is automatically inserted into
3039 the startup code for @code{main}.  @sc{gnu} C++ normally runs
3040 destructors either by using @code{atexit}, or directly from the function
3041 @code{exit}.
3043 For object file formats such as @code{COFF} or @code{ELF} which support
3044 arbitrary section names, @sc{gnu} C++ will normally arrange to put the
3045 addresses of global constructors and destructors into the @code{.ctors}
3046 and @code{.dtors} sections.  Placing the following sequence into your
3047 linker script will build the sort of table which the @sc{gnu} C++
3048 runtime code expects to see.
3050 @smallexample
3051       __CTOR_LIST__ = .;
3052       LONG((__CTOR_END__ - __CTOR_LIST__) / 4 - 2)
3053       *(.ctors)
3054       LONG(0)
3055       __CTOR_END__ = .;
3056       __DTOR_LIST__ = .;
3057       LONG((__DTOR_END__ - __DTOR_LIST__) / 4 - 2)
3058       *(.dtors)
3059       LONG(0)
3060       __DTOR_END__ = .;
3061 @end smallexample
3063 If you are using the @sc{gnu} C++ support for initialization priority,
3064 which provides some control over the order in which global constructors
3065 are run, you must sort the constructors at link time to ensure that they
3066 are executed in the correct order.  When using the @code{CONSTRUCTORS}
3067 command, use @samp{SORT(CONSTRUCTORS)} instead.  When using the
3068 @code{.ctors} and @code{.dtors} sections, use @samp{*(SORT(.ctors))} and
3069 @samp{*(SORT(.dtors))} instead of just @samp{*(.ctors)} and
3070 @samp{*(.dtors)}.
3072 Normally the compiler and linker will handle these issues automatically,
3073 and you will not need to concern yourself with them.  However, you may
3074 need to consider this if you are using C++ and writing your own linker
3075 scripts.
3077 @end table
3079 @node Output Section Discarding
3080 @subsection Output section discarding
3081 @cindex discarding sections
3082 @cindex sections, discarding
3083 @cindex removing sections
3084 The linker will not create output section which do not have any
3085 contents.  This is for convenience when referring to input sections that
3086 may or may not be present in any of the input files.  For example:
3087 @smallexample
3088 .foo @{ *(.foo) @}
3089 @end smallexample
3090 @noindent
3091 will only create a @samp{.foo} section in the output file if there is a
3092 @samp{.foo} section in at least one input file.
3094 If you use anything other than an input section description as an output
3095 section command, such as a symbol assignment, then the output section
3096 will always be created, even if there are no matching input sections.
3098 @cindex /DISCARD/
3099 The special output section name @samp{/DISCARD/} may be used to discard
3100 input sections.  Any input sections which are assigned to an output
3101 section named @samp{/DISCARD/} are not included in the output file.
3103 @node Output Section Attributes
3104 @subsection Output section attributes
3105 @cindex output section attributes
3106 We showed above that the full description of an output section looked
3107 like this:
3108 @smallexample
3109 @group
3110 @var{section} [@var{address}] [(@var{type})] : [AT(@var{lma})]
3111   @{
3112     @var{output-section-command}
3113     @var{output-section-command}
3114     @dots{}
3115   @} [>@var{region}] [AT>@var{lma_region}] [:@var{phdr} :@var{phdr} @dots{}] [=@var{fillexp}]
3116 @end group
3117 @end smallexample
3118 We've already described @var{section}, @var{address}, and
3119 @var{output-section-command}.  In this section we will describe the
3120 remaining section attributes.
3122 @menu
3123 * Output Section Type::         Output section type
3124 * Output Section LMA::          Output section LMA
3125 * Output Section Region::       Output section region
3126 * Output Section Phdr::         Output section phdr
3127 * Output Section Fill::         Output section fill
3128 @end menu
3130 @node Output Section Type
3131 @subsubsection Output section type
3132 Each output section may have a type.  The type is a keyword in
3133 parentheses.  The following types are defined:
3135 @table @code
3136 @item NOLOAD
3137 The section should be marked as not loadable, so that it will not be
3138 loaded into memory when the program is run.
3139 @item DSECT
3140 @itemx COPY
3141 @itemx INFO
3142 @itemx OVERLAY
3143 These type names are supported for backward compatibility, and are
3144 rarely used.  They all have the same effect: the section should be
3145 marked as not allocatable, so that no memory is allocated for the
3146 section when the program is run.
3147 @end table
3149 @kindex NOLOAD
3150 @cindex prevent unnecessary loading
3151 @cindex loading, preventing
3152 The linker normally sets the attributes of an output section based on
3153 the input sections which map into it.  You can override this by using
3154 the section type.  For example, in the script sample below, the
3155 @samp{ROM} section is addressed at memory location @samp{0} and does not
3156 need to be loaded when the program is run.  The contents of the
3157 @samp{ROM} section will appear in the linker output file as usual.
3158 @smallexample
3159 @group
3160 SECTIONS @{
3161   ROM 0 (NOLOAD) : @{ @dots{} @}
3162   @dots{}
3164 @end group
3165 @end smallexample
3167 @node Output Section LMA
3168 @subsubsection Output section LMA
3169 @kindex AT>@var{lma_region}
3170 @kindex AT(@var{lma})
3171 @cindex load address
3172 @cindex section load address
3173 Every section has a virtual address (VMA) and a load address (LMA); see
3174 @ref{Basic Script Concepts}.  The address expression which may appear in
3175 an output section description sets the VMA (@pxref{Output Section
3176 Address}).
3178 The linker will normally set the LMA equal to the VMA.  You can change
3179 that by using the @code{AT} keyword.  The expression @var{lma} that
3180 follows the @code{AT} keyword specifies the load address of the
3181 section.  Alternatively, with @samp{AT>@var{lma_region}} expression,
3182 you may specify a memory region for the section's load address. @xref{MEMORY}.
3184 @cindex ROM initialized data
3185 @cindex initialized data in ROM
3186 This feature is designed to make it easy to build a ROM image.  For
3187 example, the following linker script creates three output sections: one
3188 called @samp{.text}, which starts at @code{0x1000}, one called
3189 @samp{.mdata}, which is loaded at the end of the @samp{.text} section
3190 even though its VMA is @code{0x2000}, and one called @samp{.bss} to hold
3191 uninitialized data at address @code{0x3000}.  The symbol @code{_data} is
3192 defined with the value @code{0x2000}, which shows that the location
3193 counter holds the VMA value, not the LMA value.
3195 @smallexample
3196 @group
3197 SECTIONS
3198   @{
3199   .text 0x1000 : @{ *(.text) _etext = . ; @}
3200   .mdata 0x2000 :
3201     AT ( ADDR (.text) + SIZEOF (.text) )
3202     @{ _data = . ; *(.data); _edata = . ;  @}
3203   .bss 0x3000 :
3204     @{ _bstart = . ;  *(.bss) *(COMMON) ; _bend = . ;@}
3206 @end group
3207 @end smallexample
3209 The run-time initialization code for use with a program generated with
3210 this linker script would include something like the following, to copy
3211 the initialized data from the ROM image to its runtime address.  Notice
3212 how this code takes advantage of the symbols defined by the linker
3213 script.
3215 @smallexample
3216 @group
3217 extern char _etext, _data, _edata, _bstart, _bend;
3218 char *src = &_etext;
3219 char *dst = &_data;
3221 /* ROM has data at end of text; copy it. */
3222 while (dst < &_edata) @{
3223   *dst++ = *src++;
3226 /* Zero bss */
3227 for (dst = &_bstart; dst< &_bend; dst++)
3228   *dst = 0;
3229 @end group
3230 @end smallexample
3232 @node Output Section Region
3233 @subsubsection Output section region
3234 @kindex >@var{region}
3235 @cindex section, assigning to memory region
3236 @cindex memory regions and sections
3237 You can assign a section to a previously defined region of memory by
3238 using @samp{>@var{region}}.  @xref{MEMORY}.
3240 Here is a simple example:
3241 @smallexample
3242 @group
3243 MEMORY @{ rom : ORIGIN = 0x1000, LENGTH = 0x1000 @}
3244 SECTIONS @{ ROM : @{ *(.text) @} >rom @}
3245 @end group
3246 @end smallexample
3248 @node Output Section Phdr
3249 @subsubsection Output section phdr
3250 @kindex :@var{phdr}
3251 @cindex section, assigning to program header
3252 @cindex program headers and sections
3253 You can assign a section to a previously defined program segment by
3254 using @samp{:@var{phdr}}.  @xref{PHDRS}.  If a section is assigned to
3255 one or more segments, then all subsequent allocated sections will be
3256 assigned to those segments as well, unless they use an explicitly
3257 @code{:@var{phdr}} modifier.  You can use @code{:NONE} to tell the
3258 linker to not put the section in any segment at all.
3260 Here is a simple example:
3261 @smallexample
3262 @group
3263 PHDRS @{ text PT_LOAD ; @}
3264 SECTIONS @{ .text : @{ *(.text) @} :text @}
3265 @end group
3266 @end smallexample
3268 @node Output Section Fill
3269 @subsubsection Output section fill
3270 @kindex =@var{fillexp}
3271 @cindex section fill pattern
3272 @cindex fill pattern, entire section
3273 You can set the fill pattern for an entire section by using
3274 @samp{=@var{fillexp}}.  @var{fillexp} is an expression
3275 (@pxref{Expressions}).  Any otherwise unspecified regions of memory
3276 within the output section (for example, gaps left due to the required
3277 alignment of input sections) will be filled with the value, repeated as
3278 necessary.  If the fill expression is a simple hex number, ie. a string
3279 of hex digit starting with @samp{0x} and without a trailing @samp{k} or @samp{M}, then
3280 an arbitrarily long sequence of hex digits can be used to specify the
3281 fill pattern;  Leading zeros become part of the pattern too.  For all
3282 other cases, including extra parentheses or a unary @code{+}, the fill
3283 pattern is the four least significant bytes of the value of the
3284 expression.  In all cases, the number is big-endian.
3286 You can also change the fill value with a @code{FILL} command in the
3287 output section commands; (@pxref{Output Section Data}).
3289 Here is a simple example:
3290 @smallexample
3291 @group
3292 SECTIONS @{ .text : @{ *(.text) @} =0x90909090 @}
3293 @end group
3294 @end smallexample
3296 @node Overlay Description
3297 @subsection Overlay description
3298 @kindex OVERLAY
3299 @cindex overlays
3300 An overlay description provides an easy way to describe sections which
3301 are to be loaded as part of a single memory image but are to be run at
3302 the same memory address.  At run time, some sort of overlay manager will
3303 copy the overlaid sections in and out of the runtime memory address as
3304 required, perhaps by simply manipulating addressing bits.  This approach
3305 can be useful, for example, when a certain region of memory is faster
3306 than another.
3308 Overlays are described using the @code{OVERLAY} command.  The
3309 @code{OVERLAY} command is used within a @code{SECTIONS} command, like an
3310 output section description.  The full syntax of the @code{OVERLAY}
3311 command is as follows:
3312 @smallexample
3313 @group
3314 OVERLAY [@var{start}] : [NOCROSSREFS] [AT ( @var{ldaddr} )]
3315   @{
3316     @var{secname1}
3317       @{
3318         @var{output-section-command}
3319         @var{output-section-command}
3320         @dots{}
3321       @} [:@var{phdr}@dots{}] [=@var{fill}]
3322     @var{secname2}
3323       @{
3324         @var{output-section-command}
3325         @var{output-section-command}
3326         @dots{}
3327       @} [:@var{phdr}@dots{}] [=@var{fill}]
3328     @dots{}
3329   @} [>@var{region}] [:@var{phdr}@dots{}] [=@var{fill}]
3330 @end group
3331 @end smallexample
3333 Everything is optional except @code{OVERLAY} (a keyword), and each
3334 section must have a name (@var{secname1} and @var{secname2} above).  The
3335 section definitions within the @code{OVERLAY} construct are identical to
3336 those within the general @code{SECTIONS} contruct (@pxref{SECTIONS}),
3337 except that no addresses and no memory regions may be defined for
3338 sections within an @code{OVERLAY}.
3340 The sections are all defined with the same starting address.  The load
3341 addresses of the sections are arranged such that they are consecutive in
3342 memory starting at the load address used for the @code{OVERLAY} as a
3343 whole (as with normal section definitions, the load address is optional,
3344 and defaults to the start address; the start address is also optional,
3345 and defaults to the current value of the location counter).
3347 If the @code{NOCROSSREFS} keyword is used, and there any references
3348 among the sections, the linker will report an error.  Since the sections
3349 all run at the same address, it normally does not make sense for one
3350 section to refer directly to another.  @xref{Miscellaneous Commands,
3351 NOCROSSREFS}.
3353 For each section within the @code{OVERLAY}, the linker automatically
3354 defines two symbols.  The symbol @code{__load_start_@var{secname}} is
3355 defined as the starting load address of the section.  The symbol
3356 @code{__load_stop_@var{secname}} is defined as the final load address of
3357 the section.  Any characters within @var{secname} which are not legal
3358 within C identifiers are removed.  C (or assembler) code may use these
3359 symbols to move the overlaid sections around as necessary.
3361 At the end of the overlay, the value of the location counter is set to
3362 the start address of the overlay plus the size of the largest section.
3364 Here is an example.  Remember that this would appear inside a
3365 @code{SECTIONS} construct.
3366 @smallexample
3367 @group
3368   OVERLAY 0x1000 : AT (0x4000)
3369    @{
3370      .text0 @{ o1/*.o(.text) @}
3371      .text1 @{ o2/*.o(.text) @}
3372    @}
3373 @end group
3374 @end smallexample
3375 @noindent
3376 This will define both @samp{.text0} and @samp{.text1} to start at
3377 address 0x1000.  @samp{.text0} will be loaded at address 0x4000, and
3378 @samp{.text1} will be loaded immediately after @samp{.text0}.  The
3379 following symbols will be defined: @code{__load_start_text0},
3380 @code{__load_stop_text0}, @code{__load_start_text1},
3381 @code{__load_stop_text1}.
3383 C code to copy overlay @code{.text1} into the overlay area might look
3384 like the following.
3386 @smallexample
3387 @group
3388   extern char __load_start_text1, __load_stop_text1;
3389   memcpy ((char *) 0x1000, &__load_start_text1,
3390           &__load_stop_text1 - &__load_start_text1);
3391 @end group
3392 @end smallexample
3394 Note that the @code{OVERLAY} command is just syntactic sugar, since
3395 everything it does can be done using the more basic commands.  The above
3396 example could have been written identically as follows.
3398 @smallexample
3399 @group
3400   .text0 0x1000 : AT (0x4000) @{ o1/*.o(.text) @}
3401   __load_start_text0 = LOADADDR (.text0);
3402   __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
3403   .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) @{ o2/*.o(.text) @}
3404   __load_start_text1 = LOADADDR (.text1);
3405   __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
3406   . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
3407 @end group
3408 @end smallexample
3410 @node MEMORY
3411 @section MEMORY command
3412 @kindex MEMORY
3413 @cindex memory regions
3414 @cindex regions of memory
3415 @cindex allocating memory
3416 @cindex discontinuous memory
3417 The linker's default configuration permits allocation of all available
3418 memory.  You can override this by using the @code{MEMORY} command.
3420 The @code{MEMORY} command describes the location and size of blocks of
3421 memory in the target.  You can use it to describe which memory regions
3422 may be used by the linker, and which memory regions it must avoid.  You
3423 can then assign sections to particular memory regions.  The linker will
3424 set section addresses based on the memory regions, and will warn about
3425 regions that become too full.  The linker will not shuffle sections
3426 around to fit into the available regions.
3428 A linker script may contain at most one use of the @code{MEMORY}
3429 command.  However, you can define as many blocks of memory within it as
3430 you wish.  The syntax is:
3431 @smallexample
3432 @group
3433 MEMORY
3434   @{
3435     @var{name} [(@var{attr})] : ORIGIN = @var{origin}, LENGTH = @var{len}
3436     @dots{}
3437   @}
3438 @end group
3439 @end smallexample
3441 The @var{name} is a name used in the linker script to refer to the
3442 region.  The region name has no meaning outside of the linker script.
3443 Region names are stored in a separate name space, and will not conflict
3444 with symbol names, file names, or section names.  Each memory region
3445 must have a distinct name.
3447 @cindex memory region attributes
3448 The @var{attr} string is an optional list of attributes that specify
3449 whether to use a particular memory region for an input section which is
3450 not explicitly mapped in the linker script.  As described in
3451 @ref{SECTIONS}, if you do not specify an output section for some input
3452 section, the linker will create an output section with the same name as
3453 the input section.  If you define region attributes, the linker will use
3454 them to select the memory region for the output section that it creates.
3456 The @var{attr} string must consist only of the following characters:
3457 @table @samp
3458 @item R
3459 Read-only section
3460 @item W
3461 Read/write section
3462 @item X
3463 Executable section
3464 @item A
3465 Allocatable section
3466 @item I
3467 Initialized section
3468 @item L
3469 Same as @samp{I}
3470 @item !
3471 Invert the sense of any of the preceding attributes
3472 @end table
3474 If a unmapped section matches any of the listed attributes other than
3475 @samp{!}, it will be placed in the memory region.  The @samp{!}
3476 attribute reverses this test, so that an unmapped section will be placed
3477 in the memory region only if it does not match any of the listed
3478 attributes.
3480 @kindex ORIGIN =
3481 @kindex o =
3482 @kindex org =
3483 The @var{origin} is an expression for the start address of the memory
3484 region.  The expression must evaluate to a constant before memory
3485 allocation is performed, which means that you may not use any section
3486 relative symbols.  The keyword @code{ORIGIN} may be abbreviated to
3487 @code{org} or @code{o} (but not, for example, @code{ORG}).
3489 @kindex LENGTH =
3490 @kindex len =
3491 @kindex l =
3492 The @var{len} is an expression for the size in bytes of the memory
3493 region.  As with the @var{origin} expression, the expression must
3494 evaluate to a constant before memory allocation is performed.  The
3495 keyword @code{LENGTH} may be abbreviated to @code{len} or @code{l}.
3497 In the following example, we specify that there are two memory regions
3498 available for allocation: one starting at @samp{0} for 256 kilobytes,
3499 and the other starting at @samp{0x40000000} for four megabytes.  The
3500 linker will place into the @samp{rom} memory region every section which
3501 is not explicitly mapped into a memory region, and is either read-only
3502 or executable.  The linker will place other sections which are not
3503 explicitly mapped into a memory region into the @samp{ram} memory
3504 region.
3506 @smallexample
3507 @group
3508 MEMORY
3509   @{
3510     rom (rx)  : ORIGIN = 0, LENGTH = 256K
3511     ram (!rx) : org = 0x40000000, l = 4M
3512   @}
3513 @end group
3514 @end smallexample
3516 Once you define a memory region, you can direct the linker to place
3517 specific output sections into that memory region by using the
3518 @samp{>@var{region}} output section attribute.  For example, if you have
3519 a memory region named @samp{mem}, you would use @samp{>mem} in the
3520 output section definition.  @xref{Output Section Region}.  If no address
3521 was specified for the output section, the linker will set the address to
3522 the next available address within the memory region.  If the combined
3523 output sections directed to a memory region are too large for the
3524 region, the linker will issue an error message.
3526 @node PHDRS
3527 @section PHDRS Command
3528 @kindex PHDRS
3529 @cindex program headers
3530 @cindex ELF program headers
3531 @cindex program segments
3532 @cindex segments, ELF
3533 The ELF object file format uses @dfn{program headers}, also knows as
3534 @dfn{segments}.  The program headers describe how the program should be
3535 loaded into memory.  You can print them out by using the @code{objdump}
3536 program with the @samp{-p} option.
3538 When you run an ELF program on a native ELF system, the system loader
3539 reads the program headers in order to figure out how to load the
3540 program.  This will only work if the program headers are set correctly.
3541 This manual does not describe the details of how the system loader
3542 interprets program headers; for more information, see the ELF ABI.
3544 The linker will create reasonable program headers by default.  However,
3545 in some cases, you may need to specify the program headers more
3546 precisely.  You may use the @code{PHDRS} command for this purpose.  When
3547 the linker sees the @code{PHDRS} command in the linker script, it will
3548 not create any program headers other than the ones specified.
3550 The linker only pays attention to the @code{PHDRS} command when
3551 generating an ELF output file.  In other cases, the linker will simply
3552 ignore @code{PHDRS}.
3554 This is the syntax of the @code{PHDRS} command.  The words @code{PHDRS},
3555 @code{FILEHDR}, @code{AT}, and @code{FLAGS} are keywords.
3557 @smallexample
3558 @group
3559 PHDRS
3561   @var{name} @var{type} [ FILEHDR ] [ PHDRS ] [ AT ( @var{address} ) ]
3562         [ FLAGS ( @var{flags} ) ] ;
3564 @end group
3565 @end smallexample
3567 The @var{name} is used only for reference in the @code{SECTIONS} command
3568 of the linker script.  It is not put into the output file.  Program
3569 header names are stored in a separate name space, and will not conflict
3570 with symbol names, file names, or section names.  Each program header
3571 must have a distinct name.
3573 Certain program header types describe segments of memory which the
3574 system loader will load from the file.  In the linker script, you
3575 specify the contents of these segments by placing allocatable output
3576 sections in the segments.  You use the @samp{:@var{phdr}} output section
3577 attribute to place a section in a particular segment.  @xref{Output
3578 Section Phdr}.
3580 It is normal to put certain sections in more than one segment.  This
3581 merely implies that one segment of memory contains another.  You may
3582 repeat @samp{:@var{phdr}}, using it once for each segment which should
3583 contain the section.
3585 If you place a section in one or more segments using @samp{:@var{phdr}},
3586 then the linker will place all subsequent allocatable sections which do
3587 not specify @samp{:@var{phdr}} in the same segments.  This is for
3588 convenience, since generally a whole set of contiguous sections will be
3589 placed in a single segment.  You can use @code{:NONE} to override the
3590 default segment and tell the linker to not put the section in any
3591 segment at all.
3593 @kindex FILEHDR
3594 @kindex PHDRS
3595 You may use the @code{FILEHDR} and @code{PHDRS} keywords appear after
3596 the program header type to further describe the contents of the segment.
3597 The @code{FILEHDR} keyword means that the segment should include the ELF
3598 file header.  The @code{PHDRS} keyword means that the segment should
3599 include the ELF program headers themselves.
3601 The @var{type} may be one of the following.  The numbers indicate the
3602 value of the keyword.
3604 @table @asis
3605 @item @code{PT_NULL} (0)
3606 Indicates an unused program header.
3608 @item @code{PT_LOAD} (1)
3609 Indicates that this program header describes a segment to be loaded from
3610 the file.
3612 @item @code{PT_DYNAMIC} (2)
3613 Indicates a segment where dynamic linking information can be found.
3615 @item @code{PT_INTERP} (3)
3616 Indicates a segment where the name of the program interpreter may be
3617 found.
3619 @item @code{PT_NOTE} (4)
3620 Indicates a segment holding note information.
3622 @item @code{PT_SHLIB} (5)
3623 A reserved program header type, defined but not specified by the ELF
3624 ABI.
3626 @item @code{PT_PHDR} (6)
3627 Indicates a segment where the program headers may be found.
3629 @item @var{expression}
3630 An expression giving the numeric type of the program header.  This may
3631 be used for types not defined above.
3632 @end table
3634 You can specify that a segment should be loaded at a particular address
3635 in memory by using an @code{AT} expression.  This is identical to the
3636 @code{AT} command used as an output section attribute (@pxref{Output
3637 Section LMA}).  The @code{AT} command for a program header overrides the
3638 output section attribute.
3640 The linker will normally set the segment flags based on the sections
3641 which comprise the segment.  You may use the @code{FLAGS} keyword to
3642 explicitly specify the segment flags.  The value of @var{flags} must be
3643 an integer.  It is used to set the @code{p_flags} field of the program
3644 header.
3646 Here is an example of @code{PHDRS}.  This shows a typical set of program
3647 headers used on a native ELF system.
3649 @example
3650 @group
3651 PHDRS
3653   headers PT_PHDR PHDRS ;
3654   interp PT_INTERP ;
3655   text PT_LOAD FILEHDR PHDRS ;
3656   data PT_LOAD ;
3657   dynamic PT_DYNAMIC ;
3660 SECTIONS
3662   . = SIZEOF_HEADERS;
3663   .interp : @{ *(.interp) @} :text :interp
3664   .text : @{ *(.text) @} :text
3665   .rodata : @{ *(.rodata) @} /* defaults to :text */
3666   @dots{}
3667   . = . + 0x1000; /* move to a new page in memory */
3668   .data : @{ *(.data) @} :data
3669   .dynamic : @{ *(.dynamic) @} :data :dynamic
3670   @dots{}
3672 @end group
3673 @end example
3675 @node VERSION
3676 @section VERSION Command
3677 @kindex VERSION @{script text@}
3678 @cindex symbol versions
3679 @cindex version script
3680 @cindex versions of symbols
3681 The linker supports symbol versions when using ELF.  Symbol versions are
3682 only useful when using shared libraries.  The dynamic linker can use
3683 symbol versions to select a specific version of a function when it runs
3684 a program that may have been linked against an earlier version of the
3685 shared library.
3687 You can include a version script directly in the main linker script, or
3688 you can supply the version script as an implicit linker script.  You can
3689 also use the @samp{--version-script} linker option.
3691 The syntax of the @code{VERSION} command is simply
3692 @smallexample
3693 VERSION @{ version-script-commands @}
3694 @end smallexample
3696 The format of the version script commands is identical to that used by
3697 Sun's linker in Solaris 2.5.  The version script defines a tree of
3698 version nodes.  You specify the node names and interdependencies in the
3699 version script.  You can specify which symbols are bound to which
3700 version nodes, and you can reduce a specified set of symbols to local
3701 scope so that they are not globally visible outside of the shared
3702 library.
3704 The easiest way to demonstrate the version script language is with a few
3705 examples.
3707 @smallexample
3708 VERS_1.1 @{
3709          global:
3710                  foo1;
3711          local:
3712                  old*;
3713                  original*;
3714                  new*;
3717 VERS_1.2 @{
3718                  foo2;
3719 @} VERS_1.1;
3721 VERS_2.0 @{
3722                  bar1; bar2;
3723 @} VERS_1.2;
3724 @end smallexample
3726 This example version script defines three version nodes.  The first
3727 version node defined is @samp{VERS_1.1}; it has no other dependencies.
3728 The script binds the symbol @samp{foo1} to @samp{VERS_1.1}.  It reduces
3729 a number of symbols to local scope so that they are not visible outside
3730 of the shared library; this is done using wildcard patterns, so that any
3731 symbol whose name begins with @samp{old}, @samp{original}, or @samp{new}
3732 is matched.  The wildcard patterns available are the same as those used
3733 in the shell when matching filenames (also known as ``globbing'').
3735 Next, the version script defines node @samp{VERS_1.2}.  This node
3736 depends upon @samp{VERS_1.1}.  The script binds the symbol @samp{foo2}
3737 to the version node @samp{VERS_1.2}.
3739 Finally, the version script defines node @samp{VERS_2.0}.  This node
3740 depends upon @samp{VERS_1.2}.  The scripts binds the symbols @samp{bar1}
3741 and @samp{bar2} are bound to the version node @samp{VERS_2.0}.
3743 When the linker finds a symbol defined in a library which is not
3744 specifically bound to a version node, it will effectively bind it to an
3745 unspecified base version of the library.  You can bind all otherwise
3746 unspecified symbols to a given version node by using @samp{global: *}
3747 somewhere in the version script.
3749 The names of the version nodes have no specific meaning other than what
3750 they might suggest to the person reading them.  The @samp{2.0} version
3751 could just as well have appeared in between @samp{1.1} and @samp{1.2}.
3752 However, this would be a confusing way to write a version script.
3754 Node name can be omited, provided it is the only version node
3755 in the version script.  Such version script doesn't assign any versions to
3756 symbols, only selects which symbols will be globally visible out and which
3757 won't.
3759 @smallexample
3760 @{ global: foo; bar; local: *; @}
3761 @end smallexample
3763 When you link an application against a shared library that has versioned
3764 symbols, the application itself knows which version of each symbol it
3765 requires, and it also knows which version nodes it needs from each
3766 shared library it is linked against.  Thus at runtime, the dynamic
3767 loader can make a quick check to make sure that the libraries you have
3768 linked against do in fact supply all of the version nodes that the
3769 application will need to resolve all of the dynamic symbols.  In this
3770 way it is possible for the dynamic linker to know with certainty that
3771 all external symbols that it needs will be resolvable without having to
3772 search for each symbol reference.
3774 The symbol versioning is in effect a much more sophisticated way of
3775 doing minor version checking that SunOS does.  The fundamental problem
3776 that is being addressed here is that typically references to external
3777 functions are bound on an as-needed basis, and are not all bound when
3778 the application starts up.  If a shared library is out of date, a
3779 required interface may be missing; when the application tries to use
3780 that interface, it may suddenly and unexpectedly fail.  With symbol
3781 versioning, the user will get a warning when they start their program if
3782 the libraries being used with the application are too old.
3784 There are several GNU extensions to Sun's versioning approach.  The
3785 first of these is the ability to bind a symbol to a version node in the
3786 source file where the symbol is defined instead of in the versioning
3787 script.  This was done mainly to reduce the burden on the library
3788 maintainer.  You can do this by putting something like:
3789 @smallexample
3790 __asm__(".symver original_foo,foo@@VERS_1.1");
3791 @end smallexample
3792 @noindent
3793 in the C source file.  This renames the function @samp{original_foo} to
3794 be an alias for @samp{foo} bound to the version node @samp{VERS_1.1}.
3795 The @samp{local:} directive can be used to prevent the symbol
3796 @samp{original_foo} from being exported. A @samp{.symver} directive
3797 takes precedence over a version script.
3799 The second GNU extension is to allow multiple versions of the same
3800 function to appear in a given shared library.  In this way you can make
3801 an incompatible change to an interface without increasing the major
3802 version number of the shared library, while still allowing applications
3803 linked against the old interface to continue to function.
3805 To do this, you must use multiple @samp{.symver} directives in the
3806 source file.  Here is an example:
3808 @smallexample
3809 __asm__(".symver original_foo,foo@@");
3810 __asm__(".symver old_foo,foo@@VERS_1.1");
3811 __asm__(".symver old_foo1,foo@@VERS_1.2");
3812 __asm__(".symver new_foo,foo@@@@VERS_2.0");
3813 @end smallexample
3815 In this example, @samp{foo@@} represents the symbol @samp{foo} bound to the
3816 unspecified base version of the symbol.  The source file that contains this
3817 example would define 4 C functions: @samp{original_foo}, @samp{old_foo},
3818 @samp{old_foo1}, and @samp{new_foo}.
3820 When you have multiple definitions of a given symbol, there needs to be
3821 some way to specify a default version to which external references to
3822 this symbol will be bound.  You can do this with the
3823 @samp{foo@@@@VERS_2.0} type of @samp{.symver} directive.  You can only
3824 declare one version of a symbol as the default in this manner; otherwise
3825 you would effectively have multiple definitions of the same symbol.
3827 If you wish to bind a reference to a specific version of the symbol
3828 within the shared library, you can use the aliases of convenience
3829 (i.e. @samp{old_foo}), or you can use the @samp{.symver} directive to
3830 specifically bind to an external version of the function in question.
3832 You can also specify the language in the version script:
3834 @smallexample
3835 VERSION extern "lang" @{ version-script-commands @}
3836 @end smallexample
3838 The supported @samp{lang}s are @samp{C}, @samp{C++}, and @samp{Java}. 
3839 The linker will iterate over the list of symbols at the link time and
3840 demangle them according to @samp{lang} before matching them to the
3841 patterns specified in @samp{version-script-commands}.
3843 @node Expressions
3844 @section Expressions in Linker Scripts
3845 @cindex expressions
3846 @cindex arithmetic
3847 The syntax for expressions in the linker script language is identical to
3848 that of C expressions.  All expressions are evaluated as integers.  All
3849 expressions are evaluated in the same size, which is 32 bits if both the
3850 host and target are 32 bits, and is otherwise 64 bits.
3852 You can use and set symbol values in expressions.
3854 The linker defines several special purpose builtin functions for use in
3855 expressions.
3857 @menu
3858 * Constants::                   Constants
3859 * Symbols::                     Symbol Names
3860 * Location Counter::            The Location Counter
3861 * Operators::                   Operators
3862 * Evaluation::                  Evaluation
3863 * Expression Section::          The Section of an Expression
3864 * Builtin Functions::           Builtin Functions
3865 @end menu
3867 @node Constants
3868 @subsection Constants
3869 @cindex integer notation
3870 @cindex constants in linker scripts
3871 All constants are integers.
3873 As in C, the linker considers an integer beginning with @samp{0} to be
3874 octal, and an integer beginning with @samp{0x} or @samp{0X} to be
3875 hexadecimal.  The linker considers other integers to be decimal.
3877 @cindex scaled integers
3878 @cindex K and M integer suffixes
3879 @cindex M and K integer suffixes
3880 @cindex suffixes for integers
3881 @cindex integer suffixes
3882 In addition, you can use the suffixes @code{K} and @code{M} to scale a
3883 constant by
3884 @c TEXI2ROFF-KILL
3885 @ifinfo
3886 @c END TEXI2ROFF-KILL
3887 @code{1024} or @code{1024*1024}
3888 @c TEXI2ROFF-KILL
3889 @end ifinfo
3890 @tex
3891 ${\rm 1024}$ or ${\rm 1024}^2$
3892 @end tex
3893 @c END TEXI2ROFF-KILL
3894 respectively. For example, the following all refer to the same quantity:
3895 @smallexample
3896   _fourk_1 = 4K;
3897   _fourk_2 = 4096;
3898   _fourk_3 = 0x1000;
3899 @end smallexample
3901 @node Symbols
3902 @subsection Symbol Names
3903 @cindex symbol names
3904 @cindex names
3905 @cindex quoted symbol names
3906 @kindex "
3907 Unless quoted, symbol names start with a letter, underscore, or period
3908 and may include letters, digits, underscores, periods, and hyphens.
3909 Unquoted symbol names must not conflict with any keywords.  You can
3910 specify a symbol which contains odd characters or has the same name as a
3911 keyword by surrounding the symbol name in double quotes:
3912 @smallexample
3913   "SECTION" = 9;
3914   "with a space" = "also with a space" + 10;
3915 @end smallexample
3917 Since symbols can contain many non-alphabetic characters, it is safest
3918 to delimit symbols with spaces.  For example, @samp{A-B} is one symbol,
3919 whereas @samp{A - B} is an expression involving subtraction.
3921 @node Location Counter
3922 @subsection The Location Counter
3923 @kindex .
3924 @cindex dot
3925 @cindex location counter
3926 @cindex current output location
3927 The special linker variable @dfn{dot} @samp{.} always contains the
3928 current output location counter.  Since the @code{.} always refers to a
3929 location in an output section, it may only appear in an expression
3930 within a @code{SECTIONS} command.  The @code{.} symbol may appear
3931 anywhere that an ordinary symbol is allowed in an expression.
3933 @cindex holes
3934 Assigning a value to @code{.} will cause the location counter to be
3935 moved.  This may be used to create holes in the output section.  The
3936 location counter may never be moved backwards.
3938 @smallexample
3939 SECTIONS
3941   output :
3942     @{
3943       file1(.text)
3944       . = . + 1000;
3945       file2(.text)
3946       . += 1000;
3947       file3(.text)
3948     @} = 0x12345678;
3950 @end smallexample
3951 @noindent
3952 In the previous example, the @samp{.text} section from @file{file1} is
3953 located at the beginning of the output section @samp{output}.  It is
3954 followed by a 1000 byte gap.  Then the @samp{.text} section from
3955 @file{file2} appears, also with a 1000 byte gap following before the
3956 @samp{.text} section from @file{file3}.  The notation @samp{= 0x12345678}
3957 specifies what data to write in the gaps (@pxref{Output Section Fill}).
3959 @cindex dot inside sections
3960 Note: @code{.} actually refers to the byte offset from the start of the
3961 current containing object.  Normally this is the @code{SECTIONS}
3962 statement, whoes start address is 0, hence @code{.} can be used as an
3963 absolute address.  If @code{.} is used inside a section description
3964 however, it refers to the byte offset from the start of that section,
3965 not an absolute address.  Thus in a script like this:
3967 @smallexample
3968 SECTIONS
3970     . = 0x100
3971     .text: @{
3972       *(.text)
3973       . = 0x200
3974     @}
3975     . = 0x500
3976     .data: @{
3977       *(.data)
3978       . += 0x600
3979     @}
3981 @end smallexample
3983 The @samp{.text} section will be assigned a starting address of 0x100
3984 and a size of exactly 0x200 bytes, even if there is not enough data in
3985 the @samp{.text} input sections to fill this area.  (If there is too
3986 much data, an error will be produced because this would be an attempt to
3987 move @code{.} backwards).  The @samp{.data} section will start at 0x500
3988 and it will have an extra 0x600 bytes worth of space after the end of
3989 the values from the @samp{.data} input sections and before the end of
3990 the @samp{.data} output section itself.
3992 @need 2000
3993 @node Operators
3994 @subsection Operators
3995 @cindex operators for arithmetic
3996 @cindex arithmetic operators
3997 @cindex precedence in expressions
3998 The linker recognizes the standard C set of arithmetic operators, with
3999 the standard bindings and precedence levels:
4000 @c TEXI2ROFF-KILL
4001 @ifinfo
4002 @c END TEXI2ROFF-KILL
4003 @smallexample
4004 precedence      associativity   Operators                Notes
4005 (highest)
4006 1               left            !  -  ~                  (1)
4007 2               left            *  /  %
4008 3               left            +  -
4009 4               left            >>  <<
4010 5               left            ==  !=  >  <  <=  >=
4011 6               left            &
4012 7               left            |
4013 8               left            &&
4014 9               left            ||
4015 10              right           ? :
4016 11              right           &=  +=  -=  *=  /=       (2)
4017 (lowest)
4018 @end smallexample
4019 Notes:
4020 (1) Prefix operators
4021 (2) @xref{Assignments}.
4022 @c TEXI2ROFF-KILL
4023 @end ifinfo
4024 @tex
4025 \vskip \baselineskip
4026 %"lispnarrowing" is the extra indent used generally for smallexample
4027 \hskip\lispnarrowing\vbox{\offinterlineskip
4028 \hrule
4029 \halign
4030 {\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ #\ \hfil&\vrule#&\strut\hfil\ {\tt #}\ \hfil&\vrule#\cr
4031 height2pt&\omit&&\omit&&\omit&\cr
4032 &Precedence&&  Associativity  &&{\rm Operators}&\cr
4033 height2pt&\omit&&\omit&&\omit&\cr
4034 \noalign{\hrule}
4035 height2pt&\omit&&\omit&&\omit&\cr
4036 &highest&&&&&\cr
4037 % '176 is tilde, '~' in tt font
4038 &1&&left&&\qquad-          \char'176\      !\qquad\dag&\cr
4039 &2&&left&&*          /        \%&\cr
4040 &3&&left&&+          -&\cr
4041 &4&&left&&>>         <<&\cr
4042 &5&&left&&==         !=       >      <      <=      >=&\cr
4043 &6&&left&&\&&\cr
4044 &7&&left&&|&\cr
4045 &8&&left&&{\&\&}&\cr
4046 &9&&left&&||&\cr
4047 &10&&right&&?        :&\cr
4048 &11&&right&&\qquad\&=      +=       -=     *=     /=\qquad\ddag&\cr
4049 &lowest&&&&&\cr
4050 height2pt&\omit&&\omit&&\omit&\cr}
4051 \hrule}
4052 @end tex
4053 @iftex
4055 @obeylines@parskip=0pt@parindent=0pt
4056 @dag@quad Prefix operators.
4057 @ddag@quad @xref{Assignments}.
4059 @end iftex
4060 @c END TEXI2ROFF-KILL
4062 @node Evaluation
4063 @subsection Evaluation
4064 @cindex lazy evaluation
4065 @cindex expression evaluation order
4066 The linker evaluates expressions lazily.  It only computes the value of
4067 an expression when absolutely necessary.
4069 The linker needs some information, such as the value of the start
4070 address of the first section, and the origins and lengths of memory
4071 regions, in order to do any linking at all.  These values are computed
4072 as soon as possible when the linker reads in the linker script.
4074 However, other values (such as symbol values) are not known or needed
4075 until after storage allocation.  Such values are evaluated later, when
4076 other information (such as the sizes of output sections) is available
4077 for use in the symbol assignment expression.
4079 The sizes of sections cannot be known until after allocation, so
4080 assignments dependent upon these are not performed until after
4081 allocation.
4083 Some expressions, such as those depending upon the location counter
4084 @samp{.}, must be evaluated during section allocation.
4086 If the result of an expression is required, but the value is not
4087 available, then an error results.  For example, a script like the
4088 following
4089 @smallexample
4090 @group
4091 SECTIONS
4092   @{
4093     .text 9+this_isnt_constant :
4094       @{ *(.text) @}
4095   @}
4096 @end group
4097 @end smallexample
4098 @noindent
4099 will cause the error message @samp{non constant expression for initial
4100 address}.
4102 @node Expression Section
4103 @subsection The Section of an Expression
4104 @cindex expression sections
4105 @cindex absolute expressions
4106 @cindex relative expressions
4107 @cindex absolute and relocatable symbols
4108 @cindex relocatable and absolute symbols
4109 @cindex symbols, relocatable and absolute
4110 When the linker evaluates an expression, the result is either absolute
4111 or relative to some section.  A relative expression is expressed as a
4112 fixed offset from the base of a section.
4114 The position of the expression within the linker script determines
4115 whether it is absolute or relative.  An expression which appears within
4116 an output section definition is relative to the base of the output
4117 section.  An expression which appears elsewhere will be absolute.
4119 A symbol set to a relative expression will be relocatable if you request
4120 relocatable output using the @samp{-r} option.  That means that a
4121 further link operation may change the value of the symbol.  The symbol's
4122 section will be the section of the relative expression.
4124 A symbol set to an absolute expression will retain the same value
4125 through any further link operation.  The symbol will be absolute, and
4126 will not have any particular associated section.
4128 You can use the builtin function @code{ABSOLUTE} to force an expression
4129 to be absolute when it would otherwise be relative.  For example, to
4130 create an absolute symbol set to the address of the end of the output
4131 section @samp{.data}:
4132 @smallexample
4133 SECTIONS
4134   @{
4135     .data : @{ *(.data) _edata = ABSOLUTE(.); @}
4136   @}
4137 @end smallexample
4138 @noindent
4139 If @samp{ABSOLUTE} were not used, @samp{_edata} would be relative to the
4140 @samp{.data} section.
4142 @node Builtin Functions
4143 @subsection Builtin Functions
4144 @cindex functions in expressions
4145 The linker script language includes a number of builtin functions for
4146 use in linker script expressions.
4148 @table @code
4149 @item ABSOLUTE(@var{exp})
4150 @kindex ABSOLUTE(@var{exp})
4151 @cindex expression, absolute
4152 Return the absolute (non-relocatable, as opposed to non-negative) value
4153 of the expression @var{exp}.  Primarily useful to assign an absolute
4154 value to a symbol within a section definition, where symbol values are
4155 normally section relative.  @xref{Expression Section}.
4157 @item ADDR(@var{section})
4158 @kindex ADDR(@var{section})
4159 @cindex section address in expression
4160 Return the absolute address (the VMA) of the named @var{section}.  Your
4161 script must previously have defined the location of that section.  In
4162 the following example, @code{symbol_1} and @code{symbol_2} are assigned
4163 identical values:
4164 @smallexample
4165 @group
4166 SECTIONS @{ @dots{}
4167   .output1 :
4168     @{
4169     start_of_output_1 = ABSOLUTE(.);
4170     @dots{}
4171     @}
4172   .output :
4173     @{
4174     symbol_1 = ADDR(.output1);
4175     symbol_2 = start_of_output_1;
4176     @}
4177 @dots{} @}
4178 @end group
4179 @end smallexample
4181 @item ALIGN(@var{exp})
4182 @kindex ALIGN(@var{exp})
4183 @cindex round up location counter
4184 @cindex align location counter
4185 Return the location counter (@code{.}) aligned to the next @var{exp}
4186 boundary.
4187 @code{ALIGN} doesn't change the value of the location counter---it just
4188 does arithmetic on it.  Here is an example which aligns the output
4189 @code{.data} section to the next @code{0x2000} byte boundary after the
4190 preceding section and sets a variable within the section to the next
4191 @code{0x8000} boundary after the input sections:
4192 @smallexample
4193 @group
4194 SECTIONS @{ @dots{}
4195   .data ALIGN(0x2000): @{
4196     *(.data)
4197     variable = ALIGN(0x8000);
4198   @}
4199 @dots{} @}
4200 @end group
4201 @end smallexample
4202 @noindent
4203 The first use of @code{ALIGN} in this example specifies the location of
4204 a section because it is used as the optional @var{address} attribute of
4205 a section definition (@pxref{Output Section Address}).  The second use
4206 of @code{ALIGN} is used to defines the value of a symbol.
4208 The builtin function @code{NEXT} is closely related to @code{ALIGN}.
4210 @item BLOCK(@var{exp})
4211 @kindex BLOCK(@var{exp})
4212 This is a synonym for @code{ALIGN}, for compatibility with older linker
4213 scripts.  It is most often seen when setting the address of an output
4214 section.
4216 @item DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
4217 @kindex DATA_SEGMENT_ALIGN(@var{maxpagesize}, @var{commonpagesize})
4218 This is equivalent to either
4219 @smallexample
4220 (ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - 1)))
4221 @end smallexample
4223 @smallexample
4224 (ALIGN(@var{maxpagesize}) + (. & (@var{maxpagesize} - @var{commonpagesize})))
4225 @end smallexample
4226 @noindent
4227 depending on whether the latter uses fewer @var{commonpagesize} sized pages
4228 for the data segment (area between the result of this expression and
4229 @code{DATA_SEGMENT_END}) than the former or not.
4230 If the latter form is used, it means @var{commonpagesize} bytes of runtime
4231 memory will be saved at the expense of up to @var{commonpagesize} wasted
4232 bytes in the on-disk file.
4234 This expression can only be used directly in @code{SECTIONS} commands, not in
4235 any output section descriptions and only once in the linker script.
4236 @var{commonpagesize} should be less or equal to @var{maxpagesize} and should
4237 be the system page size the object wants to be optimized for (while still
4238 working on system page sizes up to @var{maxpagesize}).
4240 @noindent
4241 Example:
4242 @smallexample
4243   . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
4244 @end smallexample
4246 @item DATA_SEGMENT_END(@var{exp})
4247 @kindex DATA_SEGMENT_END(@var{exp})
4248 This defines the end of data segment for @code{DATA_SEGMENT_ALIGN}
4249 evaluation purposes.
4251 @smallexample
4252   . = DATA_SEGMENT_END(.);
4253 @end smallexample
4255 @item DEFINED(@var{symbol})
4256 @kindex DEFINED(@var{symbol})
4257 @cindex symbol defaults
4258 Return 1 if @var{symbol} is in the linker global symbol table and is
4259 defined, otherwise return 0.  You can use this function to provide
4260 default values for symbols.  For example, the following script fragment
4261 shows how to set a global symbol @samp{begin} to the first location in
4262 the @samp{.text} section---but if a symbol called @samp{begin} already
4263 existed, its value is preserved:
4265 @smallexample
4266 @group
4267 SECTIONS @{ @dots{}
4268   .text : @{
4269     begin = DEFINED(begin) ? begin : . ;
4270     @dots{}
4271   @}
4272   @dots{}
4274 @end group
4275 @end smallexample
4277 @item LOADADDR(@var{section})
4278 @kindex LOADADDR(@var{section})
4279 @cindex section load address in expression
4280 Return the absolute LMA of the named @var{section}.  This is normally
4281 the same as @code{ADDR}, but it may be different if the @code{AT}
4282 attribute is used in the output section definition (@pxref{Output
4283 Section LMA}).
4285 @kindex MAX
4286 @item MAX(@var{exp1}, @var{exp2})
4287 Returns the maximum of @var{exp1} and @var{exp2}.
4289 @kindex MIN
4290 @item MIN(@var{exp1}, @var{exp2})
4291 Returns the minimum of @var{exp1} and @var{exp2}.
4293 @item NEXT(@var{exp})
4294 @kindex NEXT(@var{exp})
4295 @cindex unallocated address, next
4296 Return the next unallocated address that is a multiple of @var{exp}.
4297 This function is closely related to @code{ALIGN(@var{exp})}; unless you
4298 use the @code{MEMORY} command to define discontinuous memory for the
4299 output file, the two functions are equivalent.
4301 @item SIZEOF(@var{section})
4302 @kindex SIZEOF(@var{section})
4303 @cindex section size
4304 Return the size in bytes of the named @var{section}, if that section has
4305 been allocated.  If the section has not been allocated when this is
4306 evaluated, the linker will report an error.  In the following example,
4307 @code{symbol_1} and @code{symbol_2} are assigned identical values:
4308 @smallexample
4309 @group
4310 SECTIONS@{ @dots{}
4311   .output @{
4312     .start = . ;
4313     @dots{}
4314     .end = . ;
4315     @}
4316   symbol_1 = .end - .start ;
4317   symbol_2 = SIZEOF(.output);
4318 @dots{} @}
4319 @end group
4320 @end smallexample
4322 @item SIZEOF_HEADERS
4323 @itemx sizeof_headers
4324 @kindex SIZEOF_HEADERS
4325 @cindex header size
4326 Return the size in bytes of the output file's headers.  This is
4327 information which appears at the start of the output file.  You can use
4328 this number when setting the start address of the first section, if you
4329 choose, to facilitate paging.
4331 @cindex not enough room for program headers
4332 @cindex program headers, not enough room
4333 When producing an ELF output file, if the linker script uses the
4334 @code{SIZEOF_HEADERS} builtin function, the linker must compute the
4335 number of program headers before it has determined all the section
4336 addresses and sizes.  If the linker later discovers that it needs
4337 additional program headers, it will report an error @samp{not enough
4338 room for program headers}.  To avoid this error, you must avoid using
4339 the @code{SIZEOF_HEADERS} function, or you must rework your linker
4340 script to avoid forcing the linker to use additional program headers, or
4341 you must define the program headers yourself using the @code{PHDRS}
4342 command (@pxref{PHDRS}).
4343 @end table
4345 @node Implicit Linker Scripts
4346 @section Implicit Linker Scripts
4347 @cindex implicit linker scripts
4348 If you specify a linker input file which the linker can not recognize as
4349 an object file or an archive file, it will try to read the file as a
4350 linker script.  If the file can not be parsed as a linker script, the
4351 linker will report an error.
4353 An implicit linker script will not replace the default linker script.
4355 Typically an implicit linker script would contain only symbol
4356 assignments, or the @code{INPUT}, @code{GROUP}, or @code{VERSION}
4357 commands.
4359 Any input files read because of an implicit linker script will be read
4360 at the position in the command line where the implicit linker script was
4361 read.  This can affect archive searching.
4363 @ifset GENERIC
4364 @node Machine Dependent
4365 @chapter Machine Dependent Features
4367 @cindex machine dependencies
4368 @command{ld} has additional features on some platforms; the following
4369 sections describe them.  Machines where @command{ld} has no additional
4370 functionality are not listed.
4372 @menu
4373 * H8/300::                      @code{ld} and the H8/300
4374 * i960::                        @code{ld} and the Intel 960 family
4375 * ARM::                         @code{ld} and the ARM family
4376 * HPPA ELF32::                  @code{ld} and HPPA 32-bit ELF
4377 @ifset MMIX
4378 * MMIX::                        @code{ld} and MMIX
4379 @end ifset
4380 @ifset TICOFF
4381 * TI COFF::                     @command{ld} and TI COFF
4382 @end ifset
4383 @end menu
4384 @end ifset
4386 @c FIXME!  This could use @raisesections/@lowersections, but there seems to be a conflict
4387 @c         between those and node-defaulting.
4388 @ifset H8300
4389 @ifclear GENERIC
4390 @raisesections
4391 @end ifclear
4393 @node H8/300
4394 @section @command{ld} and the H8/300
4396 @cindex H8/300 support
4397 For the H8/300, @command{ld} can perform these global optimizations when
4398 you specify the @samp{--relax} command-line option.
4400 @table @emph
4401 @cindex relaxing on H8/300
4402 @item relaxing address modes
4403 @command{ld} finds all @code{jsr} and @code{jmp} instructions whose
4404 targets are within eight bits, and turns them into eight-bit
4405 program-counter relative @code{bsr} and @code{bra} instructions,
4406 respectively.
4408 @cindex synthesizing on H8/300
4409 @item synthesizing instructions
4410 @c FIXME: specifically mov.b, or any mov instructions really?
4411 @command{ld} finds all @code{mov.b} instructions which use the
4412 sixteen-bit absolute address form, but refer to the top
4413 page of memory, and changes them to use the eight-bit address form.
4414 (That is: the linker turns @samp{mov.b @code{@@}@var{aa}:16} into
4415 @samp{mov.b @code{@@}@var{aa}:8} whenever the address @var{aa} is in the
4416 top page of memory).
4417 @end table
4419 @ifclear GENERIC
4420 @lowersections
4421 @end ifclear
4422 @end ifset
4424 @ifclear GENERIC
4425 @ifset Hitachi
4426 @c This stuff is pointless to say unless you're especially concerned
4427 @c with Hitachi chips; don't enable it for generic case, please.
4428 @node Hitachi
4429 @chapter @command{ld} and other Hitachi chips
4431 @command{ld} also supports the H8/300H, the H8/500, and the Hitachi SH.  No
4432 special features, commands, or command-line options are required for
4433 these chips.
4434 @end ifset
4435 @end ifclear
4437 @ifset I960
4438 @ifclear GENERIC
4439 @raisesections
4440 @end ifclear
4442 @node i960
4443 @section @command{ld} and the Intel 960 family
4445 @cindex i960 support
4447 You can use the @samp{-A@var{architecture}} command line option to
4448 specify one of the two-letter names identifying members of the 960
4449 family; the option specifies the desired output target, and warns of any
4450 incompatible instructions in the input files.  It also modifies the
4451 linker's search strategy for archive libraries, to support the use of
4452 libraries specific to each particular architecture, by including in the
4453 search loop names suffixed with the string identifying the architecture.
4455 For example, if your @command{ld} command line included @w{@samp{-ACA}} as
4456 well as @w{@samp{-ltry}}, the linker would look (in its built-in search
4457 paths, and in any paths you specify with @samp{-L}) for a library with
4458 the names
4460 @smallexample
4461 @group
4463 libtry.a
4464 tryca
4465 libtryca.a
4466 @end group
4467 @end smallexample
4469 @noindent
4470 The first two possibilities would be considered in any event; the last
4471 two are due to the use of @w{@samp{-ACA}}.
4473 You can meaningfully use @samp{-A} more than once on a command line, since
4474 the 960 architecture family allows combination of target architectures; each
4475 use will add another pair of name variants to search for when @w{@samp{-l}}
4476 specifies a library.
4478 @cindex @option{--relax} on i960
4479 @cindex relaxing on i960
4480 @command{ld} supports the @samp{--relax} option for the i960 family.  If
4481 you specify @samp{--relax}, @command{ld} finds all @code{balx} and
4482 @code{calx} instructions whose targets are within 24 bits, and turns
4483 them into 24-bit program-counter relative @code{bal} and @code{cal}
4484 instructions, respectively.  @command{ld} also turns @code{cal}
4485 instructions into @code{bal} instructions when it determines that the
4486 target subroutine is a leaf routine (that is, the target subroutine does
4487 not itself call any subroutines).
4489 @ifclear GENERIC
4490 @lowersections
4491 @end ifclear
4492 @end ifset
4494 @ifclear GENERIC
4495 @raisesections
4496 @end ifclear
4498 @node ARM
4499 @section @command{ld}'s support for interworking between ARM and Thumb code
4501 @cindex ARM interworking support
4502 @kindex --support-old-code
4503 For the ARM, @command{ld} will generate code stubs to allow functions calls
4504 betweem ARM and Thumb code.  These stubs only work with code that has
4505 been compiled and assembled with the @samp{-mthumb-interwork} command
4506 line option.  If it is necessary to link with old ARM object files or
4507 libraries, which have not been compiled with the -mthumb-interwork
4508 option then the @samp{--support-old-code} command line switch should be
4509 given to the linker.  This will make it generate larger stub functions
4510 which will work with non-interworking aware ARM code.  Note, however,
4511 the linker does not support generating stubs for function calls to
4512 non-interworking aware Thumb code.
4514 @cindex thumb entry point
4515 @cindex entry point, thumb
4516 @kindex --thumb-entry=@var{entry}
4517 The @samp{--thumb-entry} switch is a duplicate of the generic
4518 @samp{--entry} switch, in that it sets the program's starting address.
4519 But it also sets the bottom bit of the address, so that it can be
4520 branched to using a BX instruction, and the program will start
4521 executing in Thumb mode straight away.
4523 @node HPPA ELF32
4524 @section @command{ld} and HPPA 32-bit ELF support
4525 @cindex HPPA multiple sub-space stubs
4526 @kindex --multi-subspace
4527 When generating a shared library, @command{ld} will by default generate
4528 import stubs suitable for use with a single sub-space application.
4529 The @samp{--multi-subspace} switch causes @command{ld} to generate export
4530 stubs, and different (larger) import stubs suitable for use with
4531 multiple sub-spaces.
4533 @cindex HPPA stub grouping
4534 @kindex --stub-group-size=@var{N}
4535 Long branch stubs and import/export stubs are placed by @command{ld} in
4536 stub sections located between groups of input sections.
4537 @samp{--stub-group-size} specifies the maximum size of a group of input
4538 sections handled by one stub section.  Since branch offsets are signed,
4539 a stub section may serve two groups of input sections, one group before
4540 the stub section, and one group after it.  However, when using
4541 conditional branches that require stubs, it may be better (for branch
4542 prediction) that stub sections only serve one group of input sections.
4543 A negative value for @samp{N} chooses this scheme, ensuring that
4544 branches to stubs always use a negative offset.  Two special values of
4545 @samp{N} are recognized, @samp{1} and @samp{-1}.  These both instruct
4546 @command{ld} to automatically size input section groups for the branch types
4547 detected, with the same behaviour regarding stub placement as other
4548 positive or negative values of @samp{N} respectively.
4550 Note that @samp{--stub-group-size} does not split input sections.  A
4551 single input section larger than the group size specified will of course
4552 create a larger group (of one section).  If input sections are too
4553 large, it may not be possible for a branch to reach its stub.
4555 @ifset MMIX
4556 @node MMIX
4557 @section @code{ld} and MMIX
4558 For MMIX, there is choice of generating @code{ELF} object files or
4559 @code{mmo} object files when linking.  The simulator @code{mmix}
4560 understands the @code{mmo} format.  The binutils @code{objcopy} utility
4561 can translate between the two formats.
4563 There is one special section, the @samp{.MMIX.reg_contents} section.
4564 Contents in this section is assumed to correspond to that of global
4565 registers, and symbols referring to it are translated to special symbols,
4566 equal to registers.  In a final link, the start address of the
4567 @samp{.MMIX.reg_contents} section corresponds to the first allocated
4568 global register multiplied by 8.  Register @code{$255} is not included in
4569 this section; it is always set to the program entry, which is at the
4570 symbol @code{Main} for @code{mmo} files.
4572 Symbols with the prefix @code{__.MMIX.start.}, for example
4573 @code{__.MMIX.start..text} and @code{__.MMIX.start..data} are special;
4574 there must be only one each, even if they are local.  The default linker
4575 script uses these to set the default start address of a section.
4577 Initial and trailing multiples of zero-valued 32-bit words in a section,
4578 are left out from an mmo file.
4579 @end ifset
4581 @ifset TICOFF
4582 @node TI COFF
4583 @section @command{ld}'s support for various TI COFF versions
4584 @cindex TI COFF versions
4585 @kindex --format=@var{version}
4586 The @samp{--format} switch allows selection of one of the various
4587 TI COFF versions.  The latest of this writing is 2; versions 0 and 1 are
4588 also supported.  The TI COFF versions also vary in header byte-order
4589 format; @command{ld} will read any version or byte order, but the output
4590 header format depends on the default specified by the specific target.
4591 @end ifset
4593 @ifclear GENERIC
4594 @lowersections
4595 @end ifclear
4597 @ifclear SingleFormat
4598 @node BFD
4599 @chapter BFD
4601 @cindex back end
4602 @cindex object file management
4603 @cindex object formats available
4604 @kindex objdump -i
4605 The linker accesses object and archive files using the BFD libraries.
4606 These libraries allow the linker to use the same routines to operate on
4607 object files whatever the object file format.  A different object file
4608 format can be supported simply by creating a new BFD back end and adding
4609 it to the library.  To conserve runtime memory, however, the linker and
4610 associated tools are usually configured to support only a subset of the
4611 object file formats available.  You can use @code{objdump -i}
4612 (@pxref{objdump,,objdump,binutils.info,The GNU Binary Utilities}) to
4613 list all the formats available for your configuration.
4615 @cindex BFD requirements
4616 @cindex requirements for BFD
4617 As with most implementations, BFD is a compromise between
4618 several conflicting requirements. The major factor influencing
4619 BFD design was efficiency: any time used converting between
4620 formats is time which would not have been spent had BFD not
4621 been involved. This is partly offset by abstraction payback; since
4622 BFD simplifies applications and back ends, more time and care
4623 may be spent optimizing algorithms for a greater speed.
4625 One minor artifact of the BFD solution which you should bear in
4626 mind is the potential for information loss.  There are two places where
4627 useful information can be lost using the BFD mechanism: during
4628 conversion and during output. @xref{BFD information loss}.
4630 @menu
4631 * BFD outline::                 How it works: an outline of BFD
4632 @end menu
4634 @node BFD outline
4635 @section How it works: an outline of BFD
4636 @cindex opening object files
4637 @include bfdsumm.texi
4638 @end ifclear
4640 @node Reporting Bugs
4641 @chapter Reporting Bugs
4642 @cindex bugs in @command{ld}
4643 @cindex reporting bugs in @command{ld}
4645 Your bug reports play an essential role in making @command{ld} reliable.
4647 Reporting a bug may help you by bringing a solution to your problem, or
4648 it may not.  But in any case the principal function of a bug report is
4649 to help the entire community by making the next version of @command{ld}
4650 work better.  Bug reports are your contribution to the maintenance of
4651 @command{ld}.
4653 In order for a bug report to serve its purpose, you must include the
4654 information that enables us to fix the bug.
4656 @menu
4657 * Bug Criteria::                Have you found a bug?
4658 * Bug Reporting::               How to report bugs
4659 @end menu
4661 @node Bug Criteria
4662 @section Have you found a bug?
4663 @cindex bug criteria
4665 If you are not sure whether you have found a bug, here are some guidelines:
4667 @itemize @bullet
4668 @cindex fatal signal
4669 @cindex linker crash
4670 @cindex crash of linker
4671 @item
4672 If the linker gets a fatal signal, for any input whatever, that is a
4673 @command{ld} bug.  Reliable linkers never crash.
4675 @cindex error on valid input
4676 @item
4677 If @command{ld} produces an error message for valid input, that is a bug.
4679 @cindex invalid input
4680 @item
4681 If @command{ld} does not produce an error message for invalid input, that
4682 may be a bug.  In the general case, the linker can not verify that
4683 object files are correct.
4685 @item
4686 If you are an experienced user of linkers, your suggestions for
4687 improvement of @command{ld} are welcome in any case.
4688 @end itemize
4690 @node Bug Reporting
4691 @section How to report bugs
4692 @cindex bug reports
4693 @cindex @command{ld} bugs, reporting
4695 A number of companies and individuals offer support for @sc{gnu}
4696 products.  If you obtained @command{ld} from a support organization, we
4697 recommend you contact that organization first.
4699 You can find contact information for many support companies and
4700 individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs
4701 distribution.
4703 Otherwise, send bug reports for @command{ld} to
4704 @samp{bug-binutils@@gnu.org}.
4706 The fundamental principle of reporting bugs usefully is this:
4707 @strong{report all the facts}.  If you are not sure whether to state a
4708 fact or leave it out, state it!
4710 Often people omit facts because they think they know what causes the
4711 problem and assume that some details do not matter.  Thus, you might
4712 assume that the name of a symbol you use in an example does not
4713 matter.  Well, probably it does not, but one cannot be sure.  Perhaps
4714 the bug is a stray memory reference which happens to fetch from the
4715 location where that name is stored in memory; perhaps, if the name
4716 were different, the contents of that location would fool the linker
4717 into doing the right thing despite the bug.  Play it safe and give a
4718 specific, complete example.  That is the easiest thing for you to do,
4719 and the most helpful. 
4721 Keep in mind that the purpose of a bug report is to enable us to fix
4722 the bug if it is new to us.  Therefore, always write your bug reports
4723 on the assumption that the bug has not been reported previously.
4725 Sometimes people give a few sketchy facts and ask, ``Does this ring a
4726 bell?''  Those bug reports are useless, and we urge everyone to
4727 @emph{refuse to respond to them} except to chide the sender to report
4728 bugs properly.
4730 To enable us to fix the bug, you should include all these things:
4732 @itemize @bullet
4733 @item
4734 The version of @command{ld}.  @command{ld} announces it if you start it with
4735 the @samp{--version} argument.
4737 Without this, we will not know whether there is any point in looking for
4738 the bug in the current version of @command{ld}.
4740 @item
4741 Any patches you may have applied to the @command{ld} source, including any
4742 patches made to the @code{BFD} library.
4744 @item
4745 The type of machine you are using, and the operating system name and
4746 version number.
4748 @item
4749 What compiler (and its version) was used to compile @command{ld}---e.g.
4750 ``@code{gcc-2.7}''.
4752 @item
4753 The command arguments you gave the linker to link your example and
4754 observe the bug.  To guarantee you will not omit something important,
4755 list them all.  A copy of the Makefile (or the output from make) is
4756 sufficient.
4758 If we were to try to guess the arguments, we would probably guess wrong
4759 and then we might not encounter the bug.
4761 @item
4762 A complete input file, or set of input files, that will reproduce the
4763 bug.  It is generally most helpful to send the actual object files
4764 provided that they are reasonably small.  Say no more than 10K.  For
4765 bigger files you can either make them available by FTP or HTTP or else
4766 state that you are willing to send the object file(s) to whomever
4767 requests them.  (Note - your email will be going to a mailing list, so
4768 we do not want to clog it up with large attachments).  But small
4769 attachments are best.
4771 If the source files were assembled using @code{gas} or compiled using
4772 @code{gcc}, then it may be OK to send the source files rather than the
4773 object files.  In this case, be sure to say exactly what version of
4774 @code{gas} or @code{gcc} was used to produce the object files.  Also say
4775 how @code{gas} or @code{gcc} were configured.
4777 @item
4778 A description of what behavior you observe that you believe is
4779 incorrect.  For example, ``It gets a fatal signal.''
4781 Of course, if the bug is that @command{ld} gets a fatal signal, then we
4782 will certainly notice it.  But if the bug is incorrect output, we might
4783 not notice unless it is glaringly wrong.  You might as well not give us
4784 a chance to make a mistake.
4786 Even if the problem you experience is a fatal signal, you should still
4787 say so explicitly.  Suppose something strange is going on, such as, your
4788 copy of @command{ld} is out of synch, or you have encountered a bug in the
4789 C library on your system.  (This has happened!)  Your copy might crash
4790 and ours would not.  If you told us to expect a crash, then when ours
4791 fails to crash, we would know that the bug was not happening for us.  If
4792 you had not told us to expect a crash, then we would not be able to draw
4793 any conclusion from our observations.
4795 @item
4796 If you wish to suggest changes to the @command{ld} source, send us context
4797 diffs, as generated by @code{diff} with the @samp{-u}, @samp{-c}, or
4798 @samp{-p} option.  Always send diffs from the old file to the new file.
4799 If you even discuss something in the @command{ld} source, refer to it by
4800 context, not by line number.
4802 The line numbers in our development sources will not match those in your
4803 sources.  Your line numbers would convey no useful information to us.
4804 @end itemize
4806 Here are some things that are not necessary:
4808 @itemize @bullet
4809 @item
4810 A description of the envelope of the bug.
4812 Often people who encounter a bug spend a lot of time investigating
4813 which changes to the input file will make the bug go away and which
4814 changes will not affect it.
4816 This is often time consuming and not very useful, because the way we
4817 will find the bug is by running a single example under the debugger
4818 with breakpoints, not by pure deduction from a series of examples.
4819 We recommend that you save your time for something else.
4821 Of course, if you can find a simpler example to report @emph{instead}
4822 of the original one, that is a convenience for us.  Errors in the
4823 output will be easier to spot, running under the debugger will take
4824 less time, and so on.
4826 However, simplification is not vital; if you do not want to do this,
4827 report the bug anyway and send us the entire test case you used.
4829 @item
4830 A patch for the bug.
4832 A patch for the bug does help us if it is a good one.  But do not omit
4833 the necessary information, such as the test case, on the assumption that
4834 a patch is all we need.  We might see problems with your patch and decide
4835 to fix the problem another way, or we might not understand it at all.
4837 Sometimes with a program as complicated as @command{ld} it is very hard to
4838 construct an example that will make the program follow a certain path
4839 through the code.  If you do not send us the example, we will not be
4840 able to construct one, so we will not be able to verify that the bug is
4841 fixed.
4843 And if we cannot understand what bug you are trying to fix, or why your
4844 patch should be an improvement, we will not install it.  A test case will
4845 help us to understand.
4847 @item
4848 A guess about what the bug is or what it depends on.
4850 Such guesses are usually wrong.  Even we cannot guess right about such
4851 things without first using the debugger to find the facts.
4852 @end itemize
4854 @node MRI
4855 @appendix MRI Compatible Script Files
4856 @cindex MRI compatibility
4857 To aid users making the transition to @sc{gnu} @command{ld} from the MRI
4858 linker, @command{ld} can use MRI compatible linker scripts as an
4859 alternative to the more general-purpose linker scripting language
4860 described in @ref{Scripts}.  MRI compatible linker scripts have a much
4861 simpler command set than the scripting language otherwise used with
4862 @command{ld}.  @sc{gnu} @command{ld} supports the most commonly used MRI
4863 linker commands; these commands are described here.
4865 In general, MRI scripts aren't of much use with the @code{a.out} object
4866 file format, since it only has three sections and MRI scripts lack some
4867 features to make use of them.
4869 You can specify a file containing an MRI-compatible script using the
4870 @samp{-c} command-line option.
4872 Each command in an MRI-compatible script occupies its own line; each
4873 command line starts with the keyword that identifies the command (though
4874 blank lines are also allowed for punctuation).  If a line of an
4875 MRI-compatible script begins with an unrecognized keyword, @command{ld}
4876 issues a warning message, but continues processing the script.
4878 Lines beginning with @samp{*} are comments.
4880 You can write these commands using all upper-case letters, or all
4881 lower case; for example, @samp{chip} is the same as @samp{CHIP}.
4882 The following list shows only the upper-case form of each command.
4884 @table @code
4885 @cindex @code{ABSOLUTE} (MRI)
4886 @item ABSOLUTE @var{secname}
4887 @itemx ABSOLUTE @var{secname}, @var{secname}, @dots{} @var{secname}
4888 Normally, @command{ld} includes in the output file all sections from all
4889 the input files.  However, in an MRI-compatible script, you can use the
4890 @code{ABSOLUTE} command to restrict the sections that will be present in
4891 your output program.  If the @code{ABSOLUTE} command is used at all in a
4892 script, then only the sections named explicitly in @code{ABSOLUTE}
4893 commands will appear in the linker output.  You can still use other
4894 input sections (whatever you select on the command line, or using
4895 @code{LOAD}) to resolve addresses in the output file.
4897 @cindex @code{ALIAS} (MRI)
4898 @item ALIAS @var{out-secname}, @var{in-secname}
4899 Use this command to place the data from input section @var{in-secname}
4900 in a section called @var{out-secname} in the linker output file.
4902 @var{in-secname} may be an integer.
4904 @cindex @code{ALIGN} (MRI)
4905 @item ALIGN @var{secname} = @var{expression}
4906 Align the section called @var{secname} to @var{expression}.  The
4907 @var{expression} should be a power of two.
4909 @cindex @code{BASE} (MRI)
4910 @item BASE @var{expression}
4911 Use the value of @var{expression} as the lowest address (other than
4912 absolute addresses) in the output file.
4914 @cindex @code{CHIP} (MRI)
4915 @item CHIP @var{expression}
4916 @itemx CHIP @var{expression}, @var{expression}
4917 This command does nothing; it is accepted only for compatibility.
4919 @cindex @code{END} (MRI)
4920 @item END
4921 This command does nothing whatever; it's only accepted for compatibility.
4923 @cindex @code{FORMAT} (MRI)
4924 @item FORMAT @var{output-format}
4925 Similar to the @code{OUTPUT_FORMAT} command in the more general linker
4926 language, but restricted to one of these output formats:
4928 @enumerate
4929 @item
4930 S-records, if @var{output-format} is @samp{S}
4932 @item
4933 IEEE, if @var{output-format} is @samp{IEEE}
4935 @item
4936 COFF (the @samp{coff-m68k} variant in BFD), if @var{output-format} is
4937 @samp{COFF}
4938 @end enumerate
4940 @cindex @code{LIST} (MRI)
4941 @item LIST @var{anything}@dots{}
4942 Print (to the standard output file) a link map, as produced by the
4943 @command{ld} command-line option @samp{-M}.
4945 The keyword @code{LIST} may be followed by anything on the
4946 same line, with no change in its effect.
4948 @cindex @code{LOAD} (MRI)
4949 @item LOAD @var{filename}
4950 @itemx LOAD @var{filename}, @var{filename}, @dots{} @var{filename}
4951 Include one or more object file @var{filename} in the link; this has the
4952 same effect as specifying @var{filename} directly on the @command{ld}
4953 command line.
4955 @cindex @code{NAME} (MRI)
4956 @item NAME @var{output-name}
4957 @var{output-name} is the name for the program produced by @command{ld}; the
4958 MRI-compatible command @code{NAME} is equivalent to the command-line
4959 option @samp{-o} or the general script language command @code{OUTPUT}.
4961 @cindex @code{ORDER} (MRI)
4962 @item ORDER @var{secname}, @var{secname}, @dots{} @var{secname}
4963 @itemx ORDER @var{secname} @var{secname} @var{secname}
4964 Normally, @command{ld} orders the sections in its output file in the
4965 order in which they first appear in the input files.  In an MRI-compatible
4966 script, you can override this ordering with the @code{ORDER} command.  The
4967 sections you list with @code{ORDER} will appear first in your output
4968 file, in the order specified.
4970 @cindex @code{PUBLIC} (MRI)
4971 @item PUBLIC @var{name}=@var{expression}
4972 @itemx PUBLIC @var{name},@var{expression}
4973 @itemx PUBLIC @var{name} @var{expression}
4974 Supply a value (@var{expression}) for external symbol
4975 @var{name} used in the linker input files.
4977 @cindex @code{SECT} (MRI)
4978 @item SECT @var{secname}, @var{expression}
4979 @itemx SECT @var{secname}=@var{expression}
4980 @itemx SECT @var{secname} @var{expression}
4981 You can use any of these three forms of the @code{SECT} command to
4982 specify the start address (@var{expression}) for section @var{secname}.
4983 If you have more than one @code{SECT} statement for the same
4984 @var{secname}, only the @emph{first} sets the start address.
4985 @end table
4987 @node GNU Free Documentation License
4988 @appendix GNU Free Documentation License
4989 @cindex GNU Free Documentation License
4991                 GNU Free Documentation License
4993                    Version 1.1, March 2000
4995  Copyright (C) 2000  Free Software Foundation, Inc.
4996   59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
4998  Everyone is permitted to copy and distribute verbatim copies
4999  of this license document, but changing it is not allowed.
5002 0. PREAMBLE
5004 The purpose of this License is to make a manual, textbook, or other
5005 written document "free" in the sense of freedom: to assure everyone
5006 the effective freedom to copy and redistribute it, with or without
5007 modifying it, either commercially or noncommercially.  Secondarily,
5008 this License preserves for the author and publisher a way to get
5009 credit for their work, while not being considered responsible for
5010 modifications made by others.
5012 This License is a kind of "copyleft", which means that derivative
5013 works of the document must themselves be free in the same sense.  It
5014 complements the GNU General Public License, which is a copyleft
5015 license designed for free software.
5017 We have designed this License in order to use it for manuals for free
5018 software, because free software needs free documentation: a free
5019 program should come with manuals providing the same freedoms that the
5020 software does.  But this License is not limited to software manuals;
5021 it can be used for any textual work, regardless of subject matter or
5022 whether it is published as a printed book.  We recommend this License
5023 principally for works whose purpose is instruction or reference.
5026 1. APPLICABILITY AND DEFINITIONS
5028 This License applies to any manual or other work that contains a
5029 notice placed by the copyright holder saying it can be distributed
5030 under the terms of this License.  The "Document", below, refers to any
5031 such manual or work.  Any member of the public is a licensee, and is
5032 addressed as "you".
5034 A "Modified Version" of the Document means any work containing the
5035 Document or a portion of it, either copied verbatim, or with
5036 modifications and/or translated into another language.
5038 A "Secondary Section" is a named appendix or a front-matter section of
5039 the Document that deals exclusively with the relationship of the
5040 publishers or authors of the Document to the Document's overall subject
5041 (or to related matters) and contains nothing that could fall directly
5042 within that overall subject.  (For example, if the Document is in part a
5043 textbook of mathematics, a Secondary Section may not explain any
5044 mathematics.)  The relationship could be a matter of historical
5045 connection with the subject or with related matters, or of legal,
5046 commercial, philosophical, ethical or political position regarding
5047 them.
5049 The "Invariant Sections" are certain Secondary Sections whose titles
5050 are designated, as being those of Invariant Sections, in the notice
5051 that says that the Document is released under this License.
5053 The "Cover Texts" are certain short passages of text that are listed,
5054 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
5055 the Document is released under this License.
5057 A "Transparent" copy of the Document means a machine-readable copy,
5058 represented in a format whose specification is available to the
5059 general public, whose contents can be viewed and edited directly and
5060 straightforwardly with generic text editors or (for images composed of
5061 pixels) generic paint programs or (for drawings) some widely available
5062 drawing editor, and that is suitable for input to text formatters or
5063 for automatic translation to a variety of formats suitable for input
5064 to text formatters.  A copy made in an otherwise Transparent file
5065 format whose markup has been designed to thwart or discourage
5066 subsequent modification by readers is not Transparent.  A copy that is
5067 not "Transparent" is called "Opaque".
5069 Examples of suitable formats for Transparent copies include plain
5070 ASCII without markup, Texinfo input format, LaTeX input format, SGML
5071 or XML using a publicly available DTD, and standard-conforming simple
5072 HTML designed for human modification.  Opaque formats include
5073 PostScript, PDF, proprietary formats that can be read and edited only
5074 by proprietary word processors, SGML or XML for which the DTD and/or
5075 processing tools are not generally available, and the
5076 machine-generated HTML produced by some word processors for output
5077 purposes only.
5079 The "Title Page" means, for a printed book, the title page itself,
5080 plus such following pages as are needed to hold, legibly, the material
5081 this License requires to appear in the title page.  For works in
5082 formats which do not have any title page as such, "Title Page" means
5083 the text near the most prominent appearance of the work's title,
5084 preceding the beginning of the body of the text.
5087 2. VERBATIM COPYING
5089 You may copy and distribute the Document in any medium, either
5090 commercially or noncommercially, provided that this License, the
5091 copyright notices, and the license notice saying this License applies
5092 to the Document are reproduced in all copies, and that you add no other
5093 conditions whatsoever to those of this License.  You may not use
5094 technical measures to obstruct or control the reading or further
5095 copying of the copies you make or distribute.  However, you may accept
5096 compensation in exchange for copies.  If you distribute a large enough
5097 number of copies you must also follow the conditions in section 3.
5099 You may also lend copies, under the same conditions stated above, and
5100 you may publicly display copies.
5103 3. COPYING IN QUANTITY
5105 If you publish printed copies of the Document numbering more than 100,
5106 and the Document's license notice requires Cover Texts, you must enclose
5107 the copies in covers that carry, clearly and legibly, all these Cover
5108 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
5109 the back cover.  Both covers must also clearly and legibly identify
5110 you as the publisher of these copies.  The front cover must present
5111 the full title with all words of the title equally prominent and
5112 visible.  You may add other material on the covers in addition.
5113 Copying with changes limited to the covers, as long as they preserve
5114 the title of the Document and satisfy these conditions, can be treated
5115 as verbatim copying in other respects.
5117 If the required texts for either cover are too voluminous to fit
5118 legibly, you should put the first ones listed (as many as fit
5119 reasonably) on the actual cover, and continue the rest onto adjacent
5120 pages.
5122 If you publish or distribute Opaque copies of the Document numbering
5123 more than 100, you must either include a machine-readable Transparent
5124 copy along with each Opaque copy, or state in or with each Opaque copy
5125 a publicly-accessible computer-network location containing a complete
5126 Transparent copy of the Document, free of added material, which the
5127 general network-using public has access to download anonymously at no
5128 charge using public-standard network protocols.  If you use the latter
5129 option, you must take reasonably prudent steps, when you begin
5130 distribution of Opaque copies in quantity, to ensure that this
5131 Transparent copy will remain thus accessible at the stated location
5132 until at least one year after the last time you distribute an Opaque
5133 copy (directly or through your agents or retailers) of that edition to
5134 the public.
5136 It is requested, but not required, that you contact the authors of the
5137 Document well before redistributing any large number of copies, to give
5138 them a chance to provide you with an updated version of the Document.
5141 4. MODIFICATIONS
5143 You may copy and distribute a Modified Version of the Document under
5144 the conditions of sections 2 and 3 above, provided that you release
5145 the Modified Version under precisely this License, with the Modified
5146 Version filling the role of the Document, thus licensing distribution
5147 and modification of the Modified Version to whoever possesses a copy
5148 of it.  In addition, you must do these things in the Modified Version:
5150 A. Use in the Title Page (and on the covers, if any) a title distinct
5151    from that of the Document, and from those of previous versions
5152    (which should, if there were any, be listed in the History section
5153    of the Document).  You may use the same title as a previous version
5154    if the original publisher of that version gives permission.
5155 B. List on the Title Page, as authors, one or more persons or entities
5156    responsible for authorship of the modifications in the Modified
5157    Version, together with at least five of the principal authors of the
5158    Document (all of its principal authors, if it has less than five).
5159 C. State on the Title page the name of the publisher of the
5160    Modified Version, as the publisher.
5161 D. Preserve all the copyright notices of the Document.
5162 E. Add an appropriate copyright notice for your modifications
5163    adjacent to the other copyright notices.
5164 F. Include, immediately after the copyright notices, a license notice
5165    giving the public permission to use the Modified Version under the
5166    terms of this License, in the form shown in the Addendum below.
5167 G. Preserve in that license notice the full lists of Invariant Sections
5168    and required Cover Texts given in the Document's license notice.
5169 H. Include an unaltered copy of this License.
5170 I. Preserve the section entitled "History", and its title, and add to
5171    it an item stating at least the title, year, new authors, and
5172    publisher of the Modified Version as given on the Title Page.  If
5173    there is no section entitled "History" in the Document, create one
5174    stating the title, year, authors, and publisher of the Document as
5175    given on its Title Page, then add an item describing the Modified
5176    Version as stated in the previous sentence.
5177 J. Preserve the network location, if any, given in the Document for
5178    public access to a Transparent copy of the Document, and likewise
5179    the network locations given in the Document for previous versions
5180    it was based on.  These may be placed in the "History" section.
5181    You may omit a network location for a work that was published at
5182    least four years before the Document itself, or if the original
5183    publisher of the version it refers to gives permission.
5184 K. In any section entitled "Acknowledgements" or "Dedications",
5185    preserve the section's title, and preserve in the section all the
5186    substance and tone of each of the contributor acknowledgements
5187    and/or dedications given therein.
5188 L. Preserve all the Invariant Sections of the Document,
5189    unaltered in their text and in their titles.  Section numbers
5190    or the equivalent are not considered part of the section titles.
5191 M. Delete any section entitled "Endorsements".  Such a section
5192    may not be included in the Modified Version.
5193 N. Do not retitle any existing section as "Endorsements"
5194    or to conflict in title with any Invariant Section.
5196 If the Modified Version includes new front-matter sections or
5197 appendices that qualify as Secondary Sections and contain no material
5198 copied from the Document, you may at your option designate some or all
5199 of these sections as invariant.  To do this, add their titles to the
5200 list of Invariant Sections in the Modified Version's license notice.
5201 These titles must be distinct from any other section titles.
5203 You may add a section entitled "Endorsements", provided it contains
5204 nothing but endorsements of your Modified Version by various
5205 parties--for example, statements of peer review or that the text has
5206 been approved by an organization as the authoritative definition of a
5207 standard.
5209 You may add a passage of up to five words as a Front-Cover Text, and a
5210 passage of up to 25 words as a Back-Cover Text, to the end of the list
5211 of Cover Texts in the Modified Version.  Only one passage of
5212 Front-Cover Text and one of Back-Cover Text may be added by (or
5213 through arrangements made by) any one entity.  If the Document already
5214 includes a cover text for the same cover, previously added by you or
5215 by arrangement made by the same entity you are acting on behalf of,
5216 you may not add another; but you may replace the old one, on explicit
5217 permission from the previous publisher that added the old one.
5219 The author(s) and publisher(s) of the Document do not by this License
5220 give permission to use their names for publicity for or to assert or
5221 imply endorsement of any Modified Version.
5224 5. COMBINING DOCUMENTS
5226 You may combine the Document with other documents released under this
5227 License, under the terms defined in section 4 above for modified
5228 versions, provided that you include in the combination all of the
5229 Invariant Sections of all of the original documents, unmodified, and
5230 list them all as Invariant Sections of your combined work in its
5231 license notice.
5233 The combined work need only contain one copy of this License, and
5234 multiple identical Invariant Sections may be replaced with a single
5235 copy.  If there are multiple Invariant Sections with the same name but
5236 different contents, make the title of each such section unique by
5237 adding at the end of it, in parentheses, the name of the original
5238 author or publisher of that section if known, or else a unique number.
5239 Make the same adjustment to the section titles in the list of
5240 Invariant Sections in the license notice of the combined work.
5242 In the combination, you must combine any sections entitled "History"
5243 in the various original documents, forming one section entitled
5244 "History"; likewise combine any sections entitled "Acknowledgements",
5245 and any sections entitled "Dedications".  You must delete all sections
5246 entitled "Endorsements."
5249 6. COLLECTIONS OF DOCUMENTS
5251 You may make a collection consisting of the Document and other documents
5252 released under this License, and replace the individual copies of this
5253 License in the various documents with a single copy that is included in
5254 the collection, provided that you follow the rules of this License for
5255 verbatim copying of each of the documents in all other respects.
5257 You may extract a single document from such a collection, and distribute
5258 it individually under this License, provided you insert a copy of this
5259 License into the extracted document, and follow this License in all
5260 other respects regarding verbatim copying of that document.
5263 7. AGGREGATION WITH INDEPENDENT WORKS
5265 A compilation of the Document or its derivatives with other separate
5266 and independent documents or works, in or on a volume of a storage or
5267 distribution medium, does not as a whole count as a Modified Version
5268 of the Document, provided no compilation copyright is claimed for the
5269 compilation.  Such a compilation is called an "aggregate", and this
5270 License does not apply to the other self-contained works thus compiled
5271 with the Document, on account of their being thus compiled, if they
5272 are not themselves derivative works of the Document.
5274 If the Cover Text requirement of section 3 is applicable to these
5275 copies of the Document, then if the Document is less than one quarter
5276 of the entire aggregate, the Document's Cover Texts may be placed on
5277 covers that surround only the Document within the aggregate.
5278 Otherwise they must appear on covers around the whole aggregate.
5281 8. TRANSLATION
5283 Translation is considered a kind of modification, so you may
5284 distribute translations of the Document under the terms of section 4.
5285 Replacing Invariant Sections with translations requires special
5286 permission from their copyright holders, but you may include
5287 translations of some or all Invariant Sections in addition to the
5288 original versions of these Invariant Sections.  You may include a
5289 translation of this License provided that you also include the
5290 original English version of this License.  In case of a disagreement
5291 between the translation and the original English version of this
5292 License, the original English version will prevail.
5295 9. TERMINATION
5297 You may not copy, modify, sublicense, or distribute the Document except
5298 as expressly provided for under this License.  Any other attempt to
5299 copy, modify, sublicense or distribute the Document is void, and will
5300 automatically terminate your rights under this License.  However,
5301 parties who have received copies, or rights, from you under this
5302 License will not have their licenses terminated so long as such
5303 parties remain in full compliance.
5306 10. FUTURE REVISIONS OF THIS LICENSE
5308 The Free Software Foundation may publish new, revised versions
5309 of the GNU Free Documentation License from time to time.  Such new
5310 versions will be similar in spirit to the present version, but may
5311 differ in detail to address new problems or concerns.  See
5312 http://www.gnu.org/copyleft/.
5314 Each version of the License is given a distinguishing version number.
5315 If the Document specifies that a particular numbered version of this
5316 License "or any later version" applies to it, you have the option of
5317 following the terms and conditions either of that specified version or
5318 of any later version that has been published (not as a draft) by the
5319 Free Software Foundation.  If the Document does not specify a version
5320 number of this License, you may choose any version ever published (not
5321 as a draft) by the Free Software Foundation.
5324 ADDENDUM: How to use this License for your documents
5326 To use this License in a document you have written, include a copy of
5327 the License in the document and put the following copyright and
5328 license notices just after the title page:
5330 @smallexample
5331     Copyright (c)  YEAR  YOUR NAME.
5332     Permission is granted to copy, distribute and/or modify this document
5333     under the terms of the GNU Free Documentation License, Version 1.1
5334     or any later version published by the Free Software Foundation;
5335     with the Invariant Sections being LIST THEIR TITLES, with the
5336     Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
5337     A copy of the license is included in the section entitled "GNU
5338     Free Documentation License".
5339 @end smallexample
5341 If you have no Invariant Sections, write "with no Invariant Sections"
5342 instead of saying which ones are invariant.  If you have no
5343 Front-Cover Texts, write "no Front-Cover Texts" instead of
5344 "Front-Cover Texts being LIST"; likewise for Back-Cover Texts.
5346 If your document contains nontrivial examples of program code, we
5347 recommend releasing these examples in parallel under your choice of
5348 free software license, such as the GNU General Public License,
5349 to permit their use in free software.
5351 @node Index
5352 @unnumbered Index
5354 @printindex cp
5356 @tex
5357 % I think something like @colophon should be in texinfo.  In the
5358 % meantime:
5359 \long\def\colophon{\hbox to0pt{}\vfill
5360 \centerline{The body of this manual is set in}
5361 \centerline{\fontname\tenrm,}
5362 \centerline{with headings in {\bf\fontname\tenbf}}
5363 \centerline{and examples in {\tt\fontname\tentt}.}
5364 \centerline{{\it\fontname\tenit\/} and}
5365 \centerline{{\sl\fontname\tensl\/}}
5366 \centerline{are used for emphasis.}\vfill}
5367 \page\colophon
5368 % Blame: doc@cygnus.com, 28mar91.
5369 @end tex
5372 @contents
5373 @bye