Class File
In: file.c

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.

Methods

atime   atime   basename   blockdev?   chardev?   chmod   chmod   chown   chown   ctime   ctime   delete   directory?   dirname   executable?   executable_real?   exist?   exists?   expand_path   extname   file?   flock   fnmatch   fnmatch?   ftype   grpowned?   identical?   join   lchmod   lchown   link   lstat   lstat   mtime   mtime   new   owned?   path   pipe?   readable?   readable_real?   readlink   rename   setgid?   setuid?   size   size?   socket?   split   stat   sticky?   symlink   symlink?   truncate   truncate   umask   unlink   utime   writable?   writable_real?   zero?  

Classes and Modules

Module File::Constants
Class File::Stat

Constants

Separator = separator
SEPARATOR = separator
ALT_SEPARATOR = rb_obj_freeze(rb_str_new2("\\"))
ALT_SEPARATOR = Qnil
PATH_SEPARATOR = rb_obj_freeze(rb_str_new2(PATH_SEP))

Public Class methods

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

   File.atime("testfile")   #=> Wed Apr 09 08:51:48 CDT 2003

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")          #=> "ruby.rb"
   File.basename("/home/gumby/work/ruby.rb", ".rb")   #=> "ruby"

Returns true if the named file is a block device.

Returns true if the named file is a character device.

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

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

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

   File.ctime("testfile")   #=> Wed Apr 09 08:53:13 CDT 2003

Deletes the named files, returning the number of names passed as arguments. Raises an exception on any error. See also Dir::rmdir.

Returns true if the named file is a directory, false otherwise.

   File.directory?(".")

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

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

Returns true if the named file is executable by the effective user id of this process.

Returns true if the named file is executable by the real user id of this process.

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"
   File.expand_path("../../bin", "/tmp/x")   #=> "/bin"

Returns the extension (the portion of file name in path after the period).

   File.extname("test.rb")         #=> ".rb"
   File.extname("a/b/d/test.rb")   #=> ".rb"
   File.extname("test")            #=> ""
   File.extname(".profile")        #=> ""

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

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. * will match all files; 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 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]).
<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',       'cat')        #=> true
   File.fnmatch('cat',       'category')   #=> false
   File.fnmatch('c{at,ub}s', 'cats')       #=> false
   File.fnmatch('c{at,ub}s', 'cubs')       #=> false
   File.fnmatch('c{at,ub}s', 'cat')        #=> false

   File.fnmatch('c?t',    'cat')                       #=> true
   File.fnmatch('c\?t',   'cat')                       #=> false
   File.fnmatch('c??t',   'cat')                       #=> false
   File.fnmatch('c*',     'cats')                      #=> true
   File.fnmatch('c/ * FIXME * /t', 'c/a/b/c/t')                 #=> true
   File.fnmatch('c*t',    'cat')                       #=> true
   File.fnmatch('c\at',   'cat')                       #=> true
   File.fnmatch('c\at',   'cat', File::FNM_NOESCAPE)   #=> false
   File.fnmatch('a?b',    'a/b')                       #=> true
   File.fnmatch('a?b',    'a/b', File::FNM_PATHNAME)   #=> false

   File.fnmatch('*',   '.profile')                            #=> false
   File.fnmatch('*',   '.profile', File::FNM_DOTMATCH)        #=> true
   File.fnmatch('*',   'dave/.profile')                       #=> true
   File.fnmatch('*',   'dave/.profile', File::FNM_DOTMATCH)   #=> true
   File.fnmatch('*',   'dave/.profile', File::FNM_PATHNAME)   #=> false
   File.fnmatch('* / FIXME *', 'dave/.profile', File::FNM_PATHNAME)   #=> false
   STRICT = File::FNM_PATHNAME | File::FNM_DOTMATCH
   File.fnmatch('* / FIXME *', 'dave/.profile', STRICT)               #=> true

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. * will match all files; 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 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]).
<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',       'cat')        #=> true
   File.fnmatch('cat',       'category')   #=> false
   File.fnmatch('c{at,ub}s', 'cats')       #=> false
   File.fnmatch('c{at,ub}s', 'cubs')       #=> false
   File.fnmatch('c{at,ub}s', 'cat')        #=> false

   File.fnmatch('c?t',    'cat')                       #=> true
   File.fnmatch('c\?t',   'cat')                       #=> false
   File.fnmatch('c??t',   'cat')                       #=> false
   File.fnmatch('c*',     'cats')                      #=> true
   File.fnmatch('c/ * FIXME * /t', 'c/a/b/c/t')                 #=> true
   File.fnmatch('c*t',    'cat')                       #=> true
   File.fnmatch('c\at',   'cat')                       #=> true
   File.fnmatch('c\at',   'cat', File::FNM_NOESCAPE)   #=> false
   File.fnmatch('a?b',    'a/b')                       #=> true
   File.fnmatch('a?b',    'a/b', File::FNM_PATHNAME)   #=> false

   File.fnmatch('*',   '.profile')                            #=> false
   File.fnmatch('*',   '.profile', File::FNM_DOTMATCH)        #=> true
   File.fnmatch('*',   'dave/.profile')                       #=> true
   File.fnmatch('*',   'dave/.profile', File::FNM_DOTMATCH)   #=> true
   File.fnmatch('*',   'dave/.profile', File::FNM_PATHNAME)   #=> false
   File.fnmatch('* / FIXME *', 'dave/.profile', File::FNM_PATHNAME)   #=> false
   STRICT = File::FNM_PATHNAME | File::FNM_DOTMATCH
   File.fnmatch('* / FIXME *', 'dave/.profile', STRICT)               #=> true

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"

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.

Returns true if the named files are identical.

    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

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

   File.join("usr", "mail", "gumby")   #=> "usr/mail/gumby"

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.

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.

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")   #=> 0
   IO.readlines(".testfile")[0]         #=> "This is line one\n"

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

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

   File.mtime("testfile")   #=> Tue Apr 08 12:58:04 CDT 2003

Opens the file named by filename according to mode (default is ``r’’) and returns a new File object. See the description of class IO for a description of mode. 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 are platform dependent; on Unix systems, see open(2) for details.

   f = File.new("testfile", "r")
   f = File.new("newfile",  "w+")
   f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644)

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

Returns true if the named file is a pipe.

Returns true if the named file is readable by the effective user id of this process.

Returns true if the named file is readable by the real user id of this process.

Returns the name of the file referenced by the given link. Not available on all platforms.

   File.symlink("testfile", "link2test")   #=> 0
   File.readlink("link2test")              #=> "testfile"

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

   File.rename("afile", "afile.bak")   #=> 0

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

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

Returns the size of file_name.

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

Returns true if the named file is a socket.

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

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

   File.stat("testfile").mtime   #=> Tue Apr 08 12:58:04 CDT 2003

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

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")   #=> 0

Returns true if the named file is a symbolic link.

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

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

Deletes the named files, returning the number of names passed as arguments. Raises an exception on any error. See also Dir::rmdir.

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.

Returns true if the named file is writable by the effective user id of this process.

Returns true if the named file is writable by the real user id of this process.

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

Public Instance methods

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

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)

Returns the change time for file (that is, the time directory information about the file was changed, not the file itself).

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

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:

   File.new("testfile").flock(File::LOCK_UN)   #=> 0

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

Returns the modification time for file.

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

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"

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
To view or add comments on this documentation, please go to the API wiki.

[Validate]