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.