sys-admin 1.5.3-x86-mingw32

data/CHANGES

@@ -0,0 +1,112 @@
+== 1.5.3 - 6-Oct-2010
+* Refactored the Rakefile. The old installation tasks have been replaced
+  with gem build and install tasks. In addition, the platform handling has
+  been updated for MS Windows.
+* Portions of the gemspec have been moved into the Rakefile gem tasks.
+* Deploying the mingw gem by default for MS Windows now.
+
+== 1.5.2 - 2-Aug-2009
+* Now compatible with Ruby 1.9.x.
+* Added test-unit as a development dependency.
+
+== 1.5.1 - 23-Jul-2009
+* Added the User#dir attribute. This attribute contains a user's home
+  directory if set, or nil if it isn't.
+* User objects returned by the Admin.users method now include the uid.
+  Previously only the Admin.get_user method set it.
+* Added win32-security as a dependency.
+* Changed license to Artistic 2.0.
+
+== 1.5.0 - 29-Mar-2009
+* INTERFACE CHANGE (WINDOWS ONLY): The interface for MS Windows has undergone
+  a radical change. Most methods now accept a hash of options that are
+  passed directly to the underlying WMI class. Please see the documentation
+  for details.
+* Now works on various BSD flavors.
+* Added the User#groups method. This returns an array of groups that the
+  user belongs to. Suggestion inspired by Gonzalo Garramuno.
+* Added the Group#members method. The returns an array of users that the
+  group contains.
+* Changed User#class to User#access_class for UNIX flavors to avoid
+  conflicts with the Ruby core Object method. 
+* Added more tests and renamed the test files.
+* Removed an unnecessary function call where a platform might try to
+  get lastlog information even if the lastlog.h or utmp.h headers couldn't
+  be found.
+
+== 1.4.4 - 19-Nov-2008
+* Added the User#uid method for MS Windows (which is just the user's relative
+  identifier).
+* Now requires test-unit 2.x.
+* Some updates to the test suite to take advantage of test-unit 2.x features.
+* Some minor gemspec tweaks.
+
+== 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/test_sys_admin.rb
+* test/test_sys_admin_unix.rb
+* test/test_sys_admin_windows.rb

data/README

@@ -0,0 +1,156 @@
+== Description
+  The sys-admin library is a unified, cross platform replacement for the Etc module.
+   
+== Installation
+  gem install sys-admin
+
+== 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, options = {})
+Admin.get_user(uid, options = {})
+  Returns a User object based on +name+ or +uid+. The +options+ hash is
+  for MS Windows only, and allows you to restrict the search based on the
+  options you provide, e.g. 'domain' or 'localaccount'.
+   
+Admin.get_group(name, options = {})
+Admin.get_group(gid, options = {})
+  Returns a Group object based on +name+ or +uid+. The +options+ hash is
+  for MS Windows only, and allows you to restrict the search based on the
+  options you provide, e.g. 'domain' or 'localaccount'.
+
+Admin.groups(options = {})
+Admin.groups(options = {}){ |group| ... }
+  In block form, yields a Group object for each user on the system.  In
+  non-block form, returns an Array of Group objects.
+
+  The +options+ hash is for MS Windows only, and allows you to restrict the
+  search based on the options you provide, e.g. 'domain' or 'localaccount'.
+
+Admin.users(options = {})
+Admin.users(options = {}){ |user| ... }
+  In block form, yields a User object for each user on the system.  In
+  non-block form, returns an Array of User objects.
+   
+  The +options+ hash is for MS Windows only, and allows you to restrict the
+  search based on the options you provide, e.g. 'domain' or 'localaccount'.
+   
+== 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).
+	
+=== 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
+  Make the User and Group objects comparable.
+  Add ability to add, configure and delete users on Unix platforms.
+
+== 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
+  Artistic 2.0
+
+== Copyright
+  (C) 2005-2010, Daniel J. Berger
+  All Rights Reserved
+
+== Author
+  Daniel J. Berger

data/Rakefile

@@ -0,0 +1,74 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rbconfig'
+
+WINDOWS = Config::CONFIG['host_os'] =~ /msdos|mswin|win32|mingw|cygwin/i
+
+desc "Clean the build files for the sys-admin source for UNIX systems"
+task :clean do
+  Dir['*.gem'].each{ |f| File.delete(f) } # Remove any .gem files
+  unless WINDOWS
+    Dir.chdir('ext') do
+      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 library on UNIX systems (but don't install it)"
+task :build => [:clean] do
+  unless WINDOWS
+    Dir.chdir('ext') do
+      ruby 'extconf.rb'
+      sh 'make'
+      build_file = 'admin.' + Config::CONFIG['DLEXT']
+      FileUtils.cp(build_file, 'sys')
+    end
+  end
+end
+
+namespace :gem do
+  desc "Create a sys-admin gem file."
+  task :create => [:clean] do
+    spec = eval(IO.read('sys-admin.gemspec'))
+
+    if WINDOWS
+      spec.platform = Gem::Platform::CURRENT
+      spec.files = spec.files.reject{ |f| f.include?('ext') }
+      spec.add_dependency('win32-security', '>= 0.1.2')
+    else
+      spec.files = spec.files.reject{ |f| f.include?('lib') }
+      spec.extensions = ['ext/extconf.rb']
+      spec.extra_rdoc_files << 'ext/sys/admin.c'
+    end
+
+    Gem::Builder.new(spec).build
+  end
+
+  desc "Install the sys-admin gem."
+  task :install => [:create] do
+    gem = Dir['*.gem'].first
+    sh "gem install #{gem}"
+  end
+end
+
+desc "Run the test suite"
+Rake::TestTask.new('test') do |t|
+  if WINDOWS
+    t.libs << 'lib'
+  else
+    task :test => :build
+    t.libs << 'ext'
+    t.libs.delete('lib')
+  end
+  t.libs << 'test'
+  t.test_files = FileList['test/test_sys_admin.rb']
+end
+
+task :test do
+  Rake.application[:clean].execute
+end
+
+task :default => :test

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
+   Artistic 2.0
+
+== Copyright
+   Copyright 2002-2009, 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 library 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)