FileMetadata

Owns an availability-aware snapshot of an opened filesystem object. None means the provider did not supply that field; a present zero remains an observed value. Times use UTC wall time, not monotonic deadlines. The snapshot allocates nothing and retains no file/path lease. Concurrent changes may make fields stale immediately; sampling is not promised atomic. Public edits affect only this detached value. Shared mutation requires synchronization. This example uses the Linux filesystem adapter and assumes no native mode values, timestamp ordering or birth-time support.

Module std.fs

import std.fs;

Public declaration contracts and authored examples. A page can document several related symbols. Implementation bodies are excluded.

FileMetadata

pub struct FileMetadata

Example

module example.file_metadata;
from std.fs import File, Path, PosixAccess, PosixFileMode, PosixFileMetadata;
fn Main() -> i32 {
    var PathOwner = {
        // Scoped writable carriers end immediately after explicit payload transfer.
        var PathOwnerCreation = Path.TryCreate("/dev/null");
        switch PathOwnerCreation {
            case .Ok { Value = Value: mut Path& } => break move(Value);
            case .Err => return 1;
        }
    };
    var Opened = {
        var OpenedCreation = File.TryOpen(PathOwner.View);
        switch OpenedCreation {
            case .Ok { Value = Value: mut File& } => break move(Value);
            case .Err => return 2;
        }
    };
    let Snapshot = switch Opened.ReadMetadata() { case .Ok { Value = Value } => break Value; case .Err => return 3; };
    if Opened.Close() is .Err { Error = _ } { return 4; }
    // No lease remains: all observed values are independent of the closed file.
    if Snapshot.Kind != .CharacterDevice { return 5; }
    if Snapshot.ByteLength is .Some { Value = _ } { return 6; }
    if Snapshot.AllocatedByteLength is .Some { Value = _ } { return 7; }
    let Links = switch Snapshot.HardLinkCount { case .Some { Value = Value } => break Value; case .None => return 8; };
    if Links == 0 { return 9; }
    let Modified = switch Snapshot.Modified { case .Some { Value = Value } => break Value; case .None => return 10; };
    let Accessed = switch Snapshot.Accessed { case .Some { Value = Value } => break Value; case .None => return 11; };
    let Changed = switch Snapshot.Changed { case .Some { Value = Value } => break Value; case .None => return 12; };
    // Birth time may be missing; neither Changed nor epoch zero substitutes for it.
    switch Snapshot.Created { case .Some { Value = Created } => { let BirthTicks = Created.UnixTime.Count; } case .None => {} }
    let Posix = switch Snapshot.Posix { case .Some { Value = Value } => break Value; case .None => return 13; };
    // Reconstruct detached mode/identity values without changing native permissions.
    let Owner = PosixAccess { CanRead = Posix.Mode.Owner.CanRead, CanWrite = Posix.Mode.Owner.CanWrite, CanExecute = Posix.Mode.Owner.CanExecute, };
    let Mode = PosixFileMode { Owner = Owner, Group = Posix.Mode.Group, Other = Posix.Mode.Other, SetUserId = Posix.Mode.SetUserId, SetGroupId = Posix.Mode.SetGroupId, Sticky = Posix.Mode.Sticky, };
    let Identity = PosixFileMetadata { Device = Posix.Device, Inode = Posix.Inode, UserId = Posix.UserId, GroupId = Posix.GroupId, Mode = Mode, };
    if Identity.Device != Posix.Device || Identity.Inode != Posix.Inode || Identity.UserId != Posix.UserId || Identity.GroupId != Posix.GroupId { return 14; }
    if Identity.Mode.Group.CanRead != Posix.Mode.Group.CanRead || Identity.Mode.Group.CanWrite != Posix.Mode.Group.CanWrite || Identity.Mode.Group.CanExecute != Posix.Mode.Group.CanExecute { return 15; }
    if Identity.Mode.Other.CanRead != Posix.Mode.Other.CanRead || Identity.Mode.Other.CanWrite != Posix.Mode.Other.CanWrite || Identity.Mode.Other.CanExecute != Posix.Mode.Other.CanExecute { return 16; }
    if Identity.Mode.Owner.CanRead != Owner.CanRead || Identity.Mode.Owner.CanWrite != Owner.CanWrite || Identity.Mode.Owner.CanExecute != Owner.CanExecute { return 17; }
    if Identity.Mode.SetUserId != Posix.Mode.SetUserId || Identity.Mode.SetGroupId != Posix.Mode.SetGroupId || Identity.Mode.Sticky != Posix.Mode.Sticky { return 18; }
    let ContentTicks = Modified.UnixTime.Count;
    let AccessTicks = Accessed.UnixTime.Count;
    let StatusTicks = Changed.UnixTime.Count;
    return 0;
}

FileMetadata.Kind

pub Kind: FileKind;

Reported semantic object kind.

FileMetadata.ByteLength

pub ByteLength: u64?;

Logical extent in bytes when meaningful and supplied.

FileMetadata.AllocatedByteLength

pub AllocatedByteLength: u64?;

Reported storage allocation in bytes, not logical length.

FileMetadata.HardLinkCount

pub HardLinkCount: u64?;

Reported number of native hard links.

FileMetadata.Created

pub Created: Timestamp?;

Creation/birth time when supplied; never inferred from Changed.

FileMetadata.Modified

pub Modified: Timestamp?;

Content modification time in UTC.

FileMetadata.Accessed

pub Accessed: Timestamp?;

Last access time; provider updates may be delayed or disabled.

FileMetadata.Changed

pub Changed: Timestamp?;

Metadata/status change time, not creation time.

FileMetadata.Posix

pub Posix: PosixFileMetadata?;

Explicit POSIX identity/ownership/mode when supplied.