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