Module: Etc

Defined in:
ext/etc/etc.c

Defined Under Namespace

Classes: Group, Passwd

Constant Summary collapse

VERSION =

The version

rb_str_new_cstr(RUBY_ETC_VERSION)

Class Method Summary collapse

Class Method Details

.confstr(arg) ⇒ Object

confstr(name) -> String

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"



949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
 
# File 'ext/etc/etc.c', line 949

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 ⇒ Object

endgrent

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



655
656
657
658
659
660
661
662
 
# File 'ext/etc/etc.c', line 655

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

.endpwent ⇒ Object

endpwent

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



403
404
405
406
407
408
409
410
 
# File 'ext/etc/etc.c', line 403

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

.getgrent ⇒ Object

getgrent -> Etc::Group

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



677
678
679
680
681
682
683
684
685
686
687
688
 
# File 'ext/etc/etc.c', line 677

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

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

.getgrgid(*args) ⇒ Object

getgrgid(group_id) -> Etc::Group

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”]>



478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
 
# File 'ext/etc/etc.c', line 478

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(nam) ⇒ Object

getgrnam(name) -> Etc::Group

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”]>



516
517
518
519
520
521
522
523
524
525
526
527
528
529
 
# File 'ext/etc/etc.c', line 516

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 ⇒ Object

getlogin -> String

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'



114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'ext/etc/etc.c', line 114

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 ⇒ Object

getpwent -> Etc::Passwd

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.



426
427
428
429
430
431
432
433
434
435
436
437
 
# File 'ext/etc/etc.c', line 426

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

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

.getpwnam(nam) ⇒ Object

getpwnam(name) -> Etc::Passwd

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”>



262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'ext/etc/etc.c', line 262

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(*args) ⇒ Object

getpwuid(uid) -> Etc::Passwd

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”>



225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'ext/etc/etc.c', line 225

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 ⇒ Object

group { |struct| block } group -> Etc::Group

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



585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
 
# File 'ext/etc/etc.c', line 585

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 ⇒ Object

nprocessors -> Integer

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



1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
 
# File 'ext/etc/etc.c', line 1101

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 ⇒ Object

passwd { |struct| block } passwd -> Etc::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
}



331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
 
# File 'ext/etc/etc.c', line 331

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 ⇒ Object

setgrent

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



640
641
642
643
644
645
646
647
 
# File 'ext/etc/etc.c', line 640

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

.setpwent ⇒ Object

setpwent

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



388
389
390
391
392
393
394
395
 
# File 'ext/etc/etc.c', line 388

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

.sysconf(arg) ⇒ Object

sysconf(name) -> Integer

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



910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
 
# File 'ext/etc/etc.c', line 910

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 ⇒ Object

sysconfdir -> String

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.



720
721
722
723
724
725
726
727
728
729
730
 
# File 'ext/etc/etc.c', line 720

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
}

.systmpdir ⇒ Object

systmpdir -> String

Returns system temporary directory; typically “/tmp”.



737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
 
# File 'ext/etc/etc.c', line 737

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 ⇒ Object

uname -> hash

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



799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
 
# File 'ext/etc/etc.c', line 799

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