elftools 1.3.0 → 2.0.0

data/lib/elftools/sections/symbol.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'elftools/constants'
+
+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.
+      def initialize(header, stream, symstr: nil, machine: nil)
+        @header = header
+        @stream = stream
+        @symstr = symstr
+        @machine = machine
+      end
+
+      # Return the symbol name.
+      # @return [String] The name.
+      def name
+        @name ||= @symstr.call.name_at(header.st_name)
+      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
+
+      # 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
+
+      # 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
+
+      # The name of {#visibility}.
+      # @return [String] The name.
+      # @example
+      #   symbol.visibility_name
+      #   #=> 'STV_DEFAULT'
+      def visibility_name
+        Constants::STV.mapping(@machine, visibility)
+      end
+
+      # 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/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

@@ -31,15 +31,20 @@ module ELFTools
         # 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
+              m = :"#{f}="
               old_method = obj.singleton_method(m)
               obj.singleton_class.send(:undef_method, m)
               obj.define_singleton_method(m) do |val|
@@ -179,6 +184,22 @@ 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
+
     # Note header.
     class ELF_Nhdr < ELFStruct
       endian :big_and_little

data/lib/elftools/util.rb

@@ -52,7 +52,7 @@ module ELFTools
       end
 
       # Read from stream until reach a null-byte.
-      # @param [#pos=, #read] stream Streaming object
+      # @param [#pos=, #read] stream Streaming object.
       # @param [Integer] offset Start from here.
       # @return [String] Result string will never contain null byte.
       # @example

data/lib/elftools/version.rb

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

metadata

@@ -1,29 +1,34 @@
 --- !ruby/object:Gem::Specification
 name: elftools
 version: !ruby/object:Gem::Version
-  version: 1.3.0
+  version: 2.0.0
 platform: ruby
 authors:
 - david942j
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2024-02-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bindata
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4'
 - !ruby/object:Gem::Dependency
   name: os
   requirement: !ruby/object:Gem::Requirement
@@ -100,14 +105,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.21'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.21'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -134,11 +139,96 @@ files:
 - README.md
 - lib/elftools.rb
 - lib/elftools/constants.rb
+- lib/elftools/constants/machine.rb
+- lib/elftools/constants/machine_names.rb
+- lib/elftools/constants/relocation.rb
+- lib/elftools/constants/relocation/aarch64.rb
+- lib/elftools/constants/relocation/alpha.rb
+- lib/elftools/constants/relocation/amdgpu.rb
+- lib/elftools/constants/relocation/arm.rb
+- lib/elftools/constants/relocation/avr.rb
+- lib/elftools/constants/relocation/bfin.rb
+- lib/elftools/constants/relocation/bpf.rb
+- lib/elftools/constants/relocation/cr16.rb
+- lib/elftools/constants/relocation/cris.rb
+- lib/elftools/constants/relocation/crx.rb
+- lib/elftools/constants/relocation/csky.rb
+- lib/elftools/constants/relocation/d10v.rb
+- lib/elftools/constants/relocation/d30v.rb
+- lib/elftools/constants/relocation/dlx.rb
+- lib/elftools/constants/relocation/epiphany.rb
+- lib/elftools/constants/relocation/fr30.rb
+- lib/elftools/constants/relocation/frv.rb
+- lib/elftools/constants/relocation/ft32.rb
+- lib/elftools/constants/relocation/h8.rb
+- lib/elftools/constants/relocation/hppa.rb
+- lib/elftools/constants/relocation/i370.rb
+- lib/elftools/constants/relocation/i386.rb
+- lib/elftools/constants/relocation/i860.rb
+- lib/elftools/constants/relocation/i960.rb
+- lib/elftools/constants/relocation/ia64.rb
+- lib/elftools/constants/relocation/ip2k.rb
+- lib/elftools/constants/relocation/iq2000.rb
+- lib/elftools/constants/relocation/kvx.rb
+- lib/elftools/constants/relocation/lm32.rb
+- lib/elftools/constants/relocation/loongarch.rb
+- lib/elftools/constants/relocation/m32c.rb
+- lib/elftools/constants/relocation/m32r.rb
+- lib/elftools/constants/relocation/m68hc11.rb
+- lib/elftools/constants/relocation/m68k.rb
+- lib/elftools/constants/relocation/mcore.rb
+- lib/elftools/constants/relocation/mep.rb
+- lib/elftools/constants/relocation/metag.rb
+- lib/elftools/constants/relocation/microblaze.rb
+- lib/elftools/constants/relocation/mips.rb
+- lib/elftools/constants/relocation/mmix.rb
+- lib/elftools/constants/relocation/mn10200.rb
+- lib/elftools/constants/relocation/mn10300.rb
+- lib/elftools/constants/relocation/moxie.rb
+- lib/elftools/constants/relocation/msp430.rb
+- lib/elftools/constants/relocation/msp430x.rb
+- lib/elftools/constants/relocation/mt.rb
+- lib/elftools/constants/relocation/nds32.rb
+- lib/elftools/constants/relocation/nfp.rb
+- lib/elftools/constants/relocation/nfp3200.rb
+- lib/elftools/constants/relocation/nios2.rb
+- lib/elftools/constants/relocation/or1k.rb
+- lib/elftools/constants/relocation/pj.rb
+- lib/elftools/constants/relocation/ppc.rb
+- lib/elftools/constants/relocation/ppc64.rb
+- lib/elftools/constants/relocation/pru.rb
+- lib/elftools/constants/relocation/riscv.rb
+- lib/elftools/constants/relocation/rl78.rb
+- lib/elftools/constants/relocation/rx.rb
+- lib/elftools/constants/relocation/s12z.rb
+- lib/elftools/constants/relocation/s390.rb
+- lib/elftools/constants/relocation/score.rb
+- lib/elftools/constants/relocation/sh.rb
+- lib/elftools/constants/relocation/sparc.rb
+- lib/elftools/constants/relocation/spu.rb
+- lib/elftools/constants/relocation/tic6x.rb
+- lib/elftools/constants/relocation/tilegx.rb
+- lib/elftools/constants/relocation/tilepro.rb
+- lib/elftools/constants/relocation/v800.rb
+- lib/elftools/constants/relocation/v850.rb
+- lib/elftools/constants/relocation/vax.rb
+- lib/elftools/constants/relocation/visium.rb
+- lib/elftools/constants/relocation/wasm32.rb
+- lib/elftools/constants/relocation/x86_64.rb
+- lib/elftools/constants/relocation/xgate.rb
+- lib/elftools/constants/relocation/xstormy16.rb
+- lib/elftools/constants/relocation/xtensa.rb
+- lib/elftools/constants/relocation/z80.rb
 - lib/elftools/dynamic.rb
+- lib/elftools/dynamic/hash_table.rb
+- lib/elftools/dynamic/string_table.rb
+- lib/elftools/dynamic/symbols.rb
+- lib/elftools/dynamic/tag.rb
 - lib/elftools/elf_file.rb
 - lib/elftools/exceptions.rb
 - lib/elftools/lazy_array.rb
 - lib/elftools/note.rb
+- lib/elftools/relocation.rb
 - lib/elftools/sections/dynamic_section.rb
 - lib/elftools/sections/note_section.rb
 - lib/elftools/sections/null_section.rb
@@ -147,6 +237,7 @@ files:
 - lib/elftools/sections/sections.rb
 - lib/elftools/sections/str_tab_section.rb
 - lib/elftools/sections/sym_tab_section.rb
+- lib/elftools/sections/symbol.rb
 - lib/elftools/segments/dynamic_segment.rb
 - lib/elftools/segments/interp_segment.rb
 - lib/elftools/segments/load_segment.rb
@@ -161,7 +252,7 @@ licenses:
 - MIT
 metadata:
   rubygems_mfa_required: 'true'
-post_install_message: 
+  changelog_uri: https://github.com/david942j/rbelftools/blob/v2.0.0/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -169,15 +260,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: ELFTools - Pure ruby library for parsing and patching ELF files
 test_files: []