1<html lang="en"> 2<head> 3<title>Builtin Functions - Untitled</title> 4<meta http-equiv="Content-Type" content="text/html"> 5<meta name="description" content="Untitled"> 6<meta name="generator" content="makeinfo 4.13"> 7<link title="Top" rel="start" href="index.html#Top"> 8<link rel="up" href="Expressions.html#Expressions" title="Expressions"> 9<link rel="prev" href="Expression-Section.html#Expression-Section" title="Expression Section"> 10<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage"> 11<!-- 12This file documents the GNU linker LD 13(Sourcery CodeBench Lite 2013.11-24) 14version 2.23.52. 15 16Copyright (C) 1991-2013 Free Software Foundation, Inc. 17 18Permission is granted to copy, distribute and/or modify this document 19under the terms of the GNU Free Documentation License, Version 1.3 20or any later version published by the Free Software Foundation; 21with no Invariant Sections, with no Front-Cover Texts, and with no 22Back-Cover Texts. A copy of the license is included in the 23section entitled ``GNU Free Documentation License''.--> 24<meta http-equiv="Content-Style-Type" content="text/css"> 25<style type="text/css"><!-- 26 pre.display { font-family:inherit } 27 pre.format { font-family:inherit } 28 pre.smalldisplay { font-family:inherit; font-size:smaller } 29 pre.smallformat { font-family:inherit; font-size:smaller } 30 pre.smallexample { font-size:smaller } 31 pre.smalllisp { font-size:smaller } 32 span.sc { font-variant:small-caps } 33 span.roman { font-family:serif; font-weight:normal; } 34 span.sansserif { font-family:sans-serif; font-weight:normal; } 35--></style> 36<link rel="stylesheet" type="text/css" href="../cs.css"> 37</head> 38<body> 39<div class="node"> 40<a name="Builtin-Functions"></a> 41<p> 42Previous: <a rel="previous" accesskey="p" href="Expression-Section.html#Expression-Section">Expression Section</a>, 43Up: <a rel="up" accesskey="u" href="Expressions.html#Expressions">Expressions</a> 44<hr> 45</div> 46 47<h4 class="subsection">3.10.9 Builtin Functions</h4> 48 49<p><a name="index-functions-in-expressions-542"></a>The linker script language includes a number of builtin functions for 50use in linker script expressions. 51 52 <dl> 53<dt><code>ABSOLUTE(</code><var>exp</var><code>)</code><dd><a name="index-ABSOLUTE_0028_0040var_007bexp_007d_0029-543"></a><a name="index-expression_002c-absolute-544"></a>Return the absolute (non-relocatable, as opposed to non-negative) value 54of the expression <var>exp</var>. Primarily useful to assign an absolute 55value to a symbol within a section definition, where symbol values are 56normally section relative. See <a href="Expression-Section.html#Expression-Section">Expression Section</a>. 57 58 <br><dt><code>ADDR(</code><var>section</var><code>)</code><dd><a name="index-ADDR_0028_0040var_007bsection_007d_0029-545"></a><a name="index-section-address-in-expression-546"></a>Return the address (VMA) of the named <var>section</var>. Your 59script must previously have defined the location of that section. In 60the following example, <code>start_of_output_1</code>, <code>symbol_1</code> and 61<code>symbol_2</code> are assigned equivalent values, except that 62<code>symbol_1</code> will be relative to the <code>.output1</code> section while 63the other two will be absolute: 64 <pre class="smallexample"> SECTIONS { ... 65 .output1 : 66 { 67 start_of_output_1 = ABSOLUTE(.); 68 ... 69 } 70 .output : 71 { 72 symbol_1 = ADDR(.output1); 73 symbol_2 = start_of_output_1; 74 } 75 ... } 76</pre> 77 <br><dt><code>ALIGN(</code><var>align</var><code>)</code><dt><code>ALIGN(</code><var>exp</var><code>,</code><var>align</var><code>)</code><dd><a name="index-ALIGN_0028_0040var_007balign_007d_0029-547"></a><a name="index-ALIGN_0028_0040var_007bexp_007d_002c_0040var_007balign_007d_0029-548"></a><a name="index-round-up-location-counter-549"></a><a name="index-align-location-counter-550"></a><a name="index-round-up-expression-551"></a><a name="index-align-expression-552"></a>Return the location counter (<code>.</code>) or arbitrary expression aligned 78to the next <var>align</var> boundary. The single operand <code>ALIGN</code> 79doesn't change the value of the location counter—it just does 80arithmetic on it. The two operand <code>ALIGN</code> allows an arbitrary 81expression to be aligned upwards (<code>ALIGN(</code><var>align</var><code>)</code> is 82equivalent to <code>ALIGN(., </code><var>align</var><code>)</code>). 83 84 <p>Here is an example which aligns the output <code>.data</code> section to the 85next <code>0x2000</code> byte boundary after the preceding section and sets a 86variable within the section to the next <code>0x8000</code> boundary after the 87input sections: 88 <pre class="smallexample"> SECTIONS { ... 89 .data ALIGN(0x2000): { 90 *(.data) 91 variable = ALIGN(0x8000); 92 } 93 ... } 94</pre> 95 <p class="noindent">The first use of <code>ALIGN</code> in this example specifies the location of 96a section because it is used as the optional <var>address</var> attribute of 97a section definition (see <a href="Output-Section-Address.html#Output-Section-Address">Output Section Address</a>). The second use 98of <code>ALIGN</code> is used to defines the value of a symbol. 99 100 <p>The builtin function <code>NEXT</code> is closely related to <code>ALIGN</code>. 101 102 <br><dt><code>ALIGNOF(</code><var>section</var><code>)</code><dd><a name="index-ALIGNOF_0028_0040var_007bsection_007d_0029-553"></a><a name="index-section-alignment-554"></a>Return the alignment in bytes of the named <var>section</var>, if that section has 103been allocated. If the section has not been allocated when this is 104evaluated, the linker will report an error. In the following example, 105the alignment of the <code>.output</code> section is stored as the first 106value in that section. 107 <pre class="smallexample"> SECTIONS{ ... 108 .output { 109 LONG (ALIGNOF (.output)) 110 ... 111 } 112 ... } 113</pre> 114 <br><dt><code>BLOCK(</code><var>exp</var><code>)</code><dd><a name="index-BLOCK_0028_0040var_007bexp_007d_0029-555"></a>This is a synonym for <code>ALIGN</code>, for compatibility with older linker 115scripts. It is most often seen when setting the address of an output 116section. 117 118 <br><dt><code>DATA_SEGMENT_ALIGN(</code><var>maxpagesize</var><code>, </code><var>commonpagesize</var><code>)</code><dd><a name="index-DATA_005fSEGMENT_005fALIGN_0028_0040var_007bmaxpagesize_007d_002c-_0040var_007bcommonpagesize_007d_0029-556"></a>This is equivalent to either 119 <pre class="smallexample"> (ALIGN(<var>maxpagesize</var>) + (. & (<var>maxpagesize</var> - 1))) 120</pre> 121 <p>or 122 <pre class="smallexample"> (ALIGN(<var>maxpagesize</var>) + (. & (<var>maxpagesize</var> - <var>commonpagesize</var>))) 123</pre> 124 <p class="noindent">depending on whether the latter uses fewer <var>commonpagesize</var> sized pages 125for the data segment (area between the result of this expression and 126<code>DATA_SEGMENT_END</code>) than the former or not. 127If the latter form is used, it means <var>commonpagesize</var> bytes of runtime 128memory will be saved at the expense of up to <var>commonpagesize</var> wasted 129bytes in the on-disk file. 130 131 <p>This expression can only be used directly in <code>SECTIONS</code> commands, not in 132any output section descriptions and only once in the linker script. 133<var>commonpagesize</var> should be less or equal to <var>maxpagesize</var> and should 134be the system page size the object wants to be optimized for (while still 135working on system page sizes up to <var>maxpagesize</var>). 136 137 <p class="noindent">Example: 138 <pre class="smallexample"> . = DATA_SEGMENT_ALIGN(0x10000, 0x2000); 139</pre> 140 <br><dt><code>DATA_SEGMENT_END(</code><var>exp</var><code>)</code><dd><a name="index-DATA_005fSEGMENT_005fEND_0028_0040var_007bexp_007d_0029-557"></a>This defines the end of data segment for <code>DATA_SEGMENT_ALIGN</code> 141evaluation purposes. 142 143 <pre class="smallexample"> . = DATA_SEGMENT_END(.); 144</pre> 145 <br><dt><code>DATA_SEGMENT_RELRO_END(</code><var>offset</var><code>, </code><var>exp</var><code>)</code><dd><a name="index-DATA_005fSEGMENT_005fRELRO_005fEND_0028_0040var_007boffset_007d_002c-_0040var_007bexp_007d_0029-558"></a>This defines the end of the <code>PT_GNU_RELRO</code> segment when 146‘<samp><span class="samp">-z relro</span></samp>’ option is used. Second argument is returned. 147When ‘<samp><span class="samp">-z relro</span></samp>’ option is not present, <code>DATA_SEGMENT_RELRO_END</code> 148does nothing, otherwise <code>DATA_SEGMENT_ALIGN</code> is padded so that 149<var>exp</var> + <var>offset</var> is aligned to the most commonly used page 150boundary for particular target. If present in the linker script, 151it must always come in between <code>DATA_SEGMENT_ALIGN</code> and 152<code>DATA_SEGMENT_END</code>. 153 154 <pre class="smallexample"> . = DATA_SEGMENT_RELRO_END(24, .); 155</pre> 156 <br><dt><code>DEFINED(</code><var>symbol</var><code>)</code><dd><a name="index-DEFINED_0028_0040var_007bsymbol_007d_0029-559"></a><a name="index-symbol-defaults-560"></a>Return 1 if <var>symbol</var> is in the linker global symbol table and is 157defined before the statement using DEFINED in the script, otherwise 158return 0. You can use this function to provide 159default values for symbols. For example, the following script fragment 160shows how to set a global symbol ‘<samp><span class="samp">begin</span></samp>’ to the first location in 161the ‘<samp><span class="samp">.text</span></samp>’ section—but if a symbol called ‘<samp><span class="samp">begin</span></samp>’ already 162existed, its value is preserved: 163 164 <pre class="smallexample"> SECTIONS { ... 165 .text : { 166 begin = DEFINED(begin) ? begin : . ; 167 ... 168 } 169 ... 170 } 171</pre> 172 <br><dt><code>LENGTH(</code><var>memory</var><code>)</code><dd><a name="index-LENGTH_0028_0040var_007bmemory_007d_0029-561"></a>Return the length of the memory region named <var>memory</var>. 173 174 <br><dt><code>LOADADDR(</code><var>section</var><code>)</code><dd><a name="index-LOADADDR_0028_0040var_007bsection_007d_0029-562"></a><a name="index-section-load-address-in-expression-563"></a>Return the absolute LMA of the named <var>section</var>. (see <a href="Output-Section-LMA.html#Output-Section-LMA">Output Section LMA</a>). 175 176 <br><dt><code>LOG2CEIL(</code><var>exp</var><code>)</code><dd><a name="index-LOG2CEIL_0028_0040var_007bexp_007d_0029-564"></a>Return the binary logarithm of <var>exp</var> rounded towards infinity. 177<code>LOG2CEIL(0)</code> returns 0. 178 179 <p><a name="index-MAX-565"></a><br><dt><code>MAX(</code><var>exp1</var><code>, </code><var>exp2</var><code>)</code><dd>Returns the maximum of <var>exp1</var> and <var>exp2</var>. 180 181 <p><a name="index-MIN-566"></a><br><dt><code>MIN(</code><var>exp1</var><code>, </code><var>exp2</var><code>)</code><dd>Returns the minimum of <var>exp1</var> and <var>exp2</var>. 182 183 <br><dt><code>NEXT(</code><var>exp</var><code>)</code><dd><a name="index-NEXT_0028_0040var_007bexp_007d_0029-567"></a><a name="index-unallocated-address_002c-next-568"></a>Return the next unallocated address that is a multiple of <var>exp</var>. 184This function is closely related to <code>ALIGN(</code><var>exp</var><code>)</code>; unless you 185use the <code>MEMORY</code> command to define discontinuous memory for the 186output file, the two functions are equivalent. 187 188 <br><dt><code>ORIGIN(</code><var>memory</var><code>)</code><dd><a name="index-ORIGIN_0028_0040var_007bmemory_007d_0029-569"></a>Return the origin of the memory region named <var>memory</var>. 189 190 <br><dt><code>SEGMENT_START(</code><var>segment</var><code>, </code><var>default</var><code>)</code><dd><a name="index-SEGMENT_005fSTART_0028_0040var_007bsegment_007d_002c-_0040var_007bdefault_007d_0029-570"></a>Return the base address of the named <var>segment</var>. If an explicit 191value has already been given for this segment (with a command-line 192‘<samp><span class="samp">-T</span></samp>’ option) then that value will be returned otherwise the value 193will be <var>default</var>. At present, the ‘<samp><span class="samp">-T</span></samp>’ command-line option 194can only be used to set the base address for the “text”, “data”, and 195“bss” sections, but you can use <code>SEGMENT_START</code> with any segment 196name. 197 198 <br><dt><code>SIZEOF(</code><var>section</var><code>)</code><dd><a name="index-SIZEOF_0028_0040var_007bsection_007d_0029-571"></a><a name="index-section-size-572"></a>Return the size in bytes of the named <var>section</var>, if that section has 199been allocated. If the section has not been allocated when this is 200evaluated, the linker will report an error. In the following example, 201<code>symbol_1</code> and <code>symbol_2</code> are assigned identical values: 202 <pre class="smallexample"> SECTIONS{ ... 203 .output { 204 .start = . ; 205 ... 206 .end = . ; 207 } 208 symbol_1 = .end - .start ; 209 symbol_2 = SIZEOF(.output); 210 ... } 211</pre> 212 <br><dt><code>SIZEOF_HEADERS</code><dt><code>sizeof_headers</code><dd><a name="index-SIZEOF_005fHEADERS-573"></a><a name="index-header-size-574"></a>Return the size in bytes of the output file's headers. This is 213information which appears at the start of the output file. You can use 214this number when setting the start address of the first section, if you 215choose, to facilitate paging. 216 217 <p><a name="index-not-enough-room-for-program-headers-575"></a><a name="index-program-headers_002c-not-enough-room-576"></a>When producing an ELF output file, if the linker script uses the 218<code>SIZEOF_HEADERS</code> builtin function, the linker must compute the 219number of program headers before it has determined all the section 220addresses and sizes. If the linker later discovers that it needs 221additional program headers, it will report an error ‘<samp><span class="samp">not enough 222room for program headers</span></samp>’. To avoid this error, you must avoid using 223the <code>SIZEOF_HEADERS</code> function, or you must rework your linker 224script to avoid forcing the linker to use additional program headers, or 225you must define the program headers yourself using the <code>PHDRS</code> 226command (see <a href="PHDRS.html#PHDRS">PHDRS</a>). 227</dl> 228 229 </body></html> 230 231