File

A File object is a representation of a file in the underlying platform.

Class File extends module FileTest, supporting such singleton methods as File.exist?.

About the Examples

Many examples here use these variables:

# English text with newlines.
text = <<~EOT
  First line
  Second line

  Fourth line
  Fifth line
EOT

# Japanese text.
japanese = 'こんにちは'

# Binary data.
data = "\u9990\u9991\u9992\u9993\u9994"

# Text file.
File.write('t.txt', text)

# File with Japanese text.
File.write('t.ja', japanese)

# File with binary data.
f = File.new('t.dat', 'wb:UTF-16')
f.write(data)
f.close

Access Modes

Methods File.new and File.open each create a File object for a given file path.

String Access Modes

Methods File.new and File.open each may take string argument mode, which:

• Begins with a 1- or 2-character read/write mode.

• May also contain a 1-character data mode.

• May also contain a 1-character file-create mode.

Read/Write Mode

The read/write mode determines:

• Whether the file is to be initially truncated.

• Whether reading is allowed, and if so:

  • The initial read position in the file.

  • Where in the file reading can occur.

• Whether writing is allowed, and if so:

  • The initial write position in the file.

  • Where in the file writing can occur.

These tables summarize:

Read/Write Modes for Existing File

|------|-----------|----------|----------|----------|-----------|
| R/W  | Initial   |          | Initial  |          | Initial   |
| Mode | Truncate? |  Read    | Read Pos |  Write   | Write Pos |
|------|-----------|----------|----------|----------|-----------|
| 'r'  |    No     | Anywhere |    0     |   Error  |     -     |
| 'w'  |    Yes    |   Error  |    -     | Anywhere |     0     |
| 'a'  |    No     |   Error  |    -     | End only |    End    |
| 'r+' |    No     | Anywhere |    0     | Anywhere |     0     |
| 'w+' |    Yes    | Anywhere |    0     | Anywhere |     0     |
| 'a+' |    No     | Anywhere |   End    | End only |    End    |
|------|-----------|----------|----------|----------|-----------|

Read/Write Modes for \File To Be Created

|------|----------|----------|----------|-----------|
| R/W  |          | Initial  |          | Initial   |
| Mode |  Read    | Read Pos |  Write   | Write Pos |
|------|----------|----------|----------|-----------|
| 'w'  |   Error  |    -     | Anywhere |     0     |
| 'a'  |   Error  |    -     | End only |     0     |
| 'w+' | Anywhere |    0     | Anywhere |     0     |
| 'a+' | Anywhere |    0     | End only |    End    |
|------|----------|----------|----------|-----------|

Note that modes 'r' and 'r+' are not allowed for a non-existent file (exception raised).

In the tables:

• Anywhere means that methods IO#rewind, IO#pos=, and IO#seek may be used to change the file’s position, so that allowed reading or writing may occur anywhere in the file.

• End only means that writing can occur only at end-of-file, and that methods IO#rewind, IO#pos=, and IO#seek do not affect writing.

• Error means that an exception is raised if disallowed reading or writing is attempted.

Read/Write Modes for Existing File

• 'r':

  • File is not initially truncated:

    Example

    Run in Playground

    f = File.new('t.txt') # => #<File:t.txt>
    f.size == 0           # => false
    

  • File’s initial read position is 0:

    Example

    Run in Playground

    f.pos # => 0
    

  • File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:

    Example

    Run in Playground

    f.readline # => "First line\n"
    f.readline # => "Second line\n"
    
    f.rewind
    f.readline # => "First line\n"
    
    f.pos = 1
    f.readline # => "irst line\n"
    
    f.seek(1, :CUR)
    f.readline # => "econd line\n"
    

  • Writing is not allowed:

    Example

    Run in Playground

    f.write('foo') # Raises IOError.
    

• 'w':

  • File is initially truncated:

    Example

    Run in Playground

    path = 't.tmp'
    File.write(path, text)
    f = File.new(path, 'w')
    f.size == 0 # => true
    

  • File’s initial write position is 0:

    Example

    Run in Playground

    f.pos # => 0
    

  • File may be written anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

    Example

    Run in Playground

    f.write('foo')
    f.flush
    File.read(path) # => "foo"
    f.pos # => 3
    
    f.write('bar')
    f.flush
    File.read(path) # => "foobar"
    f.pos # => 6
    
    f.rewind
    f.write('baz')
    f.flush
    File.read(path) # => "bazbar"
    f.pos # => 3
    
    f.pos = 3
    f.write('foo')
    f.flush
    File.read(path) # => "bazfoo"
    f.pos # => 6
    
    f.seek(-3, :END)
    f.write('bam')
    f.flush
    File.read(path) # => "bazbam"
    f.pos # => 6
    
    f.pos = 8
    f.write('bah')  # Zero padding as needed.
    f.flush
    File.read(path) # => "bazbam\u0000\u0000bah"
    f.pos # => 11
    

  • Reading is not allowed:

    Example

    Run in Playground

    f.read # Raises IOError.
    

• 'a':

  • File is not initially truncated:

    Example

    Run in Playground

    path = 't.tmp'
    File.write(path, 'foo')
    f = File.new(path, 'a')
    f.size == 0 # => false
    

  • File’s initial position is 0 (but is ignored):

    Example

    Run in Playground

    f.pos # => 0
    

  • File may be written only at end-of-file; IO#rewind, IO#pos=, IO#seek do not affect writing:

    Example

    Run in Playground

    f.write('bar')
    f.flush
    File.read(path) # => "foobar"
    f.write('baz')
    f.flush
    File.read(path) # => "foobarbaz"
    
    f.rewind
    f.write('bat')
    f.flush
    File.read(path) # => "foobarbazbat"
    

  • Reading is not allowed:

    Example

    Run in Playground

    f.read # Raises IOError.
    

• 'r+':

  • File is not initially truncated:

    Example

    Run in Playground

    path = 't.tmp'
    File.write(path, text)
    f = File.new(path, 'r+')
    f.size == 0 # => false
    

  • File’s initial read position is 0:

    Example

    Run in Playground

    f.pos # => 0
    

  • File may be read or written anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

    Example

    Run in Playground

    f.readline # => "First line\n"
    f.readline # => "Second line\n"
    
    f.rewind
    f.readline # => "First line\n"
    
    f.pos = 1
    f.readline # => "irst line\n"
    
    f.seek(1, :CUR)
    f.readline # => "econd line\n"
    
    f.rewind
    f.write('WWW')
    f.flush
    File.read(path)
    # => "WWWst line\nSecond line\nFourth line\nFifth line\n"
    
    f.pos = 10
    f.write('XXX')
    f.flush
    File.read(path)
    # => "WWWst lineXXXecond line\nFourth line\nFifth line\n"
    
    f.seek(-6, :END)
    # => 0
    f.write('YYY')
    # => 3
    f.flush
    # => #<File:t.tmp>
    File.read(path)
    # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n"
    
    f.seek(2, :END)
    f.write('ZZZ') # Zero padding as needed.
    f.flush
    File.read(path)
    # => "WWWst lineXXXecond line\nFourth line\nFifth YYYe\n\u0000\u0000ZZZ"
    

• 'a+':

  • File is not initially truncated:

    Example

    Run in Playground

    path = 't.tmp'
    File.write(path, 'foo')
    f = File.new(path, 'a+')
    f.size == 0 # => false
    

  • File’s initial read position is 0:

    Example

    Run in Playground

    f.pos # => 0
    

  • File may be written only at end-of-file; IO#rewind, IO#pos=, IO#seek do not affect writing:

    Example

    Run in Playground

    f.write('bar')
    f.flush
    File.read(path)      # => "foobar"
    f.write('baz')
    f.flush
    File.read(path)      # => "foobarbaz"
    
    f.rewind
    f.write('bat')
    f.flush
    File.read(path) # => "foobarbazbat"
    

  • File may be read anywhere; see IO#rewind, IO#pos=, IO#seek:

    Example

    Run in Playground

    f.rewind
    f.read # => "foobarbazbat"
    
    f.pos = 3
    f.read # => "barbazbat"
    
    f.seek(-3, :END)
    f.read # => "bat"
    

Read/Write Modes for File To Be Created

Note that modes 'r' and 'r+' are not allowed for a non-existent file (exception raised).

• 'w':

  • File’s initial write position is 0:

    Example

    Run in Playground

    path = 't.tmp'
    FileUtils.rm_f(path)
    f = File.new(path, 'w')
    f.pos # => 0
    

  • File may be written anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

    Example

    Run in Playground

    f.write('foo')
    f.flush
    File.read(path) # => "foo"
    f.pos # => 3
    
    f.write('bar')
    f.flush
    File.read(path) # => "foobar"
    f.pos # => 6
    
    f.rewind
    f.write('baz')
    f.flush
    File.read(path) # => "bazbar"
    f.pos # => 3
    
    f.pos = 3
    f.write('foo')
    f.flush
    File.read(path) # => "bazfoo"
    f.pos # => 6
    
    f.seek(-3, :END)
    f.write('bam')
    f.flush
    File.read(path) # => "bazbam"
    f.pos # => 6
    
    f.pos = 8
    f.write('bah')  # Zero padding as needed.
    f.flush
    File.read(path) # => "bazbam\u0000\u0000bah"
    f.pos # => 11
    

  • Reading is not allowed:

    Example

    Run in Playground

    f.read # Raises IOError.
    

• 'a':

  • File’s initial write position is 0:

    Example

    Run in Playground

    path = 't.tmp'
    FileUtils.rm_f(path)
    f = File.new(path, 'a')
    f.pos # => 0
    

  • Writing occurs only at end-of-file:

    Example

    Run in Playground

    f.write('foo')
    f.pos # => 3
    f.write('bar')
    f.pos # => 6
    f.flush
    File.read(path) # => "foobar"
    
    f.rewind
    f.write('baz')
    f.flush
    File.read(path) # => "foobarbaz"
    

  • Reading is not allowed:

    Example

    Run in Playground

    f.read # Raises IOError.
    

• 'w+':

  • File’s initial position is 0:

    Example

    Run in Playground

    path = 't.tmp'
    FileUtils.rm_f(path)
    f = File.new(path, 'w+')
    f.pos # => 0
    

  • File may be written anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

    Example

    Run in Playground

    f.write('foo')
    f.flush
    File.read(path) # => "foo"
    f.pos # => 3
    
    f.write('bar')
    f.flush
    File.read(path) # => "foobar"
    f.pos # => 6
    
    f.rewind
    f.write('baz')
    f.flush
    File.read(path) # => "bazbar"
    f.pos # => 3
    
    f.pos = 3
    f.write('foo')
    f.flush
    File.read(path) # => "bazfoo"
    f.pos # => 6
    
    f.seek(-3, :END)
    f.write('bam')
    f.flush
    File.read(path) # => "bazbam"
    f.pos # => 6
    
    f.pos = 8
    f.write('bah')  # Zero padding as needed.
    f.flush
    File.read(path) # => "bazbam\u0000\u0000bah"
    f.pos # => 11
    

  • File may be read anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

    Example

    Run in Playground

    f.rewind
    # => 0
    f.read
    # => "bazbam\u0000\u0000bah"
    
    f.pos = 3
    # => 3
    f.read
    # => "bam\u0000\u0000bah"
    
    f.seek(-3, :END)
    # => 0
    f.read
    # => "bah"
    

• 'a+':

  • File’s initial write position is 0:

    Example

    Run in Playground

    path = 't.tmp'
    FileUtils.rm_f(path)
    f = File.new(path, 'a+')
    f.pos # => 0
    

  • Writing occurs only at end-of-file:

    Example

    Run in Playground

    f.write('foo')
    f.pos # => 3
    f.write('bar')
    f.pos # => 6
    f.flush
    File.read(path) # => "foobar"
    
    f.rewind
    f.write('baz')
    f.flush
    File.read(path) # => "foobarbaz"
    

  • File may be read anywhere (even past end-of-file); see IO#rewind, IO#pos=, IO#seek:

    Example

    Run in Playground

    f.rewind
    f.read # => "foobarbaz"
    
    f.pos = 3
    f.read # => "barbaz"
    
    f.seek(-3, :END)
    f.read # => "baz"
    
    f.pos = 800
    f.read # => ""
    

Data Mode

To specify whether data is to be treated as text or as binary data, either of the following may be suffixed to any of the string read/write modes above:

• 't': Text data; sets the default external encoding to Encoding::UTF_8; on Windows, enables conversion between EOL and CRLF and enables interpreting 0x1A as an end-of-file marker.

• 'b': Binary data; sets the default external encoding to Encoding::ASCII_8BIT; on Windows, suppresses conversion between EOL and CRLF and disables interpreting 0x1A as an end-of-file marker.

If neither is given, the stream defaults to text data.

Examples:

File.new('t.txt', 'rt')
File.new('t.dat', 'rb')

When the data mode is specified, the read/write mode may not be omitted, and the data mode must precede the file-create mode, if given:

File.new('t.dat', 'b')   # Raises an exception.
File.new('t.dat', 'rxb') # Raises an exception.

File-Create Mode

The following may be suffixed to any writable string mode above:

• 'x': Creates the file if it does not exist; raises an exception if the file exists.

Example:

File.new('t.tmp', 'wx')

When the file-create mode is specified, the read/write mode may not be omitted, and the file-create mode must follow the data mode:

File.new('t.dat', 'x')   # Raises an exception.
File.new('t.dat', 'rxb') # Raises an exception.

Integer Access Modes

When mode is an integer it must be one or more of the following constants, which may be combined by the bitwise OR operator |:

• File::RDONLY: Open for reading only.

• File::WRONLY: Open for writing only.

• File::RDWR: Open for reading and writing.

• File::APPEND: Open for appending only.

Examples:

File.new('t.txt', File::RDONLY)
File.new('t.tmp', File::RDWR | File::CREAT | File::EXCL)

Note: Method IO#set_encoding does not allow the mode to be specified as an integer.

File-Create Mode Specified as an Integer

These constants may also be ORed into the integer mode:

• File::CREAT: Create file if it does not exist.

• File::EXCL: Raise an exception if File::CREAT is given and the file exists.

Data Mode Specified as an Integer

Data mode cannot be specified as an integer. When the stream access mode is given as an integer, the data mode is always text, never binary.

Note that although there is a constant File::BINARY, setting its value in an integer stream mode has no effect; this is because, as documented in File::Constants, the File::BINARY value disables line code conversion, but does not change the external encoding.

Encodings

Any of the string modes above may specify encodings - either external encoding only or both external and internal encodings - by appending one or both encoding names, separated by colons:

f = File.new('t.dat', 'rb')
f.external_encoding # => #<Encoding:ASCII-8BIT>
f.internal_encoding # => nil
f = File.new('t.dat', 'rb:UTF-16')
f.external_encoding # => #<Encoding:UTF-16 (dummy)>
f.internal_encoding # => nil
f = File.new('t.dat', 'rb:UTF-16:UTF-16')
f.external_encoding # => #<Encoding:UTF-16 (dummy)>
f.internal_encoding # => #<Encoding:UTF-16>
f.close

The numerous encoding names are available in array Encoding.name_list:

Encoding.name_list.take(3) # => ["ASCII-8BIT", "UTF-8", "US-ASCII"]

When the external encoding is set, strings read are tagged by that encoding when reading, and strings written are converted to that encoding when writing.

When both external and internal encodings are set, strings read are converted from external to internal encoding, and strings written are converted from internal to external encoding. For further details about transcoding input and output, see Encodings.

If the external encoding is 'BOM|UTF-8', 'BOM|UTF-16LE' or 'BOM|UTF16-BE', Ruby checks for a Unicode BOM in the input document to help determine the encoding. For UTF-16 encodings the file open mode must be binary. If the BOM is found, it is stripped and the external encoding from the BOM is used.

Note that the BOM-style encoding option is case insensitive, so 'bom|utf-8' is also valid.

File Permissions

A File object has permissions, an octal integer representing the permissions of an actual file in the underlying platform.

Note that file permissions are quite different from the mode of a file stream (File object).

In a File object, the permissions are available thus, where method mode, despite its name, returns permissions:

f = File.new('t.txt')
f.lstat.mode.to_s(8) # => "100644"

On a Unix-based operating system, the three low-order octal digits represent the permissions for owner (6), group (4), and world (4). The triplet of bits in each octal digit represent, respectively, read, write, and execute permissions.

Permissions 0644 thus represent read-write access for owner and read-only access for group and world. See man pages open(2) and chmod(2).

For a directory, the meaning of the execute bit changes: when set, the directory can be searched.

Higher-order bits in permissions may indicate the type of file (plain, directory, pipe, socket, etc.) and various other special features.

On non-Posix operating systems, permissions may include only read-only or read-write, in which case, the remaining permission will resemble typical values. On Windows, for instance, the default permissions are 0644; The only change that can be made is to make the file read-only, which is reported as 0444.

For a method that actually creates a file in the underlying platform (as opposed to merely creating a File object), permissions may be specified:

File.new('t.tmp', File::CREAT, 0644)
File.new('t.tmp', File::CREAT, 0444)

Permissions may also be changed:

f = File.new('t.tmp', File::CREAT, 0444)
f.chmod(0644)
f.chmod(0444)

File Constants

Various constants for use in File and IO methods may be found in module File::Constants; an array of their names is returned by File::Constants.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 directory.

• ::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.