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