Module: Etc

Relationships & Source Files
Namespace Children
Classes: `Group`, `Passwd`
Defined in:	ext/etc/etc.c

Overview

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.

Constant Summary

VERSION =
# File 'ext/etc/etc.c', line 1121
```
rb_str_new_cstr(RUBY_ETC_VERSION)
```

Class Method Summary

.confstr(arg) mod_func

Returns system configuration variable using confstr().
.endgrent mod_func

Ends the process of scanning through the /etc/group file begun by .getgrent, and closes the file.
.endpwent mod_func

Ends the process of scanning through the /etc/passwd file begun with .getpwent, and closes the file.
.getgrent mod_func

Returns an entry from the /etc/group file.
.getgrgid(group_id) ⇒ Group mod_func

Returns information about the group with specified integer group_id, as found in /etc/group.
.getgrnam(name) ⇒ Group mod_func

Returns information about the group with specified name, as found in /etc/group.
.getlogin ⇒ String mod_func

Returns the short user name of the currently logged in user.
.getpwent mod_func

Returns an entry from the /etc/passwd file.
.getpwnam(name) ⇒ Passwd mod_func

Returns the /etc/passwd information for the user with specified login name.
.getpwuid(uid) ⇒ Passwd mod_func

Returns the /etc/passwd information for the user with the given integer uid.
.group mod_func

Provides a convenient Ruby iterator which executes a block for each entry in the /etc/group file.
.nprocessors mod_func

Returns the number of online processors.
.passwd {|struct| ... } ⇒ Passwd mod_func

Provides a convenient Ruby iterator which executes a block for each entry in the /etc/passwd file.
.setgrent mod_func

Resets the process of reading the /etc/group file, so that the next call to .getgrent will return the first entry again.
.setpwent mod_func

Resets the process of reading the /etc/passwd file, so that the next call to .getpwent will return the first entry again.
.sysconf(arg) mod_func

Returns system configuration variable using sysconf().
.sysconfdir mod_func

Returns system configuration directory.
.systmpdir mod_func

Returns system temporary directory; typically “/tmp”.
.uname mod_func

Returns the system information obtained by uname system call.

Class Method Details

.confstr(arg) (mod_func)

Returns system configuration variable using confstr().

name should be a constant under Etc which begins with CS_.

The return value is a string or nil. nil means no configuration-defined value. (confstr() returns 0 but errno is not set.)

Etc.confstr(Etc::CS_PATH) #=> "/bin:/usr/bin"

# GNU/Linux
Etc.confstr(Etc::CS_GNU_LIBC_VERSION) #=> "glibc 2.18"
Etc.confstr(Etc::CS_GNU_LIBPTHREAD_VERSION) #=> "NPTL 2.18"

[ GitHub ]

# File 'ext/etc/etc.c', line 904


static VALUE
etc_confstr(VALUE obj, VALUE arg)
{
    int name;
    char localbuf[128], *buf = localbuf;
    size_t bufsize = sizeof(localbuf), ret;
    VALUE tmp;

    name = NUM2INT(arg);

    errno = 0;
    ret = confstr(name, buf, bufsize);
    if (bufsize < ret) {
        bufsize = ret;
        buf = ALLOCV_N(char, tmp, bufsize);
        errno = 0;
        ret = confstr(name, buf, bufsize);
    }
    if (bufsize < ret)
        rb_bug("required buffer size for confstr() changed dynamically.");
    if (ret == 0) {
        if (errno == 0) /* no configuration-defined value */
            return Qnil;
        rb_sys_fail("confstr");
    }
    return rb_str_new_cstr(buf);
}

.endgrent (mod_func)

Ends the process of scanning through the /etc/group file begun by .getgrent, and closes the file.

[ GitHub ]

# File 'ext/etc/etc.c', line 635


static VALUE
etc_endgrent(VALUE obj)
{
#ifdef HAVE_GETGRENT
    endgrent();
#endif
    return Qnil;
}

.endpwent (mod_func)

Ends the process of scanning through the /etc/passwd file begun with .getpwent, and closes the file.

[ GitHub ]

# File 'ext/etc/etc.c', line 395


static VALUE
etc_endpwent(VALUE obj)
{
#ifdef HAVE_GETPWENT
    endpwent();
#endif
    return Qnil;
}

.getgrent (mod_func)

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 ::Etc::Group struct

[ GitHub ]

# File 'ext/etc/etc.c', line 654


static VALUE
etc_getgrent(VALUE obj)
{
#ifdef HAVE_GETGRENT
    struct group *gr;

    if ((gr = getgrent()) != 0) {
	return setup_group(gr);
    }
#endif
    return Qnil;
}

.getgrgid(group_id) ⇒ Group (mod_func)

Returns information about the group with specified integer group_id, as found in /etc/group.

The information is returned as a ::Etc::Group struct.

See the unix manpage for getgrgid(3) for more detail.

Example:

Etc.getgrgid(100)
#=> #<struct Etc::Group name="users", passwd="x", gid=100, mem=["meta", "root"]>

[ GitHub ]

# File 'ext/etc/etc.c', line 467


static VALUE
etc_getgrgid(int argc, VALUE *argv, VALUE obj)
{
#ifdef HAVE_GETGRENT
    VALUE id;
    gid_t gid;
    struct group *grp;

    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
}

.getgrnam(name) ⇒ Group (mod_func)

Returns information about the group with specified name, as found in /etc/group.

The information is returned as a ::Etc::Group struct.

See the unix manpage for getgrnam(3) for more detail.

Example:

Etc.getgrnam('users')
#=> #<struct Etc::Group name="users", passwd="x", gid=100, mem=["meta", "root"]>

[ GitHub ]

# File 'ext/etc/etc.c', line 505


static VALUE
etc_getgrnam(VALUE obj, VALUE nam)
{
#ifdef HAVE_GETGRENT
    struct group *grp;
    const char *p = StringValueCStr(nam);

    grp = getgrnam(p);
    if (grp == 0) rb_raise(rb_eArgError, "can't find group for %"PRIsVALUE, nam);
    return setup_group(grp);
#else
    return Qnil;
#endif
}

.getlogin ⇒ `String` (mod_func)

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'

[ GitHub ]

# File 'ext/etc/etc.c', line 112


static VALUE
etc_getlogin(VALUE obj)
{
    char *login;

#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;
}

.getpwent (mod_func)

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 ::Etc::Passwd struct.

[ GitHub ]

# File 'ext/etc/etc.c', line 415


static VALUE
etc_getpwent(VALUE obj)
{
#ifdef HAVE_GETPWENT
    struct passwd *pw;

    if ((pw = getpwent()) != 0) {
	return setup_passwd(pw);
    }
#endif
    return Qnil;
}

.getpwnam(name) ⇒ Passwd (mod_func)

Returns the /etc/passwd information for the user with specified login name.

The information is returned as a ::Etc::Passwd struct.

See the unix manpage for getpwnam(3) for more detail.

Example:

Etc.getpwnam('root')
#=> #<struct Etc::Passwd name="root", passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">

[ GitHub ]

# File 'ext/etc/etc.c', line 260


static VALUE
etc_getpwnam(VALUE obj, VALUE nam)
{
#ifdef HAVE_GETPWENT
    struct passwd *pwd;
    const char *p = StringValueCStr(nam);

    pwd = getpwnam(p);
    if (pwd == 0) rb_raise(rb_eArgError, "can't find user for %"PRIsVALUE, nam);
    return setup_passwd(pwd);
#else
    return Qnil;
#endif
}

.getpwuid(uid) ⇒ Passwd (mod_func)

Returns the /etc/passwd information for the user with the given integer uid.

The information is returned as a ::Etc::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 Etc::Passwd name="root", passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">

[ GitHub ]

# File 'ext/etc/etc.c', line 223


static VALUE
etc_getpwuid(int argc, VALUE *argv, VALUE obj)
{
#if defined(HAVE_GETPWENT)
    VALUE id;
    rb_uid_t uid;
    struct passwd *pwd;

    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
}

.group (mod_func)

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(', ')
}

[ GitHub ]

# File 'ext/etc/etc.c', line 571


static VALUE
etc_group(VALUE obj)
{
#ifdef HAVE_GETGRENT
    struct group *grp;

    if (rb_block_given_p()) {
	each_group();
    }
    else if ((grp = getgrent()) != 0) {
	return setup_group(grp);
    }
#endif
    return Qnil;
}

.nprocessors (mod_func)

Returns the number of online processors.

The result is intended as the number of processes to use all available processors.

This method is implemented using:

sched_getaffinity(): Linux
sysconf(_SC_NPROCESSORS_ONLN): GNU/Linux, NetBSD, FreeBSD, OpenBSD, DragonFly BSD, OpenIndiana, Mac OS X, AIX

Example:

require 'etc'
p Etc.nprocessors #=> 4

The result might be smaller number than physical cpus especially when ruby process is bound to specific cpus. This is intended for getting better parallel processing.

Example: (Linux)

linux$ taskset 0x3 ./ruby -retc -e "p Etc.nprocessors"  #=> 2

[ GitHub ]

# File 'ext/etc/etc.c', line 1052


static VALUE
etc_nprocessors(VALUE obj)
{
    long ret;

#if !defined(_WIN32)

#if defined(HAVE_SCHED_GETAFFINITY) && defined(CPU_ALLOC)
    int ncpus;

    ncpus = etc_nprocessors_affin();
    if (ncpus != -1) {
	return INT2NUM(ncpus);
    }
    /* fallback to _SC_NPROCESSORS_ONLN */
#endif

    errno = 0;
    ret = sysconf(_SC_NPROCESSORS_ONLN);
    if (ret == -1) {
        rb_sys_fail("sysconf(_SC_NPROCESSORS_ONLN)");
    }
#else
    SYSTEM_INFO si;
    GetSystemInfo(&si);
    ret = (long)si.dwNumberOfProcessors;
#endif
    return LONG2NUM(ret);
}

.passwd {|struct| ... } ⇒ Passwd (mod_func) .passwd ⇒ Passwd

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
}

[ GitHub ]

# File 'ext/etc/etc.c', line 329


static VALUE
etc_passwd(VALUE obj)
{
#ifdef HAVE_GETPWENT
    struct passwd *pw;

    if (rb_block_given_p()) {
	each_passwd();
    }
    else if ((pw = getpwent()) != 0) {
	return setup_passwd(pw);
    }
#endif
    return Qnil;
}

.setgrent (mod_func)

Resets the process of reading the /etc/group file, so that the next call to .getgrent will return the first entry again.

[ GitHub ]

# File 'ext/etc/etc.c', line 623


static VALUE
etc_setgrent(VALUE obj)
{
#ifdef HAVE_GETGRENT
    setgrent();
#endif
    return Qnil;
}

.setpwent (mod_func)

Resets the process of reading the /etc/passwd file, so that the next call to .getpwent will return the first entry again.

[ GitHub ]

# File 'ext/etc/etc.c', line 383


static VALUE
etc_setpwent(VALUE obj)
{
#ifdef HAVE_GETPWENT
    setpwent();
#endif
    return Qnil;
}

.sysconf(arg) (mod_func)

Returns system configuration variable using sysconf().

name should be a constant under Etc which begins with SC_.

The return value is an integer or nil. nil means indefinite limit. (sysconf() returns -1 but errno is not set.)

Etc.sysconf(Etc::SC_ARG_MAX) #=> 2097152
Etc.sysconf(Etc::SC_LOGIN_NAME_MAX) #=> 256

[ GitHub ]

# File 'ext/etc/etc.c', line 867


static VALUE
etc_sysconf(VALUE obj, VALUE arg)
{
    int name;
    long ret;

    name = NUM2INT(arg);

    errno = 0;
    ret = sysconf(name);
    if (ret == -1) {
        if (errno == 0) /* no limit */
            return Qnil;
        rb_sys_fail("sysconf");
    }
    return LONG2NUM(ret);
}

.sysconfdir (mod_func)

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.

On Windows, this always returns the directory provided by the system.

[ GitHub ]

# File 'ext/etc/etc.c', line 685


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
}

.systmpdir (mod_func)

Returns system temporary directory; typically “/tmp”.

[ GitHub ]

# File 'ext/etc/etc.c', line 698


static VALUE
etc_systmpdir(VALUE _)
{
    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
    const char default_tmp[] = "/tmp";
    const char *tmpstr = default_tmp;
    size_t tmplen = strlen(default_tmp);
# if defined _CS_DARWIN_USER_TEMP_DIR
    #ifndef MAXPATHLEN
    #define MAXPATHLEN 1024
    #endif
    char path[MAXPATHLEN];
    size_t len;
    len = confstr(_CS_DARWIN_USER_TEMP_DIR, path, sizeof(path));
    if (len > 0) {
	tmpstr = path;
	tmplen = len - 1;
	if (len > sizeof(path)) tmpstr = 0;
    }
# endif
    tmpdir = rb_filesystem_str_new(tmpstr, tmplen);
# if defined _CS_DARWIN_USER_TEMP_DIR
    if (!tmpstr) {
	confstr(_CS_DARWIN_USER_TEMP_DIR, RSTRING_PTR(tmpdir), len);
    }
# endif
#endif
#ifndef RB_PASS_KEYWORDS
    /* untaint on Ruby < 2.7 */
    FL_UNSET(tmpdir, FL_TAINT);
#endif
    return tmpdir;
}

.uname (mod_func)

Returns the system information obtained by uname system call.

The return value is a hash which has 5 keys at least:

:sysname, :nodename, :release, :version, :machine

Example:

require 'etc'
require 'pp'

pp Etc.uname
#=> {:sysname=>"Linux",
#    :nodename=>"boron",
#    :release=>"2.6.18-6-xen-686",
#    :version=>"#1 SMP Thu Nov 5 19:54:42 UTC 2009",
#    :machine=>"i686"}

[ GitHub ]

# File 'ext/etc/etc.c', line 758


static VALUE
etc_uname(VALUE obj)
{
#ifdef _WIN32
    OSVERSIONINFOW v;
    SYSTEM_INFO s;
    const char *sysname, *mach;
    VALUE result, release, version;
    VALUE vbuf, nodename = Qnil;
    DWORD len = 0;
    WCHAR *buf;

    v.dwOSVersionInfoSize = sizeof(v);
    if (!GetVersionExW(&v))
        rb_sys_fail("GetVersionEx");

    result = rb_hash_new();
    switch (v.dwPlatformId) {
      case VER_PLATFORM_WIN32s:
	sysname = "Win32s";
	break;
      case VER_PLATFORM_WIN32_NT:
	sysname = "Windows_NT";
	break;
      case VER_PLATFORM_WIN32_WINDOWS:
      default:
	sysname = "Windows";
	break;
    }
    rb_hash_aset(result, ID2SYM(rb_intern("sysname")), rb_str_new_cstr(sysname));
    release = rb_sprintf("%lu.%lu.%lu", v.dwMajorVersion, v.dwMinorVersion, v.dwBuildNumber);
    rb_hash_aset(result, ID2SYM(rb_intern("release")), release);
    version = rb_sprintf("%s Version %"PRIsVALUE": %"PRIsVALUE, sysname, release,
			 rb_w32_conv_from_wchar(v.szCSDVersion, rb_utf8_encoding()));
    rb_hash_aset(result, ID2SYM(rb_intern("version")), version);

# if defined _MSC_VER && _MSC_VER < 1300
#   define GET_COMPUTER_NAME(ptr, plen) GetComputerNameW(ptr, plen)
# else
#   define GET_COMPUTER_NAME(ptr, plen) GetComputerNameExW(ComputerNameDnsFullyQualified, ptr, plen)
# endif
    GET_COMPUTER_NAME(NULL, &len);
    buf = ALLOCV_N(WCHAR, vbuf, len);
    if (GET_COMPUTER_NAME(buf, &len)) {
	nodename = rb_w32_conv_from_wchar(buf, rb_utf8_encoding());
    }
    ALLOCV_END(vbuf);
    if (NIL_P(nodename)) nodename = rb_str_new(0, 0);
    rb_hash_aset(result, ID2SYM(rb_intern("nodename")), nodename);

# ifndef PROCESSOR_ARCHITECTURE_AMD64
#   define PROCESSOR_ARCHITECTURE_AMD64 9
# endif
# ifndef PROCESSOR_ARCHITECTURE_INTEL
#   define PROCESSOR_ARCHITECTURE_INTEL 0
# endif
    GetSystemInfo(&s);
    switch (s.wProcessorArchitecture) {
      case PROCESSOR_ARCHITECTURE_AMD64:
	mach = "x64";
	break;
      case PROCESSOR_ARCHITECTURE_ARM:
	mach = "ARM";
	break;
      case PROCESSOR_ARCHITECTURE_INTEL:
	mach = "x86";
	break;
      default:
	mach = "unknown";
	break;
    }

    rb_hash_aset(result, ID2SYM(rb_intern("machine")), rb_str_new_cstr(mach));
#else
    struct utsname u;
    int ret;
    VALUE result;

    ret = uname(&u);
    if (ret == -1)
        rb_sys_fail("uname");

    result = rb_hash_new();
    rb_hash_aset(result, ID2SYM(rb_intern("sysname")), rb_str_new_cstr(u.sysname));
    rb_hash_aset(result, ID2SYM(rb_intern("nodename")), rb_str_new_cstr(u.nodename));
    rb_hash_aset(result, ID2SYM(rb_intern("release")), rb_str_new_cstr(u.release));
    rb_hash_aset(result, ID2SYM(rb_intern("version")), rb_str_new_cstr(u.version));
    rb_hash_aset(result, ID2SYM(rb_intern("machine")), rb_str_new_cstr(u.machine));
#endif

    return result;
}

Module: Etc

Overview

Example:

Constant Summary

Class Method Summary

Class Method Details

.confstr(arg) (mod_func)

.endgrent (mod_func)

.endpwent (mod_func)

.getgrent (mod_func)

.getgrgid(group_id) ⇒ Group (mod_func)

Example:

.getgrnam(name) ⇒ Group (mod_func)

Example:

.getlogin ⇒ String (mod_func)

.getpwent (mod_func)

.getpwnam(name) ⇒ Passwd (mod_func)

Example:

.getpwuid(uid) ⇒ Passwd (mod_func)

Example:

.group (mod_func)

.nprocessors (mod_func)

.passwd {|struct| ... } ⇒ Passwd (mod_func) .passwd ⇒ Passwd

.setgrent (mod_func)

.setpwent (mod_func)

.sysconf(arg) (mod_func)

.sysconfdir (mod_func)

.systmpdir (mod_func)

.uname (mod_func)

.getlogin ⇒ `String` (mod_func)