Class: File (Ruby 2.3.4)

    In Files

    • dir.c
    • file.c
    • io.c

    Class/Module Index [+]

    Quicksearch

    File

    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

    separates directory parts in path

    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")       #=> "<relative_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")   #=> Wed Apr 09 08:51:48 CDT 2003
    
     
                   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")          #=> "ruby.rb"
    File.basename("/home/gumby/work/ruby.rb", ".rb")   #=> "ruby"
    File.basename("/home/gumby/work/ruby.rb", ".*")    #=> "ruby"
    
     
                   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")   #=> Wed Apr 09 08:53:13 CDT 2003
    

    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")   #=> 2
    
     
                   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")   #=> Wed Apr 09 08:53:13 CDT 2003
    
     
                   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")   #=> "/home/gumby/work"
    
     
                   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")           #=> "/home/oracle/bin"
    

    A simple example of using dir_string is as follows.

    File.expand_path("ruby", "/usr/bin")      #=> "/usr/bin/ruby"
    

    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__)
    #=> ".../path/to/project/lib/mygem.rb"
    

    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")         #=> ".rb"
    File.extname("a/b/d/test.rb")   #=> ".rb"
    File.extname(".a/b/d/test.rb")  #=> ".rb"
    File.extname("foo.")            #=> ""
    File.extname("test")            #=> ""
    File.extname(".profile")        #=> ""
    File.extname(".profile.sh")     #=> ".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')        #=> true  # match entire string
    File.fnmatch('cat',       'category')   #=> false # only match partial string
    
    File.fnmatch('c{at,ub}s', 'cats')                    #=> false # { } isn't supported by default
    File.fnmatch('c{at,ub}s', 'cats', File::FNM_EXTGLOB) #=> true  # { } is supported on FNM_EXTGLOB
    
    File.fnmatch('c?t',     'cat')          #=> true  # '?' match only 1 character
    File.fnmatch('c??t',    'cat')          #=> false # ditto
    File.fnmatch('c*',      'cats')         #=> true  # '*' match 0 or more characters
    File.fnmatch('c*t',     'c/a/b/t')      #=> true  # ditto
    File.fnmatch('ca[a-z]', 'cat')          #=> true  # inclusive bracket expression
    File.fnmatch('ca[^t]',  'cat')          #=> false # exclusive bracket expression ('^' or '!')
    
    File.fnmatch('cat', 'CAT')                     #=> false # case sensitive
    File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD) #=> true  # case insensitive
    
    File.fnmatch('?',   '/', File::FNM_PATHNAME)  #=> false # wildcard doesn't match '/' on FNM_PATHNAME
    File.fnmatch('*',   '/', File::FNM_PATHNAME)  #=> false # ditto
    File.fnmatch('[/]', '/', File::FNM_PATHNAME)  #=> false # ditto
    
    File.fnmatch('\?',   '?')                       #=> true  # escaped wildcard becomes ordinary
    File.fnmatch('\a',   'a')                       #=> true  # escaped ordinary remains ordinary
    File.fnmatch('\a',   '\a', File::FNM_NOESCAPE)  #=> true  # FNM_NOESCAPE makes '\' ordinary
    File.fnmatch('[\?]', '?')                       #=> true  # can escape inside bracket expression
    
    File.fnmatch('*',   '.profile')                      #=> false # wildcard doesn't match leading
    File.fnmatch('*',   '.profile', File::FNM_DOTMATCH)  #=> true  # period by default.
    File.fnmatch('.*',  '.profile')                      #=> true
    
    rbfiles = '**' '/' '*.rb' # you don't have to do like this. just write in single string.
    File.fnmatch(rbfiles, 'main.rb')                    #=> false
    File.fnmatch(rbfiles, './main.rb')                  #=> false
    File.fnmatch(rbfiles, 'lib/song.rb')                #=> true
    File.fnmatch('**.rb', 'main.rb')                    #=> true
    File.fnmatch('**.rb', './main.rb')                  #=> false
    File.fnmatch('**.rb', 'lib/song.rb')                #=> true
    File.fnmatch('*',           'dave/.profile')                      #=> true
    
    pattern = '*' '/' '*'
    File.fnmatch(pattern, 'dave/.profile', File::FNM_PATHNAME)  #=> false
    File.fnmatch(pattern, 'dave/.profile', File::FNM_PATHNAME | File::FNM_DOTMATCH) #=> true
    
    pattern = '**' '/' 'foo'
    File.fnmatch(pattern, 'a/b/c/foo', File::FNM_PATHNAME)     #=> true
    File.fnmatch(pattern, '/a/b/c/foo', File::FNM_PATHNAME)    #=> true
    File.fnmatch(pattern, 'c:/a/b/c/foo', File::FNM_PATHNAME)  #=> true
    File.fnmatch(pattern, 'a/.b/c/foo', File::FNM_PATHNAME)    #=> false
    File.fnmatch(pattern, 'a/.b/c/foo', File::FNM_PATHNAME | File::FNM_DOTMATCH) #=> true
    
     
                   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

    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')        #=> true  # match entire string
    File.fnmatch('cat',       'category')   #=> false # only match partial string
    
    File.fnmatch('c{at,ub}s', 'cats')                    #=> false # { } isn't supported by default
    File.fnmatch('c{at,ub}s', 'cats', File::FNM_EXTGLOB) #=> true  # { } is supported on FNM_EXTGLOB
    
    File.fnmatch('c?t',     'cat')          #=> true  # '?' match only 1 character
    File.fnmatch('c??t',    'cat')          #=> false # ditto
    File.fnmatch('c*',      'cats')         #=> true  # '*' match 0 or more characters
    File.fnmatch('c*t',     'c/a/b/t')      #=> true  # ditto
    File.fnmatch('ca[a-z]', 'cat')          #=> true  # inclusive bracket expression
    File.fnmatch('ca[^t]',  'cat')          #=> false # exclusive bracket expression ('^' or '!')
    
    File.fnmatch('cat', 'CAT')                     #=> false # case sensitive
    File.fnmatch('cat', 'CAT', File::FNM_CASEFOLD) #=> true  # case insensitive
    
    File.fnmatch('?',   '/', File::FNM_PATHNAME)  #=> false # wildcard doesn't match '/' on FNM_PATHNAME
    File.fnmatch('*',   '/', File::FNM_PATHNAME)  #=> false # ditto
    File.fnmatch('[/]', '/', File::FNM_PATHNAME)  #=> false # ditto
    
    File.fnmatch('\?',   '?')                       #=> true  # escaped wildcard becomes ordinary
    File.fnmatch('\a',   'a')                       #=> true  # escaped ordinary remains ordinary
    File.fnmatch('\a',   '\a', File::FNM_NOESCAPE)  #=> true  # FNM_NOESCAPE makes '\' ordinary
    File.fnmatch('[\?]', '?')                       #=> true  # can escape inside bracket expression
    
    File.fnmatch('*',   '.profile')                      #=> false # wildcard doesn't match leading
    File.fnmatch('*',   '.profile', File::FNM_DOTMATCH)  #=> true  # period by default.
    File.fnmatch('.*',  '.profile')                      #=> true
    
    rbfiles = '**' '/' '*.rb' # you don't have to do like this. just write in single string.
    File.fnmatch(rbfiles, 'main.rb')                    #=> false
    File.fnmatch(rbfiles, './main.rb')                  #=> false
    File.fnmatch(rbfiles, 'lib/song.rb')                #=> true
    File.fnmatch('**.rb', 'main.rb')                    #=> true
    File.fnmatch('**.rb', './main.rb')                  #=> false
    File.fnmatch('**.rb', 'lib/song.rb')                #=> true
    File.fnmatch('*',           'dave/.profile')                      #=> true
    
    pattern = '*' '/' '*'
    File.fnmatch(pattern, 'dave/.profile', File::FNM_PATHNAME)  #=> false
    File.fnmatch(pattern, 'dave/.profile', File::FNM_PATHNAME | File::FNM_DOTMATCH) #=> true
    
    pattern = '**' '/' 'foo'
    File.fnmatch(pattern, 'a/b/c/foo', File::FNM_PATHNAME)     #=> true
    File.fnmatch(pattern, '/a/b/c/foo', File::FNM_PATHNAME)    #=> true
    File.fnmatch(pattern, 'c:/a/b/c/foo', File::FNM_PATHNAME)  #=> true
    File.fnmatch(pattern, 'a/.b/c/foo', File::FNM_PATHNAME)    #=> false
    File.fnmatch(pattern, 'a/.b/c/foo', File::FNM_PATHNAME | File::FNM_DOTMATCH) #=> true
    
     
                   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;
    }
                
    ftype(file_name) → string click to toggle source

    Identifies the type of the named file; the return string is one of “file”, “directory”, “characterSpecial”, “blockSpecial”, “fifo”, “link”, “socket”, or “unknown”.

    File.ftype("testfile")            #=> "file"
    File.ftype("/dev/tty")            #=> "characterSpecial"
    File.ftype("/tmp/.X11-unix/X0")   #=> "socket"
    
     
                   static VALUE
    rb_file_s_ftype(VALUE klass, VALUE fname)
    {
        struct stat st;
    
        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (lstat(StringValueCStr(fname), &st) == -1) {
            rb_sys_fail_path(fname);
        }
    
        return rb_file_ftype(&st);
    }
                
    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
        BY_HANDLE_FILE_INFORMATION st1, st2;
        HANDLE f1 = 0, f2 = 0;
    
        f1 = w32_io_info(&fname1, &st1);
        if (f1 == INVALID_HANDLE_VALUE) return Qfalse;
        if (f1) {
            struct w32_io_info_args arg;
            arg.fname = &fname2;
            arg.st = &st2;
            f2 = (HANDLE)rb_ensure(call_w32_io_info, (VALUE)&arg, close_handle, (VALUE)f1);
        }
        else {
            f2 = w32_io_info(&fname2, &st2);
        }
        if (f2 == INVALID_HANDLE_VALUE) return Qfalse;
        if (f2) CloseHandle(f2);
    
        if (st1.dwVolumeSerialNumber == st2.dwVolumeSerialNumber &&
            st1.nFileIndexHigh == st2.nFileIndexHigh &&
            st1.nFileIndexLow == st2.nFileIndexLow)
            return Qtrue;
        return Qfalse;
    #endif
    }
                
    join(string, ...) → string click to toggle source

    Returns a new string formed by joining the strings using File::SEPARATOR.

    File.join("usr", "mail", "gumby")   #=> "usr/mail/gumby"
    
     
                   static VALUE
    rb_file_s_join(VALUE klass, VALUE args)
    {
        return rb_file_join(args, separator);
    }
                
    lchmod(mode_int, file_name, ...) → integer click to toggle source

    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)
    {
        VALUE vmode;
        VALUE rest;
        long mode, n;
    
        rb_scan_args(argc, argv, "1*", &vmode, &rest);
        mode = NUM2INT(vmode);
    
        n = apply2files(lchmod_internal, rest, (void *)(long)mode);
        return LONG2FIX(n);
    }
                
    lchown(owner_int, group_int, file_name,..) → integer click to toggle source

    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, 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(lchown_internal, rest, &arg);
        return LONG2FIX(n);
    }
                
    lstat(file_name) → stat click to toggle source

    Same as File::stat, but does not follow the last symbolic link. Instead, reports on the link itself.

    File.symlink("testfile", "link2test")   #=> 0
    File.stat("testfile").size              #=> 66
    File.lstat("link2test").size            #=> 8
    File.stat("link2test").size             #=> 66
    
     
                   static VALUE
    rb_file_s_lstat(VALUE klass, VALUE fname)
    {
    #ifdef HAVE_LSTAT
        struct stat st;
    
        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (lstat(StringValueCStr(fname), &st) == -1) {
            rb_sys_fail_path(fname);
        }
        return rb_stat_new(&st);
    #else
        return rb_file_s_stat(klass, fname);
    #endif
    }
                
    mkfifo(*args) click to toggle source
     
                   static VALUE
    rb_file_s_mkfifo(int argc, VALUE *argv)
    {
        VALUE path;
        int mode = 0666;
    
        rb_check_arity(argc, 1, 2);
        if (argc > 1) {
            mode = NUM2INT(argv[1]);
        }
        path = argv[0];
        FilePathValue(path);
        path = rb_str_encode_ospath(path);
        if (mkfifo(RSTRING_PTR(path), mode)) {
            rb_sys_fail_path(path);
        }
        return INT2FIX(0);
    }
                
    mtime(file_name) → time click to toggle source

    Returns the modification time for the named file as a Time object.

    file_name can be an IO object.

    File.mtime("testfile")   #=> Tue Apr 08 12:58:04 CDT 2003
    
     
                   static VALUE
    rb_file_s_mtime(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_mtime(&st);
    }
                
    new(filename, mode="r" [, opt]) → file click to toggle source
    new(filename [, mode [, perm]] [, opt]) → file

    Opens the file named by filename according to the given mode and returns a new File object.

    See IO.new for a description of mode and opt.

    If a file is being created, permission bits may be given in perm. These mode and permission bits are platform dependent; on Unix systems, see open(2) and chmod(2) man pages for details.

    Examples

    f = File.new("testfile", "r")
    f = File.new("newfile",  "w+")
    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)) {
                argv[0] = fd;
                return rb_io_initialize(argc, argv, io);
            }
        }
        rb_open_file(argc, argv, io);
    
        return io;
    }
                
    open(filename, mode="r" [, opt]) → file click to toggle source
    open(filename [, mode [, perm]] [, opt]) → file
    open(filename, mode="r" [, opt]) {|file| block } → obj
    open(filename [, mode [, perm]] [, opt]) {|file| block } → obj

    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 the File object will automatically be closed when the block terminates. The value of the block will be returned from File.open.

    If a file is being created, its initial permissions may be set using the perm parameter. See ::new for further discussion.

    See IO.new for a description of the mode and opt parameters.

     
                   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);
        }
    
        return io;
    }
                
    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;
        if (st.st_uid == geteuid()) return Qtrue;
        return Qfalse;
    }
                
    path(path) → string click to toggle source

    Returns the string representation of the path

    File.path("/dev/null")          #=> "/dev/null"
    File.path(Pathname.new("/tmp")) #=> "/tmp"
    
     
                   static VALUE
    rb_file_s_path(VALUE klass, VALUE fname)
    {
        return rb_get_path(fname);
    }
                
    pipe?(file_name) → true or false click to toggle source

    Returns true if the named file is a pipe.

    file_name can be an IO object.

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

     
                   static VALUE
    rb_file_readable_p(VALUE obj, VALUE fname)
    {
        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (eaccess(StringValueCStr(fname), R_OK) < 0) return Qfalse;
        return Qtrue;
    }
                
    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).

     
                   static VALUE
    rb_file_readable_real_p(VALUE obj, VALUE fname)
    {
        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (access(StringValueCStr(fname), R_OK) < 0) return Qfalse;
        return Qtrue;
    }
                
    realdirpath(pathname [, dir_string]) → real_pathname click to toggle source

    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, basedir;
        rb_scan_args(argc, argv, "11", &path, &basedir);
        return rb_realpath_internal(basedir, path, 0);
    }
                
    realpath(pathname [, dir_string]) → real_pathname click to toggle source

    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, basedir;
        rb_scan_args(argc, argv, "11", &path, &basedir);
        return rb_realpath_internal(basedir, path, 1);
    }
                
    rename(old_name, new_name) → 0 click to toggle source

    Renames the given file to the new name. Raises a SystemCallError if the file cannot be renamed.

    File.rename("afile", "afile.bak")   #=> 0
    
     
                   static VALUE
    rb_file_s_rename(VALUE klass, VALUE from, VALUE to)
    {
        const char *src, *dst;
        VALUE f, t;
    
        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;
    #endif
        if (rename(src, dst) < 0) {
            int e = errno;
    #if defined DOSISH
            switch (e) {
              case EEXIST:
                if (chmod(dst, 0666) == 0 &&
                    unlink(dst) == 0 &&
                    rename(src, dst) == 0)
                    return INT2FIX(0);
            }
    #endif
            syserr_fail2(e, from, to);
        }
    
        return INT2FIX(0);
    }
                
    setgid?(file_name) → true or false click to toggle source

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

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

    Returns true if the named file is a socket.

    file_name can be an IO object.

     
                   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;
    }
                
    split(file_name) → array click to toggle source

    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")   #=> ["/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));
    }
                
    stat(file_name) → stat click to toggle source

    Returns a File::Stat object for the named file (see File::Stat).

    File.stat("testfile").mtime   #=> Tue Apr 08 12:58:04 CDT 2003
    
     
                   static VALUE
    rb_file_s_stat(VALUE klass, VALUE fname)
    {
        struct stat st;
    
        FilePathValue(fname);
        if (rb_stat(fname, &st) < 0) {
            rb_sys_fail_path(fname);
        }
        return rb_stat_new(&st);
    }
                
    sticky?(file_name) → true or false click to toggle source

    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);
    #else
        return Qnil;
    #endif
    }
                
    truncate(file_name, integer) → 0 click to toggle source

    Truncates the file file_name to be at most integer bytes long. Not available on all platforms.

    f = File.new("out", "w")
    f.write("1234567890")     #=> 10
    f.close                   #=> nil
    File.truncate("out", 5)   #=> 0
    File.size("out")          #=> 5
    
     
                   static VALUE
    rb_file_s_truncate(VALUE klass, VALUE path, VALUE len)
    {
    #ifdef HAVE_TRUNCATE
    #define NUM2POS(n) NUM2OFFT(n)
        off_t pos;
    #else
    #define NUM2POS(n) NUM2LONG(n)
        long pos;
    #endif
    
        pos = NUM2POS(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) */
        {
            int tmpfd;
    
            if ((tmpfd = rb_cloexec_open(StringValueCStr(path), 0, 0)) < 0) {
                rb_sys_fail_path(path);
            }
            rb_update_max_fd(tmpfd);
            if (chsize(tmpfd, pos) < 0) {
                int e = errno;
                close(tmpfd);
                rb_syserr_fail_path(e, path);
            }
            close(tmpfd);
        }
    #endif
        return INT2FIX(0);
    #undef NUM2POS
    }
                
    umask() → integer click to toggle source
    umask(integer) → integer

    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)   #=> 18
    File.umask         #=> 6
    
     
                   static VALUE
    rb_file_s_umask(int argc, VALUE *argv)
    {
        int omask = 0;
    
        if (argc == 0) {
            omask = umask(0);
            umask(omask);
        }
        else if (argc == 1) {
            omask = umask(NUM2INT(argv[0]));
        }
        else {
            rb_check_arity(argc, 0, 1);
        }
        return INT2FIX(omask);
    }
                
    utime(atime, mtime, file_name,...) → integer click to toggle source

    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.

     
                   static VALUE
    rb_file_s_utime(int argc, VALUE *argv)
    {
        VALUE rest;
        struct utime_args args;
        struct timespec tss[2], *tsp = NULL;
        long n;
    
        rb_scan_args(argc, argv, "2*", &args.atime, &args.mtime, &rest);
    
        if (!NIL_P(args.atime) || !NIL_P(args.mtime)) {
            tsp = tss;
            tsp[0] = rb_time_timespec(args.atime);
            if (args.atime == args.mtime)
                tsp[1] = tsp[0];
            else
                tsp[1] = rb_time_timespec(args.mtime);
        }
        args.tsp = tsp;
    
        n = apply2files(utime_internal, rest, &args);
        return LONG2FIX(n);
    }
                
    world_readable?(file_name) → fixnum 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) → fixnum 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).

     
                   static VALUE
    rb_file_writable_p(VALUE obj, VALUE fname)
    {
        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (eaccess(StringValueCStr(fname), W_OK) < 0) return Qfalse;
        return Qtrue;
    }
                
    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)

     
                   static VALUE
    rb_file_writable_real_p(VALUE obj, VALUE fname)
    {
        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (access(StringValueCStr(fname), W_OK) < 0) return Qfalse;
        return Qtrue;
    }
                
    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;
        if (st.st_size == 0) return Qtrue;
        return Qfalse;
    }
                

    Public Instance Methods

    atime → time click to toggle source

    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
     
                   static VALUE
    rb_file_atime(VALUE obj)
    {
        rb_io_t *fptr;
        struct stat st;
    
        GetOpenFile(obj, fptr);
        if (fstat(fptr->fd, &st) == -1) {
            rb_sys_fail_path(fptr->pathv);
        }
        return stat_atime(&st);
    }
                
    birthtime → time click to toggle source

    Returns the birth time for file.

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

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

     
                   static VALUE
    rb_file_birthtime(VALUE obj)
    {
        rb_io_t *fptr;
        struct stat st;
    
        GetOpenFile(obj, fptr);
        if (fstat(fptr->fd, &st) == -1) {
            rb_sys_fail_path(fptr->pathv);
        }
        return stat_birthtime(&st);
    }
                
    chmod(mode_int) → 0 click to toggle source

    Changes permission bits on file to the bit pattern represented by mode_int. Actual effects are platform dependent; on Unix systems, see chmod(2) for details. Follows symbolic links. Also see File#lchmod.

    f = File.new("out", "w");
    f.chmod(0644)   #=> 0
    
     
                   static VALUE
    rb_file_chmod(VALUE obj, VALUE vmode)
    {
        rb_io_t *fptr;
        int mode;
    #if !defined HAVE_FCHMOD || !HAVE_FCHMOD
        VALUE path;
    #endif
    
        mode = NUM2INT(vmode);
    
        GetOpenFile(obj, fptr);
    #ifdef HAVE_FCHMOD
        if (fchmod(fptr->fd, mode) == -1) {
            if (HAVE_FCHMOD || errno != ENOSYS)
                rb_sys_fail_path(fptr->pathv);
        }
        else {
            if (!HAVE_FCHMOD) return INT2FIX(0);
        }
    #endif
    #if !defined HAVE_FCHMOD || !HAVE_FCHMOD
        if (NIL_P(fptr->pathv)) return Qnil;
        path = rb_str_encode_ospath(fptr->pathv);
        if (chmod(RSTRING_PTR(path), mode) == -1)
            rb_sys_fail_path(fptr->pathv);
    #endif
    
        return INT2FIX(0);
    }
                
    chown(owner_int, group_int ) → 0 click to toggle source

    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)
    {
        rb_io_t *fptr;
        rb_uid_t o;
        rb_gid_t g;
    #ifndef HAVE_FCHOWN
        VALUE path;
    #endif
    
        o = to_uid(owner);
        g = to_gid(group);
        GetOpenFile(obj, fptr);
    #ifndef HAVE_FCHOWN
        if (NIL_P(fptr->pathv)) return Qnil;
        path = rb_str_encode_ospath(fptr->pathv);
        if (chown(RSTRING_PTR(path), o, g) == -1)
            rb_sys_fail_path(fptr->pathv);
    #else
        if (fchown(fptr->fd, o, g) == -1)
            rb_sys_fail_path(fptr->pathv);
    #endif
    
        return INT2FIX(0);
    }
                
    ctime → time click to toggle source

    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   #=> Wed Apr 09 08:53:14 CDT 2003
    
     
                   static VALUE
    rb_file_ctime(VALUE obj)
    {
        rb_io_t *fptr;
        struct stat st;
    
        GetOpenFile(obj, fptr);
        if (fstat(fptr->fd, &st) == -1) {
            rb_sys_fail_path(fptr->pathv);
        }
        return stat_ctime(&st);
    }
                
    flock(locking_constant) → 0 or false click to toggle source

    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 File):

    LOCK_EX   | Exclusive lock. Only one process may hold an
              | exclusive lock for a given file at a time.
    ----------+------------------------------------------------
    LOCK_NB   | Don't block when locking. May be combined
              | with other lock options using logical or.
    ----------+------------------------------------------------
    LOCK_SH   | Shared lock. Multiple processes may each hold a
              | shared lock for a given file at the same time.
    ----------+------------------------------------------------
    LOCK_UN   | Unlock.

    Example:

    # update a counter using write lock
    # don't use "w" because it truncates the file before lock.
    File.open("counter", File::RDWR|File::CREAT, 0644) {|f|
      f.flock(File::LOCK_EX)
      value = f.read.to_i + 1
      f.rewind
      f.write("#{value}\n")
      f.flush
      f.truncate(f.pos)
    }
    
    # read the counter using read lock
    File.open("counter", "r") {|f|
      f.flock(File::LOCK_SH)
      p f.read
    }
    
     
                   static VALUE
    rb_file_flock(VALUE obj, VALUE operation)
    {
        rb_io_t *fptr;
        int op[2], op1;
        struct timeval time;
    
        op[1] = op1 = NUM2INT(operation);
        GetOpenFile(obj, fptr);
        op[0] = fptr->fd;
    
        if (fptr->mode & FMODE_WRITABLE) {
            rb_io_flush_raw(obj, 0);
        }
        while ((int)rb_thread_io_blocking_region(rb_thread_flock, op, fptr->fd) < 0) {
            int e = errno;
            switch (e) {
              case EAGAIN:
              case EACCES:
    #if defined(EWOULDBLOCK) && EWOULDBLOCK != EAGAIN
              case EWOULDBLOCK:
    #endif
                if (op1 & LOCK_NB) return Qfalse;
    
                time.tv_sec = 0;
                time.tv_usec = 100 * 1000; /* 0.1 sec */
                rb_thread_wait_for(time);
                rb_io_check_closed(fptr);
                continue;
    
              case EINTR:
    #if defined(ERESTART)
              case ERESTART:
    #endif
                break;
    
              default:
                rb_syserr_fail_path(e, fptr->pathv);
            }
        }
        return INT2FIX(0);
    }
                
    lstat → stat click to toggle source

    Same as IO#stat, but does not follow the last symbolic link. Instead, reports on the link itself.

    File.symlink("testfile", "link2test")   #=> 0
    File.stat("testfile").size              #=> 66
    f = File.new("link2test")
    f.lstat.size                            #=> 8
    f.stat.size                             #=> 66
    
     
                   static VALUE
    rb_file_lstat(VALUE obj)
    {
    #ifdef HAVE_LSTAT
        rb_io_t *fptr;
        struct stat st;
        VALUE path;
    
        GetOpenFile(obj, fptr);
        if (NIL_P(fptr->pathv)) return Qnil;
        path = rb_str_encode_ospath(fptr->pathv);
        if (lstat(RSTRING_PTR(path), &st) == -1) {
            rb_sys_fail_path(fptr->pathv);
        }
        return rb_stat_new(&st);
    #else
        return rb_io_stat(obj);
    #endif
    }
                
    mtime → time click to toggle source

    Returns the modification time for file.

    File.new("testfile").mtime   #=> Wed Apr 09 08:53:14 CDT 2003
    
     
                   static VALUE
    rb_file_mtime(VALUE obj)
    {
        rb_io_t *fptr;
        struct stat st;
    
        GetOpenFile(obj, fptr);
        if (fstat(fptr->fd, &st) == -1) {
            rb_sys_fail_path(fptr->pathv);
        }
        return stat_mtime(&st);
    }
                
    path → filename click to toggle source
    to_path → filename

    Returns the pathname used to create file as a string. Does not normalize the name.

    File.new("testfile").path               #=> "testfile"
    File.new("/tmp/../tmp/xxx", "w").path   #=> "/tmp/../tmp/xxx"
    
     
                   static VALUE
    rb_file_path(VALUE obj)
    {
        rb_io_t *fptr;
    
        fptr = RFILE(rb_io_taint_check(obj))->fptr;
        rb_io_check_initialized(fptr);
        if (NIL_P(fptr->pathv)) return Qnil;
        return rb_obj_taint(rb_str_dup(fptr->pathv));
    }
                
    size → integer click to toggle source

    Returns the size of file in bytes.

    File.new("testfile").size   #=> 66
    
     
                   static VALUE
    rb_file_size(VALUE obj)
    {
        rb_io_t *fptr;
        struct stat st;
    
        GetOpenFile(obj, fptr);
        if (fptr->mode & FMODE_WRITABLE) {
            rb_io_flush_raw(obj, 0);
        }
        if (fstat(fptr->fd, &st) == -1) {
            rb_sys_fail_path(fptr->pathv);
        }
        return OFFT2NUM(st.st_size);
    }
                
    to_path → filename click to toggle source

    Returns the pathname used to create file as a string. Does not normalize the name.

    File.new("testfile").path               #=> "testfile"
    File.new("/tmp/../tmp/xxx", "w").path   #=> "/tmp/../tmp/xxx"
    
     
                   static VALUE
    rb_file_path(VALUE obj)
    {
        rb_io_t *fptr;
    
        fptr = RFILE(rb_io_taint_check(obj))->fptr;
        rb_io_check_initialized(fptr);
        if (NIL_P(fptr->pathv)) return Qnil;
        return rb_obj_taint(rb_str_dup(fptr->pathv));
    }
                
    truncate(integer) → 0 click to toggle source

    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("1234567890")   #=> 10
    f.truncate(5)              #=> 0
    f.close()                  #=> nil
    File.size("out")           #=> 5
    
     
                   static VALUE
    rb_file_truncate(VALUE obj, VALUE len)
    {
        rb_io_t *fptr;
    #if defined(HAVE_FTRUNCATE)
    #define NUM2POS(n) NUM2OFFT(n)
        off_t pos;
    #else
    #define NUM2POS(n) NUM2LONG(n)
        long pos;
    #endif
    
        pos = NUM2POS(len);
        GetOpenFile(obj, fptr);
        if (!(fptr->mode & FMODE_WRITABLE)) {
            rb_raise(rb_eIOError, "not opened for writing");
        }
        rb_io_flush_raw(obj, 0);
    #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);
    #endif
        return INT2FIX(0);
    #undef NUM2POS
    }