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