Module sys/statx

Whether this is a regular file — S_ISREG, i.e. mode & S_IFMT == S_IFREG. Sockets, FIFOs and devices are all false.

Whether this is a directory — S_ISDIR.

Whether this is a symbolic link — S_ISLNK.

This can only ever be true if the stat did NOT follow the link, i.e. the call was made with AT_SYMLINK_NOFOLLOW. A plain statx resolves the link and reports its target, so it answers false for a symlink.

Size in bytes. For a regular file the file length; for a SYMLINK stat'ed without following, the length of the target path — which is how you size a readlink buffer exactly. For a directory an unspecified filesystem-internal number, not an entry count.

The raw st_mode word: file-type bits AND permission bits together. Mask with S_IFMT for the type (the is_* predicates above do it for you) or with 0o7777 for the permissions before passing it to std/sys/perm's fchmod. On Windows the CRT synthesizes this from the file attributes, so the group and other bits mirror the owner's rather than describing an ACL.

Owning user id. 0 on Windows, which has no numeric uid — the CRT's _stat64 zeroes the field rather than mapping a SID.

Owning group id. 0 on Windows, for the same reason as uid.

Inode number — unique per filesystem, so the pair (device, inode) identifies a file and is how you detect two paths that are hard links to the same thing. On Windows the runtime supplies the NTFS file index from GetFileInformationByHandle, which plays the same role.

Number of hard links. A directory counts 2 plus its subdirectories on most POSIX filesystems; a file with no other names counts 1, and 0 means the file has been unlinked while this descriptor kept it alive.

Modification time, whole seconds since the Unix epoch — when the CONTENTS last changed. This is the timestamp to compare for "is my build output stale".

Nanoseconds part of the modification time, 0..999_999_999. Filesystem resolution varies — HFS+ and many older filesystems store whole seconds, so a 0 here does not mean the write landed exactly on a second boundary.

Access time, whole seconds since the Unix epoch. Often stale on purpose: most systems mount with relatime or noatime, so this may not have been updated by the last read.

Nanoseconds part of the access time, 0..999_999_999.

Inode CHANGE time in whole seconds — when the metadata last changed (a chmod, a rename, a link count change), not when the file was created. POSIX has no creation time in struct stat, which is why there is no btime accessor here.

Windows differs: the CRT's st_ctime is the file's CREATION time, so this reads as a birth time there. Do not use it to detect a metadata change portably.

Nanoseconds part of the change time, 0..999_999_999. On Windows the runtime copies the modification time's sub-second part here, since the creation time's own is tracked separately — so it does not belong to the seconds value ctime_sec returns.