sys-admin 1.3.1 → 1.4.0

data/CHANGES

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

data/MANIFEST

@@ -1,17 +1,18 @@
-extconf.rb
-install.rb
-sys-admin.gemspec
-CHANGES
-MANIFEST
-README
+* install.rb
+* sys-admin.gemspec
+* CHANGES
+* MANIFEST
+* README
 
-examples/groups.rb
-examples/users.rb
+* examples/groups.rb
+* examples/users.rb
 
-lib/sys/unix.c
-lib/sys/unix.h
-lib/sys/win32.rb
+* ext/admin.c
+* ext/admin.h
+* ext/extconf.rb
 
-test/tc_admin.rb
-test/tc_unix.rb
-test/tc_win32.rb
+* lib/sys/win32.rb
+
+* test/tc_admin.rb
+* test/tc_unix.rb
+* test/tc_windows.rb

data/README

@@ -3,18 +3,18 @@
    Etc module.
    
 == Installation
-=== Win32
-	ruby test\tc_admin.rb # optional
-	ruby install.rb
+=== Windows
+   ruby tc_admin.rb # optional (in the 'test' directory)
+   ruby install.rb
 	
 === Unix
-   ruby extconf.rb
-   nmake
-   ruby test\tc_admin.rb # optional
-   nmake site-install
+   ruby extconf.rb (in the 'ext' directory)
+   make
+   ruby tc_admin.rb # optional (in the 'test' directory)
+   make install
 
 == Synopsis
-   require "sys/admin"
+   require 'sys/admin'
    include Sys
 
    # Yields a User object for each user
@@ -47,7 +47,7 @@ Admin.get_user(name, host=localhost)
 Admin.get_user(uid, host=localhost, local=true)
    Returns a User object based on +name+ or +uid+.
    
-   Win32 only: you may specify a host from which information is retrieved.
+   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.
 
@@ -55,7 +55,7 @@ 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+.
    
-   Win32 only: you may specify a host from which information is retrieved.
+   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.
 
@@ -64,7 +64,7 @@ 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.
 
-   Win32 only: you may specify a host from which information is retrieved.
+   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.
 
@@ -73,13 +73,13 @@ 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.
    
-   Win32 only: you may specify a host from which information is retrieved.
+   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 (Win32)
-	The User class has the following attributes on Win32 systems:
+=== User (Windows)
+   The User class has the following attributes on MS Windows systems:
 	
    * account_type
    * caption
@@ -99,7 +99,7 @@ Admin.users(host=localhost, local=true){ |user| ... }
    * password_required?
      
 === User (Unix)
-	The User class has the following attributes on Unix systems:
+   The User class has the following attributes on Unix systems:
 	
    * name
    * passwd
@@ -112,11 +112,12 @@ Admin.users(host=localhost, local=true){ |user| ... }
    * age
    * class
    * comment
+   * change
    * expire
 
 == Group Classes
-=== Group (Win32)
-	The Group class has the following attributes on Win32 systems:
+=== Group (Windows)
+   The Group class has the following attributes on MS Windows systems:
 	
    * caption
    * description
@@ -129,46 +130,61 @@ Admin.users(host=localhost, local=true){ |user| ... }
    * local?
 	
 === Group (Unix)
-	The Group class has the following attributes on Unix systems:
+   The Group class has the following attributes on Unix systems:
 	
-	* name
-	* gid
-	* members
-	* passwd
+   * name
+   * gid
+   * members
+   * passwd
 
 == Error Classes
 AdminError < StandardError
    Raised if anything goes wrong with any of the above methods.
 
 == Developer's Notes
-=== Win32
-	The Win32 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).
+=== 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.
+   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
-   The following methods will be added for both platforms:
-
-   * Admin.add_user
-   * Admin.config_user
-   * Admin.delete_user
+   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
 
 == Known Bugs
-   None that I'm aware of.  If you find any, please log them on the project
+   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, Daniel J. Berger
+   (C) 2005-2007, Daniel J. Berger
    All Rights Reserved
 
 == Author
    Daniel J. Berger
-   djberg96@yahoo.com
-   IRC nickname: imperator/mok/rubyhacker1
+   djberg96 at nospam at gmail dot com
+   IRC nickname: imperator/mok/rubyhacker1 (freenode)

data/examples/groups.rb

@@ -10,8 +10,8 @@ if base == "examples" || base =~ /sys-admin.*/
    require "ftools"
    Dir.chdir("..") if base == "examples"
    Dir.mkdir("sys") unless File.exists?("sys")
-   if File::ALT_SEPARATOR
-      File.copy("lib/sys/win32.rb", "sys/admin.rb")
+   if RUBY_PLATFORM.match("mswin")
+      File.copy("lib/sys/admin.rb", "sys/admin.rb")
    else
       File.copy("admin.so","sys") if File.exists?("admin.so")
    end
@@ -22,7 +22,7 @@ require "pp"
 require "sys/admin"
 include Sys
 
-if File::ALT_SEPARATOR
+if PLATFORM.match("mswin")
    pp Admin.get_group("guests")
    pp Admin.get_group(513)
 else

data/examples/users.rb

@@ -10,8 +10,8 @@ if base == "examples" || base =~ /sys-admin.*/
    require "ftools"
    Dir.chdir("..") if base == "examples"
    Dir.mkdir("sys") unless File.exists?("sys")
-   if File::ALT_SEPARATOR
-      File.copy("lib/sys/win32.rb", "sys/admin.rb")
+   if RUBY_PLATFORM.match("mswin")
+      File.copy("lib/sys/admin.rb", "sys/admin.rb")
    else
       File.copy("admin.so","sys") if File.exists?("admin.so")
    end
@@ -22,6 +22,23 @@ require "pp"
 require "sys/admin"
 include Sys
 
+user = User.new do |u|
+   u.name              = "Foo"
+   u.description       = "Test account"
+   u.password          = "changeme"
+   #u.lockout           = false
+   u.disabled          = true
+   #u.password_required = true
+end
+
+Admin.delete_user(u.name) rescue nil
+Admin.add_user(user)
+
+#pp Admin.get_user("Foo")
+
+#Admin.delete_user("Foo")
+
+=begin
 user = Admin.get_login
 
 puts "User: #{user}"
@@ -32,4 +49,5 @@ Admin.users{ |u|
 }
 
 pp Admin.get_user(user)
-pp Admin.get_user(501)
+pp Admin.get_user(501)
+=end

data/{lib/sys/unix.c → ext/admin.c}

@@ -49,12 +49,12 @@ static VALUE group_init(VALUE self){
  */
 static VALUE admin_get_login(VALUE klass){
    char login[_POSIX_LOGIN_NAME_MAX];
-   VALUE rbLogin = Qnil;
+   VALUE v_login = Qnil;
 
 #ifdef HAVE_GETLOGIN_R
-   getlogin_r(login,sizeof(login));
+   getlogin_r(login, sizeof(login));
 #elif HAVE_GETLOGIN
-   strcpy(login,getlogin());
+   strcpy(login, getlogin());
 #endif
 
 #ifdef HAVE_CUSERID
@@ -64,13 +64,13 @@ static VALUE admin_get_login(VALUE klass){
 
 #ifdef HAVE_GETENV
    if(!login)
-      strcpy(login,getenv("USER"));
+      strcpy(login, getenv("USER"));
 #endif
 
    if(login)
-      rbLogin = rb_str_new2(login);
+      v_login = rb_str_new2(login);
 
-   return rbLogin;
+   return v_login;
 }
 
 /* call-seq:
@@ -80,17 +80,15 @@ static VALUE admin_get_login(VALUE klass){
  * 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 rbVal){
-   VALUE rbUser;
+static VALUE admin_get_user(VALUE klass, VALUE v_value){
+   VALUE v_user;
 
-   if(FIXNUM_P(rbVal)){
-      rbUser = get_user_by_num(rbVal);
-   }
-   else{
-      rbUser = get_user_by_name(rbVal);
-   }
+   if(FIXNUM_P(v_value))
+      v_user = get_user_by_num(v_value);
+   else
+      v_user = get_user_by_name(v_value);
 
-   return rbUser;
+   return v_user;
 }
 
 /* call-seq:
@@ -107,17 +105,15 @@ static VALUE admin_get_user(VALUE klass, VALUE rbVal){
  * for only two types, I can live with it for the added convenience it
  * provides.
  */
-static VALUE admin_get_group(VALUE klass, VALUE rbVal){
-   VALUE rbGroup;
+static VALUE admin_get_group(VALUE klass, VALUE v_value){
+   VALUE v_group;
 
-   if(FIXNUM_P(rbVal)){
-      rbGroup = get_group_by_num(rbVal);
-   }
-   else{
-      rbGroup = get_group_by_name(rbVal);
-   }
+   if(FIXNUM_P(v_value))
+      v_group = get_group_by_num(v_value);
+   else
+      v_group = get_group_by_name(v_value);
 
-   return rbGroup;
+   return v_group;
 }
 
 /* call-seq:
@@ -128,10 +124,10 @@ static VALUE admin_get_group(VALUE klass, VALUE rbVal){
  * non-block form, returns an Array of Group objects.
  */
 static VALUE admin_groups(VALUE klass){
-   VALUE rbArray = Qnil;
+   VALUE v_array = Qnil;
 
    if(!rb_block_given_p())
-      rbArray = rb_ary_new();
+      v_array = rb_ary_new();
 
    setgrent();
 
@@ -141,39 +137,34 @@ static VALUE admin_groups(VALUE klass){
 #ifdef _GNU_SOURCE
    struct group* grp_p;
    while(!getgrent_r(&grp, buf, GROUP_BUF_SIZE, &grp_p)){
-      if(rb_block_given_p()){
+      if(rb_block_given_p())
          rb_yield(get_group(grp_p));
-      }
-      else{
-         rb_ary_push(rbArray, get_group(grp_p));
-      }
+      else
+         rb_ary_push(v_array, get_group(grp_p));
    }
 #else
    while(getgrent_r(&grp, buf, GROUP_BUF_SIZE) != NULL){
-      if(rb_block_given_p()){
+      if(rb_block_given_p())
          rb_yield(get_group(&grp));
-      }
-      else{
-         rb_ary_push(rbArray, get_group(&grp));
-      }
+      else
+         rb_ary_push(v_array, get_group(&grp));
    }
 #endif
 #elif HAVE_GETGRENT
    struct group* grp;
    while((grp = getgrent()) != NULL){
-      if(rb_block_given_p()){
+      if(rb_block_given_p())
          rb_yield(get_group(grp));
-      }
-      else{
-         rb_ary_push(rbArray, get_group(grp));
-      }
+      else
+         rb_ary_push(v_array, get_group(grp));
    }
 #else
    rb_raise(rb_eNotImpError, "groups method not supported on this platform");
 #endif
 
    endgrent();
-   return rbArray;
+
+   return v_array;
 }
 
 /* call-seq:
@@ -184,10 +175,10 @@ static VALUE admin_groups(VALUE klass){
  * non-block form, returns an Array of User objects.
  */
 static VALUE admin_users(VALUE klass){
-   VALUE rbArray = Qnil;
+   VALUE v_array = Qnil;
 
    if(!rb_block_given_p())
-      rbArray = rb_ary_new();
+      v_array = rb_ary_new();
 
    setpwent();
 
@@ -198,40 +189,38 @@ static VALUE admin_users(VALUE klass){
 #ifdef _GNU_SOURCE
    struct passwd* pwd_p;
    while(!getpwent_r(&pwd, buf, USER_BUF_SIZE, &pwd_p)){
-      if(rb_block_given_p()){
+      if(rb_block_given_p())
          rb_yield(get_user(pwd_p));
-      }
-      else{
-         rb_ary_push(rbArray, get_user(pwd_p));
-      }
+      else
+         rb_ary_push(v_array, get_user(pwd_p));
    }
 #else   
    while(getpwent_r(&pwd, buf, USER_BUF_SIZE) != NULL){
-      if(rb_block_given_p()){
+      if(rb_block_given_p())
          rb_yield(get_user(&pwd));
-      }
-      else{
-         rb_ary_push(rbArray, get_user(&pwd));
-      }
+      else
+         rb_ary_push(v_array, get_user(&pwd));
    }
 #endif
 #elif HAVE_GETPWENT
    struct passwd* pwd;
 
    while((pwd = getpwent()) != NULL){
-      if(rb_block_given_p()){
+      if(rb_block_given_p())
          rb_yield(get_user(pwd));
-      }
-      else{
-         rb_ary_push(rbArray, get_user(pwd));
-      }
+      else
+         rb_ary_push(v_array, get_user(pwd));
    }
 #else
    rb_raise(rb_eNotImpError, "users method not supported on this platform");
 #endif
 
    endpwent();
-   return rbArray;
+
+   if(rb_block_given_p())
+      return Qnil;
+
+   return v_array;
 }
 
 void Init_admin(){
@@ -268,6 +257,7 @@ void Init_admin(){
    rb_define_attr(cUser, "class", 1, 1);
    rb_define_attr(cUser, "comment", 1, 1);
    rb_define_attr(cUser, "expire", 1, 1);
+   rb_define_attr(cUser, "change", 1, 1);
    rb_define_attr(cUser, "login_time", 1, 0);
    rb_define_attr(cUser, "login_device", 1, 0);
    rb_define_attr(cUser, "login_host", 1, 0);