doc/elfutils.sgml

   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 &lt;libelf.h&gt;
  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 &lt;libelf.h&gt;
 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 &lt;libelf.h&gt;
 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
 439 Local variables:
 440 mode: sgml
 441 sgml-omitag:nil
 442 sgml-shorttag:t
 443 End:
 444 -->