elftools 2.0.0 → 2.2.0

data/lib/elftools/structs.rb

@@ -2,6 +2,8 @@
 
 require 'bindata'
 
+require 'elftools/exceptions'
+
 module ELFTools
   # Define ELF related structures in this module.
   #
@@ -15,18 +17,93 @@ module ELFTools
         { selection: :elf_class, choices: { 32 => :"#{t}32", 64 => :"#{t}64" }, copy_on_change: true }
       end
 
+      # How an integer of each width is packed, for +String#unpack+, whether it
+      # records a sign or not.
+      UNPACK_TEMPLATES = {
+        little: {
+          false => { 1 => 'C', 2 => 'v', 4 => 'V', 8 => 'Q<' },
+          true => { 1 => 'c', 2 => 's<', 4 => 'l<', 8 => 'q<' }
+        },
+        big: {
+          false => { 1 => 'C', 2 => 'n', 4 => 'N', 8 => 'Q>' },
+          true => { 1 => 'c', 2 => 's>', 4 => 'l>', 8 => 'q>' }
+        }
+      }.freeze
+
+      # Bytes of set bits to read a prototype from, longer than any structure
+      # here, so that reading one never runs short of them.
+      SET_BITS = ("\xff" * 256).b.freeze
+
       attr_accessor :elf_class # @return [Integer] 32 or 64.
       attr_accessor :offset # @return [Integer] The file offset of this header.
 
-      # Records which fields have been patched.
-      # @return [Hash{Integer => Integer}] Patches.
+      # Reads the structure, remembering the bytes it was read from.
+      #
+      # They are taken back off the stream. A stream that cannot be seeked is
+      # serialized instead.
+      # @param [#pos=, #read] io The streaming object.
+      # @return [ELFTools::Structs::ELFStruct] Itself.
+      def read(io)
+        start = io.pos if io.respond_to?(:pos)
+        super.tap { @source = start.nil? ? to_binary_s : bytes_read(io, start) }
+      end
+
+      # Which bytes of this structure have been changed since it was read.
+      #
+      # Every field answers alike, however deeply it is nested, because what is
+      # compared is the bytes the structure occupies rather than the
+      # assignments that were made to it. A field assigned the value it
+      # already held leaves nothing behind.
+      # @return [Hash{Integer => String}]
+      #   Where each run of changed bytes starts, as an offset into the
+      #   structure, and the bytes it is to be replaced with.
+      # @example
+      #   header.e_ident.ei_abiversion = 41
+      #   header.patches
+      #   #=> { 8 => "\x29" }
       def patches
-        @patches ||= {}
+        return {} if @source.nil?
+
+        changed_runs(@source, to_binary_s)
       end
 
       # BinData hash(Snapshot) that behaves like HashWithIndifferentAccess
       alias to_h snapshot
 
+      private
+
+      # The bytes a read has just taken from a stream, leaving it where the
+      # read left it.
+      # @param [#pos=, #read] io The streaming object.
+      # @param [Integer] start Where the read began.
+      # @return [String] The bytes.
+      def bytes_read(io, start)
+        here = io.pos
+        io.pos = start
+        io.read(here - start).tap { io.pos = here }
+      end
+
+      # Where two strings of bytes differ, as the runs of bytes that differ.
+      #
+      # Only as far as +before+ reaches, so that a patch never covers more of
+      # the file than the structure it came from.
+      # @param [String] before The bytes as they were.
+      # @param [String] after The bytes as they are.
+      # @return [Hash{Integer => String}] Where each run starts, and its bytes.
+      def changed_runs(before, after)
+        runs = {}
+        start = nil
+        (0..before.bytesize).each do |i|
+          if i < before.bytesize && before.getbyte(i) != after.getbyte(i)
+            start ||= i
+          elsif start
+            runs[start] = after.byteslice(start, i - start)
+            start = nil
+          end
+        end
+        runs
+      end
+
       class << self
         # Hooks the constructor.
         #
@@ -41,28 +118,60 @@ module ELFTools
         def new(*args)
           kwargs = args.last.is_a?(Hash) ? args.last : {}
           offset = kwargs.delete(:offset)
-          super.tap do |obj|
-            obj.offset = offset
-            obj.field_names.each do |f|
-              m = :"#{f}="
-              old_method = obj.singleton_method(m)
-              obj.singleton_class.send(:undef_method, m)
-              obj.define_singleton_method(m) do |val|
-                org = obj.send(f)
-                obj.patches[org.abs_offset] = ELFStruct.pack(val, org.num_bytes)
-                old_method.call(val)
-              end
-            end
-          end
+          super.tap { |obj| obj.offset = offset }
         end
 
         # Gets the endianness of current class.
+        #
+        # A class is of one endianness for as long as it exists, and asking
+        # bindata what it is named costs more than remembering the answer.
         # @return [:little, :big] The endianness.
         def self_endian
-          bindata_name[-2..] == 'be' ? :big : :little
+          @self_endian ||= bindata_name[-2..] == 'be' ? :big : :little
+        end
+
+        # What the fields of a structure record, read straight from its bytes.
+        #
+        # Reading a table of structures costs a structure for every entry of
+        # it otherwise, which is most of what reading the table costs. Nothing
+        # is remembered of the bytes, so a caller that means to assign to a
+        # field wants a structure instead.
+        # @param [String] bytes The bytes a structure is recorded in.
+        # @param [Integer] elf_class 32 or 64, which decides how wide the fields recording an address are.
+        # @param [:little, :big] endian The endianness the file records it in.
+        # @return [Hash{Symbol => Integer}] Each field, and what it records.
+        # @raise [ELFTools::ELFError] If this is not a structure of integers.
+        # @example
+        #   ELF64_sym.unpack_fields(bytes, elf_class: 64, endian: :little)
+        #   #=> { st_name: 1, st_info: 18, st_other: 0, st_shndx: 15, st_value: 4198864, st_size: 101 }
+        def unpack_fields(bytes, elf_class:, endian:)
+          values = bytes.unpack(unpack_template(elf_class, endian))
+          fields = {}
+          # Paired by hand rather than zipped, which would make an array for
+          # every field of every structure read.
+          field_names(elf_class, endian).each_with_index { |name, i| fields[name] = values[i] }
+          fields
+        end
+
+        # How many bytes a structure of this kind takes.
+        # @param [Integer] elf_class 32 or 64, which decides how wide the fields recording an address are.
+        # @param [:little, :big] endian The endianness the file records it in.
+        # @return [Integer] The number.
+        # @example
+        #   ELF64_sym.num_bytes(elf_class: 64, endian: :little)
+        #   #=> 24
+        def num_bytes(elf_class:, endian:)
+          @num_bytes ||= {}
+          # Nested rather than keyed by the pair, which would make an array of
+          # it for every structure read.
+          (@num_bytes[elf_class] ||= {})[endian] ||= prototype(elf_class, endian).num_bytes
         end
 
         # Packs an integer to string.
+        #
+        # @deprecated
+        #   Nothing here packs a patch by hand anymore, see {ELFStruct#patches}.
+        #   This is kept for anyone who called it and goes in the next major.
         # @param [Integer] val
         # @param [Integer] bytes
         # @return [String]
@@ -78,6 +187,210 @@ module ELFTools
           out = out.pack('C*')
           self_endian == :little ? out : out.reverse
         end
+
+        private
+
+        # A structure of this kind with every bit of it set, which the layout is
+        # read off: how wide each field is, and whether it records a sign.
+        #
+        # Every structure of a kind and a class is laid out alike, so one is
+        # built for the kind rather than for each question asked about it.
+        # @param [Integer] elf_class 32 or 64, which decides how wide the fields recording an address are.
+        # @param [:little, :big] endian The endianness the file records it in.
+        # @return [ELFTools::Structs::ELFStruct] The structure.
+        def prototype(elf_class, endian)
+          @prototypes ||= {}
+          (@prototypes[elf_class] ||= {})[endian] ||= begin
+            struct = new(endian: endian)
+            struct.elf_class = elf_class
+            struct.read(SET_BITS)
+          end
+        end
+
+        # What the fields of this structure are named, in the order they are
+        # recorded.
+        # @param [Integer] elf_class 32 or 64, which decides how wide the fields recording an address are.
+        # @param [:little, :big] endian The endianness the file records it in.
+        # @return [Array<Symbol>] The names.
+        def field_names(elf_class, endian)
+          @field_names ||= {}
+          (@field_names[elf_class] ||= {})[endian] ||= prototype(elf_class, endian).field_names
+        end
+
+        # How the fields of this structure are packed, as a template for
+        # +String#unpack+.
+        # @param [Integer] elf_class 32 or 64, which decides how wide the fields recording an address are.
+        # @param [:little, :big] endian The endianness the file records it in.
+        # @return [String] The template.
+        def unpack_template(elf_class, endian)
+          @unpack_templates ||= {}
+          (@unpack_templates[elf_class] ||= {})[endian] ||=
+            prototype(elf_class, endian).each_pair.map { |_, field| field_template(field, endian) }.join
+        end
+
+        # How one field is packed, which is its width and whether what it read
+        # from a field of set bits came back negative.
+        # @param [BinData::Base] field The field, read from bits that are all set.
+        # @param [:little, :big] endian The endianness the file records it in.
+        # @return [String] The template.
+        # @raise [ELFTools::ELFError] If the field is not an integer of 1, 2, 4, or 8 bytes.
+        def field_template(field, endian)
+          width = field.num_bytes
+          template = UNPACK_TEMPLATES.fetch(endian)
+          raise ELFError, format('%s is not a structure of integers', name) unless template[false].key?(width)
+
+          template.fetch(field.to_i.negative?)[width]
+        end
+      end
+    end
+
+    # What a structure the file records at an offset holds, read without
+    # building the structure.
+    #
+    # Reading a table of structures costs a structure for every entry of it
+    # otherwise, and setting up the fields of one is most of what it costs.
+    # {#struct} builds one for whatever wants the structure itself, which
+    # is what assigning to a field takes, and what is assigned is answered
+    # with from then on.
+    class Fields
+      attr_reader :elf_class # @return [Integer] 32 or 64.
+      attr_reader :endian # @return [:little, :big] The endianness the file records it in.
+
+      # What a structure already built holds, for a caller that has one.
+      # @param [ELFTools::Structs::ELFStruct] struct The structure.
+      # @return [ELFTools::Structs::Fields] The fields.
+      def self.of(struct)
+        allocate.tap { |fields| fields.send(:built_from, struct) }
+      end
+
+      # Fields nothing in the file records, for what a file states some other
+      # way than by recording a structure of it.
+      #
+      # There is nothing to read and nothing to patch, so a structure is only
+      # built if something asks for one, and is built from these.
+      # @param [Class] klass The structure class.
+      # @param [Hash{Symbol => Integer}] fields What each field is to record.
+      # @param [Integer] elf_class 32 or 64.
+      # @param [:little, :big] endian The endianness the file records it in.
+      # @param [Integer] offset Where in the file this came from.
+      # @return [ELFTools::Structs::Fields] The fields.
+      # @example
+      #   Fields.from(ELF_Rel, { r_offset: 0x1000 }, elf_class: 64, endian: :little, offset: 0x40)
+      def self.from(klass, fields, elf_class:, endian:, offset:)
+        allocate.tap { |made| made.send(:made_of, klass, fields, elf_class, endian, offset) }
+      end
+
+      # @param [Class] klass The structure class.
+      # @param [#pos=, #read] stream The streaming object.
+      # @param [Integer] offset The file offset the structure is recorded at.
+      # @param [Integer] elf_class 32 or 64.
+      # @param [:little, :big] endian The endianness the file records it in.
+      # @raise [EOFError] If the file does not reach that far.
+      def initialize(klass, stream, offset, elf_class:, endian:)
+        @klass = klass
+        @stream = stream
+        @offset = offset
+        @elf_class = elf_class
+        @endian = endian
+        @fields = unpack
+      end
+
+      # What one field of the structure records.
+      #
+      # The structure answers once there is one, so that a field assigned to
+      # reads back as it was assigned.
+      # @param [Symbol] name The name of the field.
+      # @return [Integer] The value.
+      # @example
+      #   fields[:st_value]
+      #   #=> 4198864
+      def [](name)
+        return @struct[name].to_i if @struct
+
+        @fields[name]
+      end
+
+      # Assigns to one field.
+      #
+      # The structure takes the assignment wherever the file records one, so
+      # that {ELFTools::ELFFile#patches} reports it. Fields the file records
+      # no structure of take it themselves, there being nothing to patch.
+      # @param [Symbol] name The name of the field.
+      # @param [Integer] value What it is to record.
+      # @return [void]
+      def []=(name, value)
+        if @struct.nil? && @stream.nil?
+          @fields[name] = value
+        else
+          struct[name] = value
+        end
+      end
+
+      # The structure itself, read from where the file records it, or built
+      # from these fields where it records none.
+      #
+      # The same one however often it is asked for, so that assigning to a
+      # field of it is not forgotten.
+      # @return [ELFTools::Structs::ELFStruct] The structure.
+      def struct
+        @struct ||= @stream.nil? ? build : read
+      end
+
+      private
+
+      # Takes a structure that is already built as what these fields hold.
+      # @param [ELFTools::Structs::ELFStruct] struct The structure.
+      # @return [void]
+      def built_from(struct)
+        @struct = struct
+        @elf_class = struct.elf_class
+        @endian = struct.class.self_endian
+      end
+
+      # Takes fields nothing in the file records a structure of.
+      # @return [void]
+      def made_of(klass, fields, elf_class, endian, offset)
+        @klass = klass
+        @fields = fields
+        @elf_class = elf_class
+        @endian = endian
+        @offset = offset
+      end
+
+      # The structure the file records, read from where it records it.
+      # @return [ELFTools::Structs::ELFStruct] The structure.
+      def read
+        struct = new_struct
+        @stream.pos = @offset
+        struct.read(@stream)
+      end
+
+      # A structure holding what these fields hold, for fields the file
+      # records no structure of.
+      # @return [ELFTools::Structs::ELFStruct] The structure.
+      def build
+        new_struct.tap { |struct| @fields.each { |name, value| struct[name] = value } }
+      end
+
+      # A structure of this kind, of the class and the order of the file, and
+      # of where in it this came from.
+      # @return [ELFTools::Structs::ELFStruct] The structure.
+      def new_struct
+        struct = @klass.new(endian: @endian, offset: @offset)
+        struct.elf_class = @elf_class
+        struct
+      end
+
+      # What the fields record, read from the bytes recording them.
+      # @return [Hash{Symbol => Integer}] Each field, and what it records.
+      # @raise [EOFError] If the file does not reach that far, as reading the structure itself does.
+      def unpack
+        num_bytes = @klass.num_bytes(elf_class: @elf_class, endian: @endian)
+        @stream.pos = @offset
+        bytes = @stream.read(num_bytes)
+        raise EOFError, 'End of file reached' if bytes.nil? || bytes.bytesize < num_bytes
+
+        @klass.unpack_fields(bytes, elf_class: @elf_class, endian: @endian)
       end
     end
 
@@ -200,6 +513,49 @@ module ELFTools
       uint32 :shift2    # The second shift the bloom filter is built with
     end
 
+    # An entry of the table of versions a file needs of another, which the
+    # +vn_next+ of the one before it points at.
+    class ELF_Verneed < ELFStruct
+      endian :big_and_little
+      uint16 :vn_version # Revision of this structure
+      uint16 :vn_cnt     # How many versions of the file are needed
+      uint32 :vn_file    # Name of the file, as an offset into the string table
+      uint32 :vn_aux     # Where the versions start, as an offset from here
+      uint32 :vn_next    # Where the next entry is, as an offset from here
+    end
+
+    # A version an {ELF_Verneed} needs, which the +vna_next+ of the one before
+    # it points at.
+    class ELF_Vernaux < ELFStruct
+      endian :big_and_little
+      uint32 :vna_hash  # Hash of the name
+      uint16 :vna_flags # Flags
+      uint16 :vna_other # The index the symbols name this version with
+      uint32 :vna_name  # The name, as an offset into the string table
+      uint32 :vna_next  # Where the next version is, as an offset from here
+    end
+
+    # An entry of the table of versions a file defines, which the +vd_next+ of
+    # the one before it points at.
+    class ELF_Verdef < ELFStruct
+      endian :big_and_little
+      uint16 :vd_version # Revision of this structure
+      uint16 :vd_flags   # Flags
+      uint16 :vd_ndx     # The index the symbols name this version with
+      uint16 :vd_cnt     # How many names follow, the version and its ancestors
+      uint32 :vd_hash    # Hash of the name
+      uint32 :vd_aux     # Where the names start, as an offset from here
+      uint32 :vd_next    # Where the next entry is, as an offset from here
+    end
+
+    # A name an {ELF_Verdef} records, its own or an ancestor's, which the
+    # +vda_next+ of the one before it points at.
+    class ELF_Verdaux < ELFStruct
+      endian :big_and_little
+      uint32 :vda_name # The name, as an offset into the string table
+      uint32 :vda_next # Where the next name is, as an offset from here
+    end
+
     # Note header.
     class ELF_Nhdr < ELFStruct
       endian :big_and_little

data/lib/elftools/util.rb

@@ -3,6 +3,11 @@
 module ELFTools
   # Define some util methods.
   module Util
+    # How many bytes {ClassMethods#cstring} takes from a stream at a time. Long
+    # enough that a name is usually read in one, short enough that reading one
+    # never reaches far past its end.
+    CSTRING_CHUNK = 64
+
     # Class methods.
     module ClassMethods
       # Round up the number to be multiple of
@@ -23,6 +28,26 @@ module ELFTools
         (num + n) & ~(n - 1)
       end
 
+      # Checks a value is one the bits recording it can hold.
+      #
+      # Several of the values a file records share a byte with others, so a
+      # value too large for its bits would be written over its neighbours
+      # instead of being rejected.
+      # @param [Integer] value The value.
+      # @param [Integer] bits How many bits record it.
+      # @param [String] name What the value is, for the error to name.
+      # @return [Integer] The value.
+      # @raise [ArgumentError] If the bits cannot hold it.
+      # @example
+      #   Util.fits!(16, 4, 'Symbol binding')
+      #   #=> ArgumentError: Symbol binding must be in 0..15, got 16
+      def fits!(value, bits, name)
+        highest = (1 << bits) - 1
+        return value if value.is_a?(Integer) && value.between?(0, highest)
+
+        raise ArgumentError, format('%s must be in 0..%d, got %p', name, highest, value)
+      end
+
       # Fetch the correct value from module +mod+.
       #
       # See {ELFTools::ELFFile#segment_by_type} for how to
@@ -38,20 +63,22 @@ module ELFTools
         module_name = mod.name.sub('ELFTools::', '')
         # if val is an integer, check if exists in mod
         if val.is_a?(Integer)
-          return val if mod.constants.any? { |c| mod.const_get(c) == val }
+          return val if values_of(mod).key?(val)
 
           raise ArgumentError, "No constants in #{module_name} is #{val}"
         end
         val = val.to_s.upcase
         prefix = module_name.split('::')[-1]
         val = "#{prefix}_#{val}" unless val.start_with?(prefix)
-        val = val.to_sym
-        raise ArgumentError, "No constants in #{module_name} named \"#{val}\"" unless mod.const_defined?(val)
+        value = constants_of(mod)[val]
+        raise ArgumentError, "No constants in #{module_name} named \"#{val}\"" if value.nil?
 
-        mod.const_get(val)
+        value
       end
 
       # Read from stream until reach a null-byte.
+      #
+      # The stream is left just past the null-byte.
       # @param [#pos=, #read] stream Streaming object.
       # @param [Integer] offset Start from here.
       # @return [String] Result string will never contain null byte.
@@ -60,16 +87,19 @@ module ELFTools
       #   #=> "\x7FELF\x02\x01\x01"
       def cstring(stream, offset)
         stream.pos = offset
-        # read until "\x00"
-        ret = ''
+        ret = +''
         loop do
-          c = stream.read(1)
-          return nil if c.nil? # reach EOF
-          break if c == "\x00"
+          chunk = stream.read(CSTRING_CHUNK)
+          return nil if chunk.nil? # reach EOF
+
+          stop = chunk.index("\x00")
+          if stop
+            stream.pos = offset + ret.bytesize + stop + 1
+            return ret << chunk.byteslice(0, stop)
+          end
 
-          ret += c
+          ret << chunk
         end
-        ret
       end
 
       # Select objects from enumerator with +.type+ property
@@ -93,6 +123,33 @@ module ELFTools
           end
         end
       end
+
+      private
+
+      # What a module names each of its constants, and what each is worth.
+      #
+      # Names are compared upcased, which is how a constant keeping the case
+      # the ABI wrote it in, +SHT_GNU_verneed+ for one, is found by the name it
+      # is asked for. Read once per module, because reading them is more work
+      # than the lookup it is for.
+      # @param [Module] mod The module.
+      # @return [Hash{String => Integer}] The constants, by their upcased name.
+      def constants_of(mod)
+        (@constants_of ||= {})[mod] ||= mod.constants.each_with_object({}) do |constant, table|
+          # A constant still waiting to be autoloaded is left alone, so that
+          # asking after one never loads what nothing has asked for.
+          next if mod.autoload?(constant)
+
+          table[constant.to_s.upcase] ||= mod.const_get(constant)
+        end
+      end
+
+      # Which values a module names a constant for.
+      # @param [Module] mod The module.
+      # @return [Hash{Integer => Boolean}] The values, as the keys.
+      def values_of(mod)
+        (@values_of ||= {})[mod] ||= constants_of(mod).values.to_h { |value| [value, true] }
+      end
     end
     extend ClassMethods
   end

data/lib/elftools/version.rb

@@ -2,5 +2,5 @@
 
 module ELFTools
   # Current gem version
-  VERSION = '2.0.0'
+  VERSION = '2.2.0'
 end