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