123456789_123456789_123456789_123456789_123456789_

Class: File

Relationships & Source Files
Namespace Children
Modules:
Classes:
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, ::IO
Instance Chain:
Inherits: IO
Defined in: file.c,
dir.c,
io.c

Overview

A File is an abstraction of any file object accessible by the program and is closely associated with class ::IO. File includes the methods of module ::FileTest as class methods, allowing you to write (for example) File.exist?("foo").

In the description of File methods, permission bits are a platform-specific set of bits that indicate permissions of a file. On Unix-based systems, permissions are viewed as a set of three octets, for the owner, the group, and the rest of the world. For each of these entities, permissions may be set to read, write, or execute the file:

The permission bits 0644 (in octal) would thus be interpreted as read/write for owner, and read-only for group and other. Higher-order bits may also be used to indicate the type of file (plain, directory, pipe, socket, and so on) and various other special features. If the permissions are for a directory, the meaning of the execute bit changes; when set the directory can be searched.

On non-Posix operating systems, there may be only the ability to make a file read-only or read-write. In this case, the remaining permission bits will be synthesized to resemble typical values. For instance, on Windows NT the default permission bits are 0644, which means read/write for owner, read-only for all others. The only change that can be made is to make the file read-only, which is reported as 0444.

Various constants for the methods in File can be found in Constants.

Constant Summary

Constants - Included

APPEND, BINARY, CREAT, DIRECT, DSYNC, EXCL, LOCK_EX, LOCK_NB, LOCK_SH, LOCK_UN, NOATIME, NOCTTY, NOFOLLOW, NONBLOCK, NULL, RDONLY, RDWR, RSYNC, SHARE_DELETE, SYNC, TMPFILE, TRUNC, WRONLY

::IO - Inherited

SEEK_CUR, SEEK_DATA, SEEK_END, SEEK_HOLE, SEEK_SET

Class Attribute Summary

Class Method Summary

::IO - Inherited

.binread

Opens the file, optionally seeks to the given offset, then returns length bytes (defaulting to the rest of the file).

.binwrite

Same as IO.write except opening the file in binary mode and ASCII-8BIT encoding (“wb:ASCII-8BIT”).

.copy_stream

copy_stream copies src to dst.

.for_fd

Synonym for IO.new.

.foreach

Executes the block for every line in the named I/O port, where lines are separated by sep.

.open

Alias for .open.

.pipe

::IO.pipe(…) {|read_io, write_io| … }

.popen

Runs the specified command as a subprocess; the subprocess's standard input and output will be connected to the returned ::IO object.

.read

Opens the file, optionally seeks to the given offset, then returns length bytes (defaulting to the rest of the file).

.readlines

Reads the entire file specified by name as individual lines, and returns those lines in an array.

.select

Alias for Kernel.select.

.sysopen

Opens the given path, returning the underlying file descriptor as a ::Fixnum.

.try_convert

Try to convert obj into an ::IO, using to_io method.

.write

Opens the file, optionally seeks to the given offset, writes string, then returns the length written.

Instance Attribute Summary

::IO - Inherited

#autoclose=

Sets auto-close flag.

#autoclose?

Returns true if the underlying file descriptor of ios will be closed automatically at its finalization, otherwise false.

#close_on_exec=

Sets a close-on-exec flag.

#close_on_exec?

Returns true if ios will be closed on exec.

#lineno

Returns the current line number in ios.

#lineno=

Manually sets the current line number to the given value.

#pos

Returns the current offset (in bytes) of ios.

#pos=

Seeks to the given position (in bytes) in ios.

#sync

Returns the current “sync mode'' of ios.

#sync=

Sets the “sync mode'' to true or false.

#binmode

Puts ios into binary mode.

#binmode?

Returns true if ios is binmode.

#closed?

Returns true if ios is completely closed (for duplex streams, both reader and writer), false otherwise.

#eof

Returns true if ios is at end of file that means there are no more data to read.

#eof?

Alias for IO#eof.

#isatty

Alias for IO#tty?.

#tell

Alias for IO#pos.

#tty?

Returns true if ios is associated with a terminal device (tty), false otherwise.

::Enumerable - Included

#all?

Passes each element of the collection to the given block.

#any?

Passes each element of the collection to the given block.

#none?

Passes each element of the collection to the given block.

#one?

Passes each element of the collection to the given block.

Instance Method Summary

::IO - Inherited

#<<

::String Output—Writes obj to ios.

#advise

Announce an intention to access data from the current file in a specific pattern.

#bytes

This is a deprecated alias for each_byte.

#chars

This is a deprecated alias for each_char.

#close

Closes ios and flushes any pending writes to the operating system.

#close_read

Closes the read end of a duplex I/O stream (i.e., one that contains both a read and a write stream, such as a pipe).

#close_write

Closes the write end of a duplex I/O stream (i.e., one that contains both a read and a write stream, such as a pipe).

#codepoints

This is a deprecated alias for each_codepoint.

#each

ios.each_line(sep=$/) {|line| block } -> ios.

#each_byte

Calls the given block once for each byte (0..255) in ios, passing the byte as an argument.

#each_char

Calls the given block once for each character in ios, passing the character as an argument.

#each_codepoint

Passes the ::Integer ordinal of each character in ios, passing the codepoint as an argument.

#each_line

Alias for IO#each.

#external_encoding

Returns the ::Encoding object that represents the encoding of the file.

#fcntl

Provides a mechanism for issuing low-level commands to control or query file-oriented I/O streams.

#fdatasync

Immediately writes all buffered data in ios to disk.

#fileno

Alias for IO#to_i.

#flush

Flushes any buffered data within ios to the underlying operating system (note that this is Ruby internal buffering only; the OS may buffer the data as well).

#fsync

Immediately writes all buffered data in ios to disk.

#getbyte

Gets the next 8-bit byte (0..255) from ios.

#getc

Reads a one-character string from ios.

#gets

Reads the next “line'' from the I/O stream; lines are separated by sep.

#initialize

Returns a new ::IO object (a stream) for the given integer file descriptor fd and mode string.

#inspect

Return a string describing this ::IO object.

#internal_encoding

Returns the ::Encoding of the internal string if conversion is specified.

#ioctl

Provides a mechanism for issuing low-level commands to control or query I/O devices.

#lines

This is a deprecated alias for each_line.

#pid

Returns the process ID of a child process associated with ios.

#print

Writes the given object(s) to ios.

#printf

Formats and writes to ios, converting parameters under control of the format string.

#putc

If obj is ::Numeric, write the character whose code is the least-significant byte of obj, otherwise write the first byte of the string representation of obj to ios.

#puts

Writes the given object(s) to ios.

#read

Reads length bytes from the I/O stream.

#read_nonblock

Reads at most maxlen bytes from ios using the read(2) system call after O_NONBLOCK is set for the underlying file descriptor.

#readbyte

Reads a byte as with IO#getbyte, but raises an ::EOFError on end of file.

#readchar

Reads a one-character string from ios.

#readline

Reads a line as with IO#gets, but raises an ::EOFError on end of file.

#readlines

Reads all of the lines in ios, and returns them in anArray.

#readpartial

Reads at most maxlen bytes from the I/O stream.

#reopen

Reassociates ios with the I/O stream given in other_IO or to a new stream opened on path.

#rewind

Positions ios to the beginning of input, resetting lineno to zero.

#seek

Seeks to a given offset anInteger in the stream according to the value of whence:

#set_encoding

If single argument is specified, read string from io is tagged with the encoding specified.

#stat

Returns status information for ios as an object of type Stat.

#sysread

Reads maxlen bytes from ios using a low-level read and returns them as a string.

#sysseek

Seeks to a given offset in the stream according to the value of whence (see IO#seek for values of whence).

#syswrite

Writes the given string to ios using a low-level write.

#to_i

Returns an integer representing the numeric file descriptor for ios.

#to_io

Returns ios.

#ungetbyte

Pushes back bytes (passed as a parameter) onto ios, such that a subsequent buffered read will return it.

#ungetc

Pushes back one character (passed as a parameter) onto ios, such that a subsequent buffered character read will return it.

#write

Writes the given string to ios.

#write_nonblock

Writes the given string to ios using the write(2) system call after O_NONBLOCK is set for the underlying file descriptor.

::Enumerable - Included

#chunk

Enumerates over the items, chunking them together based on the return value of the block.

#chunk_while

Creates an enumerator for each chunked elements.

#collect

Alias for Enumerable#map.

#collect_concat
#count

Returns the number of items in enum through enumeration.

#cycle

Calls block for each element of enum repeatedly n times or forever if none or nil is given.

#detect

Alias for Enumerable#find.

#drop

Drops first n elements from enum, and returns rest elements in an array.

#drop_while

Drops elements up to, but not including, the first element for which the block returns nil or false and returns an array containing the remaining elements.

#each_cons

Iterates the given block for each array of consecutive <n> elements.

#each_entry

Calls block once for each element in self, passing that element as a parameter, converting multiple values from yield to an array.

#each_slice

Iterates the given block for each slice of <n> elements.

#each_with_index

Calls block with two arguments, the item and its index, for each item in enum.

#each_with_object

Iterates the given block for each element with an arbitrary object given, and returns the initially given object.

#entries

Alias for Enumerable#to_a.

#find

Passes each entry in enum to block.

#find_all
#find_index

Compares each entry in enum with value or passes to block.

#first

Returns the first element, or the first n elements, of the enumerable.

#flat_map

Returns a new array with the concatenated results of running block once for every element in enum.

#grep

Returns an array of every element in enum for which Pattern === element.

#grep_v

Inverted version of Enumerable#grep.

#group_by

Groups the collection by result of the block.

#include?
#inject

Combines all elements of enum by applying a binary operation, specified by a block or a symbol that names a method or operator.

#lazy

Returns a lazy enumerator, whose methods map/collect, flat_map/collect_concat, select/find_all, reject, grep, grep_v, zip, take, take_while, drop, and drop_while enumerate values only on an as-needed basis.

#map

Returns a new array with the results of running block once for every element in enum.

#max

Returns the object in enum with the maximum value.

#max_by

Returns the object in enum that gives the maximum value from the given block.

#member?

Returns true if any member of enum equals obj.

#min

Returns the object in enum with the minimum value.

#min_by

Returns the object in enum that gives the minimum value from the given block.

#minmax

Returns a two element array which contains the minimum and the maximum value in the enumerable.

#minmax_by

Returns a two element array containing the objects in enum that correspond to the minimum and maximum values respectively from the given block.

#partition

Returns two arrays, the first containing the elements of enum for which the block evaluates to true, the second containing the rest.

#reduce
#reject

Returns an array for all elements of enum for which the given block returns false.

#reverse_each

Builds a temporary array and traverses that array in reverse order.

#select

Returns an array containing all elements of enum for which the given block returns a true value.

#slice_after

Creates an enumerator for each chunked elements.

#slice_before

Creates an enumerator for each chunked elements.

#slice_when

Creates an enumerator for each chunked elements.

#sort

Returns an array containing the items in enum sorted, either according to their own <=> method, or by using the results of the supplied block.

#sort_by

Sorts enum using a set of keys generated by mapping the values in enum through the given block.

#take

Returns first n elements from enum.

#take_while

Passes elements to the block until the block returns nil or false, then stops iterating and returns an array of all prior elements.

#to_a

Returns an array containing the items in enum.

#to_h

Returns the result of interpreting enum as a list of [key, value] pairs.

#zip

Takes one element from enum and merges corresponding elements from each args.

Constructor Details

.new(filename, mode="r" [, opt]) ⇒ File .new(filename [, mode [, perm]] [, opt]) ⇒ File

Opens the file named by filename according to the given mode and returns a new File object.

See IO.new for a description of mode and opt.

If a file is being created, permission bits may be given in perm. These mode and permission bits are platform dependent; on Unix systems, see open(2) and chmod(2) man pages for details.

Examples

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

Class Attribute Details

.directory?(file_name) ⇒ Boolean (readonly)

Alias for Dir.exist?.

Class Method Details

.absolute_path(file_name [, dir_string] ) ⇒ File

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"

.atime(file_name) ⇒ Time

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

Returns the last component of the filename given in file_name, which can be formed using both SEPARATOR and ALT_SEPARATOR as the separator when 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

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?(file_name) ⇒ Boolean

Returns true if the named file is a block device.

file_name can be an ::IO object.

.chardev?(file_name) ⇒ Boolean

Returns true if the named file is a character device.

file_name can be an ::IO object.

.chmod(mode_int, file_name, ... ) ⇒ Integer

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

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

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
Also known as: .unlink

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

.dirname(file_name) ⇒ dir_name

Returns all components of the filename given in file_name except the last one. The filename can be formed using both SEPARATOR and ALT_SEPARATOR as the separator when ALT_SEPARATOR is not nil.

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

.executable?(file_name) ⇒ Boolean

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

.executable_real?(file_name) ⇒ Boolean

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

.exist?(file_name) ⇒ Boolean

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.

.exists?(file_name) ⇒ Boolean

Deprecated method. Don't use.

.expand_path(file_name [, dir_string] ) ⇒ File

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

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.

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

.file?(file) ⇒ Boolean

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]) ⇒ Boolean .fnmatch?(pattern, path, [flags]) ⇒ Boolean
Also known as: .fnmatch?

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 files 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('?',   '/', 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

rbfiles = '**' '/' '*.rb' # you don't have to do like this. just write in single string.
File.fnmatch(rbfiles, 'main.rb')                    #=> false
File.fnmatch(rbfiles, './main.rb')                  #=> false
File.fnmatch(rbfiles, '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

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

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

.fnmatch(pattern, path, [flags]) ⇒ Boolean .fnmatch?(pattern, path, [flags]) ⇒ Boolean

Alias for .fnmatch.

.ftype(file_name) ⇒ String

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) ⇒ Boolean

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) ⇒ Boolean

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

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

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

.lchmod(mode_int, file_name, ...) ⇒ Integer

Equivalent to .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

Equivalent to .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.

.lstat(file_name) ⇒ stat

Same as .stat, but does not follow the last symbolic link. Instead, reports on the link itself.

File.symlink("testfile", "link2test")   #=> 0
File.stat("testfile").size              #=> 66
File.lstat("link2test").size            #=> 8
File.stat("link2test").size             #=> 66

.mkfifo(*args)

.mtime(file_name) ⇒ Time

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

.open(filename, mode="r" [, opt]) ⇒ File .open(filename [, mode [, perm]] [, opt]) ⇒ File .open(filename, mode="r" [, opt]) {|file| ... } ⇒ Object .open(filename [, mode [, perm]] [, opt]) {|file| ... } ⇒ Object

With no associated block, open is a synonym for .new. If the optional code block is given, it will be passed the opened file as an argument and the File object will automatically be closed when the block terminates. The value of the block will be returned from open.

If a file is being created, its initial permissions may be set using the perm parameter. See .new for further discussion.

See IO.new for a description of the mode and opt parameters.

.owned?(file_name) ⇒ Boolean

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

Returns the string representation of the path

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

.pipe?(file_name) ⇒ Boolean

Returns true if the named file is a pipe.

file_name can be an ::IO object.

.readable?(file_name) ⇒ Boolean

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

.readable_real?(file_name) ⇒ Boolean

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

.realdirpath(pathname [, dir_string]) ⇒ real_pathname

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

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

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) ⇒ Boolean

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

.setuid?(file_name) ⇒ Boolean

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

.size(file_name) ⇒ Integer

Returns the size of file_name.

file_name can be an ::IO object.

.size?(file_name) ⇒ Integer?

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?(file_name) ⇒ Boolean

Returns true if the named file is a socket.

file_name can be an ::IO object.

.split(file_name) ⇒ Array

Splits the given string into a directory and a file component and returns them in a two-element array. See also .dirname and .basename.

File.split("/home/gumby/.profile")   #=> ["/home/gumby", ".profile"]

.stat(file_name) ⇒ stat

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

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

.sticky?(file_name) ⇒ Boolean

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

.symlink?(file_name) ⇒ Boolean

Returns true if the named file is a symbolic link.

.truncate(file_name, integer) ⇒ 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

.umaskInteger .umask(integer) ⇒ Integer

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

.utime(atime, mtime, file_name,...) ⇒ Integer

Sets the access and modification times of each named file to the first two arguments. Returns the number of file names in the argument list.

.world_readable?(file_name) ⇒ Fixnum?

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) ⇒ Fixnum?

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) ⇒ Boolean

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

.writable_real?(file_name) ⇒ Boolean

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

.zero?(file_name) ⇒ Boolean

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

file_name can be an ::IO object.

Instance Method Details

#atimeTime

Returns the last access time (a ::Time object)

for <i>file</i>, or epoch if <i>file</i> has not been accessed.

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

#birthtimeTime

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

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

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)

#ctimeTime

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

Locks or unlocks a file according to locking_constant (a logical or of the values in the table below). Returns false if File::LOCK_NB is specified and the operation would otherwise have blocked. Not available on all platforms.

Locking constants (in class File):

LOCK_EX   | Exclusive lock. Only one process may hold an
          | exclusive lock for a given file at a time.
----------+------------------------------------------------
LOCK_NB   | Don't block when locking. May be combined
          | with other lock options using logical or.
----------+------------------------------------------------
LOCK_SH   | Shared lock. Multiple processes may each hold a
          | shared lock for a given file at the same time.
----------+------------------------------------------------
LOCK_UN   | Unlock.

Example:

# update a counter using write lock
# don't use "w" because it truncates the file before lock.
File.open("counter", File::RDWR|File::CREAT, 0644) {|f|
  f.flock(File::LOCK_EX)
  value = f.read.to_i + 1
  f.rewind
  f.write("#{value}\n")
  f.flush
  f.truncate(f.pos)
}

# read the counter using read lock
File.open("counter", "r") {|f|
  f.flock(File::LOCK_SH)
  p f.read
}

#lstatstat

Same as IO#stat, but does not follow the last symbolic link. Instead, reports on the link itself.

File.symlink("testfile", "link2test")   #=> 0
File.stat("testfile").size              #=> 66
f = File.new("link2test")
f.lstat.size                            #=> 8
f.stat.size                             #=> 66

#mtimeTime

Returns the modification time for file.

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

#pathFile #to_pathFile
Also known as: #to_path

Returns the pathname used to create file as a string. Does not normalize the name.

File.new("testfile").path               #=> "testfile"
File.new("/tmp/../tmp/xxx", "w").path   #=> "/tmp/../tmp/xxx"

#sizeInteger

Returns the size of file in bytes.

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

#pathFile #to_pathFile

Alias for #path.

#truncate(integer) ⇒ 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