<!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 <libelf.h>
</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 <libelf.h>
</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 <libelf.h>
</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 varients
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:
-->