1 This is ld.info, produced by makeinfo version 4.0 from ./ld.texinfo.
4 * Ld: (ld). The GNU linker.
7 This file documents the GNU linker LD version 2.11.2.
9 Copyright (C) 1991, 92, 93, 94, 95, 96, 97, 98, 99, 2000 Free
10 Software Foundation, Inc.
13 File: ld.info, Node: Overlay Description, Prev: Output Section Attributes, Up: SECTIONS
18 An overlay description provides an easy way to describe sections
19 which are to be loaded as part of a single memory image but are to be
20 run at the same memory address. At run time, some sort of overlay
21 manager will copy the overlaid sections in and out of the runtime
22 memory address as required, perhaps by simply manipulating addressing
23 bits. This approach can be useful, for example, when a certain region
24 of memory is faster than another.
26 Overlays are described using the `OVERLAY' command. The `OVERLAY'
27 command is used within a `SECTIONS' command, like an output section
28 description. The full syntax of the `OVERLAY' command is as follows:
29 OVERLAY [START] : [NOCROSSREFS] [AT ( LDADDR )]
33 OUTPUT-SECTION-COMMAND
34 OUTPUT-SECTION-COMMAND
39 OUTPUT-SECTION-COMMAND
40 OUTPUT-SECTION-COMMAND
44 } [>REGION] [:PHDR...] [=FILL]
46 Everything is optional except `OVERLAY' (a keyword), and each
47 section must have a name (SECNAME1 and SECNAME2 above). The section
48 definitions within the `OVERLAY' construct are identical to those
49 within the general `SECTIONS' contruct (*note SECTIONS::), except that
50 no addresses and no memory regions may be defined for sections within
53 The sections are all defined with the same starting address. The
54 load addresses of the sections are arranged such that they are
55 consecutive in memory starting at the load address used for the
56 `OVERLAY' as a whole (as with normal section definitions, the load
57 address is optional, and defaults to the start address; the start
58 address is also optional, and defaults to the current value of the
61 If the `NOCROSSREFS' keyword is used, and there any references among
62 the sections, the linker will report an error. Since the sections all
63 run at the same address, it normally does not make sense for one
64 section to refer directly to another. *Note NOCROSSREFS: Miscellaneous
67 For each section within the `OVERLAY', the linker automatically
68 defines two symbols. The symbol `__load_start_SECNAME' is defined as
69 the starting load address of the section. The symbol
70 `__load_stop_SECNAME' is defined as the final load address of the
71 section. Any characters within SECNAME which are not legal within C
72 identifiers are removed. C (or assembler) code may use these symbols
73 to move the overlaid sections around as necessary.
75 At the end of the overlay, the value of the location counter is set
76 to the start address of the overlay plus the size of the largest
79 Here is an example. Remember that this would appear inside a
81 OVERLAY 0x1000 : AT (0x4000)
83 .text0 { o1/*.o(.text) }
84 .text1 { o2/*.o(.text) }
87 This will define both `.text0' and `.text1' to start at address 0x1000.
88 `.text0' will be loaded at address 0x4000, and `.text1' will be loaded
89 immediately after `.text0'. The following symbols will be defined:
90 `__load_start_text0', `__load_stop_text0', `__load_start_text1',
93 C code to copy overlay `.text1' into the overlay area might look
96 extern char __load_start_text1, __load_stop_text1;
97 memcpy ((char *) 0x1000, &__load_start_text1,
98 &__load_stop_text1 - &__load_start_text1);
100 Note that the `OVERLAY' command is just syntactic sugar, since
101 everything it does can be done using the more basic commands. The above
102 example could have been written identically as follows.
104 .text0 0x1000 : AT (0x4000) { o1/*.o(.text) }
105 __load_start_text0 = LOADADDR (.text0);
106 __load_stop_text0 = LOADADDR (.text0) + SIZEOF (.text0);
107 .text1 0x1000 : AT (0x4000 + SIZEOF (.text0)) { o2/*.o(.text) }
108 __load_start_text1 = LOADADDR (.text1);
109 __load_stop_text1 = LOADADDR (.text1) + SIZEOF (.text1);
110 . = 0x1000 + MAX (SIZEOF (.text0), SIZEOF (.text1));
113 File: ld.info, Node: MEMORY, Next: PHDRS, Prev: SECTIONS, Up: Scripts
118 The linker's default configuration permits allocation of all
119 available memory. You can override this by using the `MEMORY' command.
121 The `MEMORY' command describes the location and size of blocks of
122 memory in the target. You can use it to describe which memory regions
123 may be used by the linker, and which memory regions it must avoid. You
124 can then assign sections to particular memory regions. The linker will
125 set section addresses based on the memory regions, and will warn about
126 regions that become too full. The linker will not shuffle sections
127 around to fit into the available regions.
129 A linker script may contain at most one use of the `MEMORY' command.
130 However, you can define as many blocks of memory within it as you
134 NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
138 The NAME is a name used in the linker script to refer to the region.
139 The region name has no meaning outside of the linker script. Region
140 names are stored in a separate name space, and will not conflict with
141 symbol names, file names, or section names. Each memory region must
142 have a distinct name.
144 The ATTR string is an optional list of attributes that specify
145 whether to use a particular memory region for an input section which is
146 not explicitly mapped in the linker script. As described in *Note
147 SECTIONS::, if you do not specify an output section for some input
148 section, the linker will create an output section with the same name as
149 the input section. If you define region attributes, the linker will use
150 them to select the memory region for the output section that it creates.
152 The ATTR string must consist only of the following characters:
172 Invert the sense of any of the preceding attributes
174 If a unmapped section matches any of the listed attributes other than
175 `!', it will be placed in the memory region. The `!' attribute
176 reverses this test, so that an unmapped section will be placed in the
177 memory region only if it does not match any of the listed attributes.
179 The ORIGIN is an expression for the start address of the memory
180 region. The expression must evaluate to a constant before memory
181 allocation is performed, which means that you may not use any section
182 relative symbols. The keyword `ORIGIN' may be abbreviated to `org' or
183 `o' (but not, for example, `ORG').
185 The LEN is an expression for the size in bytes of the memory region.
186 As with the ORIGIN expression, the expression must evaluate to a
187 constant before memory allocation is performed. The keyword `LENGTH'
188 may be abbreviated to `len' or `l'.
190 In the following example, we specify that there are two memory
191 regions available for allocation: one starting at `0' for 256 kilobytes,
192 and the other starting at `0x40000000' for four megabytes. The linker
193 will place into the `rom' memory region every section which is not
194 explicitly mapped into a memory region, and is either read-only or
195 executable. The linker will place other sections which are not
196 explicitly mapped into a memory region into the `ram' memory region.
200 rom (rx) : ORIGIN = 0, LENGTH = 256K
201 ram (!rx) : org = 0x40000000, l = 4M
204 Once you define a memory region, you can direct the linker to place
205 specific output sections into that memory region by using the `>REGION'
206 output section attribute. For example, if you have a memory region
207 named `mem', you would use `>mem' in the output section definition.
208 *Note Output Section Region::. If no address was specified for the
209 output section, the linker will set the address to the next available
210 address within the memory region. If the combined output sections
211 directed to a memory region are too large for the region, the linker
212 will issue an error message.
215 File: ld.info, Node: PHDRS, Next: VERSION, Prev: MEMORY, Up: Scripts
220 The ELF object file format uses "program headers", also knows as
221 "segments". The program headers describe how the program should be
222 loaded into memory. You can print them out by using the `objdump'
223 program with the `-p' option.
225 When you run an ELF program on a native ELF system, the system loader
226 reads the program headers in order to figure out how to load the
227 program. This will only work if the program headers are set correctly.
228 This manual does not describe the details of how the system loader
229 interprets program headers; for more information, see the ELF ABI.
231 The linker will create reasonable program headers by default.
232 However, in some cases, you may need to specify the program headers more
233 precisely. You may use the `PHDRS' command for this purpose. When the
234 linker sees the `PHDRS' command in the linker script, it will not
235 create any program headers other than the ones specified.
237 The linker only pays attention to the `PHDRS' command when
238 generating an ELF output file. In other cases, the linker will simply
241 This is the syntax of the `PHDRS' command. The words `PHDRS',
242 `FILEHDR', `AT', and `FLAGS' are keywords.
246 NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ]
247 [ FLAGS ( FLAGS ) ] ;
250 The NAME is used only for reference in the `SECTIONS' command of the
251 linker script. It is not put into the output file. Program header
252 names are stored in a separate name space, and will not conflict with
253 symbol names, file names, or section names. Each program header must
254 have a distinct name.
256 Certain program header types describe segments of memory which the
257 system loader will load from the file. In the linker script, you
258 specify the contents of these segments by placing allocatable output
259 sections in the segments. You use the `:PHDR' output section attribute
260 to place a section in a particular segment. *Note Output Section
263 It is normal to put certain sections in more than one segment. This
264 merely implies that one segment of memory contains another. You may
265 repeat `:PHDR', using it once for each segment which should contain the
268 If you place a section in one or more segments using `:PHDR', then
269 the linker will place all subsequent allocatable sections which do not
270 specify `:PHDR' in the same segments. This is for convenience, since
271 generally a whole set of contiguous sections will be placed in a single
272 segment. You can use `:NONE' to override the default segment and tell
273 the linker to not put the section in any segment at all.
275 You may use the `FILEHDR' and `PHDRS' keywords appear after the
276 program header type to further describe the contents of the segment.
277 The `FILEHDR' keyword means that the segment should include the ELF
278 file header. The `PHDRS' keyword means that the segment should include
279 the ELF program headers themselves.
281 The TYPE may be one of the following. The numbers indicate the
282 value of the keyword.
285 Indicates an unused program header.
288 Indicates that this program header describes a segment to be
289 loaded from the file.
292 Indicates a segment where dynamic linking information can be found.
295 Indicates a segment where the name of the program interpreter may
299 Indicates a segment holding note information.
302 A reserved program header type, defined but not specified by the
306 Indicates a segment where the program headers may be found.
309 An expression giving the numeric type of the program header. This
310 may be used for types not defined above.
312 You can specify that a segment should be loaded at a particular
313 address in memory by using an `AT' expression. This is identical to the
314 `AT' command used as an output section attribute (*note Output Section
315 LMA::). The `AT' command for a program header overrides the output
318 The linker will normally set the segment flags based on the sections
319 which comprise the segment. You may use the `FLAGS' keyword to
320 explicitly specify the segment flags. The value of FLAGS must be an
321 integer. It is used to set the `p_flags' field of the program header.
323 Here is an example of `PHDRS'. This shows a typical set of program
324 headers used on a native ELF system.
328 headers PT_PHDR PHDRS ;
330 text PT_LOAD FILEHDR PHDRS ;
338 .interp : { *(.interp) } :text :interp
339 .text : { *(.text) } :text
340 .rodata : { *(.rodata) } /* defaults to :text */
342 . = . + 0x1000; /* move to a new page in memory */
343 .data : { *(.data) } :data
344 .dynamic : { *(.dynamic) } :data :dynamic
349 File: ld.info, Node: VERSION, Next: Expressions, Prev: PHDRS, Up: Scripts
354 The linker supports symbol versions when using ELF. Symbol versions
355 are only useful when using shared libraries. The dynamic linker can use
356 symbol versions to select a specific version of a function when it runs
357 a program that may have been linked against an earlier version of the
360 You can include a version script directly in the main linker script,
361 or you can supply the version script as an implicit linker script. You
362 can also use the `--version-script' linker option.
364 The syntax of the `VERSION' command is simply
365 VERSION { version-script-commands }
367 The format of the version script commands is identical to that used
368 by Sun's linker in Solaris 2.5. The version script defines a tree of
369 version nodes. You specify the node names and interdependencies in the
370 version script. You can specify which symbols are bound to which
371 version nodes, and you can reduce a specified set of symbols to local
372 scope so that they are not globally visible outside of the shared
375 The easiest way to demonstrate the version script language is with a
395 This example version script defines three version nodes. The first
396 version node defined is `VERS_1.1'; it has no other dependencies. The
397 script binds the symbol `foo1' to `VERS_1.1'. It reduces a number of
398 symbols to local scope so that they are not visible outside of the
401 Next, the version script defines node `VERS_1.2'. This node depends
402 upon `VERS_1.1'. The script binds the symbol `foo2' to the version
405 Finally, the version script defines node `VERS_2.0'. This node
406 depends upon `VERS_1.2'. The scripts binds the symbols `bar1' and
407 `bar2' are bound to the version node `VERS_2.0'.
409 When the linker finds a symbol defined in a library which is not
410 specifically bound to a version node, it will effectively bind it to an
411 unspecified base version of the library. You can bind all otherwise
412 unspecified symbols to a given version node by using `global: *'
413 somewhere in the version script.
415 The names of the version nodes have no specific meaning other than
416 what they might suggest to the person reading them. The `2.0' version
417 could just as well have appeared in between `1.1' and `1.2'. However,
418 this would be a confusing way to write a version script.
420 When you link an application against a shared library that has
421 versioned symbols, the application itself knows which version of each
422 symbol it requires, and it also knows which version nodes it needs from
423 each shared library it is linked against. Thus at runtime, the dynamic
424 loader can make a quick check to make sure that the libraries you have
425 linked against do in fact supply all of the version nodes that the
426 application will need to resolve all of the dynamic symbols. In this
427 way it is possible for the dynamic linker to know with certainty that
428 all external symbols that it needs will be resolvable without having to
429 search for each symbol reference.
431 The symbol versioning is in effect a much more sophisticated way of
432 doing minor version checking that SunOS does. The fundamental problem
433 that is being addressed here is that typically references to external
434 functions are bound on an as-needed basis, and are not all bound when
435 the application starts up. If a shared library is out of date, a
436 required interface may be missing; when the application tries to use
437 that interface, it may suddenly and unexpectedly fail. With symbol
438 versioning, the user will get a warning when they start their program if
439 the libraries being used with the application are too old.
441 There are several GNU extensions to Sun's versioning approach. The
442 first of these is the ability to bind a symbol to a version node in the
443 source file where the symbol is defined instead of in the versioning
444 script. This was done mainly to reduce the burden on the library
445 maintainer. You can do this by putting something like:
446 __asm__(".symver original_foo,foo@VERS_1.1");
448 in the C source file. This renames the function `original_foo' to be
449 an alias for `foo' bound to the version node `VERS_1.1'. The `local:'
450 directive can be used to prevent the symbol `original_foo' from being
453 The second GNU extension is to allow multiple versions of the same
454 function to appear in a given shared library. In this way you can make
455 an incompatible change to an interface without increasing the major
456 version number of the shared library, while still allowing applications
457 linked against the old interface to continue to function.
459 To do this, you must use multiple `.symver' directives in the source
460 file. Here is an example:
462 __asm__(".symver original_foo,foo@");
463 __asm__(".symver old_foo,foo@VERS_1.1");
464 __asm__(".symver old_foo1,foo@VERS_1.2");
465 __asm__(".symver new_foo,foo@@VERS_2.0");
467 In this example, `foo@' represents the symbol `foo' bound to the
468 unspecified base version of the symbol. The source file that contains
469 this example would define 4 C functions: `original_foo', `old_foo',
470 `old_foo1', and `new_foo'.
472 When you have multiple definitions of a given symbol, there needs to
473 be some way to specify a default version to which external references to
474 this symbol will be bound. You can do this with the `foo@@VERS_2.0'
475 type of `.symver' directive. You can only declare one version of a
476 symbol as the default in this manner; otherwise you would effectively
477 have multiple definitions of the same symbol.
479 If you wish to bind a reference to a specific version of the symbol
480 within the shared library, you can use the aliases of convenience (i.e.
481 `old_foo'), or you can use the `.symver' directive to specifically bind
482 to an external version of the function in question.
485 File: ld.info, Node: Expressions, Next: Implicit Linker Scripts, Prev: VERSION, Up: Scripts
487 Expressions in Linker Scripts
488 =============================
490 The syntax for expressions in the linker script language is
491 identical to that of C expressions. All expressions are evaluated as
492 integers. All expressions are evaluated in the same size, which is 32
493 bits if both the host and target are 32 bits, and is otherwise 64 bits.
495 You can use and set symbol values in expressions.
497 The linker defines several special purpose builtin functions for use
502 * Constants:: Constants
503 * Symbols:: Symbol Names
504 * Location Counter:: The Location Counter
505 * Operators:: Operators
506 * Evaluation:: Evaluation
507 * Expression Section:: The Section of an Expression
508 * Builtin Functions:: Builtin Functions
511 File: ld.info, Node: Constants, Next: Symbols, Up: Expressions
516 All constants are integers.
518 As in C, the linker considers an integer beginning with `0' to be
519 octal, and an integer beginning with `0x' or `0X' to be hexadecimal.
520 The linker considers other integers to be decimal.
522 In addition, you can use the suffixes `K' and `M' to scale a
523 constant by `1024' or `1024*1024' respectively. For example, the
524 following all refer to the same quantity:
530 File: ld.info, Node: Symbols, Next: Location Counter, Prev: Constants, Up: Expressions
535 Unless quoted, symbol names start with a letter, underscore, or
536 period and may include letters, digits, underscores, periods, and
537 hyphens. Unquoted symbol names must not conflict with any keywords.
538 You can specify a symbol which contains odd characters or has the same
539 name as a keyword by surrounding the symbol name in double quotes:
541 "with a space" = "also with a space" + 10;
543 Since symbols can contain many non-alphabetic characters, it is
544 safest to delimit symbols with spaces. For example, `A-B' is one
545 symbol, whereas `A - B' is an expression involving subtraction.
548 File: ld.info, Node: Location Counter, Next: Operators, Prev: Symbols, Up: Expressions
553 The special linker variable "dot" `.' always contains the current
554 output location counter. Since the `.' always refers to a location in
555 an output section, it may only appear in an expression within a
556 `SECTIONS' command. The `.' symbol may appear anywhere that an
557 ordinary symbol is allowed in an expression.
559 Assigning a value to `.' will cause the location counter to be
560 moved. This may be used to create holes in the output section. The
561 location counter may never be moved backwards.
575 In the previous example, the `.text' section from `file1' is located at
576 the beginning of the output section `output'. It is followed by a 1000
577 byte gap. Then the `.text' section from `file2' appears, also with a
578 1000 byte gap following before the `.text' section from `file3'. The
579 notation `= 0x1234' specifies what data to write in the gaps (*note
580 Output Section Fill::).
582 Note: `.' actually refers to the byte offset from the start of the
583 current containing object. Normally this is the `SECTIONS' statement,
584 whoes start address is 0, hence `.' can be used as an absolute address.
585 If `.' is used inside a section description however, it refers to the
586 byte offset from the start of that section, not an absolute address.
587 Thus in a script like this:
603 The `.text' section will be assigned a starting address of 0x100 and
604 a size of exactly 0x200 bytes, even if there is not enough data in the
605 `.text' input sections to fill this area. (If there is too much data,
606 an error will be produced because this would be an attempt to move `.'
607 backwards). The `.data' section will start at 0x500 and it will have
608 an extra 0x600 bytes worth of space after the end of the values from
609 the `.data' input sections and before the end of the `.data' output
613 File: ld.info, Node: Operators, Next: Evaluation, Prev: Location Counter, Up: Expressions
618 The linker recognizes the standard C set of arithmetic operators,
619 with the standard bindings and precedence levels:
620 precedence associativity Operators Notes
626 5 left == != > < <= >=
632 11 right &= += -= *= /= (2)
634 Notes: (1) Prefix operators (2) *Note Assignments::.
637 File: ld.info, Node: Evaluation, Next: Expression Section, Prev: Operators, Up: Expressions
642 The linker evaluates expressions lazily. It only computes the value
643 of an expression when absolutely necessary.
645 The linker needs some information, such as the value of the start
646 address of the first section, and the origins and lengths of memory
647 regions, in order to do any linking at all. These values are computed
648 as soon as possible when the linker reads in the linker script.
650 However, other values (such as symbol values) are not known or needed
651 until after storage allocation. Such values are evaluated later, when
652 other information (such as the sizes of output sections) is available
653 for use in the symbol assignment expression.
655 The sizes of sections cannot be known until after allocation, so
656 assignments dependent upon these are not performed until after
659 Some expressions, such as those depending upon the location counter
660 `.', must be evaluated during section allocation.
662 If the result of an expression is required, but the value is not
663 available, then an error results. For example, a script like the
667 .text 9+this_isnt_constant :
671 will cause the error message `non constant expression for initial
675 File: ld.info, Node: Expression Section, Next: Builtin Functions, Prev: Evaluation, Up: Expressions
677 The Section of an Expression
678 ----------------------------
680 When the linker evaluates an expression, the result is either
681 absolute or relative to some section. A relative expression is
682 expressed as a fixed offset from the base of a section.
684 The position of the expression within the linker script determines
685 whether it is absolute or relative. An expression which appears within
686 an output section definition is relative to the base of the output
687 section. An expression which appears elsewhere will be absolute.
689 A symbol set to a relative expression will be relocatable if you
690 request relocatable output using the `-r' option. That means that a
691 further link operation may change the value of the symbol. The symbol's
692 section will be the section of the relative expression.
694 A symbol set to an absolute expression will retain the same value
695 through any further link operation. The symbol will be absolute, and
696 will not have any particular associated section.
698 You can use the builtin function `ABSOLUTE' to force an expression
699 to be absolute when it would otherwise be relative. For example, to
700 create an absolute symbol set to the address of the end of the output
704 .data : { *(.data) _edata = ABSOLUTE(.); }
707 If `ABSOLUTE' were not used, `_edata' would be relative to the `.data'
711 File: ld.info, Node: Builtin Functions, Prev: Expression Section, Up: Expressions
716 The linker script language includes a number of builtin functions for
717 use in linker script expressions.
720 Return the absolute (non-relocatable, as opposed to non-negative)
721 value of the expression EXP. Primarily useful to assign an
722 absolute value to a symbol within a section definition, where
723 symbol values are normally section relative. *Note Expression
727 Return the absolute address (the VMA) of the named SECTION. Your
728 script must previously have defined the location of that section.
729 In the following example, `symbol_1' and `symbol_2' are assigned
734 start_of_output_1 = ABSOLUTE(.);
739 symbol_1 = ADDR(.output1);
740 symbol_2 = start_of_output_1;
745 Return the location counter (`.') aligned to the next EXP
746 boundary. EXP must be an expression whose value is a power of
747 two. This is equivalent to
748 (. + EXP - 1) & ~(EXP - 1)
750 `ALIGN' doesn't change the value of the location counter--it just
751 does arithmetic on it. Here is an example which aligns the output
752 `.data' section to the next `0x2000' byte boundary after the
753 preceding section and sets a variable within the section to the
754 next `0x8000' boundary after the input sections:
756 .data ALIGN(0x2000): {
758 variable = ALIGN(0x8000);
762 The first use of `ALIGN' in this example specifies the location of
763 a section because it is used as the optional ADDRESS attribute of
764 a section definition (*note Output Section Address::). The second
765 use of `ALIGN' is used to defines the value of a symbol.
767 The builtin function `NEXT' is closely related to `ALIGN'.
770 This is a synonym for `ALIGN', for compatibility with older linker
771 scripts. It is most often seen when setting the address of an
775 Return 1 if SYMBOL is in the linker global symbol table and is
776 defined, otherwise return 0. You can use this function to provide
777 default values for symbols. For example, the following script
778 fragment shows how to set a global symbol `begin' to the first
779 location in the `.text' section--but if a symbol called `begin'
780 already existed, its value is preserved:
784 begin = DEFINED(begin) ? begin : . ;
791 Return the absolute LMA of the named SECTION. This is normally
792 the same as `ADDR', but it may be different if the `AT' attribute
793 is used in the output section definition (*note Output Section
797 Returns the maximum of EXP1 and EXP2.
800 Returns the minimum of EXP1 and EXP2.
803 Return the next unallocated address that is a multiple of EXP.
804 This function is closely related to `ALIGN(EXP)'; unless you use
805 the `MEMORY' command to define discontinuous memory for the output
806 file, the two functions are equivalent.
809 Return the size in bytes of the named SECTION, if that section has
810 been allocated. If the section has not been allocated when this is
811 evaluated, the linker will report an error. In the following
812 example, `symbol_1' and `symbol_2' are assigned identical values:
819 symbol_1 = .end - .start ;
820 symbol_2 = SIZEOF(.output);
825 Return the size in bytes of the output file's headers. This is
826 information which appears at the start of the output file. You
827 can use this number when setting the start address of the first
828 section, if you choose, to facilitate paging.
830 When producing an ELF output file, if the linker script uses the
831 `SIZEOF_HEADERS' builtin function, the linker must compute the
832 number of program headers before it has determined all the section
833 addresses and sizes. If the linker later discovers that it needs
834 additional program headers, it will report an error `not enough
835 room for program headers'. To avoid this error, you must avoid
836 using the `SIZEOF_HEADERS' function, or you must rework your linker
837 script to avoid forcing the linker to use additional program
838 headers, or you must define the program headers yourself using the
839 `PHDRS' command (*note PHDRS::).
842 File: ld.info, Node: Implicit Linker Scripts, Prev: Expressions, Up: Scripts
844 Implicit Linker Scripts
845 =======================
847 If you specify a linker input file which the linker can not
848 recognize as an object file or an archive file, it will try to read the
849 file as a linker script. If the file can not be parsed as a linker
850 script, the linker will report an error.
852 An implicit linker script will not replace the default linker script.
854 Typically an implicit linker script would contain only symbol
855 assignments, or the `INPUT', `GROUP', or `VERSION' commands.
857 Any input files read because of an implicit linker script will be
858 read at the position in the command line where the implicit linker
859 script was read. This can affect archive searching.
862 File: ld.info, Node: Machine Dependent, Next: BFD, Prev: Scripts, Up: Top
864 Machine Dependent Features
865 **************************
867 `ld' has additional features on some platforms; the following
868 sections describe them. Machines where `ld' has no additional
869 functionality are not listed.
873 * H8/300:: `ld' and the H8/300
874 * i960:: `ld' and the Intel 960 family
875 * ARM:: `ld' and the ARM family
876 * HPPA ELF32:: `ld' and HPPA 32-bit ELF
878 * TI COFF:: `ld' and TI COFF
881 File: ld.info, Node: H8/300, Next: i960, Up: Machine Dependent
886 For the H8/300, `ld' can perform these global optimizations when you
887 specify the `--relax' command-line option.
889 _relaxing address modes_
890 `ld' finds all `jsr' and `jmp' instructions whose targets are
891 within eight bits, and turns them into eight-bit program-counter
892 relative `bsr' and `bra' instructions, respectively.
894 _synthesizing instructions_
895 `ld' finds all `mov.b' instructions which use the sixteen-bit
896 absolute address form, but refer to the top page of memory, and
897 changes them to use the eight-bit address form. (That is: the
898 linker turns `mov.b `@'AA:16' into `mov.b `@'AA:8' whenever the
899 address AA is in the top page of memory).
902 File: ld.info, Node: i960, Next: ARM, Prev: H8/300, Up: Machine Dependent
904 `ld' and the Intel 960 family
905 =============================
907 You can use the `-AARCHITECTURE' command line option to specify one
908 of the two-letter names identifying members of the 960 family; the
909 option specifies the desired output target, and warns of any
910 incompatible instructions in the input files. It also modifies the
911 linker's search strategy for archive libraries, to support the use of
912 libraries specific to each particular architecture, by including in the
913 search loop names suffixed with the string identifying the architecture.
915 For example, if your `ld' command line included `-ACA' as well as
916 `-ltry', the linker would look (in its built-in search paths, and in
917 any paths you specify with `-L') for a library with the names
924 The first two possibilities would be considered in any event; the last
925 two are due to the use of `-ACA'.
927 You can meaningfully use `-A' more than once on a command line, since
928 the 960 architecture family allows combination of target architectures;
929 each use will add another pair of name variants to search for when `-l'
932 `ld' supports the `--relax' option for the i960 family. If you
933 specify `--relax', `ld' finds all `balx' and `calx' instructions whose
934 targets are within 24 bits, and turns them into 24-bit program-counter
935 relative `bal' and `cal' instructions, respectively. `ld' also turns
936 `cal' instructions into `bal' instructions when it determines that the
937 target subroutine is a leaf routine (that is, the target subroutine does
938 not itself call any subroutines).
941 File: ld.info, Node: ARM, Next: HPPA ELF32, Prev: i960, Up: Machine Dependent
943 `ld''s support for interworking between ARM and Thumb code
944 ==========================================================
946 For the ARM, `ld' will generate code stubs to allow functions calls
947 betweem ARM and Thumb code. These stubs only work with code that has
948 been compiled and assembled with the `-mthumb-interwork' command line
949 option. If it is necessary to link with old ARM object files or
950 libraries, which have not been compiled with the -mthumb-interwork
951 option then the `--support-old-code' command line switch should be
952 given to the linker. This will make it generate larger stub functions
953 which will work with non-interworking aware ARM code. Note, however,
954 the linker does not support generating stubs for function calls to
955 non-interworking aware Thumb code.
957 The `--thumb-entry' switch is a duplicate of the generic `--entry'
958 switch, in that it sets the program's starting address. But it also
959 sets the bottom bit of the address, so that it can be branched to using
960 a BX instruction, and the program will start executing in Thumb mode
964 File: ld.info, Node: HPPA ELF32, Next: TI COFF, Prev: ARM, Up: Machine Dependent
966 `ld' and HPPA 32-bit ELF support
967 ================================
969 When generating a shared library, `ld' will by default generate
970 import stubs suitable for use with a single sub-space application. The
971 `--multi-subspace' switch causes `ld' to generate export stubs, and
972 different (larger) import stubs suitable for use with multiple
975 Long branch stubs and import/export stubs are placed by `ld' in stub
976 sections located between groups of input sections. `--stub-group-size'
977 specifies the maximum size of a group of input sections handled by one
978 stub section. Since branch offsets are signed, a stub section may
979 serve two groups of input sections, one group before the stub section,
980 and one group after it. However, when using conditional branches that
981 require stubs, it may be better (for branch prediction) that stub
982 sections only serve one group of input sections. A negative value for
983 `N' chooses this scheme, ensuring that branches to stubs always use a
984 negative offset. Two special values of `N' are recognized, `1' and
985 `-1'. These both instruct `ld' to automatically size input section
986 groups for the branch types detected, with the same behaviour regarding
987 stub placement as other positive or negative values of `N' respectively.
989 Note that `--stub-group-size' does not split input sections. A
990 single input section larger than the group size specified will of course
991 create a larger group (of one section). If input sections are too
992 large, it may not be possible for a branch to reach its stub.
995 File: ld.info, Node: TI COFF, Prev: HPPA ELF32, Up: Machine Dependent
997 `ld''s support for various TI COFF versions
998 ===========================================
1000 The `--format' switch allows selection of one of the various TI COFF
1001 versions. The latest of this writing is 2; versions 0 and 1 are also
1002 supported. The TI COFF versions also vary in header byte-order format;
1003 `ld' will read any version or byte order, but the output header format
1004 depends on the default specified by the specific target.
1007 File: ld.info, Node: BFD, Next: Reporting Bugs, Prev: Machine Dependent, Up: Top
1012 The linker accesses object and archive files using the BFD libraries.
1013 These libraries allow the linker to use the same routines to operate on
1014 object files whatever the object file format. A different object file
1015 format can be supported simply by creating a new BFD back end and adding
1016 it to the library. To conserve runtime memory, however, the linker and
1017 associated tools are usually configured to support only a subset of the
1018 object file formats available. You can use `objdump -i' (*note
1019 objdump: (binutils.info)objdump.) to list all the formats available for
1022 As with most implementations, BFD is a compromise between several
1023 conflicting requirements. The major factor influencing BFD design was
1024 efficiency: any time used converting between formats is time which
1025 would not have been spent had BFD not been involved. This is partly
1026 offset by abstraction payback; since BFD simplifies applications and
1027 back ends, more time and care may be spent optimizing algorithms for a
1030 One minor artifact of the BFD solution which you should bear in mind
1031 is the potential for information loss. There are two places where
1032 useful information can be lost using the BFD mechanism: during
1033 conversion and during output. *Note BFD information loss::.
1037 * BFD outline:: How it works: an outline of BFD
1040 File: ld.info, Node: BFD outline, Up: BFD
1042 How it works: an outline of BFD
1043 ===============================
1045 When an object file is opened, BFD subroutines automatically
1046 determine the format of the input object file. They then build a
1047 descriptor in memory with pointers to routines that will be used to
1048 access elements of the object file's data structures.
1050 As different information from the the object files is required, BFD
1051 reads from different sections of the file and processes them. For
1052 example, a very common operation for the linker is processing symbol
1053 tables. Each BFD back end provides a routine for converting between
1054 the object file's representation of symbols and an internal canonical
1055 format. When the linker asks for the symbol table of an object file, it
1056 calls through a memory pointer to the routine from the relevant BFD
1057 back end which reads and converts the table into a canonical form. The
1058 linker then operates upon the canonical form. When the link is finished
1059 and the linker writes the output file's symbol table, another BFD back
1060 end routine is called to take the newly created symbol table and
1061 convert it into the chosen output format.
1065 * BFD information loss:: Information Loss
1066 * Canonical format:: The BFD canonical object-file format
1069 File: ld.info, Node: BFD information loss, Next: Canonical format, Up: BFD outline
1074 _Information can be lost during output._ The output formats
1075 supported by BFD do not provide identical facilities, and information
1076 which can be described in one form has nowhere to go in another format.
1077 One example of this is alignment information in `b.out'. There is
1078 nowhere in an `a.out' format file to store alignment information on the
1079 contained data, so when a file is linked from `b.out' and an `a.out'
1080 image is produced, alignment information will not propagate to the
1081 output file. (The linker will still use the alignment information
1082 internally, so the link is performed correctly).
1084 Another example is COFF section names. COFF files may contain an
1085 unlimited number of sections, each one with a textual section name. If
1086 the target of the link is a format which does not have many sections
1087 (e.g., `a.out') or has sections without names (e.g., the Oasys format),
1088 the link cannot be done simply. You can circumvent this problem by
1089 describing the desired input-to-output section mapping with the linker
1092 _Information can be lost during canonicalization._ The BFD internal
1093 canonical form of the external formats is not exhaustive; there are
1094 structures in input formats for which there is no direct representation
1095 internally. This means that the BFD back ends cannot maintain all
1096 possible data richness through the transformation between external to
1097 internal and back to external formats.
1099 This limitation is only a problem when an application reads one
1100 format and writes another. Each BFD back end is responsible for
1101 maintaining as much data as possible, and the internal BFD canonical
1102 form has structures which are opaque to the BFD core, and exported only
1103 to the back ends. When a file is read in one format, the canonical form
1104 is generated for BFD and the application. At the same time, the back
1105 end saves away any information which may otherwise be lost. If the data
1106 is then written back in the same format, the back end routine will be
1107 able to use the canonical form provided by the BFD core as well as the
1108 information it prepared earlier. Since there is a great deal of
1109 commonality between back ends, there is no information lost when
1110 linking or copying big endian COFF to little endian COFF, or `a.out' to
1111 `b.out'. When a mixture of formats is linked, the information is only
1112 lost from the files whose format differs from the destination.
1115 File: ld.info, Node: Canonical format, Prev: BFD information loss, Up: BFD outline
1117 The BFD canonical object-file format
1118 ------------------------------------
1120 The greatest potential for loss of information occurs when there is
1121 the least overlap between the information provided by the source
1122 format, that stored by the canonical format, and that needed by the
1123 destination format. A brief description of the canonical form may help
1124 you understand which kinds of data you can count on preserving across
1128 Information stored on a per-file basis includes target machine
1129 architecture, particular implementation format type, a demand
1130 pageable bit, and a write protected bit. Information like Unix
1131 magic numbers is not stored here--only the magic numbers' meaning,
1132 so a `ZMAGIC' file would have both the demand pageable bit and the
1133 write protected text bit set. The byte order of the target is
1134 stored on a per-file basis, so that big- and little-endian object
1135 files may be used with one another.
1138 Each section in the input file contains the name of the section,
1139 the section's original address in the object file, size and
1140 alignment information, various flags, and pointers into other BFD
1144 Each symbol contains a pointer to the information for the object
1145 file which originally defined it, its name, its value, and various
1146 flag bits. When a BFD back end reads in a symbol table, it
1147 relocates all symbols to make them relative to the base of the
1148 section where they were defined. Doing this ensures that each
1149 symbol points to its containing section. Each symbol also has a
1150 varying amount of hidden private data for the BFD back end. Since
1151 the symbol points to the original file, the private data format
1152 for that symbol is accessible. `ld' can operate on a collection
1153 of symbols of wildly different formats without problems.
1155 Normal global and simple local symbols are maintained on output,
1156 so an output file (no matter its format) will retain symbols
1157 pointing to functions and to global, static, and common variables.
1158 Some symbol information is not worth retaining; in `a.out', type
1159 information is stored in the symbol table as long symbol names.
1160 This information would be useless to most COFF debuggers; the
1161 linker has command line switches to allow users to throw it away.
1163 There is one word of type information within the symbol, so if the
1164 format supports symbol type information within symbols (for
1165 example, COFF, IEEE, Oasys) and the type is simple enough to fit
1166 within one word (nearly everything but aggregates), the
1167 information will be preserved.
1170 Each canonical BFD relocation record contains a pointer to the
1171 symbol to relocate to, the offset of the data to relocate, the
1172 section the data is in, and a pointer to a relocation type
1173 descriptor. Relocation is performed by passing messages through
1174 the relocation type descriptor and the symbol pointer. Therefore,
1175 relocations can be performed on output data using a relocation
1176 method that is only available in one of the input formats. For
1177 instance, Oasys provides a byte relocation format. A relocation
1178 record requesting this relocation type would point indirectly to a
1179 routine to perform this, so the relocation may be performed on a
1180 byte being written to a 68k COFF file, even though 68k COFF has no
1181 such relocation type.
1184 Object formats can contain, for debugging purposes, some form of
1185 mapping between symbols, source line numbers, and addresses in the
1186 output file. These addresses have to be relocated along with the
1187 symbol information. Each symbol with an associated list of line
1188 number records points to the first record of the list. The head
1189 of a line number list consists of a pointer to the symbol, which
1190 allows finding out the address of the function whose line number
1191 is being described. The rest of the list is made up of pairs:
1192 offsets into the section and line numbers. Any format which can
1193 simply derive this information can pass it successfully between
1194 formats (COFF, IEEE and Oasys).
1197 File: ld.info, Node: Reporting Bugs, Next: MRI, Prev: BFD, Up: Top
1202 Your bug reports play an essential role in making `ld' reliable.
1204 Reporting a bug may help you by bringing a solution to your problem,
1205 or it may not. But in any case the principal function of a bug report
1206 is to help the entire community by making the next version of `ld' work
1207 better. Bug reports are your contribution to the maintenance of `ld'.
1209 In order for a bug report to serve its purpose, you must include the
1210 information that enables us to fix the bug.
1214 * Bug Criteria:: Have you found a bug?
1215 * Bug Reporting:: How to report bugs