sys-admin 1.3.1

data/CHANGES

@@ -0,0 +1,31 @@
+== 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,17 @@
+extconf.rb
+install.rb
+sys-admin.gemspec
+CHANGES
+MANIFEST
+README
+
+examples/groups.rb
+examples/users.rb
+
+lib/sys/unix.c
+lib/sys/unix.h
+lib/sys/win32.rb
+
+test/tc_admin.rb
+test/tc_unix.rb
+test/tc_win32.rb

data/README

@@ -0,0 +1,174 @@
+== Description
+   The sys-admin package is a unified, cross platform replacement for the
+   Etc module.
+   
+== Installation
+=== Win32
+	ruby test\tc_admin.rb # optional
+	ruby install.rb
+	
+=== Unix
+   ruby extconf.rb
+   nmake
+   ruby test\tc_admin.rb # optional
+   nmake site-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+.
+   
+   Win32 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+.
+   
+   Win32 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.
+
+   Win32 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.
+   
+   Win32 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:
+	
+   * 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
+   * expire
+
+== Group Classes
+=== Group (Win32)
+	The Group class has the following attributes on Win32 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
+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).
+	
+	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.
+
+== Future Plans
+   The following methods will be added for both platforms:
+
+   * Admin.add_user
+   * Admin.config_user
+   * Admin.delete_user
+
+== 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, Daniel J. Berger
+   All Rights Reserved
+
+== Author
+   Daniel J. Berger
+   djberg96@yahoo.com
+   IRC nickname: imperator/mok/rubyhacker1

data/examples/groups.rb

@@ -0,0 +1,39 @@
+###########################################################################
+# groups.rb
+#
+# Sample script to demonstrate some of the various group methods.  Alter
+# as you see fit.
+###########################################################################
+base = File.basename(Dir.pwd)
+
+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")
+   else
+      File.copy("admin.so","sys") if File.exists?("admin.so")
+   end
+   $LOAD_PATH.unshift(Dir.pwd)
+end
+
+require "pp"
+require "sys/admin"
+include Sys
+
+if File::ALT_SEPARATOR
+   pp Admin.get_group("guests")
+   pp Admin.get_group(513)
+else
+   pp Admin.get_group("adm")
+   pp Admin.get_group(7)
+end
+
+Admin.groups{ |g|
+   pp g
+   puts
+}
+
+# This should raise an error
+Admin.get_group("fofofofof")

data/examples/users.rb

@@ -0,0 +1,35 @@
+###########################################################################
+# users.rb
+#
+# Sample script to demonstrate some of the various user methods.  Alter
+# as you see fit.
+###########################################################################
+base = File.basename(Dir.pwd)
+
+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")
+   else
+      File.copy("admin.so","sys") if File.exists?("admin.so")
+   end
+   $LOAD_PATH.unshift(Dir.pwd)
+end
+
+require "pp"
+require "sys/admin"
+include Sys
+
+user = Admin.get_login
+
+puts "User: #{user}"
+
+Admin.users{ |u|
+   pp u
+   puts
+}
+
+pp Admin.get_user(user)
+pp Admin.get_user(501)

data/extconf.rb

@@ -0,0 +1,62 @@
+require "mkmf"
+require "ftools"
+
+if PLATFORM.match('mswin')
+   STDERR.puts "Use the install.rb file on Win32 systems."
+   STDERR.puts "Exiting.  The sys-admin package was NOT installed."
+   exit
+else
+   File.move("lib/sys/win32.rb", "lib/sys/win32.orig") rescue nil # Don't install
+
+   have_func("getlogin_r")
+   have_func("getlogin")
+   have_func("getenv")
+   
+   have_func("cuserid")
+   
+   have_func("getpwuid_r")
+   have_func("getpwuid")
+   have_func("getpwnam_r")
+   have_func("getpwnam")
+   have_func("getpwent_r")
+   have_func("getpwent")
+   
+   have_func("getgrgid_r")
+   have_func("getgrgid")
+   have_func("getgrnam_r")
+   have_func("getgrnam")
+   have_func("getgrent_r")
+   have_func("getgrent")
+   
+   have_struct_member("struct passwd", "pw_gecos", "pwd.h")
+   have_struct_member("struct passwd", "pw_change", "pwd.h")
+   have_struct_member("struct passwd", "pw_quota", "pwd.h")
+   have_struct_member("struct passwd", "pw_age", "pwd.h")
+   have_struct_member("struct passwd", "pw_class", "pwd.h")
+   have_struct_member("struct passwd", "pw_comment", "pwd.h")
+   have_struct_member("struct passwd", "pw_expire", "pwd.h")
+   have_struct_member("struct passwd", "pw_passwd", "pwd.h")
+   
+   have_struct_member("struct group", "gr_passwd", "grp.h")
+
+   utmp    = have_header("utmp.h")
+   lastlog = have_header("lastlog.h")
+
+   if utmp || lastlog
+      have_struct_member(
+         "struct lastlog",
+         "ll_time",
+         ["utmp.h", "time.h", "lastlog.h"]
+      )
+   end
+
+   $CFLAGS += " -D_POSIX_PTHREAD_SEMANTICS"
+   if PLATFORM.match("linux")
+      $CFLAGS += " -D_GNU_SOURCE -D_REENTRANT"
+   end
+
+   File.copy("lib/sys/unix.c", "admin.c")
+   File.copy("lib/sys/unix.h", "admin.h")
+end
+
+create_makefile("sys/admin")

data/lib/sys/unix.c

@@ -0,0 +1,283 @@
+#include "ruby.h"
+#include "admin.h"
+
+/*
+ * call-seq:
+ *    User.new
+ *    User.new{ |user| ... } 
+ *
+ * Creates and returns a User object.  If a block is provided, yields the
+ * object back to the block.
+ */
+static VALUE user_init(VALUE self){
+   if(rb_block_given_p())
+      rb_yield(self);
+
+   return self;
+}
+
+/*
+ * call-seq:
+ *    Group.new
+ *    Group.new{ |user| ... } 
+ *
+ * Creates and returns a Group object.  If a block is provided, yields the
+ * object back to the block.
+ */
+static VALUE group_init(VALUE self){
+   if(rb_block_given_p())
+      rb_yield(self);
+
+   return self;
+}
+
+/*
+ * call-seq:
+ *    Sys::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 "USER"
+ * environment variable.  If that still isn't defined, nil is returned.
+ *
+ *--
+ * 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,
+ * then nil is returned.
+ */
+static VALUE admin_get_login(VALUE klass){
+   char login[_POSIX_LOGIN_NAME_MAX];
+   VALUE rbLogin = Qnil;
+
+#ifdef HAVE_GETLOGIN_R
+   getlogin_r(login,sizeof(login));
+#elif HAVE_GETLOGIN
+   strcpy(login,getlogin());
+#endif
+
+#ifdef HAVE_CUSERID
+   if(!login)
+      cuserid(login);
+#endif
+
+#ifdef HAVE_GETENV
+   if(!login)
+      strcpy(login,getenv("USER"));
+#endif
+
+   if(login)
+      rbLogin = rb_str_new2(login);
+
+   return rbLogin;
+}
+
+/* call-seq:
+ *    Admin.get_user(name)
+ *    Admin.get_user(uid)
+ * 
+ * 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;
+
+   if(FIXNUM_P(rbVal)){
+      rbUser = get_user_by_num(rbVal);
+   }
+   else{
+      rbUser = get_user_by_name(rbVal);
+   }
+
+   return rbUser;
+}
+
+/* call-seq:
+ *    Admin.get_group(name)
+ *    Admin.get_group(gid)
+ * 
+ * Returns a Group object for the given +name+ or +gid+.  Raises an AdminError
+ * if a group cannot be found for that name or GID.
+ *
+ *--
+ * Developer's Note:
+ * 
+ * I generally oppose method overloading like this, but for this method, and
+ * 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;
+
+   if(FIXNUM_P(rbVal)){
+      rbGroup = get_group_by_num(rbVal);
+   }
+   else{
+      rbGroup = get_group_by_name(rbVal);
+   }
+
+   return rbGroup;
+}
+
+/* call-seq:
+ *    Admin.groups
+ *    Admin.groups{ |group| ... }
+ *
+ * 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){
+   VALUE rbArray = Qnil;
+
+   if(!rb_block_given_p())
+      rbArray = rb_ary_new();
+
+   setgrent();
+
+#ifdef HAVE_GETGRENT_R
+   struct group grp;
+   char buf[GROUP_BUF_SIZE];
+#ifdef _GNU_SOURCE
+   struct group* grp_p;
+   while(!getgrent_r(&grp, buf, GROUP_BUF_SIZE, &grp_p)){
+      if(rb_block_given_p()){
+         rb_yield(get_group(grp_p));
+      }
+      else{
+         rb_ary_push(rbArray, get_group(grp_p));
+      }
+   }
+#else
+   while(getgrent_r(&grp, buf, GROUP_BUF_SIZE) != NULL){
+      if(rb_block_given_p()){
+         rb_yield(get_group(&grp));
+      }
+      else{
+         rb_ary_push(rbArray, get_group(&grp));
+      }
+   }
+#endif
+#elif HAVE_GETGRENT
+   struct group* grp;
+   while((grp = getgrent()) != NULL){
+      if(rb_block_given_p()){
+         rb_yield(get_group(grp));
+      }
+      else{
+         rb_ary_push(rbArray, get_group(grp));
+      }
+   }
+#else
+   rb_raise(rb_eNotImpError, "groups method not supported on this platform");
+#endif
+
+   endgrent();
+   return rbArray;
+}
+
+/* call-seq:
+ *    Admin.users
+ *    Admin.users{ |user| ... }
+ *
+ * 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){
+   VALUE rbArray = Qnil;
+
+   if(!rb_block_given_p())
+      rbArray = rb_ary_new();
+
+   setpwent();
+
+#ifdef HAVE_GETPWENT_R
+   struct passwd pwd;
+   char buf[USER_BUF_SIZE];
+
+#ifdef _GNU_SOURCE
+   struct passwd* pwd_p;
+   while(!getpwent_r(&pwd, buf, USER_BUF_SIZE, &pwd_p)){
+      if(rb_block_given_p()){
+         rb_yield(get_user(pwd_p));
+      }
+      else{
+         rb_ary_push(rbArray, get_user(pwd_p));
+      }
+   }
+#else   
+   while(getpwent_r(&pwd, buf, USER_BUF_SIZE) != NULL){
+      if(rb_block_given_p()){
+         rb_yield(get_user(&pwd));
+      }
+      else{
+         rb_ary_push(rbArray, get_user(&pwd));
+      }
+   }
+#endif
+#elif HAVE_GETPWENT
+   struct passwd* pwd;
+
+   while((pwd = getpwent()) != NULL){
+      if(rb_block_given_p()){
+         rb_yield(get_user(pwd));
+      }
+      else{
+         rb_ary_push(rbArray, get_user(pwd));
+      }
+   }
+#else
+   rb_raise(rb_eNotImpError, "users method not supported on this platform");
+#endif
+
+   endpwent();
+   return rbArray;
+}
+
+void Init_admin(){
+   VALUE mSys, cAdmin;
+
+   /* Module and class definitions */
+   mSys   = rb_define_module("Sys");
+   cAdmin = rb_define_class_under(mSys, "Admin", rb_cObject);
+   cUser  = rb_define_class_under(mSys, "User",  rb_cObject);
+   cGroup = rb_define_class_under(mSys, "Group", rb_cObject);
+   cAdminError = rb_define_class_under(mSys, "AdminError", rb_eStandardError);
+
+   /* Class Methods */
+   rb_define_singleton_method(cAdmin, "get_login", admin_get_login, 0);
+   rb_define_singleton_method(cAdmin, "get_user", admin_get_user, 1);
+   rb_define_singleton_method(cAdmin, "get_group", admin_get_group, 1);
+   rb_define_singleton_method(cAdmin, "users", admin_users, 0);
+   rb_define_singleton_method(cAdmin, "groups", admin_groups, 0);
+
+   /* Instance Methods */
+   rb_define_method(cUser, "initialize", user_init, 0);
+   rb_define_method(cGroup,"initialize", group_init, 0);
+
+   /* User Attributes */
+   rb_define_attr(cUser, "name", 1, 1);
+   rb_define_attr(cUser, "passwd", 1, 1);
+   rb_define_attr(cUser, "uid", 1, 1);
+   rb_define_attr(cUser, "gid", 1, 1);
+   rb_define_attr(cUser, "dir", 1, 1);
+   rb_define_attr(cUser, "shell", 1, 1);
+   rb_define_attr(cUser, "gecos", 1, 1);
+   rb_define_attr(cUser, "quota", 1, 1);
+   rb_define_attr(cUser, "age", 1, 1);
+   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, "login_time", 1, 0);
+   rb_define_attr(cUser, "login_device", 1, 0);
+   rb_define_attr(cUser, "login_host", 1, 0);
+
+   /* Group Attributes */
+   rb_define_attr(cGroup, "name", 1, 1);
+   rb_define_attr(cGroup, "gid", 1, 1);
+   rb_define_attr(cGroup, "members", 1, 1);
+   rb_define_attr(cGroup, "passwd", 1, 1);
+
+   /* Constants */
+   rb_define_const(cAdmin, "VERSION", rb_str_new2(SYS_ADMIN_VERSION));
+}