模块 Etc

Etc 模块提供了对通常存储在 Unix 系统 /etc 目录中的文件的信息的访问。

可访问的信息包括 /etc/passwd 和 /etc/group 文件中的信息，以及关于系统的临时目录 (/tmp) 和配置目录 (/etc) 的信息。

与诸如 +$USER+ 的环境变量相比，Etc 模块提供了一种更可靠的方式来访问有关已登录用户的信息。

示例

require 'etc'

login = Etc.getlogin
info = Etc.getpwnam(login)
username = info.gecos.split(/,/).first
puts "Hello #{username}, I see your login name is #{login}"

请注意，此模块提供的方法并非始终安全。它应该用于信息目的，而不是用于安全目的。

在此模块中定义的所有操作都是类方法，因此您可以将 Etc 模块包含到您的类中。

常量

VERSION: 版本

公共类方法

confstr(name) → String

来源

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

使用 confstr() 返回系统配置变量。

name 应该是 Etc 下以 CS_ 开头的常量。

返回值是一个字符串或 nil。nil 表示没有配置定义的值。（confstr() 返回 0，但 errno 未设置。）

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"

endgrent

来源

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

结束扫描由 ::getgrent 开始的 /etc/group 文件的过程，并关闭该文件。

endpwent

来源

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

结束扫描由 ::getpwent 开始的 /etc/passwd 文件的过程，并关闭该文件。

getgrent → Etc::Group

来源

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

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

从 /etc/group 文件返回一个条目。

第一次调用时，它会打开该文件并返回第一个条目；每次后续调用都会返回下一个条目，如果已到达文件末尾，则返回 nil。

要在处理完成后关闭文件，请调用 ::endgrent。

每个条目都作为 Group 结构体返回

getgrgid(group_id) → Etc::Group

来源

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
}

返回有关 /etc/group 中找到的具有指定整数 group_id 的组的信息。

该信息作为 Group 结构体返回。

有关更多详细信息，请参阅 unix 手册页 getgrgid(3)。

示例

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

getgrnam(name) → Etc::Group

来源

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
}

返回有关 /etc/group 中找到的具有指定 name 的组的信息。

该信息作为 Group 结构体返回。

有关更多详细信息，请参阅 unix 手册页 getgrnam(3)。

示例

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

getlogin → String

来源

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

返回当前登录用户的短用户名。不幸的是，要欺骗 ::getlogin 通常相当容易。

为了安全起见，请避免使用 ::getlogin。

如果 ::getlogin 失败，请尝试 ::getpwuid。

有关更多详细信息，请参阅 unix 手册页 getpwuid(3)。

例如：

Etc.getlogin -> 'guest'

getpwent → Etc::Passwd

来源

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

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

从 /etc/passwd 文件返回一个条目。

第一次调用时，它会打开该文件并返回第一个条目；每次后续调用都会返回下一个条目，如果已到达文件末尾，则返回 nil。

要在处理完成后关闭文件，请调用 ::endpwent。

每个条目都作为 Passwd 结构体返回。

getpwnam(name) → Etc::Passwd

来源

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
}

返回具有指定登录 name 的用户的 /etc/passwd 信息。

该信息作为 Passwd 结构体返回。

有关更多详细信息，请参阅 unix 手册页 getpwnam(3)。

示例

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

getpwuid(uid) → Etc::Passwd

来源

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
}

返回具有给定整数 uid 的用户的 /etc/passwd 信息。

该信息作为 Passwd 结构体返回。

如果省略 uid，则会返回 Passwd[:uid] 中的值。

有关更多详细信息，请参阅 unix 手册页 getpwuid(3)。

示例

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

group { |struct| block }

group → Etc::Group

来源

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

提供了一个方便的 Ruby 迭代器，该迭代器为 /etc/group 文件中的每个条目执行一个代码块。

代码块会传递一个 Group 结构体。

有关详细信息，请参见上面的 ::getgrent。

示例

require 'etc'

Etc.group {|g|
  puts g.name + ": " + g.mem.join(', ')
}

nprocessors → Integer

来源

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

返回在线处理器的数量。

该结果旨在作为使用所有可用处理器的进程数。

此方法使用以下方式实现：

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

示例

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

该结果可能小于物理 CPU 的数量，尤其是在 Ruby 进程绑定到特定 CPU 时。这旨在获得更好的并行处理。

示例：（Linux）

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

passwd { |struct| block }

passwd → Etc::Passwd

来源

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

提供了一个方便的 Ruby 迭代器，该迭代器为 /etc/passwd 文件中的每个条目执行一个代码块。

代码块会传递一个 Passwd 结构体。

有关详细信息，请参见上面的 ::getpwent。

示例

require 'etc'

Etc.passwd {|u|
  puts u.name + " = " + u.gecos
}

setgrent

来源

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

重置读取 /etc/group 文件的过程，以便下次调用 ::getgrent 时再次返回第一个条目。

setpwent

来源

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

重置读取 /etc/passwd 文件的过程，以便下次调用 ::getpwent 时再次返回第一个条目。

sysconf(name) → Integer

来源

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

使用 sysconf() 返回系统配置变量。

name 应该是 Etc 下以 SC_ 开头的常量。

返回值是一个整数或 nil。nil 表示无限限制。（sysconf() 返回 -1，但 errno 未设置。）

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

sysconfdir → String

来源

static VALUE
etc_sysconfdir(VALUE obj)
{
#ifdef _WIN32
    return rb_w32_special_folder(CSIDL_COMMON_APPDATA);
#elif defined(LOAD_RELATIVE)
    return rb_hash_aref(rbconfig(), rb_str_new_lit("sysconfdir"));
#else
    return rb_filesystem_str_new_cstr(SYSCONFDIR);
#endif
}

返回系统配置目录。

这通常是 "/etc"，但会根据编译 Ruby 时使用的前缀进行修改。例如，如果 Ruby 构建并安装在 /usr/local 中，则在 Windows 以外的其他平台上会返回 "/usr/local/etc"。

在 Windows 上，这始终返回系统提供的目录。

systmpdir → String

来源

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

返回系统临时目录；通常为 “/tmp”。

uname → hash

来源

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, SYMBOL_LIT("sysname"), rb_str_new_cstr(sysname));
    release = rb_sprintf("%lu.%lu.%lu", v.dwMajorVersion, v.dwMinorVersion, v.dwBuildNumber);
    rb_hash_aset(result, SYMBOL_LIT("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, SYMBOL_LIT("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, SYMBOL_LIT("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, SYMBOL_LIT("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, SYMBOL_LIT("sysname"), rb_str_new_cstr(u.sysname));
    rb_hash_aset(result, SYMBOL_LIT("nodename"), rb_str_new_cstr(u.nodename));
    rb_hash_aset(result, SYMBOL_LIT("release"), rb_str_new_cstr(u.release));
    rb_hash_aset(result, SYMBOL_LIT("version"), rb_str_new_cstr(u.version));
    rb_hash_aset(result, SYMBOL_LIT("machine"), rb_str_new_cstr(u.machine));
#endif

    return result;
}

返回 uname 系统调用获取的系统信息。

返回值是一个至少具有 5 个键的哈希值

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

示例

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