memory_io 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f287dc7b3453557bbcda2f2ce09e03d779d0dbff69f8ef059069f03c76da427
-  data.tar.gz: a471ab55f6abd70783a220d0939cdd8f84231f59a533a6470a9f64119c184a41
+  metadata.gz: ae436fb71c1c77ce99b26657dc3e9497e8730ee578f0fe412186a67ee4881d12
+  data.tar.gz: 822612ae59c6c669a6136724dc9636349a3f6b3b314b20d3e024bc1481faf9e2
 SHA512:
-  metadata.gz: 959a45d2dcab5ced28be35f6988a6c6fadbd1fd6510e21747727f16e87cabddf23e951ffba71d8deec4baa1be440ce5bd79b1fe54e1bad66a17deb9185c54db9
-  data.tar.gz: a1fe1e032d09a53ce4611e2738255ac1444b5a0283e959606a1da232db28c9d0d42a7277977b17d2bb8fcfa476cc58c53368ad64fa970d0b7b91a5536e59e79e
+  metadata.gz: 1fc69554905f1fbd661045c65fd0570e0baea78191d531a7faa39157f9a5faa6618f3693a2cabd7f2117a7a849cd1fc5925123868103b8a414359ed49843068e
+  data.tar.gz: f5449be7a6af8e443e857492aa73533735fdc639d4215a79c4b7b0a7effae9db34d5511ec46fec11aba545185f0d6b9f9947ab02f9de88d17a10b78901a96c19

data/README.md

@@ -15,7 +15,7 @@ I usually need to dump a structure, say `string` in C++, from memory for debuggi
 This is not hard if using gdb.
 However, gdb doesn't support writing Ruby scripts
 (unless you use [gdb-ruby](https://github.com/david942j/gdb-ruby), which has **MemoryIO** as its dependency).
-So I created this projected to make the debug procedure much easier.
+So I created this project to make the debug procedure much easier.
 
 This repository has two main goals:
 
@@ -167,6 +167,34 @@ process.read('libc', 4)
 
 ## Developing
 
+```bash
+$ git clone https://github.com/david942j/memory_io
+$ cd memory_io
+$ bundle install
+$ bundle exec rake
+```
+
+The default rake task regenerates README.md, runs RuboCop, and runs all specs.
+
 ### To Add a New Structure
 
-TBA
+Pull Requests of new structures are welcome! Say you want to add the structure `Vec` of Rust:
+
+1. Create a file `lib/memory_io/types/rust/vec.rb`.
+2. Define class `MemoryIO::Types::Rust::Vec` and make it inherit from `MemoryIO::Types::Type`.
+   Types are registered automatically when the class is defined;
+   the symbols to access it are derived from the class name.
+   `MemoryIO::Types::Rust::Vec` gets the full-name `:'rust/vec'` and the alias `:vec`.
+3. Implement class method `read(stream)`, which reads bytes from `stream`
+   and returns an instance of your class.
+   Implement class method `write(stream, obj)` as well if the structure supports writing.
+   Some helper methods, such as `read_size_t` and `keep_pos`, are defined
+   in [Types::Type](https://www.rubydoc.info/github/david942j/memory_io/MemoryIO/Types/Type) for you.
+4. Write the doc-comment right above the class definition.
+   The first line of it will be shown in the section [Implemented Structures](#implemented-structures),
+   which is auto-generated by `rake readme`.
+5. Add specs in `spec/types/rust/vec_spec.rb`.
+6. Run `bundle exec rake` and make sure everything is green.
+
+See [lib/memory_io/types/cpp/string.rb](lib/memory_io/types/cpp/string.rb)
+([spec](spec/types/cpp/string_spec.rb)) as a complete example.

data/lib/memory_io/context.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'elftools'
+
+require 'memory_io/stream'
+
+module MemoryIO
+  # Describes how the memory being accessed lays out its data.
+  #
+  # The context belongs to the memory, not to the machine running this library.
+  # They only coincide when the memory belongs to a process on the same host.
+  class Context
+    # Byte orders that can be asked for. +:native+ resolves to the byte order
+    # of the host, which is the right answer whenever the memory belongs to a
+    # process running on it.
+    ENDIANS = %i[little big native].freeze
+
+    # The byte order of the host.
+    NATIVE_ENDIAN = [1].pack('S') == "\x01\x00".b ? :little : :big
+
+    # Assumed when nothing more specific is known.
+    DEFAULT_POINTER_SIZE = 8
+
+    # @return [:little, :big]
+    #   Byte order of the memory. +:native+ has already been resolved.
+    attr_reader :endian
+
+    # @return [Integer]
+    #   Size of a pointer, in bytes.
+    attr_reader :pointer_size
+
+    # @return [Hash]
+    #   The attributes, in the form {#initialize} accepts.
+    def to_h
+      { endian: endian, pointer_size: pointer_size }
+    end
+
+    # @param [:little, :big, :native] endian
+    #   Byte order of the memory.
+    # @param [Integer] pointer_size
+    #   Size of a pointer, in bytes.
+    #
+    # @raise [ArgumentError]
+    #   +endian+ is not one of {ENDIANS}.
+    #
+    # @example
+    #   Context.new(endian: :big).endian
+    #   #=> :big
+    def initialize(endian: :native, pointer_size: DEFAULT_POINTER_SIZE)
+      raise ArgumentError, "endian must be one of #{ENDIANS.inspect}, got #{endian.inspect}" \
+        unless ENDIANS.include?(endian)
+
+      @endian = endian == :native ? NATIVE_ENDIAN : endian
+      @pointer_size = pointer_size
+    end
+
+    class << self
+      # @return [MemoryIO::Context]
+      #   Used when a stream carries no context of its own.
+      def default
+        @default ||= new
+      end
+
+      # @param [Object] stream
+      #   The stream a type is reading from.
+      #
+      # @return [MemoryIO::Context]
+      #   The context +stream+ was tagged with, or {.default} when it carries none.
+      def of(stream)
+        stream.is_a?(MemoryIO::Stream) ? stream.context : default
+      end
+
+      # Derive a context from an ELF file, which describes the memory it is
+      # loaded into.
+      #
+      # @param [String] path
+      #   Path of the ELF file.
+      #
+      # @return [MemoryIO::Context?]
+      #   +nil+ if +path+ is unreadable or is not an ELF file.
+      #
+      # @example
+      #   Context.from_elf('/proc/self/exe')
+      #   #=> #<MemoryIO::Context @endian=:little, @pointer_size=8>
+      def from_elf(path)
+        ::File.open(path, 'rb') do |file|
+          elf = ELFTools::ELFFile.new(file)
+          new(endian: elf.endian, pointer_size: elf.elf_class / 8)
+        end
+      rescue SystemCallError, ELFTools::ELFError
+        nil
+      end
+    end
+  end
+end

data/lib/memory_io/error.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module MemoryIO
+  # The base class of all errors raised by {MemoryIO}.
+  #
+  # Rescue this class to catch every error this library raises on its own.
+  # Errors that propagate from Ruby itself are not covered.
+  #
+  # @example
+  #   begin
+  #     MemoryIO.attach(0)
+  #   rescue MemoryIO::Error => e
+  #     puts e.message
+  #   end
+  #   # /proc/0/mem does not exist
+  class Error < StandardError; end
+
+  # Raised when the memory of the target process is not accessible.
+  #
+  # @example
+  #   MemoryIO.attach(0)
+  #   # MemoryIO::ProcessNotFoundError: /proc/0/mem does not exist
+  class ProcessNotFoundError < Error; end
+
+  # Raised when an address expression cannot be evaluated.
+  #
+  # @example
+  #   MemoryIO.attach('self').read('heep + 0x10', 4)
+  #   # MemoryIO::InvalidAddressError: Failed to evaluate address: "heep + 0x10"
+  class InvalidAddressError < Error; end
+
+  # Raised when a value doesn't fit in the type it is written as.
+  #
+  # @example
+  #   MemoryIO::IO.new(stream).write(0x100000041, as: :u32)
+  #   # MemoryIO::ValueOutOfRangeError: 0x100000041 is out of range for 32-bit unsigned integer (0x0..0xffffffff)
+  class ValueOutOfRangeError < Error; end
+end

data/lib/memory_io/io.rb

@@ -1,12 +1,18 @@
 # encoding: ascii-8bit
 # frozen_string_literal: true
 
+require 'memory_io/context'
+require 'memory_io/stream'
 require 'memory_io/types/types'
 
 module MemoryIO
   # Main class to use {MemoryIO}.
   class IO
-    attr_reader :stream # @return [#pos, #pos=, #read, #write]
+    # @!attribute [r] stream
+    #   @return [#pos, #pos=, #read, #write] The stream given at instantiation.
+    # @!attribute [r] context
+    #   @return [MemoryIO::Context] The context of the memory reached through {#stream}.
+    attr_reader :stream, :context
 
     # Instantiate an {IO} object.
     #
@@ -15,17 +21,29 @@ module MemoryIO
     #   +file+ can be un-writable if you will not invoke any write-related method.
     #
     #   If +stream.read(*)+ returns empty string or +nil+, it would be seen as reaching EOF.
-    def initialize(stream)
+    # @param [:little, :big, :native] endian
+    #   Byte order of the memory reached through +stream+.
+    #   The default is right whenever that memory belongs to a process on this host,
+    #   and should be given when it does not, such as a dump taken elsewhere.
+    # @param [Integer] pointer_size
+    #   Size of a pointer in that memory, in bytes.
+    #
+    # @example
+    #   # a dump captured on a 32-bit big endian machine
+    #   MemoryIO::IO.new(File.open('core.dump', 'rb'), endian: :big, pointer_size: 4)
+    def initialize(stream, endian: :native, pointer_size: MemoryIO::Context::DEFAULT_POINTER_SIZE)
       @stream = stream
+      @context = MemoryIO::Context.new(endian: endian, pointer_size: pointer_size)
+      @tagged = MemoryIO::Stream.new(stream, @context)
     end
 
     # Read and convert result into custom type/structure.
     #
     # @param [Integer] num_elements
     #   Number of elements to be read.
-    #   This parameter must be positive and larger than zero.
+    #   Zero reads nothing, as it does for +::IO#read+.
     #
-    #   This parameter may effect the return type,
+    #   This parameter may affect the return type,
     #   see documents of return value.
     # @param [Integer?] from
     #   Invoke +stream.pos = from+ before starting to read.
@@ -57,7 +75,11 @@ module MemoryIO
     #   * +as != nil+ and +num_elements > 1+:
     #     An array with length +num_elements+ is returned.
     #
-    #   If EOF is occured, object(s) read will be returned.
+    #   If EOF occurred, only the objects that could be read in full are returned,
+    #   so the result may be shorter than +num_elements+ (possibly empty).
+    #
+    # @raise [ArgumentError]
+    #   +num_elements+ is negative or is not an Integer.
     #
     # @example
     #   stream = StringIO.new('A' * 8 + 'B' * 8)
@@ -67,7 +89,7 @@ module MemoryIO
     #   io.read(100)
     #   #=> "BBBBBBB"
     #
-    #   # read two unsigned 32-bit integers starts from posistion 4
+    #   # read two unsigned 32-bit integers starting from position 4
     #   io.read(2, from: 4, as: :u32)
     #   #=> [1094795585, 1111638594] # [0x41414141, 0x42424242]
     #
@@ -89,6 +111,17 @@ module MemoryIO
     #   io.read(2, as: :c_str)
     #   #=> ["123", "45678"]
     # @example
+    #   # reading beyond the end of stream returns what was read
+    #   stream = StringIO.new("\x01\x02\x03\x04")
+    #   io = MemoryIO::IO.new(stream)
+    #   io.read(3, as: :u32)
+    #   #=> [67305985]
+    #
+    #   # an object that can't be read in full is not returned
+    #   io.rewind
+    #   io.read(1, as: :u64)
+    #   #=> nil
+    # @example
     #   # pass lambda to `as`
     #   stream = StringIO.new("\x03123\x044567")
     #   io = MemoryIO::IO.new(stream)
@@ -101,12 +134,15 @@ module MemoryIO
     #
     # @see Types
     def read(num_elements, from: nil, as: nil, force_array: false)
+      unless num_elements.is_a?(Integer) && !num_elements.negative?
+        raise ArgumentError, "num_elements must be a non-negative Integer, got #{num_elements.inspect}"
+      end
+
       stream.pos = from if from
       return stream.read(num_elements) if as.nil?
 
       conv = to_proc(as, :read)
-      # TODO: handle eof
-      ret = Array.new(num_elements) { conv.call(stream) }
+      ret = read_elements(num_elements, conv)
       ret = ret.first if num_elements == 1 && !force_array
       ret
     end
@@ -125,7 +161,7 @@ module MemoryIO
     #
     #   A +Proc+ is allowed, which should accept +stream+ and one object as arguments.
     #
-    #   If +objects+ is a descendant instance of {Types::Type} and +as+ is +nil,
+    #   If +objects+ is a descendant instance of {Types::Type} and +as+ is +nil+,
     #   +objects.class+ will be used for +as+.
     #   Otherwise, when +as = nil+, this method will simply call +stream.write(objects)+.
     #
@@ -167,7 +203,7 @@ module MemoryIO
       return stream.write(objects) if as.nil?
 
       conv = to_proc(as, :write)
-      Array(objects).map { |o| conv.call(stream, o) }
+      Array(objects).map { |o| conv.call(@tagged, o) }
     end
 
     # Set +stream+ to the beginning.
@@ -180,6 +216,42 @@ module MemoryIO
 
     private
 
+    # @api private
+    #
+    # Read up to +num_elements+ objects, stopping early at the end of stream.
+    #
+    # An object is only collected if it could be read in full, so a stream
+    # that ends mid-object yields the objects preceding it rather than a
+    # truncated one.
+    #
+    # @return [Array<Object>]
+    def read_elements(num_elements, conv)
+      ret = []
+      num_elements.times do
+        break if eof?
+
+        begin
+          ret << conv.call(@tagged)
+        rescue ::EOFError
+          break
+        end
+      end
+      ret
+    end
+
+    # @api private
+    #
+    # @return [Boolean]
+    #   Whether +stream+ has no more data to be read.
+    def eof?
+      return stream.eof? if stream.respond_to?(:eof?)
+
+      pos = stream.pos
+      byte = stream.read(1)
+      stream.pos = pos
+      byte.nil? || byte.empty?
+    end
+
     # @api private
     def to_proc(as, rw)
       ret = as.respond_to?(rw) ? as.method(rw) : as

data/lib/memory_io/logger.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+# MemoryIO - Read/Write structures in memory.
+module MemoryIO
+  class << self
+    # Diagnostics that are worth surfacing but don't stop the operation
+    # are written here, so they can be silenced or redirected.
+    #
+    # @return [Logger]
+    #   Defaults to a logger writing to +$stderr+.
+    #
+    # @example
+    #   MemoryIO.logger.level = Logger::ERROR
+    #
+    #   MemoryIO.logger = Logger.new('memory_io.log')
+    def logger
+      @logger ||= ::Logger.new($stderr, progname: 'memory_io', formatter: FORMATTER)
+    end
+
+    attr_writer :logger
+  end
+
+  # @api private
+  #
+  # Keeps a message readable when it is shown to a human.
+  #
+  # @example
+  #   # [memory_io] WARN: something happened
+  FORMATTER = proc { |severity, _datetime, progname, msg| "[#{progname}] #{severity}: #{msg}\n" }
+end

data/lib/memory_io/process.rb

@@ -1,5 +1,10 @@
 # frozen_string_literal: true
 
+require 'memory_io/error'
+require 'memory_io/io'
+require 'memory_io/logger'
+require 'memory_io/util'
+
 module MemoryIO
   # Records information of a process.
   class Process
@@ -7,25 +12,41 @@ module MemoryIO
     # @return [#readable?, #writable?]
     attr_reader :perm
 
+    # @return [MemoryIO::Context]
+    #   The context of this process's memory.
+    attr_reader :context
+
     # @api private
     #
     # Create process object from pid.
     #
     # @param [Integer] pid
     #   Process id.
+    # @param [:little, :big, :native, nil] endian
+    #   Byte order of the process's memory.
+    # @param [Integer?] pointer_size
+    #   Size of a pointer in the process, in bytes.
+    #
+    #   Both default to what the process's executable declares, so a 32-bit
+    #   process is read correctly without being told. Pass them to override
+    #   a target whose executable can't be examined, or names an interpreter
+    #   rather than the program itself.
+    #
+    # @raise [MemoryIO::ProcessNotFoundError]
+    #   The memory of +pid+ is not accessible.
     #
     # @note
     #   This class only supports procfs-based system. i.e. /proc is mounted and readable.
-    def initialize(pid)
+    def initialize(pid, endian: nil, pointer_size: nil)
       @pid = pid
       @mem = "/proc/#{pid}/mem"
       # check permission of '/proc/pid/mem'
       @perm = MemoryIO::Util.file_permission(@mem)
-      # TODO: raise custom exception
-      raise Errno::ENOENT, @mem if perm.nil?
+      raise MemoryIO::ProcessNotFoundError, "#{@mem} does not exist" if perm.nil?
+
+      @context = build_context(endian, pointer_size)
 
-      # FIXME: use logger
-      warn(<<-EOS.strip) unless perm.readable? || perm.writable?
+      MemoryIO.logger.warn(<<-EOS.strip) unless perm.readable? || perm.writable?
 You have no permission to read/write this process.
 
 Check the setting of /proc/sys/kernel/yama/ptrace_scope, or try
@@ -74,9 +95,9 @@ $ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
 
     # Read from process's memory.
     #
-    # This method has *almost* same arguements and return types as {IO#read}.
+    # This method has *almost* same arguments and return types as {IO#read}.
     # The only difference is this method needs parameter +addr+ (which
-    # will be passed to paramter +from+ in {IO#read}).
+    # will be passed to parameter +from+ in {IO#read}).
     #
     # @param [Integer, String] addr
     #   The address start to read.
@@ -89,6 +110,9 @@ $ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
     # @return [String, Object, Array<Object>]
     #   See {IO#read}.
     #
+    # @raise [MemoryIO::InvalidAddressError]
+    #   +addr+ is an expression that cannot be evaluated.
+    #
     # @example
     #   process = MemoryIO.attach(`pidof victim`.to_i)
     #   puts process.read('heap', 4, as: :u64).map { |c| '0x%016x' % c }
@@ -104,7 +128,7 @@ $ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
     #   #=> "\x7fELF"
     # @see IO#read
     def read(addr, num_elements, **options)
-      mem_io(:read) { |io| io.read(num_elements, from: MemoryIO::Util.safe_eval(addr, **bases), **options) }
+      mem_io(:read) { |io| io.read(num_elements, from: resolve_address(addr), **options) }
     end
 
     # Write objects at +addr+.
@@ -120,6 +144,9 @@ $ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
     #
     # @return [void]
     #
+    # @raise [MemoryIO::InvalidAddressError]
+    #   +addr+ is an expression that cannot be evaluated.
+    #
     # @example
     #   process = MemoryIO.attach('self')
     #   s = 'A' * 16
@@ -128,14 +155,53 @@ $ echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope
     #   #=> 'BBBBCCCCAAAAAAAA'
     # @see IO#write
     def write(addr, objects, **options)
-      mem_io(:write) { |io| io.write(objects, from: MemoryIO::Util.safe_eval(addr, **bases), **options) }
+      mem_io(:write) { |io| io.write(objects, from: resolve_address(addr), **options) }
     end
 
     private
 
+    # The executable of a process describes the memory it runs in, so prefer it
+    # over assuming this host's context. What the caller gave wins over both.
+    #
+    # A process started through an interpreter names the interpreter here, whose
+    # context can differ from the program's. Recovering the program's own context
+    # would mean picking it out of the mappings, which aren't populated yet when
+    # a process is attached to right after it starts, so leave that to the caller.
+    #
+    # @return [MemoryIO::Context]
+    def build_context(endian, pointer_size)
+      declared = MemoryIO::Context.from_elf("/proc/#{@pid}/exe") || MemoryIO::Context.new
+      MemoryIO::Context.new(endian: endian || declared.endian,
+                            pointer_size: pointer_size || declared.pointer_size)
+    end
+
+    # Resolve +addr+ into an absolute address.
+    #
+    # {#bases} is only consulted when +addr+ is an expression that can
+    # reference it, so an address that is already absolute costs no extra work.
+    #
+    # @param [Integer, String] addr
+    #   The address to resolve.
+    #
+    # @return [Integer]
+    #   The resolved address.
+    #
+    # @raise [MemoryIO::InvalidAddressError]
+    #   +addr+ is an expression that cannot be evaluated,
+    #   or evaluates to something that is not an address.
+    def resolve_address(addr)
+      return addr if addr.is_a?(Integer)
+
+      address = MemoryIO::Util.safe_eval(addr, **bases)
+      raise MemoryIO::InvalidAddressError, "Failed to evaluate address: #{addr.inspect}" unless address.is_a?(Numeric)
+      raise MemoryIO::InvalidAddressError, "Address is not an integer: #{addr.inspect}" unless address == address.to_i
+
+      address.to_i
+    end
+
     def mem_io(perm)
       flags = perm == :write ? 'wb' : 'rb'
-      File.open(@mem, flags) { |f| yield MemoryIO::IO.new(f) }
+      File.open(@mem, flags) { |f| yield MemoryIO::IO.new(f, **@context.to_h) }
     end
   end
 end

data/lib/memory_io/stream.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module MemoryIO
+  # @api private
+  #
+  # A stream tagged with the {Context} of the memory it accesses.
+  #
+  # Types are handed one of these instead of the bare stream, so that a type
+  # can learn how to interpret the bytes it reads without the reading
+  # interface having to grow another argument.
+  #
+  # Every other message is forwarded, so a stream behaves as it did before.
+  class Stream
+    # @return [MemoryIO::Context]
+    attr_reader :context
+
+    # @param [#read, #write] stream
+    #   The stream to be tagged.
+    # @param [MemoryIO::Context] context
+    #   The context of the memory reached through +stream+.
+    def initialize(stream, context)
+      @stream = stream
+      @context = context
+    end
+
+    def read(*)
+      @stream.read(*)
+    end
+
+    def write(*)
+      @stream.write(*)
+    end
+
+    def pos
+      @stream.pos
+    end
+
+    def pos=(val)
+      @stream.pos = val
+    end
+
+    private
+
+    def method_missing(name, *, &)
+      return super unless @stream.respond_to?(name)
+
+      @stream.public_send(name, *, &)
+    end
+
+    def respond_to_missing?(name, include_private = false)
+      @stream.respond_to?(name, include_private) || super
+    end
+  end
+end

data/lib/memory_io/types/basic/number.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'memory_io/context'
+require 'memory_io/error'
 require 'memory_io/types/type'
 
 module MemoryIO
@@ -8,64 +10,144 @@ module MemoryIO
     module Basic
       # Register numbers to {Types}.
       #
-      # All types registered by this class are assumed as *little endian*.
+      # The byte order is taken from the {MemoryIO::Context} of the stream being
+      # read, so the same type reads correctly from memory of either byte order.
       #
-      # This class registered (un)signed {8, 16, 32, 64)-bit integers and IEEE-754 floating numbers.
+      # This class registered (un)signed (8, 16, 32, 64)-bit integers and IEEE-754 floating numbers.
       class Number
+        # Indicators of the integer widths, by size in bytes.
+        # A single byte has no byte order to indicate.
+        INTEGER_INDICATORS = { 1 => 'C', 2 => 'S', 4 => 'L', 8 => 'Q' }.freeze
+
+        # Indicators of the real widths, by size in bytes and then byte order.
+        #
+        # @example
+        #   # 'e' and 'E' are IEEE-754 single and double precision, little endian.
+        REAL_INDICATORS = { 4 => { little: 'e', big: 'g' }, 8 => { little: 'E', big: 'G' } }.freeze
+
+        # Appended to an integer indicator to fix its byte order.
+        ENDIAN_INDICATORS = { little: '<', big: '>' }.freeze
+
         # @param [Integer] bytes
         #   Bytes.
         # @param [Boolean] signed
         #   Signed or unsigned.
-        # @param [String] pack_str
-        #   The indicator to be passed to +Array#pack+ and +String#unpack+.
-        def initialize(bytes, signed, pack_str)
+        # @param [Boolean] real
+        #   Whether this type holds a real number rather than an integer.
+        def initialize(bytes, signed, real: false)
           @bytes = bytes
           @signed = signed
-          @pack_str = pack_str
+          @real = real
+          @range = value_range unless real
+          @indicators = ENDIAN_INDICATORS.keys.to_h { |e| [e, indicator(e)] }
         end
 
         # @return [Integer]
+        #
+        # @raise [EOFError]
+        #   Fewer than +bytes+ bytes remain in +stream+.
         def read(stream)
-          unpack(stream.read(@bytes))
+          endian = MemoryIO::Context.of(stream).endian
+          unpack(MemoryIO::Util.read_exactly(stream, @bytes), endian)
         end
 
         # @param [Integer] val
+        #
+        # @raise [MemoryIO::ValueOutOfRangeError]
+        #   +val+ doesn't fit in this type, which would otherwise be written truncated.
         def write(stream, val)
-          stream.write(pack(val))
+          endian = MemoryIO::Context.of(stream).endian
+          raise MemoryIO::ValueOutOfRangeError, out_of_range_message(val) if out_of_range?(val, endian)
+
+          stream.write(pack(val, endian))
         end
 
         private
 
-        def unpack(str)
-          val = str.unpack1(@pack_str)
+        # Anything that isn't a number of the matching kind is left for
+        # +Array#pack+ to reject.
+        #
+        # @return [Boolean]
+        def out_of_range?(val, endian)
+          if @range
+            val.is_a?(Integer) && !@range.cover?(val)
+          else
+            val.is_a?(Numeric) && overflows?(val, endian)
+          end
+        end
+
+        # A finite value that packs to an infinity has exceeded what the type
+        # can represent. Losing precision is inherent to the type and allowed,
+        # as is writing an infinity that was asked for.
+        #
+        # @return [Boolean]
+        def overflows?(val, endian)
+          val.infinite?.nil? && pack(val, endian).unpack1(@indicators[endian]).infinite?
+        end
+
+        # @return [Range]
+        def value_range
+          bits = @bytes * 8
+          @signed ? (-(2**(bits - 1))..((2**(bits - 1)) - 1)) : (0..((2**bits) - 1))
+        end
+
+        # @return [String]
+        def out_of_range_message(val)
+          return format('%s exceeds the range of %d-bit floating number', val, @bytes * 8) unless @range
+
+          format('%s is out of range for %d-bit %s integer (%s..%s)',
+                 hex(val), @bytes * 8, @signed ? 'signed' : 'unsigned',
+                 hex(@range.first), hex(@range.last))
+        end
+
+        # +format+'s '%#x' renders a negative number in two's complement notation.
+        #
+        # @return [String]
+        #
+        # @example
+        #   hex(-128)
+        #   #=> '-0x80'
+        def hex(val)
+          format('%s0x%x', val.negative? ? '-' : '', val.abs)
+        end
+
+        # @return [String]
+        #   The +Array#pack+ indicator of this type in +endian+ byte order.
+        def indicator(endian)
+          return REAL_INDICATORS[@bytes][endian] if @real
+          return INTEGER_INDICATORS[@bytes] if @bytes == 1
+
+          INTEGER_INDICATORS[@bytes] + ENDIAN_INDICATORS[endian]
+        end
+
+        def unpack(str, endian)
+          val = str.unpack1(@indicators[endian])
+          # a real is already signed by its representation
+          return val if @real
+
           val -= (2**(@bytes * 8)) if @signed && val >= (2**((@bytes * 8) - 1))
           val
         end
 
-        def pack(val)
-          [val].pack(@pack_str)
+        def pack(val, endian)
+          [val].pack(@indicators[endian])
         end
 
         # Register (un)signed n-bits integers.
-        {
-          8 => 'C',
-          16 => 'S',
-          32 => 'I',
-          64 => 'Q'
-        }.each do |t, c|
-          Type.register(Number.new(t / 8, true, c),
+        [8, 16, 32, 64].each do |t|
+          Type.register(Number.new(t / 8, true),
                         alias: [:"basic/s#{t}", :"s#{t}"],
                         doc: "A signed #{t}-bit integer.")
-          Type.register(Number.new(t / 8, false, c),
+          Type.register(Number.new(t / 8, false),
                         alias: [:"basic/u#{t}", :"u#{t}"],
                         doc: "An unsigned #{t}-bit integer.")
         end
 
         # Register floating numbers.
-        Type.register(Number.new(4, false, 'F'),
+        Type.register(Number.new(4, true, real: true),
                       alias: %i[basic/float float],
                       doc: 'IEEE-754 32-bit floating number.')
-        Type.register(Number.new(8, false, 'D'),
+        Type.register(Number.new(8, true, real: true),
                       alias: %i[basic/double double],
                       doc: 'IEEE-754 64-bit floating number.')
       end

data/lib/memory_io/types/clang/c_str.rb

@@ -12,17 +12,31 @@ module MemoryIO
       # A null-terminated string.
       class CStr < Types::Type
 
+        # Number of bytes to fetch at a time while searching for the terminator.
+        CHUNK_SIZE = 1024
+
         # @api private
         #
+        # The terminator is searched for in blocks rather than byte by byte,
+        # and +stream+ is left just after it so the next read starts at the
+        # following string.
+        #
         # @return [String]
         #   String without null byte.
         def self.read(stream)
           ret = +''
           loop do
-            c = stream.read(1)
-            break if c.nil? || c == '' || c == "\x00"
+            chunk = stream.read(CHUNK_SIZE)
+            break if chunk.nil? || chunk.empty?
+
+            terminator = chunk.index("\x00")
+            if terminator
+              ret << chunk[0, terminator]
+              stream.pos -= chunk.size - terminator - 1
+              break
+            end
 
-            ret << c
+            ret << chunk
           end
           ret
         end

data/lib/memory_io/types/cpp/string.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
 
+require 'memory_io/context'
+require 'memory_io/logger'
 require 'memory_io/types/type'
+require 'memory_io/util'
 
 module MemoryIO
   module Types
@@ -50,20 +53,20 @@ module MemoryIO
         # @param [String] str
         def data=(str)
           @data = str
-          warn("Length of str (#{str.size}) is larger than capacity (#{capacity})") if str.size > capacity
+          return unless str.size > capacity
+
+          MemoryIO.logger.warn("Length of str (#{str.size}) is larger than capacity (#{capacity})")
         end
 
         # Custom inspect view.
         #
         # @return [String]
         def inspect
-          # rubocop:disable Lint/FormatParameterMismatch
-          format("#<%s @data=%s, @capacity=%d, @dataplus=0x%0#{SIZE_T * 2}x>",
+          format('#<%s @data=%s, @capacity=%d, @dataplus=0x%s>',
                  self.class.name,
                  data.inspect,
                  capacity,
-                 dataplus)
-          # rubocop:enable Lint/FormatParameterMismatch
+                 dataplus.to_s(16).rjust(SIZE_T * 2, '0'))
         end
 
         class << self
@@ -71,6 +74,11 @@ module MemoryIO
           #
           # @return [CPP::String]
           #
+          # @raise [EOFError]
+          #   The object is incomplete, or its characters cannot be read from
+          #   where it points. {MemoryIO::IO#read} answers with the objects it
+          #   read in full rather than one that is partly filled in.
+          #
           # @example
           #   # echo '#include <string>\n#include <cstdio>\nint main() {' > a.cpp && \
           #   # echo 'std::string a="abcd"; printf("%p\\n", &a);' >> a.cpp && \
@@ -85,10 +93,11 @@ module MemoryIO
           def read(stream)
             dataplus = read_size_t(stream)
             length = read_size_t(stream)
-            union = stream.read(LOCAL_CAPACITY + 1)
+            union = MemoryIO::Util.read_exactly(stream, LOCAL_CAPACITY + 1)
             if length > LOCAL_CAPACITY
-              capacity = MemoryIO::Util.unpack(union[0, Type::SIZE_T])
-              data = keep_pos(stream, pos: dataplus) { |s| s.read(length) }
+              context = MemoryIO::Context.of(stream)
+              capacity = MemoryIO::Util.unpack(union[0, context.pointer_size], context.endian)
+              data = keep_pos(stream, pos: dataplus) { |s| MemoryIO::Util.read_exactly(s, length) }
             else
               capacity = LOCAL_CAPACITY
               data = union[0, length]

data/lib/memory_io/types/record.rb

@@ -19,12 +19,14 @@ module MemoryIO
       #
       # @param [Object] object
       # @param [Array<Symbol>] keys
+      # @param [Hash] option
+      #   Extra options.
       #
-      # @option [Thread::Backtrace::Location] caller
-      #   This option should present if and only if +object+ is a subclass of {Types::Type}.
-      # @option [String] doc
+      # @option option [Thread::Backtrace::Location] :caller
+      #   This option should be present if and only if +object+ is a subclass of {Types::Type}.
+      # @option option [String] :doc
       #   Doc-string.
-      #   Automatically parse from caller location if this parameter doesn't present.
+      #   Automatically parsed from caller location if this option isn't present.
       def initialize(object, keys, option = {})
         @obj = object
         @keys = keys

data/lib/memory_io/types/type.rb

@@ -1,17 +1,22 @@
 # frozen_string_literal: true
 
+require 'memory_io/context'
 require 'memory_io/types/record'
 require 'memory_io/util'
 
 module MemoryIO
   module Types
-    # The base class, all descendants of this class would be consider as a valid 'type'.
+    # The base class, all descendants of this class would be considered as a valid 'type'.
     class Type
-      # The size of +size_t+. i.e. +sizeof(size_t)+.
-      SIZE_T = 8
+      # The size of +size_t+ assumed when the stream says nothing more specific.
+      #
+      # @see MemoryIO::Context#pointer_size
+      SIZE_T = MemoryIO::Context::DEFAULT_POINTER_SIZE
 
       class << self
-        # Read {Type::SIZE_T} bytes and cast to a little endian unsigned integer.
+        # Read one +size_t+ and cast it to an unsigned integer.
+        #
+        # Its width and byte order are taken from the {MemoryIO::Context} of +stream+.
         #
         # @param [#read] stream
         #   Stream to read.
@@ -19,15 +24,21 @@ module MemoryIO
         # @return [Integer]
         #   Result.
         #
+        # @raise [EOFError]
+        #   Fewer bytes than a +size_t+ remain in +stream+.
+        #
         # @example
         #   s = StringIO.new("\xEF\xBE\xAD\xDExV4\x00")
         #   Type.read_size_t(s).to_s(16)
         #   #=> '345678deadbeef'
         def read_size_t(stream)
-          MemoryIO::Util.unpack(stream.read(SIZE_T))
+          context = MemoryIO::Context.of(stream)
+          MemoryIO::Util.unpack(MemoryIO::Util.read_exactly(stream, context.pointer_size), context.endian)
         end
 
-        # Pack +val+ into {Type::SIZE_T} bytes and write to +stream+.
+        # Pack +val+ into one +size_t+ and write it to +stream+.
+        #
+        # Its width and byte order are taken from the {MemoryIO::Context} of +stream+.
         #
         # @param [#write] stream
         #   Stream to write.
@@ -42,11 +53,16 @@ module MemoryIO
         #   s.string
         #   #=> "\x23\x01\x00\x00\x00\x00\x00\x00"
         def write_size_t(stream, val)
-          stream.write(MemoryIO::Util.pack(val, SIZE_T))
+          context = MemoryIO::Context.of(stream)
+          stream.write(MemoryIO::Util.pack(val, context.pointer_size, context.endian))
         end
 
         # Yield a block and resume the position of stream.
         #
+        # The position is resumed even if the block raises,
+        # so a failure while following an invalid pointer doesn't
+        # leave the stream at an unexpected position.
+        #
         # @param [#pos, #pos=] stream
         #   Stream.
         # @param [Integer] pos
@@ -69,9 +85,11 @@ module MemoryIO
         def keep_pos(stream, pos: nil)
           org = stream.pos
           stream.pos = pos if pos
-          ret = yield stream
-          stream.pos = org
-          ret
+          begin
+            yield stream
+          ensure
+            stream.pos = org
+          end
         end
 
         # @api private
@@ -81,8 +99,9 @@ module MemoryIO
         # @param [Symbol] symbol
         #   Symbol that has been registered in {.register}.
         #
-        # @return [{Symbol => Object}]
-        #   The object that registered in {.register}.
+        # @return [MemoryIO::Types::Record?]
+        #   The record that was registered in {.register},
+        #   or +nil+ if +symbol+ has never been registered.
         #
         # @see .register
         def find(symbol)
@@ -93,10 +112,12 @@ module MemoryIO
         #
         # @param [#read, #write] object
         #   Normally, +object+ is a descendant class of {Type}.
+        # @param [Hash] option
+        #   Extra options.
         #
-        # @option [Symbol, Array<Symbol>] alias
+        # @option option [Symbol, Array<Symbol>] :alias
         #   Custom symbol name(s) that can be used in {.find}.
-        # @option [String] doc
+        # @option option [String] :doc
         #   Doc string that will be shown in README.md.
         #
         # @return [Array<Symbol>]
@@ -117,7 +138,7 @@ module MemoryIO
         #
         # @note
         #   If all symbols in +alias+ have been registered, an ArgumentError will be raised.
-        #   However, if at least one of aliases hasn't been used, registration will success.
+        #   However, if at least one of aliases hasn't been used, registration will succeed.
         #
         # @see .find
         def register(object, option = {})

data/lib/memory_io/types/types.rb

@@ -18,16 +18,16 @@ module MemoryIO
     #
     # This method will search all descendants of {Types::Type}.
     #
-    # @return [Symbol] name
+    # @param [Symbol] name
     #   Class name to be searched.
     #
     # @return [#read, #write]
     #   Any object that implemented method +read+ and +write+.
-    #   Usually returns a class inherit {Types::Type}.
+    #   Usually returns a class inherited from {Types::Type}.
     #
     # @example
     #   Types.find(:c_str)
-    #   #=> MemoryIO::Types::CStr
+    #   #=> MemoryIO::Types::Clang::CStr
     #
     #   Types.find(:u64)
     #   #=> #<MemoryIO::Types::Number:0x000055ecc017a310 @bytes=8, @pack_str="Q", @signed=false>
@@ -50,7 +50,7 @@ module MemoryIO
     #
     # @example
     #   Types.get_proc(:c_str, :write)
-    #   #=> #<Method: MemoryIO::Types::CStr.write>
+    #   #=> #<Method: MemoryIO::Types::Clang::CStr.write>
     #   Types.get_proc(:s32, :read)
     #   #=> #<Method: MemoryIO::Types::Number#read>
     def get_proc(name, rw)

data/lib/memory_io/util.rb

@@ -18,12 +18,12 @@ module MemoryIO
         @writable = stat.writable_real?
         # we do a trick here because /proc/[pid]/mem might be marked as writeable but fails at sysopen.
         begin
-          @readable && File.open(file, 'rb').close
+          @readable && File.open(file, 'rb', &:close)
         rescue Errno::EACCES
           @readable = false
         end
         begin
-          @writable && File.open(file, 'wb').close
+          @writable && File.open(file, 'wb', &:close)
         rescue Errno::EACCES
           @writable = false
         end
@@ -78,25 +78,53 @@ module MemoryIO
     # @param [{Symbol => Integer}] vars
     #   Predefined variables
     #
-    # @return [Integer]
-    #   Result.
+    # @return [Integer?]
+    #   Result, or +nil+ if +str+ is not a valid expression.
     #
     # @example
     #   Util.safe_eval('heap + 0x10 * pp', heap: 0xde00, pp: 8)
     #   #=> 56960 # 0xde80
+    #
+    #   Util.safe_eval('0xzz')
+    #   #=> nil
     def safe_eval(str, **vars)
       return str if str.is_a?(Integer)
 
-      # dentaku 2 doesn't support hex
-      str = str.gsub(/0x[0-9a-zA-Z]+/) { |c| c.to_i(16) }
       Dentaku::Calculator.new.store(vars).evaluate(str)
     end
 
+    # @api private
+    #
+    # Read exactly +size+ bytes from +stream+.
+    #
+    # @param [#read] stream
+    #   Stream to read.
+    # @param [Integer] size
+    #   Number of bytes to read.
+    #
+    # @return [String]
+    #   The bytes read.
+    #
+    # @raise [EOFError]
+    #   Fewer than +size+ bytes remain in +stream+.
+    #
+    # @example
+    #   Util.read_exactly(StringIO.new('1234'), 8)
+    #   # EOFError: Requires 0x8 bytes, but only 0x4 bytes remain
+    def read_exactly(stream, size)
+      str = stream.read(size)
+      remain = str.nil? ? 0 : str.size
+      raise ::EOFError, format('Requires 0x%x bytes, but only 0x%x bytes remain', size, remain) if remain < size
+
+      str
+    end
+
     # Unpack a string into an integer.
-    # Little endian is used.
     #
     # @param [String] str
     #   String.
+    # @param [:little, :big] endian
+    #   Byte order of +str+.
     #
     # @return [Integer]
     #   Result.
@@ -106,12 +134,14 @@ module MemoryIO
     #   #=> 255
     #   Util.unpack("@\xE2\x01\x00")
     #   #=> 123456
-    def unpack(str)
-      str.bytes.reverse.reduce(0) { |s, c| (s * 256) + c }
+    #   Util.unpack("\x00\x01\xE2@", :big)
+    #   #=> 123456
+    def unpack(str, endian = :little)
+      bytes = endian == :little ? str.bytes.reverse : str.bytes
+      bytes.reduce(0) { |s, c| (s * 256) + c }
     end
 
     # Pack an integer into +b+ bytes.
-    # Little endian is used.
     #
     # @param [Integer] val
     #   The integer to pack.
@@ -119,6 +149,8 @@ module MemoryIO
     #   only lower +b+ bytes in +val+ will be packed.
     #
     # @param [Integer] b
+    # @param [:little, :big] endian
+    #   Byte order to pack +val+ in.
     #
     # @return [String]
     #   Packing result with length +b+.
@@ -126,8 +158,12 @@ module MemoryIO
     # @example
     #   Util.pack(0x123, 4)
     #   #=> "\x23\x01\x00\x00"
-    def pack(val, b)
-      Array.new(b) { |i| (val >> (i * 8)) & 0xff }.pack('C*')
+    #   Util.pack(0x123, 4, :big)
+    #   #=> "\x00\x00\x01\x23"
+    def pack(val, b, endian = :little)
+      bytes = Array.new(b) { |i| (val >> (i * 8)) & 0xff }
+      bytes.reverse! if endian == :big
+      bytes.pack('C*')
     end
 
     # Remove extension name (.so) and version in library name.

data/lib/memory_io/version.rb

@@ -2,5 +2,5 @@
 
 module MemoryIO
   # Current gem version.
-  VERSION = '0.3.0'
+  VERSION = '1.0.0'
 end

data/lib/memory_io.rb

@@ -9,12 +9,36 @@ module MemoryIO
   # Get a process by process id.
   #
   # @param [Integer] pid
-  #   Process Id in linux.
+  #   Process id in Linux.
+  # @param [:little, :big, :native, nil] endian
+  #   Byte order of the process's memory.
+  # @param [Integer?] pointer_size
+  #   Size of a pointer in the process, in bytes.
+  #
+  #   Both are taken from the process's executable when not given.
   #
   # @return [MemoryIO::Process]
   #   A process object for further usage.
-  def attach(pid)
-    MemoryIO::Process.new(pid)
+  #
+  # @raise [MemoryIO::ProcessNotFoundError]
+  #   The memory of +pid+ is not accessible.
+  #
+  # @example
+  #   process = MemoryIO.attach(`pidof victim`.to_i)
+  #   process.read('heap', 8)
+  # @example
+  #   # a program started through an interpreter is described by the
+  #   # interpreter, so state the context of the program instead
+  #   MemoryIO.attach(`pidof victim32`.to_i, pointer_size: 4)
+  #
+  # @note
+  #   The context is read from +/proc/[pid]/exe+, which names the interpreter
+  #   when the process was started through one. Pass +endian+ and
+  #   +pointer_size+ for such a process, whose context may differ from
+  #   the interpreter running it.
+  # @see MemoryIO::Process#initialize
+  def attach(pid, endian: nil, pointer_size: nil)
+    MemoryIO::Process.new(pid, endian: endian, pointer_size: pointer_size)
   end
 end
 

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: memory_io
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - david942j
 bindir: bin
 cert_chain: []
-date: 2025-11-02 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: dentaku
@@ -15,14 +15,48 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '4'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3'
+        version: '4'
+- !ruby/object:Gem::Dependency
+  name: elftools
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.3'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: logger
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.6'
 - !ruby/object:Gem::Dependency
   name: ostruct
   requirement: !ruby/object:Gem::Requirement
@@ -85,14 +119,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.22'
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: yard
   requirement: !ruby/object:Gem::Requirement
@@ -119,8 +153,12 @@ files:
 - LICENSE
 - README.md
 - lib/memory_io.rb
+- lib/memory_io/context.rb
+- lib/memory_io/error.rb
 - lib/memory_io/io.rb
+- lib/memory_io/logger.rb
 - lib/memory_io/process.rb
+- lib/memory_io/stream.rb
 - lib/memory_io/types/basic/number.rb
 - lib/memory_io/types/clang/c_str.rb
 - lib/memory_io/types/cpp/string.rb
@@ -141,14 +179,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.2'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: memory_io
 test_files: []