Module sys/time
File timestamp updates (utime/futime/lutime) — the raw syscall
boundary.
Three wrappers over utimensat(2)/futimens(2): by path, by descriptor,
and by path without following a symlink. All are synchronous on every
platform, so they return i32 directly rather than an IoFuture. No
public std module sets timestamps yet (std/fs/metadata only reads
them); tests/sys/time.test.yo is the only caller in this tree.
Times are (seconds, nanoseconds) pairs, both for atime and mtime.
Stability
unstable — the UTIME_NOW / UTIME_OMIT sentinels are the open question.
POSIX encodes "use the current time" and "leave this one alone" as magic
tv_nsec values (0x3fffffff and 0x3ffffffe), which the Linux and
macOS paths forward to the kernel — but the Windows implementation folds
nsec arithmetically into a FILETIME, so those sentinels become
nonsense timestamps instead of being honoured. Freezing needs that
divergence closed (recognize the sentinels in the Windows shim) and
probably a Yo-level Option-shaped API where "omit" is .None rather
than a reserved integer.
Functions
Set the access and modification times of the file at path, FOLLOWING a
symlink — POSIX utimensat(AT_FDCWD, path, times, 0). Returns 0 on
success, a negative errno on failure (-EPERM when you own neither the
file nor CAP_FOWNER).
atime_nsec and mtime_nsec are 0..999_999_999, or one of the POSIX
sentinels UTIME_NOW (0x3fffffff) / UTIME_OMIT (0x3ffffffe) — which
are honoured on Linux and macOS only; see the module's Stability note for
Windows. Note there is no way to set the ctime: POSIX updates it as a side
effect of this call.
On Windows the runtime opens the path with FILE_WRITE_ATTRIBUTES and
FILE_FLAG_BACKUP_SEMANTICS (so directories work) and calls SetFileTime.
Parameters
| Name | Type | Notes |
|---|---|---|
path | *u8 | |
atime_sec | i64 | |
atime_nsec | i64 | |
mtime_sec | i64 | |
mtime_nsec | i64 |
Returns: i32
Set the access and modification times of an OPEN descriptor — POSIX
futimens(2). Returns 0 on success, a negative errno on failure.
This is the form to use when the path may have been renamed or unlinked
since the open, for the same reason std/sys/file's fstat exists. Same
nanosecond and sentinel rules as utime.
Windows has no futimens: the runtime recovers the path from the handle
with GetFinalPathNameByHandleW, reopens it for attribute writes and
calls SetFileTime — so unlike POSIX it does need the file to still be
reachable by name.
Parameters
| Name | Type | Notes |
|---|---|---|
fd | i32 | |
atime_sec | i64 | |
atime_nsec | i64 | |
mtime_sec | i64 | |
mtime_nsec | i64 |
Returns: i32
Set the times of the SYMLINK itself rather than its target —
utimensat(..., AT_SYMLINK_NOFOLLOW). Returns 0 on success, a negative
errno on failure. On a path that is not a symlink it behaves exactly like
utime. Same nanosecond and sentinel rules.
Parameters
| Name | Type | Notes |
|---|---|---|
path | *u8 | |
atime_sec | i64 | |
atime_nsec | i64 | |
mtime_sec | i64 | |
mtime_nsec | i64 |
Returns: i32