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