module FileTest - Documentation for Ruby 3.3

# module FileTest

`FileTest` implements file test operations similar to those used in `File::Stat`. It exists as a standalone module, and its methods are also insinuated into the `File` class. (Note that this is not done by inclusion: the interpreter cheats).

### Public Instance Methods

blockdev?(filepath) → true or false click to toggle source

Returns `true` if `filepath` points to a block device, `false` otherwise:

    File.blockdev?('/dev/sda1')       # => true
    File.blockdev?(File.new('t.tmp')) # => false

    static VALUE
    rb_file_blockdev_p(VALUE obj, VALUE fname)
    {
    #ifndef S_ISBLK
    #   ifdef S_IFBLK
    #       define S_ISBLK(m) (((m) & S_IFMT) == S_IFBLK)
    #   else
    #       define S_ISBLK(m) (0)  /* anytime false */
    #   endif
    #endif

    #ifdef S_ISBLK
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        if (S_ISBLK(st.st_mode)) return Qtrue;

    #endif
        return Qfalse;
    }

chardev?(filepath) → true or false click to toggle source

Returns `true` if `filepath` points to a character device, `false` otherwise.

    File.chardev?($stdin)     # => true
    File.chardev?('t.txt')     # => false

    static VALUE
    rb_file_chardev_p(VALUE obj, VALUE fname)
    {
    #ifndef S_ISCHR
    #   define S_ISCHR(m) (((m) & S_IFMT) == S_IFCHR)
    #endif

        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        if (S_ISCHR(st.st_mode)) return Qtrue;

        return Qfalse;
    }

directory?(path) → true or false click to toggle source

With string `object` given, returns `true` if `path` is a string path leading to a directory, or to a symbolic link to a directory; `false` otherwise:

    File.directory?('.')              # => true
    File.directory?('foo')            # => false
    File.symlink('.', 'dirlink')      # => 0
    File.directory?('dirlink')        # => true
    File.symlink('t,txt', 'filelink') # => 0
    File.directory?('filelink')       # => false

Argument `path` can be an `IO` object.

    VALUE
    rb_file_directory_p(VALUE obj, VALUE fname)
    {
    #ifndef S_ISDIR
    #   define S_ISDIR(m) (((m) & S_IFMT) == S_IFDIR)
    #endif

        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        if (S_ISDIR(st.st_mode)) return Qtrue;
        return Qfalse;
    }

empty?
Alias for: zero?
executable?(file_name) → true or false click to toggle source

Returns `true` if the named file is executable by the effective user and group id of this process. See eaccess(3).

Windows does not support execute permissions separately from read permissions. On Windows, a file is only considered executable if it ends in .bat, .cmd, .com, or .exe.

Note that some OS-level security features may cause this to return true even though the file is not executable by the effective user/group.

    static VALUE
    rb_file_executable_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_eaccess(fname, X_OK) >= 0);
    }

executable_real?(file_name) → true or false click to toggle source

Returns `true` if the named file is executable by the real user and group id of this process. See access(3).

Windows does not support execute permissions separately from read permissions. On Windows, a file is only considered executable if it ends in .bat, .cmd, .com, or .exe.

Note that some OS-level security features may cause this to return true even though the file is not executable by the real user/group.

    static VALUE
    rb_file_executable_real_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_access(fname, X_OK) >= 0);
    }

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

Return `true` if the named file exists.

file_name can be an `IO` object.

“file exists” means that stat() or fstat() system call is successful.

    static VALUE
    rb_file_exist_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return Qtrue;
    }

file?(file) → true or false click to toggle source

Returns `true` if the named `file` exists and is a regular file.

`file` can be an `IO` object.

If the `file` argument is a symbolic link, it will resolve the symbolic link and use the file referenced by the link.

    static VALUE
    rb_file_file_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return RBOOL(S_ISREG(st.st_mode));
    }

grpowned?(file_name) → true or false click to toggle source

Returns `true` if the named file exists and the effective group id of the calling process is the owner of the file. Returns `false` on Windows.

file_name can be an `IO` object.

    static VALUE
    rb_file_grpowned_p(VALUE obj, VALUE fname)
    {
    #ifndef _WIN32
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        if (rb_group_member(st.st_gid)) return Qtrue;
    #endif
        return Qfalse;
    }

identical?(file_1, file_2) → true or false click to toggle source

Returns `true` if the named files are identical.

file_1 and file_2 can be an `IO` object.

    open("a", "w") {}
    p File.identical?("a", "a")      #=> true
    p File.identical?("a", "./a")    #=> true
    File.link("a", "b")
    p File.identical?("a", "b")      #=> true
    File.symlink("a", "c")
    p File.identical?("a", "c")      #=> true
    open("d", "w") {}
    p File.identical?("a", "d")      #=> false

    static VALUE
    rb_file_identical_p(VALUE obj, VALUE fname1, VALUE fname2)
    {
    #ifndef _WIN32
        struct stat st1, st2;

        if (rb_stat(fname1, &st1) < 0) return Qfalse;
        if (rb_stat(fname2, &st2) < 0) return Qfalse;
        if (st1.st_dev != st2.st_dev) return Qfalse;
        if (st1.st_ino != st2.st_ino) return Qfalse;
        return Qtrue;
    #else
        extern VALUE rb_w32_file_identical_p(VALUE, VALUE);
        return rb_w32_file_identical_p(fname1, fname2);
    #endif
    }

owned?(file_name) → true or false click to toggle source

Returns `true` if the named file exists and the effective used id of the calling process is the owner of the file.

file_name can be an `IO` object.

    static VALUE
    rb_file_owned_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return RBOOL(st.st_uid == geteuid());
    }

pipe?(filepath) → true or false click to toggle source

Returns `true` if `filepath` points to a pipe, `false` otherwise:

    File.mkfifo('tmp/fifo')
    File.pipe?('tmp/fifo') # => true
    File.pipe?('t.txt')    # => false

    static VALUE
    rb_file_pipe_p(VALUE obj, VALUE fname)
    {
    #ifdef S_IFIFO
    #  ifndef S_ISFIFO
    #    define S_ISFIFO(m) (((m) & S_IFMT) == S_IFIFO)
    #  endif

        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        if (S_ISFIFO(st.st_mode)) return Qtrue;

    #endif
        return Qfalse;
    }

readable?(file_name) → true or false click to toggle source

Returns `true` if the named file is readable by the effective user and group id of this process. See eaccess(3).

Note that some OS-level security features may cause this to return true even though the file is not readable by the effective user/group.

    static VALUE
    rb_file_readable_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_eaccess(fname, R_OK) >= 0);
    }

readable_real?(file_name) → true or false click to toggle source

Returns `true` if the named file is readable by the real user and group id of this process. See access(3).

Note that some OS-level security features may cause this to return true even though the file is not readable by the real user/group.

    static VALUE
    rb_file_readable_real_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_access(fname, R_OK) >= 0);
    }

setgid?(file_name) → true or false click to toggle source

Returns `true` if the named file has the setgid bit set.

file_name can be an `IO` object.

    static VALUE
    rb_file_sgid_p(VALUE obj, VALUE fname)
    {
    #ifdef S_ISGID
        return check3rdbyte(fname, S_ISGID);
    #else
        return Qfalse;
    #endif
    }

setuid?(file_name) → true or false click to toggle source

Returns `true` if the named file has the setuid bit set.

file_name can be an `IO` object.

    static VALUE
    rb_file_suid_p(VALUE obj, VALUE fname)
    {
    #ifdef S_ISUID
        return check3rdbyte(fname, S_ISUID);
    #else
        return Qfalse;
    #endif
    }

size(file_name) → integer click to toggle source

Returns the size of `file_name`.

file_name can be an `IO` object.

    static VALUE
    rb_file_s_size(VALUE klass, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) {
            int e = errno;
            FilePathValue(fname);
            rb_syserr_fail_path(e, fname);
        }
        return OFFT2NUM(st.st_size);
    }

size?(file_name) → Integer or nil click to toggle source

Returns `nil` if `file_name` doesn’t exist or has zero size, the size of the file otherwise.

file_name can be an `IO` object.

    static VALUE
    rb_file_size_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qnil;
        if (st.st_size == 0) return Qnil;
        return OFFT2NUM(st.st_size);
    }

socket?(filepath) → true or false click to toggle source

Returns `true` if `filepath` points to a socket, `false` otherwise:

    require 'socket'
    File.socket?(Socket.new(:INET, :STREAM)) # => true
    File.socket?(File.new('t.txt'))          # => false

    static VALUE
    rb_file_socket_p(VALUE obj, VALUE fname)
    {
    #ifndef S_ISSOCK
    #  ifdef _S_ISSOCK
    #    define S_ISSOCK(m) _S_ISSOCK(m)
    #  else
    #    ifdef _S_IFSOCK
    #      define S_ISSOCK(m) (((m) & S_IFMT) == _S_IFSOCK)
    #    else
    #      ifdef S_IFSOCK
    #        define S_ISSOCK(m) (((m) & S_IFMT) == S_IFSOCK)
    #      endif
    #    endif
    #  endif
    #endif

    #ifdef S_ISSOCK
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        if (S_ISSOCK(st.st_mode)) return Qtrue;
    #endif

        return Qfalse;
    }

sticky?(file_name) → true or false click to toggle source

Returns `true` if the named file has the sticky bit set.

file_name can be an `IO` object.

    static VALUE
    rb_file_sticky_p(VALUE obj, VALUE fname)
    {
    #ifdef S_ISVTX
        return check3rdbyte(fname, S_ISVTX);
    #else
        return Qfalse;
    #endif
    }

symlink?(filepath) → true or false click to toggle source

Returns `true` if `filepath` points to a symbolic link, `false` otherwise:

    symlink = File.symlink('t.txt', 'symlink')
    File.symlink?('symlink') # => true
    File.symlink?('t.txt')   # => false

    static VALUE
    rb_file_symlink_p(VALUE obj, VALUE fname)
    {
    #ifndef S_ISLNK
    #  ifdef _S_ISLNK
    #    define S_ISLNK(m) _S_ISLNK(m)
    #  else
    #    ifdef _S_IFLNK
    #      define S_ISLNK(m) (((m) & S_IFMT) == _S_IFLNK)
    #    else
    #      ifdef S_IFLNK
    #        define S_ISLNK(m) (((m) & S_IFMT) == S_IFLNK)
    #      endif
    #    endif
    #  endif
    #endif

    #ifdef S_ISLNK
        struct stat st;

        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (lstat_without_gvl(StringValueCStr(fname), &st) < 0) return Qfalse;
        if (S_ISLNK(st.st_mode)) return Qtrue;
    #endif

        return Qfalse;
    }

world_readable?(file_name) → integer or nil click to toggle source

If file_name is readable by others, returns an integer representing the file permission bits of file_name. Returns `nil` otherwise. The meaning of the bits is platform dependent; on Unix systems, see `stat(2)`.

file_name can be an `IO` object.

    File.world_readable?("/etc/passwd")           #=> 420
    m = File.world_readable?("/etc/passwd")
    sprintf("%o", m)                              #=> "644"

    static VALUE
    rb_file_world_readable_p(VALUE obj, VALUE fname)
    {
    #ifdef S_IROTH
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qnil;
        if ((st.st_mode & (S_IROTH)) == S_IROTH) {
            return UINT2NUM(st.st_mode & (S_IRUGO|S_IWUGO|S_IXUGO));
        }
    #endif
        return Qnil;
    }

world_writable?(file_name) → integer or nil click to toggle source

If file_name is writable by others, returns an integer representing the file permission bits of file_name. Returns `nil` otherwise. The meaning of the bits is platform dependent; on Unix systems, see `stat(2)`.

file_name can be an `IO` object.

    File.world_writable?("/tmp")                  #=> 511
    m = File.world_writable?("/tmp")
    sprintf("%o", m)                              #=> "777"

    static VALUE
    rb_file_world_writable_p(VALUE obj, VALUE fname)
    {
    #ifdef S_IWOTH
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qnil;
        if ((st.st_mode & (S_IWOTH)) == S_IWOTH) {
            return UINT2NUM(st.st_mode & (S_IRUGO|S_IWUGO|S_IXUGO));
        }
    #endif
        return Qnil;
    }

writable?(file_name) → true or false click to toggle source

Returns `true` if the named file is writable by the effective user and group id of this process. See eaccess(3).

Note that some OS-level security features may cause this to return true even though the file is not writable by the effective user/group.

    static VALUE
    rb_file_writable_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_eaccess(fname, W_OK) >= 0);
    }

writable_real?(file_name) → true or false click to toggle source

Returns `true` if the named file is writable by the real user and group id of this process. See access(3).

Note that some OS-level security features may cause this to return true even though the file is not writable by the real user/group.

    static VALUE
    rb_file_writable_real_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_access(fname, W_OK) >= 0);
    }

zero?(file_name) → true or false click to toggle source

Returns `true` if the named file exists and has a zero size.

file_name can be an `IO` object.

    static VALUE
    rb_file_zero_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return RBOOL(st.st_size == 0);
    }

Also aliased as: empty?