class File - Documentation for Ruby 3.4
Description: class File: A \File object is a representation of a file in the underlying platform. Class \File extends module FileTest, supporting such singleton methods as <tt
Keywords: ruby,class,File

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

    # Russian text.
    russian = "\u{442 435 441 442}" # => "тест"

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

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

    # File with Russian text.
    File.write('t.rus', russian)

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

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

  - File’s initial read position is 0:

        f.pos # => 0

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

        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:

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

- `'w'`:

  - File is initially truncated:

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

  - File’s initial write position is 0:

        f.pos # => 0

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

        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:

        f.read # Raises IOError.

- `'a'`:

  - File is not initially truncated:

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

        f.pos # => 0

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

        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:

        f.read # Raises IOError.

- `'r+'`:

  - File is not initially truncated:

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

  - File’s initial read position is 0:

        f.pos # => 0

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

        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:

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

  - File’s initial read position is 0:

        f.pos # => 0

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

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

        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:

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

        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:

        f.read # Raises IOError.

- `'a'`:

  - File’s initial write position is 0:

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

  - Writing occurs only at end-of-file:

        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:

        f.read # Raises IOError.

- `'w+'`:

  - File’s initial position is 0:

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

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

        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:

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

  - Writing occurs only at end-of-file:

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

        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.

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

    static VALUE
    s_absolute_path(int c, const VALUE * v, VALUE _)
    {
        return rb_file_s_absolute_path(c, v);
    }

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"

absolute_path?(file_name) → true or false
Source

    static VALUE
    s_absolute_path_p(VALUE klass, VALUE fname)
    {
        VALUE path = rb_get_path(fname);

        if (!rb_is_absolute_path(RSTRING_PTR(path))) return Qfalse;
        return Qtrue;
    }

Returns `true` if `file_name` is an absolute path, and `false` otherwise.

    File.absolute_path?("c:/foo")     #=> false (on Linux), true (on Windows)

atime(file_name) → time
Source

    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);
    }

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

basename(file_name [, suffix] ) → base_name
Source

    static VALUE
    rb_file_s_basename(int argc, VALUE *argv, VALUE _)
    {
        VALUE fname, fext, basename;
        const char *name, *p;
        long f, n;
        rb_encoding *enc;

        fext = Qnil;
        if (rb_check_arity(argc, 1, 2) == 2) {
            fext = argv[1];
            StringValue(fext);
            enc = check_path_encoding(fext);
        }
        fname = argv[0];
        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);
        return basename;
    }

Returns the last component of the filename given in file_name (after first stripping trailing separators), 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"

birthtime(file_name) → time
Source

    VALUE
    rb_file_s_birthtime(VALUE klass, VALUE fname)
    {
        statx_data st;

        if (rb_statx(fname, &st, STATX_BTIME) < 0) {
            int e = errno;
            FilePathValue(fname);
            rb_syserr_fail_path(e, fname);
        }
        return statx_birthtime(&st, fname);
    }

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

blockdev?(filepath) → true or false
Source

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

Returns `true` if `filepath` points to a block device, `false` otherwise:

    File.blockdev?('/dev/sda1')       # => true
    File.blockdev?(File.new('t.tmp')) # => false

chardev?(filepath) → true or false
Source

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

Returns `true` if `filepath` points to a character device, `false` otherwise.

    File.chardev?($stdin)     # => true
    File.chardev?('t.txt')     # => false

chmod(mode_int, file_name, ... ) → integer
Source

    static VALUE
    rb_file_s_chmod(int argc, VALUE *argv, VALUE _)
    {
        mode_t mode;

        apply2args(1);
        mode = NUM2MODET(*argv++);

        return apply2files(chmod_internal, argc, argv, &mode);
    }

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

chown(owner_int, group_int, file_name, ...) → integer
Source

    static VALUE
    rb_file_s_chown(int argc, VALUE *argv, VALUE _)
    {
        struct chown_args arg;

        apply2args(2);
        arg.owner = to_uid(*argv++);
        arg.group = to_gid(*argv++);

        return apply2files(chown_internal, argc, argv, &arg);
    }

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

ctime(file_name) → time
Source

    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);
    }

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

delete(file_name, ...) → integer
unlink(file_name, ...) → integer
Source

    static VALUE
    rb_file_s_unlink(int argc, VALUE *argv, VALUE klass)
    {
        return apply2files(unlink_internal, argc, argv, 0);
    }

Deletes the named files, returning the number of names passed as arguments. Raises an exception on any error. Since the underlying implementation relies on the `unlink(2)` system call, the type of exception raised depends on its error type (see linux.die.net/man/2/unlink) and has the form of e.g. Errno::ENOENT.

See also `Dir::rmdir`.

directory?(path) → true or false
Source

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

With string `object` given, returns `true` if `path` is a string path leading to a directory, or to a symbolic link to a directory; `false` otherwise:

    File.directory?('.')              # => true
    File.directory?('foo')            # => false
    File.symlink('.', 'dirlink')      # => 0
    File.directory?('dirlink')        # => true
    File.symlink('t,txt', 'filelink') # => 0
    File.directory?('filelink')       # => false

Argument `path` can be an `IO` object.

dirname(file_name, level = 1) → dir_name
Source

    static VALUE
    rb_file_s_dirname(int argc, VALUE *argv, VALUE klass)
    {
        int n = 1;
        if ((argc = rb_check_arity(argc, 1, 2)) > 1) {
            n = NUM2INT(argv[1]);
        }
        return rb_file_dirname_n(argv[0], n);
    }

Returns all components of the filename given in file_name except the last one (after first stripping trailing separators). 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"

If `level` is given, removes the last `level` components, not only one.

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

zero?(file_name) → true or false
Source

    static VALUE
    rb_file_zero_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return RBOOL(st.st_size == 0);
    }

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

file_name can be an `IO` object.

executable?(file_name) → true or false
Source

    static VALUE
    rb_file_executable_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_eaccess(fname, X_OK) >= 0);
    }

Returns `true` if the named file is executable by the effective user and group id of this process. See eaccess(3).

Windows does not support execute permissions separately from read permissions. On Windows, a file is only considered executable if it ends in .bat, .cmd, .com, or .exe.

Note that some OS-level security features may cause this to return true even though the file is not executable by the effective user/group.

executable_real?(file_name) → true or false
Source

    static VALUE
    rb_file_executable_real_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_access(fname, X_OK) >= 0);
    }

Returns `true` if the named file is executable by the real user and group id of this process. See access(3).

Windows does not support execute permissions separately from read permissions. On Windows, a file is only considered executable if it ends in .bat, .cmd, .com, or .exe.

Note that some OS-level security features may cause this to return true even though the file is not executable by the real user/group.

exist?(file_name) → true or false
Source

    static VALUE
    rb_file_exist_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return Qtrue;
    }

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.

expand_path(file_name [, dir_string] ) → abs_file_name
Source

    static VALUE
    s_expand_path(int c, const VALUE * v, VALUE _)
    {
        return rb_file_s_expand_path(c, v);
    }

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

extname(path) → string
Source

    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! */
        return extname;
    }

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

On Windows, trailing dots are truncated.

    File.extname("test.rb")         #=> ".rb"
    File.extname("a/b/d/test.rb")   #=> ".rb"
    File.extname(".a/b/d/test.rb")  #=> ".rb"
    File.extname("foo.")            #=> "" on Windows
    File.extname("foo.")            #=> "." on non-Windows
    File.extname("test")            #=> ""
    File.extname(".profile")        #=> ""
    File.extname(".profile.sh")     #=> ".sh"

file?(file) → true or false
Source

    static VALUE
    rb_file_file_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return RBOOL(S_ISREG(st.st_mode));
    }

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.

fnmatch( pattern, path, [flags] ) → (true or false)
Source

    # File dir.rb, line 503
    def fnmatch(pattern, path, flags = 0)
    end

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 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('cat', 'CAT', File::FNM_SYSCASE)  #=> true or false # depends on the system default

    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

    File.fnmatch('**/*.rb', 'main.rb')                  #=> false
    File.fnmatch('**/*.rb', './main.rb')                #=> false
    File.fnmatch('**/*.rb', '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

    File.fnmatch('**/foo', 'a/b/c/foo', File::FNM_PATHNAME)     #=> true
    File.fnmatch('**/foo', '/a/b/c/foo', File::FNM_PATHNAME)    #=> true
    File.fnmatch('**/foo', 'c:/a/b/c/foo', File::FNM_PATHNAME)  #=> true
    File.fnmatch('**/foo', 'a/.b/c/foo', File::FNM_PATHNAME)    #=> false
    File.fnmatch('**/foo', 'a/.b/c/foo', File::FNM_PATHNAME | File::FNM_DOTMATCH) #=> true

Also aliased as: fnmatch?
fnmatch?( pattern, path, [flags] ) → (true or false)
Alias for: fnmatch
ftype(file_name) → string
Source

    static VALUE
    rb_file_s_ftype(VALUE klass, VALUE fname)
    {
        struct stat st;

        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (lstat_without_gvl(StringValueCStr(fname), &st) == -1) {
            rb_sys_fail_path(fname);
        }

        return rb_file_ftype(&st);
    }

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"

grpowned?(file_name) → true or false
Source

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

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.

identical?(file_1, file_2) → true or false
Source

    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
        extern VALUE rb_w32_file_identical_p(VALUE, VALUE);
        return rb_w32_file_identical_p(fname1, fname2);
    #endif
    }

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

join(string, ...) → string
Source

    static VALUE
    rb_file_s_join(VALUE klass, VALUE args)
    {
        return rb_file_join(args);
    }

Returns a new string formed by joining the strings using `"/"`.

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

lchmod(mode_int, file_name, ...) → integer
Source

    static VALUE
    rb_file_s_lchmod(int argc, VALUE *argv, VALUE _)
    {
        mode_t mode;

        apply2args(1);
        mode = NUM2MODET(*argv++);

        return apply2files(lchmod_internal, argc, argv, &mode);
    }

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.

lchown(owner_int, group_int, file_name,..) → integer
Source

    static VALUE
    rb_file_s_lchown(int argc, VALUE *argv, VALUE _)
    {
        struct chown_args arg;

        apply2args(2);
        arg.owner = to_uid(*argv++);
        arg.group = to_gid(*argv++);

        return apply2files(lchown_internal, argc, argv, &arg);
    }

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.

link(old_name, new_name) → 0
Source

    static VALUE
    rb_file_s_link(VALUE klass, VALUE from, VALUE to)
    {
        FilePathValue(from);
        FilePathValue(to);
        from = rb_str_encode_ospath(from);
        to = rb_str_encode_ospath(to);

        if (link(StringValueCStr(from), StringValueCStr(to)) < 0) {
            sys_fail2(from, to);
        }
        return INT2FIX(0);
    }

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"

lstat(filepath) → stat
Source

    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_without_gvl(StringValueCStr(fname), &st) == -1) {
            rb_sys_fail_path(fname);
        }
        return rb_stat_new(&st);
    #else
        return rb_file_s_stat(klass, fname);
    #endif
    }

Like `File::stat`, but does not follow the last symbolic link; instead, returns a `File::Stat` object for the link itself.

    File.symlink('t.txt', 'symlink')
    File.stat('symlink').size  # => 47
    File.lstat('symlink').size # => 5

lutime(atime, mtime, file_name, ...) → integer
Source

    static VALUE
    rb_file_s_lutime(int argc, VALUE *argv, VALUE _)
    {
        return utime_internal_i(argc, argv, TRUE);
    }

Sets the access and modification times of each named file to the first two arguments. If a file is a symlink, this method acts upon the link itself as opposed to its referent; for the inverse behavior, see `File.utime`. Returns the number of file names in the argument list.

mkfifo(file_name, mode=0666) → 0
Source

    static VALUE
    rb_file_s_mkfifo(int argc, VALUE *argv, VALUE _)
    {
        VALUE path;
        struct mkfifo_arg ma;

        ma.mode = 0666;
        rb_check_arity(argc, 1, 2);
        if (argc > 1) {
            ma.mode = NUM2MODET(argv[1]);
        }
        path = argv[0];
        FilePathValue(path);
        path = rb_str_encode_ospath(path);
        ma.path = RSTRING_PTR(path);
        if (IO_WITHOUT_GVL(nogvl_mkfifo, &ma)) {
            rb_sys_fail_path(path);
        }
        return INT2FIX(0);
    }

Creates a FIFO special file with name file_name. mode specifies the FIFO’s permissions. It is modified by the process’s umask in the usual way: the permissions of the created file are (mode & ~umask).

mtime(file_name) → time
Source

    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);
    }

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

new(path, mode = 'r', perm = 0666, **opts) → file
Source

    static VALUE
    rb_file_initialize(int argc, VALUE *argv, VALUE io)
    {
        if (RFILE(io)->fptr) {
            rb_raise(rb_eRuntimeError, "reinitializing File");
        }
        VALUE fname, vmode, vperm, opt;
        int posargc = rb_scan_args(argc, argv, "12:", &fname, &vmode, &vperm, &opt);
        if (posargc < 3) {          /* perm is File only */
            VALUE fd = rb_check_to_int(fname);

            if (!NIL_P(fd)) {
                return io_initialize(io, fd, vmode, opt);
            }
        }
        return rb_open_file(io, fname, vmode, vperm, opt);
    }

Opens the file at the given `path` according to the given `mode`; creates and returns a new `File` object for that file.

The new `File` object is buffered mode (or non-sync mode), unless `filename` is a tty. See `IO#flush`, `IO#fsync`, `IO#fdatasync`, and `IO#sync=`.

Argument `path` must be a valid file path:

    f = File.new('/etc/fstab')
    f.close
    f = File.new('t.txt')
    f.close

Optional argument `mode` (defaults to ‘r’) must specify a valid mode; see Access Modes:

    f = File.new('t.tmp', 'w')
    f.close
    f = File.new('t.tmp', File::RDONLY)
    f.close

Optional argument `perm` (defaults to 0666) must specify valid permissions see File Permissions:

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

Optional keyword arguments `opts` specify:

- Open Options.

- Encoding options.

open(path, mode = 'r', perm = 0666, **opts) → file
open(path, mode = 'r', perm = 0666, **opts) {|f| ... } → object
Source

    static VALUE
    rb_io_s_open(int argc, VALUE *argv, VALUE klass)
    {
        VALUE io = rb_class_new_instance_kw(argc, argv, klass, RB_PASS_CALLED_KEYWORDS);

        if (rb_block_given_p()) {
            return rb_ensure(rb_yield, io, io_close, io);
        }

        return io;
    }

Creates a new `File` object, via `File.new` with the given arguments.

With no block given, returns the `File` object.

With a block given, calls the block with the `File` object and returns the block’s value.

owned?(file_name) → true or false
Source

    static VALUE
    rb_file_owned_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return RBOOL(st.st_uid == geteuid());
    }

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.

path(path) → string
Source

    static VALUE
    rb_file_s_path(VALUE klass, VALUE fname)
    {
        return rb_get_path(fname);
    }

Returns the string representation of the path

    File.path(File::NULL)           #=> "/dev/null"
    File.path(Pathname.new("/tmp")) #=> "/tmp"

pipe?(filepath) → true or false
Source

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

Returns `true` if `filepath` points to a pipe, `false` otherwise:

    File.mkfifo('tmp/fifo')
    File.pipe?('tmp/fifo') # => true
    File.pipe?('t.txt')    # => false

readable?(file_name) → true or false
Source

    static VALUE
    rb_file_readable_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_eaccess(fname, R_OK) >= 0);
    }

Returns `true` if the named file is readable by the effective user and group id of this process. See eaccess(3).

Note that some OS-level security features may cause this to return true even though the file is not readable by the effective user/group.

readable_real?(file_name) → true or false
Source

    static VALUE
    rb_file_readable_real_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_access(fname, R_OK) >= 0);
    }

Returns `true` if the named file is readable by the real user and group id of this process. See access(3).

Note that some OS-level security features may cause this to return true even though the file is not readable by the real user/group.

readlink(link_name) → file_name
Source

    static VALUE
    rb_file_s_readlink(VALUE klass, VALUE path)
    {
        return rb_readlink(path, rb_filesystem_encoding());
    }

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"

realdirpath(pathname [, dir_string]) → real_pathname
Source

    static VALUE
    rb_file_s_realdirpath(int argc, VALUE *argv, VALUE klass)
    {
        VALUE basedir = (rb_check_arity(argc, 1, 2) > 1) ? argv[1] : Qnil;
        VALUE path = argv[0];
        FilePathValue(path);
        return rb_realpath_internal(basedir, path, 0);
    }

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.

realpath(pathname [, dir_string]) → real_pathname
Source

    static VALUE
    rb_file_s_realpath(int argc, VALUE *argv, VALUE klass)
    {
        VALUE basedir = (rb_check_arity(argc, 1, 2) > 1) ? argv[1] : Qnil;
        VALUE path = argv[0];
        FilePathValue(path);
        return rb_realpath_internal(basedir, path, 1);
    }

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.

rename(old_name, new_name) → 0
Source

    static VALUE
    rb_file_s_rename(VALUE klass, VALUE from, VALUE to)
    {
        struct rename_args ra;
        VALUE f, t;

        FilePathValue(from);
        FilePathValue(to);
        f = rb_str_encode_ospath(from);
        t = rb_str_encode_ospath(to);
        ra.src = StringValueCStr(f);
        ra.dst = StringValueCStr(t);
    #if defined __CYGWIN__
        errno = 0;
    #endif
        if (IO_WITHOUT_GVL_INT(no_gvl_rename, &ra) < 0) {
            int e = errno;
    #if defined DOSISH
            switch (e) {
              case EEXIST:
                if (chmod(ra.dst, 0666) == 0 &&
                    unlink(ra.dst) == 0 &&
                    rename(ra.src, ra.dst) == 0)
                    return INT2FIX(0);
            }
    #endif
            syserr_fail2(e, from, to);
        }

        return INT2FIX(0);
    }

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

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

setgid?(file_name) → true or false
Source

    static VALUE
    rb_file_sgid_p(VALUE obj, VALUE fname)
    {
    #ifdef S_ISGID
        return check3rdbyte(fname, S_ISGID);
    #else
        return Qfalse;
    #endif
    }

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

file_name can be an `IO` object.

setuid?(file_name) → true or false
Source

    static VALUE
    rb_file_suid_p(VALUE obj, VALUE fname)
    {
    #ifdef S_ISUID
        return check3rdbyte(fname, S_ISUID);
    #else
        return Qfalse;
    #endif
    }

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

file_name can be an `IO` object.

size(file_name) → integer
Source

    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);
    }

Returns the size of `file_name`.

file_name can be an `IO` object.

size?(file_name) → Integer or nil
Source

    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);
    }

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.

socket?(filepath) → true or false
Source

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

Returns `true` if `filepath` points to a socket, `false` otherwise:

    require 'socket'
    File.socket?(Socket.new(:INET, :STREAM)) # => true
    File.socket?(File.new('t.txt'))          # => false

split(file_name) → array
Source

    static VALUE
    rb_file_s_split(VALUE klass, VALUE path)
    {
        FilePathStringValue(path);          /* get rid of converting twice */
        return rb_assoc_new(rb_file_dirname(path), rb_file_s_basename(1,&path,Qundef));
    }

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

stat(filepath) → stat
Source

    static VALUE
    rb_file_s_stat(VALUE klass, VALUE fname)
    {
        struct stat st;

        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (stat_without_gvl(RSTRING_PTR(fname), &st) < 0) {
            rb_sys_fail_path(fname);
        }
        return rb_stat_new(&st);
    }

Returns a `File::Stat` object for the file at `filepath` (see `File::Stat`):

    File.stat('t.txt').class # => File::Stat

sticky?(file_name) → true or false
Source

    static VALUE
    rb_file_sticky_p(VALUE obj, VALUE fname)
    {
    #ifdef S_ISVTX
        return check3rdbyte(fname, S_ISVTX);
    #else
        return Qfalse;
    #endif
    }

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

file_name can be an `IO` object.

symlink(old_name, new_name) → 0
Source

    static VALUE
    rb_file_s_symlink(VALUE klass, VALUE from, VALUE to)
    {
        FilePathValue(from);
        FilePathValue(to);
        from = rb_str_encode_ospath(from);
        to = rb_str_encode_ospath(to);

        if (symlink(StringValueCStr(from), StringValueCStr(to)) < 0) {
            sys_fail2(from, to);
        }
        return INT2FIX(0);
    }

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

symlink?(filepath) → true or false
Source

    static VALUE
    rb_file_symlink_p(VALUE obj, VALUE fname)
    {
    #ifndef S_ISLNK
    #  ifdef _S_ISLNK
    #    define S_ISLNK(m) _S_ISLNK(m)
    #  else
    #    ifdef _S_IFLNK
    #      define S_ISLNK(m) (((m) & S_IFMT) == _S_IFLNK)
    #    else
    #      ifdef S_IFLNK
    #        define S_ISLNK(m) (((m) & S_IFMT) == S_IFLNK)
    #      endif
    #    endif
    #  endif
    #endif

    #ifdef S_ISLNK
        struct stat st;

        FilePathValue(fname);
        fname = rb_str_encode_ospath(fname);
        if (lstat_without_gvl(StringValueCStr(fname), &st) < 0) return Qfalse;
        if (S_ISLNK(st.st_mode)) return Qtrue;
    #endif

        return Qfalse;
    }

Returns `true` if `filepath` points to a symbolic link, `false` otherwise:

    symlink = File.symlink('t.txt', 'symlink')
    File.symlink?('symlink') # => true
    File.symlink?('t.txt')   # => false

truncate(file_name, integer) → 0
Source

    static VALUE
    rb_file_s_truncate(VALUE klass, VALUE path, VALUE len)
    {
        struct truncate_arg ta;
        int r;

        ta.pos = NUM2OFFT(len);
        FilePathValue(path);
        path = rb_str_encode_ospath(path);
        ta.path = StringValueCStr(path);

        r = IO_WITHOUT_GVL_INT(nogvl_truncate, &ta);
        if (r < 0)
            rb_sys_fail_path(path);
        return INT2FIX(0);
    }

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

umask() → integer
umask(integer) → integer
Source

    static VALUE
    rb_file_s_umask(int argc, VALUE *argv, VALUE _)
    {
        mode_t omask = 0;

        switch (argc) {
          case 0:
            omask = umask(0);
            umask(omask);
            break;
          case 1:
            omask = umask(NUM2MODET(argv[0]));
            break;
          default:
            rb_error_arity(argc, 0, 1);
        }
        return MODET2NUM(omask);
    }

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

delete(file_name, ...) → integer
unlink(file_name, ...) → integer
Source

    static VALUE
    rb_file_s_unlink(int argc, VALUE *argv, VALUE klass)
    {
        return apply2files(unlink_internal, argc, argv, 0);
    }

Deletes the named files, returning the number of names passed as arguments. Raises an exception on any error. Since the underlying implementation relies on the `unlink(2)` system call, the type of exception raised depends on its error type (see linux.die.net/man/2/unlink) and has the form of e.g. Errno::ENOENT.

See also `Dir::rmdir`.

utime(atime, mtime, file_name, ...) → integer
Source

    static VALUE
    rb_file_s_utime(int argc, VALUE *argv, VALUE _)
    {
        return utime_internal_i(argc, argv, FALSE);
    }

Sets the access and modification times of each named file to the first two arguments. If a file is a symlink, this method acts upon its referent rather than the link itself; for the inverse behavior see `File.lutime`. Returns the number of file names in the argument list.

world_readable?(file_name) → integer or nil
Source

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

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"

world_writable?(file_name) → integer or nil
Source

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

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"

writable?(file_name) → true or false
Source

    static VALUE
    rb_file_writable_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_eaccess(fname, W_OK) >= 0);
    }

Returns `true` if the named file is writable by the effective user and group id of this process. See eaccess(3).

Note that some OS-level security features may cause this to return true even though the file is not writable by the effective user/group.

writable_real?(file_name) → true or false
Source

    static VALUE
    rb_file_writable_real_p(VALUE obj, VALUE fname)
    {
        return RBOOL(rb_access(fname, W_OK) >= 0);
    }

Returns `true` if the named file is writable by the real user and group id of this process. See access(3).

Note that some OS-level security features may cause this to return true even though the file is not writable by the real user/group.

zero?(file_name) → true or false
Source

    static VALUE
    rb_file_zero_p(VALUE obj, VALUE fname)
    {
        struct stat st;

        if (rb_stat(fname, &st) < 0) return Qfalse;
        return RBOOL(st.st_size == 0);
    }

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

file_name can be an `IO` object.

### Public Instance Methods

atime → time
Source

    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);
    }

Returns the last access time (a `Time` object) for file, or epoch if file has not been accessed.

    File.new("testfile").atime   #=> Wed Dec 31 18:00:00 CST 1969

birthtime → time
Source

    static VALUE
    rb_file_birthtime(VALUE obj)
    {
        rb_io_t *fptr;
        statx_data st;

        GetOpenFile(obj, fptr);
        if (fstatx_without_gvl(fptr, &st, STATX_BTIME) == -1) {
            rb_sys_fail_path(fptr->pathv);
        }
        return statx_birthtime(&st, fptr->pathv);
    }

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

chmod(mode_int) → 0
Source

    static VALUE
    rb_file_chmod(VALUE obj, VALUE vmode)
    {
        rb_io_t *fptr;
        mode_t mode;
    #if !defined HAVE_FCHMOD || !HAVE_FCHMOD
        VALUE path;
    #endif

        mode = NUM2MODET(vmode);

        GetOpenFile(obj, fptr);
    #ifdef HAVE_FCHMOD
        if (rb_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 (rb_chmod(RSTRING_PTR(path), mode) == -1)
            rb_sys_fail_path(fptr->pathv);
    #endif

        return INT2FIX(0);
    }

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

chown(owner_int, group_int ) → 0
Source

    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 (rb_chown(RSTRING_PTR(path), o, g) == -1)
            rb_sys_fail_path(fptr->pathv);
    #else
        if (rb_fchown(fptr->fd, o, g) == -1)
            rb_sys_fail_path(fptr->pathv);
    #endif

        return INT2FIX(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)

ctime → time
Source

    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);
    }

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

flock(locking_constant) → 0 or false
Source

    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_io_blocking_region(fptr, rb_thread_flock, op) < 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);
    }

Locks or unlocks file `self` according to the given `locking_constant`, a bitwise OR of the values in the table below.

Not available on all platforms.

Returns `false` if `File::LOCK_NB` is specified and the operation would have blocked; otherwise returns `0`.

Constant | Lock | Effect
--- | --- | ---
`File::LOCK_EX` | Exclusive | Only one process may hold an exclusive lock for `self` at a time.
`File::LOCK_NB` | Non-blocking | No blocking; may be combined with `File::LOCK_SH` or `File::LOCK_EX` using the bitwise OR operator `|`.
`File::LOCK_SH` | Shared | Multiple processes may each hold a shared lock for `self` at the same time.
`File::LOCK_UN` | Unlock | Remove an existing lock held by this process.

Example:

    # Update a counter using an exclusive lock.
    # Don't use File::WRONLY because it truncates the file.
    File.open('counter', File::RDWR | File::CREAT, 0644) do |f|
      f.flock(File::LOCK_EX)
      value = f.read.to_i + 1
      f.rewind
      f.write("#{value}\n")
      f.flush
      f.truncate(f.pos)
    end

    # Read the counter using a shared lock.
    File.open('counter', 'r') do |f|
      f.flock(File::LOCK_SH)
      f.read
    end

lstat → stat
Source

    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_without_gvl(RSTRING_PTR(path), &st) == -1) {
            rb_sys_fail_path(fptr->pathv);
        }
        return rb_stat_new(&st);
    #else
        return rb_io_stat(obj);
    #endif
    }

Like `File#stat`, but does not follow the last symbolic link; instead, returns a `File::Stat` object for the link itself:

    File.symlink('t.txt', 'symlink')
    f = File.new('symlink')
    f.stat.size  # => 47
    f.lstat.size # => 11

mtime → time
Source

    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);
    }

Returns the modification time for file.

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

size → integer
Source

    static VALUE
    file_size(VALUE self)
    {
        return OFFT2NUM(rb_file_size(self));
    }

Returns the size of file in bytes.

    File.new("testfile").size   #=> 66

truncate(integer) → 0
Source

    static VALUE
    rb_file_truncate(VALUE obj, VALUE len)
    {
        rb_io_t *fptr;
        struct ftruncate_arg fa;

        fa.pos = NUM2OFFT(len);
        GetOpenFile(obj, fptr);
        if (!(fptr->mode & FMODE_WRITABLE)) {
            rb_raise(rb_eIOError, "not opened for writing");
        }
        rb_io_flush_raw(obj, 0);
        fa.fd = fptr->fd;
        if ((int)rb_io_blocking_region(fptr, nogvl_ftruncate, &fa) < 0) {
            rb_sys_fail_path(fptr->pathv);
        }
        return INT2FIX(0);
    }

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