FatFS API¶

This API provides an implementation of the FatFS filesystem. It creates an easy way to interact with files on a connected media device.

In order to use this API, the fatfs object must be present in the project’s config.json file. Additionally, either the SPI or SDIO child object should be included to take full advantage of the library. An example is given below:

{
    "fs": {
        "fatfs": {
            "driver": {
                "sdio": {}
            }
        }
    }
}

This would enable the FatFS API to interface with a direct SDIO connection to an SD card.

See the Kubos SD Example for an example of how to use this interface.

enum KUBOS_CORE_FF::FRESULT¶

File function return code.

Values:

FR_OK = 0¶: (0) Succeeded

FR_DISK_ERR¶: (1) A hard error occurred in the low level disk I/O layer

FR_INT_ERR¶: (2) Assertion failed

FR_NOT_READY¶: (3) The physical drive cannot work

FR_NO_FILE¶: (4) Could not find the file

FR_NO_PATH¶: (5) Could not find the path

FR_INVALID_NAME¶: (6) The path name format is invalid

FR_DENIED¶: (7) Access denied due to prohibited access or directory full

FR_EXIST¶: (8) Access denied due to prohibited access

FR_INVALID_OBJECT¶: (9) The file/directory object is invalid

FR_WRITE_PROTECTED¶: (10) The physical drive is write protected

FR_INVALID_DRIVE¶: (11) The logical drive number is invalid

FR_NOT_ENABLED¶: (12) The volume has no work area

FR_NO_FILESYSTEM¶: (13) There is no valid FAT volume

FR_MKFS_ABORTED¶: (14) The f_mkfs() aborted due to any parameter error

FR_TIMEOUT¶: (15) Could not get a grant to access the volume within defined period

FR_LOCKED¶: (16) The operation is rejected according to the file sharing policy

FR_NOT_ENOUGH_CORE¶: (17) LFN working buffer could not be allocated

FR_TOO_MANY_OPEN_FILES¶: (18) Number of open files > _FS_LOCK

FR_INVALID_PARAMETER¶: (19) Given parameter is invalid

typedef char TCHAR¶

typedef DWORD FSIZE_t¶: Type of file size variables and object identifier.

FRESULT f_open(FIL *fp, const TCHAR *path, BYTE mode)¶

Open (and/or) create a file.

Return

FRESULT

Parameters

fp: Pointer to file
path: Path of file to open
mode: File open mode

FRESULT f_close(FIL *fp)¶

Close a file.

Return

FRESULT

Parameters

fp: Pointer to file

FRESULT f_read(FIL *fp, void *buff, UINT btr, UINT *br)¶

Read data from a file.

Return

FRESULT

Parameters

fp: Pointer to file
buff: Pointer to storage buffer
btr: Number of bytes to read
br: Number of bytes read

FRESULT f_write(FIL *fp, const void *buff, UINT btw, UINT *bw)¶

Write data to a file.

Return

FRESULT

Parameters

fp: Pointer to file
buff: Pointer to storage buffer
btw: Number of bytes to write
bw: Number of bytes written

FRESULT f_lseek(FIL *fp, FSIZE_t ofs)¶

Move file pointer of a file object.

Return

FRESULT

Parameters

fp: Pointer to file
ofs: Byte offset from top of the file to set read/write pointer

FRESULT f_truncate(FIL *fp)¶

Truncate file size.

Return

FRESULT

Parameters

fp: Pointer to file

FRESULT f_sync(FIL *fp)¶

Flush cached information of a writing file.

Return

FRESULT

Parameters

fp: Pointer to file

FRESULT f_opendir(FAT_DIR *dp, const TCHAR *path)¶

Open file directory.

Return

FRESULT

Parameters

dp: Pointer to directory object structure
path: Directory name

FRESULT f_closedir(FAT_DIR *dp)¶

Close file directory.

Return

FRESULT

Parameters

dp: Pointer to directory object structure

FRESULT f_readdir(FAT_DIR *dp, FILINFO *fno)¶

Read a directory item.

Return

FRESULT

Parameters

dp: Pointer to directory object structure
fno: Pointer to file information structure

FRESULT f_findfirst(FAT_DIR *dp, FILINFO *fno, const TCHAR *path, const TCHAR *pattern)¶

Find first file match in a directory.

Return

FRESULT

Parameters

dp: Pointer to blank directory object
fno: Pointer to file information storage structure
path: Pointer to the directory name to be opened
pattern: Pointer to the pattern to match

FRESULT f_findnext(FAT_DIR *dp, FILINFO *fno)¶

Find next file match in a directory.

Return

FRESULT

Parameters

dp: Pointer to directory object
fno: Pointer to file information storage structure

FRESULT f_mkdir(const TCHAR *path)¶

Create a new directory.

Return

FRESULT

Parameters

path: Directory name to be created

FRESULT f_unlink(const TCHAR *path)¶

Delete an existing file or directory.

Return

FRESULT

Parameters

path: Name of file or directory to delete

FRESULT f_rename(const TCHAR *path_old, const TCHAR *path_new)¶

Rename/move an existing file or directory.

Return

FRESULT

Parameters

path_old: Current name of file or directory
path_new: New name of file or directory

FRESULT f_stat(const TCHAR *path, FILINFO *fno)¶

Get file status.

Return

FRESULT

Parameters

path: Name of file to check
fno: Pointer to file info structure

FRESULT f_chmod(const TCHAR *path, BYTE attr, BYTE mask)¶

Change attributes of a file or directory.

Return

FRESULT

Parameters

path: Name of file or directory
attr: New attribute flags to set
mask: Mask specifying which attribute is changed

FRESULT f_utime(const TCHAR *path, const FILINFO *fno)¶

Change timestamp of file or directory.

Return

FRESULT

Parameters

path: Name of file/directory
fno: Pointer to new file info structure

FRESULT f_chdir(const TCHAR *path)¶

Change current directory.

Return

FRESULT

Parameters

path: Directory to change to

FRESULT f_chdrive(const TCHAR *path)¶

Change current drive.

Return

FRESULT

Parameters

path: Drive to change to

FRESULT f_getcwd(TCHAR *buff, UINT len)¶

Get current directory.

Return

FRESULT

Parameters

buff: Buffer for returned path name
len: Size of buffer

FRESULT f_getfree(const TCHAR *path, DWORD *nclst, FATFS **fatfs)¶

Get nubmer of free clusters on the drive.

Return

FRESULT

Parameters

path: Logical drive number
nclst: Number of free clusters
fatfs: Pointer->pointer->pointer->filesystem object

FRESULT f_getlabel(const TCHAR *path, TCHAR *label, DWORD *vsn)¶

Get volume label.

Return

FRESULT

Parameters

path: Drive number
label: Volume label
vsn: Volume serial number

FRESULT f_setlabel(const TCHAR *label)¶

Set volume label.

Return

FRESULT

Parameters

label: Volume label

FRESULT f_forward(FIL *fp, UINT (*func)(const BYTE *, UINT), UINT btf, UINT *bf, )¶

Forward data to the data streaming device.

Return

FRESULT

Parameters

fp: Pointer to file
func: Data streaming function
btf: Number of bytes to forward
bf: Number of bytes forwarded

FRESULT f_expand(FIL *fp, FSIZE_t szf, BYTE opt)¶

Allocate a contiguous block to the file.

Return

FRESULT

Parameters

fp: Pointer to file
szf: Size to expand to
opt: Operation mode. Prepare only (0) or Allocate now (1).

FRESULT f_mount(FATFS *fs, const TCHAR *path, BYTE opt)¶

Mount/Unmount a logical drive.

Return

FRESULT

Parameters

fs: Pointer to file system object
path: Logical drive number
opt: Initialization option. Don’t mount now (0) or force mount (1)

FRESULT f_mkfs(const TCHAR *path, BYTE sfd, UINT au)¶

Create a new volume on the logical drive.

Return

FRESULT

Parameters

path: Logical drive number
sfd: Format options
au: Size of the allocation unit

FRESULT f_fdisk(BYTE pdrv, const DWORD szt[], void *work)¶

Divide a physical drive.

Return

FRESULT

Parameters

pdrv: Physical drive number
szt: Partition map table
work: Work area

int f_putc(TCHAR c, FIL *fp)¶

Put a character into a file.

Return

If successful, number of characters written; otherwise -1

Parameters

c: Character to put
fp: Pointer to file

int f_puts(const TCHAR *str, FIL *fp)¶

Write a string into a file.

Return

If successful, number of characters written; otherwise -1

Parameters

str: String to write
fp: Pointer to file

int f_printf(FIL *fp, const TCHAR *str, ...)¶

Write a formatted string into a file.

Return

If successful, number of characters written; otherwise -1

Parameters

fp: Pointer to file
str: String to write
...: Optional arguments

TCHAR *f_gets(TCHAR *buff, int len, FIL *fp)¶

Read a string into a file.

Return

If successful, returns buff

Parameters

buff: Read buffer
len: Size of read buffer
fp: Pointer to file

_FATFS 88100¶: Revision ID.

LD2PD(vol) (BYTE)(vol)¶

Definitions of volume management.

Each logical drive is bound to the same physical drive number

LD2PT(vol) 0¶: Find first valid partition or in SFD.

_T(x) x¶

_TEXT(x) x¶

f_eof(fp) ((int)((fp)->fptr == (fp)->obj.objsize))¶: Test for end-of-file on a file.

f_error(fp) ((fp)->err)¶: Test for an error on a file.

f_tell(fp) ((fp)->fptr)¶: Get current read/write pointer of a file.

f_size(fp) ((fp)->obj.objsize)¶: Get size of a file.

f_rewind(fp) f_lseek((fp), 0)¶: Set read/write pointer to beginning of file.

f_rewinddir(dp) f_readdir((dp), 0)¶: Get first item in a directory.

EOF (-1)¶: End-of-file indicator.

FA_READ 0x01¶

Specifies read access to the object.

Data can be read from the file.

FA_WRITE 0x02¶

Specifies write access to the object.

Data can be written to the file. Combine with FA_READ for read-write access.

FA_OPEN_EXISTING 0x00¶

Opens the file.

The function fails if the file is not existing. (Default)

FA_CREATE_NEW 0x04¶

Creates a new file.

The function fails with FR_EXIST if the file is existing.

FA_CREATE_ALWAYS 0x08¶

Creates a new file.

If the file is existing, it will be truncated and overwritten.

FA_OPEN_ALWAYS 0x10¶

Opens the file if it is existing.

If not, a new file will be created.

_FA_MODIFIED 0x20¶: Flag to mark file as modified.

_FA_DIRTY 0x40¶: Flag to mark file as dirty.

FS_FAT12 1¶: FAT12 file system.

FS_FAT16 2¶: FAT16 file system.

FS_FAT32 3¶: FAT32 file system.

FS_EXFAT 4¶: exFAT file system

AM_RDO 0x01¶: File attribute bit - Read only.

AM_HID 0x02¶: File attribute bit - Hidden.

AM_SYS 0x04¶: File attribute bit - System.

AM_VOL 0x08¶: File attribute bit - Volume label.

AM_LFN 0x0F¶: File attribute bit - LFN entry.

AM_DIR 0x10¶: File attribute bit - Directory.

AM_ARC 0x20¶: File attribute bit - Archive.

AM_MASK 0x3F¶: File attribute bit - Mask of defined bits.

CREATE_LINKMAP ((FSIZE_t)0 - 1)¶: Fast seek controls.

struct FATFS¶

#include <ff.h>

File system object structure (FATFS)

Public Members

BYTE fs_type¶: File system type (0:N/A)

BYTE drv¶: Physical drive number.

BYTE n_fats¶: Number of FATs (1 or 2)

BYTE wflag¶: win[] flag (b0:dirty)

BYTE fsi_flag¶: FSINFO flags (b7:disabled, b0:dirty)

WORD id¶: File system mount ID.

WORD n_rootdir¶: Number of root directory entries (FAT12/16)

WORD csize¶: Cluster size [sectors].

DWORD last_clst¶: Last allocated cluster.

DWORD free_clst¶: Number of free clusters.

DWORD n_fatent¶: Number of FAT entries (number of clusters + 2)

DWORD fsize¶: Size of an FAT [sectors].

DWORD volbase¶: Volume base sector.

DWORD fatbase¶: FAT base sector.

DWORD dirbase¶: Root directory base sector/cluster.

DWORD database¶: Data base sector.

DWORD winsect¶: Current sector appearing in the win[].

BYTE win[_MAX_SS]¶: Disk access window for Directory, FAT (and file data at tiny cfg)

struct _FDID¶

#include <ff.h>

Object ID and allocation information (_FDID)

Public Members

FATFS *fs¶: Pointer to the owner file system object.

WORD id¶: Owner file system mount ID.

BYTE attr¶: Object attribute.

BYTE stat¶: Object chain status (b1-0: =0:not contiguous, =2:contiguous (no data on FAT), =3:got flagmented, b2:sub-directory stretched)

DWORD sclust¶: Object start cluster (0:no cluster or root directory)

FSIZE_t objsize¶: Object size (valid when sclust != 0)

struct FIL¶

#include <ff.h>

File object structure (FIL)

Public Members

_FDID obj¶: Object identifier.

BYTE flag¶: File status flags.

BYTE err¶: Abort flag (error code)

FSIZE_t fptr¶: File read/write pointer (Zeroed on file open)

DWORD clust¶: Current cluster of fpter (not valid when fprt is 0)

DWORD sect¶: Sector number appearing in buf[] (0:invalid)

DWORD dir_sect¶: Sector number containing the directory entry.

BYTE *dir_ptr¶: Pointer to the directory entry in the win[].

BYTE buf[_MAX_SS]¶: File private data read/write window.

struct FAT_DIR¶

#include <ff.h>

Directory object structure (FAT_DIR)

Public Members

_FDID obj¶: Object identifier.

DWORD dptr¶: Current read/write offset.

DWORD clust¶: Current cluster.

DWORD sect¶: Current sector.

BYTE *dir¶: Pointer to the directory item in the win[].

BYTE *fn¶: Pointer to the SFN (in/out) {body[8],ext[3],status[1]}.

struct FILINFO¶

#include <ff.h>

File information structure (FILINFO)

Public Members

FSIZE_t fsize¶: File size.

WORD fdate¶: Modified date.

WORD ftime¶: Modified time.

BYTE fattrib¶: File attribute.

TCHAR fname[13]¶: File name.