RTEMS GNU Tools On-Line Library

Builtin Functions

3.10.7: Builtin Functions

The linker script language includes a number of builtin functions for use in linker script expressions.

ABSOLUTE(exp)

Return the absolute (non-relocatable, as opposed to non-negative) value of the expression exp. Primarily useful to assign an absolute value to a symbol within a section definition, where symbol values are normally section relative. See Expression Section.

ADDR(section)

Return the absolute address (the VMA) of the named section. Your script must previously have defined the location of that section. In the following example, symbol_1 and symbol_2 are assigned identical values:

SECTIONS { ...
  .output1 :
    { 
    start_of_output_1 = ABSOLUTE(.);
    ...
    }
  .output :
    {
    symbol_1 = ADDR(.output1);
    symbol_2 = start_of_output_1;
    }
... }

ALIGN(exp)

Return the location counter (.) aligned to the next exp boundary. exp must be an expression whose value is a power of two. This is equivalent to

(. + exp - 1) & ~(exp - 1)

ALIGN doesn't change the value of the location counter---it just does arithmetic on it. Here is an example which aligns the output .data section to the next 0x2000 byte boundary after the preceding section and sets a variable within the section to the next 0x8000 boundary after the input sections:

SECTIONS { ...
  .data ALIGN(0x2000): {
    *(.data)
    variable = ALIGN(0x8000);
  }
... }

The first use of ALIGN in this example specifies the location of a section because it is used as the optional address attribute of a section definition (see Output Section Address). The second use of ALIGN is used to defines the value of a symbol.

The builtin function NEXT is closely related to ALIGN.

BLOCK(exp)

This is a synonym for ALIGN, for compatibility with older linker scripts. It is most often seen when setting the address of an output section.

DEFINED(symbol)

Return 1 if symbol is in the linker global symbol table and is defined, otherwise return 0. You can use this function to provide default values for symbols. For example, the following script fragment shows how to set a global symbol `begin' to the first location in the `.text' section---but if a symbol called `begin' already existed, its value is preserved:

SECTIONS { ...
  .text : {
    begin = DEFINED(begin) ? begin : . ;
    ...
  }
  ...
}

LOADADDR(section)

Return the absolute LMA of the named section. This is normally the same as ADDR, but it may be different if the AT attribute is used in the output section definition (see Output Section LMA).

MAX(exp1, exp2)

Returns the maximum of exp1 and exp2.

MIN(exp1, exp2)

Returns the minimum of exp1 and exp2.

NEXT(exp)

Return the next unallocated address that is a multiple of exp. This function is closely related to ALIGN(exp); unless you use the MEMORY command to define discontinuous memory for the output file, the two functions are equivalent.

SIZEOF(section)

Return the size in bytes of the named section, if that section has been allocated. If the section has not been allocated when this is evaluated, the linker will report an error. In the following example, symbol_1 and symbol_2 are assigned identical values:

SECTIONS{ ...
  .output {
    .start = . ;
    ...
    .end = . ;
    }
  symbol_1 = .end - .start ;
  symbol_2 = SIZEOF(.output);
... }

SIZEOF_HEADERS

sizeof_headers

Return the size in bytes of the output file's headers. This is information which appears at the start of the output file. You can use this number when setting the start address of the first section, if you choose, to facilitate paging.

When producing an ELF output file, if the linker script uses the SIZEOF_HEADERS builtin function, the linker must compute the number of program headers before it has determined all the section addresses and sizes. If the linker later discovers that it needs additional program headers, it will report an error `not enough room for program headers'. To avoid this error, you must avoid using the SIZEOF_HEADERS function, or you must rework your linker script to avoid forcing the linker to use additional program headers, or you must define the program headers yourself using the PHDRS command (see PHDRS).