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