There are many options to configure the features of FatFs for various requirements of each project. The configuration options are defined in ffconf.h.
Read/Write (0) or Read-only (1). Read-only configuration removes writing API functions, f_write, f_sync, f_unlink, f_mkdir, f_chmod, f_rename, f_truncate, f_getfree and optional writing functions as well.
This option defines minimization level to remove some basic API functions as follows:
| Value | Description |
|---|---|
| 0 | All basic API functions are available. |
| 1 | f_stat, f_getfree, f_unlink, f_mkdir, f_chmod, f_utime, f_truncate and f_rename function are removed. |
| 2 | f_opendir, f_readdir and f_closedir function are removed in addition to 1. |
| 3 | f_lseek function is removed in addition to 2. |
Disable (0) or Enable (1) filtered directory read functions, f_findfirst and f_findnext. Also FF_FS_MINIMIZE needs to be 0 or 1.
Disable (0) or Enable (1) f_mkfs function.
Disable (0) or Enable (1) fast seek function to enable accelerated mode for f_lseek, f_read and f_write function. For more information, read here.
Disable (0) or Enable (1) f_expand function.
Disable (0) or Enable (1) metadata control functions, f_chmod and f_utime. Also FF_FS_READONLY needs to be 0.
Disable (0) or Enable (1) API functions for volume label, f_getlabel and f_setlabel.
Disable (0) or Enable (1) f_forward function.
This option switches string functions, f_gets, f_putc, f_puts and f_printf. These functions are equivalents of regular string stream I/O functions in POSIX. If sprintf is available and code conversion is not needed, f_write with sprintf will be efficient in code size and performance rather than f_printf. When enable this feature, stdarg.h is included in ff.c.
| Value | Description |
|---|---|
| 0 | Disable string functions. |
| 1 | Enable string functions without LF-CRLF conversion. |
| 2 | Enable string functions with LF-CRLF conversion. |
This option switches support for long long integer argument in f_printf.
Disable (0) or Enable (1). When enable this feature, C standard needs to be C99 or later.
This option switches support for floating point argument in f_printf. When enable this feature, C standard needs to be C99 or later and math.h is included in ff.c.
| Value | Description |
|---|---|
| 0 | Disable floating point argument. |
| 1 | Enable floating point argument in type 'f', 'e' and 'E'. |
| 2 | Enable it with decimal separator ',' instead of '.'. |
When character encoding on the API is Unicode (FF_LFN_UNICODE >= 1), string I/O functions enabled by FF_USE_STRFUNC convert the character encoding in it. This option defines the assumption of character encoding on the file to be read/written via those functions. When LFN is not enabled or FF_LFN_UNICODE == 0, the string functions work without any code conversion and this option has no effect.
| Value | Character encoding on the file |
|---|---|
| 0 | ANSI/OEM in current code page |
| 1 | Unicode in UTF-16LE |
| 2 | Unicode in UTF-16BE |
| 3 | Unicode in UTF-8 |
This option specifies the OEM code page used on the target system. Incorrect setting of the code page can cause a file open failure. If any non-ASCII character is not used for the path name or FF_LFN_UNICODE != 0, there is no difference between any code page settings. Set it 437 anyway.
| Value | Code page |
|---|---|
| 0 | Includes all code pages below and set by f_setcp() |
| 437 | U.S. |
| 720 | Arabic |
| 737 | Greek |
| 771 | KBL |
| 775 | Baltic |
| 850 | Latin 1 |
| 852 | Latin 2 |
| 855 | Cyrillic |
| 857 | Turkish |
| 860 | Portuguese |
| 861 | Icelandic |
| 862 | Hebrew |
| 863 | Canadian French |
| 864 | Arabic |
| 865 | Nordic |
| 866 | Russian |
| 869 | Greek 2 |
| 932 | Japanese (DBCS) |
| 936 | Simplified Chinese (DBCS) |
| 949 | Korean (DBCS) |
| 950 | Traditional Chinese (DBCS) |
This option switches the support for long file name (LFN). When enable the LFN, Unicode support module ffunicode.c need to be added to the project. When use stack for the working buffer, take care on stack overflow. When use heap memory for the working buffer, memory management functions (ff_memalloc and ff_memfree) need to be added to the project.
| Value | Description |
|---|---|
| 0 | Disable LFN. Path name in only 8.3 format can be used. |
| 1 | Enable LFN with static working buffer on the BSS. Always NOT thread-safe. |
| 2 | Enable LFN with dynamic working buffer on the STACK. |
| 3 | Enable LFN with dynamic working buffer on the HEAP. |
LFN function requiers certain internal working buffer for the file name. This option defines size of the buffer and the value can be in range of 12 to 255 characters (actually in UTF-16 code units) of the LFN. The buffer occupies (FF_MAX_LFN + 1) * 2 bytes and additional (FF_MAX_LFN + 44) / 15 * 32 bytes when exFAT is enabled. It is recommended to be set 255 to fully support the LFN specification. This option has no effect when LFN is not enabled.
This option switches character encoding for the file name on the API. FatFs supports the code point up to U+10FFFF. This option also affects behavior of string I/O functions (see FF_STRF_ENCODE).
| Value | Character Encoding | TCHAR |
|---|---|---|
| 0 | ANSI/OEM in current CP | char |
| 1 | Unicode in UTF-16 | WCHAR |
| 2 | Unicode in UTF-8 | char |
| 3 | Unicode in UTF-32 | DWORD |
When Unicode is selected, FF_CODE_PAGE has actually no meaning except for compatibility with legacy systems, such as MS-DOS and any system without support for LFN.
When LFN is not enabled, this option has no effect and FatFs works in ANSI/OEM code on the API. For more information, read here.
This set of options defines size of file name members, fname[] and altname[], in the FILINFO structure which is used to read out the directory items. These values should be suffcient for the file names to read. The maximum possible length of read file name depends on the character encoding scheme on the API as follows:
| Encoding | LFN length | SFN length |
|---|---|---|
| ANSI/OEM in SBCS | 255 items | 12 items |
| ANSI/OEM in DBCS | 510 items | 12 items |
| Unicode in UTF-16/32 | 255 items | 12 items |
| Unicode in UTF-8 | 765 items | 34 items |
If the size of name member is insufficient for the LFN, the item is treated as without LFN. When LFN is not enabled, these options have no effect.
This option configures relative path function. For more information, read here.
| Value | Description |
|---|---|
| 0 | Disable relative path and remove related functions. |
| 1 | Enable relative path. f_chdir and f_chdrive function is available. |
| 2 | f_getcwd function is available in addition to 1 |
This option configures number of volumes (logical drives up to 10) to be used.
This option switches the support for string volume ID. When arbitrary string for the volume ID is enabled for the drive prefix, also pre-defined strings by FF_VOLUME_STRS or user defined strings can be used as drive prefix in the path name. Numeric drive number is always valid regardless of this option, and also either format of drive prefix can be enabled by this option.
| Value | Description | Example |
|---|---|---|
| 0 | Only DOS/Windows style drive prefix in numeric ID can be used. | 1:/filename |
| 1 | Also DOS/Windows style drive prefix in string ID can be used. | flash:/filename |
| 2 | Also Unix style drive prefix in string ID can be used. | /flash/filename |
This option defines the volume ID strings for each logical drives. Number of items must not be less than FF_VOLUMES. Valid characters for the volume ID string are A-Z, a-z and 0-9, however, they are compared in case-insensitive. If FF_STR_VOLUME_ID == 0, this option has no effect. If FF_STR_VOLUME_ID >= 1 and this option is not defined, a user defined volume string table needs to be defined as shown below. The table should not be modified on the fly.
/* User defined volume ID strings for 0: to 3: */
const char* VolumeStr[FF_VOLUMES] = {"ram","flash","sd","usb"};
Disable (0) or Enable (1). This option switches multi-partition function. By default (0), each logical drive number is bound to the same physical drive number and only a volume in the physical drive is mounted. When enabled, each logical drive is bound to the partition on the physical drive listed in the user defined partition resolution table VolToPart[]. Also f_fdisk funciton will be available. For more information, read here.
This set of options defines the extent of sector size used for the low level disk I/O interface, disk_read and disk_write function. Valid values are 512, 1024, 2048 and 4096. FF_MIN_SS defines minimum sector size and FF_MAX_SS defines the maximum sector size. Always set both 512 for memory card and harddisk. But a larger value may be required for on-board flash memory and some type of optical media. When FF_MAX_SS > FF_MIN_SS, support of variable sector size is enabled and GET_SECTOR_SIZE command needs to be implemented to the disk_ioctl function.
This option switches media access interface to 64-bit LBA and enables GUID Partition Table (GPT) for partition management, Enabled (1) or Disabled (0). exFAT filesystem needs to be enabled to enable this feature.
This option specifies the threshold of determination of partitioning format when create patitions on the drive in f_mkfs and f_fdisk function. When number of available sectors is equal or larger than this value, the drive will be partitioned in GPT. This option has no effect when FF_LBA64 == 0.
Disable (0) or Enable (1). This option switches ATA-TRIM function. To enable Trim function, also CTRL_TRIM command should be implemented to the disk_ioctl function.
Normal (0) or Tiny (1). The tiny configuration reduces size of the FIL structure, file object, FF_MAX_SS bytes each. Instead of private sector buffer eliminated from the file object, common sector buffer in the FATFS structure, filesystem object, is used for the file data transfer.
This option switches support for exFAT filesystem in addition to the FAT/FAT32 filesystem, Enabled (1) or Disabled (0). To enable exFAT, also LFN must be enabled and configureing FF_LFN_UNICODE >= 1 and FF_MAX_LFN == 255 is recommended for full-featured exFAT function. Note that enabling exFAT discards ANSI C (C89) compatibility and wants C99 because of need for 64-bit integer type.
Use RTC (0) or Do not use RTC (1). This option controls timestamp featuer. If the system does not have an RTC or valid timestamp is not needed, set FF_FS_NORTC to 1 to disable the timestamp function. Every objects modified by FatFs will have a constant timestamp defined by FF_NORTC_MON, FF_NORTC_MDAY and FF_NORTC_YEAR. To use the timestamp featuer, set FF_FS_NORTC == 0 and add get_fattime function to the project to get current time form the RTC. This option has no effect in read-only configuration.
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.
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.
| Value | Description |
|---|---|
| bit0=0 | Use free cluster count in the FSINFO if available. |
| bit0=1 | Do not trust free cluster count in the FSINFO. |
| bit1=0 | Use last allocated cluster number in the FSINFO to find a free cluster if available. |
| bit1=1 | Do not trust last allocated cluster number in the FSINFO. |
This option switches file lock feature to control duplicated file open and illegal operations to the open objects. Note that this feature is independent of re-entrancy. This option must be 0 in read-only configuration.
| Value | Description |
|---|---|
| 0 | Disable file lock feature. To avoid to collapse files due to wrong file operations, application program needs to avoid illegal open, remove and rename to the open objects. |
| >0 | Enable file lock feature. The value defines how many files/sub-directories can be opened simultaneously under the file lock feature. Illigal operations to the open object will be rejected with FR_LOCKED. |
Disable (0) or Enable (1). This option switches the re-entrancy (thread safe) of the FatFs module itself. Note that file/directory access to the different volume is always re-entrant and it can work simultaneously regardless of this option, however, volume management functions, f_mount, f_mkfs and f_fdisk, are always not re-entrant. Only file/directory access to the same volume, in other words, exclusive use of each filesystem object, is under control in this feature. To enable this feature, also user provided synchronization handlers, ff_mutex_take, ff_mutex_give, ff_mutex_create and ff_mutex_delete, need to be added to the project. Sample code is available in ffsystem.c.
Number of O/S time ticks to abort the file function with FR_TIMEOUT when the wait time exceeds this period. This option has no effect when FF_FS_REENTRANT == 0.