Class: File::Stat

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Instance Chain: self, ::Comparable
Inherits:	Object
Defined in:	file.c, file.c

Overview

Objects of class Stat encapsulate common status information for ::File objects. The information is recorded at the moment the Stat object is created; changes made to the file after that point will not be reflected. Stat objects are returned by IO#stat, stat, #lstat, and lstat. Many of these methods return platform-specific values, and not all values are meaningful on all systems. See also Kernel#test.

Class Method Summary

.new(file_name) ⇒ Stat constructor

Create a Stat object for the given file name (raising an exception if the file doesn't exist).

Instance Attribute Summary

#blockdev? ⇒ Boolean readonly

Returns true if the file is a block device, false if it isn't or if the operating system doesn't support this feature.
#chardev? ⇒ Boolean readonly

Returns true if the file is a character device, false if it isn't or if the operating system doesn't support this feature.
#directory? ⇒ Boolean readonly

Returns true if stat is a directory, false otherwise.
#executable? ⇒ Boolean readonly

Returns true if stat is executable or if the operating system doesn't distinguish executable files from nonexecutable files.
#executable_real? ⇒ Boolean readonly

Same as #executable?, but tests using the real owner of the process.
#file? ⇒ Boolean readonly

Returns true if stat is a regular file (not a device file, pipe, socket, etc.).
#grpowned? ⇒ Boolean readonly

Returns true if the effective group id of the process is the same as the group id of stat.
#owned? ⇒ Boolean readonly

Returns true if the effective user id of the process is the same as the owner of stat.
#pipe? ⇒ Boolean readonly

Returns true if the operating system supports pipes and stat is a pipe; false otherwise.
#readable? ⇒ Boolean readonly

Returns true if stat is readable by the effective user id of this process.
#readable_real? ⇒ Boolean readonly

Returns true if stat is readable by the real user id of this process.
#setgid? ⇒ Boolean readonly

Returns true if stat has the set-group-id permission bit set, false if it doesn't or if the operating system doesn't support this feature.
#setuid? ⇒ Boolean readonly

Returns true if stat has the set-user-id permission bit set, false if it doesn't or if the operating system doesn't support this feature.
#size ⇒ Fixnum readonly

Returns the size of stat in bytes.
#size ⇒ Integer readonly

Returns the size of stat in bytes.
#socket? ⇒ Boolean readonly

Returns true if stat is a socket, false if it isn't or if the operating system doesn't support this feature.
#sticky? ⇒ Boolean readonly

Returns true if stat has its sticky bit set, false if it doesn't or if the operating system doesn't support this feature.
#symlink? ⇒ Boolean readonly

Returns true if stat is a symbolic link, false if it isn't or if the operating system doesn't support this feature.
#world_readable? ⇒ Boolean readonly

If stat is readable by others, returns an integer representing the file permission bits of stat.
#world_writable? ⇒ Boolean readonly

If stat is writable by others, returns an integer representing the file permission bits of stat.
#writable? ⇒ Boolean readonly

Returns true if stat is writable by the effective user id of this process.
#writable_real? ⇒ Boolean readonly

Returns true if stat is writable by the real user id of this process.
#zero? ⇒ Boolean readonly

Returns true if stat is a zero-length file; false otherwise.

Instance Method Summary

#<=>(other_stat) ⇒ 1, ...

Compares Stat objects by comparing their respective modification times.
#atime ⇒ Time

Returns the last access time for this file as an object of class ::Time.
#birthtime ⇒ Time

Returns the birth time for stat.
#blksize ⇒ Integer^?

Returns the native file system's block size.
#blocks ⇒ Integer^?

Returns the number of native file system blocks allocated for this file, or nil if the operating system doesn't support this feature.
#ctime ⇒ Time

Returns the change time for stat (that is, the time directory information about the file was changed, not the file itself).
#dev ⇒ Fixnum

Returns an integer representing the device on which stat resides.
#dev_major ⇒ Fixnum

Returns the major part of File_Stat#dev or nil.
#dev_minor ⇒ Fixnum

Returns the minor part of File_Stat#dev or nil.
#ftype ⇒ String

Identifies the type of stat.
#gid ⇒ Fixnum

Returns the numeric group id of the owner of stat.
#ino ⇒ Fixnum

Returns the inode number for stat.
#inspect ⇒ String

Produce a nicely formatted description of stat.
#mode ⇒ Fixnum

Returns an integer representing the permission bits of stat.
#mtime ⇒ Time

Returns the modification time of stat.
#nlink ⇒ Fixnum

Returns the number of hard links to stat.
#rdev ⇒ Fixnum^?

Returns an integer representing the device type on which stat resides.
#rdev_major ⇒ Fixnum

Returns the major part of File_Stat#rdev or nil.
#rdev_minor ⇒ Fixnum

Returns the minor part of File_Stat#rdev or nil.
#uid ⇒ Fixnum

Returns the numeric user id of the owner of stat.

::Comparable - Included

#<	Compares two objects based on the receiver's #<=> method, returning true if it returns -1.
#<=	Compares two objects based on the receiver's #<=> method, returning true if it returns -1 or 0.
#==	Compares two objects based on the receiver's #<=> method, returning true if it returns 0.
#>	Compares two objects based on the receiver's #<=> method, returning true if it returns 1.
#>=	Compares two objects based on the receiver's #<=> method, returning true if it returns 0 or 1.
#between?	Returns `false` if obj #<=> min is less than zero or if anObject #<=> max is greater than zero, `true` otherwise.

Constructor Details

.new(file_name) ⇒ `Stat`

Create a Stat object for the given file name (raising an exception if the file doesn't exist).

Instance Attribute Details

#blockdev? ⇒ `Boolean` (readonly)

Returns true if the file is a block device, false if it isn't or if the operating system doesn't support this feature.

File.stat("testfile").blockdev?    #=> false
File.stat("/dev/hda1").blockdev?   #=> true

#chardev? ⇒ `Boolean` (readonly)

Returns true if the file is a character device, false if it isn't or if the operating system doesn't support this feature.

File.stat("/dev/tty").chardev?   #=> true

#directory? ⇒ `Boolean` (readonly)

Returns true if stat is a directory, false otherwise.

File.stat("testfile").directory?   #=> false
File.stat(".").directory?          #=> true

#executable? ⇒ `Boolean` (readonly)

Returns true if stat is executable or if the operating system doesn't distinguish executable files from nonexecutable files. The tests are made using the effective owner of the process.

File.stat("testfile").executable?   #=> false

#executable_real? ⇒ `Boolean` (readonly)

Same as #executable?, but tests using the real owner of the process.

#file? ⇒ `Boolean` (readonly)

Returns true if stat is a regular file (not a device file, pipe, socket, etc.).

File.stat("testfile").file?   #=> true

#grpowned? ⇒ `Boolean` (readonly)

Returns true if the effective group id of the process is the same as the group id of stat. On Windows NT, returns false.

File.stat("testfile").grpowned?      #=> true
File.stat("/etc/passwd").grpowned?   #=> false

#owned? ⇒ `Boolean` (readonly)

Returns true if the effective user id of the process is the same as the owner of stat.

File.stat("testfile").owned?      #=> true
File.stat("/etc/passwd").owned?   #=> false

#pipe? ⇒ `Boolean` (readonly)

Returns true if the operating system supports pipes and stat is a pipe; false otherwise.

#readable? ⇒ `Boolean` (readonly)

Returns true if stat is readable by the effective user id of this process.

File.stat("testfile").readable?   #=> true

#readable_real? ⇒ `Boolean` (readonly)

Returns true if stat is readable by the real user id of this process.

File.stat("testfile").readable_real?   #=> true

#setgid? ⇒ `Boolean` (readonly)

Returns true if stat has the set-group-id permission bit set, false if it doesn't or if the operating system doesn't support this feature.

File.stat("/usr/sbin/lpc").setgid?   #=> true

#setuid? ⇒ `Boolean` (readonly)

Returns true if stat has the set-user-id permission bit set, false if it doesn't or if the operating system doesn't support this feature.

File.stat("/bin/su").setuid?   #=> true

#size ⇒ Fixnum (readonly)

Returns the size of stat in bytes.

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

#size ⇒ Integer (readonly)

Returns the size of stat in bytes.

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

#socket? ⇒ `Boolean` (readonly)

Returns true if stat is a socket, false if it isn't or if the operating system doesn't support this feature.

File.stat("testfile").socket?   #=> false

#sticky? ⇒ `Boolean` (readonly)

Returns true if stat has its sticky bit set, false if it doesn't or if the operating system doesn't support this feature.

File.stat("testfile").sticky?   #=> false

#symlink? ⇒ `Boolean` (readonly)

Returns true if stat is a symbolic link, false if it isn't or if the operating system doesn't support this feature. As File.stat automatically follows symbolic links, symlink? will always be false for an object returned by File.stat.

File.symlink("testfile", "alink")   #=> 0
File.stat("alink").symlink?         #=> false
File.lstat("alink").symlink?        #=> true

#world_readable? ⇒ `Boolean` (readonly)

If stat is readable by others, returns an integer representing the file permission bits of stat. Returns nil otherwise. The meaning of the bits is platform dependent; on Unix systems, see stat(2).

m = File.stat("/etc/passwd").world_readable?  #=> 420
sprintf("%o", m)                              #=> "644"

#world_writable? ⇒ `Boolean` (readonly)

If stat is writable by others, returns an integer representing the file permission bits of stat. Returns nil otherwise. The meaning of the bits is platform dependent; on Unix systems, see stat(2).

m = File.stat("/tmp").world_writable?         #=> 511
sprintf("%o", m)                              #=> "777"

#writable? ⇒ `Boolean` (readonly)

Returns true if stat is writable by the effective user id of this process.

File.stat("testfile").writable?   #=> true

#writable_real? ⇒ `Boolean` (readonly)

Returns true if stat is writable by the real user id of this process.

File.stat("testfile").writable_real?   #=> true

#zero? ⇒ `Boolean` (readonly)

Returns true if stat is a zero-length file; false otherwise.

File.stat("testfile").zero?   #=> false

Instance Method Details

#<=>(other_stat) ⇒ `1`, ...

Compares Stat objects by comparing their respective modification times.

nil is returned if other_stat is not a Stat object

f1 = File.new("f1", "w")
sleep 1
f2 = File.new("f2", "w")
f1.stat <=> f2.stat   #=> -1

#atime ⇒ Time

Returns the last access time for this file as an object of class ::Time.

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

#birthtime ⇒ Time

Returns the birth time for stat. If the platform doesn't have birthtime, returns ctime.

File.write("testfile", "foo")
sleep 10
File.write("testfile", "bar")
sleep 10
File.chmod(0644, "testfile")
sleep 10
File.read("testfile")
File.stat("testfile").birthtime   #=> 2014-02-24 11:19:17 +0900
File.stat("testfile").mtime       #=> 2014-02-24 11:19:27 +0900
File.stat("testfile").ctime       #=> 2014-02-24 11:19:37 +0900
File.stat("testfile").atime       #=> 2014-02-24 11:19:47 +0900

#blksize ⇒ Integer^?

Returns the native file system's block size. Will return nil on platforms that don't support this information.

File.stat("testfile").blksize   #=> 4096

#blocks ⇒ Integer^?

Returns the number of native file system blocks allocated for this file, or nil if the operating system doesn't support this feature.

File.stat("testfile").blocks   #=> 2

#ctime ⇒ Time

Returns the change time for stat (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.stat("testfile").ctime   #=> Wed Apr 09 08:53:14 CDT 2003

#dev ⇒ Fixnum

Returns an integer representing the device on which stat resides.

File.stat("testfile").dev   #=> 774

#dev_major ⇒ Fixnum

Returns the major part of File_Stat#dev or nil.

File.stat("/dev/fd1").dev_major   #=> 2
File.stat("/dev/tty").dev_major   #=> 5

#dev_minor ⇒ Fixnum

Returns the minor part of File_Stat#dev or nil.

File.stat("/dev/fd1").dev_minor   #=> 1
File.stat("/dev/tty").dev_minor   #=> 0

#ftype ⇒ String

Identifies the type of stat. The return string is one of: “file'', “directory'', “characterSpecial'', “blockSpecial'', “fifo'', “link'', “socket'', or “unknown''.

File.stat("/dev/tty").ftype   #=> "characterSpecial"

#gid ⇒ Fixnum

Returns the numeric group id of the owner of stat.

File.stat("testfile").gid   #=> 500

#ino ⇒ Fixnum

Returns the inode number for stat.

File.stat("testfile").ino   #=> 1083669

#inspect ⇒ String

Produce a nicely formatted description of stat.

File.stat("/etc/passwd").inspect
   #=> "#<File::Stat dev=0xe000005, ino=1078078, mode=0100644,
   #    nlink=1, uid=0, gid=0, rdev=0x0, size=1374, blksize=4096,
   #    blocks=8, atime=Wed Dec 10 10:16:12 CST 2003,
   #    mtime=Fri Sep 12 15:41:41 CDT 2003,
   #    ctime=Mon Oct 27 11:20:27 CST 2003,
   #    birthtime=Mon Aug 04 08:13:49 CDT 2003>"

#mode ⇒ Fixnum

Returns an integer representing the permission bits of stat. The meaning of the bits is platform dependent; on Unix systems, see stat(2).

File.chmod(0644, "testfile")   #=> 1
s = File.stat("testfile")
sprintf("%o", s.mode)          #=> "100644"

#mtime ⇒ Time

Returns the modification time of stat.

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

#nlink ⇒ Fixnum

Returns the number of hard links to stat.

File.stat("testfile").nlink             #=> 1
File.link("testfile", "testfile.bak")   #=> 0
File.stat("testfile").nlink             #=> 2

#rdev ⇒ Fixnum^?

Returns an integer representing the device type on which stat resides. Returns nil if the operating system doesn't support this feature.

File.stat("/dev/fd1").rdev   #=> 513
File.stat("/dev/tty").rdev   #=> 1280

#rdev_major ⇒ Fixnum

Returns the major part of File_Stat#rdev or nil.

File.stat("/dev/fd1").rdev_major   #=> 2
File.stat("/dev/tty").rdev_major   #=> 5

#rdev_minor ⇒ Fixnum

Returns the minor part of File_Stat#rdev or nil.

File.stat("/dev/fd1").rdev_minor   #=> 1
File.stat("/dev/tty").rdev_minor   #=> 0

#uid ⇒ Fixnum

Returns the numeric user id of the owner of stat.

File.stat("testfile").uid   #=> 501

Class: File::Stat

Overview

Class Method Summary

Instance Attribute Summary

Instance Method Summary

::Comparable - Included

Constructor Details

.new(file_name) ⇒ Stat

Instance Attribute Details

#blockdev? ⇒ Boolean (readonly)

#chardev? ⇒ Boolean (readonly)

#directory? ⇒ Boolean (readonly)

#executable? ⇒ Boolean (readonly)

#executable_real? ⇒ Boolean (readonly)

#file? ⇒ Boolean (readonly)

#grpowned? ⇒ Boolean (readonly)

#owned? ⇒ Boolean (readonly)

#pipe? ⇒ Boolean (readonly)

#readable? ⇒ Boolean (readonly)

#readable_real? ⇒ Boolean (readonly)

#setgid? ⇒ Boolean (readonly)

#setuid? ⇒ Boolean (readonly)