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