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