Class: File::Stat

Inherits:
Object show all
Includes:
Comparable
Defined in:
file.c,
file.c

Overview

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

Instance Method Summary collapse

Methods included from Comparable

#<, #<=, #==, #>, #>=, #between?

Constructor Details

#File::Stat.new(file_name) ⇒ Object

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



3664
3665
3666
 
# File 'file.c', line 3664

static VALUE
rb_stat_init(obj, fname)
VALUE obj, fname;

Instance Method Details

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

Compares File::Stat objects by comparing their respective modification times.

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

Returns:

  • (-1, 0, 1) 


197
198
199
 
# File 'file.c', line 197

static VALUE
rb_stat_cmp(self, other)
VALUE self, other;

#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

Returns:



533
534
535
 
# File 'file.c', line 533

static VALUE
rb_stat_atime(self)
VALUE self;

#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

Returns:



488
489
490
 
# File 'file.c', line 488

static VALUE
rb_stat_blksize(self)
VALUE self;

#blockdev? ⇒ Boolean

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

Returns:

  • (Boolean) 


3834
3835
3836
 
# File 'file.c', line 3834

static VALUE
rb_stat_b(obj)
VALUE obj;

#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

Returns:



510
511
512
 
# File 'file.c', line 510

static VALUE
rb_stat_blocks(self)
VALUE self;

#chardev? ⇒ Boolean

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

Returns:

  • (Boolean) 


3857
3858
3859
 
# File 'file.c', line 3857

static VALUE
rb_stat_c(obj)
VALUE obj;

#ctime ⇒ aTime

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

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

Returns:

  • (aTime) 


569
570
571
 
# File 'file.c', line 569

static VALUE
rb_stat_ctime(self)
VALUE self;

#dev ⇒ Fixnum

Returns an integer representing the device on which stat resides.

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

Returns:



238
239
240
 
# File 'file.c', line 238

static VALUE
rb_stat_dev(self)
VALUE self;

#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

Returns:



256
257
258
 
# File 'file.c', line 256

static VALUE
rb_stat_dev_major(self)
VALUE self;

#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

Returns:



279
280
281
 
# File 'file.c', line 279

static VALUE
rb_stat_dev_minor(self)
VALUE self;

#directory? ⇒ Boolean

Returns true if stat is a directory, false otherwise.

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

Returns:

  • (Boolean) 


3744
3745
3746
 
# File 'file.c', line 3744

static VALUE
rb_stat_d(obj)
VALUE obj;

#executable? ⇒ Boolean

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

Returns:

  • (Boolean) 


4067
4068
4069
 
# File 'file.c', line 4067

static VALUE
rb_stat_x(obj)
VALUE obj;

#executable_real? ⇒ Boolean

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

Returns:

  • (Boolean) 


4101
4102
4103
 
# File 'file.c', line 4101

static VALUE
rb_stat_X(obj)
VALUE obj;

#file? ⇒ Boolean

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

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

Returns:

  • (Boolean) 


4137
4138
4139
 
# File 'file.c', line 4137

static VALUE
rb_stat_f(obj)
VALUE obj;

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

Returns:



3726
3727
3728
 
# File 'file.c', line 3726

static VALUE
rb_stat_ftype(obj)
VALUE obj;

#gid ⇒ Fixnum

Returns the numeric group id of the owner of stat.

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

Returns:



384
385
386
 
# File 'file.c', line 384

static VALUE
rb_stat_gid(self)
VALUE self;

#grpowned? ⇒ Boolean

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

Returns:

  • (Boolean) 


3906
3907
3908
 
# File 'file.c', line 3906

static VALUE
rb_stat_grpowned(obj)
VALUE obj;

#initialize_copy ⇒ Object

:nodoc:



3687
3688
3689
 
# File 'file.c', line 3687

static VALUE
rb_stat_init_copy(copy, orig)
VALUE copy, orig;

#ino ⇒ Fixnum

Returns the inode number for stat.

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

Returns:



302
303
304
 
# File 'file.c', line 302

static VALUE
rb_stat_ino(self)
VALUE self;

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

Returns:



590
591
592
 
# File 'file.c', line 590

static VALUE
rb_stat_inspect(self)
VALUE self;

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

Returns:



326
327
328
 
# File 'file.c', line 326

static VALUE
rb_stat_mode(self)
VALUE self;

#mtime ⇒ aTime

Returns the modification time of stat.

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

Returns:

  • (aTime) 


550
551
552
 
# File 'file.c', line 550

static VALUE
rb_stat_mtime(self)
VALUE self;

#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

Returns:



349
350
351
 
# File 'file.c', line 349

static VALUE
rb_stat_nlink(self)
VALUE self;

#owned? ⇒ Boolean

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

Returns:

  • (Boolean) 


3878
3879
3880
 
# File 'file.c', line 3878

static VALUE
rb_stat_owned(obj)
VALUE obj;

#pipe? ⇒ Boolean

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

Returns:

  • (Boolean) 


3760
3761
3762
 
# File 'file.c', line 3760

static VALUE
rb_stat_p(obj)
VALUE obj;

#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

Returns:



404
405
406
 
# File 'file.c', line 404

static VALUE
rb_stat_rdev(self)
VALUE self;

#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

Returns:



426
427
428
 
# File 'file.c', line 426

static VALUE
rb_stat_rdev_major(self)
VALUE self;

#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

Returns:



449
450
451
 
# File 'file.c', line 449

static VALUE
rb_stat_rdev_minor(self)
VALUE self;

#readable? ⇒ Boolean

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

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

Returns:

  • (Boolean) 


3927
3928
3929
 
# File 'file.c', line 3927

static VALUE
rb_stat_r(obj)
VALUE obj;

#readable_real? ⇒ Boolean

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

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

Returns:

  • (Boolean) 


3963
3964
3965
 
# File 'file.c', line 3963

static VALUE
rb_stat_R(obj)
VALUE obj;

#setgid? ⇒ Boolean

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

Returns:

  • (Boolean) 


4218
4219
4220
 
# File 'file.c', line 4218

static VALUE
rb_stat_sgid(obj)
VALUE obj;

#setuid? ⇒ Boolean

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

Returns:

  • (Boolean) 


4196
4197
4198
 
# File 'file.c', line 4196

static VALUE
rb_stat_suid(obj)
VALUE obj;

#size ⇒ Fixnum

Returns the size of stat in bytes.

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

Returns:



470
471
472
 
# File 'file.c', line 470

static VALUE
rb_stat_size(self)
VALUE self;

#size ⇒ Integer

Returns the size of stat in bytes.

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

Returns:



4175
4176
4177
 
# File 'file.c', line 4175

static VALUE
rb_stat_s(obj)
VALUE obj;

#socket? ⇒ Boolean

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

Returns:

  • (Boolean) 


3810
3811
3812
 
# File 'file.c', line 3810

static VALUE
rb_stat_S(obj)
VALUE obj;

#sticky? ⇒ Boolean

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

Returns:

  • (Boolean) 


4240
4241
4242
 
# File 'file.c', line 4240

static VALUE
rb_stat_sticky(obj)
VALUE obj;

#symlink? ⇒ Boolean

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

Returns:

  • (Boolean) 


3788
3789
3790
 
# File 'file.c', line 3788

static VALUE
rb_stat_l(obj)
VALUE obj;

#uid ⇒ Fixnum

Returns the numeric user id of the owner of stat.

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

Returns:



367
368
369
 
# File 'file.c', line 367

static VALUE
rb_stat_uid(self)
VALUE self;

#writable? ⇒ Boolean

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

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

Returns:

  • (Boolean) 


3997
3998
3999
 
# File 'file.c', line 3997

static VALUE
rb_stat_w(obj)
VALUE obj;

#writable_real? ⇒ Boolean

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

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

Returns:

  • (Boolean) 


4031
4032
4033
 
# File 'file.c', line 4031

static VALUE
rb_stat_W(obj)
VALUE obj;

#zero? ⇒ Boolean

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

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

Returns:

  • (Boolean) 


4156
4157
4158
 
# File 'file.c', line 4156

static VALUE
rb_stat_z(obj)
VALUE obj;