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_ST_PW_GECOS+
change

password change time(integer) must be compiled with HAVE_ST_PW_CHANGE

quota

quota value(integer) must be compiled with HAVE_ST_PW_QUOTA

age

password age(integer) must be compiled with HAVE_ST_PW_AGE

class

user access class(string) must be compiled with HAVE_ST_PW_CLASS

comment

comment(string) must be compiled with HAVE_ST_PW_COMMENT

expire

account expiration time(integer) must be compiled with HAVE_ST_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_ST_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

.endgrent ⇒ Object

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



555
556
557
558
559
560
561
562
 
# File 'etc.c', line 555

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.



314
315
316
317
318
319
320
321
 
# File 'etc.c', line 314

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



574
575
576
577
578
579
580
581
582
583
584
585
 
# File 'etc.c', line 574

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

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

.getgrgid ⇒ 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 Struct::Group name=“users”, passwd=“x”, gid=100, mem=[“meta”, “root”]>



386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
 
# File 'etc.c', line 386

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

    rb_secure(4);
    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 ⇒ 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 Struct::Group name=“users”, passwd=“x”, gid=100, mem=[“meta”, “root”]>



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

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

    rb_secure(4);
    SafeStringValue(nam);
    grp = getgrnam(RSTRING_PTR(nam));
    if (grp == 0) rb_raise(rb_eArgError, "can't find group for %s", RSTRING_PTR(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'



58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'etc.c', line 58

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

    rb_secure(4);
#ifdef HAVE_GETLOGIN
    login = getlogin();
    if (!login) login = getenv("USER");
#else
    login = getenv("USER");
#endif

    if (login)
	return rb_tainted_str_new2(login);
    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.



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

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

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

.getpwnam ⇒ 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 Struct::Passwd name=“root”, passwd=“x”, uid=0, gid=0, gecos=“root”,dir=“/root”, shell=“/bin/bash”>



180
181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'etc.c', line 180

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 %s", RSTRING_PTR(nam));
    return setup_passwd(pwd);
#else
    return Qnil;
#endif
}

.getpwuid ⇒ 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 Struct::Passwd name=“root”, passwd=“x”, uid=0, gid=0, gecos=“root”,dir=“/root”, shell=“/bin/bash”>



142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'etc.c', line 142

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

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



491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
 
# File 'etc.c', line 491

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

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

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



248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
 
# File 'etc.c', line 248

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

    rb_secure(4);
    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.



543
544
545
546
547
548
549
550
 
# File 'etc.c', line 543

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.



302
303
304
305
306
307
308
309
 
# File 'etc.c', line 302

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

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



602
603
604
605
606
607
608
609
610
 
# File 'etc.c', line 602

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



615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
 
# File 'etc.c', line 615

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
    tmpdir = rb_filesystem_str_new_cstr("/tmp");
#endif
    FL_UNSET(tmpdir, FL_TAINT|FL_UNTRUSTED);
    return tmpdir;
}