You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
444 lines
12 KiB
444 lines
12 KiB
<!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: |
|
-->
|
|
|