systemd-journal 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 1c86b79ec4112caca8d17887e2b0fdea3096a470
-  data.tar.gz: 52e39912dc156aa0a7a75639b255f027b8c4b816
+  metadata.gz: dfbc842565f8f2b0c02a231336a2398a52d5fd3e
+  data.tar.gz: 55318a3e7b014bbff59acfb837363961ece1817b
 SHA512:
-  metadata.gz: c2a59f402dd49f61cc8586cb743413f317c0e9f1852e7c6199a63aeacafabfce77f76039a58d1ec050f40196f3c79663c11882897586be71f9a1868adb1eb8f1
-  data.tar.gz: fb9c8f267606434664ce7e52a7822a72d4684b8f81646571a161c3bb14920c7a6b86dce08b0f67b7584ae7c541667ff3d48f7b6d744840290f7fbfad222dad1b
+  metadata.gz: 3a0251260147d45da969179dd6053eda8826cf08187e55efd2fa6d83c7994fe75ee82683c4ca9b80770cd3172d21299fe46f960a8bbe975f9e12f2e8fa8cfc62
+  data.tar.gz: 96b8d2c07dae3dca254e36d6b2fefb6c190edd61749ff9a6e941056837fbc8e5c1650727633a900afed77bfd19108ac5d7766d0e14436951721ee494665c23c5

data/README.md

@@ -8,11 +8,11 @@ Ruby bindings for reading from the systemd journal.
 
 Add this line to your application's Gemfile:
 
-    gem 'systemd-journal', git: 'https://github.com/ledbettj/systemd-journal.git'
+    gem 'systemd-journal', '~> 0.1.0'
 
 And then execute:
 
-    $ bundle
+    bundle install
 
 ## Usage
 
@@ -21,7 +21,6 @@ For example, printing all messages:
     require 'systemd/journal'
     
     j = Systemd::Journal.new
-    j.seek(:head)
     
     while j.move_next
       puts j.read_field('MESSAGE')
@@ -32,7 +31,6 @@ Or to print all data in each entry:
     require 'systemd/journal'
     
     j = Systemd::Journal.new
-    j.seek(:head)
     
     while j.move_next
       j.current_entry do |key, value|

data/Rakefile

@@ -7,5 +7,5 @@ end
 
 YARD::Rake::YardocTask.new do |t|
   t.files = ['lib/**/*.rb']
-  t.options = ['--no-private']
+  t.options = ['--no-private', '--markup=markdown']
 end

data/examples/ssh_watcher.rb

@@ -9,12 +9,13 @@ class SSHWatcher
 
   def run
     @journal.add_match('_EXE', '/usr/bin/sshd')
-    # skip all existing entries
+    # skip all existing entries -- sd_journal_seek_tail() is currently broken.
     while @journal.move_next ; end
 
     while true
-      @journal.wait(1_000_000 * 5)
-      process_event(@journal.current_entry) while @journal.move_next
+      if @journal.wait(1_000_000 * 5) != :nop
+        process_event(@journal.current_entry) while @journal.move_next
+      end
     end
     
   end

data/lib/systemd/journal.rb

@@ -4,16 +4,28 @@ require 'systemd/journal/compat'
 require 'systemd/journal_error'
 
 module Systemd
+  # Class to allow interacting with the systemd journal.
+  # To read from the journal, instantiate a new {Systemd::Journal}; to write to
+  # the journal, use
+  # {Systemd::Journal::Compat::ClassMethods#message Journal.message} or
+  # {Systemd::Journal::Compat::ClassMethods#print Journal.print}.
   class Journal
     include Systemd::Journal::Compat
 
     # Returns a new instance of a Journal, opened with the provided options.
     # @param [Hash] opts optional initialization parameters.
-    # @option opts [Integer] :flags a set of bitwise OR-ed `Journal::Flags`
-    #   which control what journal files are opened.  Defaults to 0 (all).
+    # @option opts [Integer] :flags a set of bitwise OR-ed
+    #   {Systemd::Journal::Flags} which control what journal files are opened.
+    #   Defaults to `0`, meaning all journals avaiable to the current user.
     # @option opts [String]  :path if provided, open the journal files living
     #   in the provided directory only.  Any provided flags will be ignored per
     #   since sd_journal_open_directory does not currently accept any flags.
+    # @example Read only system journal entries
+    #   j = Systemd::Journal.new(flags: Systemd::Journal::Flags::SYSTEM_ONLY)
+    # @example Directly open a journal directory
+    #   j = Systemd::Journal.new(
+    #     path: '/var/log/journal/5f5777e46c5f4131bd9b71cbed6b9abf'
+    #   )
     def initialize(opts = {})
       flags = opts[:flags] || 0
       path  = opts[:path]
@@ -32,8 +44,9 @@ module Systemd
     end
 
     # Move the read pointer to the next entry in the journal.
-    # @return [Boolean] True if moving to the next entry was successful.  False
-    #   indicates that we've reached the end of the journal.
+    # @return [Boolean] True if moving to the next entry was successful.
+    # @return [Boolean] False if unable to move to the next entry, indicating
+    #   that the pointer has reached the end of the journal.
     def move_next
       case (rc = Native::sd_journal_next(@ptr))
       when 0 then false # EOF
@@ -43,9 +56,9 @@ module Systemd
     end
 
     # Move the read pointer forward by `amount` entries.
-    # @return the actual number of entries which the pointer was moved by. If
-    #   this number is less than the requested, we've reached the end of the
-    #   journal.
+    # @return [Integer] the actual number of entries by which the read pointer
+    #   moved. If this number is less than the requested amount, the read
+    #   pointer has reached the end of the journal.
     def move_next_skip(amount)
       rc = Native::sd_journal_next_skip(@ptr, amount)
       raise JournalError.new(rc) if rc < 0
@@ -54,7 +67,8 @@ module Systemd
 
     # Move the read pointer to the previous entry in the journal.
     # @return [Boolean] True if moving to the previous entry was successful.
-    #   False indicates that we've reached the start of the journal.
+    # @return [Boolean] False if unable to move to the previous entry,
+    #   indicating that the pointer has reached the beginning of the journal.
     def move_previous
       case (rc = Native::sd_journal_previous(@ptr))
       when 0 then false # EOF
@@ -64,9 +78,9 @@ module Systemd
     end
 
     # Move the read pointer backwards by `amount` entries.
-    # @return the actual number of entries which the pointer was moved by. If
-    #   this number is less than the requested, we've reached the start of the
-    #   journal.
+    # @return [Integer] the actual number of entries by which the read pointer
+    #   was moved.  If this number is less than the requested amount, the read
+    #   pointer has reached the beginning of the journal.
     def move_previous_skip(amount)
       rc = Native::sd_journal_previous_skip(@ptr, amount)
       raise JournalError.new(rc) if rc < 0
@@ -74,15 +88,14 @@ module Systemd
     end
 
     # Seek to a position in the journal.
-    # Note: after seeking, you must call move_next or move_previous before
-    #   you can call read_field or current_entry
+    # Note: after seeking, you must call {#move_next} or {#move_previous}
+    #   before you can call {#read_field} or {#current_entry}.
     #
     # @param [Symbol, Time] whence one of :head, :tail, or a Time instance.
-    #   :head (or :start) will seek to the beginning of the journal.
-    #   :tail (or :end) will seek to the end of the journal.
-    #   when a Time is provided, seek to the journal entry logged closest to
-    #   the provided time.
-    # @return [Boolean] True on success, otherwise an error is raised.
+    #   `:head` (or `:start`) will seek to the beginning of the journal.
+    #   `:tail` (or `:end`) will seek to the end of the journal. When a `Time`
+    #   is provided, seek to the journal entry logged closest to that time.
+    # @return [True]
     def seek(whence)
       rc = case whence
            when :head, :start
@@ -102,10 +115,14 @@ module Systemd
     end
 
     # Read the contents of the provided field from the current journal entry.
-    #   move_next or move_previous must be called at least once after
+    #   {#move_next} or {#move_previous} must be called at least once after
     #   initialization or seeking prior to attempting to read data.
-    # @param [String] field the name of the field to read -- e.g., 'MESSAGE'
+    # @param [String] field the name of the field to read.
     # @return [String] the value of the requested field.
+    # @example Read the `MESSAGE` field from the current entry
+    #   j = Systemd::Journal.new
+    #   j.move_next
+    #   puts j.read_field('MESSAGE')
     def read_field(field)
       len_ptr = FFI::MemoryPointer.new(:size_t, 1)
       out_ptr = FFI::MemoryPointer.new(:pointer, 1)
@@ -120,12 +137,16 @@ module Systemd
 
     # Read the contents of all fields from the current journal entry.
     # If given a block, it will yield each field in the form of
-    # (fieldname, value).
+    # `(fieldname, value)`.
     #
-    # move_next or move_previous must be called at least once after
-    # initialization or seeking prior to calling current_entry
+    # {#move_next} or {#move_previous} must be called at least once after
+    # initialization or seeking prior to calling {#current_entry}
     #
     # @return [Hash] the contents of the current journal entry.
+    # @example Print all items in the current entry
+    #   j = Systemd::Journal.new
+    #   j.move_next
+    #   j.current_entry{ |field, value| puts "#{field}: #{value}" }
     def current_entry
       Native::sd_journal_restart_data(@ptr)
 
@@ -150,18 +171,29 @@ module Systemd
 
     # Block until the journal is changed.
     # @param timeout_usec [Integer] the maximum number of microseconds to wait
-    #   or -1 to wait indefinitely.
+    #   or `-1` to wait indefinitely.
+    # @example Wait for an event for a maximum of 3 seconds
+    #   j = Systemd::Journal.new
+    #   j.seek(:tail)
+    #   if j.wait(3 * 1_000_000) != :nop
+    #     # event occurred
+    #   end
+    # @return [Symbol] :nop if the wait time was reached (no events occured).
+    # @return [Symbol] :append if new entries were appened to the journal.
+    # @return [Symbol] :invalidate if journal files were added/removed/rotated.
     def wait(timeout_usec = -1)
       rc = Native::sd_journal_wait(@ptr, timeout_usec)
-      raise JournalError.new(rc) if rc < 0
+      raise JournalError.new(rc) if rc.is_a?(Fixnum) && rc < 0
+      rc
     end
 
     # Add a filter to journal, such that only entries where the given filter
     # matches are returned.
-    # move_next or move_previous must be invoked after adding a match before
-    # attempting to read from the journal.
+    # {#move_next} or {#move_previous} must be invoked after adding a match
+    # before attempting to read from the journal.
     # @param [String] field the column to filter on, e.g. _PID, _EXE.
     # @param [String] value the match to search for, e.g. '/usr/bin/sshd'
+    # @return [nil]
     def add_match(field, value)
       match = "#{field.to_s.upcase}=#{value}"
       rc = Native::sd_journal_add_match(@ptr, match, match.length)
@@ -170,8 +202,18 @@ module Systemd
 
     # Add an OR condition to the filter.  All previously added matches
     # and any matches added afterwards will be OR-ed together.
-    # move_next or move_previous must be invoked after adding a match before
-    # attempting to read from the journal.
+    # {#move_next} or {#move_previous} must be invoked after adding a match
+    # before attempting to read from the journal.
+    # @return [nil]
+    # @example Filter entries returned using an OR condition
+    #   j = Systemd::Journal.new
+    #   j.add_match('PRIORITY', 5)
+    #   j.add_match('_EXE', '/usr/bin/sshd')
+    #   j.add_disjunction
+    #   while j.move_next
+    #     # current_entry is either an sshd event or
+    #     # has priority 5
+    #   end
     def add_disjunction
       rc = Native::sd_journal_add_disjunction(@ptr)
       raise JournalError.new(rc) if rc < 0
@@ -179,22 +221,33 @@ module Systemd
 
     # Add an AND condition to the filter.  All previously added matches
     # and any matches added afterwards will be AND-ed together.
-    # move_next or move_previous must be invoked after adding a match before
-    # attempting to read from the journal.
+    # {#move_next} or {#move_previous} must be invoked after adding a match
+    # before attempting to read from the journal.
+    # @return [nil]
+    # @example Filter entries returned using an AND condition
+    #   j = Systemd::Journal.new
+    #   j.add_match('PRIORITY', 5)
+    #   j.add_match('_EXE', '/usr/bin/sshd')
+    #   j.add_conjunction
+    #   while j.move_next
+    #     # current_entry is an sshd event with priority 5
+    #   end
     def add_conjunction
       rc = Native::sd_journal_add_conjunction(@ptr)
       raise JournalError.new(rc) if rc < 0
     end
 
-    # remove all matches and conjunctions/disjunctions.
+    # Remove all matches and conjunctions/disjunctions.
+    # @return [nil]
     def clear_matches
       Native::sd_journal_flush_matches(@ptr)
     end
 
-    # @return the amount of disk usage in bytes used for systemd journal
-    #  files.  If Systemd::Journal::Flags::LOCAL_ONLY was passed when
-    # opening the journal,  this value will only reflect the size of journal
-    #files of the local host, otherwise of all hosts.
+    # Get the number of bytes the Journal is currently using on disk.
+    # If {Systemd::Journal::Flags::LOCAL_ONLY} was passed when opening the
+    # journal,  this value will only reflect the size of journal files of the
+    # local host, otherwise of all hosts.
+    # @return [Integer] size in bytes
     def disk_usage
       size_ptr = FFI::MemoryPointer.new(:uint64)
       rc = Native::sd_journal_get_usage(@ptr, size_ptr)

data/lib/systemd/journal/compat.rb

@@ -7,19 +7,30 @@ module Systemd
     # by Daniel Mack (https://github.com/zonque/systemd-journal.gem)
     module Compat
 
-      LOG_EMERG   = 0 # system is unusable
-      LOG_ALERT   = 1 # action must be taken immediately
-      LOG_CRIT    = 2 # critical conditions
-      LOG_ERR     = 3 # error conditions
-      LOG_WARNING = 4 # warning conditions
-      LOG_NOTICE  = 5 # normal but significant condition
-      LOG_INFO    = 6 # informational
-      LOG_DEBUG   = 7 # debug-level messages
+       # system is unusable
+      LOG_EMERG   = 0
+      # action must be taken immediately
+      LOG_ALERT   = 1
+      # critical conditions
+      LOG_CRIT    = 2
+      # error conditions
+      LOG_ERR     = 3
+      # warning conditions
+      LOG_WARNING = 4
+      # normal but significant condition
+      LOG_NOTICE  = 5
+      # informational
+      LOG_INFO    = 6
+      # debug-level messages
+      LOG_DEBUG   = 7
 
+      # @private
       def self.included(base)
         base.extend(ClassMethods)
       end
 
+      # methods in this module will be available as class methods on
+      #  {Systemd::Journal}
       module ClassMethods
 
         # write a simple message to the systemd journal.

data/lib/systemd/journal/native.rb

@@ -1,5 +1,7 @@
 module Systemd
   class Journal
+    # Provides the FFI bindings to the native `libsystemd-journal` shared
+    #   library.
     module Native
       require 'ffi'
       extend FFI::Library
@@ -26,7 +28,12 @@ module Systemd
       attach_function :sd_journal_enumerate_data, [:pointer, :pointer, :pointer], :int
 
       # event notification
-      attach_function :sd_journal_wait, [:pointer, :uint64], :int
+      enum :wake_reason, [
+        :nop,
+        :append,
+        :invalidate
+      ]
+      attach_function :sd_journal_wait, [:pointer, :uint64], :wake_reason
 
       # filtering
       attach_function :sd_journal_add_match,       [:pointer, :string, :size_t], :int

data/lib/systemd/journal/version.rb

@@ -1,5 +1,6 @@
 module Systemd
   class Journal
-    VERSION = '0.1.0'
+    # The version of the systemd-journal gem.
+    VERSION = '0.1.1'
   end
 end

data/lib/systemd/journal_error.rb

@@ -15,6 +15,7 @@ module Systemd
 
     private
 
+    # FFI wrapper for the C standard library to pull in `strerror`.
     # @private
     module LIBC
       extend FFI::Library

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: systemd-journal
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - John Ledbetter
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-07-25 00:00:00.000000000 Z
+date: 2013-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ffi
@@ -67,7 +67,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.5
+rubygems_version: 2.0.3
 signing_key: 
 specification_version: 4
 summary: Ruby bindings to libsystemd-journal