Class: File (Ruby 1.9.3)
Quicksearch
A File is an abstraction of any file object accessible by the
program and is closely associated with class IO
File includes the methods of module FileTest as
class methods, allowing you to write (for example)
File.exist?(&foo&).
In the description of
methods, permission
bits are a platform-specific set of bits that indicate permissions of
a file. On Unix-based systems, permissions are viewed as a set of three
octets, for the owner, the group, and the rest of the world. For each of
these entities, permissions may be set to read, write, or execute the file:
The permission bits 0644 (in octal) would thus be interpreted
as read/write for owner, and read-only for group and other. Higher-order
bits may also be used to indicate the type of file (plain, directory, pipe,
socket, and so on) and various other special features. If the permissions
are for a directory, the meaning of the when set the
directory can be searched.
On non-Posix operating systems, there may be only the ability to make a
file read-only or read-write. In this case, the remaining permission bits
will be synthesized to resemble typical values. For instance, on Windows NT
the default permission bits are 0644, which means read/write
for owner, read-only for all others. The only change that can be made is to
make the file read-only, which is reported as 0444.
Converts a pathname to an absolute pathname. Relative paths are referenced
from the current working directory of the process unless
dir_string is given, in which case it will be used as the starting
point. If the given pathname starts with a “~” it is NOT
expanded, it is treated as a normal directory name.
File.absolute_path(&~oracle/bin&)
rb_file_s_absolute_path(int argc, VALUE *argv)
VALUE fname,
if (argc == 1) {
return rb_file_absolute_path(argv[0], Qnil);
rb_scan_args(argc, argv, &11&, &fname, &dname);
return rb_file_absolute_path(fname, dname);
Returns the last access time for the named file as a Time object).
File.atime(&testfile&)
Returns the last component of the filename given in file_name,
which must be formed using forward slashes (“/”) regardless of
the separator used on the local file system. If suffix is given
and present at the end of file_name, it is removed.
File.basename(&/home/gumby/work/ruby.rb&)
File.basename(&/home/gumby/work/ruby.rb&, &.rb&)
static VALUE
rb_file_s_basename(int argc, VALUE *argv)
VALUE fname, fext,
const char *name, *p;
rb_encoding *
if (rb_scan_args(argc, argv, &11&, &fname, &fext) == 2) {
rb_encoding *
StringValue(fext);
if (!rb_enc_asciicompat(enc = rb_enc_get(fext))) {
rb_raise(rb_eEncCompatError, &ascii incompatible character encodings: %s&,
rb_enc_name(enc));
FilePathStringValue(fname);
if (!NIL_P(fext)) enc = rb_enc_check(fname, fext);
else enc = rb_enc_get(fname);
if ((n = RSTRING_LEN(fname)) == 0 || !*(name = RSTRING_PTR(fname)))
return rb_str_new_shared(fname);
p = ruby_enc_find_basename(name, &f, &n, enc);
if (n &= 0) {
if (NIL_P(fext)) {
rb_encoding *fenc = rb_enc_get(fext);
const char *
if (enc != fenc &&
rb_enc_str_coderange(fext) != ENC_CODERANGE_7BIT) {
fext = rb_str_conv_enc(fext, fenc, enc);
fp = StringValueCStr(fext);
if (!(f = rmext(p, f, n, fp, RSTRING_LEN(fext), enc))) {
RB_GC_GUARD(fext);
if (f == RSTRING_LEN(fname)) return rb_str_new_shared(fname);
basename = rb_str_new(p, f);
rb_enc_copy(basename, fname);
OBJ_INFECT(basename, fname);
Returns true if the named file is a block device.
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)
define S_ISBLK(m) (0)
/* anytime false */
#ifdef S_ISBLK
if (rb_stat(fname, &st) & 0) return Q
if (S_ISBLK(st.st_mode)) return Q
Returns true if the named file is a character device.
static VALUE
rb_file_chardev_p(VALUE obj, VALUE fname)
#ifndef S_ISCHR
define S_ISCHR(m) (((m) & S_IFMT) == S_IFCHR)
if (rb_stat(fname, &st) & 0) return Q
if (S_ISCHR(st.st_mode)) return Q
Changes permission bits on the named file(s) to the bit pattern represented
by mode_int. Actual effects are operating system dependent (see
the beginning of this section). On Unix systems, see chmod(2)
for details. Returns the number of files processed.
File.chmod(0644, &testfile&, &out&)
static VALUE
rb_file_s_chmod(int argc, VALUE *argv)
rb_secure(2);
rb_scan_args(argc, argv, &1*&, &vmode, &rest);
mode = NUM2INT(vmode);
n = apply2files(chmod_internal, rest, &mode);
return LONG2FIX(n);
Changes the owner and group of the named file(s) to the given numeric owner
and group id’s. Only a process with superuser privileges may change the
owner of a file. The current owner of a file may change the file’s group to
any group to which the owner belongs. A nil or -1 owner or
group id is ignored. Returns the number of files processed.
File.chown(nil, 100, &testfile&)
static VALUE
rb_file_s_chown(int argc, VALUE *argv)
VALUE o, g,
struct chown_
rb_secure(2);
rb_scan_args(argc, argv, &2*&, &o, &g, &rest);
if (NIL_P(o)) {
arg.owner = -1;
arg.owner = NUM2UIDT(o);
if (NIL_P(g)) {
arg.group = -1;
arg.group = NUM2GIDT(g);
n = apply2files(chown_internal, rest, &arg);
return LONG2FIX(n);
Returns the change time for the named file (the time at which directory
information about the file was changed, not the file itself).
Note that on Windows (NTFS), returns creation time (birth time).
File.ctime(&testfile&)
Deletes the named files, returning the number of names passed as arguments.
Raises an exception on any error. See also Dir::rmdir.
static VALUE
rb_file_s_unlink(VALUE klass, VALUE args)
rb_secure(2);
n = apply2files(unlink_internal, args, 0);
return LONG2FIX(n);
Returns true if the named file is a directory, or a symlink
that points at a directory, and false otherwise.
File.directory?(&.&)
rb_file_directory_p(VALUE obj, VALUE fname)
#ifndef S_ISDIR
define S_ISDIR(m) (((m) & S_IFMT) == S_IFDIR)
if (rb_stat(fname, &st) & 0) return Q
if (S_ISDIR(st.st_mode)) return Q
Returns all components of the filename given in file_name except
the last one. The filename must be formed using forward slashes
(“/”) regardless of the separator used on the local file
File.dirname(&/home/gumby/work/ruby.rb&)
static VALUE
rb_file_s_dirname(VALUE klass, VALUE fname)
return rb_file_dirname(fname);
Returns true if the named file is executable by the effective
user id of this process.
static VALUE
rb_file_executable_p(VALUE obj, VALUE fname)
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (eaccess(StringValueCStr(fname), X_OK) & 0) return Q
Returns true if the named file is executable by the real user
id of this process.
static VALUE
rb_file_executable_real_p(VALUE obj, VALUE fname)
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (access_internal(StringValueCStr(fname), X_OK) & 0) return Q
Returns true if the named file is a directory,
false otherwise.
static VALUE
rb_file_exist_p(VALUE obj, VALUE fname)
if (rb_stat(fname, &st) & 0) return Q
Return true if the named file exists.
static VALUE
rb_file_exist_p(VALUE obj, VALUE fname)
if (rb_stat(fname, &st) & 0) return Q
Converts a pathname to an absolute pathname. Relative paths are referenced
from the current working directory of the process unless
dir_string is given, in which case it will be used as the starting
point. The given pathname may start with a “~”, which expands
to the process owner’s home directory (the environment variable
HOME must be set correctly). “~user”
expands to the named user’s home directory.
File.expand_path(&~oracle/bin&)
File.expand_path(&../../bin&, &/tmp/x&)
rb_file_s_expand_path(int argc, VALUE *argv)
VALUE fname,
if (argc == 1) {
return rb_file_expand_path(argv[0], Qnil);
rb_scan_args(argc, argv, &11&, &fname, &dname);
return rb_file_expand_path(fname, dname);
Returns the extension (the portion of file name in path after the
File.extname(&test.rb&)
File.extname(&a/b/d/test.rb&)
File.extname(&test&)
File.extname(&.profile&)
static VALUE
rb_file_s_extname(VALUE klass, VALUE fname)
const char *name, *e;
FilePathStringValue(fname);
name = StringValueCStr(fname);
len = RSTRING_LEN(fname);
e = ruby_enc_find_extname(name, &len, rb_enc_get(fname));
if (len &= 1)
return rb_str_new(0, 0);
extname = rb_str_subseq(fname, e - name, len); /* keep the dot, too! */
OBJ_INFECT(extname, fname);
Returns true if the named file exists and is a regular file.
static VALUE
rb_file_file_p(VALUE obj, VALUE fname)
if (rb_stat(fname, &st) & 0) return Q
if (S_ISREG(st.st_mode)) return Q
Returns true if path matches against pattern The pattern
instead it follows rules similar to shell
filename globbing. It may contain the following metacharacters:
Matches any file. Can be restricted by other values in the glob.
c* will match all files
beginning with c; *c will match all files ending
with c; and *c* will match all files that have
c in them (including at the beginning or end). Equivalent to
/ .* /x in regexp.
Matches directories recursively or files expansively.
Matches any one character. Equivalent to /.{1}/ in regexp.
Matches any one character in set. Behaves exactly like
character sets in , including set negation
&code&&/code&
Escapes the next metacharacter.
flags is a bitwise OR of the FNM_xxx parameters. The
same glob pattern and flags are used by Dir::glob.
File.fnmatch('cat',
File.fnmatch('cat',
'category')
File.fnmatch('c{at,ub}s', 'cats')
File.fnmatch('c?t',
File.fnmatch('c??t',
File.fnmatch('c*',
File.fnmatch('c*t',
'c/a/b/t')
File.fnmatch('ca[a-z]', 'cat')
File.fnmatch('ca[^t]',
File.fnmatch('cat', 'CAT')
File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD)
File.fnmatch('?',
'/', File::FNM_PATHNAME)
File.fnmatch('*',
'/', File::FNM_PATHNAME)
File.fnmatch('[/]', '/', File::FNM_PATHNAME)
File.fnmatch('\?',
File.fnmatch('\a',
File.fnmatch('\a',
'\a', File::FNM_NOESCAPE)
File.fnmatch('[\?]', '?')
File.fnmatch('*',
'.profile')
File.fnmatch('*',
'.profile', File::FNM_DOTMATCH)
File.fnmatch('.*',
'.profile')
rbfiles = '**' '/' '*.rb'
File.fnmatch(rbfiles, 'main.rb')
File.fnmatch(rbfiles, './main.rb')
File.fnmatch(rbfiles, 'lib/song.rb')
File.fnmatch('**.rb', 'main.rb')
File.fnmatch('**.rb', './main.rb')
File.fnmatch('**.rb', 'lib/song.rb')
File.fnmatch('*',
'dave/.profile')
pattern = '*' '/' '*'
File.fnmatch(pattern, 'dave/.profile', File::FNM_PATHNAME)
File.fnmatch(pattern, 'dave/.profile', File::FNM_PATHNAME | File::FNM_DOTMATCH)
pattern = '**' '/' 'foo'
File.fnmatch(pattern, 'a/b/c/foo', File::FNM_PATHNAME)
File.fnmatch(pattern, '/a/b/c/foo', File::FNM_PATHNAME)
File.fnmatch(pattern, 'c:/a/b/c/foo', File::FNM_PATHNAME)
File.fnmatch(pattern, 'a/.b/c/foo', File::FNM_PATHNAME)
File.fnmatch(pattern, 'a/.b/c/foo', File::FNM_PATHNAME | File::FNM_DOTMATCH)
static VALUE
file_s_fnmatch(int argc, VALUE *argv, VALUE obj)
VALUE pattern,
if (rb_scan_args(argc, argv, &21&, &pattern, &path, &rflags) == 3)
flags = NUM2INT(rflags);
flags = 0;
StringValue(pattern);
FilePathStringValue(path);
if (fnmatch(RSTRING_PTR(pattern), rb_enc_get(pattern), RSTRING_PTR(path),
flags) == 0)
Returns true if path matches against pattern The pattern
instead it follows rules similar to shell
filename globbing. It may contain the following metacharacters:
Matches any file. Can be restricted by other values in the glob.
c* will match all files
beginning with c; *c will match all files ending
with c; and *c* will match all files that have
c in them (including at the beginning or end). Equivalent to
/ .* /x in regexp.
Matches directories recursively or files expansively.
Matches any one character. Equivalent to /.{1}/ in regexp.
Matches any one character in set. Behaves exactly like
character sets in , including set negation
&code&&/code&
Escapes the next metacharacter.
flags is a bitwise OR of the FNM_xxx parameters. The
same glob pattern and flags are used by Dir::glob.
File.fnmatch('cat',
File.fnmatch('cat',
'category')
File.fnmatch('c{at,ub}s', 'cats')
File.fnmatch('c?t',
File.fnmatch('c??t',
File.fnmatch('c*',
File.fnmatch('c*t',
'c/a/b/t')
File.fnmatch('ca[a-z]', 'cat')
File.fnmatch('ca[^t]',
File.fnmatch('cat', 'CAT')
File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD)
File.fnmatch('?',
'/', File::FNM_PATHNAME)
File.fnmatch('*',
'/', File::FNM_PATHNAME)
File.fnmatch('[/]', '/', File::FNM_PATHNAME)
File.fnmatch('\?',
File.fnmatch('\a',
File.fnmatch('\a',
'\a', File::FNM_NOESCAPE)
File.fnmatch('[\?]', '?')
File.fnmatch('*',
'.profile')
File.fnmatch('*',
'.profile', File::FNM_DOTMATCH)
File.fnmatch('.*',
'.profile')
rbfiles = '**' '/' '*.rb'
File.fnmatch(rbfiles, 'main.rb')
File.fnmatch(rbfiles, './main.rb')
File.fnmatch(rbfiles, 'lib/song.rb')
File.fnmatch('**.rb', 'main.rb')
File.fnmatch('**.rb', './main.rb')
File.fnmatch('**.rb', 'lib/song.rb')
File.fnmatch('*',
'dave/.profile')
pattern = '*' '/' '*'
File.fnmatch(pattern, 'dave/.profile', File::FNM_PATHNAME)
File.fnmatch(pattern, 'dave/.profile', File::FNM_PATHNAME | File::FNM_DOTMATCH)
pattern = '**' '/' 'foo'
File.fnmatch(pattern, 'a/b/c/foo', File::FNM_PATHNAME)
File.fnmatch(pattern, '/a/b/c/foo', File::FNM_PATHNAME)
File.fnmatch(pattern, 'c:/a/b/c/foo', File::FNM_PATHNAME)
File.fnmatch(pattern, 'a/.b/c/foo', File::FNM_PATHNAME)
File.fnmatch(pattern, 'a/.b/c/foo', File::FNM_PATHNAME | File::FNM_DOTMATCH)
static VALUE
file_s_fnmatch(int argc, VALUE *argv, VALUE obj)
VALUE pattern,
if (rb_scan_args(argc, argv, &21&, &pattern, &path, &rflags) == 3)
flags = NUM2INT(rflags);
flags = 0;
StringValue(pattern);
FilePathStringValue(path);
if (fnmatch(RSTRING_PTR(pattern), rb_enc_get(pattern), RSTRING_PTR(path),
flags) == 0)
Identifies the ty the return string is one of
“file”, “directory”,
“characterSpecial”, “blockSpecial”,
“fifo”, “link”, “socket”, or
“unknown”.
File.ftype(&testfile&)
File.ftype(&/dev/tty&)
File.ftype(&/tmp/.X11-unix/X0&)
static VALUE
rb_file_s_ftype(VALUE klass, VALUE fname)
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (lstat(StringValueCStr(fname), &st) == -1) {
rb_sys_fail_path(fname);
return rb_file_ftype(&st);
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.
static VALUE
rb_file_grpowned_p(VALUE obj, VALUE fname)
#ifndef _WIN32
if (rb_stat(fname, &st) & 0) return Q
if (rb_group_member(st.st_gid)) return Q
Returns true if the named files are identical.
open(&a&, &w&) {}
p File.identical?(&a&, &a&)
p File.identical?(&a&, &./a&)
File.link(&a&, &b&)
p File.identical?(&a&, &b&)
File.symlink(&a&, &c&)
p File.identical?(&a&, &c&)
open(&d&, &w&) {}
p File.identical?(&a&, &d&)
static VALUE
rb_file_identical_p(VALUE obj, VALUE fname1, VALUE fname2)
#ifndef DOSISH
struct stat st1, st2;
if (rb_stat(fname1, &st1) & 0) return Q
if (rb_stat(fname2, &st2) & 0) return Q
if (st1.st_dev != st2.st_dev) return Q
if (st1.st_ino != st2.st_ino) return Q
# ifdef _WIN32
BY_HANDLE_FILE_INFORMATION st1, st2;
HANDLE f1 = 0, f2 = 0;
rb_secure(2);
# ifdef _WIN32
f1 = w32_io_info(&fname1, &st1);
if (f1 == INVALID_HANDLE_VALUE) return Q
f2 = w32_io_info(&fname2, &st2);
if (f1) CloseHandle(f1);
if (f2 == INVALID_HANDLE_VALUE) return Q
if (f2) CloseHandle(f2);
if (st1.dwVolumeSerialNumber == st2.dwVolumeSerialNumber &&
st1.nFileIndexHigh == st2.nFileIndexHigh &&
st1.nFileIndexLow == st2.nFileIndexLow)
if (!f1 || !f2) return Q
if (rb_w32_iswin95()) return Q
FilePathValue(fname1);
fname1 = rb_str_new4(fname1);
fname1 = rb_str_encode_ospath(fname1);
FilePathValue(fname2);
fname2 = rb_str_encode_ospath(fname2);
if (access(RSTRING_PTR(fname1), 0)) return Q
if (access(RSTRING_PTR(fname2), 0)) return Q
fname1 = rb_file_expand_path(fname1, Qnil);
fname2 = rb_file_expand_path(fname2, Qnil);
if (RSTRING_LEN(fname1) != RSTRING_LEN(fname2)) return Q
if (rb_memcicmp(RSTRING_PTR(fname1), RSTRING_PTR(fname2), RSTRING_LEN(fname1)))
Returns a new string formed by joining the strings using
File::SEPARATOR.
File.join(&usr&, &mail&, &gumby&)
static VALUE
rb_file_s_join(VALUE klass, VALUE args)
return rb_file_join(args, separator);
Equivalent to File::chmod, but does not follow symbolic links
(so it will change the permissions associated with the link, not the file
referenced by the link). Often not available.
static VALUE
rb_file_s_lchmod(int argc, VALUE *argv)
long mode,
rb_secure(2);
rb_scan_args(argc, argv, &1*&, &vmode, &rest);
mode = NUM2INT(vmode);
n = apply2files(lchmod_internal, rest, (void *)(long)mode);
return LONG2FIX(n);
Equivalent to File::chown, but does not follow symbolic links
(so it will change the owner associated with the link, not the file
referenced by the link). Often not available. Returns number of files in
the argument list.
static VALUE
rb_file_s_lchown(int argc, VALUE *argv)
VALUE o, g,
struct chown_
rb_secure(2);
rb_scan_args(argc, argv, &2*&, &o, &g, &rest);
if (NIL_P(o)) {
arg.owner = -1;
arg.owner = NUM2UIDT(o);
if (NIL_P(g)) {
arg.group = -1;
arg.group = NUM2GIDT(g);
n = apply2files(lchown_internal, rest, &arg);
return LONG2FIX(n);
Creates a new name for an existing file using a hard link. Will not
overwrite new_name if it already exists (raising a subclass of
SystemCallError). Not available on all platforms.
File.link(&testfile&, &.testfile&)
IO.readlines(&.testfile&)[0]
static VALUE
rb_file_s_link(VALUE klass, VALUE from, VALUE to)
rb_secure(2);
FilePathValue(from);
FilePathValue(to);
from = rb_str_encode_ospath(from);
to = rb_str_encode_ospath(to);
if (link(StringValueCStr(from), StringValueCStr(to)) & 0) {
sys_fail2(from, to);
return INT2FIX(0);
Same as File::stat, but does not follow the last symbolic
link. Instead, reports on the link itself.
File.symlink(&testfile&, &link2test&)
File.stat(&testfile&).size
File.lstat(&link2test&).size
File.stat(&link2test&).size
static VALUE
rb_file_s_lstat(VALUE klass, VALUE fname)
#ifdef HAVE_LSTAT
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (lstat(StringValueCStr(fname), &st) == -1) {
rb_sys_fail_path(fname);
return stat_new(&st);
return rb_file_s_stat(klass, fname);
Returns the modification time for the named file as a Time object.
File.mtime(&testfile&)
Opens the file named by filename according to
mode (default is “r”) and returns a new File
Parameters
See the description of class
for a description of
The file mode may optionally be specified as a Fixnum by or-ing together the flags
(O_RDONLY etc, again described under IO).
Optional permission bits may be given in perm.
These mode and
permission bits ar on Unix systems, see
open(2) for details.
Optional opt parameter is same as in IO.open.
f = File.new(&testfile&, &r&)
f = File.new(&newfile&,
f = File.new(&newfile&, File::CREAT|File::TRUNC|File::RDWR, 0644)
static VALUE
rb_file_initialize(int argc, VALUE *argv, VALUE io)
if (RFILE(io)-&fptr) {
rb_raise(rb_eRuntimeError, &reinitializing File&);
if (0 & argc && argc & 3) {
VALUE fd = rb_check_convert_type(argv[0], T_FIXNUM, &Fixnum&, &to_int&);
if (!NIL_P(fd)) {
return rb_io_initialize(argc, argv, io);
rb_open_file(argc, argv, io);
With no associated block, File.open is a synonym for ::new. If the optional code block is
given, it will be passed the opened file as an argument, and
object will automatically be closed when
the block terminates.
In this instance, File.open returns the
value of the block.
for a list of values for the
opt parameter.
static VALUE
rb_io_s_open(int argc, VALUE *argv, VALUE klass)
VALUE io = rb_class_new_instance(argc, argv, klass);
if (rb_block_given_p()) {
return rb_ensure(rb_yield, io, io_close, io);
Returns true if the named file exists and the effective used
id of the calling process is the owner of the file.
static VALUE
rb_file_owned_p(VALUE obj, VALUE fname)
if (rb_stat(fname, &st) & 0) return Q
if (st.st_uid == geteuid()) return Q
Returns the string representation of the path
File.path(&/dev/null&)
File.path(Pathname.new(&/tmp&))
static VALUE
rb_file_s_path(VALUE klass, VALUE fname)
return rb_get_path(fname);
Returns true if the named file is a pipe.
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)
if (rb_stat(fname, &st) & 0) return Q
if (S_ISFIFO(st.st_mode)) return Q
Returns true if the named file is readable by the effective
user id of this process.
static VALUE
rb_file_readable_p(VALUE obj, VALUE fname)
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (eaccess(StringValueCStr(fname), R_OK) & 0) return Q
Returns true if the named file is readable by the real user id
of this process.
static VALUE
rb_file_readable_real_p(VALUE obj, VALUE fname)
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (access_internal(StringValueCStr(fname), R_OK) & 0) return Q
Returns the name of the file referenced by the given link. Not available on
all platforms.
File.symlink(&testfile&, &link2test&)
File.readlink(&link2test&)
static VALUE
rb_file_s_readlink(VALUE klass, VALUE path)
return rb_readlink(path);
Returns the real (absolute) pathname of pathname in the actual
filesystem. The real pathname doesn’t contain symlinks or useless dots.
If dir_string is given, it is used as a base directory for
interpreting relative pathname instead of the current directory.
The last component of the real pathname can be nonexistent.
static VALUE
rb_file_s_realdirpath(int argc, VALUE *argv, VALUE klass)
VALUE path,
rb_scan_args(argc, argv, &11&, &path, &basedir);
return rb_realpath_internal(basedir, path, 0);
Returns the real (absolute) pathname of pathname in the actual
filesystem not containing symlinks or useless dots.
If dir_string is given, it is used as a base directory for
interpreting relative pathname instead of the current directory.
All components of the pathname must exist when this method is called.
static VALUE
rb_file_s_realpath(int argc, VALUE *argv, VALUE klass)
VALUE path,
rb_scan_args(argc, argv, &11&, &path, &basedir);
return rb_realpath_internal(basedir, path, 1);
Renames the given file to the new name. Raises a
SystemCallError if the file cannot be renamed.
File.rename(&afile&, &afile.bak&)
static VALUE
rb_file_s_rename(VALUE klass, VALUE from, VALUE to)
const char *src, *
rb_secure(2);
FilePathValue(from);
FilePathValue(to);
f = rb_str_encode_ospath(from);
t = rb_str_encode_ospath(to);
src = StringValueCStr(f);
dst = StringValueCStr(t);
#if defined __CYGWIN__
errno = 0;
if (rename(src, dst) & 0) {
#if defined DOSISH
switch (errno) {
case EEXIST:
#if defined (__EMX__)
case EACCES:
if (chmod(dst, 0666) == 0 &&
unlink(dst) == 0 &&
rename(src, dst) == 0)
return INT2FIX(0);
sys_fail2(from, to);
return INT2FIX(0);
Returns true if the named file has the setgid bit set.
static VALUE
rb_file_sgid_p(VALUE obj, VALUE fname)
#ifdef S_ISGID
return check3rdbyte(fname, S_ISGID);
Returns true if the named file has the setuid bit set.
static VALUE
rb_file_suid_p(VALUE obj, VALUE fname)
#ifdef S_ISUID
return check3rdbyte(fname, S_ISUID);
Returns the size of file_name.
static VALUE
rb_file_s_size(VALUE klass, VALUE fname)
if (rb_stat(fname, &st) & 0) {
FilePathValue(fname);
rb_sys_fail_path(fname);
return OFFT2NUM(st.st_size);
Returns nil if file_name doesn’t exist or has
zero size, the size of the file otherwise.
static VALUE
rb_file_size_p(VALUE obj, VALUE fname)
if (rb_stat(fname, &st) & 0) return Q
if (st.st_size == 0) return Q
return OFFT2NUM(st.st_size);
Returns true if the named file is a socket.
static VALUE
rb_file_socket_p(VALUE obj, VALUE fname)
#ifndef S_ISSOCK
ifdef _S_ISSOCK
define S_ISSOCK(m) _S_ISSOCK(m)
ifdef _S_IFSOCK
define S_ISSOCK(m) (((m) & S_IFMT) == _S_IFSOCK)
ifdef S_IFSOCK
define S_ISSOCK(m) (((m) & S_IFMT) == S_IFSOCK)
#ifdef S_ISSOCK
if (rb_stat(fname, &st) & 0) return Q
if (S_ISSOCK(st.st_mode)) return Q
Splits the given string into a directory and a file component and returns
them in a two-element array. See also File::dirname and
File::basename.
File.split(&/home/gumby/.profile&)
static VALUE
rb_file_s_split(VALUE klass, VALUE path)
FilePathStringValue(path);
/* get rid of converting twice */
return rb_assoc_new(rb_file_s_dirname(Qnil, path), rb_file_s_basename(1,&path));
Returns a File::Stat object for the named file (see
File::Stat).
File.stat(&testfile&).mtime
static VALUE
rb_file_s_stat(VALUE klass, VALUE fname)
rb_secure(4);
FilePathValue(fname);
if (rb_stat(fname, &st) & 0) {
rb_sys_fail_path(fname);
return stat_new(&st);
Returns true if the named file has the sticky bit set.
static VALUE
rb_file_sticky_p(VALUE obj, VALUE fname)
#ifdef S_ISVTX
return check3rdbyte(fname, S_ISVTX);
Creates a symbolic link called new_name for the existing file
old_name. Raises a NotImplemented exception on
platforms that do not support symbolic links.
File.symlink(&testfile&, &link2test&)
static VALUE
rb_file_s_symlink(VALUE klass, VALUE from, VALUE to)
rb_secure(2);
FilePathValue(from);
FilePathValue(to);
from = rb_str_encode_ospath(from);
to = rb_str_encode_ospath(to);
if (symlink(StringValueCStr(from), StringValueCStr(to)) & 0) {
sys_fail2(from, to);
return INT2FIX(0);
Returns true if the named file is a symbolic link.
static VALUE
rb_file_symlink_p(VALUE obj, VALUE fname)
#ifndef S_ISLNK
ifdef _S_ISLNK
define S_ISLNK(m) _S_ISLNK(m)
ifdef _S_IFLNK
define S_ISLNK(m) (((m) & S_IFMT) == _S_IFLNK)
ifdef S_IFLNK
define S_ISLNK(m) (((m) & S_IFMT) == S_IFLNK)
#ifdef S_ISLNK
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (lstat(StringValueCStr(fname), &st) & 0) return Q
if (S_ISLNK(st.st_mode)) return Q
Truncates the file file_name to be at most integer bytes
long. Not available on all platforms.
f = File.new(&out&, &w&)
f.write(&&)
File.truncate(&out&, 5)
File.size(&out&)
static VALUE
rb_file_s_truncate(VALUE klass, VALUE path, VALUE len)
rb_secure(2);
pos = NUM2OFFT(len);
FilePathValue(path);
path = rb_str_encode_ospath(path);
#ifdef HAVE_TRUNCATE
if (truncate(StringValueCStr(path), pos) & 0)
rb_sys_fail_path(path);
#else /* defined(HAVE_CHSIZE) */
if ((tmpfd = open(StringValueCStr(path), 0)) & 0) {
rb_sys_fail_path(path);
rb_update_max_fd(tmpfd);
if (chsize(tmpfd, pos) & 0) {
close(tmpfd);
rb_sys_fail_path(path);
close(tmpfd);
return INT2FIX(0);
Returns the current umask value for this process. If the optional argument
is given, set the umask to that value and return the previous value. Umask
values are subtracted from the default permissions, so a umask of
0222 would make a file read-only for everyone.
File.umask(0006)
File.umask
static VALUE
rb_file_s_umask(int argc, VALUE *argv)
int omask = 0;
rb_secure(2);
if (argc == 0) {
omask = umask(0);
umask(omask);
else if (argc == 1) {
omask = umask(NUM2INT(argv[0]));
rb_raise(rb_eArgError, &wrong number of arguments (%d for 0..1)&, argc);
return INT2FIX(omask);
Deletes the named files, returning the number of names passed as arguments.
Raises an exception on any error. See also Dir::rmdir.
static VALUE
rb_file_s_unlink(VALUE klass, VALUE args)
rb_secure(2);
n = apply2files(unlink_internal, args, 0);
return LONG2FIX(n);
Sets the access and modification times of each named file to the first two
arguments. Returns the number of file names in the argument list.
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 i
on Unix systems, see stat(2).
File.world_readable?(&/etc/passwd&)
m = File.world_readable?(&/etc/passwd&)
sprintf(&%o&, m)
static VALUE
rb_file_world_readable_p(VALUE obj, VALUE fname)
#ifdef S_IROTH
if (rb_stat(fname, &st) & 0) return Q
if ((st.st_mode & (S_IROTH)) == S_IROTH) {
return UINT2NUM(st.st_mode & (S_IRUGO|S_IWUGO|S_IXUGO));
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 i
on Unix systems, see stat(2).
File.world_writable?(&/tmp&)
m = File.world_writable?(&/tmp&)
sprintf(&%o&, m)
static VALUE
rb_file_world_writable_p(VALUE obj, VALUE fname)
#ifdef S_IWOTH
if (rb_stat(fname, &st) & 0) return Q
if ((st.st_mode & (S_IWOTH)) == S_IWOTH) {
return UINT2NUM(st.st_mode & (S_IRUGO|S_IWUGO|S_IXUGO));
Returns true if the named file is writable by the effective
user id of this process.
static VALUE
rb_file_writable_p(VALUE obj, VALUE fname)
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (eaccess(StringValueCStr(fname), W_OK) & 0) return Q
Returns true if the named file is writable by the real user id
of this process.
static VALUE
rb_file_writable_real_p(VALUE obj, VALUE fname)
rb_secure(2);
FilePathValue(fname);
fname = rb_str_encode_ospath(fname);
if (access_internal(StringValueCStr(fname), W_OK) & 0) return Q
Returns true if the named file exists and has a zero size.
static VALUE
rb_file_zero_p(VALUE obj, VALUE fname)
if (rb_stat(fname, &st) & 0) return Q
if (st.st_size == 0) return Q
Returns the last access time (a Time object)
for &i&file&/i&, or epoch if &i&file&/i& has not been accessed.
File.new(&testfile&).atime
#=& Wed Dec 31 18:00:00 CST 1969
Changes permission bits on file to the bit pattern represented by
mode_int. Actual effects ar on Unix systems,
see chmod(2) for details. Follows symbolic links. Also see
File#lchmod.
f = File.new(&out&, &w&);
f.chmod(0644)
static VALUE
rb_file_chmod(VALUE obj, VALUE vmode)
#ifndef HAVE_FCHMOD
rb_secure(2);
mode = NUM2INT(vmode);
GetOpenFile(obj, fptr);
#ifdef HAVE_FCHMOD
if (fchmod(fptr-&fd, mode) == -1)
rb_sys_fail_path(fptr-&pathv);
if (NIL_P(fptr-&pathv)) return Q
path = rb_str_encode_ospath(fptr-&pathv);
if (chmod(RSTRING_PTR(path), mode) == -1)
rb_sys_fail_path(fptr-&pathv);
return INT2FIX(0);
Changes the owner and group of file to the given numeric owner and
group id’s. Only a process with superuser privileges may change the owner
of a file. The current owner of a file may change the file’s group to any
group to which the owner belongs. A nil or -1 owner or group
id is ignored. Follows symbolic links. See also File#lchown.
File.new(&testfile&).chown(502, 1000)
static VALUE
rb_file_chown(VALUE obj, VALUE owner, VALUE group)
#ifndef HAVE_FCHOWN
rb_secure(2);
o = NIL_P(owner) ? -1 : NUM2INT(owner);
g = NIL_P(group) ? -1 : NUM2INT(group);
GetOpenFile(obj, fptr);
#ifndef HAVE_FCHOWN
if (NIL_P(fptr-&pathv)) return Q
path = rb_str_encode_ospath(fptr-&pathv);
if (chown(RSTRING_PTR(path), o, g) == -1)
rb_sys_fail_path(fptr-&pathv);
if (fchown(fptr-&fd, o, g) == -1)
rb_sys_fail_path(fptr-&pathv);
return INT2FIX(0);
Returns the change time for file (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.new(&testfile&).ctime
Locks or unlocks a file according to locking_constant (a logical
or of the values in the table below). Returns false
if File::LOCK_NB is specified and the operation would
otherwise have blocked. Not available on all platforms.
Locking constants (in class ):
| Exclusive lock. Only one process may hold an
| exclusive lock for a given file at a time.
----------+------------------------------------------------
| Don't block when locking. May be combined
| with other lock options using logical or.
----------+------------------------------------------------
| Shared lock. Multiple processes may each hold a
| shared lock for a given file at the same time.
----------+------------------------------------------------
File.open(&counter&, File::RDWR|File::CREAT, 0644) {|f|
f.flock(File::LOCK_EX)
value = f.read.to_i + 1
f.write(&#{value}\n&)
f.truncate(f.pos)
File.open(&counter&, &r&) {|f|
f.flock(File::LOCK_SH)
static VALUE
rb_file_flock(VALUE obj, VALUE operation)
int op[2], op1;
rb_secure(2);
op[1] = op1 = NUM2INT(operation);
GetOpenFile(obj, fptr);
op[0] = fptr-&
if (fptr-&mode & FMODE_WRITABLE) {
rb_io_flush(obj);
while ((int)rb_thread_io_blocking_region(rb_thread_flock, op, fptr-&fd) & 0) {
switch (errno) {
case EAGAIN:
case EACCES:
#if defined(EWOULDBLOCK) && EWOULDBLOCK != EAGAIN
case EWOULDBLOCK:
if (op1 & LOCK_NB) return Q
rb_thread_polling();
rb_io_check_closed(fptr);
case EINTR:
#if defined(ERESTART)
case ERESTART:
rb_sys_fail_path(fptr-&pathv);
return INT2FIX(0);
Same as IO#stat, but does not follow the last symbolic link.
Instead, reports on the link itself.
File.symlink(&testfile&, &link2test&)
File.stat(&testfile&).size
f = File.new(&link2test&)
f.lstat.size
f.stat.size
static VALUE
rb_file_lstat(VALUE obj)
#ifdef HAVE_LSTAT
rb_secure(2);
GetOpenFile(obj, fptr);
if (NIL_P(fptr-&pathv)) return Q
path = rb_str_encode_ospath(fptr-&pathv);
if (lstat(RSTRING_PTR(path), &st) == -1) {
rb_sys_fail_path(fptr-&pathv);
return stat_new(&st);
return rb_io_stat(obj);
Returns the modification time for file.
File.new(&testfile&).mtime
Returns the pathname used to create file as a string. Does not
normalize the name.
File.new(&testfile&).path
File.new(&/tmp/../tmp/xxx&, &w&).path
static VALUE
rb_file_path(VALUE obj)
fptr = RFILE(rb_io_taint_check(obj))-&
rb_io_check_initialized(fptr);
if (NIL_P(fptr-&pathv)) return Q
return rb_obj_taint(rb_str_dup(fptr-&pathv));
Returns the size of file in bytes.
File.new(&testfile&).size
static VALUE
rb_file_size(VALUE obj)
GetOpenFile(obj, fptr);
if (fptr-&mode & FMODE_WRITABLE) {
rb_io_flush(obj);
if (fstat(fptr-&fd, &st) == -1) {
rb_sys_fail_path(fptr-&pathv);
return OFFT2NUM(st.st_size);
Returns the pathname used to create file as a string. Does not
normalize the name.
File.new(&testfile&).path
File.new(&/tmp/../tmp/xxx&, &w&).path
static VALUE
rb_file_path(VALUE obj)
fptr = RFILE(rb_io_taint_check(obj))-&
rb_io_check_initialized(fptr);
if (NIL_P(fptr-&pathv)) return Q
return rb_obj_taint(rb_str_dup(fptr-&pathv));
Truncates file to at most integer bytes. The file must be
opened for writing. Not available on all platforms.
f = File.new(&out&, &w&)
f.syswrite(&&)
f.truncate(5)
File.size(&out&)
static VALUE
rb_file_truncate(VALUE obj, VALUE len)
rb_secure(2);
pos = NUM2OFFT(len);
GetOpenFile(obj, fptr);
if (!(fptr-&mode & FMODE_WRITABLE)) {
rb_raise(rb_eIOError, &not opened for writing&);
rb_io_flush(obj);
#ifdef HAVE_FTRUNCATE
if (ftruncate(fptr-&fd, pos) & 0)
rb_sys_fail_path(fptr-&pathv);
#else /* defined(HAVE_CHSIZE) */
if (chsize(fptr-&fd, pos) & 0)
rb_sys_fail_path(fptr-&pathv);
return INT2FIX(0);
Generated with Ruby-doc Rdoc Generator 0.36.0.