class Dir

Like Dir.glob, but does not accept keyword argument flags, and may take multiple patterns as arguments:

Dir['*.rb', '*.h'].take(3) # => ["KNOWNBUGS.rb", "array.rb", "ast.rb"]

# File dir.rb, line 223
def self.[](*args, base: nil, sort: true)
  Primitive.dir_s_aref(args, base, sort)
end

Changes the current working directory.

With argument new_dirpath and no block, changes to the given dirpath:

Dir.pwd         # => "/example"
Dir.chdir('..') # => 0
Dir.pwd         # => "/"

With no argument and no block:

• Changes to the value of environment variable HOME if defined.

• Otherwise changes to the value of environment variable LOGDIR if defined.

• Otherwise makes no change.

With argument new_dirpath and a block, temporarily changes the working directory:

• Calls the block with the argument.

• Changes to the given directory.

• Executes the block (yielding the new path).

• Restores the previous working directory.

• Returns the block’s return value.

Example:

Dir.chdir('/var/spool/mail')
Dir.pwd   # => "/var/spool/mail"
Dir.chdir('/tmp') do
  Dir.pwd # => "/tmp"
end
Dir.pwd   # => "/var/spool/mail"

With no argument and a block, calls the block with the current working directory (string) and returns the block’s return value.

Calls to Dir.chdir with blocks may be nested:

Dir.chdir('/var/spool/mail')
Dir.pwd     # => "/var/spool/mail"
Dir.chdir('/tmp') do
  Dir.pwd   # => "/tmp"
  Dir.chdir('/usr') do
    Dir.pwd # => "/usr"
  end
  Dir.pwd   # => "/tmp"
end
Dir.pwd     # => "/var/spool/mail"

In a multi-threaded program an error is raised if a thread attempts to open a chdir block while another thread has one open, or a call to chdir without a block occurs inside a block passed to chdir (even in the same thread).

Raises an exception if the target directory does not exist.

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

    return chdir_path(path, true);
}

Returns an array of the entry names in the directory at dirpath except for '.' and '..'; sets the given encoding onto each returned entry name:

Dir.children('/example') # => ["config.h", "lib", "main.rb"]
Dir.children('/example').first.encoding
# => #<Encoding:UTF-8>
Dir.children('/example', encoding: 'US-ASCII').first.encoding
# => #<Encoding:US-ASCII>

See String Encoding.

Raises an exception if the directory does not exist.

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

Changes the root directory of the calling process to that specified in dirpath. The new root directory is used for pathnames beginning with '/'. The root directory is inherited by all children of the calling process.

Only a privileged process may call chroot.

See Linux chroot.

static VALUE
dir_s_chroot(VALUE dir, VALUE path)
{
    path = check_dirname(path);
    if (IO_WITHOUT_GVL_INT(nogvl_chroot, (void *)RSTRING_PTR(path)) == -1)
        rb_sys_fail_path(path);

    return INT2FIX(0);
}

Removes the directory entry (hard link) at dirpath, along with its associated inode:

dirpath = '/tmp/tmpdir'
Dir.mkdir(dirpath)
Dir.rmdir(dirpath) # => 0

Raises an exception if the directory is not empty.

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

    dir = check_dirname(dir);
    p = RSTRING_PTR(dir);
    r = IO_WITHOUT_GVL_INT(nogvl_rmdir, (void *)p);
    if (r < 0)
        rb_sys_fail_path(dir);

    return INT2FIX(0);
}

Like Dir.foreach, except that entries '.' and '..' are not included.

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

Returns whether dirpath specifies an empty directory:

dirpath = '/tmp/foo'
Dir.mkdir(dirpath)
Dir.empty?(dirpath)            # => true
Dir.empty?('/example')         # => false
Dir.empty?('/example/main.rb') # => false

Raises an exception if dirpath does not specify a directory or file in the underlying file system.

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,};
        struct getattrlist_args args = GETATTRLIST_ARGS(&al, attrbuf, 0);
        if (gvl_getattrlist(&args, path) != 0)
            rb_sys_fail_path(orig);
        if (*(const fsobj_tag_t *)(attrbuf+1) == VT_HFS) {
            al.commonattr = 0;
            al.dirattr = ATTR_DIR_ENTRYCOUNT;
            if (gvl_getattrlist(&args, path) == 0) {
                if (attrbuf[0] >= 2 * sizeof(u_int32_t))
                    return RBOOL(attrbuf[1] == 0);
                if (false_on_notdir) return Qfalse;
            }
            rb_sys_fail_path(orig);
        }
    }
#endif

    result = (VALUE)IO_WITHOUT_GVL(nogvl_dir_empty_p, (void *)path);
    if (FIXNUM_P(result)) {
        rb_syserr_fail_path((int)FIX2LONG(result), orig);
    }
    return result;
}

Returns an array of the entry names in the directory at dirpath; sets the given encoding onto each returned entry name:

Dir.entries('/example') # => ["config.h", "lib", "main.rb", "..", "."]
Dir.entries('/example').first.encoding
# => #<Encoding:UTF-8>
Dir.entries('/example', encoding: 'US-ASCII').first.encoding
# => #<Encoding:US-ASCII>

See String Encoding.

Raises an exception if the directory does not exist.

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

Returns whether dirpath is a directory in the underlying file system:

Dir.exist?('/example')         # => true
Dir.exist?('/nosuch')          # => false
Dir.exist?('/example/main.rb') # => false

Same as File.directory?.

VALUE
rb_file_directory_p(void)
{
}

Changes the current working directory to the directory specified by the integer file descriptor fd.

When passing a file descriptor over a UNIX socket or to a child process, using fchdir instead of chdir avoids the time-of-check to time-of-use vulnerability

With no block, changes to the directory given by fd:

Dir.chdir('/var/spool/mail')
Dir.pwd # => "/var/spool/mail"
dir  = Dir.new('/usr')
fd = dir.fileno
Dir.fchdir(fd)
Dir.pwd # => "/usr"

With a block, temporarily changes the working directory:

• Calls the block with the argument.

• Changes to the given directory.

• Executes the block (yields no args).

• Restores the previous working directory.

• Returns the block’s return value.

Example:

Dir.chdir('/var/spool/mail')
Dir.pwd # => "/var/spool/mail"
dir  = Dir.new('/tmp')
fd = dir.fileno
Dir.fchdir(fd) do
  Dir.pwd # => "/tmp"
end
Dir.pwd # => "/var/spool/mail"

This method uses the fchdir() function defined by POSIX 2008; the method is not implemented on non-POSIX platforms (raises NotImplementedError).

Raises an exception if the file descriptor is not valid.

In a multi-threaded program an error is raised if a thread attempts to open a chdir block while another thread has one open, or a call to chdir without a block occurs inside a block passed to chdir (even in the same thread).

static VALUE
dir_s_fchdir(VALUE klass, VALUE fd_value)
{
    int fd = RB_NUM2INT(fd_value);

    if (chdir_alone_block_p()) {
        struct fchdir_data args;
        args.old_dir = dir_s_alloc(klass);
        dir_initialize(NULL, args.old_dir, rb_fstring_cstr("."), Qnil);
        args.fd = fd;
        args.done = FALSE;
        return rb_ensure(fchdir_yield, (VALUE)&args, fchdir_restore, (VALUE)&args);
    }
    else {
        int r = IO_WITHOUT_GVL_INT(nogvl_fchdir, &fd);
        if (r < 0)
            rb_sys_fail("fchdir");
    }

    return INT2FIX(0);
}

Returns a new Dir object representing the directory specified by the given integer directory file descriptor fd:

d0 = Dir.new('..')
d1 = Dir.for_fd(d0.fileno)

Note that the returned d1 does not have an associated path:

d0.path # => '..'
d1.path # => nil

This method uses the fdopendir() function defined by POSIX 2008; the method is not implemented on non-POSIX platforms (raises NotImplementedError).

static VALUE
dir_s_for_fd(VALUE klass, VALUE fd)
{
    struct dir_data *dp;
    VALUE dir = TypedData_Make_Struct(klass, struct dir_data, &dir_data_type, dp);

    if (!(dp->dir = IO_WITHOUT_GVL(nogvl_fdopendir, (void *)(VALUE)NUM2INT(fd)))) {
        rb_sys_fail("fdopendir");
        UNREACHABLE_RETURN(Qnil);
    }

    RB_OBJ_WRITE(dir, &dp->path, Qnil);
    return dir;
}

Calls the block with each entry name in the directory at dirpath; sets the given encoding onto each passed entry_name:

Dir.foreach('/example') {|entry_name| p entry_name }

Output:

"config.h"
"lib"
"main.rb"
".."
"."

Encoding:

Dir.foreach('/example') {|entry_name| p entry_name.encoding; break }
Dir.foreach('/example', encoding: 'US-ASCII') {|entry_name| p entry_name.encoding; break }

Output:

#<Encoding:UTF-8>
#<Encoding:US-ASCII>

See String Encoding.

Returns an enumerator if no block is given.

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

Returns the path to the current working directory:

Dir.chdir("/tmp") # => 0
Dir.pwd           # => "/tmp"

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

Returns an array of filesystem entries; see Filename Globbing.

With a block given, calls the block with each of the selected entry names and returns nil:

Dir.glob('*.rb') {|entry_name| puts entry_name } # => nil

# File dir.rb, line 239
def self.glob(pattern, _flags = 0, flags: _flags, base: nil, sort: true)
  Primitive.attr! :use_block
  Primitive.dir_s_glob(pattern, flags, base, sort)
end

Returns the home directory path of the user specified with user_name if it is not nil, or the current login user:

Dir.home         # => "/home/me"
Dir.home('root') # => "/root"

Raises ArgumentError if user_name is not a user name.

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)) {
        StringValue(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));

}

Creates a directory in the underlying file system at dirpath with the given permissions; see File Permissions:

Dir.mkdir('foo')
File.stat(Dir.new('foo')).mode.to_s(8) # => "40775"
Dir.mkdir('bar', 0644)
File.stat(Dir.new('bar')).mode.to_s(8) # => "40644"
Dir.rmdir('foo')
Dir.rmdir('bar')

Argument permissions is ignored on Windows.

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 = IO_WITHOUT_GVL_INT(nogvl_mkdir, &m);
    if (r < 0)
        rb_sys_fail_path(path);

    return INT2FIX(0);
}

Dir.mktmpdir creates a temporary directory.

require 'tmpdir'
Dir.mktmpdir {|dir|
  # use the directory
}

The directory is created with 0700 permission. Application should not change the permission to make the temporary directory accessible from other users.

The prefix and suffix of the name of the directory is specified by the optional first argument, prefix_suffix.

• If it is not specified or nil, “d” is used as the prefix and no suffix is used.

• If it is a string, it is used as the prefix and no suffix is used.

• If it is an array, first element is used as the prefix and second element is used as a suffix.

Dir.mktmpdir {|dir| dir is ".../d..." }
Dir.mktmpdir("foo") {|dir| dir is ".../foo..." }
Dir.mktmpdir(["foo", "bar"]) {|dir| dir is ".../foo...bar" }

The directory is created under Dir.tmpdir or the optional second argument tmpdir if non-nil value is given.

Dir.mktmpdir {|dir| dir is "#{Dir.tmpdir}/d..." }
Dir.mktmpdir(nil, "/var/tmp") {|dir| dir is "/var/tmp/d..." }

If a block is given, it is yielded with the path of the directory. The directory and its contents are removed using FileUtils.remove_entry with force before Dir.mktmpdir returns. The value of the block is returned.

Dir.mktmpdir {|dir|
  # use the directory...
  open("#{dir}/foo", "w") { something using the file }
}

If a block is not given, The path of the directory is returned. In this case, Dir.mktmpdir doesn’t remove the directory.

dir = Dir.mktmpdir
begin
  # use the directory...
  open("#{dir}/foo", "w") { something using the file }
ensure
  # remove the directory.
  FileUtils.remove_entry dir
end

# File lib/tmpdir.rb, line 97
def self.mktmpdir(prefix_suffix=nil, *rest, **options, &block)
  base = nil
  path = Tmpname.create(prefix_suffix || "d", *rest, **options) {|path, _, _, d|
    base = d
    mkdir(path, 0700)
  }
  if block
    begin
      yield path.dup
    ensure
      unless base
        base = File.dirname(path)
        stat = File.stat(base)
        if stat.world_writable? and !stat.sticky?
          raise ArgumentError, "parent directory is world writable but not sticky: #{base}"
        end
      end
      FileUtils.remove_entry path, true
    end
  else
    path
  end
end

Returns a new Dir object for the directory at dirpath:

Dir.new('.') # => #<Dir:.>

The value given with optional keyword argument encoding specifies the encoding for the directory entry names; if nil (the default), the file system’s encoding is used:

Dir.new('.').read.encoding                       # => #<Encoding:UTF-8>
Dir.new('.', encoding: Encoding::US_ASCI).read.encoding # => #<Encoding:US-ASCII>

# File dir.rb, line 211
def initialize(name, encoding: nil)
  Primitive.dir_initialize(name, encoding)
end

Creates a new Dir object dir for the directory at dirpath.

With no block, the method equivalent to Dir.new(dirpath, encoding):

Dir.open('.') # => #<Dir:.>

With a block given, the block is called with the created dir; on block exit dir is closed and the block’s value is returned:

Dir.open('.') {|dir| dir.inspect } # => "#<Dir:.>"

The value given with optional keyword argument encoding specifies the encoding for the directory entry names; if nil (the default), the file system’s encoding is used:

Dir.open('.').read.encoding                       # => #<Encoding:UTF-8>
Dir.open('.', encoding: Encoding::US_ASCII).read.encoding # => #<Encoding:US-ASCII>

# File dir.rb, line 183
def self.open(name, encoding: nil, &block)
  dir = Primitive.dir_s_open(name, encoding)
  if block
    begin
      yield dir
    ensure
      Primitive.dir_s_close(dir)
    end
  else
    dir
  end
end

Returns the path to the current working directory:

Dir.chdir("/tmp") # => 0
Dir.pwd           # => "/tmp"

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

Removes the directory entry (hard link) at dirpath, along with its associated inode:

dirpath = '/tmp/tmpdir'
Dir.mkdir(dirpath)
Dir.rmdir(dirpath) # => 0

Raises an exception if the directory is not empty.

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

    dir = check_dirname(dir);
    p = RSTRING_PTR(dir);
    r = IO_WITHOUT_GVL_INT(nogvl_rmdir, (void *)p);
    if (r < 0)
        rb_sys_fail_path(dir);

    return INT2FIX(0);
}

Scans the entries in the directory at dirpath, except for '.' and '..'.

With no block given, returns entries, an array of 2-element arrays. Each nested array contains an entry name and its type:

Dir.scan('/example') # => [["config.h", :file], ["lib", :directory], ["main.rb", :file]]

With a block given, calls the block with each entry name and its type; returns nil:

entries = []
Dir.scan('/example') do |entry_name, entry_type|
  entries << [entry_name, entry_type]
end # => nil
entries # => [["config.h", :file], ["lib", :directory], ["main.rb", :file]]

The type symbol is one of :file, :directory, :characterSpecial, :blockSpecial, :fifo, :link, :socket, or :unknown.

The given encoding is used as the external encoding for each entry name:

Dir.scan('/example').first.first.encoding
# => #<Encoding:UTF-8>
Dir.scan('/example', encoding: 'US-ASCII').first.first.encoding
# => #<Encoding:US-ASCII>

See String Encoding.

Raises an exception if the directory does not exist.

static VALUE
dir_s_scan(int argc, VALUE *argv, VALUE klass)
{
    VALUE dir = dir_open_dir(argc, argv);
    return rb_ensure(dir_scan_children, dir, dir_close, dir);
}

Returns the operating system’s temporary file path.

require 'tmpdir'
Dir.tmpdir # => "/tmp"

# File lib/tmpdir.rb, line 25
def self.tmpdir
  Tmpname::TMPDIR_CANDIDATES.find do |name, dir|
    unless dir
      next if !(dir = ENV[name] rescue next) or dir.empty?
    end
    dir = File.expand_path(dir)
    stat = File.stat(dir) rescue next
    case
    when !stat.directory?
      warn "#{name} is not a directory: #{dir}"
    when !File.writable?(dir)
      # We call File.writable?, not stat.writable?, because you can't tell if a dir is actually
      # writable just from stat; OS mechanisms other than user/group/world bits can affect this.
      warn "#{name} is not writable: #{dir}"
    when stat.world_writable? && !stat.sticky?
      warn "#{name} is world-writable: #{dir}"
    else
      break dir
    end
  end or raise ArgumentError, "could not find a temporary directory"
end

Removes the directory entry (hard link) at dirpath, along with its associated inode:

dirpath = '/tmp/tmpdir'
Dir.mkdir(dirpath)
Dir.rmdir(dirpath) # => 0

Raises an exception if the directory is not empty.

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

    dir = check_dirname(dir);
    p = RSTRING_PTR(dir);
    r = IO_WITHOUT_GVL_INT(nogvl_rmdir, (void *)p);
    if (r < 0)
        rb_sys_fail_path(dir);

    return INT2FIX(0);
}

Changes the current working directory to self:

Dir.pwd # => "/"
dir = Dir.new('example')
dir.chdir
Dir.pwd # => "/example"

With a block, temporarily changes the working directory:

• Calls the block.

• Changes to the given directory.

• Executes the block (yields no args).

• Restores the previous working directory.

• Returns the block’s return value.

Uses Dir.fchdir if available, and Dir.chdir if not, see those methods for caveats.

static VALUE
dir_chdir(VALUE dir)
{
#if defined(HAVE_FCHDIR) && defined(HAVE_DIRFD) && HAVE_FCHDIR && HAVE_DIRFD
    return dir_s_fchdir(rb_cDir, dir_fileno(dir));
#else
    return chdir_path(dir_get(dir)->path, false);
#endif
}

Returns an array of the entry names in self except for '.' and '..':

dir = Dir.new('/example')
dir.children # => ["config.h", "lib", "main.rb"]

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

Closes the stream in self, if it is open, and returns nil; ignored if self is already closed:

dir = Dir.new('example')
dir.read     # => "."
dir.close     # => nil
dir.close     # => nil
dir.read # Raises IOError.

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

    dirp = dir_get(dir);
    if (!dirp->dir) return Qnil;
    close_dir_data(dirp);

    return Qnil;
}

Calls the block with each entry name in self:

Dir.new('example').each {|entry_name| p entry_name }

Output:

"."
".."
"config.h"
"lib"
"main.rb"

With no block given, returns an Enumerator.

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

Calls the block with each entry name in self except '.' and '..':

dir = Dir.new('/example')
dir.each_child {|entry_name| p entry_name }

Output:

"config.h"
"lib"
"main.rb"

If no block is given, returns an enumerator.

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

Returns the file descriptor used in dir.

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

This method uses the dirfd() function defined by POSIX 2008; the method is not implemented on non-POSIX platforms (raises NotImplementedError).

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

Returns a string description of self:

Dir.new('example').inspect # => "#<Dir:example>"

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

If self was created with a string path, returns that path:

dirpath = 'doc/tmp'
Dir.mkdir(dirpath)
dir = Dir.new(dirpath)
dir.path # => "../ruby/doc/syntax"

The path remains even when the directory is removed:

Dir.rmdir(dirpath)
dir.path # => "../ruby/doc/syntax"

If self was created with a file descriptor, returns nil:

dir0 = Dir.new('.')
fd = dir0.fileno # => 8
dir1 = Dir.for_fd(fd)
dir1.path        # => nil

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

Sets the position in self and returns position. The value of position should have been returned from an earlier call to tell; if not, the return values from subsequent calls to read are unspecified.

See Dir As Stream-Like.

Examples:

dir = Dir.new('example')
dir.pos      # => 0
dir.pos = 3  # => 3
dir.pos      # => 3
dir.pos = 30 # => 30
dir.pos      # => 5

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

Reads and returns the next entry name from self; returns nil if at end-of-stream; see Dir As Stream-Like:

dir = Dir.new('example')
dir.read # => "."
dir.read # => ".."
dir.read # => "config.h"

static VALUE
dir_read(VALUE dir)
{
    struct dir_data *dirp;
    struct dirent *dp;

    GetDIR(dir, dirp);
    rb_errno_set(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 */
    }
}

Sets the position in self to zero; see Dir As Stream-Like:

dir = Dir.new('example')
dir.read    # => "."
dir.read    # => ".."
dir.pos     # => 2
dir.rewind  # => #<Dir:example>
dir.pos     # => 0

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

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

Scans the entries in self, except for '.' and '..'.

With no block given, returns entries, an array of 2-element arrays. Each nested array contains an entry name and its type:

dir = Dir.new('/example')
dir.scan # => [["config.h", :file], ["lib", :directory], ["main.rb", :file]]

With a block given, calls the block with each entry name and its type; returns nil:

entries = []
dir.scan do |entry_name, entry_type|
  entries << [entry_name, entry_type]
end # => nil
entries # => [["config.h", :file], ["lib", :directory], ["main.rb", :file]]

static VALUE
dir_scan_children(VALUE dir)
{
    if (rb_block_given_p()) {
        dir_each_entry(dir, dir_yield_with_type, Qnil, TRUE);
        return Qnil;
    }
    else {
        VALUE ary = rb_ary_new();
        dir_each_entry(dir, dir_yield_with_type, ary, TRUE);
        return ary;
    }
}

Sets the position in self and returns self. The value of position should have been returned from an earlier call to tell; if not, the return values from subsequent calls to read are unspecified.

See Dir As Stream-Like.

Examples:

dir = Dir.new('example')
dir.pos      # => 0
dir.seek(3)  # => #<Dir:example>
dir.pos      # => 3
dir.seek(30) # => #<Dir:example>
dir.pos      # => 5

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

Returns the current position of self; see Dir As Stream-Like:

dir = Dir.new('example')
dir.tell  # => 0
dir.read  # => "."
dir.tell  # => 1

static VALUE
dir_tell(VALUE dir)
{
    struct dir_data *dirp;
    long pos;

    GetDIR(dir, dirp);
    if((pos = telldir(dirp->dir)) < 0)
        rb_sys_fail("telldir");
    return rb_int2inum(pos);
}