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?, #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, #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, #take, #take_while, #to_a, #to_h, #zip

Constructor Details

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

Returns a new directory object for the named directory.

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

Overloads:

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


484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
 
# File 'dir.c', line 484

static VALUE
dir_initialize(int argc, VALUE *argv, VALUE dir)
{
    struct dir_data *dp;
    rb_encoding  *fsenc;
    VALUE dirname, opt, orig;
    static ID keyword_ids[1];
    const char *path;

    if (!keyword_ids[0]) {
	keyword_ids[0] = rb_id_encoding();
    }

    fsenc = rb_filesystem_encoding();

    rb_scan_args(argc, argv, "1:", &dirname, &opt);

    if (!NIL_P(opt)) {
	VALUE enc;
	rb_get_kwargs(opt, keyword_ids, 0, 1, &enc);
	if (enc != Qundef && !NIL_P(enc)) {
	    fsenc = rb_to_encoding(enc);
	}
    }

    GlobPathValue(dirname, FALSE);
    orig = rb_str_dup_frozen(dirname);
    dirname = rb_str_encode_ospath(dirname);
    dirname = rb_str_dup_frozen(dirname);

    TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dp);
    if (dp->dir) closedir(dp->dir);
    dp->dir = NULL;
    dp->path = Qnil;
    dp->enc = fsenc;
    path = RSTRING_PTR(dirname);
    dp->dir = opendir(path);
    if (dp->dir == NULL) {
	if (rb_gc_for_fd(errno)) {
	    dp->dir = opendir(path);
	}
#ifdef HAVE_GETATTRLIST
	else if (errno == EIO) {
	    u_int32_t attrbuf[1];
	    struct attrlist al = {ATTR_BIT_MAP_COUNT, 0};
	    if (getattrlist(path, &al, attrbuf, sizeof(attrbuf), FSOPT_NOFOLLOW) == 0) {
		dp->dir = opendir(path);
	    }
	}
#endif
	if (dp->dir == NULL) {
	    RB_GC_GUARD(dirname);
	    rb_sys_fail_path(orig);
	}
    }
    dp->path = orig;

    return dir;
}

Class Method Details

.[](string[, string ...)) ⇒ Array

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

Returns:



2224
2225
2226
2227
2228
2229
2230
2231
 
# File 'dir.c', line 2224

static VALUE
dir_s_aref(int argc, VALUE *argv, VALUE obj)
{
    if (argc == 1) {
	return rb_push_glob(argv[0], 0);
    }
    return dir_globs(argc, argv, 0);
}

.chdir([ string]) ⇒ 0 .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:



984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
 
# File 'dir.c', line 984

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

    if (rb_scan_args(argc, argv, "01", &path) == 1) {
	FilePathValue(path);
	path = rb_str_encode_ospath(path);
    }
    else {
	const char *dist = getenv("HOME");
	if (!dist) {
	    dist = getenv("LOGDIR");
	    if (!dist) rb_raise(rb_eArgError, "HOME/LOGDIR not set");
	}
	path = rb_str_new2(dist);
    }

    if (chdir_blocking > 0) {
	if (!rb_block_given_p() || rb_thread_current() != chdir_thread)
	    rb_warn("conflicting chdir during another chdir block");
    }

    if (rb_block_given_p()) {
	struct chdir_data args;

	args.old_path = rb_str_encode_ospath(rb_dir_getwd());
	args.new_path = path;
	args.done = FALSE;
	return rb_ensure(chdir_yield, (VALUE)&args, chdir_restore, (VALUE)&args);
    }
    dir_chdir(path);

    return INT2FIX(0);
}

.chroot(string) ⇒ 0

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) 


1089
1090
1091
1092
1093
1094
1095
1096
1097
 
# File 'dir.c', line 1089

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) 


1146
1147
1148
1149
1150
1151
1152
1153
1154
 
# File 'dir.c', line 1146

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

    return INT2FIX(0);
}

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

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

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

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

Overloads:

  • .entries(dirname) ⇒ Array

    Returns:

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

    Returns:



2394
2395
2396
2397
2398
2399
2400
2401
 
# File 'dir.c', line 2394

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

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

.exist?(file_name) ⇒ Boolean

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

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


2594
2595
2596
2597
 
# File 'dir.c', line 2594

VALUE
rb_file_directory_p(void)
{
}

.exists?(file_name) ⇒ Boolean

Deprecated method. Don’t use.

Returns:

  • (Boolean)

Returns:

  • (Boolean) 


2606
2607
2608
2609
2610
2611
 
# File 'dir.c', line 2606

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) 


2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
 
# File 'dir.c', line 2368

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:



1053
1054
1055
1056
1057
 
# File 'dir.c', line 1053

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

.glob(pattern, [flags]) ⇒ Object .glob(pattern, [flags]) {|filename| ... } ⇒ nil

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

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

*

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

*

Matches all files

c*

Matches all files beginning with c

*c

Matches all files ending with c

*c*

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

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

**

Matches directories recursively.

?

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

[set]

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

{p,q}

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

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

\

Escapes the next metacharacter.

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

Examples:

Dir["config.?"]                     #=> ["config.h"]
Dir.glob("config.?")                #=> ["config.h"]
Dir.glob("*.[a-z][a-z]")            #=> ["main.rb"]
Dir.glob("*.[^r]*")                 #=> ["config.h"]
Dir.glob("*.{rb,h}")                #=> ["main.rb", "config.h"]
Dir.glob("*")                       #=> ["config.h", "main.rb"]
Dir.glob("*", File::FNM_DOTMATCH)   #=> [".", "..", "config.h", "main.rb"]

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

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

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

Overloads:

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

    Yields:

    • (filename)

    Returns:

    • (nil) 


2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
 
# File 'dir.c', line 2308

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

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

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

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

.home ⇒ Object .home("root") ⇒ Object

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



2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
 
# File 'dir.c', line 2565

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) 


1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
 
# File 'dir.c', line 1117

static VALUE
dir_s_mkdir(int argc, VALUE *argv, VALUE obj)
{
    VALUE path, vmode;
    int mode;

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

    path = check_dirname(path);
    if (mkdir(RSTRING_PTR(path), mode) == -1)
	rb_sys_fail_path(path);

    return INT2FIX(0);
}

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

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

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

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:



560
561
562
563
564
565
566
567
568
569
570
571
572
 
# File 'dir.c', line 560

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:



1053
1054
1055
1056
1057
 
# File 'dir.c', line 1053

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) 


1146
1147
1148
1149
1150
1151
1152
1153
1154
 
# File 'dir.c', line 1146

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

    return INT2FIX(0);
}

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


1146
1147
1148
1149
1150
1151
1152
1153
1154
 
# File 'dir.c', line 1146

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

    return INT2FIX(0);
}

Instance Method Details

#close ⇒ nil

Closes the directory stream. Any further attempts to access dir will raise an IOError.

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

Returns:

  • (nil) 


894
895
896
897
898
899
900
901
902
903
904
905
 
# File 'dir.c', line 894

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:



752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
 
# File 'dir.c', line 752

static VALUE
dir_each(VALUE dir)
{
    struct dir_data *dirp;
    struct dirent *dp;
    IF_NORMALIZE_UTF8PATH(int norm_p);

    RETURN_ENUMERATOR(dir, 0, 0);
    GetDIR(dir, dirp);
    rewinddir(dirp->dir);
    IF_NORMALIZE_UTF8PATH(norm_p = need_normalization(dirp->dir, RSTRING_PTR(dirp->path)));
    while ((dp = READDIR(dirp->dir, dirp->enc)) != NULL) {
	const char *name = dp->d_name;
	size_t namlen = NAMLEN(dp);
	VALUE path;
#if NORMALIZE_UTF8PATH
	if (norm_p && has_nonascii(name, namlen) &&
	    !NIL_P(path = rb_str_normalize_ospath(name, namlen))) {
	    path = rb_external_str_with_enc(path, dirp->enc);
	}
	else
#endif
	path = rb_external_str_new_with_enc(name, namlen, dirp->enc);
	rb_yield(path);
	if (dirp->dir == NULL) dir_closed();
    }
    return dir;
}

#fileno ⇒ Integer

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:



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

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:



604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
 
# File 'dir.c', line 604

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

    TypedData_Get_Struct(dir, struct dir_data, &dir_data_type, dirp);
    if (!NIL_P(dirp->path)) {
	VALUE str = rb_str_new_cstr("#<");
	rb_str_append(str, rb_class_name(CLASS_OF(dir)));
	rb_str_cat2(str, ":");
	rb_str_append(str, dirp->path);
	rb_str_cat2(str, ">");
	return str;
    }
    return rb_funcallv(dir, rb_intern("to_s"), 0, 0);
}

#path ⇒ String? #to_path ⇒ String?

Returns the path parameter passed to dir’s constructor.

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

Overloads:



675
676
677
678
679
680
681
682
683
 
# File 'dir.c', line 675

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:



795
796
797
798
799
800
801
802
803
804
 
# File 'dir.c', line 795

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:



853
854
855
856
857
858
 
# File 'dir.c', line 853

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:



715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
 
# File 'dir.c', line 715

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

    GetDIR(dir, dirp);
    errno = 0;
    if ((dp = READDIR(dirp->dir, dirp->enc)) != NULL) {
	return rb_external_str_new_with_enc(dp->d_name, NAMLEN(dp), dirp->enc);
    }
    else {
	if (errno != 0) rb_sys_fail(0);
	return Qnil;		/* end of stream */
    }
}

#rewind ⇒ Dir

Repositions dir to the first entry.

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

Returns:



874
875
876
877
878
879
880
881
882
 
# File 'dir.c', line 874

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:



824
825
826
827
828
829
830
831
832
833
 
# File 'dir.c', line 824

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:



795
796
797
798
799
800
801
802
803
804
 
# File 'dir.c', line 795

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:



675
676
677
678
679
680
681
682
683
 
# File 'dir.c', line 675

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