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. 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. The options are as follows:

-b, --background

Run in the background in a subprocess after successfully mounting. This is the default behavior.

-f, --foreground

Run in the foreground and do not detach in a subprocess.

-o mount-options

Mount the filesystem with the following comma-separated mount-options:

cache=size

Sets the filesystem cache to the specified size, which is measured in an optional suffix: % for percent of system memory, K for KiB, M for MiB, or G for GiB. The default is 10% of the system memory.

ro

Mount the filesystem as read-only.

rw

Mount the filesystem for read and write. This option is the default behavior.

-p, --pretend-mount-path=path

When answering requests about where the filesystem is mounted, reply with this path instead of the actual mountpoint in tcgetblob(2). This behavior is useful for chroot(2) environments.

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:

LABEL=label

Search for a filesystem with this label as the volume label. The volume label can be changed with fatlabel(8.)

SERIAL=serial

Search for a filesystem with this serial number as the volume id in the XXXX-XXXX upper-case hexadecimal format.

UUID=uuid

Search for a filesystem with this uuid, containing the 4 byte file serial number and 8 byte volume label and a trailing nul byte. This identifier is recommended for filesystem searches to avoid mounting the wrong filesystem, although it might not be globally unique. Note that if the volume label is changed with fatlabel(8,) then fstab(5) must be updated with the new UUID.

IMPLEMENTATION NOTES

If -f, then fatfs signals readiness when it has successfully mounted the filesystem. 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, unless 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. FAT officially stores timestamps in the local timezone, without storing what timezone that is, but fatfs uses UTC instead to store time losslessly. This behavior may cause time differences when interoperating with other implementations. 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. The first cluster of a file is used as its inode number. If a zero size file without a first cluster is encountered, it will be allocated a first cluster, so it has an unique and permanent inode number. fsck.fat(8) does not like this behavior and will undo it. The filesystem is marked as dirty in FAT entry 1 when mounted. This behavior happens even on FAT12, even though it is not an official feature, but is done since running fsck.fat(8) is essential whenever the filesystem is damaged or not cleanly unmounted.

ASYNCHRONOUS EVENTS

SIGTERM

Request daemon termination. fatfs will exit after gracefully unmounting the filesystem.

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

SEE ALSO

fstab(5), disked(8), fatlabel(8), fsck.fat(8), init(8), lsblk(8), mkfs.fat(8), unmount(8)

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 a directory takes O(n^2) quadratic time due to limitations in the user-space filesystem protocol.