class File::Stat

A File::Stat object contains information about an entry in the filesystem.

Each of these methods returns a new File::Stat object. the first three follow symbolic links; the others don’t:

Snapshot

A new File::Stat object takes an immediate “snapshot” of the filesystem entry at the given ‘path’; the snapshot is never updated, regardless of changes in the entry (even its deletion):

filepath = '/tmp/t.tmp'
File.stat(filepath) # Raises Errno::ENOENT: No such file or directory.
File.write(filepath, 'foo')
stat = File.stat(filepath)
stat.birthtime # => 2026-10-03 12:19:23.723062465 -0500
File.delete(filepath)
stat.birthtime # => 2026-10-03 12:19:23.723062465 -0500

Methods in a File::Stat object may return filesystem-dependent values, and not all values are meaningful on all filesystems; for example, File::Stat#blocks returns nil on a Windows filesystem, but returns an integer on others.

Public Class Methods

File::Stat.new(path) → stat

(path file_name) → void

Source

static VALUE
rb_stat_init(VALUE obj, VALUE fname)
{
    rb_io_stat_data st;

    FilePathValue(fname);
    fname = rb_str_encode_ospath(fname);
    if (STATX(StringValueCStr(fname), &st, STATX_ALL) == -1) {
        rb_sys_fail_path(fname);
    }

    struct rb_stat *rb_st;
    TypedData_Get_Struct(obj, struct rb_stat, &stat_data_type, rb_st);

    rb_st->stat = st;
    rb_st->initialized = true;

    return Qnil;
}

Returns a new File::Stat object containing a snapshot of the filesystem entry at the given path:

File::Stat.new('/etc/passwd')
File::Stat.new('/tmp')
File::Stat.new('nosuch') # Raises Errno::ENOENT: No such file or directory.

Public Instance Methods

self <=> other → -1, 0, 1, or nil

(self other) → (-1 | 0 | 1)
(untyped) → (-1 | 0 | 1)?

Source

static VALUE
rb_stat_cmp(VALUE self, VALUE other)
{
    if (rb_obj_is_kind_of(other, rb_obj_class(self))) {
        stat_timestamp ts1 = statx_mtimespec(get_stat(self));
        stat_timestamp ts2 = statx_mtimespec(get_stat(other));
        if (ts1.tv_sec == ts2.tv_sec) {
            if (ts1.tv_nsec == ts2.tv_nsec) return INT2FIX(0);
            if (ts1.tv_nsec < ts2.tv_nsec) return INT2FIX(-1);
            return INT2FIX(1);
        }
        if (ts1.tv_sec < ts2.tv_sec) return INT2FIX(-1);
        return INT2FIX(1);
    }
    return Qnil;
}

Compares self and other, by comparing their modification times; that is, by comparing self.mtime and other.mtime.

Returns:

-1, if self.mtime is earlier.
0, if the two values are equal.
1, if self.mtime is later.
nil, if other is not a File::Stat object.

Examples:

stat0 = File.stat('README.md')
stat1 = File.stat('NEWS.md')
stat0.mtime         # => 2025-12-20 15:33:05.6972341 -0600
stat1.mtime         # => 2025-12-20 16:02:08.2672945 -0600
stat0 <=> stat1     # => -1
stat0 <=> stat0.dup # => 0
stat1 <=> stat0     # => 1
stat0 <=> :foo      # => nil

Class File::Stat includes module Comparable, each of whose methods uses File::Stat#<=> for comparison.

atime → time

() → Time

Source

static VALUE
rb_stat_atime(VALUE self)
{
    return stat_time(statx_atimespec(get_stat(self)));
}

Returns a new Time object containing the access time of the object represented by self at the time self was created; see Snapshot. See File System Timestamps.

Access time for a file is established when it is created, and may be updated when the file content is read:

filepath = 't.tmp'
File.exist?(filepath)            # => false
file = File.open(filepath, 'w+') # Create by writing; establishes access time.
file.atime                       # => 2026-08-14 11:55:55.436283939 -0500
stat0 = File::Stat.new(filepath) # Take snapshot.
stat0.atime                      # => 2026-08-14 11:55:55.436283939 -0500
file.read                        # Read file content; updates file access time.
file.atime                       # => 2026-08-14 11:56:22.74241085 -0500
stat0.atime                      # => 2026-08-14 11:55:55.436283939 -0500  # Not updated.
stat1 = File::Stat.new(filepath) # Take new snapshot.
stat1.atime                      # => 2026-08-14 11:56:22.74241085 -0500   # Updated.
# Clean up.
file.close
File.delete(filepath)

Access time for a directory is established when it is created, and may be updated when its entries are read:

dirpath = 'foo'
File.exist?(dirpath)         # => false
FileUtils.cp_r('doc', 'foo') # Create directory by copying.
File.atime(dirpath)          # => 2026-08-15 14:10:04.832180372 -0500
stat = File::Stat.new(dirpath)
stat.atime                   # => 2026-08-15 14:10:04.832180372 -0500
# Clean up.
FileUtils.rm_rf(dirpath)
dir.close

birthtime → new_time

() → Time

Source

static VALUE
rb_stat_birthtime(VALUE self)
{
    return statx_birthtime(get_stat(self));
}

Returns a new Time object containing the create time of the object represented by self at the time self was created; see Snapshot:

filename = 't.tmp'
stat = File::Stat.new(filename) # Raises Errno::ENOENT: No such file or directory
File.write(filename, 'foo')
stat = File::Stat.new(filename)
stat.birthtime # => 2026-04-14 10:41:55.5146554 -0500
File.delete(filename)
stat.birthtime # => 2026-04-14 10:41:55.5146554 -0500

See File System Timestamps.

blksize → integer or nil

() → Integer?

Source

static VALUE
rb_stat_blksize(VALUE self)
{
#ifdef HAVE_STRUCT_STAT_ST_BLKSIZE
    return ULONG2NUM(get_stat(self)->ST_(blksize));
#else
    return Qnil;
#endif
}

Returns the native file system’s block size. Will return nil on platforms that don’t support this information.

File.stat("testfile").blksize   #=> 4096

blockdev? → true or false

() → bool

Source

static VALUE
rb_stat_b(VALUE obj)
{
#ifdef S_ISBLK
    if (S_ISBLK(get_stat(obj)->ST_(mode))) return Qtrue;

#endif
    return Qfalse;
}

Returns true if the file is a block device, false if it isn’t or if the operating system doesn’t support this feature.

File.stat("testfile").blockdev?    #=> false
File.stat("/dev/hda1").blockdev?   #=> true

blocks → integer or nil

() → Integer?

Source

static VALUE
rb_stat_blocks(VALUE self)
{
#ifdef HAVE_STRUCT_STAT_ST_BLOCKS
# if SIZEOF_STRUCT_STAT_ST_BLOCKS > SIZEOF_LONG
    return ULL2NUM(get_stat(self)->ST_(blocks));
# else
    return ULONG2NUM(get_stat(self)->ST_(blocks));
# endif
#else
    return Qnil;
#endif
}

Returns the number of native file system blocks allocated for this file, or nil if the operating system doesn’t support this feature.

File.stat("testfile").blocks   #=> 2

chardev? → true or false

() → bool

Source

static VALUE
rb_stat_c(VALUE obj)
{
    if (S_ISCHR(get_stat(obj)->ST_(mode))) return Qtrue;

    return Qfalse;
}

Returns true if the file is a character device, false if it isn’t or if the operating system doesn’t support this feature.

File.stat("/dev/tty").chardev?   #=> true

ctime → time

() → Time

Source

static VALUE
rb_stat_ctime(VALUE self)
{
    return stat_time(statx_ctimespec(get_stat(self)));
}

Returns the change time for stat (that is, the time directory information about the file was changed, not the file itself).

Note that on Windows (NTFS), returns creation time (birth time).

File.stat("testfile").ctime   #=> Wed Apr 09 08:53:14 CDT 2003

dev → integer

() → Integer

Source

static VALUE
rb_stat_dev(VALUE self)
{
#if RUBY_USE_STATX
    unsigned int m = get_stat(self)->stx_dev_major;
    unsigned int n = get_stat(self)->stx_dev_minor;
    return ULL2NUM(makedev(m, n));
#elif SIZEOF_STRUCT_STAT_ST_DEV <= SIZEOF_DEV_T
    return DEVT2NUM(get_stat(self)->st_dev);
#elif SIZEOF_STRUCT_STAT_ST_DEV <= SIZEOF_LONG
    return ULONG2NUM(get_stat(self)->st_dev);
#else
    return ULL2NUM(get_stat(self)->st_dev);
#endif
}

Returns an integer representing the device on which stat resides.

File.stat("testfile").dev   #=> 774

dev_major → integer

() → Integer?

Source

static VALUE
rb_stat_dev_major(VALUE self)
{
#if RUBY_USE_STATX
    return UINT2NUM(get_stat(self)->stx_dev_major);
#elif defined(major)
    return UINT2NUM(major(get_stat(self)->st_dev));
#else
    return Qnil;
#endif
}

Returns the major part of File::Stat#dev or nil.

File.stat("/dev/fd1").dev_major   #=> 2
File.stat("/dev/tty").dev_major   #=> 5

dev_minor → integer

() → Integer?

Source

static VALUE
rb_stat_dev_minor(VALUE self)
{
#if RUBY_USE_STATX
    return UINT2NUM(get_stat(self)->stx_dev_minor);
#elif defined(minor)
    return UINT2NUM(minor(get_stat(self)->st_dev));
#else
    return Qnil;
#endif
}

Returns the minor part of File::Stat#dev or nil.

File.stat("/dev/fd1").dev_minor   #=> 1
File.stat("/dev/tty").dev_minor   #=> 0

directory? → true or false

() → bool

Source

static VALUE
rb_stat_d(VALUE obj)
{
    if (S_ISDIR(get_stat(obj)->ST_(mode))) return Qtrue;
    return Qfalse;
}

Returns true if stat is a directory, false otherwise.

File.stat("testfile").directory?   #=> false
File.stat(".").directory?          #=> true

executable? → true or false

() → bool

Source

static VALUE
rb_stat_x(VALUE obj)
{
    rb_io_stat_data *st = get_stat(obj);

#ifdef USE_GETEUID
    if (geteuid() == 0) {
        return RBOOL(st->ST_(mode) & S_IXUGO);
    }
#endif
#ifdef S_IXUSR
    if (rb_stat_owned(obj))
        return RBOOL(st->ST_(mode) & S_IXUSR);
#endif
#ifdef S_IXGRP
    if (rb_stat_grpowned(obj))
        return RBOOL(st->ST_(mode) & S_IXGRP);
#endif
#ifdef S_IXOTH
    if (!(st->ST_(mode) & S_IXOTH)) return Qfalse;
#endif
    return Qtrue;
}

Returns whether the filesystem entry represented by self exists and is executable; raises Errno::ENOENT if the entry does not exist.

On Windows, the entry is executable if its path has file extension .bat, .cmd, .com, or .exe:

File.stat('win32/rtname.cmd').executable? # => true
File.stat('win32/file.c').executable?     # => false

On other systems, the entry is executable if it has the execute/search permission for the effective user and group id of the current process; see Permissions:

File.stat('/bin/bash').executable?        # => true
File.stat('/etc/passwd').executable?      # => false
File.stat('.').executable?                # => true

Note that some filesystem settings may cause this method to return true even though the entry is not executable by the effective user/group.

executable_real? → true or false

() → bool

Source

static VALUE
rb_stat_X(VALUE obj)
{
    rb_io_stat_data *st = get_stat(obj);

#ifdef USE_GETEUID
    if (getuid() == 0) {
        return RBOOL(st->ST_(mode) & S_IXUGO);
    }
#endif
#ifdef S_IXUSR
    if (rb_stat_rowned(obj))
        return RBOOL(st->ST_(mode) & S_IXUSR);
#endif
#ifdef S_IXGRP
    if (rb_group_member(get_stat(obj)->ST_(gid)))
        return RBOOL(st->ST_(mode) & S_IXGRP);
#endif
#ifdef S_IXOTH
    if (!(st->ST_(mode) & S_IXOTH)) return Qfalse;
#endif
    return Qtrue;
}

Same as executable?, but tests using the real owner of the process.

file? → true or false

() → bool

Source

static VALUE
rb_stat_f(VALUE obj)
{
    if (S_ISREG(get_stat(obj)->ST_(mode))) return Qtrue;
    return Qfalse;
}

Returns whether self represents a filesystem entry that exists and is a regular file; see File::Stat.ftype:

# Paths.
File.stat('README.md').file?     # => true
File.stat('doc/').file?     # => false
File.stat('nosuch').file? # Raises Errno::ENOENT: No such file or directory.

ftype → string

() → File::ftype

Source

static VALUE
rb_stat_ftype(VALUE obj)
{
    return rb_file_ftype(get_stat(obj)->ST_(mode));
}

Returns the string type of the object at path, one of:

'file'.
'directory'.
'characterSpecial'.
'blockSpecial'.
'fifo'.
'link'.
'socket'.

Examples:

File.stat('README.md').ftype  # => "file"
File.stat('lib').ftype        # => "directory"
File.stat('/dev/null').ftype  # => "characterSpecial"
File.stat('/dev/loop0').ftype # => "blockSpecial"

File.mkfifo('/tmp/pipe', 0666)
File.stat('/tmp/pipe').ftype  # => "fifo"

# Follows symbolic link.
File.symlink('lib', 'lib_link')
File.stat('lib_link').ftype   # => "directory"
# Does not follow symbolic link.
File.lstat('lib_link').ftype  # => "link"

require 'socket'
UNIXServer.new('/tmp/socket')
File.stat('/tmp/socket').ftype # => "socket"

Returns 'unknown' if the type cannot be determined.

gid → integer

() → Integer

Source

static VALUE
rb_stat_gid(VALUE self)
{
    return GIDT2NUM(get_stat(self)->ST_(gid));
}

Returns the numeric group id of the owner of stat.

File.stat("testfile").gid   #=> 500

grpowned?(path) → true or false

() → bool

Source

static VALUE
rb_stat_grpowned(VALUE obj)
{
#ifndef _WIN32
    if (rb_group_member(get_stat(obj)->ST_(gid))) return Qtrue;
#endif
    return Qfalse;
}

Returns whether the filesystem entry for the given string path exists, and the effective group id of the calling process is the owner of the entry:

File.stat('README.md').grpowned?   # => true
File.stat('lib').grpowned?         # => true
File.stat('/etc/passwd').grpowned? # => false

Raises an exception if there is no entry at the given path.

Returns false on Windows.

ino → integer

() → Integer

Source

static VALUE
rb_stat_ino(VALUE self)
{
    rb_io_stat_data *ptr = get_stat(self);
#ifdef HAVE_STRUCT_STAT_ST_INOHIGH
    /* assume INTEGER_PACK_LSWORD_FIRST and st_inohigh is just next of st_ino */
    return rb_integer_unpack(&ptr->st_ino, 2,
            SIZEOF_STRUCT_STAT_ST_INO, 0,
            INTEGER_PACK_LSWORD_FIRST|INTEGER_PACK_NATIVE_BYTE_ORDER|
            INTEGER_PACK_2COMP);
#else
    return UIANY2NUM(ptr->ST_(ino));
#endif
}

Returns the inode number for stat.

File.stat("testfile").ino   #=> 1083669

inspect → string

() → String

Source

static VALUE
rb_stat_inspect(VALUE self)
{
    VALUE str;
    size_t i;
    static const struct {
        const char *name;
        VALUE (*func)(VALUE);
    } member[] = {
        {"dev",     rb_stat_dev},
        {"ino",     rb_stat_ino},
        {"mode",    rb_stat_mode},
        {"nlink",   rb_stat_nlink},
        {"uid",     rb_stat_uid},
        {"gid",     rb_stat_gid},
        {"rdev",    rb_stat_rdev},
        {"size",    rb_stat_size},
        {"blksize", rb_stat_blksize},
        {"blocks",  rb_stat_blocks},
        {"atime",   rb_stat_atime},
        {"mtime",   rb_stat_mtime},
        {"ctime",   rb_stat_ctime},
#if defined(HAVE_STRUCT_STAT_ST_BIRTHTIMESPEC)
        {"birthtime",   rb_stat_birthtime},
#endif
    };

    struct rb_stat* rb_st;
    TypedData_Get_Struct(self, struct rb_stat, &stat_data_type, rb_st);
    if (!rb_st->initialized) {
        return rb_sprintf("#<%s: uninitialized>", rb_obj_classname(self));
    }

    str = rb_str_buf_new2("#<");
    rb_str_buf_cat2(str, rb_obj_classname(self));
    rb_str_buf_cat2(str, " ");

    for (i = 0; i < sizeof(member)/sizeof(member[0]); i++) {
        VALUE v;

        if (i > 0) {
            rb_str_buf_cat2(str, ", ");
        }
        rb_str_buf_cat2(str, member[i].name);
        rb_str_buf_cat2(str, "=");
        v = (*member[i].func)(self);
        if (i == 2) {           /* mode */
            rb_str_catf(str, "0%lo", (unsigned long)NUM2ULONG(v));
        }
        else if (i == 0 || i == 6) { /* dev/rdev */
            rb_str_catf(str, "0x%"PRI_DEVT_PREFIX"x", NUM2DEVT(v));
        }
        else {
            rb_str_append(str, rb_inspect(v));
        }
    }
    rb_str_buf_cat2(str, ">");

    return str;
}

Produce a nicely formatted description of stat.

File.stat("/etc/passwd").inspect
   #=> "#<File::Stat dev=0xe000005, ino=1078078, mode=0100644,
   #    nlink=1, uid=0, gid=0, rdev=0x0, size=1374, blksize=4096,
   #    blocks=8, atime=Wed Dec 10 10:16:12 CST 2003,
   #    mtime=Fri Sep 12 15:41:41 CDT 2003,
   #    ctime=Mon Oct 27 11:20:27 CST 2003,
   #    birthtime=Mon Aug 04 08:13:49 CDT 2003>"

mode → integer

() → Integer

Source

static VALUE
rb_stat_mode(VALUE self)
{
    return UINT2NUM(ST2UINT(get_stat(self)->ST_(mode)));
}

Returns an integer representing the permission bits of stat. The meaning of the bits is platform dependent; on Unix systems, see stat(2).

File.chmod(0644, "testfile")   #=> 1
s = File.stat("testfile")
sprintf("%o", s.mode)          #=> "100644"

mtime → time

() → Time

Source

static VALUE
rb_stat_mtime(VALUE self)
{
    return stat_time(statx_mtimespec(get_stat(self)));
}

Returns a new Time object containing the modification time of the object represented by self at the time self was created; see Snapshot:

path = 't.tmp'
file = File.new(path, 'w+')
stat = File.stat(path)
stat.mtime        # => 2026-09-19 08:49:08.846933858 -0500
file.write('foo')
file.flush
File.mtime(path)  # => 2026-09-19 08:50:14.381365572 -0500
stat.mtime        # => 2026-09-19 08:49:08.846933858 -0500
stat = File.stat(path)
stat.mtime        # => 2026-09-19 08:50:14.381365572 -0500
File.unlink(path) # Clean up.

nlink → integer

() → Integer

Source

static VALUE
rb_stat_nlink(VALUE self)
{
    /* struct stat::st_nlink is nlink_t in POSIX.  Not the case for Windows. */
    const rb_io_stat_data *ptr = get_stat(self);

    return UIANY2NUM(ptr->ST_(nlink));
}

Returns the number of hard links to stat.

File.stat("testfile").nlink             #=> 1
File.link("testfile", "testfile.bak")   #=> 0
File.stat("testfile").nlink             #=> 2

owned? → true or false

() → bool

Source

static VALUE
rb_stat_owned(VALUE obj)
{
    if (get_stat(obj)->ST_(uid) == geteuid()) return Qtrue;
    return Qfalse;
}

Returns whether self represents a filesystem entry that, at the time self was created, existed and was owned by the user of the current process; see Snapshot:

filepath = 'doc/t.tmp'
File.write(filepath, 'foo')
filestat = File.stat(filepath)
filestat.owned?          # => true
File.delete(filepath)
filestat.owned?          # => true  # Snapshot unchanged.
dirpath = 'doc/tmp'
Dir.mkdir(dirpath)
dirstat = File.stat(dirpath)
dirstat.owned?           # => true
Dir.rmdir(dirpath)
dirstat.owned?           # => true  # Snapshot unchanged.
File.stat('/etc').owned? # => false

pipe? → true or false

() → bool

Source

static VALUE
rb_stat_p(VALUE obj)
{
#ifdef S_IFIFO
    if (S_ISFIFO(get_stat(obj)->ST_(mode))) return Qtrue;

#endif
    return Qfalse;
}

Returns whether the entry at the path in self is a pipe:

File.stat('doc/syntax/').pipe?        # => false  # Directory .
File.stat('doc/maintainers.md').pipe? # => false  # Regular file.
path = '/tmp/foo'
File.mkfifo(path)
File.stat(path).pipe?                 # => true
File.delete(path)                     # Clean up.

rdev → integer or nil

() → Integer?

Source

static VALUE
rb_stat_rdev(VALUE self)
{
#if RUBY_USE_STATX
    unsigned int m = get_stat(self)->stx_rdev_major;
    unsigned int n = get_stat(self)->stx_rdev_minor;
    return ULL2NUM(makedev(m, n));
#elif !defined(HAVE_STRUCT_STAT_ST_RDEV)
    return Qnil;
#elif SIZEOF_STRUCT_STAT_ST_RDEV <= SIZEOF_DEV_T
    return DEVT2NUM(get_stat(self)->ST_(rdev));
#elif SIZEOF_STRUCT_STAT_ST_RDEV <= SIZEOF_LONG
    return ULONG2NUM(get_stat(self)->ST_(rdev));
#else
    return ULL2NUM(get_stat(self)->ST_(rdev));
#endif
}

Returns an integer representing the device type on which stat resides. Returns nil if the operating system doesn’t support this feature.

File.stat("/dev/fd1").rdev   #=> 513
File.stat("/dev/tty").rdev   #=> 1280

rdev_major → integer

() → Integer?

Source

static VALUE
rb_stat_rdev_major(VALUE self)
{
#if RUBY_USE_STATX
    return UINT2NUM(get_stat(self)->stx_rdev_major);
#elif defined(HAVE_STRUCT_STAT_ST_RDEV) && defined(major)
    return UINT2NUM(major(get_stat(self)->ST_(rdev)));
#else
    return Qnil;
#endif
}

Returns the major part of File::Stat#rdev or nil.

File.stat("/dev/fd1").rdev_major   #=> 2
File.stat("/dev/tty").rdev_major   #=> 5

rdev_minor → integer

() → Integer?

Source

static VALUE
rb_stat_rdev_minor(VALUE self)
{
#if RUBY_USE_STATX
    return UINT2NUM(get_stat(self)->stx_rdev_minor);
#elif defined(HAVE_STRUCT_STAT_ST_RDEV) && defined(minor)
    return UINT2NUM(minor(get_stat(self)->ST_(rdev)));
#else
    return Qnil;
#endif
}

Returns the minor part of File::Stat#rdev or nil.

File.stat("/dev/fd1").rdev_minor   #=> 1
File.stat("/dev/tty").rdev_minor   #=> 0

readable? → true or false

() → bool

Source

static VALUE
rb_stat_r(VALUE obj)
{
    rb_io_stat_data *st = get_stat(obj);

#ifdef USE_GETEUID
    if (geteuid() == 0) return Qtrue;
#endif
#ifdef S_IRUSR
    if (rb_stat_owned(obj))
        return RBOOL(st->ST_(mode) & S_IRUSR);
#endif
#ifdef S_IRGRP
    if (rb_stat_grpowned(obj))
        return RBOOL(st->ST_(mode) & S_IRGRP);
#endif
#ifdef S_IROTH
    if (!(st->ST_(mode) & S_IROTH)) return Qfalse;
#endif
    return Qtrue;
}

Returns whether the entry represented by self exists and is readable by the owner and group of the current process; see Permissions:

path = '/tmp/secret.txt'
File.write(path, 'foo')
File.stat(path).readable? # => true
File.chmod(0o000, path)
File.stat(path).readable? # => false
File.delete(path)         # Clean up.

readable_real? → true or false

() → bool

Source

static VALUE
rb_stat_R(VALUE obj)
{
    rb_io_stat_data *st = get_stat(obj);

#ifdef USE_GETEUID
    if (getuid() == 0) return Qtrue;
#endif
#ifdef S_IRUSR
    if (rb_stat_rowned(obj))
        return RBOOL(st->ST_(mode) & S_IRUSR);
#endif
#ifdef S_IRGRP
    if (rb_group_member(get_stat(obj)->ST_(gid)))
        return RBOOL(st->ST_(mode) & S_IRGRP);
#endif
#ifdef S_IROTH
    if (!(st->ST_(mode) & S_IROTH)) return Qfalse;
#endif
    return Qtrue;
}

Like readable?, but checks against the real user and group ids instead of the effective ids.

setgid? → true or false

() → bool

Source

static VALUE
rb_stat_sgid(VALUE obj)
{
#ifdef S_ISGID
    if (get_stat(obj)->ST_(mode) & S_ISGID) return Qtrue;
#endif
    return Qfalse;
}

Returns whether the setgid bit is set in the special bits for the entry represented in self:

path = '/tmp/t.tmp'
File.write(path, 'foo')
stat = File.stat(path)   # Take a snapshot.
stat.setgid?             # => false
stat.mode.to_s(8)        # => "100664"
File.chmod(0o2644, path) # Set the bit; stat snapshot unchanged.
stat.setgid?             # => false
stat.mode.to_s(8)        # => "100664"
stat = File.stat(path)   # Fresh stat; snapshot changed.
stat.setgid?             # => true
stat.mode.to_s(8)        # => "102644"
File.delete(path)        # Clean up.

On Windows, the bit is never set; the method always returns false.

setuid? → true or false

() → bool

Source

static VALUE
rb_stat_suid(VALUE obj)
{
#ifdef S_ISUID
    if (get_stat(obj)->ST_(mode) & S_ISUID) return Qtrue;
#endif
    return Qfalse;
}

Returns whether the setuid bit is set in the special bits for the entry represented in self:

path = '/tmp/t.tmp'
File.write(path, 'foo')
stat = File.stat(path)   # Take snapshot; bit not set.
stat.setuid?             # => false
stat.mode.to_s(8)        # => "100664"
File.chmod(0o4644, path) # Set the bit; snapshot not updated.
stat.setuid?             # => false
stat.mode.to_s(8)        # => "100664"
stat = File.stat(path)   # Fresh snapshot.
stat.setuid?             # => true
stat.mode.to_s(8)        # => "104644"
File.delete(path)        # Clean up.

On Windows, the bit is never set; the method always returns false.

size → integer

() → Integer

Source

static VALUE
rb_stat_size(VALUE self)
{
    return OFFT2NUM(get_stat(self)->ST_(size));
}

Returns the size of self in bytes:

File.stat('doc/maintainers.md').size # => 14900  # Regular file.
File.stat('doc/syntax/').size        # => 4096   # Directory.
# When the file size changes.
path = '/tmp/t.tmp'
file = File.new(path, 'w+')
file.write('foo')
stat = File.stat(path) # Take snapshot.
stat.size              # => 3
file.write('bar')      # Change file size.
file.size              # => 6
stat.size              # => 3  # Snapshot unchanged.
stat = File.stat(path) # Fresh snapshot.
stat.size              # => 6  # Shapshot different.
# Clean up.
file.close
File.delete(path)

size? → integer or nil

() → Integer?

Source

static VALUE
rb_stat_s(VALUE obj)
{
    rb_off_t size = get_stat(obj)->ST_(size);

    if (size == 0) return Qnil;
    return OFFT2NUM(size);
}

Returns the size in bytes of the entry in self if the entry exists and has non-zero size, nil otherwise:

path = '/tmp/t.tmp'
File.write(path, 'foo')
File.size(path)        # => 3
stat = File.stat(path)           # Take snapshot.
stat.size?             # => 3    # Non-zero size.
File.write(path, '')
File.size(path)        # => 0
stat.size?             # => 3    # Snapshot unchanged.
stat = File.stat(path)           # Take new snapshot.
stat.size?             # => nil  # Zero size
File.delete(path)                # Clean up.

socket? → true or false

() → bool

Source

static VALUE
rb_stat_S(VALUE obj)
{
#ifdef S_ISSOCK
    if (S_ISSOCK(get_stat(obj)->ST_(mode))) return Qtrue;

#endif
    return Qfalse;
}

Returns whether entry in self is a socket:

sock_path = '/tmp/socket'
server = UNIXServer.new(sock_path)
stat = File.stat(sock_path)
stat.socket?           # => true
File.delete(sock_path) # Clean up.
stat.socket?           # => true
file_path = '/etc/passwd'
File.exist?(file_path) # => true  # Snapshot not updated.
stat = File.stat(file_path)
stat.socket?           # => false

sticky? → true or false

() → bool

Source

static VALUE
rb_stat_sticky(VALUE obj)
{
#ifdef S_ISVTX
    if (get_stat(obj)->ST_(mode) & S_ISVTX) return Qtrue;
#endif
    return Qfalse;
}

Returns whether the sticky bit is set in the special bits for self:

filepath = '/tmp/t.tmp'
File.write(filepath, 'foo')
stat = File.stat(filepath)
stat.sticky?                # => false
stat.mode.to_s(8)           # => "100664"
File.chmod(01644, filepath) # => 1        # Stat unchanged.
stat.sticky?                # => false
stat.mode.to_s(8)           # => "100664"
stat = File.stat(filepath)                # Fresh stat.
stat.sticky?                # => true
stat.mode.to_s(8)           # => "101644"
File.delete(filepath)                     # Clean up.

Returns false on Windows.

symlink? → true or false

() → bool

Source

static VALUE
rb_stat_l(VALUE obj)
{
#ifdef S_ISLNK
    if (S_ISLNK(get_stat(obj)->ST_(mode))) return Qtrue;
#endif
    return Qfalse;
}

Returns whether the entry in self (see Snapshot) is a symbolic link:

filepath = '/etc/passwd'
linkpath = '/tmp/foo'
File.symlink(filepath, linkpath)
File.stat(filepath).symlink?  # => false
File.lstat(filepath).symlink? # => false
stat = File.stat(linkpath)    # Snapshot with stat follows link.
stat.symlink?                 # => false
lstat = File.lstat(linkpath)  # Snapshot with lstat does not follow link.
lstat.symlink?                # => true
File.delete(linkpath)         # Clean up.
# Snapshots are unchanged, even when link deleted.
stat.symlink?                 # => false
lstat.symlink?                # => true

uid → integer

() → Integer

Source

static VALUE
rb_stat_uid(VALUE self)
{
    return UIDT2NUM(get_stat(self)->ST_(uid));
}

Returns the numeric user id of the owner of stat.

File.stat("testfile").uid   #=> 501

world_readable? → integer or nil

() → Integer?

Source

static VALUE
rb_stat_wr(VALUE obj)
{
#ifdef S_IROTH
    rb_io_stat_data *st = get_stat(obj);
    if ((st->ST_(mode) & (S_IROTH)) == S_IROTH) {
        return UINT2NUM(st->ST_(mode) & (S_IRUGO|S_IWUGO|S_IXUGO));
    }
#endif
    return Qnil;
}

If the entry in self exists and is readable by others, returns the integer permissions for the entry; otherwise, returns nil:

filepath = '/tmp/t.tmp'
File.write(filepath, 'foo')
File.stat(filepath).world_readable?.to_s(8) # => "664"  # World-readable.
File.chmod(0o000, filepath)                             # Make unreadable.
File.stat(filepath).world_readable?         # => nil    # Not world-readable.
File.delete(filepath)                                   # Clean up.
File.stat('.').world_readable?.to_s(8)      # => "775"  # Directory.

world_writable? → integer or nil

() → Integer?

Source

static VALUE
rb_stat_ww(VALUE obj)
{
#ifdef S_IWOTH
    rb_io_stat_data *st = get_stat(obj);
    if ((st->ST_(mode) & (S_IWOTH)) == S_IWOTH) {
        return UINT2NUM(st->ST_(mode) & (S_IRUGO|S_IWUGO|S_IXUGO));
    }
#endif
    return Qnil;
}

If the entry in self exists and is writable by others, returns the integer permissions for the entry; otherwise, returns nil:

filepath = '/tmp/t.tmp'
File.write(filepath, 'foo')
File.stat(filepath).world_writable?         # => nil   # Not world-writable.
File.chmod(0o777, filepath)                            # Make world-writable.
File.stat(filepath).world_writable?.to_s(8) # => "777" # World-writable.
File.delete(filepath)                                  # Clean up.
File.stat('/tmp').world_writable?.to_s(8)   # => "777" # Directory.

writable? → true or false

() → bool

Source

static VALUE
rb_stat_w(VALUE obj)
{
    rb_io_stat_data *st = get_stat(obj);

#ifdef USE_GETEUID
    if (geteuid() == 0) return Qtrue;
#endif
#ifdef S_IWUSR
    if (rb_stat_owned(obj))
        return RBOOL(st->ST_(mode) & S_IWUSR);
#endif
#ifdef S_IWGRP
    if (rb_stat_grpowned(obj))
        return RBOOL(st->ST_(mode) & S_IWGRP);
#endif
#ifdef S_IWOTH
    if (!(st->ST_(mode) & S_IWOTH)) return Qfalse;
#endif
    return Qtrue;
}

Returns whether the entry at the path in self exists and is writable by the effective owner and group in the current process:

filepath = '/tmp/secret.txt'
File.write(filepath, 'foo')
File.stat(filepath).writable? # => true   # Writable.
File.chmod(0o000, filepath)               # Make non-writable.
File.stat(filepath).writable? # => false  # Not writable.
File.delete(filepath)                     # Clean up.
File.stat('/etc').writable?   # => false  # Directory.

Note that filesystem security features may cause this method to return true even when the file is not writable by the effective owner and group.

writable_real? → true or false

() → bool

Source

static VALUE
rb_stat_W(VALUE obj)
{
    rb_io_stat_data *st = get_stat(obj);

#ifdef USE_GETEUID
    if (getuid() == 0) return Qtrue;
#endif
#ifdef S_IWUSR
    if (rb_stat_rowned(obj))
        return RBOOL(st->ST_(mode) & S_IWUSR);
#endif
#ifdef S_IWGRP
    if (rb_group_member(get_stat(obj)->ST_(gid)))
        return RBOOL(st->ST_(mode) & S_IWGRP);
#endif
#ifdef S_IWOTH
    if (!(st->ST_(mode) & S_IWOTH)) return Qfalse;
#endif
    return Qtrue;
}

Like File::Stat.writable?, but checks against the real owner and group instead of the effective owner and group.

Note that filesystem security features may cause this method to return true even when the entry in self is not writable by the real owner and group.

zero? → true or false

() → bool

Source

static VALUE
rb_stat_z(VALUE obj)
{
    if (get_stat(obj)->ST_(size) == 0) return Qtrue;
    return Qfalse;
}

Returns whether the entry at the path in self has size zero.

The entry may be a file:

filepath = '/tmp/t.tmp'
File.write(filepath, 'foo')
File.stat(filepath).zero? # => false
File.truncate(filepath, 0)
File.stat(filepath).zero? # => true
File.delete(filepath)     # Clean up.

The entry may be a directory:

dirpath = '/tmp/foo'
Dir.mkdir(dirpath)
stat = File.stat(dirpath)
# Size is filesystem-dependent; may or may not be zero.
stat.size                              # => 4096
stat.zero?                             # => false
filepath = File.join(dirpath, 't.tmp') # => "/tmp/foo/t.tmp"
File.write(filepath, 'foo')
stat = File.stat(dirpath)
stat.size                              # => 4096
stat.zero?                             # => false
FileUtils.rm_rf(dirpath)               # Clean up.

class File::Stat

Snapshot

Filesystem Dependencies