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