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
(path | io file_name) → boolSource
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;
}
Returns whether object (a path or IO object) represents a block device (i.e., a direct-access device):
File.blockdev?('/dev/nvme0n1') # => true File.blockdev?('/dev/loop0') # => true File.blockdev?('/dev/tty') # => false File.blockdev?('/dev/null') # => false File.blockdev?('nosuch') # => false File.blockdev?($stdin) # => false
The returned value is filesystem-dependent; on Windows, always false.
(path | io file_name) → boolSource
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;
}
Returns whether object (a path or IO object) represents a character device (i.e., a sequential-access device):
File.chardev?('/dev/tty') # => true File.chardev?('/dev/null') # => true File.chardev?($stdin) # => true File.chardev?('/dev/nvme0n1') # => false File.chardev?('/dev/loop0') # => false File.chardev?('nosuch') # => false
The returned value is filesystem-dependent; on Windows, always false.
(path | io file_name) → boolSource
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;
}
Returns whether the given object represents a directory; object may be a string path or an IO object:
File.directory?('/etc') # => true File.directory?('lib') # => true File.directory?('README.md') # => false File.directory?('nosuch') # => false File.directory?($stdin) # => false
Follows symbolic links:
dirpath = 'doc/dirname' File.symlink('.', dirpath) File.directory?(dirpath) # => true File.unlink(dirpath) filepath = 't.tmp' File.symlink('README.md', filepath) File.directory?(filepath) # => false File.unlink(filepath)
(path | io file_name) → boolReturns whether the given object exists and has size zero.
The given object may be the path to a directory (possibly non-existent):
dirpath = 'foo' File.empty?(dirpath) # => false # Directory does not exist. dir = Dir.mkdir(dirpath) # The directory size is filesystem-dependent; # for a directory with no children, may or may not be zero. File.size?(dirpath) # => 4096 File.empty?(dirpath) # => false
The given object may be the path to a file (possibly non-existent):
filepath = File.join(dirpath, 't.tmp') File.empty?(filepath) # => false # File does not exist. File.write(filepath, '') File.size(filepath) # => 0 File.empty?(filepath) # => true # File exists; size zero. File.size?(dirpath) # => 4096 File.empty?(dirpath) # => false File.write(filepath, 'bar') File.size(filepath) # => 3 File.empty?(filepath) # => false # File exists; size non-zero. FileUtils.rm_rf(dirpath) # Clean up.
The given object may be an IO object:
File.empty?($stdin) # => true
(path file_name) → boolSource
static VALUE
rb_file_executable_p(VALUE obj, VALUE fname)
{
return RBOOL(rb_eaccess(fname, X_OK) >= 0);
}
Returns whether the filesystem entry at the given string path exists and is executable.
On Windows, the entry is executable if its path has file extension .bat, .cmd, .com, or .exe:
File.executable?('win32/rtname.cmd') # => true File.executable?('win32/rtname') # => false File.executable?('win32/nosuch.cmd') # => 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.
These examples use a helper method, mode, that displays a mode both in octal digits and in characters:
File.executable?('.') # => true mode('.') # => "040775 drwxrwxr-x" File.executable?('bin/gem') # => true mode('bin/gem') # => "100775 -rwxrwxr-x" File.executable?('/etc/passwd') # => false mode('/etc/passwd') # => "100644 -rw-r--r--" File.executable?('nosuch') # => false
Note that some filesystem settings may cause this method to return true even though the entry is not executable by the effective user/group.
(path file_name) → boolSource
static VALUE
rb_file_executable_real_p(VALUE obj, VALUE fname)
{
return RBOOL(rb_access(fname, X_OK) >= 0);
}
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.
(path | io file_name) → boolSource
static VALUE
rb_file_exist_p(VALUE obj, VALUE fname)
{
struct stat st;
if (rb_stat(fname, &st) < 0) return Qfalse;
return Qtrue;
}
Return whether the specified object, a string path or IO object, exists:
# String paths. File.exist?('README.md') # => true File.exist?('.') # => true filepath = 't.tmp' File.exist?(filepath) # => false File.write(filepath, 'foo') File.exist?(filepath) # => true # File (IO object). file = File.new(filepath) File.exist?(file) # => true file.close # Clean up.
(path | io file) → boolSource
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));
}
Returns whether the given object, a string path or IO object, represents a filesystem entry that exists and is a regular file; see File.ftype:
# Paths. File.file?('README.md') # => true File.file?('doc/') # => false File.file?('nosuch') # => false # IO objects. file = File.new('README.md') File.file?(file) # => true dir = Dir.new('doc/') File.file?(dir) # => false # Clean up. file.close dir.close
(path | io file_name) → boolSource
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;
}
Returns whether the filesystem entry for the given object exists, and the effective group id of the calling process is the owner of the entry.
The given object may be the string path to a file or directory entry:
File.grpowned?('lib') # => true File.grpowned?('README.md') # => true File.grpowned?('/etc/passwd') # => false File.grpowned?('nosuch') # => false
Or an open IO stream:
File.open('README.md', 'r') {|file| File.grpowned?(file) } # => true File.open('/etc/passwd', 'r') {|file| File.grpowned?(file) } # => false
Returns false on Windows.
(path | io file_1, path | io file_2) → boolSource
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
}
Returns whether the given objects represent filesystem entries that are identical; each object may be a string path or an IO object:
# Paths. File.identical?('README.md', 'README.md') # => true # Same path. File.identical?('README.md', './README.md') # => true # Same entry. File.identical?('.', '.') # => true # Directory. File.identical?('README.md', 'LEGAL') # => false File.identical?('README.md', 'nosuch') # => false # Non-existent entry. # Links and File object. File.link('README.md', 'link') # Symbolic link. File.symlink('README.md', 'symlink') # Hard link. file = File.open('README.md', 'r') # File object. File.identical?('README.md', 'link') # => true File.identical?('README.md', 'symlink') # => true File.identical?('README.md', file) # => true # Clean up. File.unlink('link') File.unlink('symlink') file.close
(path | io file_name) → boolSource
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());
}
Returns true if the named file exists and the effective user id of the calling process is the owner of the file.
file_name can be an IO object.
(path | io file_name) → boolSource
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;
}
Returns true if filepath points to a pipe, false otherwise:
File.mkfifo('tmp/fifo') File.pipe?('tmp/fifo') # => true File.pipe?('t.txt') # => false
(path file_name) → boolSource
static VALUE
rb_file_readable_p(VALUE obj, VALUE fname)
{
return RBOOL(rb_eaccess(fname, R_OK) >= 0);
}
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.
(path file_name) → boolSource
static VALUE
rb_file_readable_real_p(VALUE obj, VALUE fname)
{
return RBOOL(rb_access(fname, R_OK) >= 0);
}
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.
(path | io file_name) → boolSource
static VALUE
rb_file_sgid_p(VALUE obj, VALUE fname)
{
#ifdef S_ISGID
return check3rdbyte(fname, S_ISGID);
#else
return Qfalse;
#endif
}
Returns true if the named file has the setgid bit set.
file_name can be an IO object.
(path | io file_name) → boolSource
static VALUE
rb_file_suid_p(VALUE obj, VALUE fname)
{
#ifdef S_ISUID
return check3rdbyte(fname, S_ISUID);
#else
return Qfalse;
#endif
}
Returns true if the named file has the setuid bit set.
file_name can be an IO object.
(path | io file_name) → IntegerSource
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);
}
Returns the size of file_name.
file_name can be an IO object.
(path | io file_name) → Integer?Source
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);
}
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.
(path | io file_name) → boolSource
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;
}
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
(path | io file_name) → boolSource
static VALUE
rb_file_sticky_p(VALUE obj, VALUE fname)
{
#ifdef S_ISVTX
return check3rdbyte(fname, S_ISVTX);
#else
return Qfalse;
#endif
}
Returns true if the named file has the sticky bit set.
file_name can be an IO object.
(path file_name) → boolSource
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;
}
Returns whether the entry at path is a symbolic link:
# Create paths. file_path = 'doc/extension.rdoc' # => "doc/extension.rdoc" target_path = File.join('..', file_path) # => "../doc/extension.rdoc" link_path = 'lib/u.tmp' # => "lib/u.tmp" File.symlink?(link_path) # => false # Create link and verify. File.symlink(target_path, link_path) File.symlink?(link_path) # => true File.delete(link_path) # Clean up.
(path | io file_name) → Integer?Source
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;
}
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"
(path | io file_name) → Integer?Source
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;
}
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"
(path file_name) → boolSource
static VALUE
rb_file_writable_p(VALUE obj, VALUE fname)
{
return RBOOL(rb_eaccess(fname, W_OK) >= 0);
}
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.
(path file_name) → boolSource
static VALUE
rb_file_writable_real_p(VALUE obj, VALUE fname)
{
return RBOOL(rb_access(fname, W_OK) >= 0);
}
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.
(path | io file_name) → boolSource
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);
}
Returns whether the given object exists and has size zero.
The given object may be the path to a directory (possibly non-existent):
dirpath = 'foo' File.empty?(dirpath) # => false # Directory does not exist. dir = Dir.mkdir(dirpath) # The directory size is filesystem-dependent; # for a directory with no children, may or may not be zero. File.size?(dirpath) # => 4096 File.empty?(dirpath) # => false
The given object may be the path to a file (possibly non-existent):
filepath = File.join(dirpath, 't.tmp') File.empty?(filepath) # => false # File does not exist. File.write(filepath, '') File.size(filepath) # => 0 File.empty?(filepath) # => true # File exists; size zero. File.size?(dirpath) # => 4096 File.empty?(dirpath) # => false File.write(filepath, 'bar') File.size(filepath) # => 3 File.empty?(filepath) # => false # File exists; size non-zero. FileUtils.rm_rf(dirpath) # Clean up.
The given object may be an IO object:
File.empty?($stdin) # => true