/ 
Sidef-26.01
River stage one • 1 direct dependent • 1 total dependent
⭐ Starred 115 GitHub stars
/ Sidef::Types::Glob::Stat

NAME

Sidef::Types::Glob::Stat - File status information interface

DESCRIPTION

This class implements an interface for retrieving and working with file system status information in Sidef. It provides access to file metadata such as permissions, ownership, timestamps, and size through a convenient object-oriented interface. The Stat class wraps Perl's stat() and lstat() functionality, making file system information easily accessible in Sidef programs.

SYNOPSIS

# Create a Stat object for a file
var stat = Stat('/path/to/file.txt')

# Check if file exists and get information
if (stat) {
    say "Size: #{stat.size} bytes"
    say "Modified: #{stat.mtime}"
    say "Owner UID: #{stat.uid}"
    say "Permissions: #{stat.mode}"
}

# Use lstat for symbolic links (doesn't follow the link)
var link_stat = Stat.lstat('/path/to/symlink')

# Get all stat information as an array
var info = stat.all
say "Device: #{info[0]}, Inode: #{info[1]}"

INHERITS

Inherits methods from:

* Sidef::Object::Object

METHODS

all

self.all

Returns an array containing all the file status information in the following order: device number, inode number, mode, number of hard links, user ID, group ID, device identifier (for special files), size in bytes, last access time, last modification time, last status change time, preferred block size, and number of blocks allocated.

This corresponds to the complete output of Perl's stat() function.

Example:

var stat = Stat('file.txt')
var fields = stat.all
# fields[0] = device, fields[1] = inode, etc.

atime

self.atime

Returns the last access time of the file as a Unix timestamp (seconds since epoch). This is the time when the file was last read or accessed.

Example:

var stat = Stat('file.txt')
say "Last accessed: #{stat.atime}"

blksize

self.blksize

Returns the preferred I/O block size for file system operations on this file, typically 4096 or 8192 bytes on modern systems. This is a hint to the system about optimal buffer sizes for reading and writing.

Example:

var stat = Stat('file.txt')
say "Preferred block size: #{stat.blksize} bytes"

blocks

self.blocks

Returns the actual number of file system blocks allocated for this file. This may be less than size/512 for sparse files or more due to file system overhead and metadata.

Example:

var stat = Stat('file.txt')
say "Blocks allocated: #{stat.blocks}"

ctime

self.ctime

Returns the last status change time of the file as a Unix timestamp. This is updated when the file's metadata (such as permissions, ownership, or hard link count) changes, not just when the content changes.

Note: On Unix systems, this is not the creation time. Windows systems may interpret this differently.

Example:

var stat = Stat('file.txt')
say "Status changed: #{stat.ctime}"

dev

self.dev

Returns the device number of the file system containing this file. This can be used to determine if two files are on the same file system.

Example:

var stat1 = Stat('file1.txt')
var stat2 = Stat('file2.txt')
if (stat1.dev == stat2.dev) {
    say "Files are on the same device"
}

gid

self.gid

Returns the numeric group ID of the file's owner. This identifies which group owns the file for permission purposes.

Example:

var stat = Stat('file.txt')
say "Group ID: #{stat.gid}"

ino

self.ino

Returns the inode number of the file. The inode is a unique identifier for the file within its file system. Multiple filenames (hard links) can refer to the same inode.

Example:

var stat = Stat('file.txt')
say "Inode: #{stat.ino}"

lstat

self.lstat(arg, obj)

Static method that creates a new Stat object using lstat() instead of stat(). Unlike stat(), lstat() does not follow symbolic links, so it returns information about the link itself rather than the target file.

Parameters:

  • arg - The file path to examine

  • obj - Optional parameter for internal use

Example:

var link_stat = Stat.lstat('/path/to/symlink')
say "Link size: #{link_stat.size}"

mode

self.mode

Returns the file mode, which includes both the file type and permissions as a numeric value. The mode is a bitmask that encodes file type (regular file, directory, symbolic link, etc.) and permission bits.

To extract permissions: mode & 0777 To check file type, use bitwise operations or File type checking methods.

Example:

var stat = Stat('file.txt')
var perms = (stat.mode & 0777)
say "Permissions: #{perms.as_oct}"

mtime

self.mtime

Returns the last modification time of the file as a Unix timestamp. This is updated whenever the file's content is changed.

Example:

var stat = Stat('file.txt')
say "Last modified: #{stat.mtime}"
self.nlink

Returns the number of hard links to the file. A newly created file has a link count of 1. Directories have at least 2 (the directory itself and the "." entry).

Example:

var stat = Stat('file.txt')
say "Number of hard links: #{stat.nlink}"

parent

self.parent

Returns the parent object or class information. This is primarily used internally for object hierarchy management.

rdev

self.rdev

Returns the device identifier for special files (character or block devices). For regular files, this value is undefined or zero. This is only meaningful for device files in /dev.

Example:

var stat = Stat('/dev/null')
if (stat.rdev) {
    say "Device identifier: #{stat.rdev}"
}

size

self.size

Returns the file size in bytes. For regular files, this is the actual size of the content. For directories, the meaning is system-dependent. For symbolic links (when using lstat), this is the length of the path string.

Example:

var stat = Stat('file.txt')
say "File size: #{stat.size} bytes"

stat

self.stat(arg, obj)

Static method that creates a new Stat object for the given file path. This follows symbolic links, returning information about the target file rather than the link itself.

Parameters:

  • arg - The file path to examine

  • obj - Optional parameter for internal use

Example:

var stat = Stat.stat('/path/to/file.txt')
say "Size: #{stat.size}"

uid

self.uid

Returns the numeric user ID of the file's owner. This identifies which user owns the file for permission purposes.

Example:

var stat = Stat('file.txt')
say "Owner UID: #{stat.uid}"

SEE ALSO

AUTHOR

Daniel "Trizen" Șuteu

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Sidef itself.