elftools 1.3.1 → 2.0.0

data/lib/elftools/elf_file.rb

@@ -59,6 +59,25 @@ module ELFTools
       note.desc.unpack1('H*')
     end
 
+    # The dynamic tags of this file, read from the view that its type makes
+    # authoritative.
+    #
+    # A relocatable file is linked by its sections, so its sections answer and
+    # any segment it carries is disregarded, being something no linker reads.
+    # An executable or a shared object is loaded by its segments alone, so the
+    # segment answers and the section recording the same tags is metadata a
+    # tool may have stripped or rewritten.
+    # @return [ELFTools::Segments::DynamicSegment, ELFTools::Sections::DynamicSection, nil]
+    #   The tags, +nil+ if the view that decides records none.
+    # @example
+    #   elf.dynamic.tag_by_type(:needed).name
+    #   #=> 'libc.so.6'
+    def dynamic
+      return sections_by_type(:dynamic).first if header.e_type.to_i == Constants::ET_REL
+
+      segment_by_type(:dynamic) || sections_by_type(:dynamic).first
+    end
+
     # Get machine architecture.
     #
     # Mappings of architecture can be found
@@ -67,7 +86,7 @@ module ELFTools
     #   Name of architecture.
     # @example
     #   elf.machine
-    #   #=> 'Advanced Micro Devices X86-64'
+    #   #=> 'Advanced Micro Devices X86-64 processor'
     def machine
       ELFTools::Constants::EM.mapping(header.e_machine)
     end
@@ -105,7 +124,7 @@ module ELFTools
     #   elf.section_by_name('no such section')
     #   #=> nil
     def section_by_name(name)
-      each_sections.find { |sec| sec.name == name }
+      each_section.find { |sec| sec.name == name }
     end
 
     # Iterate all sections.
@@ -119,19 +138,22 @@ module ELFTools
     # @return [Enumerator<ELFTools::Sections::Section>, Array<ELFTools::Sections::Section>]
     #   As +Array#each+, if block is not given, a enumerator will be returned,
     #   otherwise, the whole sections will be returned.
-    def each_sections(&block)
-      return enum_for(:each_sections) unless block_given?
+    def each_section(&block)
+      return enum_for(:each_section) unless block_given?
 
       Array.new(num_sections) do |i|
         section_at(i).tap(&block)
       end
     end
 
+    # The name this used to go by, kept so that it keeps working.
+    alias each_sections each_section
+
     # Simply use {#sections} to get all sections.
     # @return [Array<ELFTools::Sections::Section>]
     #   Whole sections.
     def sections
-      each_sections.to_a
+      each_section.to_a
     end
 
     # Acquire the +n+-th section, 0-based.
@@ -160,17 +182,21 @@ module ELFTools
     #   elf.sections_by_type(:rela)
     #   #=> [#<ELFTools::Sections::RelocationSection:0x00563cd3219970>,
     #   #    #<ELFTools::Sections::RelocationSection:0x00563cd3b89d70>]
-    def sections_by_type(type, &block)
+    def sections_by_type(type, &)
       type = Util.to_constant(Constants::SHT, type)
-      Util.select_by_type(each_sections, type, &block)
+      Util.select_by_type(each_section, type, &)
     end
 
-    # Get the string table section.
+    # The section the names of the sections are recorded in, which the ELF
+    # header names by index.
     #
-    # This section is acquired by using the +e_shstrndx+
-    # in ELF header.
-    # @return [ELFTools::Sections::StrTabSection] The desired section.
-    def strtab_section
+    # It is not the section the names of the symbols are recorded in, which
+    # {ELFTools::Sections::SymTabSection#symstr} answers.
+    # @return [ELFTools::Sections::StrTabSection] The section.
+    # @example
+    #   elf.section_name_table.name
+    #   #=> '.shstrtab'
+    def section_name_table
       section_at(header.e_shstrndx)
     end
 
@@ -192,19 +218,22 @@ module ELFTools
     # @yieldreturn [void]
     # @return [Array<ELFTools::Segments::Segment>]
     #   Whole segments will be returned.
-    def each_segments(&block)
-      return enum_for(:each_segments) unless block_given?
+    def each_segment(&block)
+      return enum_for(:each_segment) unless block_given?
 
       Array.new(num_segments) do |i|
         segment_at(i).tap(&block)
       end
     end
 
+    # The name this used to go by, kept so that it keeps working.
+    alias each_segments each_segment
+
     # Simply use {#segments} to get all segments.
     # @return [Array<ELFTools::Segments::Segment>]
     #   Whole segments.
     def segments
-      each_segments.to_a
+      each_segment.to_a
     end
 
     # Get the first segment with +p_type=type+.
@@ -250,7 +279,7 @@ module ELFTools
     #   #=> nil # no such segment exists
     def segment_by_type(type)
       type = Util.to_constant(Constants::PT, type)
-      each_segments.find { |seg| seg.header.p_type == type }
+      each_segment.find { |seg| seg.header.p_type == type }
     end
 
     # Fetch all segments with specific type.
@@ -263,9 +292,9 @@ module ELFTools
     # @yieldparam [ELFTools::Segments::Segment] segment A segment in specific type.
     # @yieldreturn [void]
     # @return [Array<ELFTools::Segments::Segment>] The target segments.
-    def segments_by_type(type, &block)
+    def segments_by_type(type, &)
       type = Util.to_constant(Constants::PT, type)
-      Util.select_by_type(each_segments, type, &block)
+      Util.select_by_type(each_segment, type, &)
     end
 
     # Acquire the +n+-th segment, 0-based.
@@ -285,7 +314,7 @@ module ELFTools
     # This method should work no matter ELF is a PIE or not.
     # This method refers from (actually equals to) binutils/readelf.c#offset_from_vma.
     # @param [Integer] vma The virtual address to be queried.
-    # @return [Integer] Related file offset.
+    # @return [Integer?] Related file offset. +nil+ if the queried region has no content in file.
     # @example
     #   elf = ELFTools::ELFFile.new(File.open('/bin/cat'))
     #   elf.offset_from_vma(0x401337)
@@ -294,6 +323,25 @@ module ELFTools
       segments_by_type(:load) do |seg|
         return seg.vma_to_offset(vma) if seg.vma_in?(vma, size)
       end
+
+      nil
+    end
+
+    # Get virtual address given offset in file
+    #
+    # @param [Integer] offset The file offset to be queried.
+    # @return [Integer?] Related virtual address. Note this is raw address, not always adjusted for base address.
+    #                    +nil+ if offset is invalid.
+    # @example
+    #   elf = ELFTools::ELFFile.new(File.open('/bin/cat'))
+    #   elf.vma_from_offset(0x1337)
+    #   #=> 0x401337
+    def vma_from_offset(offset, size = 1)
+      segments_by_type(:load) do |seg|
+        return seg.offset_to_vma(offset) if seg.offset_in?(offset, size)
+      end
+
+      nil
     end
 
     # The patch status.
@@ -363,15 +411,18 @@ module ELFTools
       shdr.read(stream)
       Sections::Section.create(shdr, stream,
                                offset_from_vma: method(:offset_from_vma),
-                               strtab: method(:strtab_section),
-                               section_at: method(:section_at))
+                               section_name_table: method(:section_name_table),
+                               section_at: method(:section_at),
+                               machine: header.e_machine.to_i)
     end
 
     def create_segment(n)
       stream.pos = header.e_phoff + n * header.e_phentsize
       phdr = Structs::ELF_Phdr[elf_class].new(endian:, offset: stream.pos)
       phdr.elf_class = elf_class
-      Segments::Segment.create(phdr.read(stream), stream, offset_from_vma: method(:offset_from_vma))
+      Segments::Segment.create(phdr.read(stream), stream,
+                               offset_from_vma: method(:offset_from_vma),
+                               machine: header.e_machine.to_i)
     end
   end
 end

data/lib/elftools/lazy_array.rb

@@ -7,6 +7,9 @@ module ELFTools
   # 'lazy loading' objects.
   # Mainly used when loading sections, segments, and
   # symbols.
+  #
+  # Only {#[]} loads an element on demand, any other method
+  # of +Array+ loads all elements before it operates.
   class LazyArray < SimpleDelegator
     # Instantiate a {LazyArray} object.
     # @param [Integer] size
@@ -28,7 +31,8 @@ module ELFTools
     #   p arr[3]
     #   # 9
     def initialize(size, &block)
-      super(Array.new(size))
+      @array = Array.new(size)
+      super(@array)
       @block = block
     end
 
@@ -36,14 +40,48 @@ module ELFTools
     #
     # Elements are lazy loaded at the first time
     # access it.
+    # @param [Integer] i
+    #   The index, negative index is *not* supported.
     # @return [Object]
     #   The element, returned type is the
     #   return type of block given in {#initialize}.
+    #   +nil+ if +i+ is out of bound.
     def [](i)
-      # XXX: support negative index?
-      return nil unless i.between?(0, __getobj__.size - 1)
+      return nil unless i.between?(0, size - 1)
 
-      __getobj__[i] ||= @block.call(i)
+      @array[i] ||= @block.call(i)
+    end
+
+    # The size of this array.
+    #
+    # This method never loads any element.
+    # @return [Integer]
+    #   The size given in {#initialize}.
+    def size
+      @array.size
+    end
+    alias length size
+
+    # Loads all elements.
+    #
+    # Called whenever a method other than {#[]} and {#size} is invoked, so that
+    # those methods operate on a fully loaded array.
+    # @return [Array]
+    #   The loaded array.
+    # @example
+    #   arr = LazyArray.new(3) { |i| i * i }
+    #   p arr.map { |v| v + 1 }
+    #   # [1, 2, 5]
+    def __getobj__
+      @array.each_index { |i| self[i] }
+      @array
+    end
+
+    private
+
+    # Queries the array without loading any element.
+    def respond_to_missing?(name, include_private = false)
+      @array.respond_to?(name, include_private)
     end
   end
 end

data/lib/elftools/note.rb

@@ -41,8 +41,8 @@ module ELFTools
     # @return [Enumerator<ELFTools::Note::Note>, Array<ELFTools::Note::Note>]
     #   If block is not given, an enumerator will be returned.
     #   Otherwise, return the array of notes.
-    def each_notes
-      return enum_for(:each_notes) unless block_given?
+    def each_note
+      return enum_for(:each_note) unless block_given?
 
       @notes_offset_map ||= {}
       cur = note_start
@@ -61,11 +61,14 @@ module ELFTools
       notes
     end
 
+    # The name this used to go by, kept so that it keeps working.
+    alias each_notes each_note
+
     # Simply +#notes+ to get all notes.
     # @return [Array<ELFTools::Note::Note>]
     #   Whole notes.
     def notes
-      each_notes.to_a
+      each_note.to_a
     end
 
     private

data/lib/elftools/relocation.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require 'elftools/constants'
+
+module ELFTools
+  # A relocation entry.
+  #
+  # Can be either a REL or RELA relocation.
+  class Relocation
+    attr_reader :header # @return [ELFTools::Structs::ELF_Rel, ELFTools::Structs::ELF_Rela] Rel(a) header.
+    attr_reader :stream # @return [#pos=, #read] Streaming object.
+
+    # Instantiate a {Relocation} object.
+    # @param [ELFTools::Structs::ELF_Rel, ELFTools::Structs::ELF_Rela] header
+    #   The relocation header.
+    # @param [#pos=, #read] stream The streaming object.
+    # @param [Integer] machine
+    #   The machine of the ELF file, which decides what {#type} means and how
+    #   {#header} records it.
+    def initialize(header, stream, machine: nil)
+      @header = header
+      @stream = stream
+      @machine = machine
+    end
+
+    # Which symbol this relocation is against, as an index into the symbol
+    # table.
+    # @return [Integer] The symbol index.
+    def symbol_index
+      sym_and_type.first
+    end
+
+    # What this relocation does, which only means something together with the
+    # machine of the file. {#type_name} names it.
+    # @return [Integer] The relocation type.
+    def type
+      sym_and_type.last
+    end
+
+    # The name of {#type}.
+    #
+    # Every architecture numbers relocation types on its own, so the name is
+    # only known when the machine of the file is.
+    # @return [String] The name.
+    # @example
+    #   relocation.type_name
+    #   #=> 'R_X86_64_JUMP_SLOT'
+    def type_name
+      Constants::R.mapping(@machine, type)
+    end
+
+    private
+
+    # What +r_info+ records, i.e. a symbol index and a relocation type. Most
+    # machines split the field in half between the two, one lays it out its
+    # own way.
+    # @return [Array(Integer, Integer)] The symbol index and the type.
+    def sym_and_type
+      return mips64_sym_and_type if mips64?
+
+      [header.r_info >> mask_bit, header.r_info & ((1 << mask_bit) - 1)]
+    end
+
+    # Whether the file records relocations the way the 64-bit MIPS ABI does,
+    # which is the one layout that departs from halving +r_info+.
+    # @return [Boolean] The answer.
+    def mips64?
+      @machine == Constants::EM_MIPS && header.elf_class == 64
+    end
+
+    # Reads +r_info+ as the 64-bit MIPS ABI records it, i.e. a symbol index of
+    # four bytes followed by four bytes the ABI keeps for itself, the last of
+    # which is the type reported here. Those bytes are ordered as the rest of
+    # the file is, which is why the two ends of the field swap places.
+    # @example
+    #   # A big endian file records the symbol index first,
+    #   #   00 00 00 08 | 00    05     18     07
+    #   #   sym         | ssym  type3  type2  type
+    #   0x0000000800051807 #=> [8, 7]
+    #   # a little endian one records the very same relocation as
+    #   0x0718050000000008 #=> [8, 7]
+    # @return [Array(Integer, Integer)] The symbol index and the type.
+    def mips64_sym_and_type
+      info = header.r_info.to_i
+      return [info >> 32, info & 0xff] if header.class.self_endian == :big
+
+      [info & 0xffff_ffff, info >> 56]
+    end
+
+    def mask_bit
+      header.elf_class == 32 ? 8 : 32
+    end
+  end
+end

data/lib/elftools/sections/dynamic_section.rb

@@ -12,6 +12,19 @@ module ELFTools
     class DynamicSection < Section
       include ELFTools::Dynamic
 
+      # Instantiate a {DynamicSection} object.
+      # @param [ELFTools::Structs::ELF_Shdr] header
+      #   See {Section#initialize} for more information.
+      # @param [#pos=, #read] stream
+      #   See {Section#initialize} for more information.
+      # @param [Integer] machine
+      #   The machine of the ELF file, which decides what the entries a tag
+      #   points at mean. This should be +e_machine+ of the ELF header.
+      def initialize(header, stream, machine: nil, **_kwargs)
+        @machine = machine
+        super
+      end
+
       # Get the start address of tags.
       # @return [Integer] Start address of tags.
       def tag_start

data/lib/elftools/sections/relocation_section.rb

@@ -1,14 +1,29 @@
 # frozen_string_literal: true
 
 require 'elftools/constants'
+require 'elftools/relocation'
 require 'elftools/sections/section'
 require 'elftools/structs'
 
 module ELFTools
   module Sections
-    # Class of note section.
-    # Note section records notes
+    # Class of relocation section.
+    # Usually for sections .rel.* and .rela.*,
+    # which record relocations in ELF file.
     class RelocationSection < Section
+      # Instantiate a {RelocationSection} object.
+      # @param [ELFTools::Structs::ELF_Shdr] header
+      #   See {Section#initialize} for more information.
+      # @param [#pos=, #read] stream
+      #   See {Section#initialize} for more information.
+      # @param [Integer] machine
+      #   The machine of the ELF file, which decides what a relocation type
+      #   means. This should be +e_machine+ of the ELF header.
+      def initialize(header, stream, machine: nil, **_kwargs)
+        @machine = machine
+        super
+      end
+
       # Is this relocation a RELA or REL type.
       # @return [Boolean] If is RELA.
       def rela?
@@ -42,19 +57,22 @@ module ELFTools
       # @return [Enumerator<ELFTools::Relocation>, Array<ELFTools::Relocation>]
       #   If block is not given, an enumerator will be returned.
       #   Otherwise, the whole relocations will be returned.
-      def each_relocations(&block)
-        return enum_for(:each_relocations) unless block_given?
+      def each_relocation(&block)
+        return enum_for(:each_relocation) unless block_given?
 
         Array.new(num_relocations) do |i|
           relocation_at(i).tap(&block)
         end
       end
 
+      # The name this used to go by, kept so that it keeps working.
+      alias each_relocations each_relocation
+
       # Simply use {#relocations} to get all relocations.
       # @return [Array<ELFTools::Relocation>]
       #   Whole relocations.
       def relocations
-        each_relocations.to_a
+        each_relocation.to_a
       end
 
       private
@@ -65,45 +83,8 @@ module ELFTools
         rel = klass.new(endian: header.class.self_endian, offset: stream.pos)
         rel.elf_class = header.elf_class
         rel.read(stream)
-        Relocation.new(rel, stream)
+        Relocation.new(rel, stream, machine: @machine)
       end
     end
   end
-
-  # A relocation entry.
-  #
-  # Can be either a REL or RELA relocation.
-  # XXX: move this to an independent file?
-  class Relocation
-    attr_reader :header # @return [ELFTools::Structs::ELF_Rel, ELFTools::Structs::ELF_Rela] Rel(a) header.
-    attr_reader :stream # @return [#pos=, #read] Streaming object.
-
-    # Instantiate a {Relocation} object.
-    def initialize(header, stream)
-      @header = header
-      @stream = stream
-    end
-
-    # +r_info+ contains sym and type, use two methods
-    # to access them easier.
-    # @return [Integer] sym infor.
-    def r_info_sym
-      header.r_info >> mask_bit
-    end
-    alias symbol_index r_info_sym
-
-    # +r_info+ contains sym and type, use two methods
-    # to access them easier.
-    # @return [Integer] type infor.
-    def r_info_type
-      header.r_info & ((1 << mask_bit) - 1)
-    end
-    alias type r_info_type
-
-    private
-
-    def mask_bit
-      header.elf_class == 32 ? 8 : 32
-    end
-  end
 end

data/lib/elftools/sections/section.rb

@@ -13,16 +13,16 @@ module ELFTools
       #   The section header object.
       # @param [#pos=, #read] stream
       #   The streaming object for further dump.
-      # @param [ELFTools::Sections::StrTabSection, Proc] strtab
+      # @param [ELFTools::Sections::StrTabSection, Proc] section_name_table
       #   The string table object. For fetching section names.
       #   If +Proc+ if given, it will call at the first
       #   time access +#name+.
       # @param [Method] offset_from_vma
       #   The method to get offset of file, given virtual memory address.
-      def initialize(header, stream, offset_from_vma: nil, strtab: nil, **_kwargs)
+      def initialize(header, stream, offset_from_vma: nil, section_name_table: nil, **_kwargs)
         @header = header
         @stream = stream
-        @strtab = strtab
+        @section_name_table = section_name_table
         @offset_from_vma = offset_from_vma
       end
 
@@ -36,7 +36,7 @@ module ELFTools
       # Get name of this section.
       # @return [String] The name.
       def name
-        @name ||= @strtab.call.name_at(header.sh_name)
+        @name ||= @section_name_table.call.name_at(header.sh_name)
       end
 
       # Fetch data of this section.

data/lib/elftools/sections/sym_tab_section.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'elftools/sections/section'
+require 'elftools/sections/symbol'
 
 module ELFTools
   module Sections
@@ -18,8 +19,12 @@ module ELFTools
       # @param [Proc] section_at
       #   The method for fetching other sections by index.
       #   This lambda should be {ELFTools::ELFFile#section_at}.
-      def initialize(header, stream, section_at: nil, **_kwargs)
+      # @param [Integer] machine
+      #   The machine of the ELF file, which decides what the fields of a
+      #   symbol mean. This should be +e_machine+ of the ELF header.
+      def initialize(header, stream, section_at: nil, machine: nil, **_kwargs)
         @section_at = section_at
+        @machine = machine
         # For faster #symbol_by_name
         super
       end
@@ -56,19 +61,22 @@ module ELFTools
       # @return [Enumerator<ELFTools::Sections::Symbol>, Array<ELFTools::Sections::Symbol>]
       #   If block is not given, an enumerator will be returned.
       #   Otherwise return array of symbols.
-      def each_symbols(&block)
-        return enum_for(:each_symbols) unless block_given?
+      def each_symbol(&block)
+        return enum_for(:each_symbol) unless block_given?
 
         Array.new(num_symbols) do |i|
           symbol_at(i).tap(&block)
         end
       end
 
+      # The name this used to go by, kept so that it keeps working.
+      alias each_symbols each_symbol
+
       # Simply use {#symbols} to get all symbols.
       # @return [Array<ELFTools::Sections::Symbol>]
       #   The whole symbols.
       def symbols
-        each_symbols.to_a
+        each_symbol.to_a
       end
 
       # Get symbol by its name.
@@ -76,7 +84,7 @@ module ELFTools
       #   The name of symbol.
       # @return [ELFTools::Sections::Symbol] Desired symbol.
       def symbol_by_name(name)
-        each_symbols.find { |symbol| symbol.name == name }
+        each_symbol.find { |symbol| symbol.name == name }
       end
 
       # Return the symbol string section.
@@ -92,35 +100,7 @@ module ELFTools
         stream.pos = header.sh_offset + n * header.sh_entsize
         sym = Structs::ELF_sym[header.elf_class].new(endian: header.class.self_endian, offset: stream.pos)
         sym.read(stream)
-        Symbol.new(sym, stream, symstr: method(:symstr))
-      end
-    end
-
-    # Class of symbol.
-    #
-    # XXX: Should this class be defined in an independent file?
-    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}.
-      def initialize(header, stream, symstr: nil)
-        @header = header
-        @stream = stream
-        @symstr = symstr
-      end
-
-      # Return the symbol name.
-      # @return [String] The name.
-      def name
-        @name ||= @symstr.call.name_at(header.st_name)
+        Symbol.new(sym, stream, symstr: method(:symstr), machine: @machine)
       end
     end
   end