File

        # File < IO

(from ruby core)
---
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](IO.html#class-IO-label-What-27s+Here), in
    particular, methods for creating, reading, and writing files
*   Includes [module
    FileTest](FileTest.html#module-FileTest-label-What-27s+Here). which
    provides dozens of additional methods.


Here, class File provides methods that are useful for:

*   [Creating](#class-File-label-Creating)
*   [Querying](#class-File-label-Querying)
*   [Settings](#class-File-label-Settings)
*   [Other](#class-File-label-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.


---
# Constants:

ALT_SEPARATOR
:   platform specific alternative separator

PATH_SEPARATOR
:   path list separator

SEPARATOR
:   separates directory parts in path

Separator
:   separates directory parts in path



# Class methods:

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

# Instance methods:

    atime
    birthtime
    chmod
    chown
    ctime
    flock
    lstat
    mtime
    path
    size
    to_path
    truncate