<!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:
|
-->
|
