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 of 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 more tasks. This is also true for 62 the data read from a file. The meaning of each member 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 104 <varlistentry> 105 <term><structfield>d_version</structfield></term> 106 <listitem> 107 <simpara>The <structfield>d_version</structfield> 108 contains the ELF version of the file.</simpara> 109 </listitem> 110 </varlistentry> 111 112 <varlistentry> 113 <term><structfield>d_size</structfield></term> 114 <listitem> 115 <simpara>The <structfield>d_size</structfield> contains 116 the size of the buffer in bytes.</simpara> 117 </listitem> 118 </varlistentry> 119 120 <varlistentry> 121 <term><structfield>d_off</structfield></term> 122 <listitem> 123 <simpara>The <structfield>d_off</structfield> is the 124 offset into the section in bytes.</simpara> 125 </listitem> 126 </varlistentry> 127 128 <varlistentry> 129 <term><structfield>d_align</structfield></term> 130 <listitem> 131 <simpara>The <structfield>d_align</structfield> is the 132 address alignment of the section in bytes.</simpara> 133 </listitem> 134 </varlistentry> 135 </variablelist> 136 </refsect1> 137 </refentry> 138 139 <beginpage> 140 141 <refentry id="elfUgetdata"> 142 <refnamediv> 143 <refname id="elfUgetdata.refname">elf_getdata</refname> 144 <refpurpose>Get washed data of section</refpurpose> 145 </refnamediv> 146 147 <refsynopsisdiv> 148 <funcsynopsis> 149 <funcsynopsisinfo> 150#include <libelf.h> 151</funcsynopsisinfo> 152 <funcprototype> 153 <funcdef>Elf_Data *<function>elf_getdata</function></funcdef> 154 <paramdef>Elf_Scn *<parameter>scn</parameter></paramdef> 155 <paramdef>Elf_Data *<parameter>data</parameter></paramdef> 156 </funcprototype> 157 </funcsynopsis> 158 </refsynopsisdiv> 159 160 <refsect1> 161 <title>Description</title> 162 163 <simpara>The <function>elf_getdata</function> function allows 164 the user to retrieve the data buffers of the section 165 <parameter>scn</parameter>. There can be more than one buffer 166 if the user explicitly added them. When a file is read the 167 <filename>libelf</filename> library creates exactly one data 168 buffer.</simpara> 169 170 <simpara>The first buffer in the list can be obtained by 171 passing a null pointer in the parameter 172 <parameter>data</parameter>. To get the next data buffer the 173 previously returned value must be passed in the 174 <parameter>data</parameter> parameter. If there are no more 175 buffer left in the list a null pointer is returned.</simpara> 176 177 <simpara>If the <parameter>data</parameter> parameter is not a 178 null pointer it must be a descriptor for a buffer 179 associated with the section <parameter>scn</parameter>. If 180 this is not the case a null pointer is returned. To 181 facilitate error handling <function>elf_getdata</function> 182 also returns a null pointer if the <parameter>scn</parameter> 183 parameter is a null pointer.</simpara> 184 </refsect1> 185 </refentry> 186 187 <refentry> 188 <refnamediv> 189 <refname id="elfUupdate.refname">elf_update</refname> 190 <refpurpose>update an ELF descriptor</refpurpose> 191 </refnamediv> 192 193 <refsynopsisdiv> 194 <funcsynopsis> 195 <funcsynopsisinfo> 196#include <libelf.h> 197</funcsynopsisinfo> 198 <funcprototype> 199 <funcdef>off_t <function>elf_update</function></funcdef> 200 <paramdef>Elf *<parameter>elf</parameter></paramdef> 201 <paramdef>Elf_Cmd <parameter>cmd</parameter></paramdef> 202 </funcprototype> 203 </funcsynopsis> 204 </refsynopsisdiv> 205 206 <refsect1> 207 <title>Description</title> 208 209 <simpara>The user is responsible for filling in the following 210 fields in the named data structures:</simpara> 211 212 <table> 213 <title>Fields not set by <function>elf_update</function></title> 214 <tgroup cols="3"> 215 <colspec colwidth="90pt"> 216 <colspec colwidth="110pt"> 217 <thead> 218 <row> 219 <entry>Data Structure</entry> 220 <entry>Member</entry> 221 <entry>Exception</entry> 222 </row> 223 </thead> 224 <tbody> 225 <row> 226 <entry morerows="8"><type>Elfxx_Ehdr</type></entry> 227 <entry>e_ident[EI_DATA]</entry> 228 <entry>see below</entry> 229 </row> 230 <row> 231 <entry></entry> 232 <entry>e_type</entry> 233 <!-- <entry morerows="1"></entry> --> 234 <entry></entry> 235 </row> 236 <row> 237 <entry></entry> 238 <entry>e_machine</entry> 239 <entry></entry> 240 </row> 241 <row> 242 <entry></entry> 243 <entry>e_version</entry> 244 <entry>see below</entry> 245 </row> 246 <row> 247 <entry></entry> 248 <entry>e_entry</entry> 249 <entry></entry> 250 </row> 251 <row> 252 <entry></entry> 253 <entry>e_phoff</entry> 254 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 255 </row> 256 <row> 257 <entry></entry> 258 <entry>e_shoff</entry> 259 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 260 </row> 261 <row> 262 <entry></entry> 263 <entry>e_flags</entry> 264 <entry></entry> 265 </row> 266 <row> 267 <entry></entry> 268 <entry>e_shstrndx</entry> 269 <entry></entry> 270 </row> 271 <row> 272 <entry morerows="7">Elfxx_Phdr</entry> 273 <entry>p_type</entry> 274 <entry morerows="7"></entry> 275 </row> 276 <row> 277 <entry></entry> 278 <entry>p_offset</entry> 279 <entry></entry> 280 </row> 281 <row> 282 <entry></entry> 283 <entry>p_vaddr</entry> 284 <entry></entry> 285 </row> 286 <row> 287 <entry></entry> 288 <entry>p_paddr</entry> 289 <entry></entry> 290 </row> 291 <row> 292 <entry></entry> 293 <entry>p_filesz</entry> 294 <entry></entry> 295 </row> 296 <row> 297 <entry></entry> 298 <entry>p_memsz</entry> 299 <entry></entry> 300 </row> 301 <row> 302 <entry></entry> 303 <entry>p_flags</entry> 304 <entry></entry> 305 </row> 306 <row> 307 <entry></entry> 308 <entry>p_align</entry> 309 <entry></entry> 310 </row> 311 312 <row> 313 <entry morerows="9">Elfxx_Shdr</entry> 314 <entry>sh_name</entry> 315 <entry morerows="3"></entry> 316 </row> 317 <row> 318 <entry></entry> 319 <entry>sh_type</entry> 320 <entry></entry> 321 </row> 322 <row> 323 <entry></entry> 324 <entry>sh_flags</entry> 325 <entry></entry> 326 </row> 327 <row> 328 <entry></entry> 329 <entry>sh_addr</entry> 330 <entry></entry> 331 </row> 332 <row> 333 <entry></entry> 334 <entry>sh_offset</entry> 335 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 336 </row> 337 <row> 338 <entry></entry> 339 <entry>sh_size</entry> 340 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 341 </row> 342 <row> 343 <entry></entry> 344 <entry>sh_link</entry> 345 <!-- <entry morerows="1"></entry> --> 346 <entry></entry> 347 </row> 348 <row> 349 <entry></entry> 350 <entry>sh_info</entry> 351 <entry></entry> 352 </row> 353 <row> 354 <entry></entry> 355 <entry>sh_addralign</entry> 356 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 357 </row> 358 <row> 359 <entry></entry> 360 <entry>sh_entsize</entry> 361 <entry></entry> 362 </row> 363 364 <row> 365 <entry morerows="5">Elf_Data</entry> 366 <entry>d_buf</entry> 367 <entry morerows="2"></entry> 368 </row> 369 <row> 370 <entry></entry> 371 <entry>d_type</entry> 372 <entry></entry> 373 </row> 374 <row> 375 <entry></entry> 376 <entry>d_size</entry> 377 <entry></entry> 378 </row> 379 <row> 380 <entry></entry> 381 <entry>d_off</entry> 382 <entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry> 383 </row> 384 <row> 385 <entry></entry> 386 <entry>d_align</entry> 387 <!-- <entry morerows="1"></entry> --> 388 <entry></entry> 389 </row> 390 <row> 391 <entry></entry> 392 <entry>d_version</entry> 393 <entry></entry> 394 </row> 395 </tbody> 396 </tgroup> 397 </table> 398 399 <simpara>Two fields of the ELF header are handled in a special 400 way:</simpara> 401 402 <variablelist> 403 <varlistentry> 404 <term>e_version</term> 405 <listitem> 406 <simpara>The user can set this field to the vvalue for 407 the version to be used. It is an error if the library 408 cannot handle this version. If the field contains the 409 value <symbol>EV_NONE</symbol> the library will fill in 410 its own internal version.</simpara> 411 </listitem> 412 </varlistentry> 413 414 <varlistentry> 415 <term>e_ident[EI_DATA]</term> 416 <listitem> 417 <simpara>The user should fill in the byte ordering for 418 the file. If the value of the field is 419 <symbol>ELFDATANONE</symbol> the library replaces it 420 with the native byte ordering for the machine.</simpara> 421 </listitem> 422 </varlistentry> 423 </variablelist> 424 </refsect1> 425 </refentry> 426 </chapter> 427 428 <chapter> 429 <title><filename>libelf</filename> Internals</title> 430 431 <simpara>Since the binary format handling tools need constant 432 attention since there are always new machines and varients 433 therefore coming out it is important to have the implementation 434 well documented. Only this way extensions can be made in the 435 right places and the mistakes of the past avoided.</simpara> 436 </chapter> 437</book> 438<!-- Keep this comment at the end of the file 439Local variables: 440mode: sgml 441sgml-omitag:nil 442sgml-shorttag:t 443End: 444--> 445