Set a named entry's create / modify / access timestamps (ra8_fs_utime()). More...

#include <stddef.h>
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_fs.h"
#include "ra8_fs_fat_internal.h"
#include "ra8_fs_meta.h"

Include dependency graph for ra8_fs_fat_utime.c:

Functions
static ra8_err_t	internal_utime_fat (const ra8_fs_mount_t m, const char path, const ra8_fs_datetime_t create, const ra8_fs_datetime_t modify, const ra8_fs_datetime_t *access)
	Set chosen timestamps on a FAT12/16/32 entry.
static ra8_err_t	internal_utime_exfat (const ra8_fs_mount_t m, const char path, const ra8_fs_datetime_t create, const ra8_fs_datetime_t modify, const ra8_fs_datetime_t *access)
	Set chosen timestamps on an exFAT root-level entry.
static ra8_err_t	internal_utime_locked (const ra8_fs_mount_t handle, const char path, const ra8_fs_datetime_t create, const ra8_fs_datetime_t modify, const ra8_fs_datetime_t *access)
	Set entry timestamps – the guarded body of ra8_fs_utime().
ra8_err_t	ra8_fs_utime (const ra8_fs_mount_t handle, const char path, const ra8_fs_datetime_t create, const ra8_fs_datetime_t modify, const ra8_fs_datetime_t *access)
	Set a named entry's create / modify / access timestamps.

Detailed Description

Set a named entry's create / modify / access timestamps (ra8_fs_utime()).

The touch / utime primitive: unlike the close-time and write-time stamps, which come from the injected clock (ra8_fs_set_clock()), these are caller-chosen, so a backup or sync restore can put a file's ORIGINAL create / modify time back instead of the moment of the restore – which is what every "newest wins" incremental heuristic keys on.

FAT stores a create date+time, a modify date+time and an access DATE only (there is no access time). exFAT stores all three as full timestamps plus the 10 ms increments and UtcOffset bytes, and its File-entry SetChecksum covers the timestamp fields, so it is recomputed over the whole entry set after the patch. The actual field packing lives in ra8_fs_fat_time.c (priv_fat_entry_set_times / priv_exfat_file_set_times); this file only resolves the entry, applies the patch, and (on exFAT) fixes the checksum.

References (every shorthand citation in this file):

"exFAT spec" = Microsoft Corp., "exFAT file system specification", revision 1.00, section 6 "Directory Structure".

NASA Power-of-Ten compliance:

Rule 2: the exFAT re-read loop is bounded by the set's entry count, itself <= k_exfat_set_max_entries.
Rule 3: zero malloc; the entry-set buffer is a bounded stack array.
Rule 7: every backend and resolver call is checked.

Copyright: Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Since: 0.1.0

Definition in file ra8_fs_fat_utime.c.

Function Documentation

◆ internal_utime_exfat()

ra8_err_t internal_utime_exfat	(	const ra8_fs_mount_t *	m,
		const char *	path,
		const ra8_fs_datetime_t *	create,
		const ra8_fs_datetime_t *	modify,
		const ra8_fs_datetime_t *	access )

static

Set chosen timestamps on an exFAT root-level entry.

Locates the file's directory-entry set, re-reads every entry back into a buffer (the SetChecksum covers them all), patches the File entry's timestamps in place, recomputes the SetChecksum over the whole set, and writes the File entry back – the only entry whose bytes changed. Root-directory namespace only, matching every other exFAT operation here.

Parameters

[in]	m	Mounted exFAT volume.
[in]	path	Root-level name.
[in]	create	Create stamp, or NULL to leave it unchanged.
[in]	modify	Modify stamp, or NULL to leave it unchanged.
[in]	access	Access stamp, or NULL to leave it unchanged.

Returns: Error code.

Return values

k_ra8_ok	Requested stamps written.
k_ra8_err_not_found	No such name in the root directory.
k_ra8_err_no_mem	The entry set is longer than the driver rewrites.
k_ra8_err_*	Backend read/write failure.

Precondition: m and path are non-NULL; m->type is exFAT.; The mount is in use.

Postcondition: On success each non-NULL reading's fields hold that instant and the set's SetChecksum is valid.; On failure the set is unchanged.

Note: Bounded loop (NASA Rule 2): the set's entry count, <= 19.; Not thread-safe; callers serialise filesystem operations.

Since: 0.1.0

Definition at line 145 of file ra8_fs_fat_utime.c.

References exfat_setpos_t::cluster, exfat_setpos_t::index, k_exfat_entry_bytes, k_exfat_off_file_csum, k_exfat_set_max_entries, k_ra8_ok, priv_exfat_dir_root(), priv_exfat_file_set_times(), priv_exfat_find_set(), priv_exfat_next_entry(), priv_exfat_set_checksum(), priv_exfat_write_dir_set(), and priv_wr16().

◆ internal_utime_fat()

ra8_err_t internal_utime_fat	(	const ra8_fs_mount_t *	m,
		const char *	path,
		const ra8_fs_datetime_t *	create,
		const ra8_fs_datetime_t *	modify,
		const ra8_fs_datetime_t *	access )

static

Set chosen timestamps on a FAT12/16/32 entry.

Resolves path to its directory entry the way ra8_fs_stat() does – parent walk, then packed 8.3 lookup with a VFAT long-name fallback – reads the sector holding the entry, applies the requested timestamp fields in place, and writes the sector back. A directory entry is stamped as readily as a file's; only the volume root (which has no entry) cannot be, and the caller has already rejected it.

Parameters

[in]	m	Mounted FAT volume.
[in]	path	Path to the entry (never the volume root here).
[in]	create	Create stamp, or NULL to leave it unchanged.
[in]	modify	Modify stamp, or NULL to leave it unchanged.
[in]	access	Access stamp, or NULL to leave it unchanged.

Returns: Error code.

Return values

k_ra8_ok	Requested stamps written.
k_ra8_err_invalid_arg	A path component is not a valid 8.3 name.
k_ra8_err_not_found	Nothing at `path`.
k_ra8_err_*	Backend read/write failure.

Precondition: m and path are non-NULL; m->type is not exFAT.; The mount is in use.

Postcondition: On success each non-NULL reading's fields hold that instant.; On failure the entry is unchanged.

Note: Not thread-safe; callers serialise filesystem operations.

Since: 0.1.0

Definition at line 75 of file ra8_fs_fat_utime.c.

References k_max_8_3_name, k_ra8_err_not_found, k_ra8_fs_dir_entry_bytes, k_ra8_ok, priv_dir_find(), priv_dir_find_long(), priv_fat_entry_set_times(), priv_path_to_83(), priv_read_sector(), priv_resolve_parent(), priv_sec_walk(), and priv_write_sector().

Referenced by internal_utime_locked().

◆ internal_utime_locked()

ra8_err_t internal_utime_locked	(	const ra8_fs_mount_t *	handle,
		const char *	path,
		const ra8_fs_datetime_t *	create,
		const ra8_fs_datetime_t *	modify,
		const ra8_fs_datetime_t *	access )

static

Set entry timestamps – the guarded body of ra8_fs_utime().

Validates the arguments, refuses the volume root (no entry to stamp), and dispatches to the FAT or exFAT patcher. All-NULL readings are a no-op success – a utime that changes nothing changed nothing. The public ra8_fs_utime brackets this with the library lock; the full contract is documented there.

Parameters

[in]	handle	Mount handle.
[in]	path	Path to the entry.
[in]	create	Create stamp, or NULL.
[in]	modify	Modify stamp, or NULL.
[in]	access	Access stamp, or NULL.

Returns: Error code.

Return values

k_ra8_ok	Requested stamps written (or none requested).
k_ra8_err_null_ptr	`handle` or `path` is NULL.
k_ra8_err_invalid_state	Mount is not in use.
k_ra8_err_invalid_arg	`path` names the volume root, or is not a valid name for this filesystem.
k_ra8_err_not_found	Nothing at `path`.
k_ra8_err_*	Backend read/write failure.

Precondition: The library lock is held (or none is installed).; handle and path are non-NULL.

Postcondition: On success the requested stamps hold their (clamped) instants.; On failure the entry is unchanged.

Note: Never call this from outside ra8_fs; it is the unlocked half.

Since: 0.1.0

Definition at line 224 of file ra8_fs_fat_utime.c.

References internal_utime_fat(), internal_utime_locked(), k_ra8_err_invalid_arg, k_ra8_err_null_ptr, and k_ra8_fs_type_exfat.

Referenced by internal_utime_locked(), and ra8_fs_utime().

◆ ra8_fs_utime()

ra8_err_t ra8_fs_utime	(	const ra8_fs_mount_t *	handle,
		const char *	path,
		const ra8_fs_datetime_t *	create,
		const ra8_fs_datetime_t *	modify,
		const ra8_fs_datetime_t *	access )

nodiscard

Set a named entry's create / modify / access timestamps.

The touch / utime primitive: each non-NULL reading overwrites that entry's corresponding timestamp fields, each NULL one leaves them unchanged. Unlike the close-time and write-time stamps – which come from the injected clock (see ra8_fs_set_clock()) – these are caller-chosen, so a backup or sync restore can put a file's ORIGINAL create / modify time back instead of the moment of the restore, which is what every "newest wins" incremental heuristic keys on.

FAT stores a create date+time, a modify date+time and an access DATE only (there is no access time); exFAT stores all three as full timestamps plus the 10 ms increments and UtcOffset bytes, and its entry-set SetChecksum is recomputed after the patch. Each reading is clamped into the range the on-disk format can express, so an out-of-range field is recorded as the nearest legal value rather than failing the call. The entry may be a file or a directory; the volume root has no entry to stamp and is rejected.

Parameters

[in]	handle	Mount handle.
[in]	path	Path to the entry (resolved as ra8_fs_stat() resolves).
[in]	create	Create stamp to write, or NULL to leave it unchanged.
[in]	modify	Modify stamp to write, or NULL to leave it unchanged.
[in]	access	Access stamp to write, or NULL to leave it unchanged.

Returns: ra8_err_t Error code.

Return values

k_ra8_ok	Requested stamps written.
k_ra8_err_null_ptr	`handle` or `path` is NULL.
k_ra8_err_invalid_state	Mount is not in use.
k_ra8_err_invalid_arg	`path` names the volume root, or is not a valid name for this filesystem.
k_ra8_err_not_found	Nothing at `path`.
k_ra8_err_*	Backend read/write failure.

Precondition: handle and path are non-NULL; the mount is in use.; No open handle is mid-write on path (its close would re-stamp it).

Postcondition: On k_ra8_ok each non-NULL reading's fields hold that (clamped) instant.; A NULL reading's fields, and any non-time byte, are unchanged.

Note: Not thread-safe unless a lock is installed (see ra8_fs_set_lock()).

See also: ra8_fs_set_clock() Installs the clock the automatic stamps use.

Since: 0.1.0

Definition at line 255 of file ra8_fs_fat_utime.c.

References internal_utime_locked(), priv_lock_acquire(), priv_lock_release(), and ra8_fs_utime().

Referenced by ra8_fs_utime().

Functions

Detailed Description

Function Documentation

◆ internal_utime_exfat()

◆ internal_utime_fat()

◆ internal_utime_locked()

◆ ra8_fs_utime()