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