ld: Builtin Functions
1
1 3.10.9 Builtin Functions
1 ------------------------
1
1 The linker script language includes a number of builtin functions for
1 use in linker script expressions.
1
1 'ABSOLUTE(EXP)'
1 Return the absolute (non-relocatable, as opposed to non-negative)
1 value of the expression EXP. Primarily useful to assign an
1 absolute value to a symbol within a section definition, where
11 symbol values are normally section relative. ⇒Expression
Section.
1
1 'ADDR(SECTION)'
1 Return the address (VMA) of the named SECTION. Your script must
1 previously have defined the location of that section. In the
1 following example, 'start_of_output_1', 'symbol_1' and 'symbol_2'
1 are assigned equivalent values, except that 'symbol_1' will be
1 relative to the '.output1' section while the other two will be
1 absolute:
1 SECTIONS { ...
1 .output1 :
1 {
1 start_of_output_1 = ABSOLUTE(.);
1 ...
1 }
1 .output :
1 {
1 symbol_1 = ADDR(.output1);
1 symbol_2 = start_of_output_1;
1 }
1 ... }
1
1 'ALIGN(ALIGN)'
1 'ALIGN(EXP,ALIGN)'
1 Return the location counter ('.') or arbitrary expression aligned
1 to the next ALIGN boundary. The single operand 'ALIGN' doesn't
1 change the value of the location counter--it just does arithmetic
1 on it. The two operand 'ALIGN' allows an arbitrary expression to
1 be aligned upwards ('ALIGN(ALIGN)' is equivalent to
1 'ALIGN(ABSOLUTE(.), ALIGN)').
1
1 Here is an example which aligns the output '.data' section to the
1 next '0x2000' byte boundary after the preceding section and sets a
1 variable within the section to the next '0x8000' boundary after the
1 input sections:
1 SECTIONS { ...
1 .data ALIGN(0x2000): {
1 *(.data)
1 variable = ALIGN(0x8000);
1 }
1 ... }
1 The first use of 'ALIGN' in this example specifies the location of
1 a section because it is used as the optional ADDRESS attribute of a
1 section definition (⇒Output Section Address). The second
1 use of 'ALIGN' is used to defines the value of a symbol.
1
1 The builtin function 'NEXT' is closely related to 'ALIGN'.
1
1 'ALIGNOF(SECTION)'
1 Return the alignment in bytes of the named SECTION, if that section
1 has been allocated. If the section has not been allocated when
1 this is evaluated, the linker will report an error. In the
1 following example, the alignment of the '.output' section is stored
1 as the first value in that section.
1 SECTIONS{ ...
1 .output {
1 LONG (ALIGNOF (.output))
1 ...
1 }
1 ... }
1
1 'BLOCK(EXP)'
1 This is a synonym for 'ALIGN', for compatibility with older linker
1 scripts. It is most often seen when setting the address of an
1 output section.
1
1 'DATA_SEGMENT_ALIGN(MAXPAGESIZE, COMMONPAGESIZE)'
1 This is equivalent to either
1 (ALIGN(MAXPAGESIZE) + (. & (MAXPAGESIZE - 1)))
1 or
1 (ALIGN(MAXPAGESIZE)
1 + ((. + COMMONPAGESIZE - 1) & (MAXPAGESIZE - COMMONPAGESIZE)))
1 depending on whether the latter uses fewer COMMONPAGESIZE sized
1 pages for the data segment (area between the result of this
1 expression and 'DATA_SEGMENT_END') than the former or not. If the
1 latter form is used, it means COMMONPAGESIZE bytes of runtime
1 memory will be saved at the expense of up to COMMONPAGESIZE wasted
1 bytes in the on-disk file.
1
1 This expression can only be used directly in 'SECTIONS' commands,
1 not in any output section descriptions and only once in the linker
1 script. COMMONPAGESIZE should be less or equal to MAXPAGESIZE and
1 should be the system page size the object wants to be optimized for
1 while still running on system page sizes up to MAXPAGESIZE. Note
1 however that '-z relro' protection will not be effective if the
1 system page size is larger than COMMONPAGESIZE.
1
1 Example:
1 . = DATA_SEGMENT_ALIGN(0x10000, 0x2000);
1
1 'DATA_SEGMENT_END(EXP)'
1 This defines the end of data segment for 'DATA_SEGMENT_ALIGN'
1 evaluation purposes.
1
1 . = DATA_SEGMENT_END(.);
1
1 'DATA_SEGMENT_RELRO_END(OFFSET, EXP)'
1 This defines the end of the 'PT_GNU_RELRO' segment when '-z relro'
1 option is used. When '-z relro' option is not present,
1 'DATA_SEGMENT_RELRO_END' does nothing, otherwise
1 'DATA_SEGMENT_ALIGN' is padded so that EXP + OFFSET is aligned to
1 the COMMONPAGESIZE argument given to 'DATA_SEGMENT_ALIGN'. If
1 present in the linker script, it must be placed between
1 'DATA_SEGMENT_ALIGN' and 'DATA_SEGMENT_END'. Evaluates to the
1 second argument plus any padding needed at the end of the
1 'PT_GNU_RELRO' segment due to section alignment.
1
1 . = DATA_SEGMENT_RELRO_END(24, .);
1
1 'DEFINED(SYMBOL)'
1 Return 1 if SYMBOL is in the linker global symbol table and is
1 defined before the statement using DEFINED in the script, otherwise
1 return 0. You can use this function to provide default values for
1 symbols. For example, the following script fragment shows how to
1 set a global symbol 'begin' to the first location in the '.text'
1 section--but if a symbol called 'begin' already existed, its value
1 is preserved:
1
1 SECTIONS { ...
1 .text : {
1 begin = DEFINED(begin) ? begin : . ;
1 ...
1 }
1 ...
1 }
1
1 'LENGTH(MEMORY)'
1 Return the length of the memory region named MEMORY.
1
1 'LOADADDR(SECTION)'
11 Return the absolute LMA of the named SECTION. (⇒Output
Section LMA).
1
1 'LOG2CEIL(EXP)'
1 Return the binary logarithm of EXP rounded towards infinity.
1 'LOG2CEIL(0)' returns 0.
1
1 'MAX(EXP1, EXP2)'
1 Returns the maximum of EXP1 and EXP2.
1
1 'MIN(EXP1, EXP2)'
1 Returns the minimum of EXP1 and EXP2.
1
1 'NEXT(EXP)'
1 Return the next unallocated address that is a multiple of EXP.
1 This function is closely related to 'ALIGN(EXP)'; unless you use
1 the 'MEMORY' command to define discontinuous memory for the output
1 file, the two functions are equivalent.
1
1 'ORIGIN(MEMORY)'
1 Return the origin of the memory region named MEMORY.
1
1 'SEGMENT_START(SEGMENT, DEFAULT)'
1 Return the base address of the named SEGMENT. If an explicit value
1 has already been given for this segment (with a command-line '-T'
1 option) then that value will be returned otherwise the value will
1 be DEFAULT. At present, the '-T' command-line option can only be
1 used to set the base address for the "text", "data", and "bss"
1 sections, but you can use 'SEGMENT_START' with any segment name.
1
1 'SIZEOF(SECTION)'
1 Return the size in bytes of the named SECTION, if that section has
1 been allocated. If the section has not been allocated when this is
1 evaluated, the linker will report an error. In the following
1 example, 'symbol_1' and 'symbol_2' are assigned identical values:
1 SECTIONS{ ...
1 .output {
1 .start = . ;
1 ...
1 .end = . ;
1 }
1 symbol_1 = .end - .start ;
1 symbol_2 = SIZEOF(.output);
1 ... }
1
1 'SIZEOF_HEADERS'
1 'sizeof_headers'
1 Return the size in bytes of the output file's headers. This is
1 information which appears at the start of the output file. You can
1 use this number when setting the start address of the first
1 section, if you choose, to facilitate paging.
1
1 When producing an ELF output file, if the linker script uses the
1 'SIZEOF_HEADERS' builtin function, the linker must compute the
1 number of program headers before it has determined all the section
1 addresses and sizes. If the linker later discovers that it needs
1 additional program headers, it will report an error 'not enough
1 room for program headers'. To avoid this error, you must avoid
1 using the 'SIZEOF_HEADERS' function, or you must rework your linker
1 script to avoid forcing the linker to use additional program
1 headers, or you must define the program headers yourself using the
1 'PHDRS' command (⇒PHDRS).
1