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