123456789_123456789_123456789_123456789_123456789_

Class: Dir

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain:
self, ::Enumerable
Inherits: Object
Defined in: dir.c

Overview

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 (.).

Class Method Summary

Instance Attribute Summary

Instance Method Summary

::Enumerable - Included

#all?

Passes each element of the collection to the given block.

#any?

Passes each element of the collection to the given block.

#chain

Returns an enumerator object generated from this enumerator and given enumerables.

#chunk

Enumerates over the items, chunking them together based on the return value of the block.

#chunk_while

Creates an enumerator for each chunked elements.

#collect

Alias for Enumerable#map.

#collect_concat
#count

Returns the number of items in enum through enumeration.

#cycle

Calls block for each element of enum repeatedly n times or forever if none or nil is given.

#detect

Alias for Enumerable#find.

#drop

Drops first n elements from enum, and returns rest elements in an array.

#drop_while

Drops elements up to, but not including, the first element for which the block returns nil or false and returns an array containing the remaining elements.

#each_cons

Iterates the given block for each array of consecutive <n> elements.

#each_entry

Calls block once for each element in self, passing that element as a parameter, converting multiple values from yield to an array.

#each_slice

Iterates the given block for each slice of <n> elements.

#each_with_index

Calls block with two arguments, the item and its index, for each item in enum.

#each_with_object

Iterates the given block for each element with an arbitrary object given, and returns the initially given object.

#entries

Alias for Enumerable#to_a.

#filter

Returns an array containing all elements of enum for which the given block returns a true value.

#find

Passes each entry in enum to block.

#find_all
#find_index

Compares each entry in enum with value or passes to block.

#first

Returns the first element, or the first n elements, of the enumerable.

#flat_map

Returns a new array with the concatenated results of running block once for every element in enum.

#grep

Returns an array of every element in enum for which Pattern === element.

#grep_v

Inverted version of Enumerable#grep.

#group_by

Groups the collection by result of the block.

#include?
#inject

Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.

#lazy

Returns a lazy enumerator, whose methods map/collect, flat_map/collect_concat, select/find_all, reject, grep, grep_v, zip, take, take_while, drop, and drop_while enumerate values only on an as-needed basis.

#map

Returns a new array with the results of running block once for every element in enum.

#max

Returns the object in enum with the maximum value.

#max_by

Returns the object in enum that gives the maximum value from the given block.

#member?

Returns true if any member of enum equals obj.

#min

Returns the object in enum with the minimum value.

#min_by

Returns the object in enum that gives the minimum value from the given block.

#minmax

Returns a two element array which contains the minimum and the maximum value in the enumerable.

#minmax_by

Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block.

#none?

Passes each element of the collection to the given block.

#one?

Passes each element of the collection to the given block.

#partition

Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.

#reduce
#reject

Returns an array for all elements of enum for which the given block returns false.

#reverse_each

Builds a temporary array and traverses that array in reverse order.

#select
#slice_after

Creates an enumerator for each chunked elements.

#slice_before

Creates an enumerator for each chunked elements.

#slice_when

Creates an enumerator for each chunked elements.

#sort

Returns an array containing the items in enum sorted.

#sort_by

Sorts enum using a set of keys generated by mapping the values in enum through the given block.

#sum

Returns the sum of elements in an ::Enumerable.

#take

Returns first n elements from enum.

#take_while

Passes elements to the block until the block returns nil or false, then stops iterating and returns an array of all prior elements.

#to_a

Returns an array containing the items in enum.

#to_h

Returns the result of interpreting enum as a list of [key, value] pairs.

#uniq

Returns a new array by removing duplicate values in self.

#zip

Takes one element from enum and merges corresponding elements from each args.

Constructor Details

.new(string) ⇒ Dir .new(string, encoding: enc) ⇒ Dir

Returns a new directory object for the named directory.

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

[ GitHub ]

  
# File 'dir.c', line 524

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

    FilePathValue(dirname);
    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;
    RB_OBJ_WRITE(dir, &dp->path, Qnil);
    dp->enc = fsenc;
    path = RSTRING_PTR(dirname);
    dp->dir = opendir_without_gvl(path);
    if (dp->dir == NULL) {
	int e = errno;
	if (rb_gc_for_fd(e)) {
	    dp->dir = opendir_without_gvl(path);
	}
#ifdef HAVE_GETATTRLIST
	else if (e == 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_without_gvl(path);
	    }
	}
#endif
	if (dp->dir == NULL) {
	    RB_GC_GUARD(dirname);
	    rb_syserr_fail_path(e, orig);
	}
    }
    RB_OBJ_WRITE(dir, &dp->path, orig);

    return dir;
}

Class Method Details

.[](string [, string ...] [, base: path] ) ⇒ Array

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

[ GitHub ]

  
# File 'dir.c', line 2789

static VALUE
dir_s_aref(int argc, VALUE *argv, VALUE obj)
{
    VALUE opts, base;
    argc = rb_scan_args(argc, argv, "*:", NULL, &opts);
    dir_glob_options(opts, &base, NULL);
    if (argc == 1) {
	return rb_push_glob(argv[0], base, 0);
    }
    return dir_globs(argc, argv, base, 0);
}

.chdir([ string]) ⇒ 0 .chdir([ string]) {|path| ... } ⇒ Object

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
[ GitHub ]

  
# File 'dir.c', line 1078

static VALUE
dir_s_chdir(int argc, VALUE *argv, VALUE obj)
{
    VALUE path = Qnil;

    if (rb_check_arity(argc, 0, 1) == 1) {
        path = rb_str_encode_ospath(rb_get_path(argv[0]));
    }
    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);
    }
    else {
	char *p = RSTRING_PTR(path);
	int r = (int)(VALUE)rb_thread_call_without_gvl(nogvl_chdir, p,
							RUBY_UBF_IO, 0);
	if (r < 0)
	    rb_sys_fail_path(path);
    }

    return INT2FIX(0);
}

.children(dirname) ⇒ Array .children(dirname, encoding: enc) ⇒ Array

Returns an array containing all of the filenames except for “.” and “..” in the given directory. Will raise a ::SystemCallError if the named directory doesn’t exist.

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

Dir.children("testdir")   #=> ["config.h", "main.rb"]
[ GitHub ]

  
# File 'dir.c', line 3093

static VALUE
dir_s_children(int argc, VALUE *argv, VALUE io)
{
    VALUE dir;

    dir = dir_open_dir(argc, argv);
    return rb_ensure(dir_collect_children, dir, dir_close, dir);
}

.chroot(string) ⇒ 0

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.

[ GitHub ]

  
# File 'dir.c', line 1213

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 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0

Alias for .rmdir.

.each_child(dirname) {|filename| ... } ⇒ nil .each_child(dirname, encoding: enc) {|filename| ... } ⇒ nil .each_child(dirname) ⇒ Enumerator .each_child(dirname, encoding: enc) ⇒ Enumerator

Calls the block once for each entry except for “.” and “..” 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.each_child("testdir") {|x| puts "Got #{x}" }

produces:

Got config.h
Got main.rb
[ GitHub ]

  
# File 'dir.c', line 3021

static VALUE
dir_s_each_child(int argc, VALUE *argv, VALUE io)
{
    VALUE dir;

    RETURN_ENUMERATOR(io, argc, argv);
    dir = dir_open_dir(argc, argv);
    rb_ensure(dir_each_child, dir, dir_close, dir);
    return Qnil;
}

.empty?(path_name) ⇒ Boolean

Returns true if the named file is an empty directory, false if it is not a directory or non-empty.

[ GitHub ]

  
# File 'dir.c', line 3351

static VALUE
rb_dir_s_empty_p(VALUE obj, VALUE dirname)
{
    VALUE result, orig;
    const char *path;
    enum {false_on_notdir = 1};

    FilePathValue(dirname);
    orig = rb_str_dup_frozen(dirname);
    dirname = rb_str_encode_ospath(dirname);
    dirname = rb_str_dup_frozen(dirname);
    path = RSTRING_PTR(dirname);

#if defined HAVE_GETATTRLIST && defined ATTR_DIR_ENTRYCOUNT
    {
	u_int32_t attrbuf[SIZEUP32(fsobj_tag_t)];
	struct attrlist al = {ATTR_BIT_MAP_COUNT, 0, ATTR_CMN_OBJTAG,};
	if (getattrlist(path, &al, attrbuf, sizeof(attrbuf), 0) != 0)
	    rb_sys_fail_path(orig);
	if (*(const fsobj_tag_t *)(attrbuf+1) == VT_HFS) {
	    al.commonattr = 0;
	    al.dirattr = ATTR_DIR_ENTRYCOUNT;
	    if (getattrlist(path, &al, attrbuf, sizeof(attrbuf), 0) == 0) {
		if (attrbuf[0] >= 2 * sizeof(u_int32_t))
		    return attrbuf[1] ? Qfalse : Qtrue;
		if (false_on_notdir) return Qfalse;
	    }
	    rb_sys_fail_path(orig);
	}
    }
#endif

    result = (VALUE)rb_thread_call_without_gvl(nogvl_dir_empty_p, (void *)path,
					    RUBY_UBF_IO, 0);
    if (result == Qundef) {
	rb_sys_fail_path(orig);
    }
    return result;
}

.entries(dirname) ⇒ Array .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 encoding keyword argument specifies the encoding of the directory. If not specified, the filesystem encoding is used.

Dir.entries("testdir")   #=> [".", "..", "config.h", "main.rb"]
[ GitHub ]

  
# File 'dir.c', line 2985

static VALUE
dir_entries(int argc, VALUE *argv, VALUE io)
{
    VALUE dir;

    dir = dir_open_dir(argc, argv);
    return rb_ensure(dir_collect, dir, dir_close, dir);
}

.exist?(file_name) ⇒ Boolean

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

[ GitHub ]

  
# File 'dir.c', line 3293

VALUE
rb_file_directory_p(void)
{
}

.exists?(file_name) ⇒ Boolean

Deprecated method. Don’t use.

[ GitHub ]

  
# File 'dir.c', line 3305

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| ... } ⇒ nil .foreach(dirname, encoding: enc) {|filename| ... } ⇒ nil .foreach(dirname) ⇒ Enumerator .foreach(dirname, encoding: enc) ⇒ 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
[ GitHub ]

  
# File 'dir.c', line 2951

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

.getwdString .pwdString

Alias for .pwd.

.glob(pattern, [flags], [base: path]) ⇒ Array .glob(pattern, [flags], [base: path]) {|filename| ... } ⇒ nil

Expands pattern, which is a pattern string or an ::Array of pattern strings, and returns an array containing the matching filenames. If a block is given, calls the block once for each matching filename, passing the filename as a parameter to the block.

The optional base keyword argument specifies the base directory for interpreting relative pathnames instead of the current working directory. As the results are not prefixed with the base directory name in this case, you will need to prepend the base directory name if you want real paths.

Note that the pattern is not a regexp, it’s closer to a shell glob. See File.fnmatch for the meaning of the flags parameter. Case sensitivity depends on your system (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 / .* /mx 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"]
Dir.glob(["*.rb", "*.h"])           #=> ["main.rb", "config.h"]

rbfiles = File.join("**", "*.rb")
Dir.glob(rbfiles)                   #=> ["main.rb",
                                    #    "lib/song.rb",
                                    #    "lib/song/karaoke.rb"]

Dir.glob(rbfiles, base: "lib")      #=> ["song.rb",
                                    #    "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"]
[ GitHub ]

  
# File 'dir.c', line 2889

static VALUE
dir_s_glob(int argc, VALUE *argv, VALUE obj)
{
    VALUE str, rflags, ary, opts, base;
    int flags;

    argc = rb_scan_args(argc, argv, "11:", &str, &rflags, &opts);
    if (argc == 2)
	flags = NUM2INT(rflags);
    else
	flags = 0;
    dir_glob_options(opts, &base, &flags);

    ary = rb_check_array_type(str);
    if (NIL_P(ary)) {
	ary = rb_push_glob(str, base, flags);
    }
    else {
	VALUE v = ary;
	ary = dir_globs(RARRAY_LEN(v), RARRAY_CONST_PTR(v), base, flags);
	RB_GC_GUARD(v);
    }

    if (rb_block_given_p()) {
	rb_ary_each(ary);
	return Qnil;
    }
    return ary;
}

.home ⇒ "/home/me" .home("root") ⇒ "/root"

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

[ GitHub ]

  
# File 'dir.c', line 3264

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

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
[ GitHub ]

  
# File 'dir.c', line 1254

static VALUE
dir_s_mkdir(int argc, VALUE *argv, VALUE obj)
{
    struct mkdir_arg m;
    VALUE path, vmode;
    int r;

    if (rb_scan_args(argc, argv, "11", &path, &vmode) == 2) {
	m.mode = NUM2MODET(vmode);
    }
    else {
	m.mode = 0777;
    }

    path = check_dirname(path);
    m.path = RSTRING_PTR(path);
    r = (int)(VALUE)rb_thread_call_without_gvl(nogvl_mkdir, &m, RUBY_UBF_IO, 0);
    if (r < 0)
	rb_sys_fail_path(path);

    return INT2FIX(0);
}

.open(string) ⇒ Dir .open(string, encoding: enc) ⇒ Dir .open(string) {|aDir| ... } ⇒ Object .open(string, encoding: enc) {|aDir| ... } ⇒ Object

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

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

[ GitHub ]

  
# File 'dir.c', line 601

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

.getwdString .pwdString
Also known as: .getwd

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

Dir.chdir("/tmp")   #=> 0
Dir.getwd           #=> "/tmp"
Dir.pwd             #=> "/tmp"
[ GitHub ]

  
# File 'dir.c', line 1177

static VALUE
dir_s_getwd(VALUE dir)
{
    return rb_dir_getwd();
}

.delete(string) ⇒ 0 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0
Also known as: .delete, .unlink

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

[ GitHub ]

  
# File 'dir.c', line 1294

static VALUE
dir_s_rmdir(VALUE obj, VALUE dir)
{
    const char *p;
    int r;

    dir = check_dirname(dir);
    p = RSTRING_PTR(dir);
    r = (int)(VALUE)rb_thread_call_without_gvl(nogvl_rmdir, (void *)p, RUBY_UBF_IO, 0);
    if (r < 0)
	rb_sys_fail_path(dir);

    return INT2FIX(0);
}

Instance Attribute Details

#posInteger (rw) #tellInteger
Also known as: #tell

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

d = Dir.new("testdir")
d.tell   #=> 0
d.read   #=> "."
d.tell   #=> 12
[ GitHub ]

  
# File 'dir.c', line 881

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 (rw)

Synonym for #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                   #=> ".."
[ GitHub ]

  
# File 'dir.c', line 939

static VALUE
dir_set_pos(VALUE dir, VALUE pos)
{
    dir_seek(dir, pos);
    return pos;
}

#posInteger (readonly) #tellInteger

Alias for #pos.

Instance Method Details

#childrenArray

Returns an array containing all of the filenames except for “.” and “..” in this directory.

d = Dir.new("testdir")
d.children   #=> ["config.h", "main.rb"]
[ GitHub ]

  
# File 'dir.c', line 3070

static VALUE
dir_collect_children(VALUE dir)
{
    VALUE ary = rb_ary_new();
    dir_each_entry(dir, rb_ary_push, ary, TRUE);
    return ary;
}

#closenil

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

d = Dir.new("testdir")
d.close   #=> nil
[ GitHub ]

  
# File 'dir.c', line 980

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| ... } ⇒ Dir #eachEnumerator

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
[ GitHub ]

  
# File 'dir.c', line 827

static VALUE
dir_each(VALUE dir)
{
    RETURN_ENUMERATOR(dir, 0, 0);
    return dir_each_entry(dir, dir_yield, Qnil, FALSE);
}

#each_child {|filename| ... } ⇒ nil #each_childEnumerator

Calls the block once for each entry except for “.” and “..” 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_child  {|x| puts "Got #{x}" }

produces:

Got config.h
Got main.rb
[ GitHub ]

  
# File 'dir.c', line 3052

static VALUE
dir_each_child_m(VALUE dir)
{
    RETURN_ENUMERATOR(dir, 0, 0);
    return dir_each_entry(dir, dir_yield, Qnil, TRUE);
}

#filenoInteger

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.

[ GitHub ]

  
# File 'dir.c', line 692

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

#inspectString

Return a string describing this Dir object.

[ GitHub ]

  
# File 'dir.c', line 647

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, idTo_s, 0, 0);
}

#pathString? #to_pathString?
Also known as: #to_path

Returns the path parameter passed to dir’s constructor.

d = Dir.new("..")
d.path   #=> ".."
[ GitHub ]

  
# File 'dir.c', line 718

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

#readString?

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"
[ GitHub ]

  
# File 'dir.c', line 781

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 {
	int e = errno;
	if (e != 0) rb_syserr_fail(e, 0);
	return Qnil;		/* end of stream */
    }
}

#rewindDir

Repositions dir to the first entry.

d = Dir.new("testdir")
d.read     #=> "."
d.rewind   #=> #<Dir:0x401b3fb0>
d.read     #=> "."
[ GitHub ]

  
# File 'dir.c', line 960

static VALUE
dir_rewind(VALUE dir)
{
    struct dir_data *dirp;

    GetDIR(dir, dirp);
    rewinddir(dirp->dir);
    return dir;
}

#seek(integer) ⇒ Dir

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

d = Dir.new("testdir")   #=> #<Dir:0x401b3c40>
d.read                   #=> "."
i = d.tell               #=> 12
d.read                   #=> ".."
d.seek(i)                #=> #<Dir:0x401b3c40>
d.read                   #=> ".."
[ GitHub ]

  
# File 'dir.c', line 910

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

#pathString? #to_pathString?

Alias for #path.