On-disk and handle data types shared by the ra8_fs public API. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for ra8_fs_types.h:

This graph shows which files directly or indirectly include this file:

Data Structures
struct	ra8_fs_backend_t
	Block-device interface that ra8_fs runs on top of. More...
struct	ra8_fs_format_opts_t
	Tunables for ra8_fs_format() (the on-disk geometry of a fresh volume). More...
struct	ra8_fs_mount_t
	Cached parse of one mounted FAT volume. More...
struct	ra8_fs_dirent_t
	Stable directory-entry value copied by ra8_fs_dir_next. More...
struct	ra8_fs_dir_t
	Caller-owned opaque directory cursor. More...
struct	ra8_fs_file_t
	Open-file state. More...
struct	ra8_fs_datetime_t
	Broken-down civil date and time used at the filesystem boundary. More...
struct	ra8_fs_timestamp_t
	One decoded on-disk timestamp plus availability facts. More...
struct	ra8_fs_stat_t
	What ra8_fs_stat() read out of a directory entry. More...

Typedefs
typedef void(*	ra8_fs_listdir_cb_t) (const char name, uint8_t attr, uint64_t size, void ctx)
	Callback invoked once per directory entry by ra8_fs_listdir().

Enumerations
enum	ra8_fs_limits_t : uint8_t { k_ra8_fs_max_files = 4 , k_ra8_fs_max_mounts = 2 , k_ra8_fs_short_name_len = 12 }
	Static-allocation limits for the FAT filesystem adapter. More...
enum	ra8_fs_byte_sizes_t : uint16_t { k_ra8_fs_sector_min = 512 , k_ra8_fs_sector_max = 4096 , k_ra8_fs_dir_entry_bytes = 32 , k_ra8_fs_dir_name_cap = 742 , k_ra8_fs_dir_state_bytes = 640 }
	Byte-size constants used by the FAT layout. More...
enum	ra8_fs_fat_limit_t : uint32_t { k_ra8_fs_fat_max_file_bytes = 0xFFFFFFFFU }
	The FAT12/16/32 per-file size ceiling. More...
enum	ra8_fs_mode_t : uint8_t { k_ra8_fs_mode_read = 0 , k_ra8_fs_mode_write = 1 , k_ra8_fs_mode_append = 2 }
	File-open modes accepted by ra8_fs_open(). More...
enum	ra8_fs_attr_t : uint8_t { k_ra8_fs_attr_read_only = 0x01 , k_ra8_fs_attr_hidden = 0x02 , k_ra8_fs_attr_system = 0x04 , k_ra8_fs_attr_volume_id = 0x08 , k_ra8_fs_attr_directory = 0x10 , k_ra8_fs_attr_archive = 0x20 , k_ra8_fs_attr_lfn = 0x0F }
	8-bit FAT attribute byte (MS FAT spec sec 6 "DIR_Attr"). More...
enum	ra8_fs_type_t : uint8_t { k_ra8_fs_type_unknown = 0 , k_ra8_fs_type_fat12 = 12 , k_ra8_fs_type_fat16 = 16 , k_ra8_fs_type_fat32 = 32 , k_ra8_fs_type_exfat = 64 }
	FAT variant detected from the BPB cluster-count rule. More...
enum	ra8_fs_partition_sel_t : uint8_t { k_ra8_fs_partition_auto = 0xFFU }
	Sentinel partition index requesting auto-selection. More...

Detailed Description

On-disk and handle data types shared by the ra8_fs public API.

The value types the filesystem API is written in terms of: the static-limit and layout enums, the block-device backend interface, the format-options struct, the mount and open-file handles, the stat result, the listdir callback, and the partition selector. They live in their own header so ra8_fs.h stays under the repository's 1000-line source cap while remaining the single include a consumer needs – ra8_fs.h includes this file, so nothing a consumer includes changes.

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

Since: 0.1.0

Definition in file ra8_fs_types.h.

Typedef Documentation

◆ ra8_fs_listdir_cb_t

typedef void(* ra8_fs_listdir_cb_t) (const char *name, uint8_t attr, uint64_t size, void *ctx)

Callback invoked once per directory entry by ra8_fs_listdir().

Parameters

[in]	name	NUL-terminated file name (8.3 on FAT volumes; the exFAT name, truncated to the driver buffer).
[in]	attr	ra8_fs_attr_t attribute byte.
[in]	size	File size in bytes (0 for directories; 64-bit because an exFAT entry may exceed 4 GiB).
[in]	ctx	Caller-provided cookie.

Definition at line 422 of file ra8_fs_types.h.

Enumeration Type Documentation

◆ ra8_fs_attr_t

enum ra8_fs_attr_t : uint8_t

8-bit FAT attribute byte (MS FAT spec sec 6 "DIR_Attr").

Enumerator
k_ra8_fs_attr_read_only	MS FAT spec sec 6 "ATTR_READ_ONLY".
k_ra8_fs_attr_hidden	MS FAT spec sec 6 "ATTR_HIDDEN".
k_ra8_fs_attr_system	MS FAT spec sec 6 "ATTR_SYSTEM".
k_ra8_fs_attr_volume_id	MS FAT spec sec 6 "ATTR_VOLUME_ID".
k_ra8_fs_attr_directory	MS FAT spec sec 6 "ATTR_DIRECTORY".
k_ra8_fs_attr_archive	MS FAT spec sec 6 "ATTR_ARCHIVE".
k_ra8_fs_attr_lfn	Long-file-name marker (we skip).

Definition at line 101 of file ra8_fs_types.h.

◆ ra8_fs_byte_sizes_t

enum ra8_fs_byte_sizes_t : uint16_t

Byte-size constants used by the FAT layout.

The sector size is a RUNTIME property of the mounted medium (ra8_fs_mount_t::bytes_per_sector), taken from the backend's reported block size and cross-checked against the volume's BPB / VBR at mount. These two constants bound it: every supported size is a power of two in [k_ra8_fs_sector_min, k_ra8_fs_sector_max] (512, 1024, 2048, 4096), which is exactly the range the FAT specification allows for BPB_BytsPerSec and exFAT allows for BytesPerSectorShift (9..12). Static sector buffers are sized to the maximum so a 4Kn medium needs no allocation the 512-byte path did not already have.

Enumerator
k_ra8_fs_sector_min	Smallest supported sector size.
k_ra8_fs_sector_max	Largest supported sector size (4Kn).
k_ra8_fs_dir_entry_bytes	MS FAT spec sec 6 "Directory Entry".
k_ra8_fs_dir_name_cap	Longest listed UTF-8 name plus NUL.
k_ra8_fs_dir_state_bytes	Opaque caller-owned cursor state.

Definition at line 59 of file ra8_fs_types.h.

◆ ra8_fs_fat_limit_t

enum ra8_fs_fat_limit_t : uint32_t

The FAT12/16/32 per-file size ceiling.

DIR_FileSize is a 32-bit field (MS FAT spec sec 6), so no FAT file can exceed 4 GiB - 1 bytes. The ceiling is inherent to the format, not to this driver: a write or truncate that would push a FAT file past it fails with k_ra8_err_invalid_size at the FAT boundary. exFAT files carry 64-bit lengths and are not subject to this cap.

Enumerator
k_ra8_fs_fat_max_file_bytes	4 GiB - 1: max DIR_FileSize.

Definition at line 78 of file ra8_fs_types.h.

◆ ra8_fs_limits_t

enum ra8_fs_limits_t : uint8_t

Static-allocation limits for the FAT filesystem adapter.

Enumerator
k_ra8_fs_max_files	Max concurrent open file handles.
k_ra8_fs_max_mounts	Max concurrent mount points.
k_ra8_fs_short_name_len	8.3 short name "AAAAAAAA.EXT" + NUL.

Definition at line 38 of file ra8_fs_types.h.

◆ ra8_fs_mode_t

enum ra8_fs_mode_t : uint8_t

File-open modes accepted by ra8_fs_open().

Enumerator
k_ra8_fs_mode_read	Read-only, must exist.
k_ra8_fs_mode_write	Truncate (or create) for writing.
k_ra8_fs_mode_append	Open at EOF for writing.

Definition at line 91 of file ra8_fs_types.h.

◆ ra8_fs_partition_sel_t

enum ra8_fs_partition_sel_t : uint8_t

Sentinel partition index requesting auto-selection.

A disk carries at most four MBR primary partitions (indices 0-3) or a GPT entry array (indices 0 .. entry-count-1, bounded at 128). Any of those is a valid index for ra8_fs_mount_partition(); this sentinel instead asks for the same first-partition auto-selection ra8_fs_mount() performs.

Invariant: Larger than any addressable partition index, so it can never collide with a real one.

See also: ra8_fs_mount_partition()

Enumerator
k_ra8_fs_partition_auto	Auto-select the first mountable partition.

Definition at line 442 of file ra8_fs_types.h.

◆ ra8_fs_type_t

enum ra8_fs_type_t : uint8_t

FAT variant detected from the BPB cluster-count rule.

Enumerator
k_ra8_fs_type_unknown	Not yet detected / mount failed.
k_ra8_fs_type_fat12	count_of_clusters < 4085.
k_ra8_fs_type_fat16	4085 <= count_of_clusters < 65525.
k_ra8_fs_type_fat32	count_of_clusters >= 65525.
k_ra8_fs_type_exfat	exFAT (read + streaming write + format).

Definition at line 115 of file ra8_fs_types.h.

Data Structures

Typedefs

Enumerations