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