Module fs/metadata

Size in bytes — Rust's Metadata::len. For a directory this is the filesystem's own bookkeeping size, not the number of entries; for a symlink read through symlink_metadata it is the length of the target string.

The raw st_mode word — permission bits AND the file-type bits (S_IFMT) in one integer, so mask before comparing. Prefer is_file/is_dir/is_symlink for the type and is_readonly for writability. On Windows the CRT synthesises it from the file attributes and the filename extension, so a real POSIX mode is only available on Linux, macOS and wasm.

True for a regular file — Rust's Metadata::is_file. Through metadata (which follows symlinks) a link to a file answers true; through symlink_metadata it does not.

True for a directory — Rust's Metadata::is_dir.

True for a symbolic link — Rust's Metadata::is_symlink. This can only ever be true for metadata obtained through symlink_metadata, because metadata follows the final link and reports the target.

Last content-modification time as a wall-clock SystemTime — Rust's Metadata::modified. Full nanosecond resolution: statx reports mtime_nsec and it was being discarded by the seconds-only accessor below, which is why this is the one to reach for.

A filesystem timestamp and SystemTime.now()'s CLOCK_REALTIME are DIFFERENT CLOCK DOMAINS, so an mtime may sit a hair ahead of a now() read afterwards (Emscripten's MEMFS measured 64 ns ahead). Nothing promises the ordering — only that the two readings are close — which is why SystemTime.duration_since hands back a Result rather than clamping to zero.

Last access time as a SystemTime — Rust's Metadata::accessed. Read this expecting it to be stale: relatime/noatime mounts are the default on Linux, so atime often only moves when the file is also written.

POSIX ctime — the last INODE change — as a SystemTime. NOT a creation time; see status_changed_time below for why, and for what Windows reports here instead.

Last modification time in WHOLE SECONDS since the Unix epoch.

Kept for callers that want the raw field, but modified() above is the one to use: it carries the nanoseconds this drops, and a SystemTime can be compared and subtracted without every call site re-deriving what the integer means. The two agree by construction — modified_time() == modified().as_unix_secs() is asserted by tests/fs/metadata.test.yo.

Last access time in whole seconds since the Unix epoch. See accessed() for the nanosecond-carrying form and the staleness caveat.

Status change time in whole seconds since the Unix epoch — POSIX ctime.

This is NOT the file's creation time: ctime moves whenever the inode's metadata changes (chmod, rename, link count), so it can be LATER than the modification time. A real creation time (statx btime / st_birthtime / Windows CreationTime) is not exposed yet — Statx requests STATX_BASIC_STATS (0x7ff), which does not include STATX_BTIME (0x800), and there is no btime_sec() accessor. See plans/archive/STD_API_AUDIT.md §5.

Windows has no ctime at all: the CRT's st_ctime is the file's CREATION time (and only on NTFS), so on that platform this answers a different question from the POSIX one — treat it as "some timestamp about the file" rather than as a change marker.

True when NO write bit is set for owner, group or other — Rust's Permissions::readonly. This is a question about the mode bits, not about whether THIS process can write: root ignores them, and an ACL, a read-only mount or an immutable flag can deny a write that the bits permit. Attempt the write if the answer has to be authoritative.

Owning user id. POSIX only — on Windows the CRT's _wstat64 leaves st_uid at 0, so this reports 0 for every file there rather than mapping the security descriptor's owner SID.

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

Inode number — with the device id, the filesystem's identity for this file, which is how two paths are recognised as the same file. On Windows this is the NTFS file index from GetFileInformationByHandle, which serves the same purpose but is 0 when that call fails (no open permission, or a filesystem that has no index). The device id itself is not exposed yet, so an identity comparison is only sound within one filesystem.

Number of hard links to this inode — 1 for an ordinary file, ≥2 once hard_link has been used, and ≥2 for a directory (. and its parent's entry). On Windows it comes from GetFileInformationByHandle, so it is the real NTFS link count when that succeeds and the CRT's constant 1 otherwise.

Release the resources self owns — a file descriptor, a socket, a lock, a buffer the allocator handed out. Called automatically when the last reference to the value goes away, so an implementor never calls it directly and must tolerate being the only one who ever does.

It must be safe to run exactly once: the runtime calls it at refcount zero, and a type that also exposes an explicit close/release is responsible for making the second call a no-op.