Class: Dir

Inherits:
Object show all
Includes:
Enumerable
Defined in:
dir.c

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Enumerable

#all?, #any?, #chain, #chunk, #chunk_while, #collect, #collect_concat, #compact, #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

Class Method Details

.chdir(new_dirpath) ⇒ 0 .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         # => "/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.

Overloads:

  • .chdir(new_dirpath) ⇒ 0

    Returns:

    • (0)
  • .chdir ⇒ 0

    Returns:

    • (0)
  • .chdir(new_dirpath) {|new_dirpath| ... } ⇒ Object

    Yields:

    • (new_dirpath)

    Returns:

  • .chdir {|cur_dirpath| ... } ⇒ Object

    Yields:

    • (cur_dirpath)

    Returns:



1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
 
# File 'dir.c', line 1301

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

Overloads:

  • .children(dirpath) ⇒ Array

    Returns:

  • .children(dirpath, encoding: 'UTF-8') ⇒ Array

    Returns:



3595
3596
3597
3598
3599
3600
3601
3602
 
# File 'dir.c', line 3595

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

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.

Returns:

  • (0) 


1571
1572
1573
1574
1575
1576
1577
1578
1579
 
# File 'dir.c', line 1571

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

Removes the directory at dirpath from the underlying file system:

Dir.rmdir('foo') # => 0

Raises an exception if the directory is not empty.

Returns:

  • (0) 


1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
 
# File 'dir.c', line 1654

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 .each_child(dirpath, encoding: 'UTF-8') {|entry_name| ... } ⇒ nil

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

Overloads:

  • .each_child(dirpath) {|entry_name| ... } ⇒ nil

    Yields:

    • (entry_name)

    Returns:

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

    Yields:

    • (entry_name)

    Returns:

    • (nil) 


3521
3522
3523
3524
3525
3526
3527
3528
3529
3530
 
# File 'dir.c', line 3521

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) ⇒ Boolean

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.

Returns:

  • (Boolean) 


3764
3765
3766
3767
3768
3769
3770
3771
3772
3773
3774
3775
3776
3777
3778
3779
3780
3781
3782
3783
3784
3785
3786
3787
3788
3789
3790
3791
3792
3793
3794
3795
3796
3797
3798
3799
3800
3801
3802
 
# File 'dir.c', line 3764

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

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.

Returns:



3498
3499
3500
3501
3502
3503
3504
3505
 
# File 'dir.c', line 3498

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) ⇒ Boolean

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

Returns:

  • (Boolean) 


3712
3713
3714
3715
 
# File 'dir.c', line 3712

VALUE
rb_file_directory_p(void)
{
}

.fchdir(fd) ⇒ 0 .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 # => "/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).

Overloads:

  • .fchdir(fd) ⇒ 0

    Returns:

    • (0)
  • .fchdir(fd) { ... } ⇒ Object

    Yields:

    Returns:



1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
 
# File 'dir.c', line 1417

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

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

Returns:



681
682
683
684
685
686
687
688
689
690
691
692
693
694
 
# File 'dir.c', line 681

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

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.

Yields:

  • (entry_name)

Returns:

  • (nil) 


3462
3463
3464
3465
3466
3467
3468
3469
3470
3471
 
# File 'dir.c', line 3462

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

Returns the path to the current working directory:

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

Returns:



1526
1527
1528
1529
1530
 
# File 'dir.c', line 1526

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

.home(user_name = nil) ⇒ Object

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.



3678
3679
3680
3681
3682
3683
3684
3685
3686
3687
3688
3689
3690
3691
3692
3693
3694
3695
3696
 
# File 'dir.c', line 3678

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

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] # => "0755"
Dir.mkdir('bar', 0644)
File.stat(Dir.new('bar')).mode.to_s(8)[1..4] # => "0644"

See File Permissions. Note that argument permissions is ignored on Windows.

Returns:

  • (0) 


1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
 
# File 'dir.c', line 1613

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

.pwd ⇒ String

Returns the path to the current working directory:

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

Returns:



1526
1527
1528
1529
1530
 
# File 'dir.c', line 1526

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

.rmdir(dirpath) ⇒ 0

Removes the directory at dirpath from the underlying file system:

Dir.rmdir('foo') # => 0

Raises an exception if the directory is not empty.

Returns:

  • (0) 


1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
 
# File 'dir.c', line 1654

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

Removes the directory at dirpath from the underlying file system:

Dir.rmdir('foo') # => 0

Raises an exception if the directory is not empty.

Returns:

  • (0) 


1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
 
# File 'dir.c', line 1654

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

Instance Method Details

#chdir ⇒ 0 #chdir { ... } ⇒ Object

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.

Overloads:

  • #chdir ⇒ 0

    Returns:

    • (0)
  • #chdir { ... } ⇒ Object

    Yields:

    Returns:



1465
1466
1467
1468
1469
1470
1471
1472
1473
 
# File 'dir.c', line 1465

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

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

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

Returns:



3568
3569
3570
3571
3572
3573
3574
 
# File 'dir.c', line 3568

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

Returns:

  • (nil) 


1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
 
# File 'dir.c', line 1108

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

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.

Yields:

  • (entry_name)

Returns:

  • (self) 


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

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

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.

Yields:

  • (entry_name)

Returns:

  • (self) 


3550
3551
3552
3553
3554
3555
 
# File 'dir.c', line 3550

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 the dirfd() function defined by POSIX 2008; the method is not implemented on non-POSIX platforms (raises NotImplementedError).

Returns:



779
780
781
782
783
784
785
786
787
788
789
790
 
# File 'dir.c', line 779

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

Returns a string description of self:

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

Returns:



734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
 
# File 'dir.c', line 734

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?

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

Dir.new('example').path # => "example"

Returns:



805
806
807
808
809
810
811
812
813
 
# File 'dir.c', line 805

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

#tell ⇒ Integer

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

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

Returns:



988
989
990
991
992
993
994
995
996
997
998
 
# File 'dir.c', line 988

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

#pos=(position) ⇒ Integer

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

Returns:



1059
1060
1061
1062
1063
1064
 
# File 'dir.c', line 1059

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

#read ⇒ String?

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"

Returns:



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

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

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

Returns:

  • (self) 


1084
1085
1086
1087
1088
1089
1090
1091
1092
 
# File 'dir.c', line 1084

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

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

#seek(position) ⇒ self

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

Returns:

  • (self) 


1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
 
# File 'dir.c', line 1024

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

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

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

Returns:



988
989
990
991
992
993
994
995
996
997
998
 
# File 'dir.c', line 988

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

#path ⇒ String?

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

Dir.new('example').path # => "example"

Returns:



805
806
807
808
809
810
811
812
813
 
# File 'dir.c', line 805

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