1<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[ 2<!ENTITY package "<filename>new-bu</filename>"> 3]> 4 5<book> 6 <title>New Binutils User's and Reference Manual</title> 7 8 <chapter> 9 <title><filename>libelf</filename> <acronym>ABI</acronym></title> 10 11 <simpara>The <acronym>ABI</acronym> of the 12 <filename>libelf</filename> implemented in the &package; package 13 is following that of Sun's implementation which in turn in derived 14 from the original SysVr4 implementation. There are some 15 extensions over Sun's versions, though, which makes it impossible 16 to replace this implementation with Sun's.</simpara> 17 18 <beginpage> 19 20 <refentry xreflabel="Elf_Data" id="ElfUData"> 21 <refnamediv> 22 <refname>Elf_Data</refname> 23 <refpurpose>Descriptor for Data Buffer</refpurpose> 24 </refnamediv> 25 26 <refsynopsisdiv> 27 <synopsis> 28#include <libelf.h> 29</synopsis> 30 </refsynopsisdiv> 31 32 <refsect1> 33 <title>Description</title> 34 35 <simpara>The <structname>Elf_Data</structname> structure is as 36 a descriptor for a data buffer associated with a section. 37 Every data buffer is associated with a specific section (see 38 <!-- xref --><structname>Elf_Scn</structname>).</simpara> 39 40 <simpara>A data buffer is created when reading a file. In 41 this case only a single buffer is present in the section. The 42 user can add as many sections as wanted to a section and they 43 can be retrieved using the <function>elf_getdata</function> 44 and <function>elf_rawdata</function> functions.<!-- xref 45 --></simpara> 46 47 <simpara>The <structname>Elf_Data</structname> structure 48 contains the following members:</simpara> 49 50 <programlisting> 51 void *d_buf 52 Elf_Type d_type 53 size_t d_size 54 off_t d_off 55 size_t d_align 56 unsigned int d_version 57</programlisting> 58 59 <simpara>All these members can be modified directly by the 60 user. They can be used to resize a section, to change its 61 content or type, and many things more. This is also true for 62 the data read from a file. The meaning of the members is as 63 follows:</simpara> 64 65 <variablelist> 66 <varlistentry> 67 <term><structfield>d_buf</structfield></term> 68 <listitem> 69 <simpara>The <structfield>d_buf</structfield> member is 70 the pointer to the buffer with the actual data. When 71 the ELF file was read from a file the first and only 72 data buffer of a section is allocated by the 73 <filename>libelf</filename> library. The user should 74 not try to resize or free this buffer. When the user 75 adds a new data buffer to a section the associated 76 memory block is normally allocated by the user. It is 77 important that the buffer must have a lifetime at least 78 until the ELF file is closed entirely (important when 79 the buffer is allocated on the stack). If the buffer is 80 not allocated on the stack it is the user's 81 responsibility to free the buffer after it is not used 82 anymore. The <structfield>d_buf</structfield> member 83 can contain a null pointer if the data buffer is 84 empty.</simpara> 85 </listitem> 86 </varlistentry> 87 88 <varlistentry> 89 <term><structfield>d_type</structfield></term> 90 <listitem> 91 <simpara>The <structfield>d_type</structfield> 92 determines how the data of the buffer is interpreted. 93 This type is determined from the section type and must 94 be the same for all data buffers for a section. See 95 <!-- xref --><type>Elf_Type</type> for more information. 96 The <function><link linkend="elfUgetdata" 97 endterm="elfUgetdata.refname"></link></function> 98 function uses this information to convert the data of 99 the buffer between the external form and the form 100 represented to the user and back if necessary.</simpara> 101 </listitem> 102 </varlistentry> 103 </variablelist> 104 </refsect1> 105 </refentry> 106 107 <beginpage> 108 109 <refentry id="elfUgetdata"> 110 <refnamediv> 111 <refname id="elfUgetdata.refname">elf_getdata</refname> 112 <refpurpose>Get washed data of section</refpurpose> 113 </refnamediv> 114 115 <refsynopsisdiv> 116 <funcsynopsis> 117 <funcsynopsisinfo> 118#include <libelf.h> 119</funcsynopsisinfo> 120 <funcprototype> 121 <funcdef>Elf_Data *<function>elf_getdata</function></funcdef> 122 <paramdef>Elf_Scn *<parameter>scn</parameter></paramdef> 123 <paramdef>Elf_Data *<parameter>data</parameter></paramdef> 124 </funcprototype> 125 </funcsynopsis> 126 </refsynopsisdiv> 127 128 <refsect1> 129 <title>Description</title> 130 131 <simpara>The <function>elf_getdata</function> function allows 132 to retriece the data buffers of the section 133 <parameter>scn</parameter>. There can be more than one buffer 134 if the user explicitly added them. When a file is read the 135 <filename>libelf</filename> library creates exactly one data 136 buffer.</simpara> 137 138 <simpara>The first buffer in the list can be obtained by 139 passing a null pointer in the parameter 140 <parameter>data</parameter>. To get the next data buffer the 141 previously returned value must be passed in the 142 <parameter>data</parameter> parameter. If there is no more 143 buffer left in the list a null pointer is returned.</simpara> 144 145 <simpara>If the <parameter>data</parameter> parameter is not a 146 null pointer it must be a descriptor with for a buffer 147 associated with the section <parameter>scn</parameter>. If 148 this is not the case a null pointer is returned. To 149 facilitate error handling <function>elf_getdata</function> 150 also returns a null pointer if the <parameter>scn</parameter> 151 parameter is a null pointer.</simpara> 152 </refsect1> 153 </refentry> 154 155 <refentry> 156 <refnamediv> 157 <refname id="elfUupdate.refname">elf_update</refname> 158 <refpurpose>update an ELF descriptor</refpurpose> 159 </refnamediv> 160 161 <refsynopsisdiv> 162 <funcsynopsis> 163 <funcsynopsisinfo> 164#include <libelf.h> 165</funcsynopsisinfo> 166 <funcprototype> 167 <funcdef>off_t <function>elf_update</function></funcdef> 168 <paramdef>Elf *<parameter>elf</parameter></paramdef> 169 <paramdef>Elf_Cmd <parameter>cmd</parameter></paramdef> 170 </funcprototype> 171 </funcsynopsis> 172 </refsynopsisdiv> 173 174 <refsect1> 175 <title>Description</title> 176 177 <simpara>The user is responsible for filling in the following 178 fields in the named data structures:</simpara> 179 180 <table> 181 <title>Fields not set by <function>elf_update</function></title> 182 <tgroup cols="3"> 183 <colspec colwidth="90pt"> 184 <colspec colwidth="110pt"> 185 <thead> 186 <row> 187 <entry>Data Structure</entry> 188 <entry>Member</entry> 189 <entry>Exception</entry> 190 </row> 191 </thead> 192 <tbody> 193 <row> 194 <entry morerows="8"><type>Elfxx_Ehdr</type></entry> 195 <entry>e_ident[EI_DATA]</entry> 196 <entry>see below</entry> 197 </row> 198 <row> 199 <entry></entry> 200 <entry>e_type</entry> 201 <!-- <entry morerows="1"></entry> --> 202 <entry></entry> 203 </row> 204 <row> 205 <entry></entry> 206 <entry>e_machine</entry> 207 <entry></entry> 208 </row> 209 <row> 210 <entry></entry> 211 <entry>e_version</entry> 212 <entry>see below</entry> 213 </row> 214 <row> 215 <entry></entry> 216 <entry>e_entry</entry> 217 <entry></entry> 218 </row> 219 <row> 220 <entry></entry> 221 <entry>e_phoff</entry> 222 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 223 </row> 224 <row> 225 <entry></entry> 226 <entry>e_shoff</entry> 227 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 228 </row> 229 <row> 230 <entry></entry> 231 <entry>e_flags</entry> 232 <entry></entry> 233 </row> 234 <row> 235 <entry></entry> 236 <entry>e_shstrndx</entry> 237 <entry></entry> 238 </row> 239 <row> 240 <entry morerows="7">Elfxx_Phdr</entry> 241 <entry>p_type</entry> 242 <entry morerows="7"></entry> 243 </row> 244 <row> 245 <entry></entry> 246 <entry>p_offset</entry> 247 <entry></entry> 248 </row> 249 <row> 250 <entry></entry> 251 <entry>p_vaddr</entry> 252 <entry></entry> 253 </row> 254 <row> 255 <entry></entry> 256 <entry>p_paddr</entry> 257 <entry></entry> 258 </row> 259 <row> 260 <entry></entry> 261 <entry>p_filesz</entry> 262 <entry></entry> 263 </row> 264 <row> 265 <entry></entry> 266 <entry>p_memsz</entry> 267 <entry></entry> 268 </row> 269 <row> 270 <entry></entry> 271 <entry>p_flags</entry> 272 <entry></entry> 273 </row> 274 <row> 275 <entry></entry> 276 <entry>p_align</entry> 277 <entry></entry> 278 </row> 279 280 <row> 281 <entry morerows="9">Elfxx_Shdr</entry> 282 <entry>sh_name</entry> 283 <entry morerows="3"></entry> 284 </row> 285 <row> 286 <entry></entry> 287 <entry>sh_type</entry> 288 <entry></entry> 289 </row> 290 <row> 291 <entry></entry> 292 <entry>sh_flags</entry> 293 <entry></entry> 294 </row> 295 <row> 296 <entry></entry> 297 <entry>sh_addr</entry> 298 <entry></entry> 299 </row> 300 <row> 301 <entry></entry> 302 <entry>sh_offset</entry> 303 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 304 </row> 305 <row> 306 <entry></entry> 307 <entry>sh_size</entry> 308 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 309 </row> 310 <row> 311 <entry></entry> 312 <entry>sh_link</entry> 313 <!-- <entry morerows="1"></entry> --> 314 <entry></entry> 315 </row> 316 <row> 317 <entry></entry> 318 <entry>sh_info</entry> 319 <entry></entry> 320 </row> 321 <row> 322 <entry></entry> 323 <entry>sh_addralign</entry> 324 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 325 </row> 326 <row> 327 <entry></entry> 328 <entry>sh_entsize</entry> 329 <entry></entry> 330 </row> 331 332 <row> 333 <entry morerows="5">Elf_Data</entry> 334 <entry>d_buf</entry> 335 <entry morerows="2"></entry> 336 </row> 337 <row> 338 <entry></entry> 339 <entry>d_type</entry> 340 <entry></entry> 341 </row> 342 <row> 343 <entry></entry> 344 <entry>d_size</entry> 345 <entry></entry> 346 </row> 347 <row> 348 <entry></entry> 349 <entry>d_off</entry> 350 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 351 </row> 352 <row> 353 <entry></entry> 354 <entry>d_align</entry> 355 <!-- <entry morerows="1"></entry> --> 356 <entry></entry> 357 </row> 358 <row> 359 <entry></entry> 360 <entry>d_version</entry> 361 <entry></entry> 362 </row> 363 </tbody> 364 </tgroup> 365 </table> 366 367 <simpara>Two fields of the ELF header are handled in a special 368 way:</simpara> 369 370 <variablelist> 371 <varlistentry> 372 <term>e_version</term> 373 <listitem> 374 <simpara>The user can set this field to the vvalue for 375 the version to be used. It is an error if the library 376 cannot handle this version. If the field contains the 377 value <symbol>EV_NONE</symbol> the library will fill in 378 its own internal version.</simpara> 379 </listitem> 380 </varlistentry> 381 382 <varlistentry> 383 <term>e_ident[EI_DATA]</term> 384 <listitem> 385 <simpara>The user should fill in the byte ordering for 386 the file. If the value of the field is 387 <symbol>ELFDATANONE</symbol> the library replaces it 388 with the native byte ordering for the machine.</simpara> 389 </listitem> 390 </varlistentry> 391 </variablelist> 392 </refsect1> 393 </refentry> 394 </chapter> 395 396 <chapter> 397 <title><filename>libelf</filename> Internals</title> 398 399 <simpara>Since the binary format handling tools need constant 400 attention since there are always new machines and varients 401 therefore coming out it is important to have the implementation 402 weel documented. Only this way extensions can be made in the 403 right places and the mistakes of the past avoided.</simpara> 404 </chapter> 405</book> 406<!-- Keep this comment at the end of the file 407Local variables: 408mode: sgml 409sgml-omitag:nil 410sgml-shorttag:t 411End: 412--> 413