aix-errlog 0.0.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aef41605d9a740c337e3b81e0a368a7b96dcdfd5e73dc3764673da0faa2a81ab
-  data.tar.gz: 06ad2a5c388cb8e98d95e007a867d374575daa51333982c11e244d9c81fc5f43
+  metadata.gz: a6e98415b5db1bba3a83301429dbc6fb7d8e5f860a35c75225596c3f3493f9df
+  data.tar.gz: 77e593f0c156f3dd12209eed4806d7d87e0cf15710ef42dbb3eb96f0804dc043
 SHA512:
-  metadata.gz: edd6fa23e192513af9eeb0e1349708e25fcb6f1e64ba39142def2bdcf91ccf25a1d4907a070770e4b0cc2d374d71f9a47aec1f3eb849346fe47c57ad7ea17b49
-  data.tar.gz: 4b5f8bf6c6c36dc5c17cccd611a86aeb69ae4cb6e66f261627f46a24034b0dd11a4230e44aa3aa625f3d55c04d101ca626d170d13e3086ad417520c3123d41d4
+  metadata.gz: 7f20031f90faa552c4f99795b9fd2395b9658cd3b2aa3a02590b10bc68d3615ffab59fc21aeb84fb9ae46512f4644539a899ea97a79067325a065082845ecdc3
+  data.tar.gz: 6d8753b599485fdc819c80e646d5b318794ed49ce89ad5112af38efa804fcb8982344f7b8891a84f6df8befc34a511c66e00e98799596c094a2732729fb2094a

data/lib/aix/errlog.rb

@@ -0,0 +1 @@
+require 'aix/errlog/errlog'

data/lib/aix/errlog/constants.rb

@@ -0,0 +1,93 @@
+module AIX
+  module Errlog
+    module Constants
+      ERR_REC_MAX = 4096
+      O_RDONLY = 0x00
+      O_WRONLY = 0x01
+      O_RDWR = 0x02
+      O_ACCMODE = 0x03
+      O_NONBLOCK = 0x04
+      O_APPEND = 0x08
+      O_CREAT = 0x100
+      O_TRUNC = 0x200
+      O_EXCL = 0x400
+      O_NOCTTY = 0x800
+      O_DIRECTORY = 0x80000
+
+      LE_MAGIC540 = 0x0C4DF540
+      LE_MAGIC = LE_MAGIC540
+
+      LE_LABEL_MAX = 20
+      LE_MACHINE_ID_MAX = 32
+      LE_NODE_ID_MAX = 32
+      LE_CLASS_MAX = 2
+      LE_TYPE_MAX = 5
+      LE_RESOURCE_MAX = 16
+      LE_RCLASS_MAX = 16
+      LE_RTYPE_MAX = 16
+      LE_VPD_MAX = 512
+      LE_IN_MAX = 256
+      LE_CONN_MAX = 20
+      LE_DETAIL_MAX = ERR_REC_MAX
+      LE_SYMPTOM_MAX = 312
+      LE_ERRDUP_MAX = 16
+      LE_WPAR_ID_MAX = 28
+
+      LE_FLAG_ERR64 = 0x01
+      LE_FLAG_ERRDUP = 0x100
+      LE_FLAG_ERRWPAR = 0x200
+
+      LE_OP_EQUAL = 0x01
+      LE_OP_NE = 0x02
+      LE_OP_SUBSTR = 0x03
+      LE_OP_LT = 0x04
+      LE_OP_LE = 0x05
+      LE_OP_GT = 0x06
+      LE_OP_GE = 0x07
+      LE_OP_LEAF = 0x100
+      LE_OP_NOT = 0x101
+      LE_OP_AND = 0x201
+      LE_OP_OR = 0x202
+      LE_OP_XOR = 0x203
+
+      LE_TYPE = 0xff00
+      LE_TYPE_INT = 0x0100
+      LE_TYPE_STRING = 0x0200
+      LE_TYPE_BOOLEAN = 0x0300
+
+      LE_MATCH_FIELD = 0xff
+      LE_MATCH_SEQUENCE = (0x01|LE_TYPE_INT)
+      LE_MATCH_LABEL = (0x02|LE_TYPE_STRING)
+      LE_MATCH_TIMESTAMP = (0x03|LE_TYPE_INT)
+      LE_MATCH_CRCID = (0x04|LE_TYPE_INT)
+      LE_MATCH_MACHINEID = (0x05|LE_TYPE_STRING)
+      LE_MATCH_NODEID = (0x06|LE_TYPE_STRING)
+      LE_MATCH_CLASS = (0x07|LE_TYPE_STRING)
+      LE_MATCH_TYPE = (0x08|LE_TYPE_STRING)
+      LE_MATCH_RESOURCE = (0x09|LE_TYPE_STRING)
+      LE_MATCH_RCLASS = (0x0a|LE_TYPE_STRING)
+      LE_MATCH_RTYPE = (0x0b|LE_TYPE_STRING)
+      LE_MATCH_VPD_IBM = (0x0c|LE_TYPE_STRING)
+      LE_MATCH_VPD_USER = (0x0d|LE_TYPE_STRING)
+      LE_MATCH_IN = (0x0e|LE_TYPE_STRING)
+      LE_MATCH_CONNWHERE = (0x0f|LE_TYPE_STRING)
+      LE_MATCH_FLAG_ERR64 = (0x10|LE_TYPE_BOOLEAN)
+      LE_MATCH_FLAG_ERRDUP = (0x11|LE_TYPE_BOOLEAN)
+      LE_MATCH_DETAIL_DATA = (0x12|LE_TYPE_STRING)
+      LE_MATCH_SYMPTOM_DATA = (0x13|LE_TYPE_STRING)
+      LE_MATCH_ERRDIAG = (0x14|LE_TYPE_INT)
+      LE_MATCH_WPARID = (0x15|LE_TYPE_STRING)
+
+      LE_FORWARD = 0x01
+      LE_REVERSE = 0x02
+
+      LE_ERR_INVARG = 0x01
+      LE_ERR_NOFILE = 0x02
+      LE_ERR_INVFILE = 0x03
+      LE_ERR_NOMEM = 0x04
+      LE_ERR_NOWRITE = 0x05
+      LE_ERR_IO = 0x06
+      LE_ERR_DONE = 0x07
+    end
+  end
+end

data/lib/aix/errlog/entry.rb

@@ -0,0 +1,46 @@
+require 'ffi'
+
+require 'aix/errlog/constants'
+
+module AIX
+  module Errlog
+    ##
+    # An errlog entry class.  Used to parse the raw errlog_entry_t struct into a
+    # more useful Ruby object.
+    # 
+    # You shouldn't need to invoke this class directly; it is generated by the
+    # Errlog#forward_each and Errlog#reverse_each.
+    class Entry
+      attr_reader :magic, :sequence, :label, :timestamp, :crcid, :errdiag, :machineid, :nodeid, :class, :type, :resource, :rclass, :rtype, :vpd_ibm, :vpd_user, :in, :connwhere, :flags, :detail, :symptom, :dup_count, :dup_time1, :dup_time2, :wparid
+
+      def initialize(raw)
+        @magic = raw[:el_magic]
+        @sequence = raw[:el_sequence]
+        @label = raw[:el_label].to_s.freeze
+        @timestamp = Time.at(raw[:el_timestamp]).freeze
+        @crcid = raw[:el_crcid]
+        @errdiag = raw[:el_errdiag]
+        @machineid = raw[:el_machineid].to_s.freeze
+        @nodeid = raw[:el_nodeid].to_s.freeze
+        @class = raw[:el_class].to_s.freeze
+        @type = raw[:el_type].to_s.freeze
+        @resource = raw[:el_resource].to_s.freeze
+        @rclass = raw[:el_rclass].to_s.freeze
+        @rtype = raw[:el_rtype].to_s.freeze
+        @vpd_ibm = raw[:el_vpd_ibm].to_s.freeze
+        @vpd_user = raw[:el_vpd_user].to_s.freeze
+        @in = raw[:el_in].to_s
+        @connwhere = raw[:el_connwhere].to_s.freeze
+        @flags = raw[:el_flags]
+        length = raw[:el_detail_length]
+        @detail = raw[:el_detail_data].to_ptr.get_bytes(0, length).freeze
+        length = raw[:el_symptom_length]
+        @symptom = raw[:el_symptom_data].to_ptr.get_bytes(0, length).freeze
+        @dup_count = raw[:el_errdup][:ed_dupcount]
+        @dup_time1 = Time.at(raw[:el_errdup][:ed_time1]).freeze
+        @dup_time2 = Time.at(raw[:el_errdup][:ed_time2]).freeze
+        @wparid = raw[:el_wparid].to_s.freeze
+      end
+    end
+  end
+end

data/lib/aix/errlog/errlog.rb

@@ -0,0 +1,436 @@
+require 'aix/errlog/constants'
+require 'aix/errlog/lib'
+require 'aix/errlog/entry'
+require 'aix/errlog/errors'
+require 'aix/errlog/match'
+
+module AIX
+  module Errlog
+    ##
+    # Simple convenince shortcut to access AIX::Errlog::Errlog.open
+    def self.open(*args, &block)
+      ::AIX::Errlog::Errlog.open(*args, &block)
+    end
+
+    ##
+    # The core errlog class.  Used to open an errlog file.
+    #
+    # The main method that should be used here is ::open (more likely
+    # AIX::Errlog.open for convenience), and the block form is strongly
+    # recommended wherever possible.  If you do not use the block form, make
+    # sure you call #close when you are done with it (enforce it with an ensure
+    # block if possible).  The garbage collector will not do this automatically,
+    # and you can leak.
+    #
+    # #forward_each and #reverse_each should do everything you need to do.  If
+    # you use the enumerator form, or even the block form of these, make sure
+    # you consume the entire enumerator before opening a new one.  If you need
+    # to enumerate the errlog in a nested loop or something like that, you'll
+    # need multuple instances of this open, otherwise it will fail (the handle
+    # operates as a cursor, so if you try to re-invoke one before it is
+    # finished, the cursor will get reset, and you'll get jumbled results).
+    # While one of these enumerators as active, trying to re-invoke one will
+    # raise an EnumeratorError.
+    #
+    # If you need to do complex matching, use the #match_* methods in here to
+    # create Match objects to work with.  You can see Match for more details as
+    # to how to create those.
+    #
+    # A simple example, showing how to get a list of all labels of all log
+    # entries in forward order which contain the string 'KILL' in their label
+    # and happen in the month of January 2017, and which have a sequence ID
+    # above 1000, or that happen in December 2016 and have a sequence ID below
+    # 500, might look something like this:
+    #
+    #   require 'date'
+    #
+    #   require 'aix/errlog'
+    #
+    #   AIX::Errlog.open do |log|
+    #     log.forward_each(match: (
+    #       log.match_label.include?('KILL') & (
+    #         (
+    #           (log.match_sequence > 1000) &
+    #           (log.match_timestamp >= DateTime.new(2017, 1, 1)) &
+    #           (log.match_timestamp < DateTime.new(2017, 2, 1))
+    #         ) | (
+    #           (log.match_sequence < 500) &
+    #           (log.match_timestamp >= DateTime.new(2016, 12, 1)) &
+    #           (log.match_timestamp < DateTime.new(2017, 1, 1))
+    #         )
+    #       )
+    #     )).map(&:label)
+    #   end
+    #
+    # Certainly, that looks a little complex, but it is a bit more efficient
+    # than iterating all log entries as a whole and then filtering after the
+    # fact, and it's a lot more pleasant than building the Match tree from
+    # scratch in C.
+    class Errlog
+      ##
+      # path is the string path to the file.
+      # mode matches as closely as possible to the semantics of the fopen mode.
+      def initialize(path='/var/adm/ras/errlog'.freeze, mode='r'.freeze)
+        mode_r = mode.include? 'r'
+        mode_w = mode.include? 'w'
+        mode_a = mode.include? 'a'
+        mode_x = mode.include? 'x'
+        mode_p = mode.include? '+'
+
+        mode_flags =
+          if mode_p
+            Constants::O_RDRW
+          elsif mode_r
+            Constants::O_RDONLY
+          else
+            Constants::O_WRONLY
+          end
+        mode_flags |= Constants::O_CREAT unless mode_r
+        mode_flags |= Constants::O_TRUNC if mode_w
+        mode_flags |= Constants::O_APPEND if mode_a
+        mode_flags |= Constants::O_EXCL if mode_x
+
+        handle_p = FFI::MemoryPointer.new(:pointer)
+
+        status = Lib.errlog_open(
+          path,
+          mode_flags,
+          Constants::LE_MAGIC,
+          handle_p,
+        )
+
+        Errors.throw(status, "path: #{path}, mode: #{mode}") unless status == :ok
+
+        @enum_active = false
+
+        # Just hold the handle directly
+        @handle = handle_p.get_pointer
+      end
+
+      ##
+      # Opens the given error log.  Arguments are passed directly into ::new
+      #
+      # If a block is given, #close will be automatically called when the block
+      # exits, and the return value of the block will be the return value of
+      # this.
+      def self.open(*args)
+        errlog = new(*args)
+        if block_given?
+          begin
+            return yield errlog
+          ensure
+            errlog.close
+          end
+        else
+          log
+        end
+      end
+
+      ##
+      # Closes the handle.  This must be called, either directly or indirectly
+      # through ::open with a block.  This may be called multiple times, but
+      # after this is called, no other functions that try to use the errlog
+      # handle may be called.
+      def close
+        unless @handle.nil?
+          status = Lib.errlog_close(@handle)
+          Errors.throw(status, "handle: #{@handle}") unless status == :ok
+          @handle = nil
+        end
+      end
+
+      ##
+      # Enumerate log Entry objects in forward order (default is reverse).  If
+      # no block is given, returns an enumerator.
+      #
+      # sequence specifies the sequence ID to start with.  It will be included
+      # in the results if specifed
+      #
+      # match takes a Match object, which specifies which entries to match.
+      #
+      # match and sequence must not be both specified.  If neither are
+      # specified, this simply iterates from the beginning (or from the previous
+      # stopped position, if #find_sequence or #find_first have already been
+      # called).
+      #
+      # An active enumerator can not be nested within another active enumerator,
+      # including the block form of this.  If you invoke any of the #each_
+      # methods while another has not finished and exited, you'll raise an
+      # EnumeratorError.  You can create an enumerator of one within the other,
+      # as long as you don't activate it until the first one has exited.
+      #
+      # Warning: if the sequence does not exist (which is common when error logs
+      # are cleaned), no entries will be returned, even if they follow the
+      # sequence ID.  If you want all entries based on their sequence number,
+      # use match instead.  You're usually better off using the timestamp
+      # instead of sequence number, because the sequence number is 32 bits and
+      # might wrap.
+      def forward_each(match: nil, sequence: nil, &block)
+        raise 'match and sequence must not be both specified' if match && sequence
+
+        return to_enum(:forward_each, match: match, sequence: sequence) unless block_given?
+        set_direction :forward
+        each(match: match, sequence: sequence, &block)
+      end
+
+      ##
+      # Enumerate log Entry objects in reverse order (default is reverse).  If
+      # no block is given, returns an enumerator.
+      #
+      # sequence specifies the sequence ID to start with.  It will be included
+      # in the results if specifed
+      #
+      # match takes a Match object, which specifies which entries to match.
+      #
+      # match and sequence must not be both specified.  If neither are
+      # specified, this simply iterates from the beginning (or from the previous
+      # stopped position, if #find_sequence or #find_first have already been
+      # called).
+      #
+      # An active enumerator can not be nested within another active enumerator,
+      # including the block form of this.  If you invoke any of the #each_
+      # methods while another has not finished and exited, you'll raise an
+      # EnumeratorError.  You can create an enumerator of one within the other,
+      # as long as you don't activate it until the first one has exited.
+      #
+      # Warning: if the sequence does not exist (which is common when error logs
+      # are cleaned), no entries will be returned, even if they follow the
+      # sequence ID.  If you want all entries based on their sequence number,
+      # use match instead.  You're usually better off using the timestamp
+      # instead of sequence number, because the sequence number is 32 bits and
+      # might wrap.
+      def reverse_each(match: nil, sequence: nil, &block)
+        raise 'match and sequence must not be both specified' if match && sequence
+
+        return to_enum(:reverse_each, match: match, sequence: sequence) unless block_given?
+        set_direction :reverse
+        each(match: match, sequence: sequence, &block)
+      end
+
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # sequence.
+      def match_sequence
+        Match.new(left: :sequence)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # label.
+      def match_label
+        Match.new(left: :label)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # timestamp.
+      def match_timestamp
+        Match.new(left: :timestamp)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # crcid.
+      def match_crcid
+        Match.new(left: :crcid)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # machineid.
+      def match_machineid
+        Match.new(left: :machineid)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # nodeid.
+      def match_nodeid
+        Match.new(left: :nodeid)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # class.
+      def match_class
+        Match.new(left: :class)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # type.
+      def match_type
+        Match.new(left: :type)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # resource.
+      def match_resource
+        Match.new(left: :resource)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # rclass.
+      def match_rclass
+        Match.new(left: :rclass)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # rtype.
+      def match_rtype
+        Match.new(left: :rtype)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # vpd_ibm.
+      def match_vpd_ibm
+        Match.new(left: :vpd_ibm)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # vpd_user.
+      def match_vpd_user
+        Match.new(left: :vpd_user)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against in.
+      def match_in
+        Match.new(left: :in)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # connwhere.
+      def match_connwhere
+        Match.new(left: :connwhere)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # flag_err64.
+      def match_flag_err64
+        Match.new(left: :flag_err64)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # flag_errdup.
+      def match_flag_errdup
+        Match.new(left: :flag_errdup)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # detail_data.
+      def match_detail_data
+        Match.new(left: :detail_data)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # symptom_data.
+      def match_symptom_data
+        Match.new(left: :symptom_data)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # errdiag.
+      def match_errdiag
+        Match.new(left: :errdiag)
+      end
+      ##
+      # Match convenience function.  Gets a Leaf match for comparing against
+      # wparid.
+      def match_wparid
+        Match.new(left: :wparid)
+      end
+
+      private
+
+      ##
+      # Get an entry for the specified sequence, if there is any, and nil
+      # otherwise.
+      def find_sequence(id)
+        entry = Lib::ErrlogEntry.new
+        status = Lib.errlog_find_sequence(@handle, id, entry)
+        return if status == :done
+        Errors.throw(status, "handle: #{@handle}, sequence: #{id}") unless status == :ok
+
+        Entry.new(entry).freeze
+      end
+
+      ##
+      # Get an entry matching the passed-in Match, if there is any, and nil
+      # otherwise.
+      def find_first(match)
+        entry = Lib::ErrlogEntry.new
+        status = Lib.errlog_find_first(@handle, match.to_struct, entry)
+        return if status == :done
+        Errors.throw(status, "handle: #{@handle}, match: #{match}") unless status == :ok
+
+        Entry.new(entry).freeze
+      end
+
+      ##
+      # Get the next entry.
+      def find_next
+        entry = Lib::ErrlogEntry.new
+        status = Lib.errlog_find_next(@handle, entry)
+        return if status == :done
+        Errors.throw(status, "handle: #{@handle}") unless status == :ok
+        Entry.new(entry).freeze
+      end
+
+      ##
+      # Sets the search direction for iteration.
+      def set_direction(direction)
+        status = Lib.errlog_set_direction(@handle, direction)
+        Errors.throw(status, "handle: #{@handle}, direction: #{direction}") unless status == :ok
+      end
+
+      ##
+      # Enumerate log entries in the order set in #set_direction (default is
+      # reverse).
+      #
+      # sequence specifies the sequence ID to start with.  It will be included
+      # in the results if specifed
+      #
+      # match takes a Match object, which specifies which entries to match.
+      #
+      # match and sequence must not be both specified.  If neither are
+      # specified, this simply iterates from the beginning (or from the previous
+      # stopped position, if #find_sequence or #find_first have already been
+      # called).
+      #
+      # An active enumerator can not be nested within another active enumerator,
+      # including the block form of this.  If you invoke any of the #each_
+      # methods while another has not finished and exited, you'll raise an
+      # EnumeratorError.  You can create an enumerator of one within the other,
+      # as long as you don't activate it until the first one has exited.
+      #
+      # Warning: if the sequence does not exist (which is common when error logs
+      # are cleaned), no entries will be returned, even if they follow the
+      # sequence ID.  If you want all entries based on their sequence number,
+      # use match instead.  You're usually better off using the timestamp
+      # instead of sequence number, because the sequence number is 32 bits and
+      # might wrap.
+      #
+      # The user-facing entry points to this are #forward_each and #reverse_each
+      def each(match: nil, sequence: nil)
+        # Does not return an enumerator, because this will always be called with
+        # an active block
+
+        begin
+          raise Errors::EnumeratorError if @enum_active
+          @enum_active = true
+
+          if sequence
+            entry = find_sequence(sequence)
+            return if entry.nil?
+            yield entry
+          end
+
+          if match
+            entry = find_first(match)
+            return if entry.nil?
+            yield entry
+          end
+
+          while entry = find_next
+            yield entry
+          end
+        ensure
+          @enum_active = false
+        end
+      end
+    end
+  end
+end

data/lib/aix/errlog/errors.rb

@@ -0,0 +1,54 @@
+module AIX
+  module Errlog
+    module Errors
+      class EnumeratorError < StandardError
+        def initialize
+          super 'Do not nest enumerators, or invoke another one while the first is still active.'
+        end
+      end
+      class ErrlogError < StandardError
+      end
+      class InvalidArgument < ErrlogError
+        def initialize(message)
+          super "A parameter error was detected.  Detail: #{message}"
+        end
+      end
+      class NoFile < ErrlogError
+        def initialize(message)
+          super "The log file does not exist.  Detail: #{message}"
+        end
+      end
+      class NoMem < ErrlogError
+        def initialize(message)
+          super "Memory could not be allocated.  Detail: #{message}"
+        end
+      end
+      class IO < ErrlogError
+        def initialize(message)
+          super "An i/o error occurred.  Detail: #{message}"
+        end
+      end
+      class InvalidFile < ErrlogError
+        def initialize(message)
+          super "The file is not a valid error log.  Detail: #{message}"
+        end
+      end
+      class UnknownError < ErrlogError
+        def initialize(message)
+          super "An error occured that could not be diagnosed.  Detail: #{message}"
+        end
+      end
+      LOOKUP = {
+        invarg: InvalidArgument,
+        nofile: NoFile,
+        nomem: NoMem,
+        io: IO,
+        invfile: InvalidFile,
+      }
+      def self.throw(status, detail)
+        errorClass = LOOKUP[status] || UnknownError
+        raise errorClass, detail
+      end
+    end
+  end
+end

data/lib/aix/errlog/lib.rb

@@ -0,0 +1,167 @@
+require 'ffi'
+
+require 'aix/errlog/constants'
+
+module AIX
+  module Errlog
+    ## 
+    # The ffi interface to the errlog library.
+    #
+    # You should never need to access this directly.  All necessary functionality
+    # should be accessible via Errlog.
+    module Lib
+      extend FFI::Library
+      ffi_lib 'liberrlog.a(shr_64.o)'
+
+      typedef :pointer, :errlog_handle_t
+      typedef :pointer, :errlog_handle_t_ptr
+
+      Err = enum(
+        :ok, 0,
+        :invarg, Constants::LE_ERR_INVARG,
+        :nofile, Constants::LE_ERR_NOFILE,
+        :invfile, Constants::LE_ERR_INVFILE,
+        :nomem, Constants::LE_ERR_NOMEM,
+        :nowrite, Constants::LE_ERR_NOWRITE,
+        :io, Constants::LE_ERR_IO,
+        :done, Constants::LE_ERR_DONE,
+      )
+
+      Direction = enum(
+        :forward, Constants::LE_FORWARD,
+        :reverse, Constants::LE_REVERSE,
+      )
+
+      Operator = enum(
+        :equal, Constants::LE_OP_EQUAL,
+        :ne, Constants::LE_OP_NE,
+        :substr, Constants::LE_OP_SUBSTR,
+        :lt, Constants::LE_OP_LT,
+        :le, Constants::LE_OP_LE,
+        :gt, Constants::LE_OP_GT,
+        :ge, Constants::LE_OP_GE,
+        :not, Constants::LE_OP_NOT,
+        :and, Constants::LE_OP_AND,
+        :or, Constants::LE_OP_OR,
+        :xor, Constants::LE_OP_XOR,
+      )
+
+      Match = enum(
+        :sequence, Constants::LE_MATCH_SEQUENCE,
+        :label, Constants::LE_MATCH_LABEL,
+        :timestamp, Constants::LE_MATCH_TIMESTAMP,
+        :crcid, Constants::LE_MATCH_CRCID,
+        :machineid, Constants::LE_MATCH_MACHINEID,
+        :nodeid, Constants::LE_MATCH_NODEID,
+        :class, Constants::LE_MATCH_CLASS,
+        :type, Constants::LE_MATCH_TYPE,
+        :resource, Constants::LE_MATCH_RESOURCE,
+        :rclass, Constants::LE_MATCH_RCLASS,
+        :rtype, Constants::LE_MATCH_RTYPE,
+        :vpd_ibm, Constants::LE_MATCH_VPD_IBM,
+        :vpd_user, Constants::LE_MATCH_VPD_USER,
+        :in, Constants::LE_MATCH_IN,
+        :connwhere, Constants::LE_MATCH_CONNWHERE,
+        :flag_err64, Constants::LE_MATCH_FLAG_ERR64,
+        :flag_errdup, Constants::LE_MATCH_FLAG_ERRDUP,
+        :detail_data, Constants::LE_MATCH_DETAIL_DATA,
+        :symptom_data, Constants::LE_MATCH_SYMPTOM_DATA,
+        :errdiag, Constants::LE_MATCH_ERRDIAG,
+        :wparid, Constants::LE_MATCH_WPARID,
+      )
+
+      class Errdup < FFI::Struct
+        layout(
+          :ed_dupcount, :uint,
+          :ed_time1, :uint32,
+          :ed_time2, :uint32,
+        )
+      end
+
+      class ErrlogEntry < FFI::Struct
+        layout(
+          :el_magic, :uint,
+          :el_sequence, :uint,
+          :el_label, [:char, Constants::LE_LABEL_MAX],
+          :el_timestamp, :uint,
+          :el_crcid, :uint,
+          :el_errdiag, :uint,
+          :el_machineid, [:char, Constants::LE_MACHINE_ID_MAX],
+          :el_nodeid, [:char, Constants::LE_NODE_ID_MAX],
+          :el_class, [:char, Constants::LE_CLASS_MAX],
+          :el_type, [:char, Constants::LE_TYPE_MAX],
+          :el_resource, [:char, Constants::LE_RESOURCE_MAX],
+          :el_rclass, [:char, Constants::LE_RCLASS_MAX],
+          :el_rtype, [:char, Constants::LE_RTYPE_MAX],
+          :el_vpd_ibm, [:char, Constants::LE_VPD_MAX],
+          :el_vpd_user, [:char, Constants::LE_VPD_MAX],
+          :el_in, [:char, Constants::LE_IN_MAX],
+          :el_connwhere, [:char, Constants::LE_CONN_MAX],
+          :el_flags, :ushort,
+          :el_detail_length, :ushort,
+          :el_detail_data, [:char, Constants::LE_DETAIL_MAX],
+          :el_symptom_length, :uint,
+          :el_symptom_data, [:char, Constants::LE_SYMPTOM_MAX],
+          :el_errdup, Errdup,
+          :el_wparid, [:char, Constants::LE_WPAR_ID_MAX],
+        )
+      end
+
+      class ErrlogMatch1U < FFI::Union
+        layout(
+          :emu_left, :pointer,
+          :emu_field, Match,
+        )
+      end
+
+      class ErrlogMatch2U < FFI::Union
+        layout(
+          :emu_right, :pointer,
+          :emu_intvalue, :uint,
+          :emu_strvalue, :string,
+        )
+      end
+
+      class ErrlogMatch < FFI::Struct
+        layout(
+          :em_op, Operator,
+          :emu1, ErrlogMatch1U,
+          :emu2, ErrlogMatch2U,
+        )
+      end
+
+      attach_function :errlog_open, [
+        :string, # path
+        :int, # mode
+        :uint, # magic
+        :errlog_handle_t_ptr, # handle
+      ], Err
+
+      attach_function :errlog_close, [
+        :errlog_handle_t, # handle
+      ], Err
+
+      attach_function :errlog_find_first, [
+        :errlog_handle_t, # handle
+        ErrlogMatch, # filter
+        ErrlogEntry, # result
+      ], Err
+
+      attach_function :errlog_find_next, [
+        :errlog_handle_t, # handle
+        ErrlogEntry, # result
+      ], Err
+
+      attach_function :errlog_find_sequence, [
+        :errlog_handle_t, # handle
+        :int, # sequence
+        ErrlogEntry, # result
+      ], Err
+
+      attach_function :errlog_set_direction, [
+        :errlog_handle_t, # handle
+        Direction, # direction
+      ], Err
+    end
+  end
+end

data/lib/aix/errlog/match.rb

@@ -0,0 +1,156 @@
+require 'date'
+
+require 'aix/errlog/constants'
+require 'aix/errlog/lib'
+
+module AIX
+  module Errlog
+    ##
+    # A class that is useful for building errlog matchers.
+    #
+    # You usually won't need to access this class directly; you'll be able to
+    # create instances of it indirectly through the field accessors that are
+    # available in Errlog.
+    #
+    # You can build field matchers using the methods on the errlog and standard
+    # logical operators, and there are standard conversions for certain things
+    # like Time and DateTime operations.  For instance, if you wanted errlog
+    # entries only in January 2018 with +FOO+ in the label somewhere, you cold
+    # use a match like this with an Errlog instance.
+    #
+    #   (
+    #     (errlog.match_timestamp >= DateTime.new(2018, 1, 1)) &
+    #     (errlog.match_timestamp < DateTime.new(2018, 2, 1)) &
+    #     errlog.match_label.include?('FOO')
+    #   )
+    #
+    # It really is that easy.  The rest of the magic is done for you behind the
+    # scenes, as long as you follow the rules and know how to make these matches
+    # in the C equivalent.  Note that there must always be a Match on the left
+    # side of all comparisons, so something like 
+    #
+    #   DateTime.new(2018, 1, 1) <= errlog.match_timestamp
+    #
+    # is not possible.
+    # 
+    # This class should allow you to build matches for errlog_find_first in a
+    # simple and natural way.  Note that & is the +LE_OP_AND+ operator, and | is
+    # the +LE_OP_OR+ operator, not &&, +and+, ||, or +or+, because those can't
+    # be overridden.
+    class Match
+      attr_accessor :left, :operator, :right
+
+      def initialize(left:, operator: nil, right: nil)
+        @left = left
+        @operator = operator
+        @right = right
+      end
+
+      # Uses the structure of this object to build a errlog_match_t structure.
+      # Does not check whether operators only work on leaves or any other
+      # specifics as that (for instance, an and operator needs two Match leaves,
+      # and won't work between a field and a Match or anything like that).  The
+      # function itself might check some of the operators to make sure that
+      # they're set and throw an error for you, but something like a segfault is
+      # more likely if you screw up the structure.  Make sure you know what
+      # you're doing.
+      def to_struct
+        raise "operator must be a symbol, but is #{@operator}" unless @operator.is_a? Symbol
+
+        # We want to be sure the struct is not garbage collected before it's
+        # used, so we need to retain a reference to it that ensures that it will
+        # live as long as this object
+        @struct = Lib::ErrlogMatch.new
+
+        @struct[:em_op] = @operator
+
+        case @left
+        when Match
+          @struct[:emu1][:emu_left] = @left.to_struct
+        when Symbol
+          @struct[:emu1][:emu_field] = @left
+        else
+          raise "left should be either a Match or Symbol object, but is #{@left}"
+        end
+
+        case @right
+        when Match
+          @struct[:emu2][:emu_right] = @right.to_struct
+        when String
+          @struct[:emu2][:emu_strvalue] = @right
+        when Numeric, Time
+          @struct[:emu2][:emu_intvalue] = @right.to_i
+        when DateTime
+          @struct[:emu2][:emu_intvalue] = @right.to_time.to_i
+        else
+          raise "left should be either a Match or Symbol object, but is #{@left}"
+        end
+
+        @struct
+      end
+
+      def ==(other)
+        @operator = :equal
+        @right = other
+        self
+      end
+      def !=(other)
+        @operator = :ne
+        @right = other
+        self
+      end
+      def include?(other)
+        @operator = :substr
+        @right = other
+        self
+      end
+      def <(other)
+        @operator = :lt
+        @right = other
+        self
+      end
+      def <=(other)
+        @operator = :le
+        @right = other
+        self
+      end
+      def >(other)
+        @operator = :gt
+        @right = other
+        self
+      end
+      def >=(other)
+        @operator = :ge
+        @right = other
+        self
+      end
+      def &(other)
+        Match.new(
+          left: self,
+          operator: :and,
+          right: other,
+        )
+      end
+      def |(other)
+        Match.new(
+          left: self,
+          operator: :or,
+          right: other,
+        )
+      end
+      def ^(other)
+        Match.new(
+          left: self,
+          operator: :xor,
+          right: other,
+        )
+      end
+      def !
+        Match.new(
+          left: self,
+          operator: :not,
+        )
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: aix-errlog
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 1.0.0
 platform: ruby
 authors:
 - Taylor C. Richberger
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-05-22 00:00:00.000000000 Z
+date: 2018-05-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -32,7 +32,11 @@ extra_rdoc_files: []
 files:
 - lib/aix/errlog.rb
 - lib/aix/errlog/constants.rb
-- lib/aix/errlog/ffi.rb
+- lib/aix/errlog/entry.rb
+- lib/aix/errlog/errlog.rb
+- lib/aix/errlog/errors.rb
+- lib/aix/errlog/lib.rb
+- lib/aix/errlog/match.rb
 homepage: https://github.com/absperf/aix-errlog
 licenses:
 - MIT