FatFs is a generic FAT/exFAT filesystem module for small embedded systems. The FatFs module is written in compliance with ANSI C (C89) and completely separated from the disk control layer. Therefore it is independent of the platforms and storage devices. It can be incorporated into small microcontrollers with limited resource, such as 8051, PIC, AVR, ARM, Z80, RX and etc. Also Petit FatFs module for tiny microcontrollers is available here.
+
FatFs is a generic FAT/exFAT filesystem module for small embedded systems. The FatFs module is written in compliance with ANSI C (C89) and completely separated from the disk control layer. Therefore it is independent of the platforms and storage devices. It can be incorporated into small microcontrollers with limited resource, such as 8051, PIC, AVR, ARM, Z80, RX and etc. Also Petit FatFs module for tiny microcontrollers is available here🔗.
Features
@@ -130,13 +130,15 @@
The FatFs module is a free software opened for education, research and development. You can use, modify and/or redistribute it for any purpose without any restriction under your responsibility. For further information, refer to the application note.
diff --git a/documents/doc/appnote.html b/documents/doc/appnote.html
index d86ec91..117645b 100644
--- a/documents/doc/appnote.html
+++ b/documents/doc/appnote.html
@@ -106,17 +106,17 @@ The FatFs module is a middleware written in ANSI C (C89). There is no platform d
ARM7 32bit
ARM7 Thumb
CM3 Thumb-2
AVR
H8/300H
PIC24
RL78
V850ES
SH-2A
RX600
IA-32
Compiler
GCC
GCC
GCC
GCC
CH38
C30
CC78K0R
CA850
SHC
RXC
MSC
-
.text (Def, R/W)
10.4k
6.7k
6.1k
12.5k
11.0k
11.4k
13.0k
8.9k
9.2k
6.5k
8.9k
-
.text (Min, R/W)
7.0k
4.7k
4.2k
8.5k
7.6k
7.9k
9.5k
6.3k
6.4k
4.7k
6.4k
-
.text (Def, R/O)
4.9k
3.2k
2.7k
6.1k
5.2k
5.4k
6.5k
4.3k
4.2k
3.2k
4.3k
-
.text (Min, R/O)
3.7k
2.5k
2.1k
4.4k
4.0k
4.2k
5.1k
3.4k
3.3k
2.5k
3.5k
+
.text (Def, R/W)
10.5k
6.7k
6.1k
12.6k
11.0k
11.4k
13.0k
8.9k
9.2k
6.5k
8.9k
+
.text (Min, R/W)
7.0k
4.7k
4.2k
8.5k
7.6k
7.9k
9.4k
6.3k
6.4k
4.7k
6.3k
+
.text (Def, R/O)
4.9k
3.2k
2.8k
6.1k
5.2k
5.5k
6.5k
4.4k
4.2k
3.2k
4.3k
+
.text (Min, R/O)
3.7k
2.5k
2.1k
4.4k
4.0k
4.2k
5.0k
3.4k
3.3k
2.5k
3.4k
.bss
V*4 + 2
V*4 + 2
V*4 + 2
V*2 + 2
V*4 + 2
V*2 + 2
V*2 + 2
V*4 + 2
V*4 + 2
V*4 + 2
V*4 + 2
Work area (FF_FS_TINY == 0)
V*564 + F*552
V*564 + F*552
V*564 + F*552
V*560 + F*546
V*560 + F*546
V*560 + F*546
V*560 + F*546
V*564 + F*552
V*564 + F*552
V*564 + F*552
V*564 + F*552
Work area (FF_FS_TINY == 1)
V*564 + F*40
V*564 + F*40
V*564 + F*40
V*560 + F*34
V*560 + F*34
V*560 + F*34
V*560 + F*34
V*564 + F*40
V*564 + F*40
V*564 + F*40
V*564 + F*40
These are the memory usage of FatFs module without lower layer on some target systems in following condition. V denotes number of mounted volumes and F denotes number of open files. Every samples here are optimezed in code size.
-FatFs R0.15 options:
+FatFs R0.15b options:
FF_FS_READONLY 0 (R/W, read/write) or 1 (R/O, read only)
FF_FS_MINIMIZE 0 (Def, with all basic functions) or 3 (Min, with fully minimized)
FF_FS_TINY 0 (Default) or 1 (Tiny file object)
@@ -202,7 +202,7 @@ And any other options are left unchanged from original setting.
64-bit LBA
LBA (Logical Block Addressing) is an addressing method to specify the location of data block, called sector, on the storage media. It is a simple linear address beginning from 0 as the first sector, 1 as the second sector and so on. The host system does not need to consider how the data block is located and managed in the storage device. FatFs supports only LBA for the media access. 32-bit LBA is a common size in the most LBA scheme. It can address up to 232 sectors, 2 TB in 512 bytes/sector. When a storage device larger than 2 TB is used, larger sector size or 64-bit LBA will be needed to address the entire sectors of the storage device.
-
By default, FatFs works in 32-bit LBA for media access. FatFs can also switch it to 64-bit LBA by a configuration option FF_LBA64. It also enables GPT (GUID Partition Table) for partiotion management on the storage device. For further information about GPT, refer to f_mkfs and f_fdisk function.
+
By default, FatFs works in 32-bit LBA for media access. FatFs can also switch it to 64-bit LBA by a configuration option FF_LBA64. It also enables GPT (GUID Partition Table) for partition management on the storage device. For further information about GPT, refer to f_mkfs and f_fdisk function.
This set of options defines the time to be used in no RTC systems. This option has no effect in read-only configuration or FF_FS_NORTC == 0.
+
FF_FS_CTIME
+
This option enables (1) or disables (0) to access the file creation time with FILINFO structure.
+
FF_FS_NOFSINFO
0 to 3. If you need to know correct free space on the FAT32 volume, set bit 0 of this option, and f_getfree function at first time after the volume mounted will force a full FAT scan. Bit 1 controls the use of last allocated cluster number for new allocation.
The specified memory address is not that always aligned to word boundary because the argument is defined as BYTE*. For more information, refer to the description of disk_read function.
Generally, a multiple sector write request (count > 1) must not be split into single sector transactions to the storage device, or the file write throughput will be drastically decreased.
-
FatFs expects delayed write function in the disk control layer. The write operation to the media does not need to be completed when return from this function by what write operation is in progress or data is only stored into the write-back cache. The write data on the buff is invalid after return from this function. The write completion request is done by CTRL_SYNC command of disk_ioctl function. Therefore, if a delayed write function is implemented, the write throughput of the filesystem will be improved.
+
FatFs expects the disk control layer may have a delayed write feature. The write operation to the media does not need to be completed when return from this function by what media write operation is in progress or data is stored into the write-back cache. The write data on the buff is invalid after return from this function. The write completion request is done by CTRL_SYNC command of disk_ioctl function. Therefore, if a delayed write feature is implemented, the write throughput of the filesystem will be improved.
Remarks: Application program MUST NOT call this function, or FAT structure on the volume can be collapsed.
????* - An any string in length of four characters or longer.
-
Since the matching algorithm uses recursion, number of wildcards in the matching pattern is limited to four to limit the stack usage. Any pattern with too many wildcards does not match any name. In LFN configuration, only fname[] is tested when FF_USE_FIND == 1 and also altname[] is tested when FF_USE_FIND == 2. There are some differences listed below between FatFs and standard systems in matching condition.
+
Since the matching algorithm uses recursion, number of wildcards in the matching pattern is limited to four to limit the stack usage. The pattern with too many wildcards does not match any name. In LFN configuration, only fname[] is tested when FF_USE_FIND == 1 and also altname[] is tested when FF_USE_FIND == 2. There are some differences listed below between FatFs and standard systems in matching condition.
"*.*" does not match any name without extension while it matches any name with or without extension in standard systems.
-
Any pattern terminated with a dot does not match any name while it matches the name without extensiton in standard systems.
+
The pattern terminated with a dot does not match any name while it matches the name without extensiton in standard systems.
DBCS extended characters are compared in case-sensitive when LFN is enabled with !FF_LFN_UNICODE.
End of file. The specified ofs was clipped at end of the file in read-only mode.
Disk full. There is no free space on the volume to expand the file.
-
The fast seek feature enables fast backward/long seek operations without FAT access by using an on-memory CLMT (cluster link map table). It is applied to f_read and f_write function as well, however, the file size cannot be expanded by f_write, f_lseek function while the file is at fast seek mode.
-
The fast seek mode is available when FF_USE_FASTSEEK = 1. The CLMT must be created into the DWORD array prior to use the fast seek mode. To create the CLMT, set address of the DWORD array to the member cltbl in the open file object, set the size of array in unit of items to the cltbl[0] and then call f_lseek function with ofs = CREATE_LINKMAP. After the function succeeded, no FAT access is occured in subsequent f_read, f_write, f_lseek function to the file. The number of items used or required is returned into the cltbl[0]. The number of items needed is (number of the file fragments + 1) * 2. For example, 12 items in the array will be used for the file fragmented in 5 portions. If the function failed with FR_NOT_ENOUGH_CORE, the size of given array is insufficient for the file.
+
The fast seek feature enables fast backward/long seek operations without FAT access by using an on-memory CLMT (cluster link map table). It is applied to f_read and f_write function as well, however, the file size cannot be expanded by f_write, f_lseek function while the file is in fast seek mode.
+
The fast seek mode is available when FF_USE_FASTSEEK = 1. The CLMT must be created into a DWORD array prior to use the fast seek mode. To create the CLMT, set address of the DWORD array to the member cltbl in the open file object, set the size of array in unit of items to the cltbl[0] and then call f_lseek function with ofs = CREATE_LINKMAP. The number of items used or required is returned into the cltbl[0]. The number of items needed is (number of the file fragments + 1) * 2. For example, 12 items in the array will be used for the file fragmented in 5 portions. If the function failed with FR_NOT_ENOUGH_CORE, the size of given array is insufficient for the file. After the function succeeded, no FAT access is occured in subsequent f_read, f_write, f_lseek function to the file. To disable the fast seek mode, set null pointer to the cltbl.
Specifies number of FAT copies on the FAT/FAT32 volume. Valid value for this member is 1 or 2. The default value (0) and any invaid value gives 1. If the FAT type is exFAT, this member has no effect.
UINT align
-
Specifies alignment of the volume data area (file allocation pool, usually erase block boundary of flash memory media) in unit of sector. The valid value for this member is between 1 and 32768 inclusive in power of 2. If a zero (the default value) or any invalid value is given, the function obtains the block size from lower layer with disk_ioctl function.
+
Specifies alignment of the volume data area (file allocation pool, usually erase block boundary of flash memory media) in unit of sector. The valid value for this member is between 1 and 32768 inclusive in power of 2. If a zero (the default value) or an invalid value is given, the function obtains the block size from lower layer with disk_ioctl function.
UINT n_root
Specifies number of root directory entries on the FAT volume. Valid value for this member is up to 32768 and aligned to sector size / 32. The default value (0) and any invaid value gives 512. If the FAT type is FAT32 or exFAT, this member has no effect.
DWORD au_size
-
Specifies size of the cluster (allocation unit) in unit of byte. The valid value for this member is between sector size and 128 * sector size inclusive in power of 2 for FAT/FAT32 volume and up to 16 MB in power of 2 for exFAT volume. If a zero (default value) or any invalid value is given, the function uses a default cluster size depends on the volume size.
+
Specifies size of the cluster (allocation unit) in unit of byte. The valid value for this member is between sector size and 128 * sector size inclusive in power of 2 for FAT/FAT32 volume and up to 16 MB in power of 2 for exFAT volume. If a zero (default value) or an invalid value is given, the function uses a default cluster size depends on the volume size.
work
Pointer to the working buffer used for the format process. If a null pointer is given with FF_USE_LFN == 3, the function uses a len bytes of heap memory in this function.
@@ -68,8 +68,8 @@ FRESULT f_mkfs (
The allocation unit, also known as cluster, is a unit of disk space allocation for files. When the size of allocation unit is 32768 bytes, a file with 100 bytes in size occupies 32768 bytes of disk space. The space efficiency of disk usage gets worse as increasing size of allocation unit, but, on the other hand, the read/write performance increases. Therefore the size of allocation unit is a trade-off between space efficiency and performance. For the large volumes in GB order, 32768 bytes or larger, automatically selected by default, is recommended for most case unless extremely many small files are created in the volume.
When the logical drive to be formatted is associated with a physical drive (FF_MULTI_PARTITION == 0 or VolToPart[].pt == 0) and FM_SFD flag is not specified, a partition occupies entire drive space is created and then the FAT volume is created in the partition. When FM_SFD flag is specified, the FAT volume is created without any disk partitioning.
When the logical drive to be formatted is associated with a specific partition by multiple partition feature (FF_MULTI_PARTITION == 1 and VolToPart[].pt > 0), the FAT volume is created in the partition of the physical drive specified by volume mapping table and FM_SFD flag is ignored. The hosting physical drive needs to be partitioned with f_fdisk function or some partitioning tool prior to create the FAT volume with this function. If the partition is not exist, the function fails with FR_MKFS_ABORTED.
-
There are three standard disk partitioning formats, MBR, GPT and SFD. The MBR format, also known as FDISK format, is usually used for harddisk, memory card and U disk. It can divide a physical drive into one or more partitions with a partition table. The GPT, GUID Partition Table, is a newly defined patitioning format for large storage devices. FatFs suppors the GPT only when 64-bit LBA is enabled. The SFD, Super-Floppy Disk, is non-partitioned disk format. The FAT volume is located at LBA 0 and occupies the entire physical drive without any disk partitioning. It is usually used for floppy disk, optical disk and most super-floppy media. Some combination of systems and media support only either partitioned format or non-partitioned format and the other is not supported.
-
Some systems manage the partitions in the on-board storage in non-standard format. The partitions are mapped as physical drives identified by pdrv in disk_* functions. For such systems, SFD format is suitable to create the FAT volume in the partition.
+
There are three standard disk partitioning formats, MBR, GPT and SFD. The MBR format, also known as FDISK format, is usually used for harddisk, memory card and U disk. It can divide a physical drive into one or more partitions with a partition table. The GPT, GUID Partition Table, is a newly defined patitioning format for large storage devices. FatFs suppors the GPT only when 64-bit LBA is enabled. The SFD, Super-Floppy Disk, is non-partitioned disk format. The FAT volume is located at LBA 0 and occupies the entire physical drive without disk partitioning. It is usually used for floppy disk, optical disk and most super-floppy media. Some combination of systems and media support only either partitioned format or non-partitioned format and the other is not supported.
+
Some systems manage the partitions of on-board storage in non-standard format. The partitions are mapped as physical drives identified by pdrv in disk_* functions. For such systems, SFD format is suitable to create the FAT volume in the partition.
diff --git a/documents/doc/readdir.html b/documents/doc/readdir.html
index 5550cee..7feb32d 100644
--- a/documents/doc/readdir.html
+++ b/documents/doc/readdir.html
@@ -86,16 +86,16 @@ FRESULT list_dir (const char *path)
int nfile, ndir;
- res = f_opendir(&dir, path); /* Open the directory */
+ res = f_opendir(&dir, path); /* Open the directory */
if (res == FR_OK) {
nfile = ndir = 0;
for (;;) {
- res = f_readdir(&dir, &fno); /* Read a directory item */
- if (res != FR_OK || fno.fname[0] == 0) break; /* Error or end of dir */
- if (fno.fattrib & AM_DIR) { /* Directory */
+ res = f_readdir(&dir, &fno); /* Read a directory item */
+ if (fno.fname[0] == 0) break; /* Error or end of dir */
+ if (fno.fattrib & AM_DIR) { /* It is a directory */
printf(" <DIR> %s\n", fno.fname);
ndir++;
- } else { /* File */
+ } else { /* It is a file */
printf("%10u %s\n", fno.fsize, fno.fname);
nfile++;
}
@@ -121,18 +121,18 @@ FRESULT scan_files (
static FILINFO fno;
- res = f_opendir(&dir, path); /* Open the directory */
+ res = f_opendir(&dir, path); /* Open the directory */
if (res == FR_OK) {
for (;;) {
- res = f_readdir(&dir, &fno); /* Read a directory item */
- if (res != FR_OK || fno.fname[0] == 0) break; /* Break on error or end of dir */
- if (fno.fattrib & AM_DIR) { /* It is a directory */
+ res = f_readdir(&dir, &fno); /* Read a directory item */
+ if (fno.fname[0] == 0) break; /* Break on error or end of dir */
+ if (fno.fattrib & AM_DIR) { /* The item is a directory */
i = strlen(path);
sprintf(&path[i], "/%s", fno.fname);
- res = scan_files(path); /* Enter the directory */
+ res = scan_files(path); /* Enter the directory */
if (res != FR_OK) break;
path[i] = 0;
- } else { /* It is a file. */
+ } else { /* The item is a file. */
printf("%s/%s\n", path, fno.fname);
}
}
diff --git a/documents/doc/setlabel.html b/documents/doc/setlabel.html
index 8812d53..64e7908 100644
--- a/documents/doc/setlabel.html
+++ b/documents/doc/setlabel.html
@@ -55,7 +55,7 @@ FRESULT f_setlabel (
Allowable characters for exFAT volume are: characters allowed for LFN includes dot. Low-case characters are preserved.
Spaces can be embedded anywhere in the volume label. Trailing spaces are truncated off at FAT volume.
-
Remark: The standard system (Windows) has a problem at the volume label with a heading \xE5 on the FAT volume. To avoid this problem, this function rejects such volume label as invalid name.
+
Remark: The standard system (Windows) has a problem in the volume label with a heading \xE5 on the FAT volume. To avoid this problem, this function rejects such volume label as invalid name.
diff --git a/documents/doc/sfileinfo.html b/documents/doc/sfileinfo.html
index 0e0ba91..e1fe1d2 100644
--- a/documents/doc/sfileinfo.html
+++ b/documents/doc/sfileinfo.html
@@ -17,6 +17,10 @@
FSIZE_t fsize; /* File size */
WORD fdate; /* Last modified date */
WORD ftime; /* Last modified time */
+#if FF_FS_CRTIME
+ WORD crdate; /* Created date */
+ WORD crtime; /* Created time */
+#endif
BYTE fattrib; /* Attribute */#if FF_USE_LFN
TCHAR altname[FF_SFN_BUF + 1]; /* Alternative object name */
@@ -54,6 +58,12 @@
Second / 2 (0..29)
+
crdate
+
The date when the file/directory was created. This member is available when FF_FS_CRTIME = 1.
+
+
crtime
+
The time when the file/directory was created. This member is available when FF_FS_CRTIME = 1
+
fattrib
The attribute flags in combination of:
@@ -66,7 +76,7 @@
fname[]
-
Null-terminated object name. A null string is stored when no item to read and it indicates this structure is invalid. The size of fname[] and altname[] each can be configured in LFN configuration.
+
Null-terminated object name is stored. If no item to read or an error occured in the function, a null string is stored to indicate this structure is invalid. The size of fname[] and altname[] each can be configured in LFN configuration.
altname[]
Alternative object name is stored if available. This member is not available in non-LFN configuration.
FRESULT f_utime (
const TCHAR* path, /* [IN] Object name */
- const FILINFO* fno/* [IN] Time and data to be set */
+ const FILINFO* fno/* [IN] Time and date to be set */
);
@@ -26,7 +26,7 @@ FRESULT f_utime (
path
Pointer to the null-terminated string that specifies an object to be changed. If a null pointer is given, the function fails with FR_INVALID_DRIVE.
fno
-
Pointer to the file information structure that has a timestamp to be set in member fdate and ftime. Do not care any other members.
+
Pointer to the file information structure that has new timestamps to be set in the members. fdate and ftime are for the last modified time. When FF_FS_CRTIME = 1, crdate and crtime for the created time are available in addition. Every timestamp is in local time. If fdate or crdate is invalid (0), the modified time or created time is left unchanged respectively. Do not care any other member.
@@ -61,7 +61,7 @@ FRESULT f_utime (
Example
FRESULT set_timestamp (
- char *obj, /* Pointer to the file name */
+ const char *fname, /* Pointer to the file name */
int year,
int month,
int mday,
@@ -74,8 +74,10 @@ FRESULT set_timestamp (
fno.fdate = (WORD)(((year - 1980) * 512U) | month * 32U | mday);
fno.ftime = (WORD)(hour * 2048U | min * 32U | sec / 2U);
-
- return f_utime(obj, &fno);
+#if FF_FS_CRTIME
+ fno.crdate = 0; /* Do not change created time in this code */
+#endif
+ return f_utime(fname, &fno);
}
+Added support for timestamp of created time. (FF_FS_CRTIME)
+Fixed FatFs fails to load the FsInfo in FAT32 volumes and the f_getfree always be forced a full FAT scan which takes a long time. (appeared at R0.15a)
+
+
+Small changes to the f_utime function to support for the timestamp of created time.
+
+
+
+
+
R0.15a Nov 22, 2024
+
+Fixed a complie error when FF_FS_LOCK != 0. (appeared at R0.15)
+Fixed a potential issue when work FatFs concurrency with FF_FS_REENTRANT, FF_VOLUMES >= 2 and FF_FS_LOCK > 0.
+Made f_setlabel accept a volume label with Unix style volume ID when FF_STR_VOLUME_ID == 2.
+Made FatFs update PercInUse field in exFAT VBR. (A preceding f_getfree is needed for the accuracy)
+
+
+
+
+
R0.15 Nov 6, 2022
@@ -27,6 +51,7 @@ User provided synchronization functions, ff_cre_syncobj, ff_del_syn
FF_SYNC_t is removed from the configuration options.
+
R0.14b Apr 17, 2021
@@ -43,6 +68,7 @@ Fixed some compiler warnings.
From this revision, FatFs depends on string.h.
+
R0.14a Dec 05, 2020
@@ -54,6 +80,7 @@ Fixed some compiler warnings.
Number of wildcards in the matching pattern in f_findfirst is limited to 4.
+
R0.14 Oct 14, 2019
@@ -68,6 +95,7 @@ Fixed f_mkfs can fail to create exFAT volume in the second partition. (
Usage of f_mkfs and f_fdisk is changed and some features are added to these functions.
+
R0.13c Oct 14, 2018
@@ -81,6 +109,7 @@ From this revision, FatFs depends on stdint.h in C99 or later. integer.h is removed.
+
R0.13b Apr 07, 2018
@@ -92,6 +121,7 @@ Fixed f_setlabel does not reject some invalid characters. (appeared at
+
R0.13a Oct 14, 2017
@@ -105,6 +135,7 @@ Fixed f_setlabel rejects some valid characters for exFAT volume. (appea
+
R0.13 May 21, 2017
@@ -121,6 +152,7 @@ Fixed creating a file can fail when a new cluster allocation to the exFAT direct
ASCII only configuration, FF_CODE_PAGE = 1, is removed. Use FF_CODE_PAGE = 437 instead.
+
R0.12c Mar 04, 2017
@@ -132,6 +164,7 @@ Fixed configuration option _VOLUMES cannot be set 10. (appeared at R0.1
+
R0.12b Sep 4, 2016
@@ -147,6 +180,7 @@ Fixed some internal errors in f_expand and f_lseek. (appeared
+
R0.12a Jul 10, 2016
@@ -161,6 +195,7 @@ Fixed compilation fails at some configurations, _USE_FASTSEEK and _
Usage of f_mkfs is changed.
+
R0.12 Apr 12, 2016
@@ -180,6 +215,7 @@ To use f_chmod, _USE_CHMOD needs to be set. _WORD_ACCESS is removed from the configuration options.
+
R0.11a Sep 5, 2015
@@ -192,6 +228,7 @@ Fixed errors in the case conversion teble of Unicode (cc*.c).
Removed some code pages actually not exist on the standard systems. (_CODE_PAGE)
+
R0.11 Feb 9, 2015
@@ -202,6 +239,7 @@ Fixed _FS_NORTC option does not work properly. (appeared at R0.10c)
+
R0.10c Nov 9, 2014
@@ -213,6 +251,7 @@ Fixed null pointer dereference on attempting to delete the root direcotry. (appe
+
R0.10b May 19, 2014
@@ -222,6 +261,7 @@ Fixed LFN entry is not deleted on delete/rename an object with its lossy convert
+
R0.10a Jan 15, 2014
@@ -236,6 +276,7 @@ Fixed creation of a directory entry with LFN fails on too many SFN collisions. (
+
R0.10 Oct 2, 2013
@@ -252,6 +293,7 @@ Fixed f_open, f_mkdir and f_setlabel can return incor
+
R0.09b Jan 24, 2013
@@ -260,6 +302,7 @@ Added f_getlabel and f_setlabel. (_USE_LABEL)
+
R0.09a Aug 27, 2012
@@ -270,6 +313,7 @@ Changed option name _FS_SHARE to _FS_LOCK.
-