elftools 1.3.1 → 2.1.0

data/lib/elftools/sections/symbol.rb

@@ -0,0 +1,202 @@
+# frozen_string_literal: true
+
+require 'elftools/constants'
+require 'elftools/util'
+
+module ELFTools
+  module Sections
+    # Class of symbol.
+    class Symbol
+      attr_reader :header # @return [ELFTools::Structs::ELF32_sym, ELFTools::Structs::ELF64_sym] Section header.
+      attr_reader :stream # @return [#pos=, #read] Streaming object.
+
+      # Instantiate a {ELFTools::Sections::Symbol} object.
+      # @param [ELFTools::Structs::ELF32_sym, ELFTools::Structs::ELF64_sym] header
+      #   The symbol header.
+      # @param [#pos=, #read] stream The streaming object.
+      # @param [ELFTools::Sections::StrTabSection, Proc] symstr
+      #   The symbol string section.
+      #   If +Proc+ is given, it will be called at the first time
+      #   access {Symbol#name}.
+      # @param [Integer] machine
+      #   The machine of the ELF file, which a name of a value depends on.
+      # @param [Proc] version
+      #   Call this to get the version this symbol binds to, which only the
+      #   symbols a file is loaded by have.
+      def initialize(header, stream, symstr: nil, machine: nil, version: nil)
+        @header = header
+        @stream = stream
+        @symstr = symstr
+        @machine = machine
+        @version = version
+      end
+
+      # Return the symbol name.
+      # @return [String] The name.
+      def name
+        @name ||= @symstr.call.name_at(header.st_name)
+      end
+
+      # The version this symbol binds to.
+      #
+      # Only the symbols a file is loaded by have one, and only where the file
+      # records the versions at all. {#name} is left as the file records it,
+      # without the version appended.
+      # @return [String, nil] The name of the version.
+      # @example
+      #   elf.dynamic.symbol_by_name('printf').version
+      #   #=> 'GLIBC_2.2.5'
+      def version
+        binding_version&.name
+      end
+
+      # Whether {#version} is one the symbol asks for by name rather than the
+      # default one of its name.
+      # @return [Boolean] The answer.
+      def version_hidden?
+        binding_version&.hidden? || false
+      end
+
+      # What this symbol is worth, which for most of them is the address of
+      # what they name.
+      #
+      # A symbol of a file that is not loaded anywhere records an offset into
+      # the section holding it instead, and one the linker is still to place,
+      # which {ELFTools::Constants::SHN_COMMON} marks, records the alignment it
+      # needs. The ABI leaves the field to the kind of symbol for that reason,
+      # and this answers with what is recorded either way.
+      # @return [Integer] The value.
+      # @example
+      #   elf.section_by_name('.symtab').symbol_by_name('main').value
+      #   #=> 4196061 # 0x4006dd
+      def value
+        header.st_value.to_i
+      end
+
+      # How many bytes what this symbol names takes.
+      # @return [Integer] The number, zero where the file records none.
+      # @example
+      #   elf.section_by_name('.symtab').symbol_by_name('main').size
+      #   #=> 142
+      def size
+        header.st_size.to_i
+      end
+
+      # What kind of entity this symbol refers to.
+      #
+      # The available types are listed in {ELFTools::Constants::STT}.
+      # @return [Integer] The type.
+      # @example
+      #   symbol.type == ELFTools::Constants::STT_FUNC
+      #   #=> true
+      def type
+        header.st_info & 0xf
+      end
+
+      # Sets what kind of entity this symbol refers to.
+      # @param [Integer] type The type.
+      # @raise [ArgumentError] If the four bits recording it cannot hold it.
+      # @example
+      #   symbol.type = ELFTools::Constants::STT_FUNC
+      def type=(type)
+        header.st_info = (bind << 4) | Util.fits!(type, 4, 'Symbol type')
+      end
+
+      # The name of {#type}.
+      #
+      # A machine names types of its own, so the name is only known when the
+      # machine of the file is.
+      # @return [String] The name.
+      # @example
+      #   symbol.type_name
+      #   #=> 'STT_FUNC'
+      def type_name
+        Constants::STT.mapping(@machine, type)
+      end
+
+      # How this symbol is linked against others with the same name.
+      #
+      # The available bindings are listed in {ELFTools::Constants::STB}.
+      # @return [Integer] The binding.
+      # @example
+      #   symbol.bind == ELFTools::Constants::STB_GLOBAL
+      #   #=> true
+      def bind
+        header.st_info >> 4
+      end
+
+      # Sets how this symbol is linked against others with the same name.
+      # @param [Integer] bind The binding.
+      # @raise [ArgumentError] If the four bits recording it cannot hold it.
+      # @example
+      #   symbol.bind = ELFTools::Constants::STB_WEAK
+      def bind=(bind)
+        header.st_info = (Util.fits!(bind, 4, 'Symbol binding') << 4) | type
+      end
+
+      # The name of {#bind}.
+      # @return [String] The name.
+      # @example
+      #   symbol.bind_name
+      #   #=> 'STB_GLOBAL'
+      def bind_name
+        Constants::STB.mapping(@machine, bind)
+      end
+
+      # How this symbol is accessed once it becomes part of an executable or
+      # shared object.
+      #
+      # The available visibilities are listed in {ELFTools::Constants::STV}.
+      # @return [Integer] The visibility.
+      # @example
+      #   symbol.visibility == ELFTools::Constants::STV_HIDDEN
+      #   #=> true
+      def visibility
+        header.st_other & 0x3
+      end
+
+      # Sets how this symbol is accessed once it becomes part of an executable
+      # or shared object.
+      #
+      # The rest of +st_other+ is left alone, which some machines record their
+      # own thing in.
+      # @param [Integer] visibility The visibility.
+      # @raise [ArgumentError] If the two bits recording it cannot hold it.
+      # @example
+      #   symbol.visibility = ELFTools::Constants::STV_HIDDEN
+      def visibility=(visibility)
+        header.st_other = (header.st_other.to_i & 0xfc) | Util.fits!(visibility, 2, 'Symbol visibility')
+      end
+
+      # The name of {#visibility}.
+      # @return [String] The name.
+      # @example
+      #   symbol.visibility_name
+      #   #=> 'STV_DEFAULT'
+      def visibility_name
+        Constants::STV.mapping(@machine, visibility)
+      end
+
+      # The version this symbol binds to, whatever is asked of it.
+      # @return [ELFTools::Dynamic::Versions::Version, nil] The version.
+      def binding_version
+        return @binding_version if defined?(@binding_version)
+
+        @binding_version = @version&.call
+      end
+      private :binding_version
+
+      # The index of the section this symbol is defined in.
+      #
+      # Values in {ELFTools::Constants::SHN} have special meanings instead of
+      # being an index.
+      # @return [Integer] The section index.
+      # @example
+      #   symbol.section_index == ELFTools::Constants::SHN_UNDEF
+      #   #=> true # the symbol is undefined and to be resolved at runtime
+      def section_index
+        header.st_shndx.to_i
+      end
+    end
+  end
+end

data/lib/elftools/sections/version_definition_section.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'elftools/sections/section'
+require 'elftools/version_tables'
+
+module ELFTools
+  module Sections
+    # Class of the section recording the versions a file defines for what it
+    # exports.
+    #
+    # This section is usually named .gnu.version_d, and records the very
+    # versions the +DT_VERDEF+ tag points at.
+    class VersionDefinitionSection < Section
+      # Instantiate a {VersionDefinitionSection} object.
+      # @param [ELFTools::Structs::ELF_Shdr] header
+      #   See {Section#initialize} for more information.
+      # @param [#pos=, #read] stream
+      #   See {Section#initialize} for more information.
+      # @param [Proc] section_at
+      #   The method for fetching other sections by index, which is where the
+      #   names are recorded.
+      def initialize(header, stream, section_at: nil, **_kwargs)
+        @section_at = section_at
+        super
+      end
+
+      # The versions this file defines for what it exports.
+      # @return [Array<ELFTools::VersionTables::Definition>]
+      #   The definitions, in the order the section records them.
+      # @example
+      #   section.definitions.map(&:name).first(3)
+      #   #=> ['libc.so.6', 'GLIBC_2.2.5', 'GLIBC_2.2.6']
+      def definitions
+        @definitions ||= VersionTables.new(stream, @section_at.call(header.sh_link),
+                                           endian: header.class.self_endian)
+                                      .definitions(header.sh_offset.to_i, header.sh_info.to_i)
+      end
+    end
+  end
+end

data/lib/elftools/sections/version_need_section.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'elftools/sections/section'
+require 'elftools/version_tables'
+
+module ELFTools
+  module Sections
+    # Class of the section recording the versions a file needs of the files it
+    # is loaded with.
+    #
+    # This section is usually named .gnu.version_r, and records the very
+    # versions the +DT_VERNEED+ tag points at.
+    class VersionNeedSection < Section
+      # Instantiate a {VersionNeedSection} object.
+      # @param [ELFTools::Structs::ELF_Shdr] header
+      #   See {Section#initialize} for more information.
+      # @param [#pos=, #read] stream
+      #   See {Section#initialize} for more information.
+      # @param [Proc] section_at
+      #   The method for fetching other sections by index, which is where the
+      #   names are recorded.
+      def initialize(header, stream, section_at: nil, **_kwargs)
+        @section_at = section_at
+        super
+      end
+
+      # The versions this file needs of the files it is loaded with.
+      # @return [Array<ELFTools::VersionTables::Requirement>]
+      #   The requirements, in the order the section records them.
+      # @example
+      #   section.requirements.map { |need| [need.file, need.versions.map(&:name)] }
+      #   #=> [['libc.so.6', ['GLIBC_2.4', 'GLIBC_2.2.5']]]
+      def requirements
+        @requirements ||= VersionTables.new(stream, @section_at.call(header.sh_link),
+                                            endian: header.class.self_endian)
+                                       .requirements(header.sh_offset.to_i, header.sh_info.to_i)
+      end
+    end
+  end
+end

data/lib/elftools/sections/version_section.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require 'elftools/sections/section'
+
+module ELFTools
+  module Sections
+    # Class of the section recording which version each symbol binds to.
+    #
+    # This section is usually named .gnu.version, and holds an index per symbol
+    # of the table its +sh_link+ names, the very indices the +DT_VERSYM+ tag
+    # points at.
+    class VersionSection < Section
+      # How many symbols the section records a version for.
+      # @return [Integer] The number.
+      def num_versions
+        header.sh_size.to_i / entry_size
+      end
+
+      # What the +n+-th symbol records as its version, which is an index into
+      # the versions a file needs or defines, with the highest bit marking a
+      # version the symbol asks for by name rather than the default one.
+      # @param [Integer] n The symbol index.
+      # @return [Integer, nil] The index, +nil+ if the section records none for it.
+      # @example
+      #   section.version_at(1)
+      #   #=> 2
+      def version_at(n)
+        return if n.negative? || n >= num_versions
+
+        stream.pos = header.sh_offset.to_i + (n * entry_size)
+        stream.read(entry_size).unpack1(header.class.self_endian == :big ? 'S>' : 'S<')
+      end
+
+      private
+
+      # What an entry takes, which the section records and the format fixes at
+      # two bytes either way.
+      # @return [Integer] The number of bytes.
+      def entry_size
+        2
+      end
+    end
+  end
+end

data/lib/elftools/segments/dynamic_segment.rb

@@ -10,6 +10,7 @@ module ELFTools
     # This class knows how to get the list of dynamic tags.
     class DynamicSegment < Segment
       include Dynamic # rock!
+
       # Get the start address of tags.
       # @return [Integer] Start address of tags.
       def tag_start

data/lib/elftools/segments/load_segment.rb

@@ -49,6 +49,29 @@ module ELFTools
         mem_head + mem_size
       end
 
+      # Returns the lowest virtual address backed by this segment's file content.
+      #
+      # A segment is mapped from an aligned boundary, so the addresses preceding
+      # {#mem_head} within the same alignment unit are backed by this segment as
+      # well. The bound is clamped to the address of the first byte of the file,
+      # so that a malformed ELF, whose +p_offset+ and +p_vaddr+ are not congruent
+      # modulo +p_align+, cannot be converted into a negative file offset.
+      # @return [Integer]
+      #   The vma.
+      def mapped_head
+        [header.p_vaddr.to_i & -header.p_align.to_i, mem_head - file_head].max
+      end
+
+      # Returns the end virtual address backed by this segment's file content.
+      #
+      # Addresses in between this and {#mem_tail} occupy memory but have no
+      # content in file, therefore cannot be converted into a file offset.
+      # @return [Integer]
+      #   The vma.
+      def mapped_tail
+        mem_head + size
+      end
+
       # Query if the given file offset located in this segment.
       # @param [Integer] offset
       #   File offset.
@@ -56,27 +79,32 @@ module ELFTools
       #   Size.
       # @return [Boolean]
       def offset_in?(offset, size = 0)
-        file_head <= offset && offset + size < file_tail
+        file_head <= offset && offset + size <= file_tail
       end
 
       # Convert file offset into virtual memory address.
+      #
+      # The conversion is a shift by a constant, so it holds no matter +p_offset+
+      # is aligned with +p_vaddr+ or not.
       # @param [Integer] offset
       #   File offset.
       # @return [Integer]
       def offset_to_vma(offset)
-        # XXX: What if file_head is not aligned with p_vaddr (which is invalid according to ELF spec)?
         offset - file_head + header.p_vaddr
       end
 
-      # Query if the given virtual memory address located in this segment.
+      # Query if the given virtual memory address is backed by this segment's
+      # file content.
+      #
+      # Only addresses in between {#mapped_head} and {#mapped_tail} can be
+      # converted into a file offset, see {#vma_to_offset}.
       # @param [Integer] vma
       #   Virtual memory address.
       # @param [Integer] size
       #   Size.
       # @return [Boolean]
       def vma_in?(vma, size = 0)
-        vma >= (header.p_vaddr & -header.p_align) &&
-          vma + size <= mem_tail
+        vma >= mapped_head && vma + size <= mapped_tail
       end
 
       # Convert virtual memory address into file offset.

data/lib/elftools/segments/segment.rb

@@ -14,10 +14,14 @@ module ELFTools
       #   Streaming object.
       # @param [Method] offset_from_vma
       #   The method to get offset of file, given virtual memory address.
-      def initialize(header, stream, offset_from_vma: nil)
+      # @param [Integer] machine
+      #   The machine of the ELF file, which decides what the entries a
+      #   segment points at mean. This should be +e_machine+ of the ELF header.
+      def initialize(header, stream, offset_from_vma: nil, machine: nil, **_kwargs)
         @header = header
         @stream = stream
         @offset_from_vma = offset_from_vma
+        @machine = machine
       end
 
       # Return +header.p_type+ in a simpler way.
@@ -37,19 +41,19 @@ module ELFTools
       # Is this segment readable?
       # @return [Boolean] True or false.
       def readable?
-        (header.p_flags & 4) == 4
+        header.p_flags.allbits?(4)
       end
 
       # Is this segment writable?
       # @return [Boolean] True or false.
       def writable?
-        (header.p_flags & 2) == 2
+        header.p_flags.allbits?(2)
       end
 
       # Is this segment executable?
       # @return [Boolean] True or false.
       def executable?
-        (header.p_flags & 1) == 1
+        header.p_flags.allbits?(1)
       end
     end
   end

data/lib/elftools/structs.rb

@@ -18,37 +18,88 @@ module ELFTools
       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.
         #
         # +BinData::Record+ doesn't allow us to override +#initialize+, so we hack +new+ here.
+        #
+        # Keyword arguments have to be taken as a trailing +Hash+ instead of +**kwargs+: bindata
+        # defines +new+ on each record class taking +*args+ only, then re-dispatches it to the
+        # endian-specific subclass this method actually runs on, which collapses the caller's
+        # keywords into a positional +Hash+ on the way. See +override_new_in_class+ in
+        # https://github.com/dmendel/bindata/blob/master/lib/bindata/dsl.rb, which is the same in
+        # 2.5.1, 3.0.0, and master.
         def new(*args)
-          # XXX: The better implementation is +new(*args, **kwargs)+, but we can't do this unless bindata changed
-          # lib/bindata/dsl.rb#override_new_in_class to invoke +new+ with both +args+ and +kwargs+.
           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}=".to_sym
-              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.
@@ -58,6 +109,10 @@ module ELFTools
         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]
@@ -179,6 +234,65 @@ module ELFTools
       64 => ELF64_sym
     }.freeze
 
+    # Header of the symbol hash table +DT_HASH+ points at.
+    class ELF_Hash < ELFStruct
+      endian :big_and_little
+      uint32 :nbucket # Number of buckets
+      uint32 :nchain  # Number of chains, which is how many symbols there are
+    end
+
+    # Header of the symbol hash table +DT_GNU_HASH+ points at.
+    class ELF_GnuHash < ELFStruct
+      endian :big_and_little
+      uint32 :nbuckets  # Number of buckets
+      uint32 :symndx    # The first symbol index the table indexes
+      uint32 :maskwords # Number of words the bloom filter takes
+      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