# 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`

  `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_STRUCT_GROUP_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`

  `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_STRUCT_PASSWD_PW_GECOS`

  change

    password change time(integer) must be compiled with `HAVE_STRUCT_PASSWD_PW_CHANGE`

  quota

    quota value(integer) must be compiled with `HAVE_STRUCT_PASSWD_PW_QUOTA`

  age

    password age(integer) must be compiled with `HAVE_STRUCT_PASSWD_PW_AGE`

  class

    user access class(string) must be compiled with `HAVE_STRUCT_PASSWD_PW_CLASS`

  comment

    comment(string) must be compiled with `HAVE_STRUCT_PASSWD_PW_COMMENT`

  expire

    account expiration time(integer) must be compiled with `HAVE_STRUCT_PASSWD_PW_EXPIRE`

VERSION

### Public Class Methods

confstr(p1) click to toggle source

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"

    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() click to toggle source

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

endpwent() click to toggle source

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

getgrent() click to toggle source

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()) != 0) {
            return setup_group(gr);
        }
    #endif
        return Qnil;
    }

getgrgid(group_id) → Group click to toggle source

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 Etc::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;

        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 click to toggle source

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 Etc::Group name="users", passwd="x", gid=100, mem=["meta", "root"]>

    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 click to toggle source

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;

    #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() click to toggle source

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()) != 0) {
            return setup_passwd(pw);
        }
    #endif
        return Qnil;
    }

getpwnam(name) → Passwd click to toggle source

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 Etc::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;
        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 click to toggle source

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 Etc::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;

        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() click to toggle source

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;

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

nprocessors() click to toggle source

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

    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| block } → Passwd click to toggle source
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 `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;

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

setgrent() click to toggle source

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

setpwent() click to toggle source

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

sysconf(p1) click to toggle source

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

    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() click to toggle source

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.

    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() click to toggle source

Returns system temporary directory; typically “/tmp”.

    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() click to toggle source

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"}

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