Update generated files.
[binutils.git] / ld / ld.info-4
blob4b1f829b93c9513eb1bf42ebd84d23f55ef8a2d8
1 This is ld.info, produced by makeinfo version 4.0 from ./ld.texinfo.
3 START-INFO-DIR-ENTRY
4 * Ld: (ld).                       The GNU linker.
5 END-INFO-DIR-ENTRY
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.
12 \x1f
13 File: ld.info,  Node: Overlay Description,  Prev: Output Section Attributes,  Up: SECTIONS
15 Overlay description
16 -------------------
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 )]
30        {
31          SECNAME1
32            {
33              OUTPUT-SECTION-COMMAND
34              OUTPUT-SECTION-COMMAND
35              ...
36            } [:PHDR...] [=FILL]
37          SECNAME2
38            {
39              OUTPUT-SECTION-COMMAND
40              OUTPUT-SECTION-COMMAND
41              ...
42            } [:PHDR...] [=FILL]
43          ...
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
51 an `OVERLAY'.
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
59 location counter).
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
65 Commands.
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
77 section.
79    Here is an example.  Remember that this would appear inside a
80 `SECTIONS' construct.
81        OVERLAY 0x1000 : AT (0x4000)
82         {
83           .text0 { o1/*.o(.text) }
84           .text1 { o2/*.o(.text) }
85         }
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',
91 `__load_stop_text1'.
93    C code to copy overlay `.text1' into the overlay area might look
94 like the following.
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));
112 \x1f
113 File: ld.info,  Node: MEMORY,  Next: PHDRS,  Prev: SECTIONS,  Up: Scripts
115 MEMORY command
116 ==============
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
131 wish.  The syntax is:
132      MEMORY
133        {
134          NAME [(ATTR)] : ORIGIN = ORIGIN, LENGTH = LEN
135          ...
136        }
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:
154      Read-only section
157      Read/write section
160      Executable section
163      Allocatable section
166      Initialized section
169      Same as `I'
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.
198      MEMORY
199        {
200          rom (rx)  : ORIGIN = 0, LENGTH = 256K
201          ram (!rx) : org = 0x40000000, l = 4M
202        }
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.
214 \x1f
215 File: ld.info,  Node: PHDRS,  Next: VERSION,  Prev: MEMORY,  Up: Scripts
217 PHDRS Command
218 =============
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
239 ignore `PHDRS'.
241    This is the syntax of the `PHDRS' command.  The words `PHDRS',
242 `FILEHDR', `AT', and `FLAGS' are keywords.
244      PHDRS
245      {
246        NAME TYPE [ FILEHDR ] [ PHDRS ] [ AT ( ADDRESS ) ]
247              [ FLAGS ( FLAGS ) ] ;
248      }
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
261 Phdr::.
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
266 section.
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.
284 `PT_NULL' (0)
285      Indicates an unused program header.
287 `PT_LOAD' (1)
288      Indicates that this program header describes a segment to be
289      loaded from the file.
291 `PT_DYNAMIC' (2)
292      Indicates a segment where dynamic linking information can be found.
294 `PT_INTERP' (3)
295      Indicates a segment where the name of the program interpreter may
296      be found.
298 `PT_NOTE' (4)
299      Indicates a segment holding note information.
301 `PT_SHLIB' (5)
302      A reserved program header type, defined but not specified by the
303      ELF ABI.
305 `PT_PHDR' (6)
306      Indicates a segment where the program headers may be found.
308 EXPRESSION
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
316 section attribute.
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.
326      PHDRS
327      {
328        headers PT_PHDR PHDRS ;
329        interp PT_INTERP ;
330        text PT_LOAD FILEHDR PHDRS ;
331        data PT_LOAD ;
332        dynamic PT_DYNAMIC ;
333      }
334      
335      SECTIONS
336      {
337        . = SIZEOF_HEADERS;
338        .interp : { *(.interp) } :text :interp
339        .text : { *(.text) } :text
340        .rodata : { *(.rodata) } /* defaults to :text */
341        ...
342        . = . + 0x1000; /* move to a new page in memory */
343        .data : { *(.data) } :data
344        .dynamic : { *(.dynamic) } :data :dynamic
345        ...
346      }
348 \x1f
349 File: ld.info,  Node: VERSION,  Next: Expressions,  Prev: PHDRS,  Up: Scripts
351 VERSION Command
352 ===============
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
358 shared library.
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
373 library.
375    The easiest way to demonstrate the version script language is with a
376 few examples.
378      VERS_1.1 {
379          global:
380                  foo1;
381          local:
382                  old*;
383                  original*;
384                  new*;
385      };
386      
387      VERS_1.2 {
388                  foo2;
389      } VERS_1.1;
390      
391      VERS_2.0 {
392                  bar1; bar2;
393      } VERS_1.2;
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
399 shared library.
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
403 node `VERS_1.2'.
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
451 exported.
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.
484 \x1f
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
498 in expressions.
500 * Menu:
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
510 \x1f
511 File: ld.info,  Node: Constants,  Next: Symbols,  Up: Expressions
513 Constants
514 ---------
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:
525        _fourk_1 = 4K;
526        _fourk_2 = 4096;
527        _fourk_3 = 0x1000;
529 \x1f
530 File: ld.info,  Node: Symbols,  Next: Location Counter,  Prev: Constants,  Up: Expressions
532 Symbol Names
533 ------------
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:
540        "SECTION" = 9;
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.
547 \x1f
548 File: ld.info,  Node: Location Counter,  Next: Operators,  Prev: Symbols,  Up: Expressions
550 The Location Counter
551 --------------------
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.
563      SECTIONS
564      {
565        output :
566          {
567            file1(.text)
568            . = . + 1000;
569            file2(.text)
570            . += 1000;
571            file3(.text)
572          } = 0x1234;
573      }
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:
589      SECTIONS
590      {
591          . = 0x100
592          .text: {
593            *(.text)
594            . = 0x200
595          }
596          . = 0x500
597          .data: {
598            *(.data)
599            . += 0x600
600          }
601      }
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
610 section itself.
612 \x1f
613 File: ld.info,  Node: Operators,  Next: Evaluation,  Prev: Location Counter,  Up: Expressions
615 Operators
616 ---------
618    The linker recognizes the standard C set of arithmetic operators,
619 with the standard bindings and precedence levels:
620      precedence      associativity   Operators                Notes
621      (highest)
622      1               left            !  -  ~                  (1)
623      2               left            *  /  %
624      3               left            +  -
625      4               left            >>  <<
626      5               left            ==  !=  >  <  <=  >=
627      6               left            &
628      7               left            |
629      8               left            &&
630      9               left            ||
631      10              right           ? :
632      11              right           &=  +=  -=  *=  /=       (2)
633      (lowest)
634    Notes: (1) Prefix operators (2) *Note Assignments::.
636 \x1f
637 File: ld.info,  Node: Evaluation,  Next: Expression Section,  Prev: Operators,  Up: Expressions
639 Evaluation
640 ----------
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
657 allocation.
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
664 following
665      SECTIONS
666        {
667          .text 9+this_isnt_constant :
668            { *(.text) }
669        }
671 will cause the error message `non constant expression for initial
672 address'.
674 \x1f
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
701 section `.data':
702      SECTIONS
703        {
704          .data : { *(.data) _edata = ABSOLUTE(.); }
705        }
707 If `ABSOLUTE' were not used, `_edata' would be relative to the `.data'
708 section.
710 \x1f
711 File: ld.info,  Node: Builtin Functions,  Prev: Expression Section,  Up: Expressions
713 Builtin Functions
714 -----------------
716    The linker script language includes a number of builtin functions for
717 use in linker script expressions.
719 `ABSOLUTE(EXP)'
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
724      Section::.
726 `ADDR(SECTION)'
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
730      identical values:
731           SECTIONS { ...
732             .output1 :
733               {
734               start_of_output_1 = ABSOLUTE(.);
735               ...
736               }
737             .output :
738               {
739               symbol_1 = ADDR(.output1);
740               symbol_2 = start_of_output_1;
741               }
742           ... }
744 `ALIGN(EXP)'
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:
755           SECTIONS { ...
756             .data ALIGN(0x2000): {
757               *(.data)
758               variable = ALIGN(0x8000);
759             }
760           ... }
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'.
769 `BLOCK(EXP)'
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
772      output section.
774 `DEFINED(SYMBOL)'
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:
782           SECTIONS { ...
783             .text : {
784               begin = DEFINED(begin) ? begin : . ;
785               ...
786             }
787             ...
788           }
790 `LOADADDR(SECTION)'
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
794      LMA::).
796 `MAX(EXP1, EXP2)'
797      Returns the maximum of EXP1 and EXP2.
799 `MIN(EXP1, EXP2)'
800      Returns the minimum of EXP1 and EXP2.
802 `NEXT(EXP)'
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.
808 `SIZEOF(SECTION)'
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:
813           SECTIONS{ ...
814             .output {
815               .start = . ;
816               ...
817               .end = . ;
818               }
819             symbol_1 = .end - .start ;
820             symbol_2 = SIZEOF(.output);
821           ... }
823 `SIZEOF_HEADERS'
824 `sizeof_headers'
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::).
841 \x1f
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.
861 \x1f
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.
871 * Menu:
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
880 \x1f
881 File: ld.info,  Node: H8/300,  Next: i960,  Up: Machine Dependent
883 `ld' and the H8/300
884 ===================
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).
901 \x1f
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
919      try
920      libtry.a
921      tryca
922      libtryca.a
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'
930 specifies a library.
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).
940 \x1f
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
961 straight away.
963 \x1f
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
973 sub-spaces.
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.
994 \x1f
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.
1006 \x1f
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
1020 your configuration.
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
1028 greater speed.
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::.
1035 * Menu:
1037 * BFD outline::                 How it works: an outline of BFD
1039 \x1f
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.
1063 * Menu:
1065 * BFD information loss::        Information Loss
1066 * Canonical format::            The BFD canonical object-file format
1068 \x1f
1069 File: ld.info,  Node: BFD information loss,  Next: Canonical format,  Up: BFD outline
1071 Information Loss
1072 ----------------
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
1090 command language.
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.
1114 \x1f
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
1125 conversions.
1127 _files_
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.
1137 _sections_
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
1141      data structures.
1143 _symbols_
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.
1169 _relocation level_
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.
1183 _line numbers_
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).
1196 \x1f
1197 File: ld.info,  Node: Reporting Bugs,  Next: MRI,  Prev: BFD,  Up: Top
1199 Reporting Bugs
1200 **************
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.
1212 * Menu:
1214 * Bug Criteria::                Have you found a bug?
1215 * Bug Reporting::               How to report bugs