Module: Etc

Module | Etc
In: | etc/etc.c

The etc module provides access to information from the /etc/passwd and /etc/group files on Linux and Unix systems.

Documented by mathew <meta@pobox.com>.

### Methods

endgrent endpwent getgrent getgrgid getgrnam getlogin getpwent getpwnam getpwuid group passwd setgrent setpwent

### Public Instance methods

endgrent()

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

[Source]

    /* Ends the process of scanning through the /etc/group file begun by
     * getgrent, and closes the file.
     */
    static VALUE
    etc_endgrent(obj)
        VALUE obj;
    {
    #ifdef HAVE_GETGRENT
        endgrent();
    #endif
        return Qnil;
    }

endpwent()

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

[Source]

    /* Ends the process of scanning through the /etc/passwd file begun with
     * getpwent, and closes the file.
     */
    static VALUE
    etc_endpwent(obj)
        VALUE obj;
    {
    #ifdef HAVE_GETPWENT
        endpwent();
    #endif
        return Qnil;
    }

getgrent()

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 Struct::Group:

- Group#name contains the name of the group as a String.
- Group#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.
- Group#gid contains the group’s numeric ID as an integer.
- Group#mem is an Array of Strings containing the short login names of the members of the group.

[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 Struct::Group:
     *
     * - Group#name contains the name of the group as a String.
     *
     * - Group#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.
     *
     * - Group#gid contains the group's numeric ID as an integer.
     *
     * - Group#mem is an Array of Strings containing the short login names of the
     *   members of the group.
     */
    static VALUE
    etc_getgrent(obj)
        VALUE obj;
    {
    #ifdef HAVE_GETGRENT
        struct group *gr;

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

getgrgid(p1)

Returns information about the group with specified integer group id (gid), as found in /etc/group.

The information is returned as a Struct::Group; see getgrent above for details.

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

[Source]

    /* Returns information about the group with specified integer group id (gid),
     * as found in /etc/group.
     *
     * The information is returned as a Struct::Group; see getgrent above for
     * details.
     *
     * e.g.  Etc.getgrgid(100) -> #<struct Struct::Group name="users", passwd="x",
     * gid=100, mem=["meta", "root"]>
     *
     */
    static VALUE
    etc_getgrgid(obj, id)
        VALUE obj, id;
    {
    #ifdef HAVE_GETGRENT
        int gid;
        struct group *grp;

        rb_secure(4);
        gid = NUM2INT(id);
        grp = getgrgid(gid);
        if (grp == 0) rb_raise(rb_eArgError, "can't find group for %d", gid);
        return setup_group(grp);
    #else
        return Qnil;
    #endif
    }

getgrnam(p1)

Returns information about the group with specified String name, as found in /etc/group.

The information is returned as a Struct::Group; see getgrent above for details.

e.g. Etc.getgrnam(‘users’) -> #<struct Struct::Group name="users", passwd="x", gid=100, mem=["meta", "root"]>

[Source]

    /* Returns information about the group with specified String name, as found
     * in /etc/group.
     *
     * The information is returned as a Struct::Group; see getgrent above for
     * details.
     *
     * e.g.  Etc.getgrnam('users') -> #<struct Struct::Group name="users",
     * passwd="x", gid=100, mem=["meta", "root"]>
     *
     */
    static VALUE
    etc_getgrnam(obj, nam)
        VALUE obj, nam;
    {
    #ifdef HAVE_GETGRENT
        struct group *grp;

        rb_secure(4);
        SafeStringValue(nam);
        grp = getgrnam(RSTRING(nam)->ptr);
        if (grp == 0) rb_raise(rb_eArgError, "can't find group for %s", RSTRING(nam)->ptr);
        return setup_group(grp);
    #else
        return Qnil;
    #endif
    }

getlogin()

Returns the short user name of the currently logged in user.

e.g.

      Etc.getlogin -> 'guest'

[Source]

    /* Returns the short user name of the currently logged in user.
     *
     * e.g.
     *   Etc.getlogin -> 'guest'
     */
    static VALUE
    etc_getlogin(obj)
        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()

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 Struct::Passwd:

- Passwd#name contains the short login name of the user as a String.
- Passwd#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.
- Passwd#uid contains the integer user ID (uid) of the user.
- Passwd#gid contains the integer group ID (gid) of the user’s primary group.
- Passwd#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.
- Passwd#dir contains the path to the home directory of the user as a String.
- Passwd#shell contains the path to the login shell of the user as a String.

[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 Struct::Passwd:
     *
     * - Passwd#name contains the short login name of the user as a String.
     *
     * - Passwd#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.
     *
     * - Passwd#uid contains the integer user ID (uid) of the user.
     *
     * - Passwd#gid contains the integer group ID (gid) of the user's primary group.
     *
     * - Passwd#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.
     *
     * - Passwd#dir contains the path to the home directory of the user as a String.
     *
     * - Passwd#shell contains the path to the login shell of the user as a String.
     */
    static VALUE
    etc_getpwent(obj)
        VALUE obj;
    {
    #ifdef HAVE_GETPWENT
        struct passwd *pw;

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

getpwnam(p1)

Returns the /etc/passwd information for the user with specified login name.

The information is returned as a Struct::Passwd; see getpwent above for details.

e.g. * Etc.getpwnam(‘root’) -> #<struct Struct::Passwd name="root", passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">

[Source]

    /* Returns the /etc/passwd information for the user with specified login name.
     *
     * The information is returned as a Struct::Passwd; see getpwent above for
     * details.
     *
     * e.g.  * Etc.getpwnam('root') -> #<struct Struct::Passwd name="root",
     * passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">
     */
    static VALUE
    etc_getpwnam(obj, nam)
        VALUE obj, nam;
    {
    #ifdef HAVE_GETPWENT
        struct passwd *pwd;

        SafeStringValue(nam);
        pwd = getpwnam(RSTRING(nam)->ptr);
        if (pwd == 0) rb_raise(rb_eArgError, "can't find user for %s", RSTRING(nam)->ptr);
        return setup_passwd(pwd);
    #else
        return Qnil;
    #endif
    }

getpwuid(...)

Returns the /etc/passwd information for the user with specified integer user id (uid).

The information is returned as a Struct::Passwd; see getpwent above for details.

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

[Source]

    /* Returns the /etc/passwd information for the user with specified integer
     * user id (uid).
     *
     * The information is returned as a Struct::Passwd; see getpwent above for
     * details.
     *
     * e.g.  * Etc.getpwuid(0) -> #<struct Struct::Passwd name="root",
     * passwd="x", uid=0, gid=0, gecos="root",dir="/root", shell="/bin/bash">
     */
    static VALUE
    etc_getpwuid(argc, argv, obj)
        int argc;
        VALUE *argv;
        VALUE obj;
    {
    #if defined(HAVE_GETPWENT)
        VALUE id;
        int uid;
        struct passwd *pwd;

        rb_secure(4);
        if (rb_scan_args(argc, argv, "01", &id) == 1) {
    	uid = NUM2INT(id);
        }
        else {
    	uid = getuid();
        }
        pwd = getpwuid(uid);
        if (pwd == 0) rb_raise(rb_eArgError, "can't find user for %d", uid);
        return setup_passwd(pwd);
    #else
        return Qnil;
    #endif
    }

group()

Provides a convenient Ruby iterator which executes a block for each entry in the /etc/group file.

The code block is passed an Etc::Group struct; see getgrent above for details.

Example:

        require 'etc'

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

[Source]

    /* Provides a convenient Ruby iterator which executes a block for each entry
     * in the /etc/group file.
     *
     * The code block is passed an Etc::Group struct; see getgrent above for
     * details.
     *
     * Example:
     *
     *     require 'etc'
     *
     *     Etc.group {|g|
     *       puts g.name + ": " + g.mem.join(', ')
     *     }
     *
     */
    static VALUE
    etc_group(obj)
        VALUE obj;
    {
    #ifdef HAVE_GETGRENT
        struct group *grp;

        rb_secure(4);
        if (rb_block_given_p()) {
    	if (group_blocking) {
    	    rb_raise(rb_eRuntimeError, "parallel group iteration");
    	}
    	group_blocking = Qtrue;
    	rb_ensure(group_iterate, 0, group_ensure, 0);
        }
        if (grp = getgrent()) {
    	return setup_group(grp);
        }
    #endif
        return Qnil;
    }

passwd()

Provides a convenient Ruby iterator which executes a block for each entry in the /etc/passwd file.

The code block is passed an Etc::Passwd struct; see getpwent above for details.

Example:

        require 'etc'

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

[Source]

    /* Provides a convenient Ruby iterator which executes a block for each entry
     * in the /etc/passwd file.
     *
     * The code block is passed an Etc::Passwd struct; see getpwent above for
     * details.
     *
     * Example:
     *
     *     require 'etc'
     *
     *     Etc.passwd {|u|
     *       puts u.name + " = " + u.gecos
     *     }
     *
     */
    static VALUE
    etc_passwd(obj)
        VALUE obj;
    {
    #ifdef HAVE_GETPWENT
        struct passwd *pw;

        rb_secure(4);
        if (rb_block_given_p()) {
    	if (passwd_blocking) {
    	    rb_raise(rb_eRuntimeError, "parallel passwd iteration");
    	}
    	passwd_blocking = Qtrue;
    	rb_ensure(passwd_iterate, 0, passwd_ensure, 0);
        }
        if (pw = getpwent()) {
    	return setup_passwd(pw);
        }
    #endif
        return Qnil;
    }

setgrent()

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

[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(obj)
        VALUE obj;
    {
    #ifdef HAVE_GETGRENT
        setgrent();
    #endif
        return Qnil;
    }

setpwent()

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

[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(obj)
        VALUE obj;
    {
    #ifdef HAVE_GETPWENT
        setpwent();
    #endif
        return Qnil;
    }

[Validate]