memory_io 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3de5ed7bf7e1f8543bbb290ed472f008ed9d8f4c1af032a11831bd904378c11e
-  data.tar.gz: e99b29afb7cdcc7941bb6249bbe453cea2cb3a6cb6eab72a8965bfa5ef9802e3
+  metadata.gz: ae436fb71c1c77ce99b26657dc3e9497e8730ee578f0fe412186a67ee4881d12
+  data.tar.gz: 822612ae59c6c669a6136724dc9636349a3f6b3b314b20d3e024bc1481faf9e2
 SHA512:
-  metadata.gz: d4d3d9e60c649dd8d4e6f3c3dfe3bb777d2a7ffd2065699e3f86fef27f9ddf079b90acc7d7a5be244301d45ba46d9c713b950bbaa7a113843631287fb1e9653f
-  data.tar.gz: 2246f04654d036e8df50440cf2c3d9ebe50933921f5720bf5f69308648ab34849d869b3969f581579dba8930ae1fbd0e5a1d6e27246900129cef39212e2876bf
+  metadata.gz: 1fc69554905f1fbd661045c65fd0570e0baea78191d531a7faa39157f9a5faa6618f3693a2cabd7f2117a7a849cd1fc5925123868103b8a414359ed49843068e
+  data.tar.gz: f5449be7a6af8e443e857492aa73533735fdc639d4215a79c4b7b0a7effae9db34d5511ec46fec11aba545185f0d6b9f9947ab02f9de88d17a10b78901a96c19

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 david942j
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,8 +1,8 @@
-[![Build Status](https://travis-ci.org/david942j/memory_io.svg?branch=master)](https://travis-ci.org/david942j/memory_io)
 [![Gem Version](https://badge.fury.io/rb/memory_io.svg)](https://badge.fury.io/rb/memory_io)
-[![Maintainability](https://api.codeclimate.com/v1/badges/dc8da34c5a8ab0095530/maintainability)](https://codeclimate.com/github/david942j/memory_io/maintainability)
-[![Test Coverage](https://api.codeclimate.com/v1/badges/dc8da34c5a8ab0095530/test_coverage)](https://codeclimate.com/github/david942j/memory_io/test_coverage)
-[![Inline docs](https://inch-ci.org/github/david942j/memory_io.svg?branch=master)](https://inch-ci.org/github/david942j/memory_io)
+[![Build Status](https://github.com/david942j/memory_io/workflows/build/badge.svg)](https://github.com/david942j/memory_io/actions)
+[![Maintainability](https://qlty.sh/gh/david942j/projects/memory_io/maintainability.svg)](https://qlty.sh/gh/david942j/projects/memory_io)
+[![Code Coverage](https://qlty.sh/gh/david942j/projects/memory_io/coverage.svg)](https://qlty.sh/gh/david942j/projects/memory_io)
+[![Yard Docs](http://img.shields.io/badge/yard-docs-blue.svg)](https://www.rubydoc.info/github/david942j/memory_io/)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](http://choosealicense.com/licenses/mit/)
 
 # MemoryIO
@@ -14,8 +14,8 @@ Read/Write complicated structures in memory easily.
 I usually need to dump a structure, say `string` in C++, from memory for debugging.
 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 dependency of **MemoryIO**).
-So I create this repo and want to make the debug procedure much easier.
+(unless you use [gdb-ruby](https://github.com/david942j/gdb-ruby), which has **MemoryIO** as its dependency).
+So I created this project to make the debug procedure much easier.
 
 This repository has two main goals:
 
@@ -25,16 +25,14 @@ This repository has two main goals:
 ## Why
 
 It's not hard to read/write a process's memory (simply open the file `/proc/$PID/mem`),
-but it still worth to wrap it.
+but it's still worthy to make a utility.
 
-This repo also targets to collect all common structures, such as how to parse a C++/Rust/Python object from memory.
+This project also targets to collect all common structures, such as how to parse a C++/Rust/Python object from memory.
 Therefore, **Pull Requests of adding new structures** are welcome :D
 
 ## Supported Platform
 
 - Linux
-- (TODO) Windows
-- (TODO) MacOS
 
 ## Implemented Structures
 
@@ -122,7 +120,7 @@ string
 require 'memory_io'
 process = MemoryIO.attach(`pidof victim`.to_i)
 
-# An example that read a chunk of pt-malloc.
+# An example that reads a chunk of pt-malloc.
 read_chunk = lambda do |stream|
   _prev_size = stream.read(8)
   size = (stream.read(8).unpack('Q').first & -16) - 8
@@ -169,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,10 +216,46 @@ 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
-      ret = ret.respond_to?(:call) ? ret : MemoryIO::Types.get_proc(ret, rw)
+      ret = MemoryIO::Types.get_proc(ret, rw) unless ret.respond_to?(:call)
       raise ArgumentError, <<-EOERR.strip unless ret.respond_to?(:call)
 
 Invalid argument `as`: #{as.inspect}. It should be either a Proc or a supported type of MemoryIO::Types.

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,30 +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.
-    #
-    # @todo
-    #   Support MacOS
-    # @todo
-    #   Support Windows
-    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
@@ -79,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.
@@ -94,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 }
@@ -109,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+.
@@ -125,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
@@ -133,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