Class: Dir

Inherits:
Object show all
Includes:
Enumerable
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 collapse

Instance Method Summary collapse

Methods included from Enumerable

#all?, #any?, #chain, #chunk, #chunk_while, #collect, #collect_concat, #count, #cycle, #detect, #drop, #drop_while, #each_cons, #each_entry, #each_slice, #each_with_index, #each_with_object, #entries, #filter, #filter_map, #find, #find_all, #find_index, #first, #flat_map, #grep, #grep_v, #group_by, #include?, #inject, #lazy, #map, #max, #max_by, #member?, #min, #min_by, #minmax, #minmax_by, #none?, #one?, #partition, #reduce, #reject, #reverse_each, #select, #slice_after, #slice_before, #slice_when, #sort, #sort_by, #sum, #take, #take_while, #tally, #to_a, #to_h, #uniq, #zip

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.

Overloads:

  • #new(string) ⇒ Dir
  • #new(string, encoding: enc) ⇒ Dir 


524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
 
# 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 ...)) ⇒ Array

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

Returns:



2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
 
# File 'dir.c', line 2781

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

Overloads:

  • .chdir([ string]) ⇒ 0

    Returns:

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

    Yields:

    Returns:



1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
 
# File 'dir.c', line 1076

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

Overloads:

  • .children(dirname) ⇒ Array

    Returns:

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

    Returns:



3085
3086
3087
3088
3089
3090
3091
3092
 
# File 'dir.c', line 3085

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.

Returns:

  • (0) 


1210
1211
1212
1213
1214
1215
1216
1217
1218
 
# File 'dir.c', line 1210

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

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

Overloads:

  • .delete(string) ⇒ 0

    Returns:

    • (0)
  • .rmdir(string) ⇒ 0

    Returns:

    • (0)
  • .unlink(string) ⇒ 0

    Returns:

    • (0) 


1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
 
# File 'dir.c', line 1290

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

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

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

Overloads:

  • .each_child(dirname) {|filename| ... } ⇒ nil

    Yields:

    • (filename)

    Returns:

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

    Yields:

    • (filename)

    Returns:

    • (nil) 


3013
3014
3015
3016
3017
3018
3019
3020
3021
3022
 
# File 'dir.c', line 3013

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.

Returns:

  • (Boolean) 


3344
3345
3346
3347
3348
3349
3350
3351
3352
3353
3354
3355
3356
3357
3358
3359
3360
3361
3362
3363
3364
3365
3366
3367
3368
3369
3370
3371
3372
3373
3374
3375
3376
3377
3378
3379
3380
3381
3382
 
# File 'dir.c', line 3344

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

Overloads:

  • .entries(dirname) ⇒ Array

    Returns:

  • .entries(dirname, encoding: enc) ⇒ Array

    Returns:



2977
2978
2979
2980
2981
2982
2983
2984
 
# File 'dir.c', line 2977

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.

Returns:

  • (Boolean) 


3286
3287
3288
3289
 
# File 'dir.c', line 3286

VALUE
rb_file_directory_p(void)
{
}

.exists?(file_name) ⇒ Boolean

Deprecated method. Don’t use.

Returns:

  • (Boolean) 


3298
3299
3300
3301
3302
3303
 
# File 'dir.c', line 3298

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) ⇒ Object .foreach(dirname, encoding: enc) ⇒ Object

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

Overloads:

  • .foreach(dirname) {|filename| ... } ⇒ nil

    Yields:

    • (filename)

    Returns:

    • (nil)
  • .foreach(dirname, encoding: enc) {|filename| ... } ⇒ nil

    Yields:

    • (filename)

    Returns:

    • (nil) 


2943
2944
2945
2946
2947
2948
2949
2950
2951
2952
 
# File 'dir.c', line 2943

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 .pwd ⇒ String

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

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

Overloads:



1174
1175
1176
1177
1178
 
# File 'dir.c', line 1174

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

.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"]

Overloads:

  • .glob(pattern, [flags], [base: path]) ⇒ Array

    Returns:

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

    Yields:

    • (filename)

    Returns:

    • (nil) 


2881
2882
2883
2884
2885
2886
2887
2888
2889
2890
2891
2892
2893
2894
2895
2896
2897
2898
2899
2900
2901
2902
2903
2904
2905
2906
2907
2908
2909
 
# File 'dir.c', line 2881

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 ⇒ Object .home("root") ⇒ Object

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



3257
3258
3259
3260
3261
3262
3263
3264
3265
3266
3267
3268
3269
3270
3271
3272
3273
3274
3275
 
# File 'dir.c', line 3257

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

Returns:

  • (0) 


1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
 
# File 'dir.c', line 1250

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

Overloads:

  • .open(string) ⇒ Dir

    Returns:

  • .open(string, encoding: enc) ⇒ Dir

    Returns:

  • .open(string) {|aDir| ... } ⇒ Object

    Yields:

    • (aDir)

    Returns:

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

    Yields:

    • (aDir)

    Returns:



600
601
602
603
604
605
606
607
608
609
610
611
612
 
# File 'dir.c', line 600

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

.getwd ⇒ String .pwd ⇒ String

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

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

Overloads:



1174
1175
1176
1177
1178
 
# File 'dir.c', line 1174

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

.delete(string) ⇒ 0 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0

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

Overloads:

  • .delete(string) ⇒ 0

    Returns:

    • (0)
  • .rmdir(string) ⇒ 0

    Returns:

    • (0)
  • .unlink(string) ⇒ 0

    Returns:

    • (0) 


1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
 
# File 'dir.c', line 1290

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

.delete(string) ⇒ 0 .rmdir(string) ⇒ 0 .unlink(string) ⇒ 0

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

Overloads:

  • .delete(string) ⇒ 0

    Returns:

    • (0)
  • .rmdir(string) ⇒ 0

    Returns:

    • (0)
  • .unlink(string) ⇒ 0

    Returns:

    • (0) 


1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
 
# File 'dir.c', line 1290

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 Method Details

#children ⇒ Array

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

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

Returns:



3062
3063
3064
3065
3066
3067
3068
 
# File 'dir.c', line 3062

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

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

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

Returns:

  • (nil) 


976
977
978
979
980
981
982
983
984
985
986
987
 
# File 'dir.c', line 976

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 #each ⇒ Object

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

Overloads:

  • #each {|filename| ... } ⇒ Dir

    Yields:

    • (filename)

    Returns:



826
827
828
829
830
831
 
# File 'dir.c', line 826

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_child ⇒ Object

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

Overloads:

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

    Yields:

    • (filename)

    Returns:

    • (nil) 


3044
3045
3046
3047
3048
3049
 
# File 'dir.c', line 3044

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

#fileno ⇒ Integer

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.

Returns:



691
692
693
694
695
696
697
698
699
700
701
702
 
# File 'dir.c', line 691

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

Return a string describing this Dir object.

Returns:



646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
 
# File 'dir.c', line 646

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? #to_path ⇒ String?

Returns the path parameter passed to dir’s constructor.

d = Dir.new("..")
d.path   #=> ".."

Overloads:



717
718
719
720
721
722
723
724
725
 
# File 'dir.c', line 717

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 #tell ⇒ Integer

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

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

Overloads:



878
879
880
881
882
883
884
885
886
887
 
# File 'dir.c', line 878

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

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                   #=> ".."

Returns:



935
936
937
938
939
940
 
# File 'dir.c', line 935

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

#read ⇒ String?

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"

Returns:



780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
 
# File 'dir.c', line 780

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

#rewind ⇒ Dir

Repositions dir to the first entry.

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

Returns:



956
957
958
959
960
961
962
963
964
 
# File 'dir.c', line 956

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 Dir#tell.

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

Returns:



907
908
909
910
911
912
913
914
915
916
 
# File 'dir.c', line 907

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

#pos ⇒ Integer #tell ⇒ Integer

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

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

Overloads:



878
879
880
881
882
883
884
885
886
887
 
# File 'dir.c', line 878

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

    GetDIR(dir, dirp);
    pos = telldir(dirp->dir);
    return rb_int2inum(pos);
}

#path ⇒ String? #to_path ⇒ String?

Returns the path parameter passed to dir’s constructor.

d = Dir.new("..")
d.path   #=> ".."

Overloads:



717
718
719
720
721
722
723
724
725
 
# File 'dir.c', line 717

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