Class: Dir (Ruby 2.3.4)

    In Files

    • dir.c

    Class/Module Index [+]

    Quicksearch

    Dir

    Objects of class Dir are directory streams representing directories in the underlying file system. They provide a variety of ways to list directories and their contents. See also File.

    The directory used in these examples contains the two regular files (config.h and main.rb), the parent directory (..), and the directory itself (.).

    Public Class Methods

    Dir[ string [, string ...] ] → array click to toggle source

    Equivalent to calling Dir.glob([string,...],0).

     
                   static VALUE
    dir_s_aref(int argc, VALUE *argv, VALUE obj)
    {
        if (argc == 1) {
            return rb_push_glob(argv[0], 0);
        }
        return dir_globs(argc, argv, 0);
    }
                
    chdir( [ string] ) → 0 click to toggle source
    chdir( [ string] ) {| path | block } → anObject

    Changes the current working directory of the process to the given string. When called without an argument, changes the directory to the value of the environment variable HOME, or LOGDIR. SystemCallError (probably Errno::ENOENT) if the target directory does not exist.

    If a block is given, it is passed the name of the new current directory, and the block is executed with that as the current directory. The original working directory is restored when the block exits. The return value of chdir is the value of the block. chdir blocks can be nested, but in a multi-threaded program an error will be raised if a thread attempts to open a chdir block while another thread has one open.

    Dir.chdir("/var/spool/mail")
    puts Dir.pwd
    Dir.chdir("/tmp") do
      puts Dir.pwd
      Dir.chdir("/usr") do
        puts Dir.pwd
      end
      puts Dir.pwd
    end
    puts Dir.pwd
    

    produces:

    /var/spool/mail
    /tmp
    /usr
    /tmp
    /var/spool/mail
     
                   static VALUE
    dir_s_chdir(int argc, VALUE *argv, VALUE obj)
    {
        VALUE path = Qnil;
    
        if (rb_scan_args(argc, argv, "01", &path) == 1) {
            FilePathValue(path);
            path = rb_str_encode_ospath(path);
        }
        else {
            const char *dist = getenv("HOME");
            if (!dist) {
                dist = getenv("LOGDIR");
                if (!dist) rb_raise(rb_eArgError, "HOME/LOGDIR not set");
            }
            path = rb_str_new2(dist);
        }
    
        if (chdir_blocking > 0) {
            if (!rb_block_given_p() || rb_thread_current() != chdir_thread)
                rb_warn("conflicting chdir during another chdir block");
        }
    
        if (rb_block_given_p()) {
            struct chdir_data args;
    
            args.old_path = rb_str_encode_ospath(rb_dir_getwd());
            args.new_path = path;
            args.done = FALSE;
            return rb_ensure(chdir_yield, (VALUE)&args, chdir_restore, (VALUE)&args);
        }
        dir_chdir(path);
    
        return INT2FIX(0);
    }
                
    chroot( string ) → 0 click to toggle source

    Changes this process’s idea of the file system root. Only a privileged process may make this call. Not available on all platforms. On Unix systems, see chroot(2) for more information.

     
                   static VALUE
    dir_s_chroot(VALUE dir, VALUE path)
    {
        path = check_dirname(path);
        if (chroot(RSTRING_PTR(path)) == -1)
            rb_sys_fail_path(path);
    
        return INT2FIX(0);
    }
                
    delete( string ) → 0 click to toggle source

    Deletes the named directory. Raises a subclass of SystemCallError if the directory isn’t empty.

     
                   static VALUE
    dir_s_rmdir(VALUE obj, VALUE dir)
    {
        dir = check_dirname(dir);
        if (rmdir(RSTRING_PTR(dir)) < 0)
            rb_sys_fail_path(dir);
    
        return INT2FIX(0);
    }
                
    entries( dirname ) → array click to toggle source
    entries( dirname, encoding: enc ) → array

    Returns an array containing all of the filenames in the given directory. Will raise a SystemCallError if the named directory doesn’t exist.

    The optional enc argument specifies the encoding of the directory. If not specified, the filesystem encoding is used.

    Dir.entries("testdir")   #=> [".", "..", "config.h", "main.rb"]
    
     
                   static VALUE
    dir_entries(int argc, VALUE *argv, VALUE io)
    {
        VALUE dir;
    
        dir = dir_open_dir(argc, argv);
        return rb_ensure(rb_Array, dir, dir_close, dir);
    }
                
    exist?(file_name) → true or false click to toggle source

    Returns true if the named file is a directory, false otherwise.

     
                   VALUE
    rb_file_directory_p(void)
    {
    }
                
    exists?(file_name) → true or false click to toggle source

    Deprecated method. Don’t use.

     
                   static VALUE
    rb_dir_exists_p(VALUE obj, VALUE fname)
    {
        rb_warning("Dir.exists? is a deprecated name, use Dir.exist? instead");
        return rb_file_directory_p(obj, fname);
    }
                
    foreach( dirname ) {| filename | block } → nil click to toggle source
    foreach( dirname, encoding: enc ) {| filename | block } → nil
    foreach( dirname ) → an_enumerator
    foreach( dirname, encoding: enc ) → an_enumerator

    Calls the block once for each entry in the named directory, passing the filename of each entry as a parameter to the block.

    If no block is given, an enumerator is returned instead.

    Dir.foreach("testdir") {|x| puts "Got #{x}" }
    

    produces:

    Got .
    Got ..
    Got config.h
    Got main.rb
     
                   static VALUE
    dir_foreach(int argc, VALUE *argv, VALUE io)
    {
        VALUE dir;
    
        RETURN_ENUMERATOR(io, argc, argv);
        dir = dir_open_dir(argc, argv);
        rb_ensure(dir_each, dir, dir_close, dir);
        return Qnil;
    }
                
    getwd → string click to toggle source

    Returns the path to the current working directory of this process as a string.

    Dir.chdir("/tmp")   #=> 0
    Dir.getwd           #=> "/tmp"
    Dir.pwd             #=> "/tmp"
    
     
                   static VALUE
    dir_s_getwd(VALUE dir)
    {
        return rb_dir_getwd();
    }
                
    glob( pattern, [flags] ) → matches click to toggle source
    glob( pattern, [flags] ) { |filename| block } → nil

    Expands pattern, which is an Array of patterns or a pattern String, and returns the results as matches or as arguments given to the block.

    Note that this pattern is not a regexp, it’s closer to a shell glob. See File.fnmatch for the meaning of the flags parameter. Note that case sensitivity depends on your system (so File::FNM_CASEFOLD is ignored), as does the order in which the results are returned.

    *

    Matches any file. Can be restricted by other values in the glob. Equivalent to / .* /x in regexp.

    *

    Matches all files

    c*

    Matches all files beginning with c

    *c

    Matches all files ending with c

    *c*

    Match all files that have c in them (including at the beginning or end).

    Note, this will not match Unix-like hidden files (dotfiles). In order to include those in the match results, you must use the File::FNM_DOTMATCH flag or something like "{*,.*}".

    **

    Matches directories recursively.

    ?

    Matches any one character. Equivalent to /.{1}/ in regexp.

    [set]

    Matches any one character in set. Behaves exactly like character sets in Regexp, including set negation ([^a-z]).

    {p,q}

    Matches either literal p or literal q. Equivalent to pattern alternation in regexp.

    Matching literals may be more than one character in length. More than two literals may be specified.

    \

    Escapes the next metacharacter.

    Note that this means you cannot use backslash on windows as part of a glob, i.e. Dir["c:\foo*"] will not work, use Dir["c:/foo*"] instead.

    Examples:

    Dir["config.?"]                     #=> ["config.h"]
    Dir.glob("config.?")                #=> ["config.h"]
    Dir.glob("*.[a-z][a-z]")            #=> ["main.rb"]
    Dir.glob("*.[^r]*")                 #=> ["config.h"]
    Dir.glob("*.{rb,h}")                #=> ["main.rb", "config.h"]
    Dir.glob("*")                       #=> ["config.h", "main.rb"]
    Dir.glob("*", File::FNM_DOTMATCH)   #=> [".", "..", "config.h", "main.rb"]
    
    rbfiles = File.join("**", "*.rb")
    Dir.glob(rbfiles)                   #=> ["main.rb",
                                        #    "lib/song.rb",
                                        #    "lib/song/karaoke.rb"]
    libdirs = File.join("**", "lib")
    Dir.glob(libdirs)                   #=> ["lib"]
    
    librbfiles = File.join("**", "lib", "**", "*.rb")
    Dir.glob(librbfiles)                #=> ["lib/song.rb",
                                        #    "lib/song/karaoke.rb"]
    
    librbfiles = File.join("**", "lib", "*.rb")
    Dir.glob(librbfiles)                #=> ["lib/song.rb"]
    
     
                   static VALUE
    dir_s_glob(int argc, VALUE *argv, VALUE obj)
    {
        VALUE str, rflags, ary;
        int flags;
    
        if (rb_scan_args(argc, argv, "11", &str, &rflags) == 2)
            flags = NUM2INT(rflags);
        else
            flags = 0;
    
        ary = rb_check_array_type(str);
        if (NIL_P(ary)) {
            ary = rb_push_glob(str, flags);
        }
        else {
            VALUE v = ary;
            ary = dir_globs(RARRAY_LEN(v), RARRAY_CONST_PTR(v), flags);
            RB_GC_GUARD(v);
        }
    
        if (rb_block_given_p()) {
            rb_ary_each(ary);
            return Qnil;
        }
        return ary;
    }
                
    home() → "/home/me" click to toggle source
    home("root") → "/root"

    Returns the home directory of the current user or the named user if given.

     
                   static VALUE
    dir_s_home(int argc, VALUE *argv, VALUE obj)
    {
        VALUE user;
        const char *u = 0;
    
        rb_check_arity(argc, 0, 1);
        user = (argc > 0) ? argv[0] : Qnil;
        if (!NIL_P(user)) {
            SafeStringValue(user);
            rb_must_asciicompat(user);
            u = StringValueCStr(user);
            if (*u) {
                return rb_home_dir_of(user, rb_str_new(0, 0));
            }
        }
        return rb_default_home_dir(rb_str_new(0, 0));
    
    }
                
    mkdir( string [, integer] ) → 0 click to toggle source

    Makes a new directory named by string, with permissions specified by the optional parameter anInteger. The permissions may be modified by the value of File::umask, and are ignored on NT. Raises a SystemCallError if the directory cannot be created. See also the discussion of permissions in the class documentation for File.

    Dir.mkdir(File.join(Dir.home, ".foo"), 0700) #=> 0
    
     
                   static VALUE
    dir_s_mkdir(int argc, VALUE *argv, VALUE obj)
    {
        VALUE path, vmode;
        int mode;
    
        if (rb_scan_args(argc, argv, "11", &path, &vmode) == 2) {
            mode = NUM2INT(vmode);
        }
        else {
            mode = 0777;
        }
    
        path = check_dirname(path);
        if (mkdir(RSTRING_PTR(path), mode) == -1)
            rb_sys_fail_path(path);
    
        return INT2FIX(0);
    }
                
    new( string ) → aDir click to toggle source
    new( string, encoding: enc ) → aDir

    Returns a new directory object for the named directory.

    The optional enc argument specifies the encoding of the directory. If not specified, the filesystem encoding is used.

     
                   static VALUE
    dir_initialize(int argc, VALUE *argv, VALUE dir)
    {
        struct dir_data *dp;
        rb_encoding  *fsenc;
        VALUE dirname, opt, orig;
        static ID keyword_ids[1];
        const char *path;
    
        if (!keyword_ids[0]) {
            keyword_ids[0] = rb_id_encoding();
        }
    
        fsenc = rb_filesystem_encoding();
    
        rb_scan_args(argc, argv, "1:", &dirname, &opt);
    
        if (!NIL_P(opt)) {
            VALUE enc;
            rb_get_kwargs(opt, keyword_ids, 0, 1, &enc);
            if (enc != Qundef && !NIL_P(enc)) {
                fsenc = rb_to_encoding(enc);
            }
        }
    
        GlobPathValue(dirname, FALSE);
        orig = rb_str_dup_frozen(dirname);
        dirname = rb_str_encode_ospath(dirname);
        dirname = rb_str_dup_frozen(dirname);
    
        TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dp);
        if (dp->dir) closedir(dp->dir);
        dp->dir = NULL;
        dp->path = Qnil;
        dp->enc = fsenc;
        path = RSTRING_PTR(dirname);
        dp->dir = opendir(path);
        if (dp->dir == NULL) {
            if (rb_gc_for_fd(errno)) {
                dp->dir = opendir(path);
            }
    #ifdef HAVE_GETATTRLIST
            else if (errno == EIO) {
                u_int32_t attrbuf[1];
                struct attrlist al = {ATTR_BIT_MAP_COUNT, 0};
                if (getattrlist(path, &al, attrbuf, sizeof(attrbuf), FSOPT_NOFOLLOW) == 0) {
                    dp->dir = opendir(path);
                }
            }
    #endif
            if (dp->dir == NULL) {
                RB_GC_GUARD(dirname);
                rb_sys_fail_path(orig);
            }
        }
        dp->path = orig;
    
        return dir;
    }
                
    open( string ) → aDir click to toggle source
    open( string, encoding: enc ) → aDir
    open( string ) {| aDir | block } → anObject
    open( string, encoding: enc ) {| aDir | block } → anObject

    The optional enc argument specifies the encoding of the directory. If not specified, the filesystem encoding is used.

    With no block, open is a synonym for Dir::new. If a block is present, it is passed aDir as a parameter. The directory is closed at the end of the block, and Dir::open returns the value of the block.

     
                   static VALUE
    dir_s_open(int argc, VALUE *argv, VALUE klass)
    {
        struct dir_data *dp;
        VALUE dir = TypedData_Make_Struct(klass, struct dir_data, &dir_data_type, dp);
    
        dir_initialize(argc, argv, dir);
        if (rb_block_given_p()) {
            return rb_ensure(rb_yield, dir, dir_close, dir);
        }
    
        return dir;
    }
                
    pwd → string click to toggle source

    Returns the path to the current working directory of this process as a string.

    Dir.chdir("/tmp")   #=> 0
    Dir.getwd           #=> "/tmp"
    Dir.pwd             #=> "/tmp"
    
     
                   static VALUE
    dir_s_getwd(VALUE dir)
    {
        return rb_dir_getwd();
    }
                
    rmdir( string ) → 0 click to toggle source

    Deletes the named directory. Raises a subclass of SystemCallError if the directory isn’t empty.

     
                   static VALUE
    dir_s_rmdir(VALUE obj, VALUE dir)
    {
        dir = check_dirname(dir);
        if (rmdir(RSTRING_PTR(dir)) < 0)
            rb_sys_fail_path(dir);
    
        return INT2FIX(0);
    }
                

    Public Instance Methods

    close → nil click to toggle source

    Closes the directory stream. Calling this method on closed Dir object is ignored since Ruby 2.3.

    d = Dir.new("testdir")
    d.close   #=> nil
    
     
                   static VALUE
    dir_close(VALUE dir)
    {
        struct dir_data *dirp;
    
        dirp = dir_get(dir);
        if (!dirp->dir) return Qnil;
        closedir(dirp->dir);
        dirp->dir = NULL;
    
        return Qnil;
    }
                
    each { |filename| block } → dir click to toggle source
    each → an_enumerator

    Calls the block once for each entry in this directory, passing the filename of each entry as a parameter to the block.

    If no block is given, an enumerator is returned instead.

    d = Dir.new("testdir")
    d.each  {|x| puts "Got #{x}" }
    

    produces:

    Got .
    Got ..
    Got config.h
    Got main.rb
     
                   static VALUE
    dir_each(VALUE dir)
    {
        struct dir_data *dirp;
        struct dirent *dp;
        IF_NORMALIZE_UTF8PATH(int norm_p);
    
        RETURN_ENUMERATOR(dir, 0, 0);
        GetDIR(dir, dirp);
        rewinddir(dirp->dir);
        IF_NORMALIZE_UTF8PATH(norm_p = need_normalization(dirp->dir, RSTRING_PTR(dirp->path)));
        while ((dp = READDIR(dirp->dir, dirp->enc)) != NULL) {
            const char *name = dp->d_name;
            size_t namlen = NAMLEN(dp);
            VALUE path;
    #if NORMALIZE_UTF8PATH
            if (norm_p && has_nonascii(name, namlen) &&
                !NIL_P(path = rb_str_normalize_ospath(name, namlen))) {
                path = rb_external_str_with_enc(path, dirp->enc);
            }
            else
    #endif
            path = rb_external_str_new_with_enc(name, namlen, dirp->enc);
            rb_yield(path);
            if (dirp->dir == NULL) dir_closed();
        }
        return dir;
    }
                
    fileno → integer click to toggle source

    Returns the file descriptor used in dir.

    d = Dir.new("..")
    d.fileno   #=> 8
    

    This method uses dirfd() function defined by POSIX 2008. NotImplementedError is raised on other platforms, such as Windows, which doesn’t provide the function.

     
                   static VALUE
    dir_fileno(VALUE dir)
    {
        struct dir_data *dirp;
        int fd;
    
        GetDIR(dir, dirp);
        fd = dirfd(dirp->dir);
        if (fd == -1)
            rb_sys_fail("dirfd");
        return INT2NUM(fd);
    }
                
    inspect → string click to toggle source

    Return a string describing this Dir object.

     
                   static VALUE
    dir_inspect(VALUE dir)
    {
        struct dir_data *dirp;
    
        TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dirp);
        if (!NIL_P(dirp->path)) {
            VALUE str = rb_str_new_cstr("#<");
            rb_str_append(str, rb_class_name(CLASS_OF(dir)));
            rb_str_cat2(str, ":");
            rb_str_append(str, dirp->path);
            rb_str_cat2(str, ">");
            return str;
        }
        return rb_funcallv(dir, rb_intern("to_s"), 0, 0);
    }
                
    path → string or nil click to toggle source

    Returns the path parameter passed to dir’s constructor.

    d = Dir.new("..")
    d.path   #=> ".."
    
     
                   static VALUE
    dir_path(VALUE dir)
    {
        struct dir_data *dirp;
    
        TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dirp);
        if (NIL_P(dirp->path)) return Qnil;
        return rb_str_dup(dirp->path);
    }
                
    pos → integer click to toggle source

    Returns the current position in dir. See also Dir#seek.

    d = Dir.new("testdir")
    d.tell   #=> 0
    d.read   #=> "."
    d.tell   #=> 12
    
     
                   static VALUE
    dir_tell(VALUE dir)
    {
        struct dir_data *dirp;
        long pos;
    
        GetDIR(dir, dirp);
        pos = telldir(dirp->dir);
        return rb_int2inum(pos);
    }
                
    pos = integer → integer click to toggle source

    Synonym for Dir#seek, but returns the position parameter.

    d = Dir.new("testdir")   #=> #<Dir:0x401b3c40>
    d.read                   #=> "."
    i = d.pos                #=> 12
    d.read                   #=> ".."
    d.pos = i                #=> 12
    d.read                   #=> ".."
    
     
                   static VALUE
    dir_set_pos(VALUE dir, VALUE pos)
    {
        dir_seek(dir, pos);
        return pos;
    }
                
    read → string or nil click to toggle source

    Reads the next entry from dir and returns it as a string. Returns nil at the end of the stream.

    d = Dir.new("testdir")
    d.read   #=> "."
    d.read   #=> ".."
    d.read   #=> "config.h"
    
     
                   static VALUE
    dir_read(VALUE dir)
    {
        struct dir_data *dirp;
        struct dirent *dp;
    
        GetDIR(dir, dirp);
        errno = 0;
        if ((dp = READDIR(dirp->dir, dirp->enc)) != NULL) {
            return rb_external_str_new_with_enc(dp->d_name, NAMLEN(dp), dirp->enc);
        }
        else {
            if (errno != 0) rb_sys_fail(0);
            return Qnil;           /* end of stream */
        }
    }
                
    rewind → dir click to toggle source

    Repositions dir to the first entry.

    d = Dir.new("testdir")
    d.read     #=> "."
    d.rewind   #=> #<Dir:0x401b3fb0>
    d.read     #=> "."
    
     
                   static VALUE
    dir_rewind(VALUE dir)
    {
        struct dir_data *dirp;
    
        GetDIR(dir, dirp);
        rewinddir(dirp->dir);
        return dir;
    }
                
    seek( integer ) → dir click to toggle source

    Seeks to a particular location in dir. integer must be a value returned by Dir#tell.

    d = Dir.new("testdir")   #=> #<Dir:0x401b3c40>
    d.read                   #=> "."
    i = d.tell               #=> 12
    d.read                   #=> ".."
    d.seek(i)                #=> #<Dir:0x401b3c40>
    d.read                   #=> ".."
    
     
                   static VALUE
    dir_seek(VALUE dir, VALUE pos)
    {
        struct dir_data *dirp;
        long p = NUM2LONG(pos);
    
        GetDIR(dir, dirp);
        seekdir(dirp->dir, p);
        return dir;
    }
                
    tell → integer click to toggle source

    Returns the current position in dir. See also Dir#seek.

    d = Dir.new("testdir")
    d.tell   #=> 0
    d.read   #=> "."
    d.tell   #=> 12
    
     
                   static VALUE
    dir_tell(VALUE dir)
    {
        struct dir_data *dirp;
        long pos;
    
        GetDIR(dir, dirp);
        pos = telldir(dirp->dir);
        return rb_int2inum(pos);
    }
                
    to_path → string or nil click to toggle source

    Returns the path parameter passed to dir’s constructor.

    d = Dir.new("..")
    d.path   #=> ".."
    
     
                   static VALUE
    dir_path(VALUE dir)
    {
        struct dir_data *dirp;
    
        TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dirp);
        if (NIL_P(dirp->path)) return Qnil;
        return rb_str_dup(dirp->path);
    }