class File - Documentation for Ruby 2.3.0 (original) (raw)

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 File 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 execute bit changes; 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.

Various constants for the methods in File can be found in File::Constants.

Constants

ALT_SEPARATOR

platform specific alternative separator

PATH_SEPARATOR

path list separator

SEPARATOR

Separator

separates directory parts in path

Public Class Methods

absolute_path(file_name [, dir_string] ) → abs_file_name click to toggle source

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

VALUE rb_file_s_absolute_path(int argc, const VALUE *argv) { VALUE fname, dname;

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

}

atime(file_name) → time click to toggle source

Returns the last access time for the named file as a Time object).

file_name can be an IO object.

File.atime("testfile")

static VALUE rb_file_s_atime(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 stat_atime(&st);

}

basename(file_name [, suffix] ) → base_name click to toggle source

Returns the last component of the filename given in file_name, which can be formed using both File::SEPARATOR and File::ALT_SEPARATOR as the separator when File::ALT_SEPARATOR is not nil. If suffix is given and present at the end of file_name, it is removed. If suffix is “.*”, any extension will be removed.

File.basename("/home/gumby/work/ruby.rb")
File.basename("/home/gumby/work/ruby.rb", ".rb")
File.basename("/home/gumby/work/ruby.rb", ".*")

static VALUE rb_file_s_basename(int argc, VALUE *argv) { VALUE fname, fext, basename; const char *name, *p; long f, n; rb_encoding *enc;

if (rb_scan_args(argc, argv, "11", &fname, &fext) == 2) {
    StringValue(fext);
    enc = check_path_encoding(fext);
}
FilePathStringValue(fname);
if (NIL_P(fext) || !(enc = rb_enc_compatible(fname, fext))) {
    enc = rb_enc_get(fname);
    fext = Qnil;
}
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)) {
        f = n;
    }
    else {
        const char *fp;
        fp = StringValueCStr(fext);
        if (!(f = rmext(p, f, n, fp, RSTRING_LEN(fext), enc))) {
            f = n;
        }
        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);
return basename;

}

birthtime(file_name) → time click to toggle source

Returns the birth time for the named file.

file_name can be an IO object.

File.birthtime("testfile")

If the platform doesn't have birthtime, raises NotImplementedError.

static VALUE rb_file_s_birthtime(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 stat_birthtime(&st);

}

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

Returns true if the named file is a block device.

file_name can be an IO object.

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?(file_name) → true or false click to toggle source

Returns true if the named file is a character device.

file_name can be an IO object.

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;

}

chmod(mode_int, file_name, ... ) → integer click to toggle source

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) { VALUE vmode; VALUE rest; int mode; long n;

rb_scan_args(argc, argv, "1*", &vmode, &rest);
mode = NUM2INT(vmode);

n = apply2files(chmod_internal, rest, &mode);
return LONG2FIX(n);

}

chown(owner_int, group_int, file_name,... ) → integer click to toggle source

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, rest; struct chown_args arg; long n;

rb_scan_args(argc, argv, "2*", &o, &g, &rest);
arg.owner = to_uid(o);
arg.group = to_gid(g);

n = apply2files(chown_internal, rest, &arg);
return LONG2FIX(n);

}

ctime(file_name) → time click to toggle source

Returns the change time for the named file (the time at which directory information about the file was changed, not the file itself).

file_name can be an IO object.

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

File.ctime("testfile")

static VALUE rb_file_s_ctime(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 stat_ctime(&st);

}

delete(file_name, ...) → integer click to toggle source

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) { long n;

n = apply2files(unlink_internal, args, 0);
return LONG2FIX(n);

}

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

Returns true if the named file is a directory, or a symlink that points at a directory, and false otherwise.

file_name can be an IO object.

File.directory?(".")

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;

}

dirname(file_name) → dir_name click to toggle source

Returns all components of the filename given in file_name except the last one. The filename can be formed using both File::SEPARATOR and File::ALT_SEPARATOR as the separator when File::ALT_SEPARATOR is not nil.

File.dirname("/home/gumby/work/ruby.rb")

static VALUE rb_file_s_dirname(VALUE klass, VALUE fname) { return rb_file_dirname(fname); }

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

static VALUE rb_file_executable_p(VALUE obj, VALUE fname) { FilePathValue(fname); fname = rb_str_encode_ospath(fname); if (eaccess(StringValueCStr(fname), X_OK) < 0) return Qfalse; return Qtrue; }

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

static VALUE rb_file_executable_real_p(VALUE obj, VALUE fname) { FilePathValue(fname); fname = rb_str_encode_ospath(fname); if (access(StringValueCStr(fname), X_OK) < 0) return Qfalse; return Qtrue; }

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;

}

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

Deprecated method. Don't use.

static VALUE rb_file_exists_p(VALUE obj, VALUE fname) { const char *s = "FileTest#"; if (obj == rb_mFileTest) { s = "FileTest."; } else if (obj == rb_cFile || (RB_TYPE_P(obj, T_CLASS) && RTEST(rb_class_inherited_p(obj, rb_cFile)))) { s = "File."; } rb_warning("%sexists? is a deprecated name, use %sexist? instead", s, s); return rb_file_exist_p(obj, fname); }

expand_path(file_name [, dir_string] ) → abs_file_name click to toggle source

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

A simple example of using dir_string is as follows.

File.expand_path("ruby", "/usr/bin")

A more complex example which also resolves parent directory is as follows. Suppose we are in bin/mygem and want the absolute path of lib/mygem.rb.

File.expand_path("../../lib/mygem.rb", FILE)

So first it resolves the parent of __FILE__, that is bin/, then go to the parent, the root of the project and appends lib/mygem.rb.

VALUE rb_file_s_expand_path(int argc, const VALUE *argv) { VALUE fname, dname;

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

}

extname(path) → string click to toggle source

Returns the extension (the portion of file name in path starting from the last period).

If path is a dotfile, or starts with a period, then the starting dot is not dealt with the start of the extension.

An empty string will also be returned when the period is the last character in path.

File.extname("test.rb")
File.extname("a/b/d/test.rb")
File.extname(".a/b/d/test.rb")
File.extname("foo.")
File.extname("test")
File.extname(".profile")
File.extname(".profile.sh")

static VALUE rb_file_s_extname(VALUE klass, VALUE fname) { const char *name, *e; long len; VALUE extname;

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);
return extname;

}

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;
if (S_ISREG(st.st_mode)) return Qtrue;
return Qfalse;

}

fnmatch( pattern, path, [flags] ) → (true or false) click to toggle source

fnmatch?( pattern, path, [flags] ) → (true or false)

Returns true if path matches against pattern. The pattern is not a regular expression; 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. Equivalent to / .* /x in regexp.

*

Matches all files regular files

c*

Matches all files beginning with c

*c

Matches all files ending with c

*c*

Matches all files that have c in them (including at the beginning or end).

To match hidden files (that start with a . set the File::FNM_DOTMATCH flag.

**

Matches directories recursively or files expansively.

?

Matches any one character. Equivalent to /.{1}/ in regexp.

[set]

Matches any one character in set. Behaves exactly like character sets in Regexp, including set negation ([^a-z]).

\

Escapes the next metacharacter.

{a,b}

Matches pattern a and pattern b if File::FNM_EXTGLOB flag is enabled. Behaves like a Regexp union ((?:a|b)).

flags is a bitwise OR of the FNM_XXX constants. The same glob pattern and flags are used by Dir::glob.

Examples:

File.fnmatch('cat', 'cat')
File.fnmatch('cat', 'category')

File.fnmatch('c{at,ub}s', 'cats')
File.fnmatch('c{at,ub}s', 'cats', File::FNM_EXTGLOB)

File.fnmatch('c?t', 'cat')
File.fnmatch('c??t', 'cat')
File.fnmatch('c*', 'cats')
File.fnmatch('c*t', 'c/a/b/t')
File.fnmatch('ca[a-z]', 'cat')
File.fnmatch('ca[^t]', 'cat')

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', '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, path; VALUE rflags; int flags;

if (rb_scan_args(argc, argv, "21", &pattern, &path, &rflags) == 3)
    flags = NUM2INT(rflags);
else
    flags = 0;

StringValue(pattern);
FilePathStringValue(path);

if (flags & FNM_EXTGLOB) {
    struct brace_args args;

    args.value = path;
    args.flags = flags;
    if (ruby_brace_expand(RSTRING_PTR(pattern), flags, fnmatch_brace,
                          (VALUE)&args, rb_enc_get(pattern)) > 0)
        return Qtrue;
}
else {
    rb_encoding *enc = rb_enc_compatible(pattern, path);
    if (!enc) return Qfalse;
    if (fnmatch(RSTRING_PTR(pattern), enc, RSTRING_PTR(path), flags) == 0)
        return Qtrue;
}
RB_GC_GUARD(pattern);

return Qfalse;

}

fnmatch?( pattern, path, [flags] ) → (true or false) click to toggle source