ruby-macho 0.2.4 → 0.2.5

data/lib/macho/open.rb

@@ -7,17 +7,17 @@ module MachO
   # @raise [MachO::TruncatedFileError] if the file is too small to have a valid header
   # @raise [MachO::MagicError] if the file's magic is not valid Mach-O magic
   def self.open(filename)
-    raise ArgumentError.new("#{filename}: no such file") unless File.file?(filename)
-    raise TruncatedFileError.new unless File.stat(filename).size >= 4
+    raise ArgumentError, "#{filename}: no such file" unless File.file?(filename)
+    raise TruncatedFileError unless File.stat(filename).size >= 4
 
     magic = File.open(filename, "rb") { |f| f.read(4) }.unpack("N").first
 
-    if MachO.fat_magic?(magic)
+    if Utils.fat_magic?(magic)
       file = FatFile.new(filename)
-    elsif MachO.magic?(magic)
+    elsif Utils.magic?(magic)
       file = MachOFile.new(filename)
     else
-      raise MagicError.new(magic)
+      raise MagicError, magic
     end
 
     file

data/lib/macho/sections.rb

@@ -45,7 +45,7 @@ module MachO
     :S_ATTR_DEBUG => 0x02000000,
     :S_ATTR_SOME_INSTRUCTIONS => 0x00000400,
     :S_ATTR_EXT_RELOC => 0x00000200,
-    :S_ATTR_LOC_RELOC => 0x00000100
+    :S_ATTR_LOC_RELOC => 0x00000100,
   }.freeze
 
   # association of section name symbols to names
@@ -62,7 +62,7 @@ module MachO
     :SECT_OBJC_STRINGS => "__selector_strs",
     :SECT_OBJC_REFS => "__selector_refs",
     :SECT_ICON_HEADER => "__header",
-    :SECT_ICON_TIFF => "__tiff"
+    :SECT_ICON_TIFF => "__tiff",
   }.freeze
 
   # Represents a section of a segment for 32-bit architectures.
@@ -91,7 +91,7 @@ module MachO
     # @return [Fixnum] the number of relocation entries
     attr_reader :nreloc
 
-    # @return [Fixnum] flags for type and addrributes of the section
+    # @return [Fixnum] flags for type and attributes of the section
     attr_reader :flags
 
     # @return [void] reserved (for offset or index)
@@ -100,12 +100,15 @@ module MachO
     # @return [void] reserved (for count or sizeof)
     attr_reader :reserved2
 
-    FORMAT = "a16a16L=9"
+    # @see MachOStructure::FORMAT
+    FORMAT = "a16a16L=9".freeze
+
+    # @see MachOStructure::SIZEOF
     SIZEOF = 68
 
     # @api private
     def initialize(sectname, segname, addr, size, offset, align, reloff,
-        nreloc, flags, reserved1, reserved2)
+                   nreloc, flags, reserved1, reserved2)
       @sectname = sectname
       @segname = segname
       @addr = addr
@@ -121,12 +124,17 @@ module MachO
 
     # @return [String] the section's name, with any trailing NULL characters removed
     def section_name
-      @sectname.delete("\x00")
+      sectname.delete("\x00")
     end
 
     # @return [String] the parent segment's name, with any trailing NULL characters removed
     def segment_name
-      @segname.delete("\x00")
+      segname.delete("\x00")
+    end
+
+    # @return [Boolean] true if the section has no contents (i.e, `size` is 0)
+    def empty?
+      size.zero?
     end
 
     # @example
@@ -145,12 +153,15 @@ module MachO
     # @return [void] reserved
     attr_reader :reserved3
 
-    FORMAT = "a16a16Q=2L=8"
+    # @see MachOStructure::FORMAT
+    FORMAT = "a16a16Q=2L=8".freeze
+
+    # @see MachOStructure::SIZEOF
     SIZEOF = 80
 
     # @api private
     def initialize(sectname, segname, addr, size, offset, align, reloff,
-        nreloc, flags, reserved1, reserved2, reserved3)
+                   nreloc, flags, reserved1, reserved2, reserved3)
       super(sectname, segname, addr, size, offset, align, reloff,
         nreloc, flags, reserved1, reserved2)
       @reserved3 = reserved3

data/lib/macho/structure.rb

@@ -3,9 +3,13 @@ module MachO
   # @abstract
   class MachOStructure
     # The String#unpack format of the data structure.
-    FORMAT = ""
+    # @return [String] the unpacking format
+    # @api private
+    FORMAT = "".freeze
 
     # The size of the data structure, in bytes.
+    # @return [Fixnum] the size, in bytes
+    # @api private
     SIZEOF = 0
 
     # @return [Fixnum] the size, in bytes, of the represented structure.
@@ -13,26 +17,14 @@ module MachO
       self::SIZEOF
     end
 
-    # @param endianness [Symbol] either :big or :little
+    # @param endianness [Symbol] either `:big` or `:little`
     # @param bin [String] the string to be unpacked into the new structure
     # @return [MachO::MachOStructure] a new MachOStructure initialized with `bin`
     # @api private
     def self.new_from_bin(endianness, bin)
-      format = specialize_format(self::FORMAT, endianness)
-
-      self.new(*bin.unpack(format))
-    end
-
-    private
+      format = Utils.specialize_format(self::FORMAT, endianness)
 
-    # Convert an abstract (native-endian) String#unpack format to big or little.
-    # @param format [String] the format string being converted
-    # @param endianness [Symbol] either :big or :little
-    # @return [String] the converted string
-    # @api private
-    def self.specialize_format(format, endianness)
-      modifier = (endianness == :big) ? ">" : "<"
-      format.tr("=", modifier)
+      new(*bin.unpack(format))
     end
   end
 end

data/lib/macho/tools.rb

@@ -12,12 +12,14 @@ module MachO
     # Changes the dylib ID of a Mach-O or Fat binary, overwriting the source file.
     # @param filename [String] the Mach-O or Fat binary being modified
     # @param new_id [String] the new dylib ID for the binary
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) whether or not to fail loudly
+    #  with an exception if the change cannot be performed
     # @return [void]
-    # @todo unstub for fat files
-    def self.change_dylib_id(filename, new_id)
+    def self.change_dylib_id(filename, new_id, options = {})
       file = MachO.open(filename)
 
-      file.dylib_id = new_id
+      file.change_dylib_id(new_id, options)
       file.write!
     end
 
@@ -25,12 +27,14 @@ module MachO
     # @param filename [String] the Mach-O or Fat binary being modified
     # @param old_name [String] the old shared library name
     # @param new_name [String] the new shared library name
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) whether or not to fail loudly
+    #  with an exception if the change cannot be performed
     # @return [void]
-    # @todo unstub for fat files
-    def self.change_install_name(filename, old_name, new_name)
+    def self.change_install_name(filename, old_name, new_name, options = {})
       file = MachO.open(filename)
 
-      file.change_install_name(old_name, new_name)
+      file.change_install_name(old_name, new_name, options)
       file.write!
     end
 
@@ -38,28 +42,43 @@ module MachO
     # @param filename [String] the Mach-O or Fat binary being modified
     # @param old_path [String] the old runtime path
     # @param new_path [String] the new runtime path
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) whether or not to fail loudly
+    #  with an exception if the change cannot be performed
     # @return [void]
-    # @todo unstub
-    def self.change_rpath(filename, old_path, new_path)
-      raise UnimplementedError.new("changing rpaths in a Mach-O")
+    def self.change_rpath(filename, old_path, new_path, options = {})
+      file = MachO.open(filename)
+
+      file.change_rpath(old_path, new_path, options)
+      file.write!
     end
 
     # Add a runtime path to a Mach-O or Fat binary, overwriting the source file.
     # @param filename [String] the Mach-O or Fat binary being modified
     # @param new_path [String] the new runtime path
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) whether or not to fail loudly
+    #  with an exception if the change cannot be performed
     # @return [void]
-    # @todo unstub
-    def self.add_rpath(filename, new_path)
-      raise UnimplementedError.new("adding rpaths to a Mach-O")
+    def self.add_rpath(filename, new_path, options = {})
+      file = MachO.open(filename)
+
+      file.add_rpath(new_path, options)
+      file.write!
     end
 
     # Delete a runtime path from a Mach-O or Fat binary, overwriting the source file.
     # @param filename [String] the Mach-O or Fat binary being modified
     # @param old_path [String] the old runtime path
+    # @param options [Hash]
+    # @option options [Boolean] :strict (true) whether or not to fail loudly
+    #  with an exception if the change cannot be performed
     # @return [void]
-    # @todo unstub
-    def self.delete_rpath(filename, old_path)
-      raise UnimplementedError.new("removing rpaths from a Mach-O")
+    def self.delete_rpath(filename, old_path, options = {})
+      file = MachO.open(filename)
+
+      file.delete_rpath(old_path, options)
+      file.write!
     end
   end
 end

data/lib/macho/utils.rb

@@ -1,48 +1,96 @@
 module MachO
-  # @param value [Fixnum] the number being rounded
-  # @param round [Fixnum] the number being rounded with
-  # @return [Fixnum] the next number >= `value` such that `round` is its divisor
-  # @see http://www.opensource.apple.com/source/cctools/cctools-870/libstuff/rnd.c
-  def self.round(value, round)
-    round -= 1
-    value += round
-    value &= ~round
-    value
-  end
+  # A collection of utility functions used throughout ruby-macho.
+  module Utils
+    # Rounds a value to the next multiple of the given round.
+    # @param value [Fixnum] the number being rounded
+    # @param round [Fixnum] the number being rounded with
+    # @return [Fixnum] the rounded value
+    # @see http://www.opensource.apple.com/source/cctools/cctools-870/libstuff/rnd.c
+    def self.round(value, round)
+      round -= 1
+      value += round
+      value &= ~round
+      value
+    end
 
-  # @param num [Fixnum] the number being checked
-  # @return [Boolean] true if `num` is a valid Mach-O magic number, false otherwise
-  def self.magic?(num)
-    MH_MAGICS.has_key?(num)
-  end
+    # Returns the number of bytes needed to pad the given size to the given alignment.
+    # @param size [Fixnum] the unpadded size
+    # @param alignment [Fixnum] the number to alignment the size with
+    # @return [Fixnum] the number of pad bytes required
+    def self.padding_for(size, alignment)
+      round(size, alignment) - size
+    end
 
-  # @param num [Fixnum] the number being checked
-  # @return [Boolean] true if `num` is a valid Fat magic number, false otherwise
-  def self.fat_magic?(num)
-    num == FAT_MAGIC
-  end
+    # Converts an abstract (native-endian) String#unpack format to big or little.
+    # @param format [String] the format string being converted
+    # @param endianness [Symbol] either `:big` or `:little`
+    # @return [String] the converted string
+    def self.specialize_format(format, endianness)
+      modifier = endianness == :big ? ">" : "<"
+      format.tr("=", modifier)
+    end
 
-  # @param num [Fixnum] the number being checked
-  # @return [Boolean] true if `num` is a valid 32-bit magic number, false otherwise
-  def self.magic32?(num)
-    num == MH_MAGIC || num == MH_CIGAM
-  end
+    # Packs tagged strings into an aligned payload.
+    # @param fixed_offset [Fixnum] the baseline offset for the first packed string
+    # @param alignment [Fixnum] the alignment value to use for packing
+    # @param strings [Hash] the labeled strings to pack
+    # @return [Array<String, Hash>] the packed string and labeled offsets
+    def self.pack_strings(fixed_offset, alignment, strings = {})
+      offsets = {}
+      next_offset = fixed_offset
+      payload = ""
 
-  # @param num [Fixnum] the number being checked
-  # @return [Boolean] true if `num` is a valid 64-bit magic number, false otherwise
-  def self.magic64?(num)
-    num == MH_MAGIC_64 || num == MH_CIGAM_64
-  end
+      strings.each do |key, string|
+        offsets[key] = next_offset
+        payload << string
+        payload << "\x00"
+        next_offset += string.bytesize + 1
+      end
 
-  # @param num [Fixnum] the number being checked
-  # @return [Boolean] true if `num` is a valid little-endian magic number, false otherwise
-  def self.little_magic?(num)
-    num == MH_CIGAM || num == MH_CIGAM_64
-  end
+      payload << "\x00" * padding_for(fixed_offset + payload.bytesize, alignment)
+      [payload, offsets]
+    end
+
+    # Compares the given number to valid Mach-O magic numbers.
+    # @param num [Fixnum] the number being checked
+    # @return [Boolean] true if `num` is a valid Mach-O magic number, false otherwise
+    def self.magic?(num)
+      MH_MAGICS.key?(num)
+    end
+
+    # Compares the given number to valid Fat magic numbers.
+    # @param num [Fixnum] the number being checked
+    # @return [Boolean] true if `num` is a valid Fat magic number, false otherwise
+    def self.fat_magic?(num)
+      num == FAT_MAGIC
+    end
+
+    # Compares the given number to valid 32-bit Mach-O magic numbers.
+    # @param num [Fixnum] the number being checked
+    # @return [Boolean] true if `num` is a valid 32-bit magic number, false otherwise
+    def self.magic32?(num)
+      num == MH_MAGIC || num == MH_CIGAM
+    end
+
+    # Compares the given number to valid 64-bit Mach-O magic numbers.
+    # @param num [Fixnum] the number being checked
+    # @return [Boolean] true if `num` is a valid 64-bit magic number, false otherwise
+    def self.magic64?(num)
+      num == MH_MAGIC_64 || num == MH_CIGAM_64
+    end
+
+    # Compares the given number to valid little-endian magic numbers.
+    # @param num [Fixnum] the number being checked
+    # @return [Boolean] true if `num` is a valid little-endian magic number, false otherwise
+    def self.little_magic?(num)
+      num == MH_CIGAM || num == MH_CIGAM_64
+    end
 
-  # @param num [Fixnum] the number being checked
-  # @return [Boolean] true if `num` is a valid big-endian magic number, false otherwise
-  def self.big_magic?(num)
-    num == MH_CIGAM || num == MH_CIGAM_64
+    # Compares the given number to valid big-endian magic numbers.
+    # @param num [Fixnum] the number being checked
+    # @return [Boolean] true if `num` is a valid big-endian magic number, false otherwise
+    def self.big_magic?(num)
+      num == MH_CIGAM || num == MH_CIGAM_64
+    end
   end
 end

data/lib/macho/view.rb

@@ -0,0 +1,23 @@
+module MachO
+  # A representation of some unspecified Mach-O data.
+  class MachOView
+    # @return [String] the raw Mach-O data
+    attr_reader :raw_data
+
+    # @return [Symbol] the endianness of the data (`:big` or `:little`)
+    attr_reader :endianness
+
+    # @return [Fixnum] the offset of the relevant data (in {#raw_data})
+    attr_reader :offset
+
+    # Creates a new MachOView.
+    # @param raw_data [String] the raw Mach-O data
+    # @param endianness [Symbol] the endianness of the data
+    # @param offset [Fixnum] the offset of the relevant data
+    def initialize(raw_data, endianness, offset)
+      @raw_data = raw_data
+      @endianness = endianness
+      @offset = offset
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruby-macho
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.5
 platform: ruby
 authors:
 - William Woodruff
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-06-18 00:00:00.000000000 Z
+date: 2016-08-07 00:00:00.000000000 Z
 dependencies: []
 description: A library for viewing and manipulating Mach-O files in Ruby.
 email: william@tuffbizz.com
@@ -30,6 +30,7 @@ files:
 - lib/macho/structure.rb
 - lib/macho/tools.rb
 - lib/macho/utils.rb
+- lib/macho/view.rb
 homepage: https://github.com/Homebrew/ruby-macho
 licenses:
 - MIT
@@ -55,3 +56,4 @@ signing_key:
 specification_version: 4
 summary: ruby-macho - Mach-O file analyzer.
 test_files: []
+has_rdoc: