Sortix cross-volatile manual

This manual documents Sortix cross-volatile. You can instead view this document in the latest official manual.

NAME

fatfs — fat filesystem driver

SYNOPSIS

fatfs

[-bf] [-o mount-options] [-p path] device mountpoint

DESCRIPTION

fatfs mounts the FAT filesystem on the device for reading and writing at the mountpoint. fatfs forks and runs in the background once the filesystem has been mounted.

A compatible FAT filesystem can be created using mkfs.fat(8), and such filesystems can be checked and repaired using fsck.fat(8). The filesystem label can be set with fatlabel(8). Filesystems can be automatically mounted by init(8) on boot by creating an entry in fstab(5) with the fat or efi type. disked(8) is typically used for partition and filesystem administration. The efi filesystem type is the same as the fat filesystem, except it uses a different mbr(7) id and a different guid(7) guid to identify the the partition as the EFI System Partition.

The FAT filesystem uses a File Allocation Table to allocate clusters. The block device is split into fixed sized clusters. The FAT entries are either 12, 16, or 32 bit wide, solely depending on the number of clusters and what width is needed. Files and directories are stored as a pointer to the first cluster, and the FAT is used as a singly linked list to next cluster. A backup FAT is commonly formatted in the filesystem for data recovery purposes. The FAT filesystem has exactly the same features regardless of the FAT entry width.

The FAT filesystem supports only files and directories. Hard links, symbolic links, block devices, sockets, fifos, block devices, character devices, and any other special files are not possible. Owner and group metadata does not exist. The only permission metadata is an owner write bit. There are no read and execute permission bits. The access timestamp has day precision. The modified timestamp has 2 second precision. The creation timestamp has 10 ms precision, but is not accessible through stat(2) and utimens(2). There is no status change timestamp and the modified time is used instead. The opened name will be used if it already is in the 8.3 format. All timestamps store the year as an unsigned 7-bit value since 1980 and will overflow in the year 2108. Directory entries are assigned a 8.3 short name, with up to 8 uppercase characters for the file name and up to 3 uppercase characters for the file extension. The original name is used as a short name if it already is in the 8.3 format. Otherwise a similar short will be used (with a prefix of file name, a ‘~’ character, numeric digits to disambiguate similar files, and three characters from the file extensions), and a long file name entry will be added with the original file name. Long file names can store up to 255 UTF-16 code units.

FAT is a case insensitive filesystem, but fatfs implements case sensitivity. Short names will always be upper case, but the original case will be preserved in the long name. fatfs allows creating a file as long as its long name is different bytewise from any other long name in the directory. fatfs does not allow opening a file by its short name, unles it has no long name, in which case the short name is used as its real name. If the requested name is in the 8.3 format, but a file already uses that short name, but the long name is not used, then the requested name is used as the long name and an unused short name is allocated. Other operating systems with case insensitive FAT filesystems will not interoperate if such files are created and such files may not be accessible except through their assigned short names.

The options are as follows:

The following identifiers are available to recognize a filesystem in fstab(5) in the fs_spec field and can be queried with the disked(8) id command:

IMPLEMENTATION NOTES

If -f, then fatfs signals readiness when it has successfully mounted the filesystem.

The Windows FAT filesystem driver limits directories to 65536 entries. fatfs has no such limitation, except it will only search for up to the ~65536 suffix when allocating an unused short name.

ASYNCHRONOUS EVENTS

EXIT STATUS

If -b, fatfs exits 0 after successfully mounting the filesystem and serving requests in a background process.

If -f, fatfs signals readiness on the READYFD file descriptor when filesystem has been mounted, and continues running in the same process.

fatfs runs as a daemon(7) until stopped by SIGTERM or until the filesystem is unmounted with unmount(8) or unmount(2), after which fatfs exits 0 if the filesystem was cleanly unmounted.

fatfs exits non-zero on fatal errors.

EXAMPLES

$ mkfs.fat /dev/foo0 
$ fatfs /dev/foo0 /mnt 
$ echo bar > /mnt/bar 
$ unmount /mnt 
$ fsck.fat /dev/foo0

BUGS

fsync(2) does not sync the inode data contents, but only its metadata. fatfs will sync in the background, but this fact cannot be observed yet. To reliably sync, unmount the filesystem.

libmount uses the volume label in the first sector rather than the volume label in the root directory.

Timestamps store years as an unsigned 7-bit value since 1980 and will overflow in the year 2108.

Reading and writing files and directories runs in O(n) linear time due to the singly linked list nature of the FAT, which takes O(n^2) quadratic time when reading a full file/directory.