Module: Etc

Defined in:
etc.c

Constant Summary collapse

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

Define-const
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.

Define-const

Class Method Summary collapse

Class Method Details

.confstr(arg) ⇒ Object

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"



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
 
# File 'etc.c', line 847

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

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



584
585
586
587
588
589
590
591
 
# File 'etc.c', line 584

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

.endpwent ⇒ Object

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



346
347
348
349
350
351
352
353
 
# File 'etc.c', line 346

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

.getgrent ⇒ Object

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



603
604
605
606
607
608
609
610
611
612
613
614
 
# File 'etc.c', line 603

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

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

.getgrgid(*args) ⇒ Object

getgrgid(group_id) -> 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”]>



418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
 
# File 'etc.c', line 418

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



456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'etc.c', line 456

static VALUE
etc_getgrnam(VALUE obj, VALUE nam)
{
#ifdef HAVE_GETGRENT
    struct group *grp;

    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
}

.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'



72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'etc.c', line 72

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

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.



366
367
368
369
370
371
372
373
374
375
376
377
 
# File 'etc.c', line 366

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

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

.getpwnam(nam) ⇒ Object

getpwnam(name) -> 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”>



213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'etc.c', line 213

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
}

.getpwuid(*args) ⇒ Object

getpwuid(uid) -> 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”>



176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
 
# File 'etc.c', line 176

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

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



521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
 
# File 'etc.c', line 521

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

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

.nprocessors ⇒ Object

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



997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
 
# File 'etc.c', line 997

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

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



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'etc.c', line 281

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

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

.setgrent ⇒ Object

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



572
573
574
575
576
577
578
579
 
# File 'etc.c', line 572

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

.setpwent ⇒ Object

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



334
335
336
337
338
339
340
341
 
# File 'etc.c', line 334

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

.sysconf(arg) ⇒ Object

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



810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
 
# File 'etc.c', line 810

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

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



631
632
633
634
635
636
637
638
639
 
# File 'etc.c', line 631

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

Returns system temporary directory; typically “/tmp”.



644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
 
# File 'etc.c', line 644

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
    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;
    }
# endif
    tmpdir = rb_filesystem_str_new(tmpstr, tmplen);
#endif
    FL_UNSET(tmpdir, FL_TAINT);
    return tmpdir;
}

.uname ⇒ Object

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



695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
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
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
 
# File 'etc.c', line 695

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_IA64
#   define PROCESSOR_ARCHITECTURE_IA64 6
# 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_IA64:
	mach = "IA64";
	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;
}