sys-proctable 0.7.4-mswin32

data/doc/hpux.txt

@@ -0,0 +1,78 @@
+= Description
+   sys-proctable
+
+   A Ruby version of the 'ps' command.  This is a C extension, not parsed
+   output.  For HP-UX, proc structs are grabbed via the pstat_getproc() call.
+
+= Synopsis
+   require 'sys/proctable'
+   include Sys
+
+   # Everything
+   ProcTable.ps{ |p|
+      puts p.pid.to_s
+      puts p.comm
+      ...
+   }
+
+   or
+
+   # Return the results as an array of ProcTableStructs
+   a = ProcTable.ps()
+   a.each do |p|
+      puts a.pid
+      ...
+   end
+
+= Constants
+VERSION
+   Returns the current version number for this package (as a string).
+
+= Class Methods
+ProcTable.fields
+   Returns a list of fields available on the current OS.  May also take
+   a block.
+
+ProcTable.ps(pid=nil)
+ProcTable.ps{ |s| ... }
+   Returns a struct of type ProcTableStruct for every process in the proc
+   table in block form.  Otherwise it returns an array of ProcTableStruct's.
+
+   If a pid is provided then a single ProcTable struct is returned, or nil
+   if the pid is not found.
+
+= Supported fields
+   You can view the supported fields with the "fields()" class method.
+
+= Future Plans
+   Have the flags field return a meaningful value.
+
+= Notes
+   The "comm" field isn't really part of the psinfo struct.  It is just a copy
+   (i.e. is identical to) the "fname" field.  I added it to provide a degree
+   of consistency between all of the platforms.  I will also make a point
+   of adding it to any future platform releases.
+
+= Known Bugs
+   None that I'm aware of.  Please log any bugs on the project page at
+   http://www.rubyforge.org/projects/sysutils
+
+= License
+   Ruby's
+
+= Copyright
+   (C) 2003-2006 Daniel J. Berger
+   All Rights Reserved.
+    
+= Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+= Author
+   Daniel J. Berger
+   djberg96 at nospam at gmail dot com
+   imperator on IRC (Freenode)
+
+= See Also
+   ps, proc

data/doc/linux.txt

@@ -0,0 +1,86 @@
+= Description
+   sys-proctable
+
+   A Ruby version of the 'ps' command.  This is a C extension, not parsed
+   output. For Linux, process information is read out of /proc.
+
+= Synopsis
+   require 'sys/proctable'
+   include Sys
+
+   # Everything
+   ProcTable.ps{ |p|
+      puts p.pid.to_s
+      puts p.comm
+      ...
+   }
+
+   or
+
+   # Just one process
+   p = ProcTable.ps(2123)
+   puts p.pid.to_s
+   puts p.comm
+   ...
+
+   or
+
+   # Return the results as an array of ProcTableStructs
+   a = ProcTable.ps()
+   a.each do |p|
+      puts a.pid
+      ...
+   end
+
+= Constants
+VERSION
+   Returns the current version number for this package (as a string).
+
+= Class Methods
+ProcTable.fields
+   Returns a list of fields available on the current OS.  May also take a
+   block.
+
+ProcTable.ps(pid=nil)
+ProcTable.ps{ |s| ... }
+   If no pid's or processes are included as arguments, in block form it
+   returns a struct of type ProcTableStruct for every process in the proc
+   table.  Otherwise it returns an array of ProcTableStruct's.
+
+   If a process id is provided, a single ProcTable struct is returned, or
+   nil if the pid is not found.
+
+= Exception Classes
+ProcTableError < StandardError
+   Raised if the /proc field is unreadable and/or unmounted.
+
+= Supported fields
+   You can view the supported fields with the "fields()" class method.
+
+= Future Plans
+   Create a pure Ruby version as an alternative.
+   Change the ttynum field to ttydev and return a string instead of an int.
+
+= Known Bugs
+   None known.  Please log any bugs on the project page at
+   http://www.rubyforge.org/projects/sysutils
+
+= License
+   Ruby's
+
+= Copyright
+   (C) 2003-2006 Daniel J. Berger
+    All Rights Reserved
+    
+= Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+= Author
+   Daniel J. Berger
+   djberg96 at nospam at gmail dot com
+   rubyhacker1 on IRC (Freenode)
+
+= See Also
+    ps, proc(5)

data/doc/solaris.txt

@@ -0,0 +1,100 @@
+= Description
+   sys-proctable
+
+   A Ruby version of the 'ps' command.  This is a C extension, not parsed
+   output.  For Solaris, data is read out of /proc via the psinfo struct.
+   
+= Synopsis
+   require 'sys/proctable'
+   include Sys
+
+   # Everything
+   ProcTable.ps{ |p|
+      puts p.pid.to_s
+      puts p.comm
+      ...
+   }
+
+   or
+
+   # Just one process
+   s = ProcTable.ps(2123)
+   puts s.pid.to_s
+   puts s.comm
+   ...
+
+   # Return the results as an array of ProcTableStructs
+   a = ProcTable.ps
+   a.each do |p|
+      puts a.pid
+      ...
+   end
+   
+= Constants
+VERSION
+   Returns the current version number for this package (as a string).
+    
+= Class Methods
+ProcTable.fields
+   Returns a list of fields available on the current OS.  May also take
+   a block.
+    
+ProcTable.ps(pid=nil)
+ProcTable.ps{ |s| ... }
+   If no pid is included as an argument, in block form it
+   returns a struct of type ProcTableStruct for every process in the proc
+   table.  Otherwise it returns an array of ProcTable struct's.  If a pid
+   is provided it will return a single ProcTable struct for that pid, or
+   nil if it is not found.
+    
+= Exception Classes
+ProcTableError < StandardError
+   Raised if the /proc directory is unreadable and/or unmounted.
+    
+= Supported fields
+   You can view the supported fields with the "fields()" class method.
+
+= Future Plans
+   Return a more meaningful result for the wchan member (2.6+).
+   Add env info where possible.
+    
+= Notes
+   The "comm" field isn't really part of the psinfo struct.  It is just a copy
+   (i.e. is identical to) the "fname" field.  I added it to provide a degree
+   of consistency between all of the platforms.  I will also make a point
+   of adding it to any future platform releases.
+
+   The cmdline string is limited to 80 characters, except for those processes
+   which you (or your program) own.
+
+   The ttydev field is, for now, an integer.  If there is no associated tty with
+   the process, a -1 is returned.   In the future, this field will be changed to
+   a string (i.e. the actual device name).
+
+   I suppose I *could* add a -lkvm version for Solaris (this is what Dan Urist
+   is now using in Proc::ProcessTable) but I haven't found a compelling reason
+   to do so.  If you think you have one, please let me know.
+    
+= Known Bugs
+   None that I am aware of.  Please log any bugs on the RubyForge project page at
+   http://www.rubyforge.org/projects/sysutils
+
+= License
+   Ruby's
+    
+= Copyright
+   (C) 2003-2006 Daniel J. Berger
+   All Rights Reserved.
+    
+= Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+	
+= Author
+   Daniel J. Berger
+   djberg96 at nospam at gmail dot com
+   imperator on IRC (Freenode)
+    
+= See Also
+   ps, proc

data/doc/top.txt

@@ -0,0 +1,53 @@
+= Description
+   A simple 'top' interface for Ruby
+
+= Prerequisites
+   Requires the "sys/proctable" package (which should be installed along
+   with this package).
+
+= Synopsis
+   require "sys/top"
+   include Sys
+
+   Top.top(5).each{ |ps|
+      p ps
+   }
+	
+= Constants
+VERSION
+   Returns the version number of this package as a String.
+	
+= Class Methods
+Top.top(number=10, field="pctcpu")
+   Returns an array of ProcTableStruct's.  The size of the array (i.e. the
+   number of processes) that it returns is based on +number+, and sorted by
+   +pctcpu+.  By default, the size and field values are 10 and "pctcpu",
+   respectively.
+
+= Notes
+   Not all fields are available on all platforms.  Please check your
+   platform specific documentation for which fields are available.
+
+   I used sort() instead of sort_by() internally to maintain backward
+   compatability with Ruby 1.6.8, which I happen to need.
+	
+= Bugs
+   None that I'm aware of.  Please log bug reports on the project page at
+   http://www.rubyforge.org/projects/sysutils
+	
+= License
+   Ruby's
+	
+= Copyright
+   (C) 2004-2006 Daniel J. Berger
+   All Rights Reserved.
+    
+= Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+
+= Author
+   Daniel J. Berger
+   djberg96 at nospam at gmail dot com
+   imperator on IRC (Freenode)

data/doc/windows.txt

@@ -0,0 +1,122 @@
+= Description
+   A Ruby interface for gathering process information.  For MS Windows,
+   the process information is gathered via OLE + WMI, using pure Ruby.
+   
+= Synopsis
+   require 'sys/proctable'
+   include Sys
+
+   # Everything
+   ProcTable.ps{ |p|
+      puts p.pid.to_s
+      puts p.comm
+      ...
+   }
+
+   or
+
+   # A single pid
+   p = ProcTable.ps(1234)
+   puts p.pid.to_s
+   puts p.comm
+   ...
+
+   or
+
+   # Return the results as an array of ProcTableStructs
+   a = ProcTable.ps
+   a.each do |p|
+      puts a.pid
+      ...
+   end
+   
+= Constants
+VERSION
+   Returns the current version number for this package (as a string).
+    
+= Class Methods
+ProcTable.fields
+   Returns an Array of fields available on the current OS in the
+   ProcTableStruct.
+    
+ProcTable.ps(pid=nil, host='localhost')
+ProcTable.ps{ |s| ... }
+   Returns a struct of type ProcTableStruct for every process in the proc
+   table in block form.  Otherwise it returns an array of ProcTableStruct's.
+
+   If 'pid' is provided, then only a struct for that pid is returned, or
+   nil if it is not found.
+ 
+   If 'host' is provided, then processes from that host are gathered.  By
+   default, process information is gathered on the local host.
+	 	
+= Supported fields
+   The currently supported fields for MS Windows (i.e. your ProcTable struct
+   members) are:
+    
+    caption, cmdline, comm, creation_class_name, creation_date,
+    cs_creation_class_name, cs_name, description, executable_path,
+    execution_state, handle, handle_count, install_date, kernel_mode_time,
+    maximum_working_set_size, minimum_working_set_size, name,
+    os_creation_class_name, os_name, other_operation_count,
+    other_transfer_count, page_faults, page_file_usage, peak_virtual_size,
+    ppid, peak_working_set_size, priority, private_page_count, pid,
+    quota_non_paged_pool_usage, quota_paged_pool_usage,
+    quota_peak_non_paged_pool_usage, quota_non_paged_pool_usage,
+    read_operation_count, read_transfer_count, session_id,
+    termination_date, thread_count, user_mode_time, virtual_size,
+    windows_version, working_set_size, write_operation_count,
+    write_transfer_count
+
+    You can also view them with the fields() class method.
+    
+= Notes
+   For the sake of attempting to provide a somewhat common API, the 'comm'
+   and 'cmdline' fields have been included as part of the structure.  The
+   'comm' member corresponds to the Name attribute of Win32_Process.  The
+   'cmdline' attribute corresponds to either the Executable_Path attribute
+   (on Windows 2000 or earlier) or the CommandLine attribute (on Windows XP
+   and later).
+	 
+   Also note that the ProcessId and ParentProcessId attributes have been
+   abbreviated as 'pid' and 'ppid' in the struct members, again to keep the
+   members more consistent between platforms.
+	 
+   The "Mem Usage" and "VM Size" that you may be used to seeing in your Task
+   Manager window (probably) correspond to the 'working_set_size' and
+   'page_file_usage' struct members, respectively, keeping in mind that
+   those values are in bytes, not kilobytes.  I say 'probably' because
+   comments that I've read online indicate that it may not always line up
+   with what you see in the Task Manager, based on the current version (or
+   even Service Pack) of Windows that you are using.
+	 
+= Future Plans
+   Possibly use the Win32_PerfFormattedData_PerfProc_Process class to get
+   additional process information.
+    
+= Known Bugs
+   Versions of Ruby earlier than 1.8.2 resulted in segfaults when trying to
+   run this code.  You will likely encounter the same behavior.
+
+   Please log any additional bug reports on the project page at
+   http://www.rubyforge.org/projects/sysutils
+	
+= License
+   Ruby's
+    
+= Copyright
+   (C) 2003-2006 Daniel J. Berger
+   All Rights Reserved
+    
+= Warranty
+   This package is provided "as is" and without any express or
+   implied warranties, including, without limitation, the implied
+   warranties of merchantability and fitness for a particular purpose.
+	
+= Author
+   Daniel J. Berger
+   djberg96 at nospam at gmail dot com
+   imperator on IRC (freenode)
+    
+= See Also
+   OLE + WMI

data/lib/sys/proctable.rb

@@ -0,0 +1,197 @@
+require 'win32ole'
+require 'socket'
+require 'parsedate'
+
+module Sys
+   class ProcTableError < StandardError; end
+   class ProcTable
+      VERSION = '0.7.4'
+      
+      ########################################################################
+      # The comm field corresponds to the 'name' field.  The 'cmdline' field
+      # is the CommandLine attribute on Windows XP or later, or the 
+      # 'executable_path' field on Windows 2000 or earlier.
+      ########################################################################     
+      @fields = %w/
+         caption
+         cmdline
+         comm
+         creation_class_name
+         creation_date
+         cs_creation_class_name
+         cs_name
+         description
+         executable_path
+         execution_state
+         handle
+         handle_count
+         install_date
+         kernel_mode_time
+         maximum_working_set_size
+         minimum_working_set_size
+         name
+         os_creation_class_name
+         os_name
+         other_operation_count
+         other_transfer_count
+         page_faults
+         page_file_usage
+         peak_virtual_size
+         ppid
+         peak_working_set_size
+         priority
+         private_page_count
+         pid
+         quota_non_paged_pool_usage
+         quota_paged_pool_usage
+         quota_peak_non_paged_pool_usage
+         quota_non_paged_pool_usage
+         read_operation_count
+         read_transfer_count
+         session_id
+         termination_date
+         thread_count
+         user_mode_time
+         virtual_size
+         windows_version
+         working_set_size
+         write_operation_count
+         write_transfer_count
+      /
+      
+      ProcTableStruct = Struct.new("ProcTableStruct", *@fields)
+      
+      # call-seq:
+      #    ProcTable.fields
+      # 
+      # Returns an array of fields that each ProcTableStruct will contain.  This
+      # may be useful if you want to know in advance what fields are available
+      # without having to perform at least one read of the /proc table.
+      #
+      def self.fields
+         @fields
+      end
+      
+      # call-seq:
+      #    ProcTable.ps(pid=nil)
+      #    ProcTable.ps(pid=nil){ |ps| ... }
+      # 
+      # In block form, yields a ProcTableStruct for each process entry that you
+      # have rights to.  This method returns an array of ProcTableStruct's in
+      # non-block form.
+      # 
+      # If a +pid+ is provided, then only a single ProcTableStruct is yielded or
+      # returned, or nil if no process information is found for that +pid+.
+      #
+      def self.ps(pid=nil, host=Socket.gethostname)
+         if pid
+            raise TypeError unless pid.kind_of?(Fixnum)
+         end
+              
+         begin
+            wmi = WIN32OLE.connect("winmgmts://#{host}/root/cimv2")
+         rescue WIN32OLERuntimeError => e
+            raise ProcTableError, e
+         else
+            a = [] # Array used to hold structs if no block given
+            wmi.InstancesOf("Win32_Process").each{ |proc|        
+               if pid                
+                  next unless proc.ProcessId == pid
+               end
+
+               # Some fields are added later, and so are nil initially
+               s = ProcTableStruct.new(
+                  proc.Caption,
+                  nil, # Added later, based on OS version
+                  proc.Name,
+                  proc.CreationClassName,
+                  self.parse_ms_date(proc.CreationDate),
+                  proc.CSCreationClassName,
+                  proc.CSName,
+                  proc.Description,
+                  proc.ExecutablePath,
+                  proc.ExecutionState,
+                  proc.Handle,
+                  proc.HandleCount,
+                  self.parse_ms_date(proc.InstallDate),
+                  self.convert(proc.KernelModeTime),
+                  proc.MaximumWorkingSetSize,
+                  proc.MinimumWorkingSetSize,
+                  proc.Name,
+                  proc.OSCreationClassName,
+                  proc.OSName,
+                  self.convert(proc.OtherOperationCount),
+                  self.convert(proc.OtherTransferCount),
+                  proc.PageFaults,
+                  proc.PageFileUsage,
+                  self.convert(proc.PeakVirtualSize),
+                  proc.ParentProcessId,
+                  self.convert(proc.PeakWorkingSetSize),
+                  proc.Priority,
+                  self.convert(proc.PrivatePageCount),
+                  proc.ProcessId,
+                  proc.QuotaNonPagedPoolUsage,
+                  proc.QuotaPagedPoolUsage,
+                  proc.QuotaPeakNonPagedPoolUsage,
+                  proc.QuotaPeakPagedPoolUsage,
+                  self.convert(proc.ReadOperationCount),
+                  self.convert(proc.ReadTransferCount),
+                  proc.SessionId,
+                  self.parse_ms_date(proc.TerminationDate),
+                  proc.ThreadCount,
+                  self.convert(proc.UserModeTime),
+                  self.convert(proc.VirtualSize),
+                  proc.WindowsVersion,
+                  self.convert(proc.WorkingSetSize),
+                  self.convert(proc.WriteOperationCount),
+                  self.convert(proc.WriteTransferCount)
+               )
+            
+               ###############################################################
+               # On Windows XP or later, set the cmdline to the CommandLine
+               # attribute.  Otherwise, set it to the ExecutablePath
+               # attribute.
+               ###############################################################
+               if proc.WindowsVersion.to_f < 5.1
+                  s.cmdline = proc.ExecutablePath
+               else
+                  s.cmdline = proc.CommandLine
+               end
+              
+               if block_given?
+                  yield s
+               else
+                  a.push(s)
+               end
+            }
+         end
+         unless block_given?
+            return nil if a.empty?
+            return a.first if pid
+            return a
+         end
+      end
+      
+      private
+      
+      #######################################################################
+      # Converts a string in the format '20040703074625.015625-360' into a
+      # Ruby Time object.
+      #######################################################################
+      def self.parse_ms_date(str)
+         return if str.nil?
+         parsed = ParseDate.parsedate(str)
+         return Time.mktime(*parsed)
+      end
+      
+      #####################################################################
+      # There is a bug in win32ole where uint64 types are returned as a
+      # String instead of a Fixnum.  This method deals with that for now.
+      #####################################################################
+      def self.convert(str)
+         return nil if str.nil? # Return nil, not 0
+         return str.to_i
+      end
+
+   end
+end