summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ChangeLog7
-rw-r--r--ext/etc/etc.c135
-rw-r--r--ext/fcntl/fcntl.c75
3 files changed, 217 insertions, 0 deletions
diff --git a/ChangeLog b/ChangeLog
index 7f49e99258..bc72ba3670 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,10 @@
+Sat Oct 29 01:58:25 2005 Yukihiro Matsumoto <matz@ruby-lang.org>
+
+ * ext/etc/etc.c: document update from mathew <meta@pobox.com>.
+ [ruby-core:06473]
+
+ * ext/fcntl/fcntl.c: ditto.
+
Thu Oct 27 16:45:31 2005 Yukihiro Matsumoto <matz@ruby-lang.org>
* string.c (scan_once): wrong condition to use mbclen2().
diff --git a/ext/etc/etc.c b/ext/etc/etc.c
index 3b788d72d7..94196e066a 100644
--- a/ext/etc/etc.c
+++ b/ext/etc/etc.c
@@ -34,6 +34,11 @@ char *getenv();
#endif
char *getlogin();
+/* Returns the short user name of the currently logged in user.
+ *
+ * e.g.
+ * Etc.getlogin -> 'guest'
+ */
static VALUE
etc_getlogin(obj)
VALUE obj;
@@ -104,6 +109,15 @@ setup_passwd(pwd)
}
#endif
+/* Returns the /etc/passwd information for the user with specified integer
+ * user id (uid).
+ *
+ * The information is returned as a Struct::Passwd; see getpwent above for
+ * details.
+ *
+ * e.g. * Etc.getpwuid(0) -> #<struct Struct::Passwd name="root",
+ * passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">
+ */
static VALUE
etc_getpwuid(argc, argv, obj)
int argc;
@@ -130,6 +144,14 @@ etc_getpwuid(argc, argv, obj)
#endif
}
+/* Returns the /etc/passwd information for the user with specified login name.
+ *
+ * The information is returned as a Struct::Passwd; see getpwent above for
+ * details.
+ *
+ * e.g. * Etc.getpwnam('root') -> #<struct Struct::Passwd name="root",
+ * passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">
+ */
static VALUE
etc_getpwnam(obj, nam)
VALUE obj, nam;
@@ -169,6 +191,21 @@ passwd_iterate()
}
#endif
+/* Provides a convenient Ruby iterator which executes a block for each entry
+ * in the /etc/passwd file.
+ *
+ * The code block is passed an Etc::Passwd struct; see getpwent above for
+ * details.
+ *
+ * Example:
+ *
+ * require 'etc'
+ *
+ * Etc.passwd {|u|
+ * puts u.name + " = " + u.gecos
+ * }
+ *
+ */
static VALUE
etc_passwd(obj)
VALUE obj;
@@ -191,6 +228,9 @@ etc_passwd(obj)
return Qnil;
}
+/* Resets the process of reading the /etc/passwd file, so that the next call
+ * to getpwent will return the first entry again.
+ */
static VALUE
etc_setpwent(obj)
VALUE obj;
@@ -201,6 +241,9 @@ etc_setpwent(obj)
return Qnil;
}
+/* Ends the process of scanning through the /etc/passwd file begun with
+ * getpwent, and closes the file.
+ */
static VALUE
etc_endpwent(obj)
VALUE obj;
@@ -211,6 +254,32 @@ etc_endpwent(obj)
return Qnil;
}
+/* Returns an entry from the /etc/passwd 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.
+ *
+ * To close the file when processing is complete, call endpwent.
+ *
+ * Each entry is returned as a Struct::Passwd:
+ *
+ * - Passwd#name contains the short login name of the user as a String.
+ *
+ * - Passwd#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.
+ *
+ * - Passwd#uid contains the integer user ID (uid) of the user.
+ *
+ * - Passwd#gid contains the integer group ID (gid) of the user's primary group.
+ *
+ * - Passwd#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.
+ *
+ * - Passwd#dir contains the path to the home directory of the user as a String.
+ *
+ * - Passwd#shell contains the path to the login shell of the user as a String.
+ */
static VALUE
etc_getpwent(obj)
VALUE obj;
@@ -249,6 +318,16 @@ setup_group(grp)
}
#endif
+/* Returns information about the group with specified integer group id (gid),
+ * as found in /etc/group.
+ *
+ * The information is returned as a Struct::Group; see getgrent above for
+ * details.
+ *
+ * e.g. Etc.getgrgid(100) -> #<struct Struct::Group name="users", passwd="x",
+ * gid=100, mem=["meta", "root"]>
+ *
+ */
static VALUE
etc_getgrgid(obj, id)
VALUE obj, id;
@@ -267,6 +346,16 @@ etc_getgrgid(obj, id)
#endif
}
+/* Returns information about the group with specified String name, as found
+ * in /etc/group.
+ *
+ * The information is returned as a Struct::Group; see getgrent above for
+ * details.
+ *
+ * e.g. Etc.getgrnam('users') -> #<struct Struct::Group name="users",
+ * passwd="x", gid=100, mem=["meta", "root"]>
+ *
+ */
static VALUE
etc_getgrnam(obj, nam)
VALUE obj, nam;
@@ -307,6 +396,21 @@ group_iterate()
}
#endif
+/* Provides a convenient Ruby iterator which executes a block for each entry
+ * in the /etc/group file.
+ *
+ * The code block is passed an Etc::Group struct; see getgrent above for
+ * details.
+ *
+ * Example:
+ *
+ * require 'etc'
+ *
+ * Etc.group {|g|
+ * puts g.name + ": " + g.mem.join(', ')
+ * }
+ *
+ */
static VALUE
etc_group(obj)
VALUE obj;
@@ -329,6 +433,9 @@ etc_group(obj)
return Qnil;
}
+/* Resets the process of reading the /etc/group file, so that the next call
+ * to getgrent will return the first entry again.
+ */
static VALUE
etc_setgrent(obj)
VALUE obj;
@@ -339,6 +446,9 @@ etc_setgrent(obj)
return Qnil;
}
+/* Ends the process of scanning through the /etc/group file begun by
+ * getgrent, and closes the file.
+ */
static VALUE
etc_endgrent(obj)
VALUE obj;
@@ -349,6 +459,26 @@ etc_endgrent(obj)
return Qnil;
}
+/* Returns an entry from the /etc/group 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.
+ *
+ * To close the file when processing is complete, call endgrent.
+ *
+ * Each entry is returned as a Struct::Group:
+ *
+ * - Group#name contains the name of the group as a String.
+ *
+ * - Group#passwd contains the encrypted password as a String. An 'x' 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.
+ *
+ * - Group#gid contains the group's numeric ID as an integer.
+ *
+ * - Group#mem is an Array of Strings containing the short login names of the
+ * members of the group.
+ */
static VALUE
etc_getgrent(obj)
VALUE obj;
@@ -365,6 +495,11 @@ etc_getgrent(obj)
static VALUE mEtc;
+/* The etc module provides access to information from the /etc/passwd and
+ * /etc/group files on Linux and Unix systems.
+ *
+ * Documented by mathew <meta@pobox.com>.
+ */
void
Init_etc()
{
diff --git a/ext/fcntl/fcntl.c b/ext/fcntl/fcntl.c
index d48630fc66..57cca103f4 100644
--- a/ext/fcntl/fcntl.c
+++ b/ext/fcntl/fcntl.c
@@ -34,6 +34,81 @@ pack up your own arguments to pass as args for locking functions, etc.
#include "ruby.h"
#include <fcntl.h>
+/* Fcntl loads the constants defined in the system's <fcntl.h> C header
+ * file, and used with both the fcntl(2) and open(2) POSIX system calls.
+ *
+ * Copyright (C) 1997-2001 Yukihiro Matsumoto
+ *
+ * Documented by mathew <meta@pobox.com>
+ *
+ * = Usage
+ *
+ * To perform a fcntl(2) operation, use IO::fcntl in the core classes.
+ *
+ * To perform an open(2) operation, use IO::sysopen.
+ *
+ * The set of operations and constants available depends upon specific OS
+ * platform. Some values listed below may not be supported on your system.
+ *
+ * The constants supported by Ruby for use with IO::fcntl are:
+ *
+ * - F_DUPFD - duplicate a close-on-exec file handle to a non-close-on-exec
+ * file handle.
+ *
+ * - F_GETFD - read the close-on-exec flag of a file handle.
+ *
+ * - F_SETFD - set the close-on-exec flag of a file handle.
+ *
+ * - FD_CLOEXEC - the value of the close-on-exec flag.
+ *
+ * - F_GETFL - get file descriptor flags.
+ *
+ * - F_SETFL - set file descriptor flags.
+ *
+ * - O_APPEND, O_NONBLOCK, etc (see below) - file descriptor flag
+ * values for the above.
+ *
+ * - F_GETLK - determine whether a given region of a file is locked.
+ *
+ * - F_SETLK - acquire a lock on a region of a file.
+ *
+ * - F_SETLKW - acquire a lock on a region of a file, waiting if necessary.
+ *
+ * - F_RDLCK, F_WRLCK, F_UNLCK - types of lock for the above.
+ *
+ * The constants supported by Ruby for use with IO::sysopen are:
+ *
+ * - O_APPEND - open file in append mode.
+ *
+ * - O_NOCTTY - open tty without it becoming controlling tty.
+ *
+ * - O_CREAT - create file if it doesn't exist.
+ *
+ * - O_EXCL - used with O_CREAT, fail if file exists.
+ *
+ * - O_TRUNC - truncate file on open.
+ *
+ * - O_NONBLOCK / O_NDELAY - open in non-blocking mode.
+ *
+ * - O_RDONLY - open read-only.
+ *
+ * - O_WRONLY - open write-only.
+ *
+ * - O_RDWR - open read-write.
+ *
+ * - O_ACCMODE - mask to extract read/write flags.
+ *
+ * Example:
+ *
+ * require 'fcntl'
+ *
+ * fd = IO::sysopen('/tmp/tempfile',
+ * Fcntl::O_WRONLY | Fcntl::O_EXCL | Fcntl::O_CREAT)
+ * f = IO.open(fd)
+ * f.syswrite("TEMP DATA")
+ * f.close
+ *
+ */
void
Init_fcntl()
{