ruby-elf 1.0.0

data/lib/elf/value.rb

@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+# Simple ELF parser for Ruby
+#
+# Copyright © 2007-2010 Diego E. "Flameeyes" Pettenò <flameeyes@gmail.com>
+# Portions inspired by elf.py
+#   Copyright © 2002 Netgraft Corporation
+# Portions inspired by elf.h
+#   Copyright © 1995-2006 Free Software Foundation, Inc.
+#
+# 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
+
+module Elf
+  class Value
+    class OutOfBound < Exception
+      attr_reader :val
+
+      def initialize(val)
+        @val = val
+        @appendix = ""
+      end
+
+      def message
+        "Value #{@val} out of bound#{@appendix}"
+      end
+      
+      def append_message(s)
+        @appendix << "\n#{s}"
+      end
+    end
+
+    def initialize(val, params)
+      @val = val
+      @mnemonic = params[0].to_s
+      @desc = params[1]
+    end
+
+    attr_reader :desc, :val, :mnemonic
+    alias :to_i :val
+    alias :to_s :desc
+
+    def ==(other)
+      self.class == other.class and @val == other.to_i
+    end
+
+    def Value.[](idx)
+      return @enums[idx] if @enums[idx]
+
+      # If the class has defined special ranges, handle them; a
+      # special range is a range of values for which unknown values
+      # are allowed (because they are bound to specific usage we don't
+      # know about — where on the other hand unknown values outside of
+      # these ranges are frown upon); different type of values have
+      # different special ranges, each with its own base name, so
+      # leave that to be decided by the class itself.
+      if self.const_defined?("SpecialRanges")
+        self::SpecialRanges.each_pair do |base, range|
+          return self::Unknown.new(idx, sprintf("%s+%07x", base, idx-range.first)) if range.include? idx
+        end
+      end
+
+      raise OutOfBound.new(idx)
+    end
+
+    def Value.from_string(str)
+      str = str.downcase
+
+      each do |value|
+        return value if value.mnemonic.downcase == str
+      end
+
+      return nil
+    end
+
+    def Value.has_key?(idx)
+      @enums.has_key?(idx)
+    end
+
+    def Value.fill(*hash)
+      if hash.size == 1 && hash[0].is_a?(Hash)
+        hash = hash[0]
+      end
+
+      @enums = { }
+
+      hash.each_pair do |index, value|
+        @enums[index] = self.new(index, value)
+        const_set(value[0], @enums[index])
+      end
+    end
+
+    def Value.each(&block)
+      @enums.each_value(&block)
+    end
+
+    private_class_method :fill
+
+    # Class for unknown values
+    #
+    # This class is used to provide a way to access at least basic
+    # data for values that are not known but are known valid (like OS-
+    # or CPU-specific types for files, sections and symbols).
+    #
+    # It mimics the basis of a Value but is custom-filled by the using
+    # code.
+    class Unknown
+      def initialize(val, desc)
+        @val = val
+        @desc = desc
+      end
+
+      attr_reader :desc, :val
+      alias :to_i :val
+      alias :to_s :desc
+    end
+  end
+end

data/manpages/cowstats.1

@@ -0,0 +1,180 @@
+'\" t
+.\"     Title: cowstats
+.\"    Author: 
+.\" Generator: DocBook XSL-NS Stylesheets v1.76.0 <http://docbook.sf.net/>
+.\"      Date: October 2008
+.\"    Manual: Reference
+.\"    Source: ruby-elf
+.\"  Language: English
+.\"
+.TH "COWSTATS" "1" "October 2008" "ruby-elf" "Reference"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+cowstats \- ELF Copy\-on\-Write analyzer
+.SH "SYNOPSIS"
+.HP \w'\fBcowstats\fR\ 'u
+\fBcowstats\fR [\fB\-\-statistics\fR] [\fB\-\-total\fR] [\fB\-\-ignore\-cxx\fR] [\fB\-\-ignore\-profiling\fR] [\fB\-\-ignore\-data\-rel\-ro\fR] [\fB\-\-sort\-by\fR\ \fIsection\-column\fR] [\fB\-\-quiet\fR] [\fB\-\-recursive\fR] [\fB@\fR\fIfile\fR | \fIfile\fR...]
+.SH "DESCRIPTION"
+.PP
+
+\fBcowstats\fR
+is a script that analyses ELF object files, results of compilation of C, C++ or other languages on an Unix system, and reports about the variables that enter Copy\-on\-Write sections\&.
+.PP
+Static variables (initialised and not) and constant pointers on PIC or PIE enabled object files are emitted in the so\-called Copy\-on\-Write sections, which require copying over pages from the original ELF executable file to a private resident area of memory at runtime\&.
+.PP
+
+\fBcowstats\fR
+reports the possible symbols that were emitted in Copy\-on\-Write sections so that they can be looked after to see if they can be made constant and/or removed or reworked\&.
+.SH "OPTIONS"
+.PP
+\fB\-s\fR, \fB\-\-statistics\fR
+.RS 4
+Instead of reporting all the variables found in Copy\-on\-Write sections, only generate a table showing the sie of data in Copy\-on\-Write sections per each file, divided into
+\fB\&.data\fR,
+\fB\&.bss\fR
+and
+\fB\&.data\&.rel\fR
+(for variables, uninitialised variables, and relocated variables and constants)\&.
+.RE
+.PP
+\fB\-t\fR, \fB\-\-total\fR
+.RS 4
+Shows some rough totals for the amount of data in Copy\-on\-Write sections for the program, assuming all the object files given are linked in the same executable\&. This will also show a rough page\-based total, which bases itself on 4K\-sized pages\&.
+.RE
+.PP
+\fB\-x\fR, \fB\-\-ignore\-cxx\fR
+.RS 4
+Ignore some C++ entries that could be considered false positives\&. C++ object files will report as CoW data the vtables and typeinfo objects for C++ classes, since they are actually emitted in Copy\-on\-Write sections\&. Since they cannot be moved from thre, this option hides them on the output, to reduce clutter and noise\&.
+.RE
+.PP
+\fB\-p\fR, \fB\-\-ignore\-profiling\fR
+.RS 4
+Similarly to C++, also profiling (with
+\fBgcov\fR) will add some symbols that would be identified as CoW data\&. Use this option to avoid reporting those symbols\&.
+.RE
+.PP
+\fB\-r\fR, \fB\-\-ignore\-data\-rel\-ro\fR
+.RS 4
+Don\*(Aqt report constants found in the \&.data\&.rel\&.ro section, and consider it as non\-relocated\&. This is helpful to reduce the noise when looking for writable data symbols, or when analysing non\-PIC builds\&.
+.RE
+.PP
+\fB\-S\fR \fIsection\-column\fR, \fB\-\-sort\-by\fR \fIsection\-column\fR
+.RS 4
+Sort the output of
+\fB\-\-statistics\fR
+by the given column\&. Useful when looking for which objects have the most hit for one particular CoW problem\&. The column can be one of the following section names:
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\&.bss
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\&.data
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\&.data\&.rel
+.RE
+.sp
+.RS 4
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+\&.data\&.rel\&.ro
+.RE
+.RE
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Do not output warnings and errors to the standard error\&. Designed to increase the signal\-to\-noise ratio when analysing eterogeneous trees recursively, or when producing output to redirect to automated systems\&.
+.RE
+.PP
+\fB\-R\fR, \fB\-\-recursive\fR
+.RS 4
+Recursively descend into directories to search for files to scan\&. This affects both the paths passed from the command line and those found in argument files\&.
+.RE
+.PP
+\fB@\fR\fIpath\fR
+.RS 4
+Read the list of files to analyse from the given file (or standard input if
+\fIpath\fR
+is
+\-)\&. Useful to pass a long list of files\&. When used with stdin or named pipes, this also allows asynchronous analysis\&.
+.RE
+.SH "BUGS"
+.PP
+
+\fBcowstats\fR
+is still an experiment, and is not yet entirely complete, there are thus a number of bugs that haven\*(Aqt been discovered or well tested yet\&.
+.PP
+A known "bug" or misbehaviour is that
+\fBcowstats\fR
+cannot know whether multple object files will be linked together in the same module (executable or shared object) or not\&. For this reason the output of
+\fB\-\-total\fR
+might not be consistent with the runtime behaviour of the module itself\&.
+.PP
+Parsing of files to provide further arguments (\fB@\fR\fIfile\fR) is not entirely comforming to other tools handling of the same syntax\&. No options are parsed from the file, and filenames are expected to be separated by newlines rather than whitespace\&.
+.PP
+Symbolic links are only followed when they are passed directly to the command line, or through @\-lists; symbolic links are
+\fInot\fR
+followed when using the
+\fB\-\-recursive\fR
+option, to avoid loops\&.
+.SH "SEE ALSO"
+.PP
+
+\m[blue]\fBFlameeyes\*(Aqs Weblog\fR\m[]
+http://blog\&.flameeyes\&.eu/
+.PP
+Related tools:
+\fBrbelf-size\fR(1),
+\fBobjdump\fR(1)\&.
+.SH "AUTHOR"
+.PP
+\fBDiego E. Pettenò\fR <\&flameeyes@gmail.com\&>
+.RS 4
+Author and main contributor.
+.RE

data/manpages/elfgrep.1

@@ -0,0 +1,188 @@
+'\" t
+.\"     Title: elfgrep
+.\"    Author: 
+.\" Generator: DocBook XSL-NS Stylesheets v1.76.0 <http://docbook.sf.net/>
+.\"      Date: January 2011
+.\"    Manual: Reference
+.\"    Source: ruby-elf
+.\"  Language: English
+.\"
+.TH "ELFGREP" "1" "January 2011" "ruby-elf" "Reference"
+.\" -----------------------------------------------------------------
+.\" * Define some portability stuff
+.\" -----------------------------------------------------------------
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.\" http://bugs.debian.org/507673
+.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
+.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.ie \n(.g .ds Aq \(aq
+.el       .ds Aq '
+.\" -----------------------------------------------------------------
+.\" * set default formatting
+.\" -----------------------------------------------------------------
+.\" disable hyphenation
+.nh
+.\" disable justification (adjust text to left margin only)
+.ad l
+.\" -----------------------------------------------------------------
+.\" * MAIN CONTENT STARTS HERE *
+.\" -----------------------------------------------------------------
+.SH "NAME"
+elfgrep \- Search for symbols matching an expression in ELF files
+.SH "SYNOPSIS"
+.HP \w'\fBelfgrep\fR\ 'u
+\fBelfgrep\fR [\fB\-\-fixed\-strings\fR] {\fB\-\-regexp\fR\ \fIPATTERN\fR...} [\fB\-\-ignore\-case\fR] [\fB\-\-match\-version\fR] [\fB\-\-no\-match\-undefined\fR | \fB\-\-no\-match\-defined\fR] [\fB\-\-invert\-match\fR] [\fB\-\-count\fR] [\fB\-\-files\-without\-match\fR | \fB\-\-files\-with\-matches\fR] [\fB\-\-with\-filename\fR | \fB\-\-no\-filename\fR] [\fB\-\-null\fR] [\fB\-\-quiet\fR] [\fB\-\-recursive\fR] [\fB@\fR\fIfile\fR | \fIfile\fR...]
+.SH "DESCRIPTION"
+.PP
+
+\fBelfgrep\fR
+is a simple script that allows to earch for particular symbols within a file, by matching regular expression on their name\&. It is insipired by the common Unix
+\fBgrep\fR(1)
+tool\&.
+.SH "OPTIONS"
+.SS "Matching Control"
+.PP
+\fB\-F\fR, \fB\-\-fixed\-strings\fR
+.RS 4
+Interpret
+\fIPATTERN\fR
+as a fixed string\&.
+.RE
+.PP
+\fB\-e\fR \fIPATTERN\fR, \fB\-\-regexp\fR \fIPATTERN\fR
+.RS 4
+Specifies the expression to match on the symbols\&. In contrast to regular
+\fBgrep\fR(1)
+you
+\fIhave\fR
+to provide at least an expression through the
+\fB\-\-regexp\fR
+option\&.
+.RE
+.PP
+\fB\-i\fR, \fB\-\-ignore\-case\fR
+.RS 4
+Ignore case distinction in both the
+\fIPATTERN\fR
+and the symbols\*(Aq names\&.
+.RE
+.PP
+\fB\-V\fR, \fB\-\-match\-version\fR
+.RS 4
+Append the ELF version information for the symbol, separated by an @ symbol, before testing the expression for match\&. This allows to match only symbols that are defined with a particular version\&.
+.RE
+.PP
+\fB\-U\fR, \fB\-\-no\-match\-undefined\fR
+.RS 4
+Do not report matches on undefined symbols; useful if you\*(Aqre looking for the objects defining the symbol, and not those using it\&.
+.RE
+.PP
+\fB\-D\fR, \fB\-\-no\-match\-defined\fR
+.RS 4
+Do not report matches on defined symbols; useful if you\*(Aqre looking for the objects using the symbol, and not those defining it\&.
+.RE
+.PP
+\fB\-v\fR, \fB\-\-invert\-match\fR
+.RS 4
+Invert the sense of matching, to select non\-matching symbols\&. This does not invert the sense of
+\fB\-\-no\-match\-undefined\fR
+and
+\fB\-\-no\-match\-defined\fR\&.
+.RE
+.SS "Output Control"
+.PP
+\fB\-c\fR, \fB\-\-count\fR
+.RS 4
+Suppress normal output; instead print a count of matching lines for each input file\&. With the
+\fB\-\-invert\-match\fR
+option, count non\-matching lines\&.
+.RE
+.PP
+\fB\-L\fR, \fB\-\-files\-without\-match\fR
+.RS 4
+Suppress normal output; instead print the name of each input file from which no output would normally have been printed\&.
+.RE
+.PP
+\fB\-l\fR, \fB\-\-files\-with\-matches\fR
+.RS 4
+Suppress normal output; instead print the name of each input file from which output would normally have been printed\&. The scalling will stop on the first match\&.
+.RE
+.PP
+\fB\-H\fR, \fB\-\-with\-filename\fR
+.RS 4
+Print the file name for each match\&. This is the default when there is more than one file to search\&.
+.RE
+.PP
+\fB\-h\fR, \fB\-\-no\-filename\fR
+.RS 4
+Suppress the prefixing of file names on output\&. This is the default when there is only one file to search\&.
+.RE
+.PP
+\fB\-Z\fR, \fB\-\-null\fR
+.RS 4
+Output a zero byte (the ASCII
+NUL
+character) instead of the character that normally follows a file name\&. For example
+\fBelfgrep \-lZ\fR
+outputs a zero byte after each file name instead of the usual newline\&. This option makes the output unambiguous, even in presence of file names containing unusual characters like newlines, so that it can be used with commands like
+\fBxargs \-0\fR\&.
+.RE
+.SS "General Options"
+.PP
+\fB\-q\fR, \fB\-\-quiet\fR
+.RS 4
+Do not output warnings and errors to the standard error\&. Designed to increase the signal\-to\-noise ratio when analysing eterogeneous trees recursively, or when producing output to redirect to automated systems\&.
+.RE
+.PP
+\fB\-R\fR, \fB\-\-recursive\fR
+.RS 4
+Recursively descend into directories to search for files to scan\&. This affects both the paths passed from the command line and those found in argument files\&.
+.RE
+.PP
+\fB@\fR\fIpath\fR
+.RS 4
+Read the list of files to analyse from the given file (or standard input if
+\fIpath\fR
+is
+\-)\&. Useful to pass a long list of files\&. When used with stdin or named pipes, this also allows asynchronous analysis\&.
+.RE
+.SH "BUGS AND MISSING FEATURES"
+.PP
+By default,
+elfgrep
+uses standard Ruby regular expressions, which are neither the basic or extended regular expressions as implemented by
+\fBgrep\fR(1)
+nor the Perl (or compatible) regular expressions\&.
+.PP
+The
+\fB\-\-fixed\-strings\fR
+option does not conform completely with the equivalent option from
+\fBgrep\fR(1)
+as it doesn\*(Aqt take a newline\-separated list of strings, but only a single string\&.
+.PP
+Parsing of files to provide further arguments (\fB@\fR\fIfile\fR) is not entirely comforming to other tools handling of the same syntax\&. No options are parsed from the file, and filenames are expected to be separated by newlines rather than whitespace\&.
+.PP
+Symbolic links are only followed when they are passed directly to the command line, or through @\-lists; symbolic links are
+\fInot\fR
+followed when using the
+\fB\-\-recursive\fR
+option, to avoid loops\&.
+.SH "SEE ALSO"
+.PP
+
+\m[blue]\fBFlameeyes\*(Aqs Weblog\fR\m[]
+http://blog\&.flameeyes\&.eu/
+.PP
+Related tools:
+\fBgrep\fR(1),
+\fBnm\fR(1)\&.
+.PP
+Lots of description of options above are lifted directly from the
+grep
+man page, to avoid confusing with different wordings\&.
+.SH "AUTHOR"
+.PP
+\fBDiego E. Pettenò\fR <\&flameeyes@gmail.com\&>
+.RS 4
+Author and main contributor.
+.RE