sys-proctable 0.7.3

data/doc/linux.txt

@@ -0,0 +1,101 @@
+== 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-2005 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 yahoo dot com
+    rubyhacker1/imperator on IRC
+
+== Credits
+    This module is largely based on the Perl module Proc::ProcessTable by
+    Dan Urist.  Many ideas, as well as large chunks of code, were taken
+    from his work.  So, a big THANK YOU goes out to Dan Urist.
+
+    A big thanks also goes out to Mike Hall who was very helpful with ideas,
+    logic and testing.
+
+    Thanks also go to Sean Chittenden for providing an account on one of his
+    FreeBSD machines.  This is how the FreeBSD support was (initially) added.
+    
+    Thanks go to James Hranicky for providing a patch that grabs name, eid,
+    euid, gid and guid info in the Linux version, along with some general
+    debugging help.
+
+== See Also
+    ps, proc(5)

data/doc/solaris.txt

@@ -0,0 +1,120 @@
+== 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
+    If you're using Ruby 1.8.x there is a known issue with large file support.
+    There are only two solutions that I am aware of currently.  You can either
+    rebuild Ruby with the --disable-largefile option or you can build a 64 bit
+    Ruby.
+    
+    I have posted this issue to the mailing list, but have not received a
+    satisfactory response.  I suspect there is an issue with the configure
+    script, because this does not happen with Ruby 1.6.x.
+    
+    Please log any additional bugs on the SourceForge project page at
+    http://www.rubyforge.org/projects/sysutils
+
+== License
+    Ruby's
+    
+== Copyright
+    (C) 2003-2005 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 yahoo dot com
+    imperator/rubyhacker1 on IRC (Freenode)
+    
+== Credits
+    This module is largely based on the Perl module Proc::ProcessTable by
+    Dan Urist.  Many ideas, as well as large chunks of code, were taken
+    from his work.  So, a big THANK YOU goes out to Dan Urist.
+
+    A big thanks also goes out to Mike Hall who was very helpful with ideas,
+    logic and testing.
+
+    Thanks also go to Sean Chittenden for providing an account on one of his
+    FreeBSD machines.  This is how the FreeBSD support was (initially) added.
+    
+== See Also
+    ps, proc

data/doc/top.txt

@@ -0,0 +1,54 @@
+== 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-2005 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 yahoo dot com
+	imperator/rubyhacker1 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-2005 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 yahoo dot com
+    imperator/mok/rubyhacker1 on IRC (freenode)
+    
+== See Also
+    OLE + WMI

data/extconf.rb

@@ -0,0 +1,104 @@
+#############################################################################
+# Installation script for sys-proctable.
+#
+# By running this file, it is assumed that you want a C extension, and not
+# a pure Ruby version.  If you want a pure Ruby version (and you're on a 
+# platform for which it's supported), run install.rb instead.
+#############################################################################
+require "mkmf"
+require "ftools"
+
+c_file  = nil
+h_file  = nil
+tc_file = nil
+lib_dir = "lib/os"
+
+########################################################################
+# Ruby 1.8.3 and later mandates the use of rb_pid_t over pid_t because
+# some libraries define their own pid_t.  So, we check for that.
+########################################################################
+have_type("rb_pid_t", "ruby.h")
+
+##########################################################################
+# Determine appropriate source files based on platform.  Also, check for
+# certain header files and/or libraries on some platforms.
+#
+# On FreeBSD a different source file is used if the /proc filesystem is
+# not found (kvm is used instead).  For OpenBSD or NetBSD, the kvm
+# interface is always used for now.
+##########################################################################
+case RUBY_PLATFORM
+   when /hpux/i
+      c_file  = "#{lib_dir}/hpux.c"
+      h_file  = "#{lib_dir}/hpux.h"
+      tc_file = "test/tc_hpux"
+   when /freebsd/i
+      if File.exists?("/proc") && Dir["/proc/*"].length > 0
+         c_file  = "#{lib_dir}/freebsd.c"
+         h_file  = "#{lib_dir}/freebsd.h"
+         tc_file = "test/tc_freebsd"
+      else
+         have_library("kvm")
+         have_struct_member("struct kinfo_proc", "kp_proc", "sys/user.h")
+         have_struct_member("struct kinfo_proc", "kp_eproc", "sys/user.h")
+         c_file  = "#{lib_dir}/bsd.c"
+         tc_file = "test/tc_kvm_bsd.rb"
+      end
+   when /openbsd|netbsd/
+      have_library("kvm")
+      c_file  = "#{lib_dir}/bsd.c"
+      tc_file = "test/tc_kvm_bsd.rb"
+   when /solaris|sunos/i
+      c_file  = "#{lib_dir}/sunos.c"
+      h_file  = "#{lib_dir}/sunos.h"
+      tc_file = "test/tc_sunos"
+      have_header('procfs.h') # false means Solaris 2.5.x
+   when /linux/i
+      c_file  = "#{lib_dir}/linux.c"
+      h_file  = "#{lib_dir}/linux.h"
+      tc_file = "test/tc_linux"
+   when /darwin/i
+      c_file = "#{lib_dir}/darwin.c"
+      tc_file = "test/tc_darwin.rb"
+   when /windows|win32|cygwin|mingw|dos/i
+      msg = "Use the install_pure_ruby.rb script to install on MS Windows"
+      STDERR.puts msg
+      exit
+   else
+      puts "This platform not currently supported.  Exiting..."
+      exit
+end
+
+########################################################################
+# Move any ".rb" files under 'lib/os/' to ".orig" to prevent mkmf from
+# installing them during the 'make site-install' phase.
+########################################################################
+Dir["lib/os/*.rb"].each{ |f|
+   File.rename(f,"lib/os/" + File.basename(f,".rb")+".orig")
+}
+
+################
+# build test.rb
+################
+test_file = "test.rb"
+File.open(test_file,"w+"){ |fh|
+   fh.puts "$LOAD_PATH.unshift Dir.pwd"
+   fh.puts "require \"test/tc_all\""
+   fh.puts "require \"#{tc_file}\""
+   fh.puts "require \"test/tc_top\""
+}
+
+########################################################################
+# Copy or link files to current directory for create_makefile to work.
+######################################################################## 
+File.delete("proctable.c") if File.exists?("proctable.c")
+File.delete("version.h") if File.exists?("version.h")
+if h_file && File.exists?(File.basename(h_file))
+   File.delete(File.basename(h_file))
+end
+	
+File.symlink(c_file,"proctable.c")
+File.symlink(h_file,File.basename(h_file)) unless h_file.nil?
+File.symlink("lib/version.h","version.h")
+
+create_makefile("sys/proctable")