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.

What’s Here

First, what’s elsewhere. Class File:

• Inherits from class IO, in particular, methods for creating, reading, and writing files

• Includes module FileTest. which provides dozens of additional methods.

Here, class File provides methods that are useful for:

• Creating

• Querying

• Settings

• Other

Creating

• ::new

  Opens the file at the given path; returns the file.

• ::open

  Same as ::new, but when given a block will yield the file to the block, and close the file upon exiting the block.

• ::link

  Creates a new name for an existing file using a hard link.

• ::mkfifo

  Returns the FIFO file created at the given path.

• ::symlink

  Creates a symbolic link for the given file path.

Querying

Paths

• ::absolute_path

  Returns the absolute file path for the given path.

• ::absolute_path?

  Returns whether the given path is the absolute file path.

• ::basename

  Returns the last component of the given file path.

• ::dirname

  Returns all but the last component of the given file path.

• ::expand_path

  Returns the absolute file path for the given path, expanding ~ for a home directory.

• ::extname

  Returns the file extension for the given file path.

• ::fnmatch? (aliased as ::fnmatch)

  Returns whether the given file path matches the given pattern.

• ::join

  Joins path components into a single path string.

• ::path

  Returns the string representation of the given path.

• ::readlink

  Returns the path to the file at the given symbolic link.

• ::realdirpath

  Returns the real path for the given file path, where the last component need not exist.

• ::realpath

  Returns the real path for the given file path, where all components must exist.

• ::split

  Returns an array of two strings: the directory name and basename of the file at the given path.

• path (aliased as to_path)

  Returns the string representation of the given path.

Times

• ::atime

  Returns a Time for the most recent access to the given file.

• ::birthtime

  Returns a Time for the creation of the given file.

• ::ctime

  Returns a Time for the metadata change of the given file.

• ::mtime

  Returns a Time for the most recent data modification to the content of the given file.

• atime

  Returns a Time for the most recent access to self.

• birthtime

  Returns a Time the creation for self.

• ctime

  Returns a Time for the metadata change of self.

• mtime

  Returns a Time for the most recent data modification to the content of self.

Types

• ::blockdev?

  Returns whether the file at the given path is a block device.

• ::chardev?

  Returns whether the file at the given path is a character device.

• ::directory?

  Returns whether the file at the given path is a diretory.

• ::executable?

  Returns whether the file at the given path is executable by the effective user and group of the current process.

• ::executable_real?

  Returns whether the file at the given path is executable by the real user and group of the current process.

• ::exist?

  Returns whether the file at the given path exists.

• ::file?

  Returns whether the file at the given path is a regular file.

• ::ftype

  Returns a string giving the type of the file at the given path.

• ::grpowned?

  Returns whether the effective group of the current process owns the file at the given path.

• ::identical?

  Returns whether the files at two given paths are identical.

• ::lstat

  Returns the File::Stat object for the last symbolic link in the given path.

• ::owned?

  Returns whether the effective user of the current process owns the file at the given path.

• ::pipe?

  Returns whether the file at the given path is a pipe.

• ::readable?

  Returns whether the file at the given path is readable by the effective user and group of the current process.

• ::readable_real?

  Returns whether the file at the given path is readable by the real user and group of the current process.

• ::setgid?

  Returns whether the setgid bit is set for the file at the given path.

• ::setuid?

  Returns whether the setuid bit is set for the file at the given path.

• ::socket?

  Returns whether the file at the given path is a socket.

• ::stat

  Returns the File::Stat object for the file at the given path.

• ::sticky?

  Returns whether the file at the given path has its sticky bit set.

• ::symlink?

  Returns whether the file at the given path is a symbolic link.

• ::umask

  Returns the umask value for the current process.

• ::world_readable?

  Returns whether the file at the given path is readable by others.

• ::world_writable?

  Returns whether the file at the given path is writable by others.

• ::writable?

  Returns whether the file at the given path is writable by the effective user and group of the current process.

• ::writable_real?

  Returns whether the file at the given path is writable by the real user and group of the current process.

• lstat

  Returns the File::Stat object for the last symbolic link in the path for self.

Contents

• ::empty? (aliased as ::zero?)

  Returns whether the file at the given path exists and is empty.

• ::size

  Returns the size (bytes) of the file at the given path.

• ::size?

  Returns nil if there is no file at the given path, or if that file is empty; otherwise returns the file size (bytes).

• size

  Returns the size (bytes) of self.

Settings

• ::chmod

  Changes permissions of the file at the given path.

• ::chown

  Change ownership of the file at the given path.

• ::lchmod

  Changes permissions of the last symbolic link in the given path.

• ::lchown

  Change ownership of the last symbolic in the given path.

• ::lutime

  For each given file path, sets the access time and modification time of the last symbolic link in the path.

• ::rename

  Moves the file at one given path to another given path.

• ::utime

  Sets the access time and modification time of each file at the given paths.

• flock

  Locks or unlocks self.

Other

• ::truncate

  Truncates the file at the given file path to the given size.

• ::unlink (aliased as ::delete)

  Deletes the file for each given file path.

• truncate

  Truncates self to the given size.