ruby-elf 1.0.7 → 1.0.8

data/manpages/rbelf-size.1.xml

@@ -1,345 +0,0 @@
-<?xml version='1.0'?>
-<!--
-Copyright © 2008-2011, Diego Elio Pettenò <flameeyes@flameeyes.eu>
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this generator; if not, write to the Free Software
-Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
--->
-<article xmlns="http://docbook.org/ns/docbook"
-         xmlns:xl="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0" xml:lang="en">
-  <info>
-    <title>rbelf-size</title>
-
-    <xi:include parse="xml" href="author.xmli" />
-  </info>
-
-  <section>
-    <title>Reference</title>
-
-    <refentry>
-      <info>
-        <date>October 2008</date>
-        <productname>ruby-elf</productname>
-      </info>
-      <refmeta>
-        <refentrytitle>rbelf-size</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </refmeta>
-      <refnamediv>
-        <refname>rbelf-size</refname>
-        <refpurpose>List section sizes of ELF files</refpurpose>
-      </refnamediv>
-      <refsynopsisdiv>
-        <cmdsynopsis>
-          <command>rbelf-size</command>
-
-          <arg choice="opt">
-            <option>--relocation-stats</option>
-            <arg choice="opt"><option>--decibel</option></arg>
-          </arg>
-
-          <arg choice="opt">
-            <option>--differential</option>
-          </arg>
-
-          <xi:include href="common.xmli"  xpointer="xpointer(id('filelist.synopsis')/*)" />
-        </cmdsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-        <title>Description</title>
-        <para>
-          <command>rbelf-size</command> is a replacement for the standard
-          <citerefentry><refentrytitle>size</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-          utility, as provided by GNU binutils and similar suites. Instead of showing the sum of all
-          the invariant, variant and unallocated sections as the size, it divides them depending on
-          how they are treated, differentiating between invariant data, invariant code, variant data
-          and relocated invariant data.
-        </para>
-      </refsect1>
-
-      <refsect1>
-        <title>Options</title>
-
-        <variablelist>
-          <varlistentry>
-            <term><option>-r</option></term>
-            <term><option>--relocation-stats</option></term>
-            <listitem>
-              <para>
-                Instead of reporting size data compatible with
-                <citerefentry><refentrytitle>size</refentrytitle><manvolnum>1</manvolnum></citerefentry>
-                report size for shared, private and relocated areas. This is helpful to assess the
-                validity of shared object approaches.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term><option>-d</option></term>
-            <term><option>--decibel</option></term>
-            <listitem>
-              <para>
-                When using the <option>--relocation-stats</option> option, a ratio is displayed
-                between the size of relocated and shared code areas, to better assess the advantages
-                and disadvantages for shared object approaches.
-              </para>
-
-              <para>
-                Since that ratio can easily skyrocket into thousands if there is very little
-                relocated data, and a lot of shared data, it might be easier to appreciate the
-                results by using a logaritmic scale.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term><option>-D</option></term>
-            <term><option>--differential</option></term>
-
-            <listitem>
-              <para>
-                Provides sizes of multiple arguments as a comparison to the first. It is designed to
-                allow comparing multiple versions of the same binary or multiple implementation of
-                the same application to evaluate the overall trend in static memory allocation.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <xi:include href="common.xmli" xpointer="xpointer(id('filelist.option')/*)" />
-        </variablelist>
-      </refsect1>
-
-      <refsect1>
-        <title>Compatible Output</title>
-
-        <para>
-          The output of <command>rbelf-size</command> differs from that of <command>size</command>
-          for the number and type of columns it outputs. While the original BSD command outputs the
-          size of the "text", "data" and "bss" sections, this tool splits them further.
-        </para>
-
-        <variablelist>
-          <varlistentry>
-            <term>exec</term>
-            <listitem>
-              <para>
-                Counts in all the sections containing executable code, this includes the
-                <varname>.text</varname> section, and others.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>data</term>
-            <listitem>
-              <para>
-                Counts in all the sections containing variable data, this excludes read-only data
-                sections, but includes relocated data and other kind of allocated and writeable data
-                sections. If the compiler is GCC or outputs GCC-compatible section names this won't
-                count in relocated constants.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>relro</term>
-            <listitem>
-              <para>
-                Counts in the relocated constants (read-only relocated data). This column will be
-                non-null only for binaries compiled by GCC or by compilers emitting GCC-compatible
-                section names. The sections counted in this entry will are relocated at runtime, but
-                are never otherwise modified. The reason why this is separated is that this section
-                may be touched by
-                <citerefentry><refentrytitle>prelink</refentrytitle><manvolnum>8</manvolnum></citerefentry>
-                so that the runtime relocation is not needed, and thus would count just as common
-                constant data.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>bss</term>
-            <listitem>
-              <para>
-                Just like <command>size</command> bss column, this counts in the size of sections
-                that are allocated at runtime as mapped to the zero page. It supports TLS
-                <varname>.tbss</varname> section.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>overhead</term>
-            <listitem>
-              <para>
-                Total size of sections providing object's metadata for the link editor and dynamic
-                loader. These include the symbol and string tables, the version tables and the hash
-                table used during linking and execution. These values are usually tied to the amount
-                of symbols exposed by an object, and can easily be reduced by hiding internal,
-                non-public symbols.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>allocated</term>
-            <listitem>
-              <para>
-                Sum of the size of all the previously-shown sections, which shows the actual
-                allocated memory used by the object. It is important to note that sections are
-                usually loaded on an alignment of the page size, which on Linux is 4KiB (4096
-                bytes), so the size of the actual memory reserved for the ELF structures in memory
-                is going to be higher than this number.
-              </para>
-            </listitem>
-          </varlistentry>
-        </variablelist>
-      </refsect1>
-
-      <refsect1>
-        <title>Relocation Statistics</title>
-
-        <para>
-          When using shared objects rather than static linking, there are many trade-offs to be
-          made. One of these relates to the amount of code that will get relocated (and thus becomes
-          private, per-process resident memory).
-        </para>
-
-        <para>
-          The <option>--relocation-stats</option> option was devised as a mean to assess the
-          cost/benefit of using shared objects, rather than using static link (e.g. with multicall
-          binaries).
-        </para>
-
-        <variablelist>
-          <varlistentry>
-            <term>shared</term>
-            <listitem>
-              <para>
-                Areas of memory that are always shared among processes; these include executable
-                areas with Position Indipendent Code, and read-only data areas.
-              </para>
-
-              <para>
-                Generally, this is what we would want to have as big as possible, compared to the
-                rest.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>private</term>
-            <listitem>
-              <para>
-                Areas of memory that will always be private to the process; these includes writeable
-                data areas and areas remapped to the zero page (what above is called bss).
-              </para>
-
-              <para>
-                This is a worst-case value, as even though the writeable sections _may_ become
-                private, if they are left untouched they will be shared among multiple (if not all)
-                processes. It is, though, useful to consider the worst-case scenario for assesment.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>relocated</term>
-            <listitem>
-              <para>
-                This value sums up the size of the memory areas that will be relocated when using
-                shared objects (or Position Indipendent Executables). Relocated areas include
-                .data.rel.ro sections, which contain data read-only for the code, but written to by
-                the dynamic linker.
-              </para>
-
-              <para>
-                Again this value is an approximation nearing the worst-case scenario.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <varlistentry>
-            <term>ratio</term>
-            <listitem>
-              <para>
-                The ratio between shared and relocated code in the current executable or shared
-                object. Using this value you can have a quick idea of the cost/benefit of using
-                shared objects for a particular task.
-              </para>
-
-              <para>
-                When using <option>--decibel</option> the value will be represented in deciBels,
-                which should make it even easier to understand: a negative value shows a overly high
-                cost, while a value between 1 and 10 will indicate some work might be needed to
-                improve the benefits.
-              </para>
-            </listitem>
-          </varlistentry>
-        </variablelist>
-      </refsect1>
-
-      <refsect1>
-        <title>Bugs and Missing Features</title>
-
-        <para>
-          When using the <option>--differential</option> option, analysis of the arguments happens
-          sequentially in a single thread rather than in parallel.
-        </para>
-
-        <xi:include href="common.xmli" xpointer="xpointer(id('filelist.bugpara')/*)" />
-      </refsect1>
-
-      <refsect1>
-        <title>See Also</title>
-        <para>
-          <citation xl:href="http://blog.flameeyes.eu/">Flameeyes's Weblog</citation>
-          http://blog.flameeyes.eu/
-        </para>
-
-        <para>
-          Related tools:
-
-          <citerefentry>
-            <refentrytitle>cowstats</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>,
-
-          <citerefentry>
-            <refentrytitle>size</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>,
-
-          <citerefentry>
-            <refentrytitle>prelink</refentrytitle>
-            <manvolnum>8</manvolnum>
-          </citerefentry>.
-        </para>
-      </refsect1>
-    </refentry>
-  </section>
-</article>
-<!--
-    Local Variables:
-    mode: nxml
-    mode: auto-fill
-    mode: flyspell
-    ispell-local-dictionary: "english"
-    fill-column: 100
-    indent-tabs-mode: nil
-    End:
--->

data/manpages/verify-lfs.1.xml

@@ -1,136 +0,0 @@
-<?xml version='1.0'?>
-<!--
-Copyright © 2010-2011, Diego Elio Pettenò <flameeyes@flameeyes.eu>
-
-This program is free software; you can redistribute it and/or modify
-it under the terms of the GNU General Public License as published by
-the Free Software Foundation; either version 2 of the License, or
-(at your option) any later version.
-
-This program is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-GNU General Public License for more details.
-
-You should have received a copy of the GNU General Public License
-along with this generator; if not, write to the Free Software
-Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
--->
-<article xmlns="http://docbook.org/ns/docbook"
-         xmlns:xl="http://www.w3.org/1999/xlink"
-         xmlns:xi="http://www.w3.org/2001/XInclude"
-         version="5.0" xml:lang="en">
-  <info>
-    <title>verify-lfs</title>
-
-    <xi:include parse="xml" href="author.xmli" />
-  </info>
-
-  <section>
-    <title>Reference</title>
-
-    <refentry>
-      <info>
-        <date>December 2010</date>
-        <productname>ruby-elf</productname>
-      </info>
-      <refmeta>
-        <refentrytitle>verify-lfs</refentrytitle>
-        <manvolnum>1</manvolnum>
-      </refmeta>
-      <refnamediv>
-        <refname>verify-lfs</refname>
-        <refpurpose>ELF analyzer to identify software not using solely LFS interfaces</refpurpose>
-      </refnamediv>
-      <refsynopsisdiv>
-        <cmdsynopsis>
-          <command>verify-lfs</command>
-
-          <arg choice="opt">
-            <option>--objects</option>
-          </arg>
-
-          <xi:include href="common.xmli"  xpointer="xpointer(id('filelist.synopsis')/*)" />
-        </cmdsynopsis>
-      </refsynopsisdiv>
-
-      <refsect1>
-        <title>Description</title>
-        <para>
-          <command>verify-lfs</command> is a script that analyses the symbols required by ELF
-          executables and libraries, listing the objects that rely entirely or partially on the
-          pre-largefile interface functions of glibc.
-        </para>
-      </refsect1>
-
-      <refsect1>
-        <title>Options</title>
-
-        <variablelist>
-          <varlistentry>
-            <term><option>-o</option></term>
-            <term><option>--objects</option></term>
-
-            <listitem>
-              <para>
-                Scan for relocatable object files (ET_REL) rather than executables or dynamic
-                libraries. This mode is designed to help identify which object might be miscompiled
-                to not use LFS functions as it was instead intended.
-              </para>
-            </listitem>
-          </varlistentry>
-
-          <xi:include href="common.xmli" xpointer="xpointer(id('filelist.option')/*)" />
-        </variablelist>
-      </refsect1>
-
-      <refsect1>
-        <title>Bugs and Missing Features</title>
-        <para>
-          <command>verify-lfs</command> uses a manually-tweaked regular expression to identify which
-          interface is being used; this expressions might be incomplete or lead to false positive,
-          please double-check the results, and report back if you have hit false positives, or false
-          negatives.
-        </para>
-
-        <xi:include href="common.xmli" xpointer="xpointer(id('filelist.bugpara')/*)" />
-      </refsect1>
-
-      <refsect1>
-        <title>Credits</title>
-
-        <para>
-          The original idea for this script comes from the <filename>summarise-stat64</filename>
-          Perl script written by Greg Banks of SGI. A huge thanks to Greg for the idea and the
-          script.
-        </para>
-      </refsect1>
-
-      <refsect1>
-        <title>See Also</title>
-        <para>
-          <citation xl:href="http://blog.flameeyes.eu/">Flameeyes's Weblog</citation>
-          http://blog.flameeyes.eu/
-        </para>
-
-        <para>
-          Related tools:
-          <citerefentry>
-            <refentrytitle>nm</refentrytitle>
-            <manvolnum>1</manvolnum>
-          </citerefentry>.
-        </para>
-      </refsect1>
-    </refentry>
-  </section>
-</article>
-<!--
-    Local Variables:
-    mode: nxml
-    mode: auto-fill
-    mode: flyspell
-    ispell-local-dictionary: "english"
-    fill-column: 100
-    indent-tabs-mode: nil
-    End:
--->