sys-proctable 0.7.3

data/CHANGES

@@ -0,0 +1,209 @@
+== 0.8.0 - ???
+* Added preliminary support for Darwin (OS X). Thanks go to David Felstead
+  for the code contribution.
+* Added inline rdoc to the source code.
+* Added a gemspec.
+* Fixed some potential 64 bit issues (struct declarations).
+
+== 0.7.3 - 27-Oct-2005
+* Fix for 1.8.3 and later (rb_pid_t). This should have only affected
+  Solaris.
+
+== 0.7.2 - 15-May-2005
+* Bug fix for the FreeBSD version that reads from /proc.
+* Eliminated the test bug on Linux (inexplicably caused by File.copy).  The
+  test suite should now run without segfaulting.
+* Include bsd.c in tarball (oops).
+* Minor test updates for FreeBSD.
+* The 'pct_cpu' member for the BSD/kvm version has been changed to 'pctcpu'
+  consistency with other platforms.
+
+== 0.7.1 - 8-May-2005
+* Bug fixed for the cmdline info on Linux.  Thanks go to Arash Abedinzadeh
+  for the spot.
+* Added an example program.
+* Minor setup fix for Win32 in tc_all.rb.
+
+== 0.7.0 - 25-Apr-2005
+* Scrapped the C implementation for Windows in favor of an OLE + WMI pure Ruby
+  approach.  See documentation for details.
+* Added an optional lkvm implementation for BSD users.  This is automatically
+  used if the /proc filesystem isn't found.
+* Added prusage info for the Solaris version.
+* Added name, eid, euid, gid and guid information for Linux.  Thanks go to
+  James Hranicky for the patch.
+* Fixed some potential bugs in the Linux version.  Thanks go to James
+  Hranicky for the spot.
+* Added the 'sys/top' package.
+* ProcTable.fields no longer supports a block form.
+* The BTIME (boot time) information has been removed from the Linux version.
+  If you want that information, use sys-uptime instead.
+* The .html and .rd files have been removed.  You can generate html on your
+  own with rdoc if you like.
+* Some code cleanup on the C side of the house.
+* Most documents made rdoc friendly.
+* Renamed 'install_pure_ruby.rb' to just 'install.rb'.
+* Removed the 'INSTALL' file.  Installation instructions are in the README.
+* Some test suite cleanup and reorganization.
+* Moved project to RubyForge.
+
+== 0.6.4 - 31-Mar-2004
+* Fixed a bug in the pure Ruby version for Win32.  Thanks go to Mark Hudson
+  for the spot.
+* Fixed a bug in the C implementation for Win32 where the cmdline and path
+  values were sometimes wrong for running processes.  Thanks go to Park Heesob
+  for the fix.
+* Updated the VERSION constant and removed the VERSION class method in the
+  pure Ruby version for Win32.
+* Updated install_pure_ruby.rb and test.rb scripts.
+* Updated warranty information.
+* The extconf.rb script has been revamped.  See the INSTALL and README files
+  for important changes since the last release.
+* The start ProcInfo struct member on Solaris, HP-UX and FreeBSD is now a
+  Time object, not a Fixnum/Bignum.
+* Modified linux.c yet again to make gcc happy when it comes to multi-line
+  string literals.
+* Minor change to way process state is handled on HP-UX.
+* Documentation additions and updates, including warranty information.
+
+== 0.6.3 - 24-Feb-2004
+* Fixed a bug in the Solaris version where the cmd_args array did not
+  necessarily contain data on 2.7 and later.  The current patch still
+  does not quite fix the problem for 2.6 and earlier but can be easily
+  derived manually by parsing the cmdline string.
+
+== 0.6.2 - 20-Jan-2004
+* Fixed a small memory leak in the solaris version.
+
+== 0.6.1 - 31-Dec-2003
+* Fixed a minor bug in the cmdline field on Linux where a blank character
+  was being appended to the end of the field.
+* Fixed a minor annoyance where the windows.rb file was being copied into
+  the Ruby lib directory on install.
+* Added a test_memleak.rb file.  Currently only supported on Linux and
+  only does a file descriptor count check.  I plan to expand this to
+  other platforms in the future.
+* Minor test suite changes
+* MANIFEST correction and update.
+
+== 0.6.0 - 22-Oct-2003
+* Significant API change (and thus, a version jump) - only a
+  single argument is now accepted to the ps() method, and only a PID
+  (Fixnum) is regarded as a valid argument.
+* Calling ps() with a pid returns a single ProcTable struct (or nil
+  if the pid is not found), instead of a one element array.
+* Argument to ps() now works properly on HP-UX and Win32.
+* Removed the '#include <sys/types32.h>' in sunos.h.  It wasn't needed
+  and you're not supposed to include it directly.
+* Fixed 2.6 compatibility issue with regards to cmdline on Solaris.
+* Removed the ProcStatException completely on Linux.  There was no reason
+  to fail on a directory read for /proc/xxx/stat.  If the read fails
+  (meaning the process died in the middle of collecting info for it), it
+  is simply ignored.
+* The ttynum bug on HPUX has been fixed.  In addition, the return value for
+  this field is now a string rather than an int and the field name has
+  been changed to "ttydev".
+* The ttynum field has been changed to ttydev on Solaris and HPUX.  On
+  Solaris, the ttydev is now reported as -1 if there is no associated tty.
+  In a future release, Solaris and the other *nix platforms will be changed 
+  so that ttydev is always a device name (i.e String).
+* Added plain text documentation for all platforms.
+* Some test suite cleanup.
+* Changed .rd2 extension to just '.rd'.
+
+== 0.5.2 - 18-Jul-2003
+* Modified cmdline to extend past the traditional 80 character limit on
+  Solaris, where possible (Solaris 2.6+ only).
+* Added the cmdline_args and num_args fields on Solaris, which returns
+  an array of cmdline arguments and the number of cmdline arguments,
+  respectively.
+* Minor modification to fields() method, in addition to warning cleanup
+  for Solaris.
+* Changed "defunct" state string to "zombie" for Solaris.
+* Should cleanly compile with -Wall -W now (gcc) on Solaris.
+* Added solaris.txt to doc directory.
+* MANIFEST corrections.
+
+== 0.5.1 - 16-Jul-2003
+* Fixed a nasty file descriptor bug in the Linux code, where file descriptors
+  were continuously being used up.
+* Added the BTIME (boot time) constant for Linux.
+* Fixed up the test/test.rb file a bit.
+* Added BTIME tests to tc_linux.rb.
+
+== 0.5.0 - 11-Jul-200
+* Added HP-UX support!
+* Note that passing PID's or strings as arguments to ps() is not supported
+  in the HP-UX version.  This functionality will be stripped out of the
+  other versions in a future release.  See the README file for more details.
+* Removed the VERSION() class method.  Use the constant instead.
+* Separated the rd docs from their respective source files.  Now in the doc
+  directory.
+* Got rid of the interactive html generation in extconf.rb.
+* Changed License to Artistic.
+
+== 0.4.3 - 30-May-2003
+* Added a version.h file to store the version number. Modified all of the
+  C source files to use that instead of hard coding the version everywhere.
+* Added a generic test.rb script for those without TestUnit installed, or
+  just futzing in general.  Modified the extconf.rb script to copy this
+  instead of writing an inline HERE document.
+* Modified extconf.rb so that it builds with mingw or cygwin.  Thanks go to
+  Peter Fischer for the spot and patch.
+* Modified test suite to work with TestUnit 0.1.6 or 0.1.8.
+
+== 0.4.2 - 14-Apr-2003
+* Added pure Ruby version for Win32 - thanks Park Heesob.
+* Modified extconf.rb file to handle pure Ruby versions.
+* Added install_pure_ruby.rb file, an alternate installation
+  script for pure Ruby versions.
+
+== 0.4.1 - 31-Mar-2003
+* Added support for Solaris 2.5.x.
+* All exceptions are now a direct subclass of StandardError.
+* Value returned for wchan now more meaningful (2.5.x only for now).
+* Fixed the start, utime and ctime for FreeBSD.
+* Minor fix to FreeBSD test suite.
+* Some changes to extconf.rb.
+* Minor doc changes.
+* Added License and Copyright info.
+
+== 0.4.0 - 10-Mar-2003
+* Added MS Windows support (non-cygwin).
+* Added environment information for Linux version.
+* Added real exceptions (type depends on platform).
+* Added a test suite (for those with testunit installed).
+* Removed the sys-uname requirement.
+* Heavily modified the extconf.rb script.
+* Changed "Changelog" to "CHANGES" and "Manifest" to "MANIFEST".
+* Added a VERSION constant and class method.
+* Minor internal directory layout change (put 'os' under 'lib').
+* Changed package name to lower case.
+* Doc changes, including license information.
+
+== 0.3.1 - 16-Aug-2002
+* Added a "comm" field to the sunos version.  I am going to try to make this a
+  common field for all platforms to help reduce RUBY_PLATFORM checking.
+* Fixed the release date for 0.3.0 (was accidentally marked *July*).
+* Added an INSTALL file.
+* Minor documentation change to the sunos.c source file.
+
+== 0.3.0 - 11-Aug-2002
+* Added FreeBSD support!
+* Struct name changed to just "ProcTableStruct" to be compliant with future
+  versions of Ruby.
+* The ps() function now returns an array of ProcTableStruct's in lvalue context.
+* Fixed the ability to search by process name in Linux.
+* Modified Linux "comm" field to strip parenthesis.
+* Some doc changes/additions.
+* Added Sean Chittenden to the "Acknowledgements" section.  Sean provided me
+  with access to a FreeBSD box, which is how I was able to provide FreeBSD
+  support.  Thanks Sean!
+
+== 0.2.0 - 19-Jul-2002
+* Added the ability to search by process name.
+* test.rb modified to be cross-platform.
+* Solaris - fixed bug with fname (was accidentally called "name").
+
+== 0.1.0 - 2-Jul-2002
+- Initial release.

data/README

@@ -0,0 +1,68 @@
+== Prerequisites
+Unix: Ruby 1.8.0 or later.
+Win32: Ruby 1.8.2 or later.
+
+== Supported Platforms
+* Windows NT family (NT, 2000, XP, etc)
+* Linux
+* FreeBSD (/proc or kvm)
+* Solaris
+* NetBSD (kvm only)
+* HP-UX
+
+== Installation
+Unix:
+   ruby extconf.rb
+   make
+   ruby test.rb (optional)
+   make site-install
+   
+Windows:
+   ruby test/tc_windows.rb (optional)
+   ruby install.rb
+
+== Notes 
+Windows users may pass a host name as a second argument to get process
+information from a different host.  This relies on the WMI service running.
+
+If you're building C source code, the test.rb file is autogenerated for you.
+
+== BSD Issues
+If you're building on FreeBSD, a standard /proc filesystem read approach is
+used if mounted.  Otherwise, a kvm interface is used.  There are more fields
+available with the kvm interface, but keep in mind that you need to be a
+member of the kvm group (or root) to use this.  You can tweak the
+extconf.rb file manually if you want to force the issue.
+
+Not all fields are available on FreeBSD 5.x (yet).  OpenBSD and NetBSD are
+not yet supported.
+
+Research has indicated that the kvm approach is less favored than a sysctl
+approach.  I will try to add this interface in the 0.8.0 release.
+
+== Solaris Issues
+The cmdline member on solaris is limited to 80 characters unless you (or
+your program) own the process.  This is a Solaris design flaw, er, feature.
+
+== Other Issues
+If you build your library as a C extension (mandatory on all platforms
+except MS Windows at the moment), then the windows.rb file under 'lib/os/'
+is renamed to 'windows.orig'.  This is to prevent mkmf from auto-installing
+it during the 'make site-install' phase.
+
+== Thread Safety
+I am not currently using a thread-safe version of readdir().  I am not especially
+concerned about it either.  If you are trying to read information out of /proc
+from different threads at the same time there is something seriously wrong with
+your code logic.  Using readdir_r() still won't solve all potential thread safety
+issues anyway.
+
+== Future Plans
+I think I'm going to replace the version for Linux with a pure Ruby version.
+
+== Help Wanted
+I do not have access to all platforms.  There are a few other major platforms
+out there, namely OS X, AIX, OpenBSD, and IRIX, among others, that I would
+like to see ports for.  There are two ways you can help - either submit code
+for your particular platform or give me an account on your platform so I can
+develop on it.

data/doc/freebsd.txt

@@ -0,0 +1,101 @@
+== Description
+   sys-proctable
+
+   A Ruby interface to the 'ps' command.  This is a C extension, not parsed
+   output.  For FreeBSD, data is read directly out of the /proc filesystem.
+
+== 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. Also takes 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 pid argument 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
+    Add a pure-ruby version as an alternative
+    Add support for other *BSD flavors
+    Add ttydev info
+    Add a sysctl version
+
+== Known Bugs
+    The kvm version for FreeBSD 5.x does not support all of the fields that
+    the 4.x version supports.
+    
+    If you find any other bugs please log them 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/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 (originally) added.
+
+== See Also
+    ps, proc

data/doc/hpux.txt

@@ -0,0 +1,90 @@
+== 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-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