xref: /third_party/elfutils/doc/elfutils.sgml

<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"[
<!ENTITY package "<filename>new-bu</filename>">
]>

<book>
  <title>New Binutils User's and Reference Manual</title>

  <chapter>
    <title><filename>libelf</filename> <acronym>ABI</acronym></title>

    <simpara>The <acronym>ABI</acronym> of the
    <filename>libelf</filename> implemented in the &package; package
    is following that of Sun's implementation which in turn in derived
    from the original SysVr4 implementation.  There are some
    extensions over Sun's versions, though, which makes it impossible
    to replace this implementation with Sun's.</simpara>

    <beginpage>

    <refentry xreflabel="Elf_Data" id="ElfUData">
      <refnamediv>
	<refname>Elf_Data</refname>
	<refpurpose>Descriptor for Data Buffer</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
	<synopsis>
#include &lt;libelf.h&gt;
</synopsis>
      </refsynopsisdiv>

      <refsect1>
	<title>Description</title>

	<simpara>The <structname>Elf_Data</structname> structure is as
	a descriptor for a data buffer associated with a section.
	Every data buffer is associated with a specific section (see
	<!-- xref --><structname>Elf_Scn</structname>).</simpara>

	<simpara>A data buffer is created when reading a file.  In
	this case only a single buffer is present in the section.  The
	user can add as many sections as wanted to a section and they
	can be retrieved using the <function>elf_getdata</function>
	and <function>elf_rawdata</function> functions.<!-- xref
	--></simpara>

	<simpara>The <structname>Elf_Data</structname> structure
	contains the following members:</simpara>

	<programlisting>
   void         *d_buf
   Elf_Type      d_type
   size_t        d_size
   off_t         d_off
   size_t        d_align
   unsigned int  d_version
</programlisting>

	<simpara>All of these members can be modified directly by the
	user.  They can be used to resize a section, to change its
	content or type, and many more tasks.  This is also true for
	the data read from a file.  The meaning of each member is as
	follows:</simpara>

	<variablelist>
	  <varlistentry>
	    <term><structfield>d_buf</structfield></term>
	    <listitem>
	      <simpara>The <structfield>d_buf</structfield> member is
	      the pointer to the buffer with the actual data.  When
	      the ELF file was read from a file the first and only
	      data buffer of a section is allocated by the
	      <filename>libelf</filename> library.  The user should
	      not try to resize or free this buffer.  When the user
	      adds a new data buffer to a section the associated
	      memory block is normally allocated by the user.  It is
	      important that the buffer must have a lifetime at least
	      until the ELF file is closed entirely (important when
	      the buffer is allocated on the stack).  If the buffer is
	      not allocated on the stack it is the user's
	      responsibility to free the buffer after it is not used
	      anymore.  The <structfield>d_buf</structfield> member
	      can contain a null pointer if the data buffer is
	      empty.</simpara>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><structfield>d_type</structfield></term>
	    <listitem>
	      <simpara>The <structfield>d_type</structfield>
	      determines how the data of the buffer is interpreted.
	      This type is determined from the section type and must
	      be the same for all data buffers for a section.  See
	      <!-- xref --><type>Elf_Type</type> for more information.
	      The <function><link linkend="elfUgetdata"
	      endterm="elfUgetdata.refname"></link></function>
	      function uses this information to convert the data of
	      the buffer between the external form and the form
	      represented to the user and back if necessary.</simpara>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><structfield>d_version</structfield></term>
	    <listitem>
	      <simpara>The <structfield>d_version</structfield>
              contains the ELF version of the file.</simpara>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><structfield>d_size</structfield></term>
	    <listitem>
	      <simpara>The <structfield>d_size</structfield> contains
              the size of the buffer in bytes.</simpara>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><structfield>d_off</structfield></term>
	    <listitem>
	      <simpara>The <structfield>d_off</structfield> is the
              offset into the section in bytes.</simpara>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term><structfield>d_align</structfield></term>
	    <listitem>
	      <simpara>The <structfield>d_align</structfield> is the
              address alignment of the section in bytes.</simpara>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </refsect1>
    </refentry>

    <beginpage>

    <refentry id="elfUgetdata">
      <refnamediv>
	<refname id="elfUgetdata.refname">elf_getdata</refname>
	<refpurpose>Get washed data of section</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
	<funcsynopsis>
	  <funcsynopsisinfo>
#include &lt;libelf.h&gt;
</funcsynopsisinfo>
	  <funcprototype>
	    <funcdef>Elf_Data *<function>elf_getdata</function></funcdef>
	    <paramdef>Elf_Scn *<parameter>scn</parameter></paramdef>
	    <paramdef>Elf_Data *<parameter>data</parameter></paramdef>
	  </funcprototype>
	</funcsynopsis>
      </refsynopsisdiv>

      <refsect1>
	<title>Description</title>

	<simpara>The <function>elf_getdata</function> function allows
	the user to retrieve the data buffers of the section
	<parameter>scn</parameter>.  There can be more than one buffer
	if the user explicitly added them.  When a file is read the
	<filename>libelf</filename> library creates exactly one data
	buffer.</simpara>

	<simpara>The first buffer in the list can be obtained by
	passing a null pointer in the parameter
	<parameter>data</parameter>.  To get the next data buffer the
	previously returned value must be passed in the
	<parameter>data</parameter> parameter.  If there are no more
	buffer left in the list a null pointer is returned.</simpara>

	<simpara>If the <parameter>data</parameter> parameter is not a
	null pointer it must be a descriptor for a buffer
	associated with the section <parameter>scn</parameter>.  If
	this is not the case a null pointer is returned.  To
	facilitate error handling <function>elf_getdata</function>
	also returns a null pointer if the <parameter>scn</parameter>
	parameter is a null pointer.</simpara>
      </refsect1>
    </refentry>

    <refentry>
      <refnamediv>
	<refname id="elfUupdate.refname">elf_update</refname>
	<refpurpose>update an ELF descriptor</refpurpose>
      </refnamediv>

      <refsynopsisdiv>
	<funcsynopsis>
	  <funcsynopsisinfo>
#include &lt;libelf.h&gt;
</funcsynopsisinfo>
	  <funcprototype>
	    <funcdef>off_t <function>elf_update</function></funcdef>
	    <paramdef>Elf *<parameter>elf</parameter></paramdef>
	    <paramdef>Elf_Cmd <parameter>cmd</parameter></paramdef>
	  </funcprototype>
	</funcsynopsis>
      </refsynopsisdiv>

      <refsect1>
	<title>Description</title>

	<simpara>The user is responsible for filling in the following
	fields in the named data structures:</simpara>

	<table>
	  <title>Fields not set by <function>elf_update</function></title>
	  <tgroup cols="3">
            <colspec colwidth="90pt">
            <colspec colwidth="110pt">
	    <thead>
	      <row>
		<entry>Data Structure</entry>
		<entry>Member</entry>
		<entry>Exception</entry>
	      </row>
	    </thead>
	    <tbody>
	      <row>
		<entry morerows="8"><type>Elfxx_Ehdr</type></entry>
		<entry>e_ident[EI_DATA]</entry>
		<entry>see below</entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>e_type</entry>
		<!-- <entry morerows="1"></entry> -->
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>e_machine</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>e_version</entry>
		<entry>see below</entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>e_entry</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>e_phoff</entry>
		<entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>e_shoff</entry>
		<entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>e_flags</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>e_shstrndx</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry morerows="7">Elfxx_Phdr</entry>
		<entry>p_type</entry>
		<entry morerows="7"></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>p_offset</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>p_vaddr</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>p_paddr</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>p_filesz</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>p_memsz</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>p_flags</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>p_align</entry>
		<entry></entry>
	      </row>

	      <row>
		<entry morerows="9">Elfxx_Shdr</entry>
		<entry>sh_name</entry>
		<entry morerows="3"></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_type</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_flags</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_addr</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_offset</entry>
		<entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_size</entry>
		<entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_link</entry>
		<!-- <entry morerows="1"></entry> -->
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_info</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_addralign</entry>
		<entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>sh_entsize</entry>
		<entry></entry>
	      </row>

	      <row>
		<entry morerows="5">Elf_Data</entry>
		<entry>d_buf</entry>
		<entry morerows="2"></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>d_type</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>d_size</entry>
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>d_off</entry>
		<entry>if <symbol>ELF_F_LAYOUT</symbol> is used</entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>d_align</entry>
		<!-- <entry morerows="1"></entry> -->
		<entry></entry>
	      </row>
	      <row>
		<entry></entry>
		<entry>d_version</entry>
		<entry></entry>
	      </row>
	    </tbody>
	  </tgroup>
	</table>

	<simpara>Two fields of the ELF header are handled in a special
	way:</simpara>

	<variablelist>
	  <varlistentry>
	    <term>e_version</term>
	    <listitem>
	      <simpara>The user can set this field to the vvalue for
	      the version to be used.  It is an error if the library
	      cannot handle this version.  If the field contains the
	      value <symbol>EV_NONE</symbol> the library will fill in
	      its own internal version.</simpara>
	    </listitem>
	  </varlistentry>

	  <varlistentry>
	    <term>e_ident[EI_DATA]</term>
	    <listitem>
	      <simpara>The user should fill in the byte ordering for
	      the file.  If the value of the field is
	      <symbol>ELFDATANONE</symbol> the library replaces it
	      with the native byte ordering for the machine.</simpara>
	    </listitem>
	  </varlistentry>
	</variablelist>
      </refsect1>
    </refentry>
  </chapter>

  <chapter>
    <title><filename>libelf</filename> Internals</title>

    <simpara>Since the binary format handling tools need constant
    attention since there are always new machines and variants
    therefore coming out it is important to have the implementation
    well documented.  Only this way extensions can be made in the
    right places and the mistakes of the past avoided.</simpara>
  </chapter>
</book>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omitag:nil
sgml-shorttag:t
End:
-->