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