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