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