ext/etc/etc.c in etc-1.3.0 vs ext/etc/etc.c in etc-1.4.1

@@ -50,11 +50,11 @@
 #ifndef _WIN32
 char *getenv();
 #endif
 char *getlogin();
 
-#define RUBY_ETC_VERSION "1.3.0"
+#define RUBY_ETC_VERSION "1.4.1"
 
 #ifdef HAVE_RB_DEPRECATE_CONSTANT
 void rb_deprecate_constant(VALUE mod, const char *name);
 #else
 # define rb_deprecate_constant(mod,name) ((void)(mod),(void)(name))
@@ -188,11 +188,12 @@
 #endif
 
 /* call-seq:
  *	getpwuid(uid)	->  Passwd
  *
- * Returns the /etc/passwd information for the user with the given integer +uid+.
+ * Returns the <tt>/etc/passwd</tt> information for the user with the given
+ * integer +uid+.
  *
  * The information is returned as a Passwd struct.
  *
  * If +uid+ is omitted, the value from <code>Passwd[:uid]</code> is returned
  * instead.
@@ -227,12 +228,12 @@
 }
 
 /* call-seq:
  *	getpwnam(name)	->  Passwd
  *
- * Returns the /etc/passwd information for the user with specified login
- * +name+.
+ * Returns the <tt>/etc/passwd</tt> information for the user with specified
+ * login +name+.
  *
  * The information is returned as a Passwd struct.
  *
  * See the unix manpage for <code>getpwnam(3)</code> for more detail.
  *
@@ -293,11 +294,11 @@
 /* call-seq:
  *	Etc.passwd { |struct| block }	->  Passwd
  *	Etc.passwd			->  Passwd
  *
  * Provides a convenient Ruby iterator which executes a block for each entry
- * in the /etc/passwd file.
+ * in the <tt>/etc/passwd</tt> file.
  *
  * The code block is passed an Passwd struct.
  *
  * See ::getpwent above for details.
  *
@@ -328,17 +329,18 @@
 
 /* call-seq:
  *	Etc::Passwd.each { |struct| block }	->  Passwd
  *	Etc::Passwd.each			->  Enumerator
  *
- * Iterates for each entry in the /etc/passwd file if a block is given.
+ * Iterates for each entry in the <tt>/etc/passwd</tt> file if a block is
+ * given.
  *
  * If no block is given, returns the Enumerator.
  *
  * The code block is passed an Passwd struct.
  *
- * See ::getpwent above for details.
+ * See Etc.getpwent above for details.
  *
  * Example:
  *
  *     require 'etc'
  *
@@ -358,35 +360,35 @@
     each_passwd();
 #endif
     return obj;
 }
 
-/* Resets the process of reading the /etc/passwd file, so that the next call
- * to ::getpwent will return the first entry again.
+/* Resets the process of reading the <tt>/etc/passwd</tt> file, so that the
+ * next call to ::getpwent will return the first entry again.
  */
 static VALUE
 etc_setpwent(VALUE obj)
 {
 #ifdef HAVE_GETPWENT
     setpwent();
 #endif
     return Qnil;
 }
 
-/* Ends the process of scanning through the /etc/passwd file begun with
- * ::getpwent, and closes the file.
+/* Ends the process of scanning through the <tt>/etc/passwd</tt> file begun
+ * with ::getpwent, and closes the file.
  */
 static VALUE
 etc_endpwent(VALUE obj)
 {
 #ifdef HAVE_GETPWENT
     endpwent();
 #endif
     return Qnil;
 }
 
-/* Returns an entry from the /etc/passwd file.
+/* Returns an entry from the <tt>/etc/passwd</tt> file.
  *
  * The first time it is called it opens the file and returns the first entry;
  * each successive call returns the next entry, or +nil+ if the end of the file
  * has been reached.
  *
@@ -433,11 +435,11 @@
 
 /* call-seq:
  *	getgrgid(group_id)  ->	Group
  *
  * Returns information about the group with specified integer +group_id+,
- * as found in /etc/group.
+ * as found in <tt>/etc/group</tt>.
  *
  * The information is returned as a Group struct.
  *
  * See the unix manpage for <code>getgrgid(3)</code> for more detail.
  *
@@ -471,11 +473,11 @@
 
 /* call-seq:
  *	getgrnam(name)	->  Group
  *
  * Returns information about the group with specified +name+, as found in
- * /etc/group.
+ * <tt>/etc/group</tt>.
  *
  * The information is returned as a Group struct.
  *
  * See the unix manpage for <code>getgrnam(3)</code> for more detail.
  *
@@ -534,11 +536,11 @@
     rb_ensure(group_iterate, 0, group_ensure, 0);
 }
 #endif
 
 /* Provides a convenient Ruby iterator which executes a block for each entry
- * in the /etc/group file.
+ * in the <tt>/etc/group</tt> file.
  *
  * The code block is passed an Group struct.
  *
  * See ::getgrent above for details.
  *
@@ -570,11 +572,12 @@
 #ifdef HAVE_GETGRENT
 /* call-seq:
  *	Etc::Group.each { |group| block }   ->	obj
  *	Etc::Group.each			    ->	Enumerator
  *
- * Iterates for each entry in the /etc/group file if a block is given.
+ * Iterates for each entry in the <tt>/etc/group</tt> file if a block is
+ * given.
  *
  * If no block is given, returns the Enumerator.
  *
  * The code block is passed a Group struct.
  *
@@ -597,35 +600,35 @@
     each_group();
     return obj;
 }
 #endif
 
-/* Resets the process of reading the /etc/group file, so that the next call
- * to ::getgrent will return the first entry again.
+/* Resets the process of reading the <tt>/etc/group</tt> file, so that the
+ * next call to ::getgrent will return the first entry again.
  */
 static VALUE
 etc_setgrent(VALUE obj)
 {
 #ifdef HAVE_GETGRENT
     setgrent();
 #endif
     return Qnil;
 }
 
-/* Ends the process of scanning through the /etc/group file begun by
- * ::getgrent, and closes the file.
+/* Ends the process of scanning through the <tt>/etc/group</tt> file begun
+ * by ::getgrent, and closes the file.
  */
 static VALUE
 etc_endgrent(VALUE obj)
 {
 #ifdef HAVE_GETGRENT
     endgrent();
 #endif
     return Qnil;
 }
 
-/* Returns an entry from the /etc/group file.
+/* Returns an entry from the <tt>/etc/group</tt> file.
  *
  * The first time it is called it opens the file and returns the first entry;
  * each successive call returns the next entry, or +nil+ if the end of the file
  * has been reached.
  *
@@ -655,13 +658,15 @@
 #endif
 
 /*
  * Returns system configuration directory.
  *
- * This is typically "/etc", but is modified by the prefix used when Ruby was
- * compiled. For example, if Ruby is built and installed in /usr/local,
- * returns "/usr/local/etc" on other platforms than Windows.
+ * This is typically <code>"/etc"</code>, but is modified by the prefix used
+ * when Ruby was compiled. For example, if Ruby is built and installed in
+ * <tt>/usr/local</tt>, returns <code>"/usr/local/etc"</code> on other
+ * platforms than Windows.
+ *
  * On Windows, this always returns the directory provided by the system.
  */
 static VALUE
 etc_sysconfdir(VALUE obj)
 {
@@ -1065,15 +1070,16 @@
 #define etc_nprocessors rb_f_notimplement
 #endif
 
 /*
  * The Etc module provides access to information typically stored in
- * files in the /etc directory on Unix systems.
+ * files in the <tt>/etc</tt> directory on Unix systems.
  *
  * The information accessible consists of the information found in the
- * /etc/passwd and /etc/group files, plus information about the system's
- * temporary directory (/tmp) and configuration directory (/etc).
+ * <tt>/etc/passwd</tt> and <tt>/etc/group</tt> files, plus information
+ * about the system's temporary directory (<tt>/tmp</tt>) and configuration
+ * directory (<tt>/etc</tt>).
  *
  * The Etc module provides a more reliable way to access information about
  * the logged in user than environment variables such as +$USER+.
  *
  * == Example:
@@ -1094,13 +1100,13 @@
 void
 Init_etc(void)
 {
     VALUE mEtc;
 
-    #ifdef HAVE_RB_EXT_RACTOR_SAFE
-	RB_EXT_RACTOR_SAFE(true);
-    #endif
+#ifdef HAVE_RB_EXT_RACTOR_SAFE
+    RB_EXT_RACTOR_SAFE(true);
+#endif
     mEtc = rb_define_module("Etc");
     rb_define_const(mEtc, "VERSION", rb_str_new_cstr(RUBY_ETC_VERSION));
     init_constants(mEtc);
 
     rb_define_module_function(mEtc, "getlogin", etc_getlogin, 0);
@@ -1156,87 +1162,83 @@
 #ifdef HAVE_STRUCT_PASSWD_PW_EXPIRE
 				      "expire",
 #endif
 				      NULL);
 #if 0
-    /* Define-const: Passwd
+    /*
+     * Passwd is a placeholder Struct for user database on Unix systems.
      *
-     * Passwd is a Struct that contains the following members:
+     * === The struct contains the following members
      *
      * name::
      *	    contains the short login name of the user as a String.
      * passwd::
      *	    contains the encrypted password of the user as a String.
-     *	    an 'x' is returned if shadow passwords are in use. An '*' is returned
-     *      if the user cannot log in using a password.
+     *	    an <code>'x'</code> is returned if shadow passwords are in
+     *	    use. An <code>'*'</code> is returned if the user cannot
+     *	    log in using a password.
      * uid::
      *	    contains the integer user ID (uid) of the user.
      * gid::
      *	    contains the integer group ID (gid) of the user's primary group.
      * dir::
      *	    contains the path to the home directory of the user as a String.
      * shell::
      *	    contains the path to the login shell of the user as a String.
      *
-     * === The following members below are optional, and must be compiled with special flags:
+     * === The following members below are system-dependent
      *
      * gecos::
      *     contains a longer String description of the user, such as
      *	   a full name. Some Unix systems provide structured information in the
      *     gecos field, but this is system-dependent.
-     *     must be compiled with +HAVE_STRUCT_PASSWD_PW_GECOS+
      * change::
-     *     password change time(integer) must be compiled with +HAVE_STRUCT_PASSWD_PW_CHANGE+
+     *     password change time(integer).
      * quota::
-     *     quota value(integer) must be compiled with +HAVE_STRUCT_PASSWD_PW_QUOTA+
+     *     quota value(integer).
      * age::
-     *     password age(integer) must be compiled with +HAVE_STRUCT_PASSWD_PW_AGE+
+     *     password age(integer).
      * class::
-     *     user access class(string) must be compiled with +HAVE_STRUCT_PASSWD_PW_CLASS+
+     *     user access class(string).
      * comment::
-     *     comment(string) must be compiled with +HAVE_STRUCT_PASSWD_PW_COMMENT+
+     *     comment(string).
      * expire::
-     *	    account expiration time(integer) must be compiled with +HAVE_STRUCT_PASSWD_PW_EXPIRE+
+     *	    account expiration time(integer).
      */
-    rb_define_const(mEtc, "Passwd", sPasswd);
+    sPasswd = rb_define_class_under(mEtc, "Passwd", rb_cStruct);
 #endif
-    rb_define_const(rb_cStruct, "Passwd", sPasswd); /* deprecated name */
-    rb_deprecate_constant(rb_cStruct, "Passwd");
     rb_extend_object(sPasswd, rb_mEnumerable);
     rb_define_singleton_method(sPasswd, "each", etc_each_passwd, 0);
+
 #ifdef HAVE_GETGRENT
     sGroup = rb_struct_define_under(mEtc, "Group", "name",
 #ifdef HAVE_STRUCT_GROUP_GR_PASSWD
 				    "passwd",
 #endif
 				    "gid", "mem", NULL);
 
 #if 0
-    /* Define-const: Group
+    /*
+     * Group is a placeholder Struct for user group database on Unix systems.
      *
-     * Group is a Struct that is only available when compiled with +HAVE_GETGRENT+.
+     * === The struct contains the following members
      *
-     * The struct contains the following members:
-     *
      * name::
      *	    contains the name of the group as a String.
      * passwd::
-     *	    contains the encrypted password as a String. An 'x' is
+     *	    contains the encrypted password as a String. An <code>'x'</code> is
      *	    returned if password access to the group is not available; an empty
      *	    string is returned if no password is needed to obtain membership of
      *	    the group.
-     *
-     *	    Must be compiled with +HAVE_STRUCT_GROUP_GR_PASSWD+.
+     *	    This is system-dependent.
      * gid::
      *	    contains the group's numeric ID as an integer.
      * mem::
      *	    is an Array of Strings containing the short login names of the
      *	    members of the group.
      */
-    rb_define_const(mEtc, "Group", sGroup);
+    sGroup = rb_define_class_under(mEtc, "Group", rb_cStruct);
 #endif
-    rb_define_const(rb_cStruct, "Group", sGroup); /* deprecated name */
-    rb_deprecate_constant(rb_cStruct, "Group");
     rb_extend_object(sGroup, rb_mEnumerable);
     rb_define_singleton_method(sGroup, "each", etc_each_group, 0);
 #endif
 }