FatFs Module Application Note

Considerations on porting to various platform

The FatFs module is assuming following terms on portability.

ANSI C
+The FatFs module is a middleware that written in ANSI C. There is no platform dependence, so long as the compiler is in compliance with ANSI C. However it handles the system portable FAT structures. You must take the endian into consideration. This setting is defined in ff.h (tff.h). It must be changed for your platform first or the compiler will abort with an error.
Size of char/short/long are 8/16/32 bit and int is 16 bit or grater.
+These correspondence are defined in integer.h. This will not be a problem on most compilers. When any conflict of the definitions between the integer.h and existing definitions is occured, you must resolve the confrict with care.

Memory Usage (R0.04b)

These are the memory usage on some target systems. The memory sizes are in unit of byte, D means number of logical drives and F means number of open files. All samples are optimezed in code size.

+ + + + + + + + + + + + + + + + +

	AVR	H8/300H	MSP430	TLCS-870/C	V850ES	SH2
Compiler	gcc	CH38	CL430	CC870C	CA850	SHC
_MCU_ENDIAN	1	2	2	1	1	2
FatFs Code (Standard, R/W cfg.)	8722	8776			6402	7338
FatFs Code (Minimum, R/W cfg.)	5814	5722			4094	4906
FatFs Code (Standard, R/O cfg.)	4248	4096			3010	3506
FatFs Code (Minimum, R/O cfg.)	3038	3110			2210	2698
FatFs Work (Static)	D*2 + 2	D*4 + 2			D*4 + 2	D*4 + 2
FatFs Work (Dynamic)	D554 + F544	D554 + F550			D554 + F550	D554 + F550
Tiny-FatFs Code (Standard, R/W cfg.)	7264	7240	6634	8837
Tiny-FatFs Code (Minimum, R/W cfg.)	4750	4806	4366	6163
Tiny-FatFs Code (Standard, R/O cfg.)	3600	3548	3212	4347
Tiny-FatFs Code (Minimum, R/O cfg.)	2568	2702	2394	3322
Tiny-FatFs Wrok (Static)	4	6	4	4
Tiny-FatFs Work (Dynamic)	544 + F*28	544 + F*32	544 + F*28	544 + F*28

FatFs vs. Tiny-FatFs

For most applications, such as portable audio and data logger, Tiny-FatFs is the best choice. However because the Tiny-FatFs does not support FAT32 in default, there is a limitation that can handle only tiny storage upto 2GB(4GB in FAT64). The FAT32 support can be added by _USE_FAT32 option with an additional code size. The FatFs is suitable for fast multiple files access, and for multiple drive system.

+ + + + + +

Memory Size	FAT Type
<= 64MB	FAT12
128MB - 2GB	FAT16
>= 4GB	FAT32

Rignt table shows the correspondence between memory size and FAT type for SD memroy card and they are shipped with this format. The data area is justified to the erase block boundary and the memory card works with the best performance. For that reason, the memory card should not be reformated with PC. When cluster size or FAT type is changed, the write performance can be decreased.

Performance effective file access

For good performance on reading/writing files on the small embedded system, application program should consider what process is done in the FatFs module. The file data on the disk is transferred by f_read function in following process.

Figure 1. Sector miss-aligned read (short)
+ +

Figure 2. Sector miss-aligned read (long)
+ +

Figure 3. Sector aligned read
+ +

The file I/O buffer means a sector buffer to read/write a partial data on the sector. On the FatFs, member buffer[] in the file object is used. On the Tiny-FatFs, member win[] in the file system object is used.

Tiny-FatFs processes all data transfer and access to the FAT/directory with only one sector buffer, so that FAT sector cached into the buffer is lost and it must reloaded at every cluster boundary. FatFs has a FAT/directory buffer separated from file I/O buffer, the frequency of FAT accesses is only 1/341, 1/256 or 1/128 (when cluster is contiguous) compared to Tiny-FatFs. Thus the Tiny-FatFs is sacrificing its performance in compensation for very small memory footprint.

Figure 1 shows that partial sector data is transferred via the file I/O buffer. At long data transfer shown in Figure 2, middle of transfer data that aligned to sector boundary is transferred into memory directly. Figure 3 shows that entier transfer data is aligned to the sector boundary. In this case, file I/O buffer is not used. At the unbuffered transfer, maximum extent of sectors are read with disk_read function at a time but it never across cluster boundary even if it is contiguous.

Therefore taking effort to sector aligned read/write accesss eliminates memcpy and the read/write performance will be improved. Besides the effect, cached FAT sector is not flushed during read/write access on the Tiny-FatFs, so that it can achieve same performance as FatFs and its small memory footprint simultanesously.

Critical section

When write operation to the FAT file system is interrupted due to any accidental failure, such as sudden blackout, incorrect disk removal and unrecoverable data error, the FAT structure can be destroyed. Following images shows the critical section on the FatFs module.

+Figure 4. Long critical section
+ fig.4

+Figure 5. Minimized critical section
+ fig.5

+
+

An interruption in the red section can cause a cross link; as a result, the file/directory being changed will be lost. There is one or more possibility listed below when an interruption in the yellow section is occured.

File data being rewrited is collapted.
A file being appended returns initial state.
A file created as new is gone.
A file created as new or in overwrite remains with length of zero.
Efficiency of disk use gets worse due to lost chain.

Each case does not affect the files that not in write operation. To minimize risk of data loss, the critical section can be minimized like shown in Figure 5 by minimizing the time that file is opened in write mode and using f_sync function properly.

Problems and Ideas

Abstraction of file object
+Currently the file object structure is held by application layer. This is not a problem for Tiny-FatFs, it consumes the task stack only 26 bytes per file. But FatFs requires 550 bytes per file. When managed the file objects in file handle, stack consumption at application module will able to be reduced. In this case, the work area for file objects is managed in FatFs module. This has a disadvantage that direct access to the file object structure cannot be used and additional file functions, such as feof and ftell, will be needed.
Efficient sector buffer management
+The FatFs module has only one sector buffer per logical drive. There is an ineffciency on random file access with many files simultanesously. When additional memory for the sector buffer is available, the file access performance will able to be improved with an advanced cache mechanism.
Long file name
+There is an extended feature to handle long file name (LFN) up to 255 characters, in addition to 8.3 format file name, on FAT file system. To support this, 512 byte string buffer for file name and UCS-2 - Shift_JIS mutual conversion table are required. Therefore memory consumption of code and work area will be increased drastically. The FatFs module does not support this feature. The LFN on the FAT file system is a patent of Microsoft. When support it on the commercial products, you have to be licensed.
Porting to RTOS
+When use FatFs module from only one task, no consideration is needed. However when make access to a logical drive from two or more tasks simultanesously, any exclusion control will be required. The FatFs module is also ported to a free RTOS based on μITRON by TOPPERS Project.

+
+

These are the problems and ideas on current revision of FatFs module. However the main target of FatFs module is 8 bit microcontrollers. These extensions requires much resource and the FatFs will unable to be ported to the 8 bit system. This may be the most serious problem on future plan.

f_chmod

The f_chmod function changes the attribute of a file or directory.

+FRESULT f_chmod (
+  const char* FileName, /* Pointer to the file or directory */
+  BYTE Attribute,       /* Attribute flags */
+  BYTE AttributeMask    /* Attribute masks */
+);
+

Parameter

FileName

Pointer to the null-terminated string that specifies a file or directory to be changed

Attribute

Attribute flags to be set in one or more combination of the following flags. The specified flags are set and others are cleard.
+ + + + + + +

Attribute	Description
AM_RDO	Read only
AM_ARC	Archive
AM_SYS	System
AM_HID	Hidden

AttributeMask

Attribute mask that specifies which attribute is changed. The specified aattributes are set or cleard.

Return Values

FR_OK (0): The function succeeded.
FR_NO_FILE: Could not find the file.
FR_NO_PATH: Could not find the path.
FR_INVALID_NAME: The file name is invalid.
FR_INVALID_DRIVE: The drive number is invalid.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_WRITE_PROTECTED: The medium is write protected.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_ENABLED: The logical drive has no work area.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Description

The f_chmod function changes the attribute of a file or directory. This function is not supported in read-only configuration and minimization level of >=1.

Example

+    // Set read-only flag, clear archive flag and others are retained.
+    f_chmod("file.txt", AR_RDO, AR_RDO | AR_ARC);
+

f_close

The f_close function closes an open file.

+FRESULT f_close (
+  FIL* FileObject     /* Pointer to the file object structure */
+);
+

Parameter

FileObject: Pointer to the open file object structure to be closed.

Return Values

FR_OK (0): The file object has been closed successfuly.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_INVALID_OBJECT: The file object is invalid.

Description

The f_close function closes an open file object. If any data has been written to the file, the cached information of the file is written back to the disk. After the function succeeded, the file object is no longer valid and it can be discarded. If the file object has been opened in read-only mode, it may be discarded without closing process by this function.

References

f_open, f_read, f_write, f_sync, FIL, FATFS

disk_initialize

The disk_initialize function initializes the disk drive.

+DSTATUS disk_initialize (
+  BYTE Drive           /* Physical drive number */
+);
+

Parameters

Drive: Specifies the physical drive number to initialize.

Return Values

This function returns a disk status as the result. For details of the disk status, refer to the disk_status function.

Description

The disk_initialize function initializes a physical drive. When the function succeeded, STA_NOINIT flag in the return value is cleard.

disk_ioctl

The disk_ioctl function cntrols device specified features and miscellaneous functions other than disk read/write.

+DRESULT disk_ioctl (
+  BYTE Drive,      /* Drive number */
+  BYTE Command,    /* Control command code */
+  void* Buffer     /* Data transfer buffer */
+);
+

Parameters

Drive: Specifies drive number (0-9).
Command: Specifies the command code.
Buffer: Pointer to the parameter buffer depends on the command code. When it is not used, specify a NULL pointer.

Return Value

RES_OK (0): The function succeeded.
RES_ERROR: Any error occured.
RES_PARERR: Invalid command code.
RES_NOTRDY: The disk dirve has not been initialized.

Description

The FatFs module uses only device independent commands described below. Any device dependent function is not used. In read-only configuration, This function is not needed.

+ + + + +

Command	Description
GET_SECTOR_COUNT	Returns total sectors on the drive into the DWORD variable pointed by Buffer.
CTRL_SYNC	Make sure that the drive has finished to write data. When the module has a write back cache, write back the dirty sector immediately.

disk_read

The disk_read function reads sector(s) from the disk drive.

+DRESULT disk_read (
+  BYTE Drive,          /* Physical drive number */
+  BYTE* Buffer,        /* Pointer to the read buffer */
+  DWORD SectorNumber,  /* Sector number to read from */
+  BYTE SectorCount     /* Number of sectros to read */
+);
+

Parameters

Drive: Specifies the physical drive number to read.
Buffer: Pointer to the read buffer to store the read data. SectorCount * 512 bytes is required for the size of the read buffer.
SectorNumber: Specifies the start sector number in logical block address.
SectorCount: Specifies number of sectors to read. The value can be 1 to 255.

Return Value

RES_OK (0): The function succeeded.
RES_ERROR: Any error occured during the read operation.
RES_PARERR: Invalid parameter.
RES_NOTRDY: The disk dirve has not been initialized.

disk_status

The disk_status function gets the disk status.

+DSTATUS disk_status (
+  BYTE Drive     /* Physical drive number */
+);
+

Parameters

Drive: Specifies the physical drive number to be tested.

Return Values

The disk status is returned in combinatin of following flags.

STA_NOINIT: Indicates that the disk drive has not been initialiezed. This flag is set on: power-on, disk removal and disk_initialize function failed, and cleared on: disk_initialize function succeeded.
STA_NODISK: Indicates that no medium in the drive. It is always cleared on fixed disk drive.
STA_PROTECTED: Indicates that the medium is write protected. It is always cleared on the drive that does not support write protect notch.

disk_write

The disk_write writes sector(s) to the disk.

+DRESULT disk_write (
+  BYTE Drive,          /* Physical drive number */
+  const BYTE* Buffer,  /* Pointer to the read buffer */
+  DWORD SectorNumber,  /* Sector number to write */
+  BYTE SectorCount     /* Number of sectors to write */
+);
+

Parameters

Drive: Specifies the physical drive number to write.
Buffer: Pointer to the data to be written.
SectorNumber +: Specifies the start sector number in logical block address.
SectorCount: Specifies number of sectors to write. The value can be 1 to 255.

Return Values

RES_OK (0): The function succeeded.
RES_ERROR: Any error occured during the write operation.
RES_WRPRT: The disk is write protected.
RES_PARERR: Invalid parameter.
RES_NOTRDY: The disk dirve has not been initialized.

Description

This function is not required in read only configuration.

get_fattime

The get_fattime function gets current time.

+DWORD get_fattime (void);
+

Return Value

Currnet time is returned with packed into a DWORD value. The bit field is as follows:

bit31:25: Year from 1980 (0..127)
bit24:21: Month (1..12)
bit20:16: Date (1..31)
bit15:11: Hour (0..23)
bit10:5: Minute (0..59)
bit4:0: Second/2 (0..29)

Description

The get_fattime function must return any valid time even if the system does not support a real time clock. This fucntion is not required in read only configuration.

File and Path name on the FatFs module

The format of file and path name on the FatFs module is similer to MS-DOS. However it does not have a concept of current directory, all objects on the drive are specified in full path from the roor directory.

+
+ "[logical drive#:][/]directory/file"
+
+ "file1.txt"           a file on drive 0
+ "/file1.txt"          (same as above)
+ "dir1/dir2/file1.txt" a file on drive 0
+ "2:dir3/file2.txt"    a file on drive 2
+ "2:/dir5"             a directory on drive 2
+ ""                    the root directory on drive 0
+ "/"                   (same as above)
+ "2:"                  the root directory on drive 2
+
+

The FatFs module supports only 8.3 format file name and long file name is currentry not supported. For directory separator, a '/' is used, not a '\'. Heading '/' is ignored and can be omitted.

The logical drive number is specified in a numeral with a colon. When drive number is omitted, it means the default drive (0). As for the Tiny-FatFs, it has only one logical drive and always works as drive 0. Any drive number cannot be contained in the path name.

Correspondence between logical/physical drive

In default, the FatFs module has work areas that called file system object for each logical drive. The logical drive is bound simply to the physical drive that has same drive number, and first partition is mounted. When _MULTI_PARTITION is specified in configuration option, each individual logical drive can be bound to any physical drive/partition. In this case, a drive number resolution table must be defined as follows:

+Example: Logical drive 0-2 are assigned to three pri-partitions on the physical drive 0 (fixed disk)
+         Logical drive 3 is assigned to physical drive 0 (removable disk)
+
+const PARTITION Drives[] = {
+    {0, 0},     /* Logical drive 0 ==> Physical drive 0, 1st partition */
+    {0, 1},     /* Logical drive 1 ==> Physical drive 0, 2nd partition */
+    {0, 2},     /* Logical drive 2 ==> Physical drive 0, 3rd partition */
+    {1, 0}      /* Logical drive 3 ==> Physical drive 1 */
+};
+

There are some consideration when use _MULTI_PARTITION configuration.

Only pri-partition (0-3) can be mounted.
When the drive have no partition table (super floppy format), partition number is ignored.
The drive that has two or more logical drive must be fixed drive.

f_getfree

The f_getfree function gets number of the free clusters.

+FRESULT f_getfree (
+  const char* Path,         /* Root directory of the drive */
+  DWORD* Clusters,          /* Pointer to the variable to store number of free clusters */
+  FATFS** FileSystemObject  /* Pointer to pointer to file system object */
+);
+

Parameters

Path: Pinter to the null-terminated string that specifies the root directory of the logical drive. Always specify a null-string for Tiny-FatFs.
Clusters: Pointer to the DWORD variable to store number of free clusters.
FileSystemObject: Pointer to the pointer that to be stored the pointer to corresponding file system object.

Return Values

FR_OK (0): The function succeeded. The *Clusters havs number of free clusters and *FileSystemObject points the file system object.
FR_INVALID_DRIVE: The drive number is invalid.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_ENABLED: The logical drive has no work area.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Descriptions

The f_getfree function gets number of free clusters on the drive. The sects_clust member in the file system object refreting number of sectors per cluster, so that the free space in unit of sector can be calcurated with this. When _USE_FSINFO option is enabled, this function can return inaccurate free cluster count on FAT32 volume. When _USE_FSINFO option is disabled, this function will take a time on FAT32 volume.

This function is not supported in read-only configuration and minimization level of >= 1.

Samples Code

+    FATFS *fs;
+    DWORD clust;
+
+
+    // Get free clusters
+    res = f_getfree("", &clust, &fs);
+    if (res) die(res);
+
+    // Get free space
+    printf("%lu KB total disk space.\n"
+           "%lu KB available on the disk.\n",
+           (DWORD)(fs->max_clust - 2) * fs->sects_clust / 2,
+           clust * fs->sects_clust / 2);
+

References

FATFS

f_lseek

The f_lseek functione moves the file read/write pointer of an open file object.

+FRESULT f_lseek (
+  FIL* FileObject,   /* Pointer to the file object structure *
+  DWORD Offset       /* File offset in unit of byte *
+);
+

Parameters

FileObject: Pointer to the open file object.
Offset: Number of bytes where from start of file

Return Values

FR_OK (0): The function succeeded.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_INVALID_OBJECT: The file object is invalid.

Description

The f_lseek function moves the file R/W pointer of an open file. The offset can be specified in only origin from top of the file. When an offset above the file size is specified in write mode, the file is extended to the offset and the data in the extended area is undefined. After the function succeeded, member fptr in the file object should be checked in order to make sure the R/W pointer has been moved correctry. In case of fptr is less than Offset, any of the followings has been occured.

In read-only mode, the Offset was clipped in file size.
The drive gets full during the file extending process.
There is any error in the FAT structure.

This function is not supported in minimization level of >= 3.

Example

+    // Move to offset of 5000 from top of the file.
+    res = f_lseek(&file, 5000);
+
+    // Forward 3000 bytes
+    res = f_lseek(&file, file.fptr + 3000);
+
+    // Rewind 2000 bytes (take care on overflow)
+    res = f_lseek(&file, file.fptr - 2000);
+
+    // Move to end of the file
+    res = f_lseek(&file, file.fsize);
+

References

f_open, FIL

f_mkdir

The f_mkdir function creates a new directory.

+FRESULT f_mkdir (
+  const char* DirName /* Pointer to the directory name */
+);
+

Parameter

DirName: Pointer to the null-terminated string that specifies the directory name to create.

Return Value

FR_OK (0): The function succeeded.
FR_NO_PATH: Could not find the path.
FR_INVALID_NAME: The path name is invalid.
FR_INVALID_DRIVE: The drive number is invalid.
FR_DENIED: The directory cannot be created due to directory table or disk is full.
FR_EXIST: A file or directory that has same name is already existing.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_WRITE_PROTECTED: The medium is write protected.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_ENABLED: The logical drive has no work area.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Description

The f_mkdir function creates a new directory. This function is not supported in read-only configuration and minimization level of >= 1.

Example

+    res = f_mkdir("sub1");
+    if (res) die(res);
+    res = f_mkdir("sub1/sub2");
+    if (res) die(res);
+    res = f_mkdir("sub1/sub2/sub3");
+    if (res) die(res);
+

f_mkfs

The f_mkfs fucntion creates a file system on the drive.

+FRESULT f_mkfs (
+  BYTE  Drive,            /* Logical drive number */
+  BYTE  PartitioningRule, /* Partitioning rule */
+  BYTE  AllocSize         /* Allocation unit size */
+);
+

Parameters

Drive: Logical drive number (0-9) to be formatted.
PartitioningRule: When 0 is given, a partition table is created into first sector on the drive and then the file system is created on the partition. This is called FDISK format. When 1 is given, the file system starts from the first sector without partition table. This is often called super floppy (SFD) format.
AllocSize: Specifies allocation unit size (number of sectors per cluster). The value must be power of 2 in range of from 1 to 64.

Return Values

FR_OK (0)

The function succeeded.

FR_INVALID_DRIVE

The drive number is invalid.

FR_NOT_READY

The drive cannot work due to any reason.

FR_WRITE_PROTECTED

The drive is write protected.

FR_NOT_ENABLED

The logical drive has no work area.

FR_RW_ERROR

The function failed due to a disk error or an internal error.

FR_MKFS_ABORTED

The function aborted before start in format due to a reason as follows. +

The disk size is too small.
Invalid parameter was given to any parameter.
Not allowable cluster size for this drive. This can occure when number of clusters becomes around 0xFF7 and 0xFFF7.

Description

The f_mkfs function creates a FAT file system on the drive. There are two partitioning rules, FDISK and SFD, for removable media. It can be selected with a parameter and FDISK format is recommended for most case. This function currently does not support multiple partition, so that existing partitions on the physical dirve will be deleted and re-created a partition occupies entire disk space.

The FAT type, FAT12/FAT16/FAT32, is determined by only how many clusters on the drive and nothing else, according to FAT specification. Thus which FAT type is selected, is depends on the drive size and specified cluster size. The cluster size affects performance of file system and large cluster increases the performance, so that 64 sectors per cluster is recommended except for small drive.

This function is supported on only FatFs with _USE_MKFS option.

f_mount

The f_mount fucntion registers/unregisters a work area to the FatFs module.

+FRESULT f_mount (
+  BYTE  Drive,              /* Logical drive number */
+  FATFS*  FileSystemObject  /* Pointer to the work area */
+);
+

Parameters

Drive: Logical drive number (0-9) to register/unregister the work area. Always 0 for Tiny-FatFs.
FileSystemObject: Pointer to the work area (file system object) to be registered.

Return Values

FR_OK (0): The function succeeded.
FR_INVALID_DRIVE: The drive number is invalid.

Description

The f_mount function registers/unregisters a work area to the FatFs module. The work area must be given to the logical drive with this function before using any file function. To unregister a work area, specify a NULL to the FileSystemObject, and then the work area can be discarded.

This function only initializes the work area and registers its address to the internal table, any access to the disk I/O layer does not occure. Actual mounting process is performed in any other file funcitons with path name when it is needed.

References

FATFS

f_mountdrv

The f_mountdrv forces the partition mounted.

+FRESULT f_mountdrv (void);
+

Return Values

FR_OK (0): The function succeeded.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_RW_ERROR: Any error occured in low level disk I/O.
FR_NOT_ENABLED: FatFs module is not enabled.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Description

The f_mountdrv forces the partition mounted (initializes FATFS structure). The file system is initialized automatically in accordance with the necessity when any file function is called. This function should not be used except for recovering FR_INCORRECT_DISK_CHANGE error. Using this function, while any file is opened, can destroy the file system.

In this function, following processes are executed.

Initializes lower level layer (disk I/O module).
Searches a FAT boot record in order of sector 0 (as SFD format) and first primary partition (as FDISK format).
Initializes file system object (FATFS structure).

References

FATFS

f_open

The f_open function creates a file object to be used to access the file.

+FRESULT f_open (
+  FIL* FileObject,      /* Pointer to the blank file object structure */
+  const char* FileName, /* Pointer to the file neme */
+  BYTE ModeFlags        /* Mode flags */
+);
+

Parameters

FileObject

Pointer to the file object structure to be created. After the f_open funciton succeeded, the file can be accessed with the file object structure until it is closed.

FileName

Pointer to a null-terminated string that specifies the file name to create or open.

ModeFlags

Specifies the type of access and open method for the file. It is specified by a combination of following flags.
+ + + + + + + + +

Value	Description
FA_READ	Specifies read access to the object. Data can be read from the file. Combine with FA_WRITE for read-write access.
FA_WRITE	Specifies write access to the object. Data can be written to the file. Combine with FA_READ for read-write access.
FA_OPEN_EXISTING	Opens the file. The function fails if the file is not existing.
FA_OPEN_ALWAYS	Opens the file, if it is existing. If not, the function creates the new file.
FA_CREATE_NEW	Creates a new file. The function fails if the file is already existing.
FA_CREATE_ALWAYS	Creates a new file. If the file is existing, it is truncated and overwritten.

Return Values

FR_OK (0): The function succeeded and the file object is valid.
FR_NO_FILE: Could not find the file.
FR_NO_PATH: Could not find the path.
FR_INVALID_NAME: The file name is invalid.
FR_INVALID_DRIVE: The drive number is invalid.
FR_EXIST: The file is already existing.
FR_DENIED: The required access was denied due to any of following reasons: write mode open of a file that has read-only attribute, file creation under existing a same name directory or read-only file, cannot be created due to the directory table or disk full.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_WRITE_PROTECTED: Write mode open or creation under the medium is write protected.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_ENABLED: The logical drive has no work area.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Description

The created file object is used for subsequent calls to refer to the file. When close an open file object, use f_close function.

Before using any file function, work area (file system object) must be given to each logical drive with f_mount function. All file functions can work after this procedure.

The mode flags, FA_WRITE, FA_CREATE_ALWAYS, FA_CREATE_NEW, FA_OPEN_ALWAYS, are not supported in read-only configuration.

Example (File Copy)

+void main ()
+{
+    FATFS fs;            // Work area (file system object) for logical drive
+    FIL fsrc, fdst;      // file objects
+    BYTE buffer[4096];   // file copy buffer
+    FRESULT res;         // FatFs function common result code
+    WORD br, bw;         // File R/W count
+
+
+    // Register a work area to logical drive 0
+    f_mount(0, &fs);
+
+    // Open source file
+    res = f_open(&fsrc, "srcfile.dat", FA_OPEN_EXISTING | FA_READ);
+    if (res) die(res);
+
+    // Create destination file
+    res = f_open(&fdst, "dstfile.dat", FA_CREATE_ALWAYS | FA_WRITE);
+    if (res) die(res);
+
+    // Copy source to destination
+    for (;;) {
+        res = f_read(&fsrc, buffer, sizeof(buffer), &br);
+        if (res || br == 0) break;      // error or eof
+        res = f_write(&fdst, buffer, br, &bw);
+        if (res || bw < br) break;   // error or disk full
+    }
+
+    // Close all files
+    f_close(&fsrc);
+    f_close(&fdst);
+
+    // Unregister a work area before discard it
+    f_mount(0, NULL);
+}
+

References

f_read, f_write, f_close, FIL, FATFS

f_opendir

The f_opendir function opens a directory.

+FRESULT f_opendir (
+  DIR* DirObject,      /* Pointer to the blank directory object structure */
+  const char* DirName  /* Pointer to the directory name */
+);
+

Parameter

DirObject: Pointer to the blank directory object to be created.
DirName: Pinter to the null-terminated string that specifies the directory name to be opened.

Return Values

FR_OK (0): The function succeeded and the directory object is created. It is used for subsequent calls to read the directory entries.
FR_NO_FILE: Could not find the directory.
FR_NO_PATH: Could not find the path.
FR_INVALID_NAME: The path name is invalid.
FR_INVALID_DRIVE: The drive number is invalid.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_ENABLED: The logical drive has no work area.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Description

The f_opendir function opens an exsisting directory and creates the directory object for subsequent calls. The directory object structure can be discarded at any time without any procedure. This function is not supported in minimization level of >=2.

References

f_readdir, DIR

f_read

The f_read function reads data from a file.

+FRESULT f_read (
+  FIL* FileObject,    /* Pointer to the file object structure */
+  void* Buffer,       /* Pointer to the buffer to store read data */
+  WORD ByteToRead,    /* Number of bytes to read */
+  WORD* ByteRead      /* Pointer to the variable to return number of bytes read */
+);
+

Parameters

FileObject: Pointer to the open file object.
Buffer: Pointer to the buffer to store read data
ByteToRead: Number of bytes to read
ByteRead: Pointer to the WORD variable to return number of bytes read.

Return Values

FR_OK (0): The function succeeded.
FR_DENIED: The function denied due to the file has been opened in write only mode.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_INVALID_OBJECT: The file object is invalid.

Description

The file pointer in the file object increases in number of bytes read. The ByteRead will become less than ByteToRead when the read pointer reached to end of the file or any error occured during the read operation.

References

f_open, f_write, f_close, FIL

f_readdir

The f_readdir function reads directory entries.

+FRESULT f_readdir (
+  DIR* DirObject,    /* Pointer to the directory object structure */
+  FILINFO* FileInfo  /* Pointer to the file information structure */
+);
+

Parameters

DirObject: Pointer to the open directory strcture.
FileInfo: Pointer to the file information structure to store the read item.

Return Values

FR_OK (0): The function succeeded.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_INVALID_OBJECT: The directory object is invalid.

Description

The f_readdir function reads directory entries in sequence. All items in the directory can be read by calling f_readdir function repeatedly. When all directory items have been read and no item to read, the function returns a null string into f_name[] member without any error. For details of the file informations, refer to the FILINFO. This function is not supported in minimization level of >=2.

Sample Code

+void scan_files (char* path)
+{
+    FILINFO finfo;
+    DIR dirs;
+    int i;
+
+    if (f_opendir(&dirs, path) == FR_OK) {
+        i = strlen(path);
+        while ((f_readdir(&dirs, &finfo) == FR_OK) && finfo.fname[0]) {
+            if (finfo.fattrib & AM_DIR) {
+                sprintf(path+i, "/%s", &finfo.fname[0]);
+                scan_files(path);
+                *(path+i) = '\0';
+            } else {
+                printf("%s/%s\n", path, &finfo.fname[0]);
+            }
+        }
+    }
+}
+

References

f_opendir, f_stat, FILINFO, DIR

f_rename

Rename file or directory.

+FRESULT f_rename (
+  const char* OldName, /* Pointer to old file/directory name */
+  const char* NewName  /* Pointer to new file/directory name */
+);
+

Parameter

OldName: Pointer to a null-terminated string specifies the old file/directory name to be renamed.
NewName: Pointer to a null-terminated string specifies the new file/directory name without drive number. Existing object nannot be specified.

Return Values

FR_OK (0): The function succeeded.
FR_NO_FILE: Could not find the file nor directory.
FR_NO_PATH: Could not find the path.
FR_INVALID_NAME: The file name is invalid.
FR_INVALID_DRIVE: The drive number is invalid.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_DENIED: The new name could not be created due to any reason.
FR_WRITE_PROTECTED: The medium is write protected.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_ENABLED: The logical drive has no work area.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Description

Rename a file or directory and can move it to other directory. Logical drive number is determined by old name, new name must not contain logical drive number. This function is not supported in read-only configuration or minimization level of >= 1.

Note: In this revision, moving any directory to other directory collapses the FAT structure on the disk.

Example

+    // Rename file or directory
+    f_rename("oldname.txt", "newname.txt");
+
+    // Rename and move file to other directory simultaneously
+    f_rename("oldname.txt", "dir1/newname.txt");
+

DIR

The DIR structure is used for the work area to read a directory by f_oepndir and f_readdir functions.

FatFs

+typedef struct _DIR {
+    WORD    id;          /* Owner file system mount ID (inverted) */
+    WORD    index;       /* Current index */
+    FATFS*  fs;          /* Pointer to the owner file system object */
+    DWORD   sclust;      /* Start cluster */
+    DWORD   clust;       /* Current cluster */
+    DWORD   sect;        /* Current sector */
+} DIR;
+

Tiny-FatFs

+typedef struct _DIR {
+    WORD    id;          /* Owner file system mount ID (inverted) */
+    WORD    index;       /* Current index */
+    FATFS*  fs;          /* Pointer to the owner file system object */
+    CLUST   sclust;      /* Start cluster */
+    CLUST   clust;       /* Current cluster */
+    DWORD   sect;        /* Current sector */
+} DIR;
+

FATFS

The FATFS structure holds dynamic work area of individual logical drives. It is given by application program and registerd/unregisterd to the FatFs module with f_mount function. Following members are in standard configuration. There is no member that can be changed from the application program.

FatFs

+typedef struct _FATFS {
+    WORD    id;             /* File system mount ID */
+    WORD    n_rootdir;      /* Number of root directory entries */
+    DWORD   winsect;        /* Current sector appearing in the win[] */
+    DWORD   sects_fat;      /* Sectors per fat */
+    DWORD   max_clust;      /* Maximum cluster# + 1 */
+    DWORD   fatbase;        /* FAT start sector */
+    DWORD   dirbase;        /* Root directory start sector (cluster# for FAT32) */
+    DWORD   database;       /* Data start sector */
+    DWORD   last_clust;     /* Last allocated cluster */
+    DWORD   free_clust;     /* Number of free clusters */
+    BYTE    fs_type;        /* FAT type (0:Not mounted) */
+    BYTE    sects_clust;    /* Sectors per cluster */
+    BYTE    n_fats;         /* Number of FAT copies */
+    BYTE    drive;          /* Physical drive number */
+    BYTE    winflag;        /* win[] dirty flag (1:must be written back) */
+    BYTE    pad1;
+    BYTE    win[512];       /* Disk access window for Directory/FAT */
+} FATFS;
+

+ +

Tiny-FatFs

+typedef struct _FATFS {
+    WORD    id;             /* File system mount ID */
+    WORD    n_rootdir;      /* Number of root directory entries */
+    DWORD   winsect;        /* Current sector appearing in the win[] */
+    DWORD   fatbase;        /* FAT start sector */
+    DWORD   dirbase;        /* Root directory start sector */
+    DWORD   database;       /* Data start sector */
+    CLUST   sects_fat;      /* Sectors per fat */
+    CLUST   max_clust;      /* Maximum cluster# + 1 */
+    CLUST   last_clust;     /* Last allocated cluster */
+    CLUST   free_clust;     /* Number of free clusters */
+    BYTE    fs_type;        /* FAT type (0:Not mounted) */
+    BYTE    sects_clust;    /* Sectors per cluster */
+    BYTE    n_fats;         /* Number of FAT copies */
+    BYTE    winflag;        /* win[] dirty flag (1:must be written back) */
+    BYTE    win[512];       /* Disk access window for Directory/FAT/File */
+} FATFS;
+

FIL

The FIL structure (file object) holds state of a file. It is created by f_open function and discarded by f_close function. There is no member that can be changed by the application program.

+ +

FatFs

+typedef struct _FIL {
+    WORD    id;             /* Owner file system mount ID (inverted) */
+    BYTE    flag;           /* File status flags */
+    BYTE    sect_clust;     /* Left sectors in cluster */
+    FATFS*  fs;             /* Pointer to the owner file system object */
+    DWORD   fptr;           /* File R/W pointer */
+    DWORD   fsize;          /* File size */
+    DWORD   org_clust;      /* File start cluster */
+    DWORD   curr_clust;     /* Current cluster */
+    DWORD   curr_sect;      /* Current sector */
+    DWORD   dir_sect;       /* Sector containing the directory entry */
+    BYTE*   dir_ptr;        /* Ponter to the directory entry in the window */
+    BYTE    buffer[512];    /* File R/W buffer */
+} FIL;
+

+ +

Tiny-FatFs

+typedef struct _FIL {
+    WORD    id;             /* Owner file system mount ID (inverted) */
+    BYTE    flag;           /* File status flags */
+    BYTE    sect_clust;     /* Left sectors in cluster */
+    FATFS*  fs;             /* Pointer to owner file system */
+    DWORD   fptr;           /* File R/W pointer */
+    DWORD   fsize;          /* File size */
+    CLUST   org_clust;      /* File start cluster */
+    CLUST   curr_clust;     /* Current cluster */
+    DWORD   curr_sect;      /* Current sector */
+    DWORD   dir_sect;       /* Sector containing the directory entry */
+    BYTE*   dir_ptr;        /* Ponter to the directory entry in the window */
+} FIL;
+

FILINFO

The FILINFO structure holds a file information returned by f_stat() and f_readdir().

+typedef struct _FILINFO {
+    DWORD fsize;            // Size
+    WORD fdate;             // Date
+    WORD ftime;             // Time
+    BYTE fattrib;           // Attribute
+    char fname[8+1+3+1];    // Name
+} FILINFO;
+

Members

f_stat

The f_stat gets the file status.

+FRESULT f_stat (
+  const char* FileName,   /* Pointer to the file or directory name */
+  FILINFO* FileInfo       /* Pointer to the FILINFO structure */
+);
+

Parameters

FileName: Pointer to the null-terminated string that specifies the file or directory to get its information.
FileInfo: Pointer to the blank FILINFO structure to store the information.

Return Values

FR_OK (0): The function succeeded.
FR_NO_FILE: Could not find the file or directory.
FR_NO_PATH: Could not find the path.
FR_INVALID_NAME: The file name is invalid.
FR_INVALID_DRIVE: The drive number is invalid.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_ENABLED: The logical drive has no work area.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Description

The f_stat gets the information of a file or directory. For details of the infomation, refer to the FILINFO structure. This function is not supported in minimization level of >= 1.

References

f_opendir, f_readdir, FILINFO

f_sync

The f_sync function flushes the cached information of a wriiting file.

+FRESULT f_sync (
+  FIL* FileObject     /* Pointer to the file object */
+);
+

Parameters

FileObject: Pointer to the open file object to be flushed.

Return Values

FR_OK (0): The function succeeded.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_INVALID_OBJECT: The file object is invalid.

Description

The f_sync function performs the same process as f_close function but the file is left opened and can continue read/write/seek operations to the file. This is suitable for applications that open files for a long time in writing mode, such as data logger. Performing f_sync of periodic or immediataly after f_write can minimize risk of data loss due to sudden blackout or unintentional disk removal. This function is not supported in read-only configuration.

References

f_close

f_unlink

The f_unlink removes file or directory.

+FRESULT f_unlink (
+  const char* FileName  /* Pointer to the file or directory name */
+);
+

Parameters

FileName: Pointer to the null-terminated string that specifies a file or directory to be removed.

Return Values

FR_OK (0): The function succeeded.
FR_NO_FILE: Could not find the file or directory.
FR_NO_PATH: Could not find the path.
FR_INVALID_NAME: The path name is invalid.
FR_INVALID_DRIVE: The drive number is invalid.
FR_DENIED: The function was denied due to either of following reasons: the file or directory has read-only attribute, the directory is not empty.
FR_NOT_READY: The disk drive cannot work due to no medium in the drive or any other reason.
FR_WRITE_PROTECTED: The medium is write protected.
FR_RW_ERROR: The function failed due to a disk error or an internal error.
FR_NOT_ENABLED: The logical drive has no work area.
FR_NO_FILESYSTEM: There is no valid FAT partition on the disk.

Description

The f_unlink function removes a file or directory. In read-only configuration or minimization level is >= 1, this function is not supported.

f_write

The f_write writes data to a file.

+FRESULT f_write (
+  FIL* FileObject,     /* Pointer to the file object structure */
+  const void* Buffer,  /* Pointer to the data to be written */
+  WORD ByteToWrite,    /* Number of bytes to write */
+  WORD* ByteWritten    /* Pointer to the variable to return number of bytes written */
+);
+