diff options
Diffstat (limited to 'doc/elfutils.sgml')
| -rw-r--r-- | doc/elfutils.sgml | 412 |
1 files changed, 0 insertions, 412 deletions
diff --git a/doc/elfutils.sgml b/doc/elfutils.sgml deleted file mode 100644 index 7ef84a8d..00000000 --- a/doc/elfutils.sgml +++ /dev/null @@ -1,412 +0,0 @@ -<!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 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 things more. This is also true for - the data read from a file. The meaning of the members 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> - </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 - to retriece 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 is 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 with 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 - weel 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: ---> |