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