elftools 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b2aa2517a78c13a631e9889e03e380b024c75585
-  data.tar.gz: 6d1de34194028eba0b787b148b648a518e6f0e1d
+  metadata.gz: 3b27e4fd08cf348de961dde3f2c606719558c031
+  data.tar.gz: b7822186925f38be8a76aeb9961a0484ee0cc2bd
 SHA512:
-  metadata.gz: 4e3b9b1c4f4e0c7cf38efd85ae0c5c250e875fb50bda990286fcf0dc69684970b6eae99f6b2881a0938ea5597da6439ae46fa694823dc3e69322e202b60f622b
-  data.tar.gz: fff51965be7467711d36af1db1374370654a7d8a771ca8f4dcc48e38fd3daff3fe928dc2dd034f3d7ded3ecadb4e8304bdc8feb996623fc052c6eeea03251742
+  metadata.gz: 9a0d0993f509e82c87c97776282057fe61ff8076018714da50ecc9c928e8b3863e7481a2ababf7ae56cb02d75dc03d5783f8d2bdf4b890b535075bed00f53bac
+  data.tar.gz: 591568c22193ada4c48874c276bde8cdb5c5587268f67e440c48b8968db395d9730888bd5d452e6f002e383e65e0a0dfb9bc7b6682b6e960bc84daa80f1cab15

data/README.md

@@ -1,4 +1,5 @@
 [![Build Status](https://travis-ci.org/david942j/rbelftools.svg?branch=master)](https://travis-ci.org/david942j/rbelftools)
+[![Build Status](https://ci.appveyor.com/api/projects/status/sq5c4gli8ir95h6k?svg=true&retina=true)](https://ci.appveyor.com/project/david942j/rbelftools)
 [![Code Climate](https://codeclimate.com/github/david942j/rbelftools/badges/gpa.svg)](https://codeclimate.com/github/david942j/rbelftools)
 [![Issue Count](https://codeclimate.com/github/david942j/rbelftools/badges/issue_count.svg)](https://codeclimate.com/github/david942j/rbelftools)
 [![Test Coverage](https://codeclimate.com/github/david942j/rbelftools/badges/coverage.svg)](https://codeclimate.com/github/david942j/rbelftools/coverage)
@@ -11,7 +12,7 @@ ELF parser in pure ruby implementation. This work is inspired by [pyelftools](ht
 
 The motivation to create this repository is want to be a dependency of [pwntools-ruby](https://github.com/peter50216/pwntools-ruby). Since ELF parser is a big work, it should not be implemented directly in pwntools.
 
-**rbelftools**'s target is to create a nice ELF parser library in ruby. More features are work in progress.
+**rbelftools**'s target is to create a nice ELF parser library in ruby. More features remain a work in progress.
 
 # Install
 
@@ -70,7 +71,7 @@ symtab_section.num_symbols
 
 symtab_section.symbol_by_name('puts@@GLIBC_2.2.5')
 #=>
-# #<ELFTools::Symbol:0x00560b14af67a0
+# #<ELFTools::Sections::Symbol:0x00560b14af67a0
 #  @header={:st_name=>348, :st_info=>18, :st_other=>0, :st_shndx=>0, :st_value=>0, :st_size=>0},
 #  @name="puts@@GLIBC_2.2.5">
 
@@ -115,26 +116,21 @@ relocations.map { |r| symtab.symbol_at(r.symbol_index).name }
 
 # Why rbelftools
 
-1. Fully documented
-
+1. Fully documented   
    Always important for an Open-Source project. Online document is [here](http://www.rubydoc.info/github/david942j/rbelftools/master/frames)
-2. Fully tested
-
+2. Fully tested   
    Of course.
-3. Lazy loading on everything
-
+3. Lazy loading on everything   
    To use **rbelftools**, only need to pass the stream object of ELF file.
    **rbelftools** will read the stream object **as least times as possible** when parsing
    the file. Most information will not be fetched until you need it, which makes
    **rbelftools** efficient.
-4. To be a library
-
-   **rbelftools** is designed to be a library for furthur usage.
+4. To be a library   
+   **rbelftools** is designed to be a library for further usage.
    It will _not_ add any too trivial features.
    For example, to check if NX disabled, you can use
    `!elf.segment_by_type(:gnu_stack).executable?` but not `elf.nx?`
-5. Section and segment parser
-
+5. Section and segment parser   
    Providing common sections and segments parser. For example, .symtab, .shstrtab
    .dynamic sections and INTERP, DYNAMIC segments, etc.
 
@@ -143,12 +139,12 @@ relocations.map { |r| symtab.symbol_at(r.symbol_index).name }
 git clone https://github.com/david942j/rbelftools.git
 cd rbelftools
 bundle
-rake
+bundle exec rake
 ```
 Any comments or suggestions are welcome!
 
 # Cross Platform
-**rbelftools** can be used on Linux and OSX. Should also work on Windows but not tested.
+**rbelftools** can be used and has been fully tested on all platforms include Linux, OSX, and Windows!
 
 # License
 MIT License

data/lib/elftools/constants.rb

@@ -8,110 +8,117 @@ module ELFTools
 
     # Section header types, records in +sh_type+.
     module SHT
-      SHT_NULL     = 0
-      SHT_PROGBITS = 1
-      SHT_SYMTAB   = 2
-      SHT_STRTAB   = 3
-      SHT_RELA     = 4
-      SHT_HASH     = 5
-      SHT_DYNAMIC  = 6
-      SHT_NOTE     = 7
-      SHT_NOBITS   = 8
-      SHT_REL      = 9
-      SHT_SHLIB    = 10
-      SHT_DYNSYM   = 11
-      SHT_NUM      = 12
+      SHT_NULL     = 0 # null section
+      SHT_PROGBITS = 1 # information defined by program itself
+      SHT_SYMTAB   = 2 # symbol table section
+      SHT_STRTAB   = 3 # string table section
+      SHT_RELA     = 4 # relocation with addends
+      SHT_HASH     = 5 # symbol hash table
+      SHT_DYNAMIC  = 6 # information of dynamic linking
+      SHT_NOTE     = 7 # note section
+      SHT_NOBITS   = 8 # section occupies no space
+      SHT_REL      = 9 # relocation
+      SHT_SHLIB    = 10 # reserved
+      SHT_DYNSYM   = 11 # symbols for dynamic
+      # Values between {SHT_LOPROC} and {SHT_HIPROC} are reserved for processor-specific semantics.
       SHT_LOPROC   = 0x70000000
-      SHT_HIPROC   = 0x7fffffff
+      SHT_HIPROC   = 0x7fffffff # see {SHT_LOPROC}
+      # Values between {SHT_LOUSER} and {SHT_HIUSER} are reserved for application programs.
       SHT_LOUSER   = 0x80000000
-      SHT_HIUSER   = 0xffffffff
+      SHT_HIUSER   = 0xffffffff # see {SHT_LOUSER}
     end
     include SHT
 
     # Program header types, records in +p_type+.
     module PT
-      PT_NULL         = 0
-      PT_LOAD         = 1
-      PT_DYNAMIC      = 2
-      PT_INTERP       = 3
-      PT_NOTE         = 4
-      PT_SHLIB        = 5
-      PT_PHDR         = 6
-      PT_TLS          = 7          # Thread local storage segment
+      PT_NULL         = 0          # null segment
+      PT_LOAD         = 1          # segment to be load
+      PT_DYNAMIC      = 2          # dynamic tags
+      PT_INTERP       = 3          # interpreter, same as .interp section
+      PT_NOTE         = 4          # same as .note* section
+      PT_SHLIB        = 5          # reserved
+      PT_PHDR         = 6          # where program header starts
+      PT_TLS          = 7          # thread local storage segment
       PT_LOOS         = 0x60000000 # OS-specific
       PT_HIOS         = 0x6fffffff # OS-specific
+      # Values between {PT_LOPROC} and {PT_HIPROC} are reserved for processor-specific semantics.
       PT_LOPROC       = 0x70000000
-      PT_HIPROC       = 0x7fffffff
-      PT_GNU_EH_FRAME = 0x6474e550
-      PT_GNU_STACK    = 0x6474e551
-      PT_GNU_RELRO    = 0x6474e552 # Read only after relocation
+      PT_HIPROC       = 0x7fffffff # see {PT_LOPROC}
+      PT_GNU_EH_FRAME = 0x6474e550 # for exception handler
+      PT_GNU_STACK    = 0x6474e551 # permission of stack
+      PT_GNU_RELRO    = 0x6474e552 # read only after relocation
     end
     include PT
 
     # Dynamic table types, records in +d_tag+.
     module DT
-      DT_NULL         = 0
-      DT_NEEDED       = 1
-      DT_PLTRELSZ     = 2
-      DT_PLTGOT       = 3
-      DT_HASH         = 4
-      DT_STRTAB       = 5
-      DT_SYMTAB       = 6
-      DT_RELA         = 7
-      DT_RELASZ       = 8
-      DT_RELAENT      = 9
-      DT_STRSZ        = 10
-      DT_SYMENT       = 11
-      DT_INIT         = 12
-      DT_FINI         = 13
-      DT_SONAME       = 14
-      DT_RPATH        = 15
-      DT_SYMBOLIC     = 16
-      DT_REL          = 17
-      DT_RELSZ        = 18
-      DT_RELENT       = 19
-      DT_PLTREL       = 20
-      DT_DEBUG        = 21
-      DT_TEXTREL      = 22
-      DT_JMPREL       = 23
-      DT_BIND_NOW     = 24
-      DT_INIT_ARRAY   = 25
-      DT_FINI_ARRAY   = 26
-      DT_INIT_ARRAYSZ = 27
-      DT_FINI_ARRAYSZ = 28
-      DT_RUNPATH      = 29
-      DT_FLAGS        = 30
-      DT_ENCODING     = 32
+      DT_NULL         = 0 # marks the end of the _DYNAMIC array
+      DT_NEEDED       = 1 # libraries need to be linked by loader
+      DT_PLTRELSZ     = 2 # total size of relocation entries
+      DT_PLTGOT       = 3 # address of procedure linkage table or global offset table
+      DT_HASH         = 4 # address of symbol hash table
+      DT_STRTAB       = 5 # address of string table
+      DT_SYMTAB       = 6 # address of symbol table
+      DT_RELA         = 7 # address of a relocation table
+      DT_RELASZ       = 8 # total size of the {DT_RELA} table
+      DT_RELAENT      = 9 # size of each entry in the {DT_RELA} table
+      DT_STRSZ        = 10 # total size of {DT_STRTAB}
+      DT_SYMENT       = 11 # size of each entry in {DT_SYMTAB}
+      DT_INIT         = 12 # where the initialization function is
+      DT_FINI         = 13 # where the termination function is
+      DT_SONAME       = 14 # the shared object name
+      DT_RPATH        = 15 # has been superseded by {DT_RUNPATH}
+      DT_SYMBOLIC     = 16 # has been superseded by the DF_SYMBOLIC flag
+      DT_REL          = 17 # similar to {DT_RELA}
+      DT_RELSZ        = 18 # total size of the {DT_REL} table
+      DT_RELENT       = 19 # size of each entry in the {DT_REL} table
+      DT_PLTREL       = 20 # type of relocation entry, either {DT_REL} or {DT_RELA}
+      DT_DEBUG        = 21 # for debugging
+      DT_TEXTREL      = 22 # has been superseded by the DF_TEXTREL flag
+      DT_JMPREL       = 23 # address of relocation entries that are associated solely with the procedure linkage table
+      DT_BIND_NOW     = 24 # if the loader needs to do relocate now, superseded by the DF_BIND_NOW flag
+      DT_INIT_ARRAY   = 25 # address init array
+      DT_FINI_ARRAY   = 26 # address of fini array
+      DT_INIT_ARRAYSZ = 27 # total size of init array
+      DT_FINI_ARRAYSZ = 28 # total size of fini array
+      DT_RUNPATH      = 29 # path of libraries for searching
+      DT_FLAGS        = 30 # flags
+      DT_ENCODING     = 32 # just a lower bound
+      # Values between {DT_LOOS} and {DT_HIOS} are reserved for operating system-specific semantics.
       DT_LOOS         = 0x6000000d
-      DT_HIOS         = 0x6ffff000
+      DT_HIOS         = 0x6ffff000 # see {DT_LOOS}
+      # Values between {DT_VALRNGLO} and {DT_VALRNGHI} use the +d_un.d_val+ field of the dynamic structure.
       DT_VALRNGLO     = 0x6ffffd00
-      DT_VALRNGHI     = 0x6ffffdff
+      DT_VALRNGHI     = 0x6ffffdff # see {DT_VALRNGLO}
+      # Values between {DT_ADDRRNGLO} and {DT_ADDRRNGHI} use the +d_un.d_ptr+ field of the dynamic structure.
       DT_ADDRRNGLO    = 0x6ffffe00
-      DT_ADDRRNGHI    = 0x6ffffeff
-      DT_VERSYM       = 0x6ffffff0
-      DT_RELACOUNT    = 0x6ffffff9
-      DT_RELCOUNT     = 0x6ffffffa
-      DT_FLAGS_1      = 0x6ffffffb
-      DT_VERDEF       = 0x6ffffffc
-      DT_VERDEFNUM    = 0x6ffffffd
-      DT_VERNEED      = 0x6ffffffe
-      DT_VERNEEDNUM   = 0x6fffffff
+      DT_GNU_HASH     = 0x6ffffef5 # the gnu hash
+      DT_ADDRRNGHI    = 0x6ffffeff # see {DT_ADDRRNGLO}
+      DT_RELACOUNT    = 0x6ffffff9 # relative relocation count
+      DT_RELCOUNT     = 0x6ffffffa # relative relocation count
+      DT_FLAGS_1      = 0x6ffffffb # flags
+      DT_VERDEF       = 0x6ffffffc # address of version definition table
+      DT_VERDEFNUM    = 0x6ffffffd # number of entries in {DT_VERDEF}
+      DT_VERNEED      = 0x6ffffffe # address of version dependency table
+      DT_VERNEEDNUM   = 0x6fffffff # number of entries in {DT_VERNEED}
+      # Values between {DT_LOPROC} and {DT_HIPROC} are reserved for processor-specific semantics.
       DT_LOPROC       = 0x70000000
-      DT_HIPROC       = 0x7fffffff
+      DT_HIPROC       = 0x7fffffff # see {DT_LOPROC}
     end
     include DT
 
     # These constants define the various ELF target machines.
     module EM
-      EM_NONE           = 0
-      EM_M32            = 1
-      EM_SPARC          = 2
-      EM_386            = 3
-      EM_68K            = 4
-      EM_88K            = 5
-      EM_486            = 6      # Perhaps disused
-      EM_860            = 7
+      EM_NONE           = 0      # none
+      EM_M32            = 1      # AT&T WE 32100
+      EM_SPARC          = 2      # SPARC
+      EM_386            = 3      # Intel 80386
+      EM_68K            = 4      # Motorola 68000
+      EM_88K            = 5      # Motorola 88000
+      EM_486            = 6      # Intel 80486
+      EM_860            = 7      # Intel 80860
       EM_MIPS           = 8      # MIPS R3000 (officially, big-endian only)
+
       # Next two are historical and binaries and
       # modules of these types will be rejected by Linux.
       EM_MIPS_RS3_LE    = 10     # MIPS R3000 little-endian
@@ -190,11 +197,11 @@ module ELFTools
 
     # This module defines elf file types.
     module ET
-      ET_NONE = 0
-      ET_REL  = 1
-      ET_EXEC = 2
-      ET_DYN  = 3
-      ET_CORE = 4
+      ET_NONE = 0 # no file type
+      ET_REL  = 1 # relocatable file
+      ET_EXEC = 2 # executable file
+      ET_DYN  = 3 # shared object
+      ET_CORE = 4 # core file
       # Return the type name according to +e_type+ in ELF file header.
       # @return [String] Type in string format.
       def self.mapping(type)

data/lib/elftools/dynamic.rb

@@ -1,28 +1,26 @@
 module ELFTools
-  # Define common methods for dynamic sections and
-  # dynamic segments.
+  # Define common methods for dynamic sections and dynamic segments.
   #
-  # Notice: this module can only be included by
-  # {ELFTools::Sections::DynamicSection} and
-  # {ELFTools::Segments::DynamicSegment} because
-  # methods here assume some attributes exist.
+  # @note
+  #   This module can only be included by {ELFTools::Sections::DynamicSection}
+  #   and {ELFTools::Segments::DynamicSegment} because methods here assume some
+  #   attributes exist.
   module Dynamic
     # Iterate all tags.
     #
-    # Notice: this method assume the following methods
-    # already exist:
-    #   header
-    #   tag_start
-    # @param [Block] block You can give a block.
+    # @note
+    #   This method assume the following methods already exist:
+    #     header
+    #     tag_start
+    # @yieldparam [ELFTools::Dynamic::Tag] tag
     # @return [Enumerator<ELFTools::Dynamic::Tag>, Array<ELFTools::Dynamic::Tag>]
     #   If block is not given, an enumerator will be returned.
     #   Otherwise, return array of tags.
-    def each_tags
+    def each_tags(&block)
       return enum_for(:each_tags) unless block_given?
       arr = []
       0.step do |i|
-        tag = tag_at(i)
-        yield tag
+        tag = tag_at(i).tap(&block)
         arr << tag
         break if tag.header.d_tag == ELFTools::Constants::DT_NULL
       end
@@ -68,13 +66,13 @@ module ELFTools
     # Get the +n+-th tag.
     #
     # Tags are lazy loaded.
-    # Notice: this method assume the following methods
-    # already exist:
-    #   header
-    #   tag_start
-    #
-    # Notice: we cannot do bound checking of +n+ here since
-    # the only way to get size of tags is calling +tags.size+.
+    # @note
+    #   This method assume the following methods already exist:
+    #     header
+    #     tag_start
+    # @note
+    #   We cannot do bound checking of +n+ here since the only way to get size
+    #   of tags is calling +tags.size+.
     # @param [Integer] n The index.
     # @return [ELFTools::Dynamic::Tag] The desired tag.
     def tag_at(n)
@@ -102,11 +100,11 @@ module ELFTools
     # A tag class.
     class Tag
       attr_reader :header # @return [ELFTools::Structs::ELF_Dyn] The dynamic tag header.
-      attr_reader :stream # @return [File] Streaming object.
+      attr_reader :stream # @return [#pos=, #read] Streaming object.
 
       # Instantiate a {ELFTools::Dynamic::Tag} object.
       # @param [ELF_Dyn] header The dynamic tag header.
-      # @param [File] stream Streaming object.
+      # @param [#pos=, #read] stream Streaming object.
       # @param [Method] str_offset
       #   Call this method to get the string offset related
       #   to file.
@@ -116,6 +114,7 @@ module ELFTools
         @str_offset = str_offset
       end
 
+      # Some dynamic have name.
       TYPE_WITH_NAME = [Constants::DT_NEEDED,
                         Constants::DT_SONAME,
                         Constants::DT_RPATH,
@@ -150,7 +149,7 @@ module ELFTools
       #
       # Only tags with name would return a name.
       # Others would return +nil+.
-      # @return [String, NilClass] The name.
+      # @return [String, nil] The name.
       def name
         return nil unless name?
         Util.cstring(stream, @str_offset.call + header.d_val.to_i)

data/lib/elftools/elf_file.rb

@@ -8,13 +8,13 @@ require 'elftools/structs'
 module ELFTools
   # The main class for using elftools.
   class ELFFile
-    attr_reader :stream # @return [File] The +File+ object.
+    attr_reader :stream # @return [#pos=, #read] The +File+ object.
     attr_reader :elf_class # @return [Integer] 32 or 64.
     attr_reader :endian # @return [Symbol] +:little+ or +:big+.
 
     # Instantiate an {ELFFile} object.
     #
-    # @param [File] stream
+    # @param [#pos=, #read] stream
     #   The +File+ object to be fetch information from.
     # @example
     #   ELFFile.new(File.open('/bin/cat'))
@@ -27,7 +27,7 @@ module ELFTools
     # Return the file header.
     #
     # Lazy loading.
-    # @retrn [ELFTools::Structs::ELF_Ehdr] The header.
+    # @return [ELFTools::Structs::ELF_Ehdr] The header.
     def header
       return @header if defined?(@header)
       stream.pos = 0
@@ -37,7 +37,7 @@ module ELFTools
     end
 
     # Return the BuildID of ELF.
-    # @return [String, NilClass]
+    # @return [String, nil]
     #   BuildID in hex form will be returned.
     #   +nil+ is returned if the .note.gnu.build-id section
     #   is not found.
@@ -52,7 +52,7 @@ module ELFTools
       note.desc.unpack('H*').first
     end
 
-    # Get Machine architecture.
+    # Get machine architecture.
     #
     # Mappings of architecture can be found
     # in {ELFTools::Constants::EM.mapping}.
@@ -89,7 +89,7 @@ module ELFTools
 
     # Acquire the section named as +name+.
     # @param [String] name The desired section name.
-    # @return [ELFTools::Sections::Section, NilClass] The target section.
+    # @return [ELFTools::Sections::Section, nil] The target section.
     # @example
     #   elf.section_by_name('.note.gnu.build-id')
     #   #=> #<ELFTools::Sections::Section:0x005647b1282428>
@@ -107,17 +107,15 @@ module ELFTools
     # only be created whenever accessing it.
     # This method is useful for {#section_by_name}
     # since not all sections need to be created.
-    # @param [Block] block
-    #   Just like +Array#each+, you can give a block.
+    # @yieldparam [ELFTools::Sections::Section] section A section.
+    # @yieldreturn [void]
     # @return [Enumerator<ELFTools::Sections::Section>, Array<ELFTools::Sections::Section>]
     #   As +Array#each+, if block is not given, a enumerator will be returned,
     #   otherwise, the whole sections will be returned.
-    def each_sections
+    def each_sections(&block)
       return enum_for(:each_sections) unless block_given?
       Array.new(num_sections) do |i|
-        sec = section_at(i)
-        yield sec
-        sec
+        section_at(i).tap(&block)
       end
     end
 
@@ -132,7 +130,7 @@ module ELFTools
     #
     # Sections are lazy loaded.
     # @param [Integer] n The index.
-    # @return [ELFTools::Sections::Section, NilClass]
+    # @return [ELFTools::Sections::Section, nil]
     #   The target section.
     #   If +n+ is out of bound, +nil+ is returned.
     def section_at(n)
@@ -142,13 +140,12 @@ module ELFTools
 
     # Fetch all sections with specific type.
     #
-    # The available types are listed in {ELFTools::Constants},
-    # start with +SHT_+.
+    # The available types are listed in {ELFTools::Constants::PT}.
     # This method accept giving block.
     # @param [Integer, Symbol, String] type
     #   The type needed, similar format as {#segment_by_type}.
-    # @param [Block] block
-    #   Block will be yielded whenever find a section.
+    # @yieldparam [ELFTools::Sections::Section] section A section in specific type.
+    # @yieldreturn [void]
     # @return [Array<ELFTools::Sections::section>] The target sections.
     # @example
     #   elf = ELFTools::ELFFile.new(File.open('spec/files/amd64.elf'))
@@ -183,16 +180,14 @@ module ELFTools
     # only be created whenever accessing it.
     # This method is useful for {#segment_by_type}
     # since not all segments need to be created.
-    # @param [Block] block
-    #   Just like +Array#each+, you can give a block.
+    # @yieldparam [ELFTools::Segments::Segment] segment A segment.
+    # @yieldreturn [void]
     # @return [Array<ELFTools::Segments::Segment>]
     #   Whole segments will be returned.
-    def each_segments
+    def each_segments(&block)
       return enum_for(:each_segments) unless block_given?
       Array.new(num_segments) do |i|
-        seg = segment_at(i)
-        yield seg
-        seg
+        segment_at(i).tap(&block)
       end
     end
 
@@ -204,11 +199,11 @@ module ELFTools
     end
 
     # Get the first segment with +p_type=type+.
-    # The available types are listed in {ELFTools::Constants},
-    # start with +PT_+.
+    # The available types are listed in {ELFTools::Constants::PT}.
     #
-    # Notice: this method will return the first segment found,
-    # to found all segments with specific type you can use {#segments_by_type}.
+    # @note
+    #   This method will return the first segment found,
+    #   to found all segments with specific type you can use {#segments_by_type}.
     # @param [Integer, Symbol, String] type
     #   See examples for clear usage.
     # @return [ELFTools::Segments::Segment] The target segment.
@@ -256,8 +251,8 @@ module ELFTools
     # This method accept giving block.
     # @param [Integer, Symbol, String] type
     #   The type needed, same format as {#segment_by_type}.
-    # @param [Block] block
-    #   Block will be yielded whenever find a segement.
+    # @yieldparam [ELFTools::Segments::Segment] segment A segment in specific type.
+    # @yieldreturn [void]
     # @return [Array<ELFTools::Segments::Segment>] The target segments.
     def segments_by_type(type, &block)
       type = Util.to_constant(Constants::PT, type)
@@ -268,7 +263,7 @@ module ELFTools
     #
     # Segments are lazy loaded.
     # @param [Integer] n The index.
-    # @return [ELFTools::Segments::Segment, NilClass]
+    # @return [ELFTools::Segments::Segment, nil]
     #   The target segment.
     #   If +n+ is out of bound, +nil+ is returned.
     def segment_at(n)

data/lib/elftools/exceptions.rb

@@ -1,3 +1,4 @@
 module ELFTools
+  # Being raised when parsing error.
   class ELFError < StandardError; end
 end

data/lib/elftools/lazy_array.rb

@@ -7,9 +7,10 @@ module ELFTools
     # Instantiate a {LazyArray} object.
     # @param [Integer] size
     #   The size of array.
-    # @param [Block] block
-    #   At first time accessing +i+-th element,
-    #   block will be called as +block.call(i)+.
+    # @yieldparam [Integer] i
+    #   Needs +i+-th element.
+    # @yieldreturn [Object]
+    #   Value of the +i+-th element.
     # @example
     #   arr = LazyArray.new(10) { |i| p i; i * i }
     #   p arr[2]

data/lib/elftools/note.rb

@@ -2,17 +2,18 @@ require 'elftools/structs'
 require 'elftools/util'
 
 module ELFTools
-  # Since both note sections and note segments
-  # refer to notes, this module defines common
-  # methods for {ELFTools::Sections::NoteSection} and {ELFTools::Segments::NoteSegment}.
+  # Since both note sections and note segments refer to notes, this module
+  # defines common methods for {ELFTools::Sections::NoteSection} and
+  # {ELFTools::Segments::NoteSegment}.
   #
-  # Notice: this module can only be included in {ELFTools::Sections::NoteSection} and
-  # {ELFTools::Segments::NoteSegment} since some methods assume some attributes already
-  # exist.
+  # @note
+  #   This module can only be included in {ELFTools::Sections::NoteSection} and
+  #   {ELFTools::Segments::NoteSegment} since some methods here assume some
+  #   attributes already exist.
   module Note
-    # Since size of {ELFTools::Structs::ELF_Nhdr} will not change no
-    # matter what endian and what arch, we can do this here.
-    # This value should equal to 12.
+    # Since size of {ELFTools::Structs::ELF_Nhdr} will not change no matter in
+    # what endian and what arch, we can do this here. This value should equal
+    # to 12.
     SIZE_OF_NHDR = Structs::ELF_Nhdr.new(endian: :little).num_bytes
 
     # Iterate all notes in a note section or segment.
@@ -30,13 +31,16 @@ module ELFTools
     #   |      ...      |
     #   +---------------+
     #
-    # Notice: This method assume following methods exist:
-    #   stream
-    #   note_start
-    #   note_total_size
-    # @return [Array<ELFTools::Note::Note>]
-    #   The array of notes will be returned.
+    # @note
+    #   This method assume following methods exist:
+    #     stream
+    #     note_start
+    #     note_total_size
+    # @return [Enumerator<ELFTools::Note::Note>, Array<ELFTools::Note::Note>]
+    #   If block is not given, an enumerator will be returned.
+    #   Otherwise, return the array of notes.
     def each_notes
+      return enum_for(:each_notes) unless block_given?
       @notes_offset_map ||= {}
       cur = note_start
       notes = []
@@ -49,19 +53,23 @@ module ELFTools
         desc_size = Util.align(note.header.n_descsz, 2)
         cur += SIZE_OF_NHDR + name_size + desc_size
         notes << note
-        yield note if block_given?
+        yield note
       end
       notes
     end
 
     # Simply +#notes+ to get all notes.
-    alias notes each_notes
+    # @return [Array<ELFTools::Note::Note>]
+    #   Whole notes.
+    def notes
+      each_notes.to_a
+    end
 
     private
 
     # Get the endian.
     #
-    # Notice: This method assume method +header+ exists.
+    # @note This method assume method +header+ exists.
     # @return [Symbol] +:little+ or +:big+.
     def endian
       header.class.self_endian
@@ -75,12 +83,12 @@ module ELFTools
     # Class of a note.
     class Note
       attr_reader :header # @return [ELFTools::Structs::ELF_Nhdr] Note header.
-      attr_reader :stream # @return [File] Streaming object.
+      attr_reader :stream # @return [#pos=, #read] Streaming object.
       attr_reader :offset # @return [Integer] Address of this note start, includes note header.
 
       # Instantiate a {ELFTools::Note::Note} object.
       # @param [ELF_Nhdr] header The note header.
-      # @param [File] stream Streaming object.
+      # @param [#pos=, #read] stream Streaming object.
       # @param [Integer] offset
       #   Start address of this note, includes the header.
       def initialize(header, stream, offset)

data/lib/elftools/sections/relocation_section.rb

@@ -23,7 +23,7 @@ module ELFTools
       #
       # relocations are lazy loaded.
       # @param [Integer] n The index.
-      # @return [ELFTools::Relocation, NilClass]
+      # @return [ELFTools::Relocation, nil]
       #   The target relocation.
       #   If +n+ is out of bound, +nil+ is returned.
       def relocation_at(n)
@@ -35,17 +35,15 @@ module ELFTools
       #
       # All relocations are lazy loading, the relocation
       # only be created whenever accessing it.
-      # @param [Block] block
-      #   Just like +Array#each+, you can give a block.
+      # @yieldparam [ELFTools::Relocation] rel A relocation object.
+      # @yieldreturn [void]
       # @return [Enumerator<ELFTools::Relocation>, Array<ELFTools::Relocation>]
       #   If block is not given, an enumerator will be returned.
       #   Otherwise, the whole relocations will be returned.
-      def each_relocations
+      def each_relocations(&block)
         return enum_for(:each_relocations) unless block_given?
         Array.new(num_relocations) do |i|
-          rel = relocation_at(i)
-          yield rel
-          rel
+          relocation_at(i).tap(&block)
         end
       end
 
@@ -75,7 +73,7 @@ module ELFTools
   # XXX: move this to an independent file?
   class Relocation
     attr_reader :header # @return [ELFTools::Structs::ELF_Rel, ELFTools::Structs::ELF_Rela] Rel(a) header.
-    attr_reader :stream # @return [File] Streaming object.
+    attr_reader :stream # @return [#pos=, #read] Streaming object.
 
     # Instantiate a {Relocation} object.
     def initialize(header, stream)

data/lib/elftools/sections/section.rb

@@ -4,12 +4,12 @@ module ELFTools
     # Base class of sections.
     class Section
       attr_reader :header # @return [ELFTools::Structs::ELF_Shdr] Section header.
-      attr_reader :stream # @return [File] Streaming object.
+      attr_reader :stream # @return [#pos=, #read] Streaming object.
 
       # Instantiate a {Section} object.
       # @param [ELFTools::Structs::ELF_Shdr] header
       #   The section header object.
-      # @param [File] stream
+      # @param [#pos=, #read] stream
       #   The streaming object for further dump.
       # @param [ELFTools::Sections::StrTabSection, Proc] strtab
       #   The string table object. For fetching section names.

data/lib/elftools/sections/sections.rb

@@ -16,7 +16,7 @@ module ELFTools
     class << Section
       # Use different class according to +header.sh_type+.
       # @param [ELFTools::Structs::ELF_Shdr] header Section header.
-      # @param [File] stream Streaming object.
+      # @param [#pos=, #read] stream Streaming object.
       # @return [ELFTools::Sections::Section]
       #   Return object dependes on +header.sh_type+.
       def create(header, stream, *args)

data/lib/elftools/sections/sym_tab_section.rb

@@ -11,15 +11,14 @@ module ELFTools
       # to easily fetch other sections.
       # @param [ELFTools::Structs::ELF_Shdr] header
       #   See {Section#initialize} for more information.
-      # @param [File] stream
+      # @param [#pos=, #read] stream
       #   See {Section#initialize} for more information.
       # @param [Proc] section_at
       #   The method for fetching other sections by index.
       #   This lambda should be {ELFTools::ELFFile#section_at}.
-      def initialize(header, stream, section_at: nil, **_kwagrs)
+      def initialize(header, stream, section_at: nil, **_kwargs)
         @section_at = section_at
         # For faster #symbol_by_name
-        @symbol_name_map = {}
         super
       end
 
@@ -36,7 +35,7 @@ module ELFTools
       #
       # Symbols are lazy loaded.
       # @param [Integer] n The index.
-      # @return [ELFTools::Symbol, NilClass]
+      # @return [ELFTools::Sections::Symbol, nil]
       #   The target symbol.
       #   If +n+ is out of bound, +nil+ is returned.
       def symbol_at(n)
@@ -50,30 +49,31 @@ module ELFTools
       # only be created whenever accessing it.
       # This method is useful for {#symbol_by_name}
       # since not all symbols need to be created.
-      # @param [Block] block
-      #   Just like +Array#each+, you can give a block.
-      # @return [Array<ELFTools::symbol>]
-      #   The whole symbols will be returned.
-      def each_symbols
+      # @yieldparam [ELFTools::Sections::Symbol] sym A symbol object.
+      # @yieldreturn [void]
+      # @return [Enumerator<ELFTools::Sections::Symbol>, Array<ELFTools::Sections::Symbol>]
+      #   If block is not given, an enumerator will be returned.
+      #   Otherwise return array of symbols.
+      def each_symbols(&block)
+        return enum_for(:each_symbols) unless block_given?
         Array.new(num_symbols) do |i|
-          sym = symbol_at(i)
-          block_given? ? yield(sym) : sym
+          symbol_at(i).tap(&block)
         end
       end
 
-      alias symbols each_symbols
+      # Simply use {#symbols} to get all symbols.
+      # @return [Array<ELFTools::Sections::Symbol>]
+      #   The whole symbols.
+      def symbols
+        each_symbols.to_a
+      end
 
-      # Get symbol by it's name.
+      # Get symbol by its name.
       # @param [String] name
       #   The name of symbol.
-      # @return [ELFTools::Symbol] Desired symbol.
+      # @return [ELFTools::Sections::Symbol] Desired symbol.
       def symbol_by_name(name)
-        return @symbol_name_map[name] if @symbol_name_map[name]
-        each_symbols do |symbol|
-          @symbol_name_map[symbol.name] = symbol
-          return symbol if symbol.name == name
-        end
-        nil
+        each_symbols.find { |symbol| symbol.name == name }
       end
 
       # Return the symbol string section.
@@ -98,12 +98,12 @@ module ELFTools
     # XXX: Should this class be defined in an independent file?
     class Symbol
       attr_reader :header # @return [ELFTools::Structs::ELF32_sym, ELFTools::Structs::ELF64_sym] Section header.
-      attr_reader :stream # @return [File] Streaming object.
+      attr_reader :stream # @return [#pos=, #read] Streaming object.
 
-      # Instantiate a {ELFTools::Symbol} object.
+      # Instantiate a {ELFTools::Sections::Symbol} object.
       # @param [ELFTools::Structs::ELF32_sym, ELFTools::Structs::ELF64_sym] header
       #   The symbol header.
-      # @param [File] stream The streaming object.
+      # @param [#pos=, #read] stream The streaming object.
       # @param [ELFTools::Sections::StrTabSection, Proc] symstr
       #   The symbol string section.
       #   If +Proc+ is given, it will be called at the first time

data/lib/elftools/segments/segment.rb

@@ -3,12 +3,12 @@ module ELFTools
     # Base class of segments.
     class Segment
       attr_reader :header # @return [ELFTools::Structs::ELF32_Phdr, ELFTools::Structs::ELF64_Phdr] Program header.
-      attr_reader :stream # @return [File] Streaming object.
+      attr_reader :stream # @return [#pos=, #read] Streaming object.
 
       # Instantiate a {Segment} object.
       # @param [ELFTools::Structs::ELF32_Phdr, ELFTools::Structs::ELF64_Phdr] header
       #   Program header.
-      # @param [File] stream
+      # @param [#pos=, #read] stream
       #   Streaming object.
       # @param [Method] offset_from_vma
       #   The method to get offset of file, given virtual memory address.

data/lib/elftools/segments/segments.rb

@@ -13,7 +13,7 @@ module ELFTools
     class << Segment
       # Use different class according to +header.p_type+.
       # @param [ELFTools::Structs::ELF32_Phdr, ELFTools::Structs::ELF64_Phdr] header Program header of a segment.
-      # @param [File] stream Streaming object.
+      # @param [#pos=, #read] stream Streaming object.
       # @return [ELFTools::Segments::Segment]
       #   Return object dependes on +header.p_type+.
       def create(header, stream, *args)

data/lib/elftools/structs.rb

@@ -8,6 +8,7 @@ module ELFTools
   module Structs
     # The base structure to define common methods.
     class ELFStruct < BinData::Record
+      # DRY. Many fields have different type in different arch.
       CHOICE_SIZE_T = {
         selection: :elf_class, choices: { 32 => :uint32, 64 => :uint64 }
       }.freeze
@@ -15,7 +16,7 @@ module ELFTools
       attr_accessor :elf_class # @return [Integer] 32 or 64.
 
       # Hacking to get endian of current class
-      # @return [Symbol, NilClass] +:little+ or +:big+.
+      # @return [Symbol, nil] +:little+ or +:big+.
       def self.self_endian
         bindata_name[-2..-1] == 'ge' ? :big : :little
       end
@@ -89,6 +90,7 @@ module ELFTools
       uint64 :p_memsz
       uint64 :p_align
     end
+    # Get program header class according to bits.
     ELF_Phdr = {
       32 => ELF32_Phdr,
       64 => ELF64_Phdr
@@ -115,6 +117,7 @@ module ELFTools
       uint64 :st_value # Value of the symbol
       uint64 :st_size  # Associated symbol size
     end
+    # Get symbol header class according to bits.
     ELF_sym = {
       32 => ELF32_sym,
       64 => ELF64_sym

data/lib/elftools/util.rb

@@ -47,7 +47,7 @@ module ELFTools
       end
 
       # Read from stream until reach a null-byte.
-      # @param [File] stream Streaming object
+      # @param [#pos=, #read] stream Streaming object
       # @param [Integer] offset Start from here.
       # @return [String] Result string will never contain null byte.
       # @example
@@ -80,9 +80,9 @@ module ELFTools
       #   The return value will be objects in +enum+ with attribute
       #   +.type+ equals to +type+.
       def select_by_type(enum, type)
-        enum.select do |sec|
-          if sec.type == type
-            yield sec if block_given?
+        enum.select do |obj|
+          if obj.type == type
+            yield obj if block_given?
             true
           end
         end

data/lib/elftools/version.rb

@@ -1,3 +1,4 @@
 module ELFTools
-  VERSION = '0.2.0'.freeze
+  # Current gem version
+  VERSION = '0.2.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elftools
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - david942j
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-17 00:00:00.000000000 Z
+date: 2017-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bindata
@@ -94,6 +94,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.6'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: |2
     A light weight ELF parser. elftools is designed to be a low-level ELF parser.
     Inspired by https://github.com/eliben/pyelftools.