class Dir - RDoc Documentation (original) (raw)

An object of class Dir represents a directory in the underlying file system.

It consists mainly of:

About the Examples ↑

Some examples on this page use this simple file tree:

example/ ├── config.h ├── lib/ │ ├── song/ │ │ └── karaoke.rb │ └── song.rb └── main.rb

Others use the file tree for the Ruby project itself.

Dir As Array-Like ↑

A Dir object is in some ways array-like:

Dir As Stream-Like ↑

A Dir object is in some ways stream-like.

The stream is initially open for reading, but may be closed manually (using method close), and will be closed on block exit if created by Dir.open called with a block. The closed stream may not be further manipulated, and may not be reopened.

The stream has a position, which is the index of an entry in the directory:

Examples (using the simple file tree):

dir = Dir.new('example') dir.pos

dir.read dir.read dir.read dir.read dir.read dir.pos
dir.read dir.pos

dir.rewind dir.pos

dir.pos = 3 dir.pos

dir.seek(4) dir.pos

dir.close dir.read

What’s Here ↑

First, what’s elsewhere. Class Dir:

Here, class Dir provides methods that are useful for:

Reading ↑

Setting ↑

Querying ↑

Iterating ↑

Other ↑

Public Class Methods

Dir[*patterns, base: nil, sort: true] → array click to toggle source

Calls Dir.glob with argument patterns and the values of keyword arguments base and sort; returns the array of selected entry names.

def self.[](*args, base: nil, sort: true) Primitive.dir_s_aref(args, base, sort) end

chdir(new_dirpath) → 0 click to toggle source

chdir → 0

chdir(new_dirpath) {|new_dirpath| ... } → object

chdir {|cur_dirpath| ... } → object

Changes the current working directory.

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

Dir.pwd
Dir.chdir('..') Dir.pwd

With no argument and no block:

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

Example:

Dir.chdir('/var/spool/mail') Dir.pwd
Dir.chdir('/tmp') do Dir.pwd end Dir.pwd

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
Dir.chdir('/tmp') do Dir.pwd
Dir.chdir('/usr') do Dir.pwd end Dir.pwd
end Dir.pwd

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

}

children(dirpath) → array click to toggle source

children(dirpath, encoding: 'UTF-8') → array

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') Dir.children('/example').first.encoding

Dir.children('/example', encoding: 'US-ASCII').first.encoding

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

}

chroot(dirpath) → 0 click to toggle source

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

}

rmdir(dirpath) → 0 click to toggle source

Removes the directory at dirpath from the underlying file system:

Dir.rmdir('foo')

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

}

each_child(dirpath) {|entry_name| ... } → nil click to toggle source

each_child(dirpath, encoding: 'UTF-8') {|entry_name| ... } → nil

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;

}

empty?(dirpath) → true or false click to toggle source

Returns whether dirpath specifies an empty directory:

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

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;

}

entries(dirname, encoding: 'UTF-8') → array click to toggle source

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

Dir.entries('/example') Dir.entries('/example').first.encoding

Dir.entries('/example', encoding: 'US-ASCII').first.encoding

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

}

exist?(dirpath) → true or false click to toggle source

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

Dir.exist?('/example')
Dir.exist?('/nosuch')
Dir.exist?('/example/main.rb')

Same as File.directory?.

VALUE rb_file_directory_p(void) { }

fchdir(fd) → 0 click to toggle source

fchdir(fd) { ... } → object

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 dir = Dir.new('/usr') fd = dir.fileno Dir.fchdir(fd) Dir.pwd

With a block, temporarily changes the working directory:

Example:

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

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

}

for_fd(fd) → dir click to toggle source

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

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;

}

foreach(dirpath, encoding: 'UTF-8') {|entry_name| ... } → nil click to toggle source

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:

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;

}

pwd → string click to toggle source

Returns the path to the current working directory:

Dir.chdir("/tmp") Dir.pwd

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

glob(*patterns, flags: 0, base: nil, sort: true) → array click to toggle source

glob(*patterns, flags: 0, base: nil, sort: true) {|entry_name| ... } → nil

Forms an array entry_names of the entry names selected by the arguments.

Argument patterns is a string pattern or an array of string patterns; note that these are not regexps; see below.

Notes for the following examples:

With no block, returns array entry_names; example (using the simple file tree):

Dir.glob('*')

With a block, calls the block with each of the entry_names and returns nil:

Dir.glob('*') {|entry_name| puts entry_name }

Output:

config.h lib main.rb

If optional keyword argument flags is given, the value modifies the matching; see below.

If optional keyword argument base is given, its value specifies the base directory. Each pattern string specifies entries relative to the base directory; the default is '.'. The base directory is not prepended to the entry names in the result:

Dir.glob(pattern, base: 'lib').take(5)

Dir.glob(pattern, base: 'lib/irb').take(5)

If optional keyword sort is given, its value specifies whether the array is to be sorted; the default is true. Passing value false with that keyword disables sorting (though the underlying file system may already have sorted the array).

Patterns

Each pattern string is expanded according to certain metacharacters; examples below use the Ruby file tree:

More examples (using the simple file tree):

We're in the example directory.

File.basename(Dir.pwd) # => "example" 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", "lib", "main.rb"] Dir.glob('', File::FNM_DOTMATCH) # => [".", "config.h", "lib", "main.rb"] Dir.glob([".rb", ".h"]) # => ["main.rb", "config.h"]

Dir.glob('**/*.rb') => ["lib/song/karaoke.rb", "lib/song.rb", "main.rb"]

Dir.glob('**/*.rb', base: 'lib') # => ["song/karaoke.rb", "song.rb"]

Dir.glob('**/lib') # => ["lib"]

Dir.glob('/lib//*.rb') # => ["lib/song/karaoke.rb", "lib/song.rb"]

Dir.glob('**/lib/*.rb') # => ["lib/song.rb"]

Flags

If optional keyword argument flags is given (the default is zero – no flags), its value should be the bitwise OR of one or more of the constants defined in module File::Constants.

Example:

flags = File::FNM_EXTGLOB | File::FNM_DOTMATCH

Specifying flags can extend, restrict, or otherwise modify the matching.

The flags for this method (other constants in File::Constants do not apply):

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

home(user_name = nil) → dirpath click to toggle source

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

Dir.home
Dir.home('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));

}

mkdir(dirpath, permissions = 0775) → 0 click to toggle source

Creates a directory in the underlying file system at dirpath with the given permissions; returns zero:

Dir.mkdir('foo') File.stat(Dir.new('foo')).mode.to_s(8)[1..4] Dir.mkdir('bar', 0644) File.stat(Dir.new('bar')).mode.to_s(8)[1..4]

See File Permissions. Note that 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);

}

new(dirpath) → dir click to toggle source

new(dirpath, encoding: nil) → dir

Returns a new Dir object for the directory at dirpath:

Dir.new('.')

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
Dir.new('.', encoding: 'US-ASCII').read.encoding

def initialize(name, encoding: nil) Primitive.dir_initialize(name, encoding) end

open(dirpath) → dir click to toggle source

open(dirpath, encoding: nil) → dir

open(dirpath) {|dir| ... } → object

open(dirpath, encoding: nil) {|dir| ... } → object

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

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

Dir.open('.')

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 }

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
Dir.open('.', encoding: 'US-ASCII').read.encoding

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

pwd → string click to toggle source

Returns the path to the current working directory:

Dir.chdir("/tmp") Dir.pwd

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

rmdir(dirpath) → 0 click to toggle source

Removes the directory at dirpath from the underlying file system:

Dir.rmdir('foo')

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

}

rmdir(dirpath) → 0 click to toggle source

Removes the directory at dirpath from the underlying file system:

Dir.rmdir('foo')

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

}

Public Instance Methods

chdir → 0 click to toggle source

chdir { ... } → object

Changes the current working directory to self:

Dir.pwd dir = Dir.new('example') dir.chdir Dir.pwd

With a block, temporarily changes the working directory:

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 }

children → array click to toggle source

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

dir = Dir.new('/example') dir.children

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

close → nil click to toggle source

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
dir.close
dir.read

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;

}

each {|entry_name| ... } → self click to toggle source

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

each_child {|entry_name| ... } → self click to toggle source

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

fileno → integer click to toggle source

Returns the file descriptor used in dir.

d = Dir.new('..') d.fileno

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

}

inspect → string click to toggle source

Returns a string description of self:

Dir.new('example').inspect

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

}

path → string or nil click to toggle source

Returns the dirpath string that was used to create self (or nil if created by method Dir.for_fd):

Dir.new('example').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()

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

dir = Dir.new('example') dir.tell
dir.read
dir.tell

pos = position → integer click to toggle source

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
dir.pos = 3
dir.pos
dir.pos = 30 dir.pos

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

read → string or nil click to toggle source

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

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 */
}

}

rewind → self click to toggle source

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

dir = Dir.new('example') dir.read
dir.read
dir.pos
dir.rewind
dir.pos

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

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

}

seek(position) → self click to toggle source

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
dir.seek(3)
dir.pos
dir.seek(30) dir.pos

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 of self; see Dir As Stream-Like:

dir = Dir.new('example') dir.tell
dir.read
dir.tell

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

}

Also aliased as: pos

to_path()

Returns the dirpath string that was used to create self (or nil if created by method Dir.for_fd):

Dir.new('example').path