metadata
import std::fs::metadata; · source
Types
Metadata
type struct Metadata {
raw_mode: u32;
byte_size: u64;
mtime_sec: i64;
file_type(&this) -> FileType;
is_file(&this) -> boolean;
is_dir(&this) -> boolean;
is_symlink(&this) -> boolean;
len(&this) -> u64;
mode(&this) -> u32;
permissions(&this) -> u32;
modified_secs(&this) -> i64;
}A POD snapshot of one stat — freely copied, nothing to drop.
mode() is the full st_mode — type bits plus permission bits — and permissions() the permission bits alone. len() is meaningful for regular files; modified_secs() is seconds since the Unix epoch.
Properties
| Property | Type |
|---|---|
raw_mode | u32 |
byte_size | u64 |
mtime_sec | i64 |
Methods
file_type(&this) -> FileType;
is_file(&this) -> boolean;
is_dir(&this) -> boolean;
is_symlink(&this) -> boolean;
len(&this) -> u64;
len(&this) -> u64;Size in bytes (meaningful for regular files).
mode(&this) -> u32;
mode(&this) -> u32;Full st_mode (type bits + permission bits). On Windows the permission bits are synthesized from the read-only attribute (see the module header), not real ACLs.
permissions(&this) -> u32;
permissions(&this) -> u32;Unix permission bits (the low 12 bits of st_mode). Synthesized on Windows; see the module header.
modified_secs(&this) -> i64;
modified_secs(&this) -> i64;Last-modification time in whole seconds since the Unix epoch.
FileType
type enum FileType {
File;
Dir;
Symlink;
Other;
}
implement enum FileType {
static from_mode(mode: u32) -> FileType;
}The type bits of mode, decoded. Other covers everything that is not a regular file, a directory, or a symlink — sockets, pipes, devices, and an entry whose type the filesystem would not report.
Variants
| Variant |
|---|
File |
Dir |
Symlink |
Other |
Constructors
static from_mode(mode: u32) -> FileType;
static from_mode(mode: u32) -> FileType;Classify from a st_mode value (the S_IFMT bits).
Free Functions
Querying the filesystem
metadata(p) follows symlinks like stat(2); symlink_metadata(p) reports the link itself like lstat(2). The predicates exists, is_file, and is_dir return a bare boolean.
function metadata(p: Path) -> Result<Metadata, IoError>;
function metadata(p: Path) -> Result<Metadata, IoError>;Metadata for p, following symlinks (stat(2)).
function symlink_metadata(p: Path) -> Result<Metadata, IoError>;
function symlink_metadata(p: Path) -> Result<Metadata, IoError>;Metadata for p without following a final symlink. On POSIX this is lstat(2); on Windows it is the handle-free attribute query, which reports the reparse point itself (see attr_metadata).
function exists(p: Path) -> boolean;
function exists(p: Path) -> boolean;True if p exists (any type). Uses access(2) with F_OK (0). A non-existence answer is not distinguished from a permission error on an intermediate directory; use metadata if you need the reason.
function is_file(p: Path) -> boolean;
function is_file(p: Path) -> boolean;True if p exists and is a regular file.
function is_dir(p: Path) -> boolean;
function is_dir(p: Path) -> boolean;True if p exists and is a directory.
Platform notes
On POSIX this is stat(2) and lstat(2). struct stat is opaque across glibc versions, so it is read as a fixed-size buffer with the needed fields pulled out by their Linux x86-64 offsets.
On Windows it uses the Win32 file API rather than msvcrt's stat shims, which lay the struct out completely differently — decoding it with the POSIX offsets would return garbage. metadata opens an attribute-only handle so directories open too, and symlink_metadata reads the reparse point directly. Windows has no POSIX permission bits, so mode() is synthesized there: type bits from the file attributes plus 0644/0444 for files (by the read-only attribute) or 0755/0555 for directories. It is not a view of the real ACL. modified_secs converts the FILETIME to Unix seconds.
Constants
const STAT_OFF_MODE: u64 = 24;
const STAT_OFF_SIZE: u64 = 48;
const STAT_OFF_MTIME_SEC: u64 = 88;
const WFAD_OFF_ATTRS: u64 = 0;
const WFAD_OFF_WTIME: u64 = 20;
const WFAD_OFF_SIZE_HIGH: u64 = 28;
const WFAD_OFF_SIZE_LOW: u64 = 32;
const BHFI_OFF_ATTRS: u64 = 0;
const BHFI_OFF_WTIME: u64 = 20;
const BHFI_OFF_SIZE_HIGH: u64 = 32;
const BHFI_OFF_SIZE_LOW: u64 = 36;
const FILETIME_TO_UNIX_TICKS: u64 = 116444736000000000;
const FILETIME_TICKS_PER_SEC: u64 = 10000000;
const WIN_PERM_FILE_RW: u32 = 420;
const WIN_PERM_FILE_RO: u32 = 292;
const WIN_PERM_DIR_RW: u32 = 493;
const WIN_PERM_DIR_RO: u32 = 365;
const WIN_PERM_LINK: u32 = 511;type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.
type struct Name {
field: Type;
method(&this) -> Ret { ... }
}A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.
type struct Metadata {
raw_mode: u32;
byte_size: u64;
mtime_sec: i64;
}A snapshot of a path's metadata. POD (no owned resources), freely copied; no drop needed.
Metadata.raw_mode: u32Metadata.byte_size: u64Metadata.mtime_sec: i64Metadata::file_type(&this) -> FileType&this
mut &this
thisThe receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.
type enum FileType {
File;
Dir;
Symlink;
Other;
}The broad category of a filesystem entry.
std::fs::metadataMetadata::is_file(&this) -> booleanMetadata::is_dir(&this) -> booleanMetadata::is_symlink(&this) -> booleanMetadata::len(&this) -> u64Size in bytes (meaningful for regular files).
Metadata::mode(&this) -> u32Full st_mode (type bits + permission bits). On Windows the permission bits are synthesized from the read-only attribute (see the module header), not real ACLs.
Metadata::permissions(&this) -> u32Unix permission bits (the low 12 bits of st_mode). Synthesized on Windows; see the module header.
Metadata::modified_secs(&this) -> i64Last-modification time in whole seconds since the Unix epoch.
type enum Name {
Unit,
Payload(T),
Named { x: i32 },
}An algebraic data type. Variants may be bare or carry a tuple or struct payload, and a match on an enum must cover every variant. Name::Variant names a variant; methods are added with implement enum Name { ... }.
type enum FileType {
File;
Dir;
Symlink;
Other;
}The broad category of a filesystem entry.
FileType::FileFileType::DirFileType::SymlinkFileType::Otherimplement struct Name { ... }
implement trait Trait for Type { ... }
implement u64 { ... }Adds methods to a type outside its declaration. implement struct T (or enum, or a bare primitive) opens an inherent block; implement trait Tr for T supplies a trait's methods for one type. Resolution is at compile time - no dynamic dispatch.
implement enum Name { ... }Names the enum an inherent block extends - the only way to give an enum methods.
language referencestatic name(param: Type) -> Ret { ... }A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.
static FileType::from_mode(mode: u32) -> FileTypeClassify from a st_mode value (the S_IFMT bits).
(parameter) mode: u32const NAME: Type = value;At module level, a true compile-time constant, conventionally SCREAMING_SNAKE_CASE. (mut at module level declares mutable global state instead.)
const STAT_OFF_MODE: u64 = 24;const STAT_OFF_SIZE: u64 = 48;const STAT_OFF_MTIME_SEC: u64 = 88;const WFAD_OFF_ATTRS: u64 = 0;const WFAD_OFF_WTIME: u64 = 20;const WFAD_OFF_SIZE_HIGH: u64 = 28;const WFAD_OFF_SIZE_LOW: u64 = 32;const BHFI_OFF_ATTRS: u64 = 0;const BHFI_OFF_WTIME: u64 = 20;const BHFI_OFF_SIZE_HIGH: u64 = 32;const BHFI_OFF_SIZE_LOW: u64 = 36;const FILETIME_TO_UNIX_TICKS: u64 = 116444736000000000;const FILETIME_TICKS_PER_SEC: u64 = 10000000;const WIN_PERM_FILE_RW: u32 = 420;const WIN_PERM_FILE_RO: u32 = 292;const WIN_PERM_DIR_RW: u32 = 493;const WIN_PERM_DIR_RO: u32 = 365;const WIN_PERM_LINK: u32 = 511;import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).
namespace std::fs::metadata;File metadata: a typed Metadata snapshot of a path's type, size, and modification time.
Metadata::mode(&this) -> u32Full st_mode (type bits + permission bits). On Windows the permission bits are synthesized from the read-only attribute (see the module header), not real ACLs.
Metadata::permissions(&this) -> u32Unix permission bits (the low 12 bits of st_mode). Synthesized on Windows; see the module header.
Metadata::modified_secs(&this) -> i64Last-modification time in whole seconds since the Unix epoch.
std::fs::metadataMetadata.raw_mode: u32Metadata.byte_size: u64Metadata.mtime_sec: i64Metadata::file_type(&this) -> FileTypeMetadata::is_file(&this) -> booleanMetadata::is_dir(&this) -> booleanMetadata::is_symlink(&this) -> booleanFileType::OtherFileType::FileFileType::DirFileType::Symlinkstatic FileType::from_mode(mode: u32) -> FileTypeClassify from a st_mode value (the S_IFMT bits).
function metadata(p: Path) -> Result<Metadata, IoError>Metadata for p, following symlinks (stat(2)).
extern "C" function stat(path: u8*, buf: u8*) -> i32function symlink_metadata(p: Path) -> Result<Metadata, IoError>Metadata for p without following a final symlink. On POSIX this is lstat(2); on Windows it is the handle-free attribute query, which reports the reparse point itself (see attr_metadata).
extern "C" function lstat(path: u8*, buf: u8*) -> i32function exists(p: Path) -> booleanTrue if p exists (any type). Uses access(2) with F_OK (0). A non-existence answer is not distinguished from a permission error on an intermediate directory; use metadata if you need the reason.
function name<T>(param: Type) -> Ret { ... }Declares a function. Parameters are written name: Type and are never inferred; the return type follows -> and defaults to void. Declaration order does not matter: every signature is collected before any body is checked, so functions may call each other freely and recurse.
function metadata(p: Path) -> Result<Metadata, IoError>Metadata for p, following symlinks (stat(2)).
(parameter) p: Pathtype struct Path {
inner: Str;
}Path / PathBuf: filesystem paths as length-typed UTF-8.
std::fs::pathtype struct Metadata {
raw_mode: u32;
byte_size: u64;
mtime_sec: i64;
}A snapshot of a path's metadata. POD (no owned resources), freely copied; no drop needed.
type struct IoError {
kind: IoErrorKind;
os_code: i32;
}function symlink_metadata(p: Path) -> Result<Metadata, IoError>Metadata for p without following a final symlink. On POSIX this is lstat(2); on Windows it is the handle-free attribute query, which reports the reparse point itself (see attr_metadata).
function attr_metadata(p: Path) -> Result<Metadata, IoError>Handle-free attribute query (GetFileAttributesExA). Reports the final path component ITSELF: a symlink/junction shows up as FileType::Symlink with the reparse point's own size/mtime, which is exactly lstat(2) semantics. Also the fallback for metadata when a share-mode conflict blocks opening a handle.
function exists(p: Path) -> booleanTrue if p exists (any type). Uses access(2) with F_OK (0). A non-existence answer is not distinguished from a permission error on an intermediate directory; use metadata if you need the reason.
extern "C" function access(path: u8*, mode: i32) -> i32function is_file(p: Path) -> booleanTrue if p exists and is a regular file.
function is_dir(p: Path) -> booleanTrue if p exists and is a directory.
type struct FILETIME {
dwLowDateTime: u32;
dwHighDateTime: u32;
}100-nanosecond intervals since 1601-01-01 UTC.
std::sys::syscall