sys-admin 1.4.0 → 1.4.1

data/CHANGES

@@ -1,3 +1,9 @@
+== 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

data/MANIFEST

@@ -2,6 +2,7 @@
 * sys-admin.gemspec
 * CHANGES
 * MANIFEST
+* Rakefile
 * README
 
 * examples/groups.rb

data/README

@@ -3,15 +3,8 @@
    Etc module.
    
 == Installation
-=== Windows
-   ruby tc_admin.rb # optional (in the 'test' directory)
-   ruby install.rb
-	
-=== Unix
-   ruby extconf.rb (in the 'ext' directory)
-   make
-   ruby tc_admin.rb # optional (in the 'test' directory)
-   make install
+   rake test (optional)
+   rake install
 
 == Synopsis
    require 'sys/admin'

data/Rakefile

@@ -0,0 +1,53 @@
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+
+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')
+         FileUtils.rm_rf('sys') if File.exists?('sys')
+         build_file = 'admin.' + Config::CONFIG['DLEXT']
+         sh 'make distclean' if File.exists?(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']
+         Dir.mkdir('sys') unless File.exists?('sys')
+         FileUtils.cp(build_file, 'sys')
+      end
+   end
+end
+
+if RUBY_PLATFORM.match('mswin')
+   desc "Install the sys-admin package"
+   task :install do
+      sh 'ruby install.rb'
+   end
+else
+   desc "Install the sys-admin package"
+   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/ext/admin.c

@@ -6,8 +6,10 @@
  *    User.new
  *    User.new{ |user| ... } 
  *
- * Creates and returns a User object.  If a block is provided, yields the
- * object back to the block.
+ * 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.
  */
 static VALUE user_init(VALUE self){
    if(rb_block_given_p())
@@ -21,8 +23,10 @@ static VALUE user_init(VALUE self){
  *    Group.new
  *    Group.new{ |user| ... } 
  *
- * Creates and returns a Group object.  If a block is provided, yields the
- * object back to the block.
+ * 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.
  */
 static VALUE group_init(VALUE self){
    if(rb_block_given_p())
@@ -43,8 +47,8 @@ static VALUE group_init(VALUE self){
  * Developer's Note:
  * 
  * Uses the (POSIX) reentrant version of getlogin_r() if supported.  Otherwise
- * it resorts to the standard getlogin function.  If that fails, it resorts to
- * cuserid().  If that fails, it resorts to getenv("USER").  If that fails,
+ * it resorts to the standard getlogin() function. If that fails, it resorts
+ * to cuserid(). If that fails, it resorts to getenv("USER"). If that fails,
  * then nil is returned.
  */
 static VALUE admin_get_login(VALUE klass){
@@ -77,7 +81,7 @@ static VALUE admin_get_login(VALUE klass){
  *    Admin.get_user(name)
  *    Admin.get_user(uid)
  * 
- * Returns a User object for the given +name+ or +uid+.  Raises an AdminError
+ * Returns a User object for the given +name+ or +uid+. Raises an AdminError
  * if a user cannot be found for that name or user ID.
  */
 static VALUE admin_get_user(VALUE klass, VALUE v_value){
@@ -95,7 +99,7 @@ static VALUE admin_get_user(VALUE klass, VALUE v_value){
  *    Admin.get_group(name)
  *    Admin.get_group(gid)
  * 
- * Returns a Group object for the given +name+ or +gid+.  Raises an AdminError
+ * Returns a Group object for the given +name+ or +gid+. Raises an AdminError
  * if a group cannot be found for that name or GID.
  *
  *--
@@ -120,7 +124,7 @@ static VALUE admin_get_group(VALUE klass, VALUE v_value){
  *    Admin.groups
  *    Admin.groups{ |group| ... }
  *
- * In block form, yields a Group object for each group on the system.  In
+ * In block form, yields a Group object for each group on the system. In
  * non-block form, returns an Array of Group objects.
  */
 static VALUE admin_groups(VALUE klass){
@@ -171,7 +175,7 @@ static VALUE admin_groups(VALUE klass){
  *    Admin.users
  *    Admin.users{ |user| ... }
  *
- * In block form, yields a User object for each user on the system.  In
+ * In block form, yields a User object for each user on the system. In
  * non-block form, returns an Array of User objects.
  */
 static VALUE admin_users(VALUE klass){
@@ -226,11 +230,19 @@ static VALUE admin_users(VALUE klass){
 void Init_admin(){
    VALUE mSys, cAdmin;
 
-   /* Module and class definitions */
-   mSys   = rb_define_module("Sys");
+   /* The Sys module is used primarily as a namespace for Sys::Admin */
+   mSys = rb_define_module("Sys");
+
+   /* A unified, cross platform replacement for the Etc module. */
    cAdmin = rb_define_class_under(mSys, "Admin", rb_cObject);
-   cUser  = rb_define_class_under(mSys, "User",  rb_cObject);
+
+   /* Encapsulates information typically found in /etc/passwd */
+   cUser = rb_define_class_under(mSys, "User",  rb_cObject);
+
+   /* Encapsulates information typically found in /etc/group */
    cGroup = rb_define_class_under(mSys, "Group", rb_cObject);
+
+   /* Error raised if any of the Sys::Admin methods fail */
    cAdminError = rb_define_class_under(mSys, "AdminError", rb_eStandardError);
 
    /* Class Methods */
@@ -245,29 +257,71 @@ void Init_admin(){
    rb_define_method(cGroup,"initialize", group_init, 0);
 
    /* User Attributes */
+
+   /* The user name associated with the account */
    rb_define_attr(cUser, "name", 1, 1);
+
+   /* The user's encrypted password. Deprecated in favor of /etc/shadow */
    rb_define_attr(cUser, "passwd", 1, 1);
+
+   /* The user's user ID */
    rb_define_attr(cUser, "uid", 1, 1);
+
+   /* The user's primary group ID */
    rb_define_attr(cUser, "gid", 1, 1);
+
+   /* The absolute pathname of the user's home directory */
    rb_define_attr(cUser, "dir", 1, 1);
+
+   /* The user's login shell */
    rb_define_attr(cUser, "shell", 1, 1);
+
+   /* A comment field. Rarely used. */
    rb_define_attr(cUser, "gecos", 1, 1);
+
+   /* The user's alloted amount of disk space */
    rb_define_attr(cUser, "quota", 1, 1);
+
+   /* Used in the past for password aging. Deprecated in favor of /etc/shadow */
    rb_define_attr(cUser, "age", 1, 1);
+
+   /* The user's access class */
    rb_define_attr(cUser, "class", 1, 1);
+
+   /* Another comment field. Rarely used. */
    rb_define_attr(cUser, "comment", 1, 1);
+
+   /* Account expiration date */
    rb_define_attr(cUser, "expire", 1, 1);
+
+   /* Next data a password change will be needed */
    rb_define_attr(cUser, "change", 1, 1);
+
+   /* The last time the user logged in */
    rb_define_attr(cUser, "login_time", 1, 0);
+
+   /* The name of the terminal device the user last logged on with */
    rb_define_attr(cUser, "login_device", 1, 0);
+
+   /* The hostname from which the user last logged in */
    rb_define_attr(cUser, "login_host", 1, 0);
 
    /* Group Attributes */
+
+   /* The name of the group */
    rb_define_attr(cGroup, "name", 1, 1);
+
+   /* The group's group ID */
    rb_define_attr(cGroup, "gid", 1, 1);
+
+   /* An array of users that are members of the group */
    rb_define_attr(cGroup, "members", 1, 1);
+
+   /* The group password, if any. */
    rb_define_attr(cGroup, "passwd", 1, 1);
 
    /* Constants */
+
+   /* 1.4.1: The version of this package */
    rb_define_const(cAdmin, "VERSION", rb_str_new2(SYS_ADMIN_VERSION));
 }

data/ext/admin.h

@@ -8,7 +8,7 @@
 #include <errno.h>
 #include <string.h>
 
-#define SYS_ADMIN_VERSION "1.4.0"
+#define SYS_ADMIN_VERSION "1.4.1"
 
 #ifdef HAVE_LASTLOG_H
 #include <lastlog.h>
@@ -20,17 +20,27 @@
 #define _POSIX_LOGIN_NAME_MAX 9
 #endif
 
+/* OS X returns -1 on this for some reason, so check for it */
+#if defined(__MACH__) || defined(__APPLE__)
+#define USER_BUF_SIZE 1024
+#else
 #ifdef _SC_GETPW_R_SIZE_MAX
 #define USER_BUF_SIZE (sysconf(_SC_GETPW_R_SIZE_MAX))
 #else
 #define USER_BUF_SIZE 1024
 #endif
+#endif
 
+/* OS X returns -1 on this for some reason, so check for it */
+#if defined(__MACH__) || defined(__APPLE__)
+#define GROUP_BUF_SIZE 7296
+#else
 #ifdef _SC_GETGR_R_SIZE_MAX
 #define GROUP_BUF_SIZE (sysconf(_SC_GETGR_R_SIZE_MAX))
 #else
 #define GROUP_BUF_SIZE 7296
 #endif
+#endif
 
 #ifndef _PATH_LASTLOG
 #define _PATH_LASTLOG "/var/adm/lastlog"
@@ -126,7 +136,7 @@ static VALUE get_group_by_num(VALUE v_gid){
    struct group* grpbuf;
 
    if(getgrgid_r(gid, &grp, buf, sizeof(buf), &grpbuf) != 0)
-      rb_raise(cAdminError, "%s", strerror(errno));
+      rb_raise(cAdminError, "getgrgid_r() failed: %s", strerror(errno));
 
    if(!grpbuf)
       rb_raise(cAdminError, "no group found for group ID: %i", gid);
@@ -172,7 +182,7 @@ static VALUE get_group_by_name(VALUE v_name){
 
    v_group = get_group(grp);
 #else
-   rb_raise(rb_eNotImpError,"get_group is not supported on this platform");
+   rb_raise(rb_eNotImpError, "get_group is not supported on this platform");
 #endif
 
    return v_group;
@@ -332,11 +342,12 @@ void get_user_from_value(VALUE v_user, struct passwd* pwd){
 static VALUE get_group(struct group* g){
    VALUE v_group = rb_funcall(cGroup,rb_intern("new"),0,0);
    VALUE v_array = rb_ary_new();
+   char **my_gr_mem = g->gr_mem;
 
    /* Return the members as an Array of Strings */
-   while(*g->gr_mem){
-      rb_ary_push(v_array, rb_str_new2(*g->gr_mem));
-      g->gr_mem++;
+   while(*my_gr_mem){
+      rb_ary_push(v_array, rb_str_new2(*my_gr_mem));
+      my_gr_mem++;
    }
 
    rb_iv_set(v_group, "@name", rb_str_new2(g->gr_name));

data/test/tc_unix.rb

@@ -1,18 +1,9 @@
 ###############################################################################
 # tc_unix.rb
 #
-# Test suite for the Unix version of sys-admin.
+# Test suite for the Unix version of sys-admin. This test should be run
+# via the 'rake test' task.
 ###############################################################################
-base = File.basename(Dir.pwd)
-
-if base == "test" || base =~ /sys-admin.*/
-   require "fileutils"
-   Dir.chdir("..") if base == "test"
-   Dir.mkdir("sys") unless File.exists?("sys")
-   FileUtils.cp("ext/admin.so", "sys") if File.exists?("ext/admin.so")
-   $LOAD_PATH.unshift(Dir.pwd)
-end
-
 require 'test/unit'
 require 'sys/admin'
 include Sys
@@ -26,7 +17,7 @@ class TC_Sys_Admin_Unix < Test::Unit::TestCase
    end
 
    def test_version
-      assert_equal("1.4.0", Admin::VERSION)
+      assert_equal("1.4.1", Admin::VERSION)
    end
 
    def test_get_login

data/test/tc_windows.rb

@@ -4,18 +4,9 @@
 # Test suite for the Win32 version of sys-admin.  Note that some of the tests
 # are numbered to ensure a certain order.  That way I can add test users
 # before configuring or deleting them.
+# 
+# It is assumed that this test will be run via the 'rake test' task.
 ###############################################################################
-base = File.basename(Dir.pwd)
-
-if base == "test" || base =~ /sys-admin.*/
-   require "ftools"
-   Dir.chdir("..") if base == "test"
-   Dir.mkdir("sys") unless File.exists?("sys")
-   File.copy("lib/sys/admin.rb", "sys/admin.rb")
-   $LOAD_PATH.unshift(Dir.pwd)
-   Dir.chdir("test") rescue nil
-end
-
 require "test/unit"
 require "sys/admin"
 require "socket"
@@ -33,7 +24,7 @@ class TC_Sys_Admin_Win32 < Test::Unit::TestCase
    end
 
    def test_version
-      assert_equal("1.4.0", Admin::VERSION)
+      assert_equal("1.4.1", Admin::VERSION)
    end
    
    def test_01_add_local_user

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification 
-rubygems_version: 0.9.0
+rubygems_version: 0.9.2
 specification_version: 1
 name: sys-admin
 version: !ruby/object:Gem::Version 
-  version: 1.4.0
-date: 2007-01-20 00:00:00 -07:00
+  version: 1.4.1
+date: 2007-03-22 00:00:00 -06:00
 summary: A unified, cross platform replacement for the "etc" package.
 require_paths: 
 - lib
@@ -31,12 +31,13 @@ authors:
 files: 
 - examples/groups.rb
 - examples/users.rb
+- test/tc_admin.rb
 - test/tc_unix.rb
 - test/tc_windows.rb
-- test/tc_admin.rb
-- README
 - CHANGES
 - MANIFEST
+- README
+- Rakefile
 - ext/extconf.rb
 - ext/admin.c
 - ext/admin.h