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