sys-admin 1.4.3-x86-mswin32-60

data/CHANGES

@@ -0,0 +1,69 @@
+== 1.4.3 - 2-Mar-2008
+* The block form of Admin.users now properly ensures that endpwent() is
+  called. Likewise, the block form of Admin.groups now properly ensures
+  that endgrent() is called. This would only have been an issue if you
+  broke out of the block before it terminated.
+* The AdminError class is now Admin::Error.
+* Some internal directory layout changes.
+
+== 1.4.2 - 26-Jun-2007
+* Fixed a bug in the Admin.get_login method where it would return junk
+  if the underlying getlogin() function failed (Unix). Thanks go to Gonzalo
+  Garramuno for the spot. This bug also resulted in some refactoring of the
+  underlying C code.
+* Removed the install.rb file. The logic in that file has been moved directly
+  into the Rakefile.
+
+== 1.4.1 - 21-Mar-2007
+* Bug fix for OS X. Thanks go to an anonymous user for the spot.
+* Added a Rakefile. Building, testing and installing should now use the
+  Rake tasks (for non-gem installs).
+* Much more inline documentation, especially for User and Group attributes.
+
+== 1.4.0 - 20-Jan-2007
+* Added the following methods: add_local_user, config_local_user,
+  delete_local_user, add_global_group, config_global_group, and
+  delete_global_group.  MS Windows only at the moment.
+* Added corresponding tests.
+* Added much more inline documentation.
+* Major refactoring of the get_lastlog_info helper function in admin.h.  This
+  fixed a major bug in some flavors of Linux where the Admin.users method
+  could go into an infinite loop.  It also fixed some minor bugs where console
+  and host values were sometimes filled with junk characters.
+* Added the User#change attribute, and a check for the pw_change struct member
+  in the extconf.rb file.
+* The User#expire attribute is now handled as a Time object instead of an
+  integer.
+* Renamed tc_win32.rb to tc_windows.rb
+
+== 1.3.1 - 29-Jun-2005
+* Fixed a bug where the inability to read the lastlog file caused an error.
+  From now on that error is ignored, and the lastlog attributes of the User
+  object are set to nil.
+* Added a beta version of Admin.delete_user (Windows only).
+
+== 1.3.0 - 3-Jun-2005
+* Bug fixes for Linux.
+* Removed the version.h file - no longer needed since the Win32 version is
+  pure Ruby.
+
+== 1.2.0 - 30-Apr-2005
+* Replaced the Win32 version with a pure Ruby version that uses Win32API and
+  win32ole + WMI.
+* The LocalGroup class no longer exists in the Win32 version.  Instead, it is
+  now an attribute of a Group object.  The issue was forced by WMI.
+* The default for users and groups on Win32 systems is now local rather than
+  global.  See the documentation for why you probably don't want to iterate
+  over global accounts.
+* Corresponding doc changes and test suite changes.
+
+== 1.1.0 - 1-Apr-2005
+* Fixed bug where a segfault could occur when trying to retrieve a user or
+  group by an ID that didn't exist (Unix).
+* Added tests for intentional failures.
+* Added lastlog information tothe User class (Unix).
+* Modified the way User objects are created internally (Unix).
+* Fixed a bug in the User#shell attribute (Unix).
+
+== 1.0.0 - 25-Mar-2005
+* Initial release

data/MANIFEST

@@ -0,0 +1,14 @@
+* sys-admin.gemspec
+* CHANGES
+* MANIFEST
+* Rakefile
+* README
+* examples/groups.rb
+* examples/users.rb
+* ext/admin.c
+* ext/admin.h
+* ext/extconf.rb
+* lib/sys/admin.rb
+* test/tc_admin.rb
+* test/tc_unix.rb
+* test/tc_windows.rb

data/README

@@ -0,0 +1,185 @@
+== Description
+   The sys-admin package is a unified, cross platform replacement for the
+   Etc module.
+   
+== Installation
+   rake test (optional)
+   rake install
+
+== Synopsis
+   require 'sys/admin'
+   include Sys
+
+   # Yields a User object for each user
+   Admin.users{ |user|
+      p user
+   }
+
+   # Returns an Array of User objects
+   a = Admin.users
+
+   # Yields a Group object for each group
+   Admin.groups{ |group|
+      p group
+   }
+
+   # Returns an Array of Group objects
+   g = Admin.groups
+
+   # Get information about a particular user
+   p Admin.get_user("nobody")
+
+   # Get information about a particular group
+   p Admin.get_group("adm")
+
+== Admin
+Admin.get_login
+   Returns the user name (only) of the current login.
+
+Admin.get_user(name, host=localhost)
+Admin.get_user(uid, host=localhost, local=true)
+   Returns a User object based on +name+ or +uid+.
+   
+   Windows only: you may specify a host from which information is retrieved.
+   The default is the local machine.  You may also specify whether to
+   retrieve a local or global account.  The default is local.
+
+Admin.get_group(name, host=localhost, local=true) 
+Admin.get_group(gid, host=localhost, local=true)
+   Returns a Group object based on +name+ or +uid+.
+   
+   Windows only: you may specify a host from which information is retrieved.
+   The default is the local machine.  You can retrieve either a global or
+   local group, depending on the value of the +local+ argument.
+
+Admin.groups(host=localhost, local=true)
+Admin.groups(host=localhost, local=true){ |group| ... }
+   In block form, yields a Group object for each user on the system.  In
+   non-block form, returns an Array of Group objects.
+
+   Windows only: you may specify a host from which information is retrieved.
+   The default is the local machine.  You can retrieve either a global or
+   local group, depending on the value of the +local+ argument.
+
+Admin.users(host=localhost, local=true)
+Admin.users(host=localhost, local=true){ |user| ... }
+   In block form, yields a User object for each user on the system.  In
+   non-block form, returns an Array of User objects.
+   
+   Windows only: you may specify a host from which information is retrieved.
+   The default is the local machine.  You can retrieve either a global or
+   local group, depending on the value of the +local+ argument.
+   
+== User class
+=== User (Windows)
+   The User class has the following attributes on MS Windows systems:
+	
+   * account_type
+   * caption
+   * description
+   * domain
+   * password
+   * full_name
+   * install_date
+   * name
+   * sid
+   * status
+   * disabled?
+   * local?
+   * lockout?
+   * password_changeable?
+   * password_expires?
+   * password_required?
+     
+=== User (Unix)
+   The User class has the following attributes on Unix systems:
+	
+   * name
+   * passwd
+   * uid
+   * gid
+   * dir
+   * shell
+   * gecos
+   * quota
+   * age
+   * class
+   * comment
+   * change
+   * expire
+
+== Group Classes
+=== Group (Windows)
+   The Group class has the following attributes on MS Windows systems:
+	
+   * caption
+   * description
+   * domain
+   * install_date
+   * name
+   * sid
+   * status
+   * gid
+   * local?
+	
+=== Group (Unix)
+   The Group class has the following attributes on Unix systems:
+	
+   * name
+   * gid
+   * members
+   * passwd
+
+== Error Classes
+Admin::Error < StandardError
+   Raised if anything goes wrong with any of the above methods.
+
+== Developer's Notes
+=== MS Windows
+   The Windows version now uses a win32ole + WMI approach to getting
+   information.  This means that the WMI service must be running on the
+   target machine in order to work (which it is, by default).
+	
+   Note that, by default, local user and group information is retrieved
+   instead of global.  You probably do NOT want to iterate over global users
+   or groups because there can be quite a few on your domain.
+   
+=== UNIX
+   The underlying implementation is similar to core Ruby's Etc implementation.
+   But, in addition to the different interface, I use the re-entrant version
+   of the appropriate functions when available.
+
+== Future Plans
+   Add the following methods for UNIX:
+
+   * Admin.add_local_user
+   * Admin.config_local_user
+   * Admin.delete_local_user
+   * Admin.add_global_user
+   * Admin.config_global_user
+   * Admin.delete_global_user
+   
+   * Admin.add_local_group
+   * Admin.config_local_group
+   * Admin.delete_local_group
+   * Admin.add_global_group
+   * Admin.config_global_group
+   * Admin.delete_global_group
+
+   Make the User and Group objects comparable.
+
+== Known Bugs
+   None that I'm aware of. If you find any, please log them on the project
+   page at http://www.rubyforge.org/projects/sysutils.
+
+== License
+   Ruby's
+
+== Copyright
+   (C) 2005-2008, Daniel J. Berger
+   All Rights Reserved
+
+== Author
+   Daniel J. Berger
+   djberg96 at nospam at gmail dot com
+   IRC nickname: imperator/mok/rubyhacker1 (freenode)

data/Rakefile

@@ -0,0 +1,56 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rbconfig'
+include Config
+
+desc "Clean the build files for the sys-admin source for UNIX systems"
+task :clean do
+   Dir.chdir('ext') do
+      unless RUBY_PLATFORM.match('mswin')
+         build_file = 'admin.' + Config::CONFIG['DLEXT']
+         sh 'make distclean' if File.exists?(build_file)
+         File.delete("sys/#{build_file}") if File.exists?("sys/#{build_file}")
+      end
+   end
+end
+
+desc "Build the sys-admin package on UNIX systems (but don't install it)"
+task :build => [:clean] do
+   Dir.chdir('ext') do
+      unless RUBY_PLATFORM.match('mswin')
+         ruby 'extconf.rb'
+         sh 'make'
+         build_file = 'admin.' + Config::CONFIG['DLEXT']
+         FileUtils.cp(build_file, 'sys')
+      end
+   end
+end
+
+if RUBY_PLATFORM.match('mswin')
+   desc "Install the sys-admin package for MS Windows"
+   task :install do
+      install_dir = File.join(CONFIG['sitelibdir'], 'sys')
+      Dir.mkdir(install_dir) unless File.exists?(install_dir)
+      FileUtils.cp('lib/sys/admin.rb', install_dir, :verbose => true)
+   end
+else
+   desc "Install the sys-admin package for Unix platforms"
+   task :install => [:build] do
+      Dir.chdir('ext') do
+         sh 'make install'
+      end
+   end
+end
+
+desc "Run the test suite"
+Rake::TestTask.new("test") do |t|
+   if RUBY_PLATFORM.match('mswin')
+      t.libs << 'lib'
+   else
+      task :test => :build
+      t.libs << 'ext'
+      t.libs.delete('lib')
+   end
+   t.test_files = FileList['test/tc_admin.rb']
+end

data/doc/sys-admin-unix.txt

@@ -0,0 +1,164 @@
+= Description
+A unified, cross-platform replacement for the Etc module that allows you to
+get information about users and groups.
+
+= Synopsis
+   require 'sys/admin'
+   include Sys
+
+   Admin.get_login           # -> 'djberge'
+   Admin.get_user('djberge') # -> Admin::User object
+   Admin.get_group(501)      # -> Admin::Group object
+
+   # Iterate over all users
+   Admin.users do |usr|
+      p usr
+   end
+
+   # Iterate over all groups
+   Admin.groups do |grp|
+      p grp
+   end
+
+= Constants
+
+= Class Methods
+== Sys::Admin
+Admin.get_group(name)
+Admin.get_group(gid)
+   Returns a Group object for the given name or gid. Raises an Admin::Error
+   if a group cannot be found for that name or GID.
+
+Admin.get_login
+   Returns the login for the process. If this is called from a process that
+   has no controlling terminal, then it resorts to returning the "LOGNAME"
+   or "USER" environment variable. If neither of those is defined, then nil
+   is returned.
+
+   Note that this method will probably return the real user login, but may
+   return the effective user login. YMMV depending on your platform and how
+   the program is run.
+
+Admin.get_user(name)
+Admin.get_user(uid)
+   Returns a User object for the given name or uid. Raises an Admin::Error if
+   a user cannot be found for that name or user ID.
+
+Admin.groups
+Admin.groups{ |grp| ... }
+   In block form, yields a Group object for each group on the system. In
+   non-block form, returns an Array of Group objects.
+
+Admin.users
+Admin.users{ |grp| ... }
+   In block form, yields a User object for each group on the system. In
+   non-block form, returns an Array of User objects.
+
+== Sys::Admin::Group
+Group.new
+Group.new{ |grp| ... }
+   Creates and returns a Group object, which encapsulates the information
+   typically found within an /etc/group entry, i.e. a struct group. If a
+   block is provided, yields the object back to the block.
+
+   At the moment this is only useful for MS Windows.
+
+== Sys::Admin::User
+User.new
+User.new{ |usr| ... }
+   Creates and returns a User object, which encapsulates the information
+   typically found within an /etc/passwd entry, i.e. a struct passwd. If a
+   block is provided, yields the object back to the block.
+
+   At the moment this is only useful for MS Windows.
+
+= Instance Methods
+== Sys::Admin::Group
+Group#gid
+   The group id.
+
+Group#members
+   An array of users that are members of the group.
+
+Group#name
+   The name of the group.
+
+Group#passwd
+   The group password, if any.
+
+== Sys::Admin::User
+User#age
+   Used in the past for password aging. Deprecated in favor of /etc/shadow.
+
+User#change
+   Next date a password change will be needed.
+
+User#class
+   The user's access class.
+
+User#comment
+   Another comment field. Rarely used.
+
+User#dir
+   The absolute pathname of the user's home directory.
+
+User#expire
+   Account expiration date.
+
+User#gecos
+   A comment field. Rarely used.
+
+User#gid
+   The user's primary group id.
+
+User#login_device
+   The name of the terminal device the user last logged on with.
+
+User#login_host
+   The hostname from which the user last logged in.
+
+User#login_time
+   The last time the user logged in.
+
+User#name
+   The user name associated with the account.
+
+User#passwd
+   The user's encrypted password. Deprecated in favor of /etc/shadow.
+
+User#quota
+   The user's alloted amount of disk space.
+
+User#shell
+   The user's login shell.
+
+User#uid
+   The user's user id.
+
+== Notes
+   Not all platforms support all of the User members. The only ones that are
+   supported on all platforms are name, uid, gid, dir and shell. The rest
+   will simply return nil if they aren't supported.
+   
+== Known Bugs
+   None that I am aware of. Please log any bugs you find on the project
+   website at http://www.rubyforge.org/projects/sysutils.
+
+== License
+   Ruby's
+
+== Copyright
+   Copyright 2002-2007, Daniel J. Berger
+
+   All Rights Reserved. This module is free software. It may be used,
+   redistributed and/or modified under the same terms as Ruby itself.
+
+== 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)