ruby-macho 0.0.9 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 119afdca4c1793c3bc3f8285c88a8126ab4e1e76
-  data.tar.gz: 26346fa156b237e2606e8b005c95330bc1b194ad
+  metadata.gz: b2197be0a734893a06de0c2a50c78a125e1e0f7b
+  data.tar.gz: 6333cb31cc35794f81b35c1e5f5a3e5d8f63d509
 SHA512:
-  metadata.gz: 413afe10c917e3e7365711b821904f058d48a9c92a6fcf36d1fecd132b1bbd5971e2d6e547b1684fb46061a328cfaf71afc35788068a1480d33bbde24a0e6d1d
-  data.tar.gz: cf66bd02bac6b2956bbad64d2f0f82de46e339713ab9ddbfecea88902399f304a58fcb8588294025f647180077f4e054feb40ed85bbeaee941aa00aed26babca
+  metadata.gz: 2965997a877ab4c4d675f7e51b8b8ddb7fa82dda776e6b2fe5bb10bcfbf27845809723dc072257076a87c351fe03321839d669dd517ec36e0f57453a7831bef5
+  data.tar.gz: 326050eb144d5e9c415dcf58d10fb3da1c565044fae5bb3d1482fe9f15124c64490f95b2e595748b8f567e69db1cc8e5797cf0917c855150ae034bb9094b456c

data/lib/macho.rb

@@ -9,6 +9,7 @@ require "#{File.dirname(__FILE__)}/macho/exceptions"
 require "#{File.dirname(__FILE__)}/macho/utils"
 require "#{File.dirname(__FILE__)}/macho/tools"
 
+# The primary namespace for ruby-macho.
 module MachO
 	# Opens the given filename as a MachOFile or FatFile, depending on its magic.
 	# @param filename [String] the file being opened

data/lib/macho/exceptions.rb

@@ -1,59 +1,65 @@
 module MachO
-	# generic toplevel error
+	# A generic Mach-O error in execution.
 	class MachOError < RuntimeError
 	end
 
-	# raised when a file's magic bytes are not valid mach-o magic
+	# Raised when a file's magic bytes are not valid Mach-O magic.
 	class MagicError < MachOError
+		# @param num [Fixnum] the unknown number
 		def initialize(num)
 			super "Unrecognized Mach-O magic: 0x#{"%02x" % num}"
 		end
 	end
 
-	# raised when a fat binary is loaded with MachOFile
+	# Raised when a fat binary is loaded with MachOFile.
 	class FatBinaryError < MachOError
 		def initialize
 			super "Fat binaries must be loaded with MachO::FatFile"
 		end
 	end
 
-	# raised when a mach-o is loaded with FatFile
+	# Raised when a Mach-O is loaded with FatFile.
 	class MachOBinaryError < MachOError
 		def initialize
 			super "Normal binaries must be loaded with MachO::MachOFile"
 		end
 	end
 
-	# raised when the CPU type is unknown
+	# Raised when the CPU type is unknown.
 	class CPUTypeError < MachOError
+		# @param num [Fixnum] the unknown number
 		def initialize(num)
 			super "Unrecognized CPU type: 0x#{"%02x" % num}"
 		end
 	end
 
-	# raised when the CPU subtype is unknown
+	# Raised when the CPU subtype is unknown.
 	class CPUSubtypeError < MachOError
+		# @param num [Fixnum] the unknown number
 		def initialize(num)
 			super "Unrecognized CPU sub-type: 0x#{"%02x" % num}"
 		end
 	end
 
-	# raised when a mach-o file's filetype field is unknown
+	# Raised when a mach-o file's filetype field is unknown.
 	class FiletypeError < MachOError
+		# @param num [Fixnum] the unknown number
 		def initialize(num)
 			super "Unrecognized Mach-O filetype code: 0x#{"%02x" % num}"
 		end
 	end
 
-	# raised when an unknown load command is encountered
+	# Raised when an unknown load command is encountered.
 	class LoadCommandError < MachOError
+		# @param num [Fixnum] the unknown number
 		def initialize(num)
 			super "Unrecognized Mach-O load command: 0x#{"%02x" % num}"
 		end
 	end
 
-	# raised when load commands are too large to fit in the current file
+	# Raised when load commands are too large to fit in the current file.
 	class HeaderPadError < MachOError
+		# @param filename [String] the filename
 		def initialize(filename)
 			super "Updated load commands do not fit in the header of " +
 			"#{filename}. #{filename} needs to be relinked, possibly with " +
@@ -61,8 +67,9 @@ module MachO
 		end
 	end
 
-	# raised when attempting to change a dylib name that doesn't exist
+	# Raised when attempting to change a dylib name that doesn't exist.
 	class DylibUnknownError < MachOError
+		# @param dylib [String] the unknown shared library name
 		def initialize(dylib)
 			super "No such dylib name: #{dylib}"
 		end

data/lib/macho/fat_file.rb

@@ -105,7 +105,7 @@ module MachO
 		end
 
 		# Write all (fat) data to the file used to initialize the instance.
-		# IMPORTANT: Overwrites all data in the file!
+		# @note Overwrites all data in the file!
 		def write!
 			File.open(@filename, "wb") { |f| f.write(@raw_data) }
 		end
@@ -158,6 +158,7 @@ module MachO
 
 		# @todo this needs to be redesigned. arch[:offset] and arch[:size] are
 		# already out-of-date, and the header needs to be synchronized as well.
+		# @private
 		def synchronize_raw_data
 			machos.each_with_index do |macho, i|
 				arch = fat_archs[i]

data/lib/macho/headers.rb

@@ -1,12 +1,23 @@
 module MachO
-	# magic numbers used in Mach-O files
-	FAT_MAGIC = 0xcafebabe # big-endian fat magic
-	FAT_CIGAM = 0xbebafeca # little-endian fat magic
-	MH_MAGIC = 0xfeedface # 32-bit big-endian magic
-	MH_CIGAM = 0xcefaedfe # 32-bit little-endian magic
-	MH_MAGIC_64 = 0xfeedfacf # 64-bit big-endian magic
-	MH_CIGAM_64 = 0xcffaedfe # 64-bit little-endian magic
+	# big-endian fat magic
+	FAT_MAGIC = 0xcafebabe
 
+	# little-endian fat magic
+	FAT_CIGAM = 0xbebafeca
+
+	# 32-bit big-endian magic
+	MH_MAGIC = 0xfeedface
+
+	# 32-bit little-endian magic
+	MH_CIGAM = 0xcefaedfe
+
+	# 64-bit big-endian magic
+	MH_MAGIC_64 = 0xfeedfacf
+
+	# 64-bit little-endian magic
+	MH_CIGAM_64 = 0xcffaedfe
+
+	# association of magic numbers to string representations
 	MH_MAGICS = {
 		FAT_MAGIC => "FAT_MAGIC",
 		FAT_CIGAM => "FAT_CIGAM",
@@ -16,18 +27,28 @@ module MachO
 		MH_CIGAM_64 => "MH_CIGAM_64"
 	}
 
-	# capability bits used in the definition of cputype
-	CPU_ARCH_MASK = 0xff000000
+	# mask for CPUs with 64-bit architectures (when running a 64-bit ABI?)
 	CPU_ARCH_ABI64 = 0x01000000
 
-	# (select) values for cputype in MachHeader/MachHeader64
+	# any CPU (unused?)
 	CPU_TYPE_ANY = -1
+
+	# x86 compatible CPUs
 	CPU_TYPE_X86 = 0x07
+
+	# i386 and later compatible CPUs
 	CPU_TYPE_I386 = CPU_TYPE_X86
+
+	# x86_64 (AMD64) compatible CPUs
 	CPU_TYPE_X86_64 = (CPU_TYPE_X86 | CPU_ARCH_ABI64)
+
+	# PowerPC compatible CPUs (7400 series?)
 	CPU_TYPE_POWERPC = 0x24
+
+	# PowerPC64 compatible CPUs (970 series?)
 	CPU_TYPE_POWERPC64 = (CPU_TYPE_POWERPC | CPU_ARCH_ABI64)
 
+	# association of cpu types to string representations
 	CPU_TYPES = {
 		CPU_TYPE_ANY => "CPU_TYPE_ANY",
 		CPU_TYPE_X86 => "CPU_TYPE_X86",
@@ -37,34 +58,59 @@ module MachO
 		CPU_TYPE_POWERPC64 => "CPU_TYPE_POWERPC64"
 	}
 
-	# capability bits used in the definition of cpusubtype
-	# http://llvm.org/docs/doxygen/html/Support_2MachO_8h_source.html
+	# mask for CPU subtype capabilities
 	CPU_SUBTYPE_MASK = 0xff000000
+
+	# 64-bit libraries (undocumented!)
+	# @see http://llvm.org/docs/doxygen/html/Support_2MachO_8h_source.html
 	CPU_SUBTYPE_LIB64 = 0x80000000
 
-	# (select) cpusubtypes
+	# all x86-type CPUs
 	CPU_SUBTYPE_X86_ALL = 3
+
+	# all x86-type CPUs (what makes this different from CPU_SUBTYPE_X86_ALL?)
 	CPU_SUBTYPE_X86_ARCH1 = 4
 
+	# association of cpu subtypes to string representations
 	CPU_SUBTYPES = {
 		CPU_SUBTYPE_X86_ALL => "CPU_SUBTYPE_X86_ALL",
 		CPU_SUBTYPE_X86_ARCH1 => "CPU_SUBTYPE_X86_ARCH1"
 	}
 
-	# values for filetype in MachHeader/MachHeader64
-	MH_OBJECT = 0x1			# relocatable object file
-	MH_EXECUTE = 0x2		# demand paged executable file
-	MH_FVMLIB = 0x3			# fixed VM shared library file
-	MH_CORE = 0x4			# core file
-	MH_PRELOAD = 0x5		# preloaded executable file
-	MH_DYLIB = 0x6			# dynamically bound shared library
-	MH_DYLINKER = 0x7		# dynamic link editor
-	MH_BUNDLE = 0x8			# dynamically bound bundle file
-	MH_DYLIB_STUB = 0x9		# shared library stub for static linking only no,
-							# section contents
-	MH_DSYM = 0xa			# companion file with only debug sections
-	MH_KEXT_BUNDLE = 0xb	# x86_64 lexts
+	# relocatable object file
+	MH_OBJECT = 0x1
 
+	# demand paged executable file
+	MH_EXECUTE = 0x2
+
+	# fixed VM shared library file
+	MH_FVMLIB = 0x3
+
+	# core dump file
+	MH_CORE = 0x4
+
+	# preloaded executable file
+	MH_PRELOAD = 0x5
+
+	# dynamically bound shared library
+	MH_DYLIB = 0x6
+
+	# dynamic link editor
+	MH_DYLINKER = 0x7
+
+	# dynamically bound bundle file
+	MH_BUNDLE = 0x8
+
+	# shared library stub for static linking only, no section contents
+	MH_DYLIB_STUB = 0x9
+
+	# companion file with only debug sections
+	MH_DSYM = 0xa
+
+	# x86_64 kexts
+	MH_KEXT_BUNDLE = 0xb
+
+	# association of filetypes to string representations
 	MH_FILETYPES = {
 		MH_OBJECT => "MH_OBJECT",
 		MH_EXECUTE => "MH_EXECUTE",
@@ -79,34 +125,85 @@ module MachO
 		MH_KEXT_BUNDLE => "MH_KEXT_BUNDLE"
 	}
 
-	# values for flags field in MachHeader/MachHeader64
+	# the object file has no undefined references (flag)
 	MH_NOUNDEFS = 0x1
+
+	# the object file is the output of an incremental link against a base file (flag)
 	MH_INCRLINK = 0x2
+
+	# the object file is input for the dynamic linker and can't be staticly link edited again (flag)
 	MH_DYLDLINK = 0x4
+
+	# the object file's undefined references are bound by the dynamic linker when loaded (flag)
 	MH_BINDATLOAD = 0x8
+
+	# the file has its dynamic undefined references prebound (flag)
 	MH_PREBOUND = 0x10
+
+	# the file has its read-only and read-write segments split (flag)
 	MH_SPLIT_SEGS = 0x20
+
+	# the shared library init routine is to be run lazily via catching memory faults to its writeable segments (obsolete) (flag)
 	MH_LAZY_INIT = 0x40
+
+	# the image is using two-level name space bindings (flag)
 	MH_TWOLEVEL = 0x80
+
+	# the executable is forcing all images to use flat name space bindings (flag)
 	MH_FORCE_FLAT = 0x100
+
+	# this umbrella guarantees no multiple defintions of symbols in its sub-images so the two-level namespace hints can always be used (flag)
 	MH_NOMULTIDEFS = 0x200
+
+	# do not have dyld notify the prebinding agent about this executable (flag)
 	MH_NOPREFIXBINDING = 0x400
+
+	# the binary is not prebound but can have its prebinding redone. only used when MH_PREBOUND is not set (flag)
 	MH_PREBINDABLE = 0x800
+
+	# indicates that this binary binds to all two-level namespace modules of its dependent libraries. only used when MH_PREBINDABLE and MH_TWOLEVEL are both set (flag)
 	MH_ALLMODSBOUND = 0x1000
+
+	# safe to divide up the sections into sub-sections via symbols for dead code stripping (flag)
 	MH_SUBSECTIONS_VIA_SYMBOLS = 0x2000
+
+	# the binary has been canonicalized via the unprebind operation (flag)
 	MH_CANONICAL = 0x4000
+
+	# the final linked image contains external weak symbols (flag)
 	MH_WEAK_DEFINES = 0x8000
+
+	# the final linked image uses weak symbols (flag)
 	MH_BINDS_TO_WEAK = 0x10000
+
+	# When this bit is set, all stacks in the task will be given stack execution privilege.  Only used in MH_EXECUTE filetypes (flag)
 	MH_ALLOW_STACK_EXECUTION = 0x20000
+
+	# When this bit is set, the binary declares it is safe for use in processes with uid zero (flag)
 	MH_ROOT_SAFE = 0x40000
+
+	# When this bit is set, the binary declares it is safe for use in processes when issetugid() is true (flag)
 	MH_SETUID_SAFE = 0x80000
+
+	# When this bit is set on a dylib, the static linker does not need to examine dependent dylibs to see if any are re-exported (flag)
 	MH_NO_REEXPORTED_DYLIBS = 0x100000
+
+	# When this bit is set, the OS will load the main executable at a random address.  Only used in MH_EXECUTE filetypes (flag)
 	MH_PIE = 0x200000
+
+	# Only for use on dylibs.  When linking against a dylib that has this bit set, the static linker will automatically not create a LC_LOAD_DYLIB load command to the dylib if no symbols are being referenced from the dylib (flag)
 	MH_DEAD_STRIPPABLE_DYLIB = 0x400000
+
+	# Contains a section of type S_THREAD_LOCAL_VARIABLES (flag)
 	MH_HAS_TLV_DESCRIPTORS = 0x800000
+
+	# When this bit is set, the OS will run the main executable with a non-executable heap even on platforms (e.g. i386) that don't require it. Only used in MH_EXECUTE filetypes (flag)
 	MH_NO_HEAP_EXECUTION = 0x1000000
+
+	# The code was linked for use in an application extension (flag)
 	MH_APP_EXTENSION_SAFE = 0x02000000
 
+	# association of mach header flags to string representations
 	MH_FLAGS = {
 		MH_NOUNDEFS => "MH_NOUNDEFS",
 		MH_INCRLINK => "MH_INCRLINK",
@@ -136,7 +233,6 @@ module MachO
 		MH_APP_EXTENSION_SAFE => "MH_APP_EXTENSION_SAFE"
 	}
 
-	# 'Fat' binaries envelop Mach-O binaries so include them for completeness,
 	# Fat binary header structure
 	class FatHeader < CStruct
 		uint32 :magic
@@ -162,6 +258,10 @@ module MachO
 		uint32 :sizeofcmds
 		uint32 :flags
 
+		# @example
+		#  puts "this mach-o has position-independent execution" if header.flag?(MH_PIE)
+		# @param flag [Fixnum] a mach header flag constant
+		# @return [Boolean] true if `flag` is present in the header's flag section
 		def flag?(flag)
 			flags & flag == flag
 		end
@@ -178,6 +278,10 @@ module MachO
 		uint32 :flags
 		uint32 :reserved
 
+		# @example
+		#  puts "this mach-o has position-independent execution" if header.flag?(MH_PIE)
+		# @param flag [Fixnum] a mach header flag constant
+		# @return [Boolean] true if `flag` is present in the header's flag section
 		def flag?(flag)
 			flags & flag == flag
 		end

data/lib/macho/load_commands.rb

@@ -3,55 +3,148 @@ module MachO
 	# LC_REQ_DYLD to be recognized by the dynamic linder (dyld)
 	LC_REQ_DYLD = 0x80000000
 
-	# values for cmd in LoadCommand
+	# segment of this file to be mapped
 	LC_SEGMENT = 0x1
+
+	# link-edit stab symbol table info
 	LC_SYMTAB = 0x2
+
+	# link-edit gdb symbol table info (obsolete)
 	LC_SYMSEG = 0x3
+
+	# thread
 	LC_THREAD = 0x4
+
+	# unix thread (includes a stack)
 	LC_UNIXTHREAD = 0x5
+
+	# load a specified fixed VM shared library
 	LC_LOADFVMLIB = 0x6
+
+	# fixed VM shared library identification
 	LC_IDFVMLIB = 0x7
+
+	# object identification info (obsolete)
 	LC_IDENT = 0x8
+
+	# fixed VM file inclusion (internal use)
 	LC_FVMFILE = 0x9
+
+	# prepage command (internal use) 
 	LC_PREPAGE = 0xa
+
+	# dynamic link-edit symbol table info
 	LC_DYSYMTAB = 0xb
+
+	# load a dynamically linked shared library
 	LC_LOAD_DYLIB = 0xc
+
+	# dynamically linked shared lib ident
 	LC_ID_DYLIB = 0xd
+
+	# load a dynamic linker
 	LC_LOAD_DYLINKER = 0xe
+
+	# dynamic linker identification
 	LC_ID_DYLINKER = 0xf
+
+	# modules prebound for a dynamically linked shared library
 	LC_PREBOUND_DYLIB = 0x10
+
+	# image routines
 	LC_ROUTINES = 0x11
+
+	# sub framework
 	LC_SUB_FRAMEWORK = 0x12
+
+	# sub umbrella
 	LC_SUB_UMBRELLA = 0x13
+
+	# sub umbrella
 	LC_SUB_CLIENT = 0x14
+
+	# sub umbrella
 	LC_SUB_LIBRARY = 0x15
+
+	# two-level namespace lookup hints
 	LC_TWOLEVEL_HINTS = 0x16
+
+	# prebind checksum 
 	LC_PREBIND_CKSUM = 0x17
+
+	# load a dynamically linked shared library that is allowed to be missing (all symbols are weak imported).
 	LC_LOAD_WEAK_DYLIB = (0x18 | LC_REQ_DYLD)
+
+	# 64-bit segment of this file to be mapped
 	LC_SEGMENT_64 = 0x19
+
+	# 64-bit image routines
 	LC_ROUTINES_64 = 0x1a
+
+	# the uuid
 	LC_UUID = 0x1b
+
+	# runpath additions
 	LC_RPATH = (0x1c | LC_REQ_DYLD)
+
+	# local of code signature
 	LC_CODE_SIGNATURE = 0x1d
+
+	# local of info to split segments
 	LC_SEGMENT_SPLIT_INFO = 0x1e
+
+	# load and re-export dylib
 	LC_REEXPORT_DYLIB = (0x1f | LC_REQ_DYLD)
+
+	# delay load of dylib until first use
 	LC_LAZY_LOAD_DYLIB = 0x20
+
+	# encrypted segment information
 	LC_ENCRYPTION_INFO = 0x21
+
+	# compressed dyld information
 	LC_DYLD_INFO = 0x22
+
+	# compressed dyld information only
 	LC_DYLD_INFO_ONLY = (0x22 | LC_REQ_DYLD)
+
+	# load upward dylib
 	LC_LOAD_UPWARD_DYLIB = (0x23 | LC_REQ_DYLD)
+
+	# build for MacOSX min OS version
 	LC_VERSION_MIN_MACOSX = 0x24
+
+	# build for iPhoneOS min OS version
 	LC_VERSION_MIN_IPHONEOS = 0x25
+
+	# compressed table of function start addresses
 	LC_FUNCTION_STARTS = 0x26
+
+	# string for dyld to treat like environment variable
 	LC_DYLD_ENVIRONMENT = 0x27
+
+	# replacement for LC_UNIXTHREAD
 	LC_MAIN = (0x28 | LC_REQ_DYLD)
+
+	# table of non-instructions in __text
 	LC_DATA_IN_CODE = 0x29
+
+	# source version used to build binary
 	LC_SOURCE_VERSION = 0x2a
+
+	# Code signing DRs copied from linked dylibs
 	LC_DYLIB_CODE_SIGN_DRS = 0x2b
+
+	# 64-bit encrypted segment information
 	LC_ENCRYPTION_INFO_64 = 0x2c
+
+	# linker options in MH_OBJECT files
 	LC_LINKER_OPTION = 0x2d
+
+	# linker options in MH_OBJECT files
 	LC_LINKER_OPTIMIZATION_HINT = 0x2e
 
+	# association of load commands to string representations
 	LOAD_COMMANDS = {
 		LC_SEGMENT => "LC_SEGMENT",
 		LC_SYMTAB => "LC_SYMTAB",
@@ -102,6 +195,7 @@ module MachO
 		LC_LINKER_OPTIMIZATION_HINT => "LC_LINKER_OPTIMIZATION_HINT"
 	}
 
+	# association of load commands to string representations of class names
 	LC_STRUCTURES = {
 		LC_SEGMENT => "SegmentCommand",
 		LC_SYMTAB => "SymtabCommand",
@@ -152,60 +246,102 @@ module MachO
 		LC_LINKER_OPTIMIZATION_HINT => "LinkeditDataCommand"
 	}
 
-	# currently known segment names
-	# we don't use these anywhere right now, but they're good to have
+	# pagezero segment name
 	SEG_PAGEZERO = "__PAGEZERO"
+
+	# text segment name
 	SEG_TEXT = "__TEXT"
+
+	# data segment name
 	SEG_DATA = "__DATA"
+
+	# objective-c runtime segment
 	SEG_OBJC = "__OBJC"
+
+	# icon segment
 	SEG_ICON = "__ICON"
+
+	# link editor structures segment
 	SEG_LINKEDIT = "__LINKEDIT"
+
+	# unix stack segment
 	SEG_UNIXSTACK = "__UNIXSTACK"
+
+	# segment for self-modifying code with RWX permissions
 	SEG_IMPORT = "__IMPORT"
 
-	# constant bits for flags in SegmentCommand, SegmentCommand64
+	# the file contents for this segment is for the high part of the VM space, the low part is zero filled (for stacks in core files)
 	SG_HIGHVM = 0x1
+
+	# this segment is the VM that is allocated by a fixed VM library, for overlap checking in the link editor
 	SG_FVMLIB = 0x2
+
+	# this segment has nothing that was relocated in it and nothing relocated to it, that is it maybe safely replaced without relocation
 	SG_NORELOC = 0x4
+
+	# this segment is protected.  if the segment starts at file offset 0, the first page of the segment is not protected.  all other pages of the segment are protected.
 	SG_PROTECTED_VERSION_1 = 0x8
 
 	# Mach-O load command structure
-	# this is the most generic load command - only cmd ID and size are
-	# represented, and no actual data. used when a more specific class
-	# isn't available/implemented
+	# This is the most generic load command - only cmd ID and size are
+	# represented, and no actual data. Used when a more specific class
+	# isn't available/implemented.
 	class LoadCommand < MachOStructure
-		attr_reader :offset, :cmd, :cmdsize
+		# @return [Fixnum] the offset in the file the command was created from
+		attr_reader :offset
+
+		# @return [Fixnum] the load command's identifying number
+		attr_reader :cmd
+
+		# @return [Fixnum] the size of the load command, in bytes
+		attr_reader :cmdsize
 
 		@format = "VV"
 		@sizeof = 8
 
+		# Creates a new LoadCommand given an offset and binary string
+		# @param offset [Fixnum] the offset to initialize with
+		# @param bin [String] the binary string to initialize with
+		# @return [MachO::LoadCommand] the new load command
+		# @private
 		def self.new_from_bin(offset, bin)
 			self.new(offset, *bin.unpack(@format))
 		end
 
+		# @param offset [Fixnum] the offset to initialize iwth
+		# @param cmd [Fixnum] the load command's identifying number
+		# @param cmdsize [Fixnum] the size of the load command in bytes
+		# @private
 		def initialize(offset, cmd, cmdsize)
 			@offset = offset
 			@cmd = cmd
 			@cmdsize = cmdsize
 		end
 
+		# @return [String] a string representation of the load command's identifying number
 		def to_s
 			LOAD_COMMANDS[cmd]
 		end
 	end
 
+	# A load command containing a single 128-bit unique random number identifying
+	# an object produced by static link editor. Corresponds to LC_UUID.
 	class UUIDCommand < LoadCommand
+		# @return [Array<Fixnum>] the UUID
 		attr_reader :uuid
 
 		@format = "VVa16"
 		@sizeof = 24
 
+		# @private
 		def initialize(offset, cmd, cmdsize, uuid)
 			super(offset, cmd, cmdsize)
 			@uuid = uuid.unpack("C16") # re-unpack for the actual UUID array
 		end
 	end
 
+	# A load command indicating that part of this file is to be mapped into
+	# the task's address space. Corresponds to LC_SEGMENT.
 	class SegmentCommand < LoadCommand
 		attr_reader :segname, :vmaddr, :vmsize, :fileoff, :filesize, :maxprot
 		attr_reader :initprot, :nsects, :flags
@@ -213,6 +349,7 @@ module MachO
 		@format = "VVa16VVVVVVVV"
 		@sizeof = 56
 
+		# @private
 		def initialize(offset, cmd, cmdsize, segname, vmaddr, vmsize, fileoff,
 				filesize, maxprot, initprot, nsects, flags)
 			super(offset, cmd, cmdsize)
@@ -227,11 +364,14 @@ module MachO
 			@flags = flags
 		end
 
+		# @return [String] the segment's name, with any trailing NULL characters removed
 		def segment_name
 			@segname.delete("\x00")
 		end
 	end
 
+	# A load command indicating that part of this file is to be mapped into
+	# the task's address space. Corresponds to LC_SEGMENT_64.
 	class SegmentCommand64 < LoadCommand
 		attr_reader :segname, :vmaddr, :vmsize, :fileoff, :filesize, :maxprot
 		attr_reader :initprot, :nsects, :flags
@@ -239,6 +379,7 @@ module MachO
 		@format = "VVa16QQQQVVVV"
 		@sizeof = 72
 
+		# @private
 		def initialize(offset, cmd, cmdsize, segname, vmaddr, vmsize, fileoff,
 				filesize, maxprot, initprot, nsects, flags)
 			super(offset, cmd, cmdsize)
@@ -253,17 +394,22 @@ module MachO
 			@flags = flags
 		end
 
+		# @return [String] the segment's name, with any trailing NULL characters removed
 		def segment_name
 			@segname.delete("\x00")
 		end
 	end
 
+	# A load command representing some aspect of shared libraries, depending
+	# on filetype. Corresponds to LC_ID_DYLIB, LC_LOAD_DYLIB, LC_LOAD_WEAK_DYLIB,
+	# and LC_REEXPORT_DYLIB.
 	class DylibCommand < LoadCommand
 		attr_reader :name, :timestamp, :current_version, :compatibility_version
 
 		@format = "VVVVVV"
 		@sizeof = 24
 
+		# @private
 		def initialize(offset, cmd, cmdsize, name, timestamp, current_version,
 				compatibility_version)
 			super(offset, cmd, cmdsize)
@@ -274,24 +420,31 @@ module MachO
 		end
 	end
 
+	# A load command representing some aspect of the dynamic linker, depending
+	# on filetype. Corresponds to LC_ID_DYLINKER, LC_LOAD_DYLINKER, and
+	# LC_DYLD_ENVIRONMENT.
 	class DylinkerCommand < LoadCommand
 		attr_reader :name
 
 		@format = "VVV"
 		@sizeof = 12
 
+		# @private
 		def initialize(offset, cmd, cmdsize, name)
 			super(offset, cmd, cmdsize)
 			@name = name
 		end
 	end
 
+	# A load command used to indicate dynamic libraries used in prebinding.
+	# Corresponds to LC_PREBOUND_DYLIB.
 	class PreboundDylibCommand < LoadCommand
 		attr_reader :name, :nmodules, :linked_modules
 
 		@format = "VVVVV"
 		@sizeof = 20
 
+		# @private
 		def initialize(offset, cmd, cmdsize, name, nmodules, linked_modules)
 			super(offset, cmd, cmdsize)
 			@name = name
@@ -300,12 +453,15 @@ module MachO
 		end
 	end
 
-	# NOTE: cctools-870 has all fields of thread_command commented out
-	# except common ones (cmd, cmdsize)
+	# A load command used to represent threads.
+	# @note cctools-870 has all fields of thread_command commented out except common ones (cmd, cmdsize)
 	class ThreadCommand < LoadCommand
 
 	end
 
+	# A load command containing the address of the dynamic shared library
+	# initialization routine and an index into the module table for the module
+	# that defines the routine. Corresponds to LC_ROUTINES.
 	class RoutinesCommand < LoadCommand
 		attr_reader :init_address, :init_module, :reserved1, :reserved2
 		attr_reader :reserved3, :reserved4, :reserved5, :reserved6
@@ -313,6 +469,7 @@ module MachO
 		@format = "VVVVVVVVVV"
 		@sizeof = 40
 
+		# @private
 		def initialize(offset, cmd, cmdsize, init_address, init_module,
 				reserved1, reserved2, reserved3, reserved4, reserved5,
 				reserved6)
@@ -328,6 +485,9 @@ module MachO
 		end
 	end
 
+	# A load command containing the address of the dynamic shared library
+	# initialization routine and an index into the module table for the module
+	# that defines the routine. Corresponds to LC_ROUTINES_64.
 	class RoutinesCommand64 < LoadCommand
 		attr_reader :init_address, :init_module, :reserved1, :reserved2
 		attr_reader :reserved3, :reserved4, :reserved5, :reserved6
@@ -335,6 +495,7 @@ module MachO
 		@format = "VVQQQQQQQQ"
 		@sizeof = 72
 
+		# @private
 		def initialize(offset, cmd, cmdsize, init_address, init_module,
 				reserved1, reserved2, reserved3, reserved4, reserved5,
 				reserved6)
@@ -350,60 +511,85 @@ module MachO
 		end
 	end
 
+	# A load command signifying membership of a subframework containing the name
+	# of an umbrella framework. Corresponds to LC_SUB_FRAMEWORK.
 	class SubFrameworkCommand < LoadCommand
 		attr_reader :umbrella
 
 		@format = "VVV"
 		@sizeof = 12
 
+		# @private
 		def initialize(offset, cmd, cmdsize, umbrella)
 			super(offset, cmd, cmdsize)
 			@umbrella = umbrella
 		end
 	end
 
+	# A load command signifying membership of a subumbrella containing the name
+	# of an umbrella framework. Corresponds to LC_SUB_UMBRELLA.
 	class SubUmbrellaCommand < LoadCommand
 		attr_reader :sub_umbrella
 
 		@format = "VVV"
 		@sizeof = 12
 
+		# @private
 		def initialize(offset, cmd, cmdsize, sub_umbrella)
 			super(offset, cmd, cmdsize)
 			@sub_umbrella = sub_umbrella
 		end
 	end
 
+	# A load command signifying a sublibrary of a shared library. Corresponds
+	# to LC_SUB_LIBRARY.
 	class SubLibraryCommand < LoadCommand
 		attr_reader :sub_library
 
 		@format = "VVV"
 		@sizeof = 12
 
+		# @private
 		def initialize(offset, cmd, cmdsize, sub_library)
 			super(offset, cmd, cmdsize)
 			@sub_library = sub_library
 		end
 	end
 
+	# A load command signifying a shared library that is a subframework of
+	# an umbrella framework. Corresponds to LC_SUB_CLIENT.
 	class SubClientCommand < LoadCommand
 		attr_reader :sub_client
 
 		@format = "VVV"
 		@sizeof = 12
 
+		# @private
 		def initialize(offset, cmd, cmdsize, sub_client)
 			super(offset, cmd, cmdsize)
 			@sub_client = sub_client
 		end
 	end
 
+	# A load command containing the offsets and sizes of the link-edit 4.3BSD
+	# "stab" style symbol table information. Corresponds to LC_SYMTAB.
 	class SymtabCommand < LoadCommand
-		attr_reader :symoff, :nsyms, :stroff, :strsize
+		# @return [Fixnum] the symbol table's offset
+		attr_reader :symoff
+
+		# @return [Fixnum] the number of symbol table entries
+		attr_reader :nsyms
+
+		# @return the string table's offset
+		attr_reader :stroff
+
+		# @return the string table size in bytes
+		attr_reader :strsize
 
 		@format = "VVVVVV"
 		@sizeof = 24
 
+		# @private
 		def initialize(offset, cmd, cmdsize, symoff, nsyms, stroff, strsize)
 			super(offset, cmd, cmdsize)
 			@symoff = symoff
@@ -413,16 +599,51 @@ module MachO
 		end
 	end
 
+	# A load command containing symbolic information needed to support data
+	# structures used by the dynamic link editor. Corresponds to LC_DYSYMTAB.
 	class DysymtabCommand < LoadCommand
-		attr_reader :ilocalsym, :nlocalsym, :iextdefsym, :nextdefsym
-		attr_reader :iundefsym, :nundefsym, :tocoff, :ntoc, :modtaboff
-		attr_reader :nmodtab, :extrefsymoff, :nextrefsyms, :indirectsymoff
-		attr_reader :nindirectsyms, :extreloff, :nextrel, :locreloff, :nlocrel
+		attr_reader :ilocalsym
+
+		attr_reader :nlocalsym
+
+		attr_reader :iextdefsym
+
+		attr_reader :nextdefsym
+
+		attr_reader :iundefsym
+
+		attr_reader :nundefsym
+
+		attr_reader :tocoff
+
+		attr_reader :ntoc
+
+		attr_reader :modtaboff
+
+		attr_reader :nmodtab
+
+		attr_reader :extrefsymoff
+
+		attr_reader :nextrefsyms
+
+		attr_reader :indirectsymoff
+
+		attr_reader :nindirectsyms
+
+		attr_reader :extreloff
+
+		attr_reader :nextrel
+
+		attr_reader :locreloff
+
+		attr_reader :nlocrel
+
 
 		@format = "VVVVVVVVVVVVVVVVVVVV"
 		@sizeof = 80
 
 		# ugh
+		# @private
 		def initialize(offset, cmd, cmdsize, ilocalsym, nlocalsym, iextdefsym,
 				nextdefsym, iundefsym, nundefsym, tocoff, ntoc, modtaboff,
 				nmodtab, extrefsymoff, nextrefsyms, indirectsymoff,
@@ -449,12 +670,19 @@ module MachO
 		end
 	end
 
+	# A load command containing the offset and number of hints in the two-level
+	# namespace lookup hints table. Corresponds to LC_TWOLEVEL_HINTS.
 	class TwolevelHintsCommand < LoadCommand
-		attr_reader :htoffset, :nhints
+		# @return [Fixnum] the offset to the hint table
+		attr_reader :htoffset
+
+		# @return [Fixnum] the number of hints in the hint table
+		attr_reader :nhints
 
 		@format = "VVVV"
 		@sizeof = 16
 
+		# @private
 		def initialize(offset, cmd, cmdsize, htoffset, nhints)
 			super(offset, cmd, cmdsize)
 			@htoffset = htoffset
@@ -462,36 +690,52 @@ module MachO
 		end
 	end
 
+	# A load command containing the value of the original checksum for prebound
+	# files, or zero. Corresponds to LC_PREBIND_CKSUM.
 	class PrebindCksumCommand < LoadCommand
+		# @return [Fixnum] the checksum or 0
 		attr_reader :cksum
 
 		@format = "VVV"
 		@sizeof = 12
 
+		# @private
 		def initialize(offset, cmd, cmdsize, cksum)
 			super(offset, cmd, cmdsize)
 			@cksum = cksum
 		end
 	end
 
+	# A load command representing an rpath, which specifies a path that should
+	# be added to the current run path used to find @rpath prefixed dylibs.
+	# Corresponds to LC_RPATH.
 	class RpathCommand < LoadCommand
 		attr_reader :path
 
 		@format = "VVV"
 		@sizeof = 12
 
+		# @private
 		def initialize(offset, cmd, cmdsize, path)
 			super(offset, cmd, cmdsize)
 			@path = path
 		end
 	end
 
+	# A load command representing the offsets and sizes of a blob of data in
+	# the __LINKEDIT segment. Corresponds to LC_CODE_SIGNATURE, LC_SEGMENT_SPLIT_INFO,
+	# LC_FUNCTION_STARTS, LC_DATA_IN_CODE, LC_DYLIB_CODE_SIGN_DRS, and LC_LINKER_OPTIMIZATION_HINT.
 	class LinkeditDataCommand < LoadCommand
-		attr_reader :dataoff, :datasize
+		# @return [Fixnum] offset to the data in the __LINKEDIT segment
+		attr_reader :dataoff
+
+		# @return [Fixnum] size of the data in the __LINKEDIT segment
+		attr_reader :datasize
 
 		@format = "VVVV"
 		@sizeof = 16
 
+		# @private
 		def initialize(offset, cmd, cmdsize, dataoff, datasize)
 			super(offset, cmd, cmdsize)
 			@dataoff = dataoff
@@ -499,12 +743,22 @@ module MachO
 		end
 	end
 
+	# A load command representing the offset to and size of an encrypted
+	# segment. Corresponds to LC_ENCRYPTION_INFO.
 	class EncryptionInfoCommand < LoadCommand
-		attr_reader :cryptoff, :cryptsize, :cryptid
+		# @return [Fixnum] the offset to the encrypted segment
+		attr_reader :cryptoff
+
+		# @return [Fixnum] the size of the encrypted segment
+		attr_reader :cryptsize
+
+		# @return [Fixnum] the encryption system, or 0 if not encrypted yet
+		attr_reader :cryptid
 
 		@format = "VVVVV"
 		@sizeof = 20
 
+		# @private
 		def initialize(offset, cmd, cmdsize, cryptoff, cryptsize, cryptid)
 			super(offset, cmd, cmdsize)
 			@cryptoff = cryptoff
@@ -513,12 +767,25 @@ module MachO
 		end
 	end
 
+	# A load command representing the offset to and size of an encrypted
+	# segment. Corresponds to LC_ENCRYPTION_INFO_64.
 	class EncryptionInfoCommand64 < LoadCommand
-		attr_reader :cryptoff, :cryptsize, :cryptid, :pad
+		# @return [Fixnum] the offset to the encrypted segment
+		attr_reader :cryptoff
+
+		# @return [Fixnum] the size of the encrypted segment
+		attr_reader :cryptsize
+
+		# @return [Fixnum] the encryption system, or 0 if not encrypted yet
+		attr_reader :cryptid
+
+		# @return [Fixnum] 64-bit padding value
+		attr_reader :pad
 
 		@format = "VVVVVV"
 		@sizeof = 24
 
+		# @private
 		def initialize(offset, cmd, cmdsize, cryptoff, cryptsize, cryptid)
 			super(offset, cmd, cmdsize)
 			@cryptoff = cryptoff
@@ -528,12 +795,19 @@ module MachO
 		end
 	end
 
+	# A load command containing the minimum OS version on which the binary
+	# was built to run. Corresponds to LC_VERSION_MIN_MACOSX and LC_VERSION_MIN_IPHONEOS.
 	class VersionMinCommand < LoadCommand
-		attr_reader :version, :sdk
+		# @return [Fixnum] the version X.Y.Z packed as x16.y8.z8
+		attr_reader :version
+
+		# @return [Fixnum] the SDK version X.Y.Z packed as x16.y8.z8
+		attr_reader :sdk
 
 		@format = "VVVV"
 		@sizeof = 16
 
+		# @private
 		def initialize(offset, cmd, cmdsize, version, sdk)
 			super(offset, cmd, cmdsize)
 			@version = version
@@ -541,6 +815,9 @@ module MachO
 		end
 	end
 
+	# A load command containing the file offsets and sizes of the new
+	# compressed form of the information dyld needs to load the image.
+	# Corresponds to LC_DYLD_INFO and LC_DYLD_INFO_ONLY.
 	class DyldInfoCommand < LoadCommand
 		attr_reader :rebase_off, :rebase_size, :bind_off, :bind_size
 		attr_reader :weak_bind_off, :weak_bind_size, :lazy_bind_off
@@ -549,6 +826,7 @@ module MachO
 		@format = "VVVVVVVVVVVV"
 		@sizeof = 48
 
+		# @private
 		def initialize(offset, cmd, cmdsize, rebase_off, rebase_size, bind_off,
 				bind_size, weak_bind_off, weak_bind_size, lazy_bind_off,
 				lazy_bind_size, export_off, export_size)
@@ -566,24 +844,34 @@ module MachO
 		end
 	end
 
+	# A load command containing linker options embedded in object files.
+	# Corresponds to LC_LINKER_OPTION.
 	class LinkerOptionCommand < LoadCommand
+		# @return [Fixnum] the number of strings
 		attr_reader :count
 
 		@format = "VVV"
 		@sizeof = 12
 
+		# @private
 		def initialize(offset, cmd, cmdsize, count)
 			super(offset, cmd, cmdsize)
 			@count = count
 		end
 	end
 
+	# A load command specifying the offset of main(). Corresponds to LC_MAIN.
 	class EntryPointCommand < LoadCommand
-		attr_reader :entryoff, :stacksize
+		# @return [Fixnum] the file (__TEXT) offset of main()
+		attr_reader :entryoff
+
+		# @return [Fixnum] if not 0, the initial stack size.
+		attr_reader :stacksize
 
 		@format = "VVQQ"
 		@sizeof = 24
 
+		# @private
 		def initialize(offset, cmd, cmdsize, entryoff, stacksize)
 			super(offset, cmd, cmdsize)
 			@entryoff = entryoff
@@ -591,12 +879,16 @@ module MachO
 		end
 	end
 
+	# A load command specifying the version of the sources used to build the
+	# binary. Corresponds to LC_SOURCE_VERSION.
 	class SourceVersionCommand < LoadCommand
+		# @return [Fixnum] the version packed as a24.b10.c10.d10.e10
 		attr_reader :version
 
 		@format = "VVQ"
 		@sizeof = 16
 
+		# @private
 		def initialize(offset, cmd, cmdsize, version)
 			super(offset, cmd, cmdsize)
 			@version = version