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