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