module Etc
The Etc module provides access to information typically stored in files in the /etc 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).
The Etc module provides a more reliable way to access information about the logged in user than environment variables such as +$USER+.
Example:¶ ↑
require 'etc' login = Etc.getlogin info = Etc.getpwnam(login) username = info.gecos.split(/,/).first puts "Hello #{username}, I see your login name is #{login}"
Note that the methods provided by this module are not always secure. It should be used for informational purposes, and not for security.
All operations defined in this module are class methods, so that you can include the Etc module into your class.
Constants
- Group
-
Group is a Struct that is only available when compiled with
HAVE_GETGRENT.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 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_ST_GR_PASSWD. - 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.
- Passwd
-
Passwd is a Struct that 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.
- 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:¶ ↑
- 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_ST_PW_GECOS - change
-
password change time(integer) must be compiled with
HAVE_ST_PW_CHANGE - quota
-
quota value(integer) must be compiled with
HAVE_ST_PW_QUOTA - age
-
password age(integer) must be compiled with
HAVE_ST_PW_AGE - class
-
user access class(string) must be compiled with
HAVE_ST_PW_CLASS - comment
-
comment(string) must be compiled with
HAVE_ST_PW_COMMENT - expire
-
account expiration time(integer) must be compiled with
HAVE_ST_PW_EXPIRE
Public Class Methods
Ends the process of scanning through the /etc/group file begun by ::getgrent, and closes the file.
static VALUE
etc_endgrent(VALUE obj)
{
#ifdef HAVE_GETGRENT
endgrent();
#endif
return Qnil;
}
Ends the process of scanning through the /etc/passwd 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/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 Group struct
static VALUE
etc_getgrent(VALUE obj)
{
#ifdef HAVE_GETGRENT
struct group *gr;
if (gr = getgrent()) {
return setup_group(gr);
}
#endif
return Qnil;
}
Returns information about the group with specified integer
group_id, as found in /etc/group.
The information is returned as a Group struct.
See the unix manpage for getgrgid(3) for more detail.
Example:¶ ↑
Etc.getgrgid(100) #=> #<struct Struct::Group name="users", passwd="x", gid=100, mem=["meta", "root"]>
static VALUE
etc_getgrgid(int argc, VALUE *argv, VALUE obj)
{
#ifdef HAVE_GETGRENT
VALUE id;
gid_t gid;
struct group *grp;
rb_secure(4);
if (rb_scan_args(argc, argv, "01", &id) == 1) {
gid = NUM2GIDT(id);
}
else {
gid = getgid();
}
grp = getgrgid(gid);
if (grp == 0) rb_raise(rb_eArgError, "can't find group for %d", (int)gid);
return setup_group(grp);
#else
return Qnil;
#endif
}
Returns information about the group with specified name, as
found in /etc/group.
The information is returned as a Group struct.
See the unix manpage for getgrnam(3) for more detail.
Example:¶ ↑
Etc.getgrnam('users') #=> #<struct Struct::Group name="users", passwd="x", gid=100, mem=["meta", "root"]>
static VALUE
etc_getgrnam(VALUE obj, VALUE nam)
{
#ifdef HAVE_GETGRENT
struct group *grp;
rb_secure(4);
SafeStringValue(nam);
grp = getgrnam(RSTRING_PTR(nam));
if (grp == 0) rb_raise(rb_eArgError, "can't find group for %"PRIsVALUE, nam);
return setup_group(grp);
#else
return Qnil;
#endif
}
Returns the short user name of the currently logged in user. Unfortunately, it is often rather easy to fool ::getlogin.
Avoid ::getlogin for security-related purposes.
If ::getlogin fails, try ::getpwuid.
See the unix manpage for getpwuid(3) for more detail.
e.g.
Etc.getlogin -> 'guest'
static VALUE
etc_getlogin(VALUE obj)
{
char *login;
rb_secure(4);
#ifdef HAVE_GETLOGIN
login = getlogin();
if (!login) login = getenv("USER");
#else
login = getenv("USER");
#endif
if (login) {
#ifdef _WIN32
rb_encoding *extenc = rb_utf8_encoding();
#else
rb_encoding *extenc = rb_locale_encoding();
#endif
return rb_external_str_new_with_enc(login, strlen(login), extenc);
}
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 Passwd struct.
static VALUE
etc_getpwent(VALUE obj)
{
#ifdef HAVE_GETPWENT
struct passwd *pw;
if (pw = getpwent()) {
return setup_passwd(pw);
}
#endif
return Qnil;
}
Returns the /etc/passwd information for the user with specified login
name.
The information is returned as a Passwd struct.
See the unix manpage for getpwnam(3) for more detail.
Example:¶ ↑
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(VALUE obj, VALUE nam)
{
#ifdef HAVE_GETPWENT
struct passwd *pwd;
SafeStringValue(nam);
pwd = getpwnam(RSTRING_PTR(nam));
if (pwd == 0) rb_raise(rb_eArgError, "can't find user for %"PRIsVALUE, nam);
return setup_passwd(pwd);
#else
return Qnil;
#endif
}
Returns the /etc/passwd information for the user with the given integer
uid.
The information is returned as a Passwd struct.
If uid is omitted, the value from Passwd[:uid] is
returned instead.
See the unix manpage for getpwuid(3) for more detail.
Example:¶ ↑
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(int argc, VALUE *argv, VALUE obj)
{
#if defined(HAVE_GETPWENT)
VALUE id;
rb_uid_t uid;
struct passwd *pwd;
rb_secure(4);
if (rb_scan_args(argc, argv, "01", &id) == 1) {
uid = NUM2UIDT(id);
}
else {
uid = getuid();
}
pwd = getpwuid(uid);
if (pwd == 0) rb_raise(rb_eArgError, "can't find user for %d", (int)uid);
return setup_passwd(pwd);
#else
return Qnil;
#endif
}
Provides a convenient Ruby iterator which executes a block for each entry in the /etc/group file.
The code block is passed an Group struct.
See ::getgrent above for details.
Example:
require 'etc' Etc.group {|g| puts g.name + ": " + g.mem.join(', ') }
static VALUE
etc_group(VALUE obj)
{
#ifdef HAVE_GETGRENT
struct group *grp;
rb_secure(4);
if (rb_block_given_p()) {
each_group();
}
else if (grp = getgrent()) {
return setup_group(grp);
}
#endif
return Qnil;
}
Provides a convenient Ruby iterator which executes a block for each entry in the /etc/passwd file.
The code block is passed an Passwd struct.
See ::getpwent above for details.
Example:
require 'etc' Etc.passwd {|u| puts u.name + " = " + u.gecos }
static VALUE
etc_passwd(VALUE obj)
{
#ifdef HAVE_GETPWENT
struct passwd *pw;
rb_secure(4);
if (rb_block_given_p()) {
each_passwd();
}
else if (pw = getpwent()) {
return setup_passwd(pw);
}
#endif
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(VALUE obj)
{
#ifdef HAVE_GETGRENT
setgrent();
#endif
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(VALUE obj)
{
#ifdef HAVE_GETPWENT
setpwent();
#endif
return Qnil;
}
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”.
static VALUE
etc_sysconfdir(VALUE obj)
{
#ifdef _WIN32
return rb_w32_special_folder(CSIDL_COMMON_APPDATA);
#else
return rb_filesystem_str_new_cstr(SYSCONFDIR);
#endif
}
Returns system temporary directory; typically “/tmp”.
static VALUE
etc_systmpdir(void)
{
VALUE tmpdir;
#ifdef _WIN32
WCHAR path[_MAX_PATH];
UINT len = rb_w32_system_tmpdir(path, numberof(path));
if (!len) return Qnil;
tmpdir = rb_w32_conv_from_wchar(path, rb_filesystem_encoding());
#else
tmpdir = rb_filesystem_str_new_cstr("/tmp");
#endif
FL_UNSET(tmpdir, FL_TAINT|FL_UNTRUSTED);
return tmpdir;
}