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