Adjust for monotone.

1 files changed, 444 insertions, 0 deletions

diff --git a/doc/elfutils.sgml b/doc/elfutils.sgml
new file mode 100644
index 00000000..d7fea40d
--- /dev/null
+++ b/doc/elfutils.sgml
@@ -0,0 +1,444 @@
+<!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 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:
+-->