Multiple volumes (physical drives and partitions).
-
Multiple ANSI/OEM code pages including DBCS.
-
Long file name in ANSI/OEM or Unicode.
+
Long file name in ANSI/OEM, UTF-16 or UTF-8.
exFAT filesystem.
-
RTOS envilonment.
-
Fixed or variable sector size.
+
Thread safe for RTOS.
+
Multiple volumes (physical drives and partitions).
+
Variable sector size.
+
Multiple code pages including DBCS.
Read-only, optional API, I/O buffer and etc...
@@ -119,7 +119,7 @@
Resources
The FatFs module is a free software opened for education, research and development. You can use, modify and/or redistribute it for personal projects or commercial products without any restriction under your responsibility. For further information, refer to the application note.
The FatFs module is assuming following conditions on portability.
ANSI C
@@ -40,13 +40,13 @@ The FatFs module is a middleware written in ANSI C (C89). There is no platform d
The FatFs module assumes that size of char/short/long are 8/16/32 bit and int is 16 or 32 bit. These correspondence are defined in integer.h. This will not be a problem on most compilers. When a conflict with existing definitions is occured, you must resolve it with care.
-
System organizations
+
System Organizations
The dependency diagram shown below is a typical but not specific configuration of the embedded system with FatFs module.
(a) If a working disk module with FatFs disk interface is provided, nothing else will be needed. (b) To attach existing disk drivers with different interface, glue functions are needed to translate the interfaces between FatFs and the drivers.
-
Required functions
+
Required Functions
You need to provide only low level disk I/O functions required by FatFs module and nothing else. If a working disk module for the target system is already provided, you need to write only glue functions to attach it to the FatFs module. If not, you need to port another disk I/O module or write it from scratch. Most of defined functions are not that always required. For example, any write function is not required at read-only configuration. Following table shows which function is required depends on the configuration options.
Function
Required when
Note
@@ -81,17 +81,17 @@ The FatFs module assumes that size of char/short/long
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 (Full, R/W)
10.3k
6.7k
6.3k
12.4k
9.9k
11.4k
13.1k
8.7k
9.0k
6.5k
8.6k
-
text (Min, R/W)
6.9k
4.7k
4.4k
8.4k
6.9k
8.0k
9.4k
6.2k
6.2k
4.6k
6.1k
-
text (Full, R/O)
4.7k
3.1k
2.8k
5.7k
4.7k
5.4k
6.4k
4.2k
4.0k
3.1k
4.1k
-
text (Min, R/O)
3.6k
2.4k
2.2k
4.4k
3.6k
4.2k
5.0k
3.3k
3.1k
2.4k
3.2k
+
text (Full, R/W)
10.4k
6.7k
6.3k
12.4k
9.9k
11.2k
13.0k
8.7k
9.0k
6.5k
8.9k
+
text (Min, R/W)
7.0k
4.7k
4.4k
8.4k
6.9k
7.8k
9.4k
6.0k
6.2k
4.6k
6.3k
+
text (Full, R/O)
4.8k
3.1k
2.8k
5.7k
4.7k
5.3k
6.4k
4.2k
4.0k
3.1k
4.2k
+
text (Min, R/O)
3.6k
2.4k
2.2k
4.4k
3.6k
4.1k
5.0k
3.3k
3.1k
2.4k
3.3k
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 on some target systems with following condition. The memory sizes are in unit of byte, V denotes option FF_VOLUMES and F denotes number of open files. All samples here are optimezed in code size.
-FatFs R0.13 options:
+FatFs R0.13a options:
FF_FS_READONLY 0 (R/W) or 1 (R/O)
FF_FS_MINIMIZE 0 (Full, with all basic functions) or 3 (Min, with fully minimized)
FF_FS_TINY 0 (Default) or 1 (Tiny file object)
@@ -155,20 +155,20 @@ And other options are left unchanged from original setting.
950 (Traditional Chinese)
+111k
0 (All code pages)
+486k
-
When the LFN is enabled, the module size will be increased depends on the configured code page. Right table shows increment of code size by LFN function at different code pages. Especially, in the CJK region, tens of thousands of characters are being used. Unfortunately, it requires a huge OEM-Unicode bidirectional conversion table and the module size will be drastically increased as shown in the table. As the result, the FatFs with LFN enebled with those code pages will not able to be ported on the most 8-bit MCU systems.
+
When the LFN is enabled, the module size will be increased depends on the configured code page. Right table shows increment of code size by LFN function at different code pages. Especially, in the CJK region, tens of thousands of characters are being used. Unfortunately, it requires a huge OEM-Unicode bidirectional conversion table and the module size will be drastically increased as shown in the table. As the result, the FatFs with LFN enebled with those code pages will not able to be ported on the most 8-bit MCU systems. If you can discard ANSI/OEM code API and compatibility with non-ASCII SFN, you will able to configure FatFs for Unicode API with any SBCS.
There ware some restrictions on using LFN for open source project because the support for LFN on the FAT volume was a patent of Microsoft Corporation. The related patents have expired and using the LFN function have got free for any projects.
Unicode API
-
By default, FatFs uses ANSI/OEM code set on the API even at LFN configuration. FatFs can also switch the character encoding on the API to Unicode by configuration option FF_LFN_UNICODE. This means that FatFs supports the full featured LFN specification. The data type TCHAR specifies path name strings on the API is an alias of either char(ANSI/OEM) or WCHAR(UTF-16) depends on that option. For more information, refer to the description in the file name.
-
Note that code page setting, FF_CODE_PAGE, has actually no meaning for the path names at the Unicode API. However it still affects code conversion of string I/O functions at FF_STRF_ENCODE = 0 and backward compatibility with non-LFN systems, so that code page needs to be set properly when it is considered a problem.
+
By default, FatFs uses ANSI/OEM code set on the API even at LFN configuration. FatFs can also switch the character encoding on the API to Unicode by configuration option FF_LFN_UNICODE. This means that FatFs supports the full featured LFN specification. The data type TCHAR specifies path name strings on the API is an alias of either char(ANSI/OEM or UTF-8) or WCHAR(UTF-16) depends on that option. For more information, refer to the description in the file name.
+
Note that code page setting, FF_CODE_PAGE, has actually no meaning for the path names at the Unicode API. However it still affects code conversion of string I/O functions at FF_STRF_ENCODE == 0 and backward compatibility with non-LFN systems, so that code page needs to be set properly when it is considered a problem.
exFAT Filesystem
-
The exFAT (Microsoft's Extended File Allocation Table) filesystem is a succession of the FAT filesystem which has been widely used in embedded systems, consumer devices and portable storage media. It is adopted by SDA (SD Association) as a recommended filesystem for high capacity SD cards larger than 32 GB and they are being shipped with this format, so that the exFAT became one of the standard filesystems for removable media as well as FAT. The exFAT filesystem allows the file size beyond the 4 GB limit what FAT filesystem allows upto and some filesystem overhead, especially cluster allocation delay, are reduced as well. This feature improves the write throughput to the file.
-
Note that the exFAT is a patent of Microsoft Corporation. The exFAT function of FatFs is an implementation based on US. Pat. App. Pub. No. 2009/0164440 A1. FatFs module can swich the support for exFAT on/off by configuration option, FF_FS_EXFAT. When enable the exFAT on the commercial products, a license by Microsoft will be needed depends on the final destination of the products.
+
The exFAT (Microsoft's Extended File Allocation Table) filesystem is a succession of the FAT/FAT32 filesystem which has been widely used in embedded systems, consumer devices and portable storage media. It is adopted by SDA (SD Association) as a recommended filesystem for high capacity SD cards larger than 32 GB and they are being shipped with this format, so that the exFAT became one of the standard filesystems for removable media as well as FAT. The exFAT filesystem allows the file size beyond the 4 GB limit what FAT filesystem allows upto and some filesystem overhead, especially cluster allocation delay, are reduced as well. This feature improves the write throughput to the file.
+
Note that the exFAT is a patent of Microsoft Corporation. The exFAT function of FatFs is an implementation based on US. Pat. App. Pub. No. 2009/0164440 A1. FatFs module can switch the support for exFAT on/off by configuration option, FF_FS_EXFAT. When enable the exFAT on the commercial products, a license by Microsoft will be needed depends on the final destination of the products.
Remark: Enabling exFAT discards ANSI C (C89) compatibility because of need for 64-bit integer type.
FatFs has being developped as a personal project of the author, ChaN. It is free from the code anyone else wrote at current release. Following code block shows a copy of the FatFs license document that included in the source files.
This option switches the support for long file name (LFN). When enable the LFN, Unicode support functions ffunicode.c need to be added to the project. The working buffer for LFN occupies (FF_MAX_LFN + 1) * 2 bytes and additional ((FF_MAX_LFN + 44) / 15 * 32 bytes when exFAT enabled. 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.
+
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.
@@ -153,19 +154,37 @@
FF_MAX_LFN
-
This option defines the size of LFN working buffer from 12 to 255 in unit of character. This option has no effect when LFN is disabled.
+
LFN function requiers certain internal working buffer. This option defines size of the buffer and the value can be in range of 12 to 255 in UTF-16 encoding unit 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 disabled.
FF_LFN_UNICODE
-
This option switches character encoding on the API, ANSI/OEM (0) or Unicode in UTF-16 (1). To use Unicode string for the path name, enable LFN and set this option to 1. This option also affects behavior of string I/O functions. When LFN is disabled, this option has no effect. For more information, read here.
+
This option switches character encoding on the API.
+
+
Value
Character Encoding
TCHAR
+
0
ANSI/OEM in current CP
char
+
1
Unicode in UTF-16
WCHAR
+
2
Unicode in UTF-8
char
+
+
This option also affects behavior of string I/O functions. When LFN is disabled, this option has no effect. For more information, read here.
+
+
FF_LFN_BUF, FF_SFN_BUF
+
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 the read file name depends on the character encoding on the API as follows:
+
+
Encoding
LFN length
SFN length
+
ANSI/OEM at SBCS
255 items
12 items
+
ANSI/OEM at DBCS
510 items
12 items
+
Unicode in UTF-16
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.
FF_STRF_ENCODE
-
When Unicode API is selected by FF_LFN_UNICODE = 1, string I/O functions, f_gets, f_putc, f_puts and f_printf convert the character encodins in it. This option defines the assumption of character encoding on the file to be read/written via those functions. When Unicode API is not selected, the string functions work without any conversion and this option has no effect.
-
+
When character encoding on the API is Unicode (FF_LFN_UNICODE >= 1), string I/O functions, f_gets, f_putc, f_puts and f_printf, convert the character encodins in it. This option defines the assumption of character encoding on the file to be read/written via those functions. When FF_LFN_UNICODE == 0, the string functions work without any code conversion and this option has no effect.
+
Value
Description
-
0
ANSI/OEM
-
1
UTF-16LE
-
2
UTF-16BE
-
3
UTF-8
+
0
ANSI/OEM in current CP
+
1
Unicode in UTF-16LE
+
2
Unicode in UTF-16BE
+
3
Unicode in UTF-8
FF_FS_RPATH
@@ -221,13 +240,13 @@
Normal (0) or Tiny (1). At the tiny configuration, size of the file object FIL is reduced FF_MAX_SS bytes. Instead of private data buffer eliminated from the file object, common sector buffer in the filesystem object FATFS is used for the file data transfer.
FF_FS_EXFAT
-
This option switches support for the exFAT filesystem in addition to the FAT/FAT32 filesystem, Enabled(1) or Disabled(0). To enable this feature, 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 because of need for 64-bit integer type.
+
This option switches support for the 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 because of need for 64-bit integer type.
FF_FS_NORTC
-
Use RTC (0) or Do not use RTC (1). This option controls timestamp function. If the system does not have an RTC function or valid timestamp is not needed, set FF_FS_NORTC to 1 to disable the timestamp function. Any object modified by FatFs will have a fixed timestamp defined by FF_NORTC_MON, FF_NORTC_MDAY and FF_NORTC_YEAR. To use the timestamp function, set FF_FS_NORTC = 0 and add get_fattime function to the project to get the current time form real-time clock. This option has no effect at read-only configuration.
+
Use RTC (0) or Do not use RTC (1). This option controls timestamp function. If the system does not have any RTC function 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 fixed timestamp defined by FF_NORTC_MON, FF_NORTC_MDAY and FF_NORTC_YEAR. To use the timestamp function, 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 at read-only configuration.
FF_NORTC_MON, FF_NORTC_MDAY, FF_NORTC_YEAR
-
This set of options defines the time to be used at no RTC systems. This option has no effect at read-only configuration or FF_FS_NORTC = 0.
+
This set of options defines the time to be used at no RTC systems. This option has no effect at read-only configuration or FF_FS_NORTC == 0.
FF_FS_LOCK
This option switches file lock function to control duplicated file open and illegal operations to open objects. Note that the file lock function is independent of re-entrancy. This option must be 0 at read-only configuration.
@@ -241,10 +260,10 @@
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 but volume control 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 of this function. To enable this feature, also user provided synchronization handlers, ff_req_grant, ff_rel_grant, ff_del_syncobj and ff_cre_syncobj, need to be added to the project. Sample code is available in ffsystem.c.
FF_FS_TIMEOUT
-
Number of time ticks to abort the file function with FR_TIMEOUT when wait time is too long. This option has no effect when FF_FS_REENTRANT = 0.
+
Number of time ticks to abort the file function with FR_TIMEOUT when wait time is too long. This option has no effect when FF_FS_REENTRANT == 0.
FF_SYNC_t
-
This option defines O/S dependent sync object type. e.g. HANDLE, ID, OS_EVENT*, SemaphoreHandle_t and etc. A header file for O/S definitions needs to be included somewhere in the scope of ff.c. This option has no effect when FF_FS_REENTRANT = 0.
+
This option defines O/S dependent sync object type. e.g. HANDLE, ID, OS_EVENT*, SemaphoreHandle_t and etc. A header file for O/S definitions needs to be included somewhere in the scope of ff.c. This option has no effect when FF_FS_REENTRANT == 0.
Pointer to the parameter depends on the command code. Do not care if no parameter to be passed.
+
Pointer to the parameter depends on the command code. Do not care if the command has no parameter to be passed.
@@ -60,11 +60,11 @@ DRESULT disk_ioctl (
CTRL_SYNC
Make sure that the device has finished pending write process. If the disk I/O module has a write back cache, the dirty buffers must be written back to the media immediately. Nothing to do for this command if each write operation to the media is completed within the disk_write function.
GET_SECTOR_COUNT
Returns number of available sectors on the drive into the DWORD variable pointed by buff. This command is used in only f_mkfs and f_fdisk function to determine the volume/partition size to be created. Required at FF_USE_MKFS == 1 or FF_MULTI_PARTITION == 1.
GET_SECTOR_SIZE
Returns sector size of the device into the WORD variable pointed by buff. Valid return values for this command are 512, 1024, 2048 and 4096. This command is required only if FF_MAX_SS > FF_MIN_SS. When FF_MAX_SS == FF_MIN_SS, this command is never used and the device must work at that sector size.
-
GET_BLOCK_SIZE
Returns erase block size of the flash memory media in unit of sector into the DWORD variable pointed by buff. The allowable value is from 1 to 32768 in power of 2. Return 1 if the erase block size is unknown or non flash memory media. This command is used by only f_mkfs function and it attempts to align data area on the erase block boundary. Required at FF_USE_MKFS == 1.
+
GET_BLOCK_SIZE
Returns erase block size of the flash memory media in unit of sector into the DWORD variable pointed by buff. The allowable value is 1 to 32768 in power of 2. Return 1 if the erase block size is unknown or non flash memory media. This command is used by only f_mkfs function and it attempts to align data area on the erase block boundary. Required at FF_USE_MKFS == 1.
CTRL_TRIM
Informs the device the data on the block of sectors is no longer needed and it can be erased. The sector block is specified by a DWORD array {<start sector>, <end sector>} pointed by buff. This is an identical command to Trim of ATA device. Nothing to do for this command if this funcion is not supported or not a flash memory device. FatFs does not check the result code and the file function is not affected even if the sector block was not erased well. This command is called on remove a cluster chain and in the f_mkfs function. Required at FF_USE_TRIM == 1.
-
FatFs never uses any device dependent command nor user defined command. Following table shows an example of non-standard commands may be useful for some applications.
+
FatFs never uses any device dependent command nor user defined command. Following table shows an example of non-standard commands which may be useful for some applications.
Example of optional ioctl command
Command
Description
@@ -91,7 +91,7 @@ DRESULT disk_ioctl (
QuickInfo
-
The disk_ioctl function is not needed when FF_FS_READONLY == 1 and FF_MAX_SS == FF_MIN_SS.
Read/write operation to the generic storage devices, such as memory card, hadddisk and optical disk, is done in unit of block of data bytes called sector. FatFs supports the sector size in range of from 512 to 4096 bytes. When FatFs is configured for fixed sector size (FF_MIN_SS == MAX_SS, this is the most case), the read/write function must work at that sector size. When FatFs is configured for variable sector size (FF_MIN_SS != MAX_SS), the sector size of medium is inquired with disk_ioctl function immediately following disk_initialize function.
+
Read/write operation to the generic storage devices, such as memory card, hadddisk and optical disk, is done in unit of block of data bytes called sector. FatFs supports the sector size in range of from 512 to 4096 bytes. When FatFs is configured for fixed sector size (FF_MIN_SS == FF_MAX_SS, this is the most case), the read/write function must work at that sector size. When FatFs is configured for variable sector size (FF_MIN_SS != FF_MAX_SS), the sector size of medium is inquired with disk_ioctl function immediately following disk_initialize function.
The memory address specified by buff is not that always aligned to word boundary because the argument is defined as BYTE*. The unaligned read/write request can occure at direct transfer. If the bus architecture, especially DMA controller, does not allow unaligned memory access, it should be solved in this function. There are some workarounds described below to avoid this issue.
Convert word transfer to byte transfer in this function if needed. - Recommended.
On the f_read() calls, avoid long read request that includes a whole of sector. - Any direct transfer never occures.
-
On the f_read(fp, data, btw, bw) calls, make sure that (((UINT)data & 3) == (f_tell(fp) & 3)) is true. - Word alignment of buff is guaranteed.
+
On the f_read(fp, dat, btw, bw) calls, make sure that (((UINT)dat & 3) == (f_tell(fp) & 3)) is true. - Word alignment of buff is guaranteed no matter dat is not word aligned.
Generally, a multiple sector read request must not be split into single sector transactions to the storage device, or read throughput gets worse.
The current drive status is returned in combination of status flags described below. FatFs refers only STA_NOINIT and STA_PROTECT.
STA_NOINIT
-
Indicates that the device has not been initialized and not ready to work. This flag is set on system reset, media removal or failure of disk_initialize function. It is cleared on disk_initialize function succeeded. Any media change that occurs asynchronously must be captured and reflect it to the status flags, or auto-mount function will not work correctly. If the system does not support media change detection, application program needs to explicitly re-mount the volume with f_mount function after each media change.
+
Indicates that the device has not been initialized and not ready to work. This flag is set on system reset, media removal or failure of disk_initialize function. It is cleared on disk_initialize function succeeded. Any media change that occurs asynchronously must be captured and reflect it to the status flags, or auto-mount function will not work correctly. If the system does not support media change detection, application program needs to explicitly re-mount the volume with f_mount function after each media change.
STA_NODISK
Indicates that no medium in the drive. This is always cleared at fixed disk drive. Note that FatFs does not refer this flag.
STA_PROTECT
-
Indicates that the medium is write protected. This is always cleared at the drives without write protect function. Not valid if no medium in the drive.
+
Indicates that the medium is write protected. This is always cleared at the drives without write protect function. Not valid if STA_NODISK is set.
When opt is 0, the function finds a contiguous data area and set it as suggested point for next allocation instead of allocating it to the file. The next cluster allocation is started at top of the contiguous area found by this function. Thus the write file is guaranteed be contiguous and no allocation delay until the size reaches that size at least unless any other changes to the volume is performed.
The contiguous file would have an advantage at time-critical read/write operations. It eliminates some overheads in the filesystem and the storage media caused by random access due to fragmented file data. Especially FAT access for the contiguous file on the exFAT volume is completely eliminated and storage media will be accessed sequentially.
Pointer to the first item of the partition map table.
work
-
Pointer to the function work area. The size must be at least FF_MAX_SS bytes.
+
Pointer to the function work area. The size must be at least FF_MAX_SS bytes. When a null pointer is given, the function allocates a memory block for the working buffer (at only FF_USE_LFN == 3).
The format of path name on the FatFs module is similer to the filename specs of DOS/Windos as follows:
[drive#:][/]directory/file
-
The FatFs module supports long file name (LFN) and 8.3 format file name (SFN). The LFN can be used when (FF_USE_LFN != 0). The sub directories are separated with a \ or / in the same way as DOS/Windows API. Duplicated separators are skipped and ignored. Only a difference is that the logical drive is specified in a numeral with a colon. When drive prefix is omitted, the drive number is assumed as default drive (drive 0 or current drive).
-
Control characters ('\0' to '\x1F') are recognized as end of the path name. Leading/embedded spaces in the path name are valid as a part of the name at LFN configuration but the space is recognized as end of the path name at non-LFN configuration. Trailing spaces and dots are ignored at both configurations.
+
The FatFs module supports long file name (LFN) and 8.3 format file name (SFN). The LFN can be used when FF_USE_LFN != 0. The sub directories are separated with a \ or / in the same way as DOS/Windows API. Duplicated separators are skipped and ignored. Only a difference is that the logical drive is specified in a numeral with a colon. When drive prefix is omitted, the drive number is assumed as default drive (drive 0 or current drive).
+
Control characters (\0 to \x1F) are recognized as end of the path name. Leading/embedded spaces in the path name are valid as a part of the name at LFN configuration but the space is recognized as end of the path name at non-LFN configuration. Trailing spaces and dots are ignored at both configurations.
In default configuration (FF_FS_RPATH == 0), it does not have a concept of current directory like OS oriented filesystem. Every object on the volume is always specified in full path name that followed from the root directory. Dot directory names (".", "..") are not allowed. Heading separator is ignored and it can be exist or omitted. The default drive is fixed to drive 0.
When relative path is enabled (FF_FS_RPATH >= 1), specified path is followed from the root directory if a heading separator is exist. If not, it is followed from the current directory of the drive set by f_chdir function. Dot names are also allowed for the path names. The default drive is the current drive set by f_chdrive function.
@@ -41,28 +41,29 @@
Legal Characters and Case Sensitivity
-
On the FAT filesystem, legal characters for object name (file/directory name) are, 0-9 A-Z ! # $ % & ' ( ) - @ ^ _ ` { } ~ and extended characters (\x80-\xFF). Under LFN supported system, also + , ; = [ ] and space are legal for the object name and the white spaces and periods can be placed anywhere in the path name except for end of the object name.
-
FAT filesystem is case-insensitive to the object names on the volume. All object names are compared in case-insensitive. For example, these three names, file.txt, File.Txt and FILE.TXT, are identical. This is applied to also extended charactres. When an object is created on the FAT volume, upper converted name is recorded to the SFN entry, and the raw name is recorded to the LFN entry.
+
On the FAT filesystem, legal characters for object name (file/directory name) are, 0-9 A-Z ! # $ % & ' ( ) - @ ^ _ ` { } ~ and extended characters (\x80-\xFF). Under LFN supported system, also + , ; = [ ] and space are legal for the object name and the white spaces and dots can be placed anywhere in the path name except for end of the object name.
+
FAT filesystem is case-insensitive to the object names on the volume. All object names on the FAT volume are compared in case-insensitive. For example, these three names, file.txt, File.Txt and FILE.TXT, are identical. This is applied to also extended charactres. When an object is created on the FAT volume, upper converted name is recorded to the SFN entry, and the raw name is recorded to the LFN entry.
As for the DBCS language MS-DOS, it was case-sensitive to the extended characters. To follow this specification, FatFs works with case-sensitive to the extended characters at only non-LFN with DBCS configuration (DOS/DBCS specs). But at LFN configuration, FatFs works with case-insensitive to all characters (WindowsNT specs). This can cause a problem on compatibility with Windows system when an object with extended characters is created on the volume at non-LFN and DBCS configuration; therfore the object names with DBCS extended characters should not be used on the FAT volume shared by those systems.
Unicode API
-
The path names are input/output in either ANSI/OEM code or Unicode depends on the configuration options. The type of arguments which specify the path names are defined as TCHAR. It is an alias of char by default. The code set used to the path name string is ANSI/OEM specifid by FF_CODE_PAGE. When FF_LFN_UNICODE is set to 1, the type of the TCHAR is switched to WCHAR to support Unicode (UTF-16 encoding). In this case, the full-featured LFN specification is supported and the Unicode specific characters, such as ✝☪✡☸☭, can also be used for the path name. It also affects data types and encoding of the string I/O functions. To define literal strings, _T(s) and _TEXT(s) macro are available to select either ANSI/OEM or Unicode automatically. The code shown below is an example to define the literal strings.
+
The path names are input/output in either ANSI/OEM code or Unicode depends on the configuration options. The type of arguments which specifies the path names is defined as TCHAR. It is an alias of char by default and the code set used for the path name string is ANSI/OEM specifid by FF_CODE_PAGE. When FF_LFN_UNICODE is set to 1, the type of the TCHAR is switched to WCHAR to support UTF-16 encoded Unicode string. When UTF-16 or UTF-8 is specified by this option, the full-featured LFN specification is supported and the Unicode specific characters, such as ✝☪✡☸☭, can also be used for the path name. It also affects data types and encoding of the string I/O functions. To define literal strings, _T(s) and _TEXT(s) macro are available to select either ANSI/OEM or Unicode automatically. The code shown below is an example to define the literal strings.
FatFs module needs dynamic work area, filesystem object, for each volume (logical drive). It is registered/unregistered to the FatFs module by f_mount function. By default, each logical drive is bound to the physical drive with the same drive number and an FAT volume on the drive is serched by the volume mount process. It reads boot sectors and checks it if it is an FAT boot sector in order of sector 0 as SFD format, 1st partition, 2nd partition, 3rd partition and 4th partition as FDISK format.
-
When FF_MULTI_PARTITION == 1 is specified by configuration option, each individual logical drive is bound to the partition on the physical drive specified by volume management table. The volume management table needs to be defined by user to resolve the mappings of logical drives and partitions. Following code is an example of a volume management table.
+
When FF_MULTI_PARTITION = 1 is specified by configuration option, each individual logical drive is bound to the partition on the physical drive specified by volume management table. The volume management table needs to be defined by user to resolve the mappings of logical drives and partitions. Following code is an example of a volume management table.
-Example: 0:-2: are tied to three pri-partitions on the physical drive 0 (fixed drive)
- 3: is tied to an FAT volume on the physical drive 1 (removable drive)
+Example: "0:", "1:" and "2:" are tied to three pri-partitions on the physical drive 0 (fixed drive)
+ "3:" is tied to an FAT volume on the physical drive 1 (removable drive)
PARTITION VolToPart[FF_VOLUMES] = {
{0, 1}, /* "0:" ==> Physical drive 0, 1st partition */
diff --git a/documents/doc/findfirst.html b/documents/doc/findfirst.html
index 1cd2e1e..5e44289 100644
--- a/documents/doc/findfirst.html
+++ b/documents/doc/findfirst.html
@@ -66,14 +66,14 @@ FRESULT f_findfirst (
"*.*" never matches any name without extension while it matches any name with or without extension at the standard systems.
Any pattern terminated with a period never matches any name while it matches any name without extensiton at the standard systems.
The f_getcwd function retrieves full path name of the current directory of the current drive. When FF_VOLUMES is larger than 1, a logical drive number is added to top of the path name.
+
The f_getcwd function retrieves full path name of the current directory of the current drive. When FF_VOLUMES is larger than 1, a logical drive number is added to top of the path name.
Note: In this revision, this function cannot retrieve the current directory path on the exFAT volume. It always returns the root directory path.
Pointer to the DWORD variable to store number of free clusters.
fatfs
-
Pointer to pointer that to store a pointer to the corresponding file system object.
+
Pointer to pointer that to store a pointer to the corresponding filesystem object.
@@ -53,13 +53,13 @@ FRESULT f_getfree (
Descriptions
-
The f_getfree function gets number of free clusters on the volume. The member csize in the file system object indicates number of sectors per cluster, so that the free space in unit of sector can be calcurated with this information. When FSINFO structure on the FAT32 volume is not in sync, this function can return an incorrect free cluster count. To avoid this problem, FatFs can be forced full FAT scan by FF_FS_NOFSINFO option.
+
The f_getfree function gets number of free clusters on the volume. The member csize in the filesystem object indicates number of sectors per cluster, so that the free space in unit of sector can be calcurated with this information. When FSINFO structure on the FAT32 volume is not in sync, this function can return an incorrect free cluster count. To avoid this problem, FatFs can be forced full FAT scan by FF_FS_NOFSINFO option.
QuickInfo
-
Available when FF_FS_READONLY == 0 and FF_FS_MINIMIZE == 0.
Pointer to the null-terminated string that specifies the logical drive. Null-string specifies the default drive.
label
-
Pointer to the buffer to store the volume label. The buffer size must be at least 24 items at FF_LFN_UNICODE == 0 or 12 items at FF_LFN_UNICODE == 1. If the volume has no label, a null-string will be returned. Set null pointer if this information is not needed.
+
Pointer to the buffer to store the volume label. If the volume has no label, a null-string will be returned. Set null pointer if this information is not needed. The buffer size should be shown below at least to avoid buffer overflow.
+
+
FF_FS_EXFAT == 0
FF_FS_EXFAT == 1
+
FF_USE_LFN == 0
12 items
-
+
FF_LFN_UNICODE == 0
12 items
23 items
+
FF_LFN_UNICODE == 1
12 items
12 items
+
FF_LFN_UNICODE == 2
34 items
34 items
+
+
vsn
Pointer to the DWORD variable to store the volume serial number. Set null pointer if this information is not needed.
The read operation continues until a '\n' is stored, reached end of the file or the buffer is filled with len - 1 characters. The read string is terminated with a '\0'. When no character to read or any error occured during read operation, it returns a null pointer. The status of EOF and error can be examined with f_eof and f_error function.
-
When FatFs is configured to Unicode API (FF_LFN_UNICODE == 1), data types on the srting fuctions, f_putc, f_puts, f_printf and f_gets, is also switched to Unicode. The character encoding on the file to be read/written via those functions is assumed depends on FF_STRF_ENCODE.
+
When FatFs is configured to Unicode API (FF_LFN_UNICODE >= 1), data types on the srting fuctions, f_putc, f_puts, f_printf and f_gets, is also switched to Unicode. The character encoding on the file to be read via this function is assumed as FF_STRF_ENCODE. If the character encoding on the file differs from that on the API, it is converted in this function. In this case, input characters with wrong encoding will be lost.
QuickInfo
-
This is a wrapper function of f_read function. Available when FF_USE_STRFUNC is 1 or 2. When it is set to 2, '\r's contained in the file are stripped out.
+
This is a wrapper function of f_read function. Available when FF_USE_STRFUNC >= 1. When it is set to 2, '\r's contained in the file are stripped out.
Byte offset from top of the file to set read/write pointer. The data type FSIZE_t is an alias of either DWORD(32-bit) or QWORD(64-bit) depends on the configuration option FF_FS_EXFAT.
+
Byte offset from top of the file to set read/write pointer. The data type FSIZE_t is an alias of either DWORD(32-bit) or QWORD(64-bit) depends on the configuration option FF_FS_EXFAT.
@@ -61,7 +61,7 @@ FRESULT f_lseek (
QuickInfo
-
Available when FF_FS_MINIMIZE <= 2. To use fast seek function, FF_USE_FASTSEEK needs to be set 1.
Pointer to the null-terminated string specifies the logical drive to be formatted. If it has no drive number in it, it means the default drive. The logical drive may or may not be mounted for the format process.
opt
-
Specifies the format option in combination of FM_FAT, FM_FAT32, FM_EXFAT and bitwise-or of these three, FM_ANY. FM_EXFAT is ignored when exFAT is not enabled. These flags specify which FAT type to be created on the volume. If two or more types are specified, one out of them will be selected depends on the volume size. The flag FM_SFD specifies to place the volume on the drive in SFD format.
+
Specifies the format option in combination of FM_FAT, FM_FAT32, FM_EXFAT and bitwise-or of these three, FM_ANY. FM_EXFAT is ignored when exFAT is not enabled. These flags specify which FAT type to be created on the volume. If two or more types are specified, one out of them will be selected depends on the volume size and au. The flag FM_SFD specifies to create the volume on the drive in SFD format.
au
-
Specifies size of the allocation unit (cluter) in unit of byte. The valid value is n times the sector size. The n is power of 2 from 1 to 128 for FAT volume and upto 16MiB for exFAT volume. If zero is given, the default allocation unit size is selected depends on the volume size.
+
Specifies size of the allocation unit (cluter) in unit of byte. The valid value is n times the sector size. The n is power of 2 from 1 to 128 for FAT volume and upto 16MiB for exFAT volume. If zero is given, the default allocation unit size is selected depends on the volume size.
work
-
Pointer to the working buffer used for the format process.
+
Pointer to the working buffer used for the format process. When a null pointer is given, the function allocates a memory block for the working buffer and len has no effect (at only FF_USE_LFN == 3).
len
Size of the working buffer in unit of byte. It needs to be the sector size of the corresponding physical drive at least. Plenty of working buffer reduces number of write transactions to the drive and the format process will finish quickly.
The FAT sub-type, FAT12/FAT16/FAT32, of FAT volume except exFAT is determined by only number of clusters on the volume and nothing else, according to the FAT specification issued by Microsoft. Thus which FAT sub-type is selected, is depends on the volume size and the specified cluster size. In case of the combination of FAT type and cluter size specified by argument cannot be valid on the volume, the function will fail with FR_MKFS_ABORTED.
+
The FAT sub-type, FAT12/FAT16/FAT32, of FAT volume except exFAT is determined by only number of clusters on the volume and nothing else, according to the FAT specification issued by Microsoft. Thus the FAT sub-type of created volume depends on the volume size and the cluster size. In case of the combination of FAT type and cluter size specified by argument cannot be valid on the volume, the function will fail with FR_MKFS_ABORTED. The minimum drive size is 128 sectors with FM_SFD option.
The allocation unit, also called 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 as the size of allocation unit. Therefore the size of allocation unit is a trade-off between space efficiency and performance. For the large storages in GB order, 32768 bytes or larger (this is automatically selected by default) is recommended for most case unless extremely many small files are created on a volume.
-
There are two disk formats, FDISK and SFD. The FDISK format is usually used for harddisk, MMC, SDC, CFC and U Disk. It can divide a physical drive into one or more partitions with a partition table on the MBR (maser boot record, the first sector of the physical drive). The SFD (super-floppy disk) format is non-partitioned disk format. The FAT volume starts at the first sector of the physical drive without any disk partitioning. It is usually used for floppy disk, Microdrive, optical disk and most type of super-floppy media. Some systems support only either one of the two formats and the other is not supported.
+
There are two disk partitioning formats, FDISK and SFD. The 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 on the MBR (maser boot record, the first sector of the physical drive). The SFD (super-floppy disk) format is non-partitioned disk format. The FAT volume starts at the first sector of the physical drive without any disk partitioning. It is usually used for floppy disk, optical disk and most super-floppy media. Some systems support only either one of the two disk formats and the other is not supported.
When the logical drive to be formatted is bound to a physical drive and FM_SFD is not specified, a primary partition occupies whole drive space is created and then the FAT volume is created in it. When FM_SFD is specified, the FAT volume occupies from the first sector of the physical drive is created without partitioning.
-
When the logical drive to be formatted is bound to a specific partition (1-4) by support of multiple partition (FF_MULTI_PARTITION) the FAT volume is created into the partition and FM_SFD flag is ignored. The physical drive needs to be partitioned with f_fdisk function or any other partitioning tools prior to create the FAT volume with this function.
+
When the logical drive to be formatted is bound to a specific partition (1-4) by support of multiple partition (FF_MULTI_PARTITION == 1) the FAT volume is created into the partition and FM_SFD flag is ignored. The physical drive needs to be partitioned with f_fdisk function or any other partitioning tools prior to create the FAT volume with this function.
QuickInfo
-
Available when FF_FS_READOLNY == 0 and FF_USE_MKFS == 1.
If forced mounting is not specified (opt = 0), this function always succeeds regardless of the physical drive status. It only clears (de-initializes) the given work area and registers its address to the internal table and no activity of the physical drive in this function. To unregister the work area, specify a NULL to the fs, and then the work area can be discarded. The volume mount processes, initialize the corresponding physical drive, find the FAT volume in it and then initialize the work area, is performed in the subsequent file/directory functions when either of following conditions is true.
-
File system object has not been initialized. It is de-initialized by f_mount function.
+
Filesystem object has not been initialized. It is de-initialized by f_mount function.
Physical drive is not initialized. It is de-initialized by system reset or media removal.
If the function with forced mounting (opt = 1) failed, it means that the filesystem object has been registered successfully but the volume is currently not ready to work. The volume mount process will be attempted at subsequent file/directroy functions if the filesystem object is not initialized. (delayed mounting)
diff --git a/documents/doc/open.html b/documents/doc/open.html
index 3e3e621..1dd81d8 100644
--- a/documents/doc/open.html
+++ b/documents/doc/open.html
@@ -1,7 +1,7 @@
-
+
@@ -94,7 +94,7 @@ Mode flags of POSIX fopen() corresponds to FatFs mode flags as follows:
QuickInfo
-
Always available. Only FA_READ and FA_OPEN_EXISTING are supported when FF_FS_READONLY == 1.
+
Always available. Only FA_READ and FA_OPEN_EXISTING are available for the mode flags when FF_FS_READONLY == 1.
Pointer to the null terminated format string. The terminator charactor will not be written.
+
Pointer to the null '\0' terminated format string. The terminator character will not be output.
...
Optional arguments...
@@ -39,25 +39,28 @@ int f_printf (
Return Values
-
When the function succeeded, it returns number of characters written. If the function could not write the generated string to the file due to disk full or an error, EOF (-1) will be returned.
+
When the string was written successfuly, it returns number of character encoding units written to the file. When the function failed due to disk full or any error, an EOF (-1) will be returned.
Description
-
The format control directive is a sub-set of standard library shown as follos:
-
-
Type: c C s S d D u U x X b B
-
Size: l L
-
Flag: 0 -
-
+
The format control directive is a sub-set of standard library shown as follows:
+
+ %[flag][width][type]
+
+
+
flag
Padding options. A - specifies left justified. A 0 specifies zero padded.
+
width
Minimum width of the field, 1-99 or *. If the width of generated string is less than the specified value, rest field is padded with white spaces or zeros. An * specifies the value comes from an argument in int type.
+
type
c s d u o x b and prefix l specify type of the argument, character, string, signed integer in decimal, unsigned integer in decimal, unsigned integer in octal, unsigned integer in hexdecimal and unsigned integer in binary respectively. If sizeof (long) is greater than sizeof (int) (this is typical of 8/16-bit systems), a prefix l needs to be explicitly specified for long integer argument. These characters except for x are case insensitive.
+
+
When FatFs is configured for Unicode API (FF_LFN_UNICODE >= 1), character encoding on the string fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, should not be divided into two function calls, or the character will be lost. The character encoding on the file to be written via this function is selected by FF_STRF_ENCODE option. If the character encoding on the file differs from that on the API, it is converted in this function. In this case, input characters with wrong encoding or invalid for the output will be lost.
QuickInfo
-
This is a wrapper function of f_write function. Available when FF_FS_READONLY == 0 and FF_USE_STRFUNC is 1 or 2. When it is set to 2, '\n's contained in the output are converted to '\r'+'\n'.
-
When FatFs is configured to Unicode API (FF_LFN_UNICODE == 1), data types on the srting fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The character encoding on the file to be read/written via those functions is selected by FF_STRF_ENCODE option.
+
This is a wrapper function of f_write function. Available when FF_FS_READONLY == 0 and FF_USE_STRFUNC >= 1. When it is set to 2, '\n's contained in the output are converted to '\r'+'\n' each.
When the character was written successfuly, it returns number of characters written. When the function failed due to disk full or any error, an EOF (-1) will be returned.
-
When FatFs is configured to Unicode API (FF_LFN_UNICODE == 1), character encoding on the string fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The character encoding on the file to be read/written via those functions is selected by FF_STRF_ENCODE option.
+
When the character was written successfuly, it returns number of character encoding units written to the file. When the function failed due to disk full or any error, an EOF (-1) will be returned.
+
+
Description
+
When FatFs is configured for Unicode API (FF_LFN_UNICODE >= 1), character encoding on the string fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The character encoding on the file to be written via those functions is selected by FF_STRF_ENCODE option. The Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, cannot be written by this function.
+
+
QuickInfo
This is a wrapper function of f_write function. Available when FF_FS_READONLY == 0 and FF_USE_STRFUNC is 1 or 2. When it is set to 2, a '\n' is converted to '\r'+'\n'.
When the function succeeded, it returns number of characters written. When the write operation is aborted due to disk full or any error, an EOF (-1) will be returned.
-
When FatFs is configured to Unicode API (FF_LFN_UNICODE == 1), character encoding on the srting fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The character encoding on the file to be read/written via those functions is selected by FF_STRF_ENCODE option.
+
When the string was written successfuly, it returns number of character encoding units written to the file. When the function failed due to disk full or any error, an EOF (-1) will be returned.
+
+
+
+
+
Description
+
When FatFs is configured for Unicode API (FF_LFN_UNICODE >= 1), character encoding on the string fuctions, f_putc, f_puts, f_printf and f_gets function, is also switched to Unicode. The input Unicode characters in multiple encoding unit, such as surrogate pair and multi-byte sequence, should not be divided into two function calls, or the character will be lost. The character encoding on the file to be written via this functions is selected by FF_STRF_ENCODE option. If the character encoding on the file differs from that on the API, it is converted in this function. In this case, input characters with wrong encoding or invalid for the output will be lost.
QuickInfo
-
This is a wrapper function of f_write function. Available when FF_FS_READONLY == 0 and FF_USE_STRFUNC is 1 or 2. When it is set to 2, '\n's contained in the string are converted to '\r'+'\n'.
+
This is a wrapper function of f_write function. Available when FF_FS_READONLY == 0 and FF_USE_STRFUNC is 1 or 2. When it is set to 2, '\n's contained in the string are converted to '\r'+'\n'.
diff --git a/documents/doc/rc.html b/documents/doc/rc.html
index 246b988..00a7556 100644
--- a/documents/doc/rc.html
+++ b/documents/doc/rc.html
@@ -48,7 +48,14 @@ Note that if once this error occured at any operation to an open file, the file
The given string is invalid as the path name. One of the following possibilities is suspected.
+
+
There is any character not allowed for the file name.
+
The string is out of 8.3 format. (at non-LFN cfg.)
+
FF_MAX_LFN is insufficient for the file name. (at LFN cfg.)
+
There is any character encoding error in the string.
+
+
FR_DENIED
The required access was denied due to one of the following reasons:
@@ -69,8 +76,8 @@ Note that if once this error occured at any operation to an open file, the file
FR_INVALID_OBJECT
The file/directory object is invalid or a null pointer is given. There are some reasons as follows:
-
It has been closed, it has not been opened or it has been collapsed.
-
It has been invalidated by a voulme mount process. Open objects on the volume are invalidated by voulme mount process.
+
It has been closed, or collapsed.
+
It has been invalidated. Open objects on the volume are invalidated by voulme mount process.
Physical drive is not ready to work due to a media removal.
Pointer to the file information structure to store the information about read item. A null pointer rewinds the read index of the directory.
@@ -49,19 +49,20 @@ FRESULT f_readdir (
Description
The f_readdir function reads a directory item, informations about the object. All items in the directory can be read in sequence by f_readdir function calls. Dot entries ("." and "..") in the sub-directory are filtered out and they will never appear in the read items. When all directory items have been read and no item to read, a nul string is stored into the fno->fname[] without any error. When a null pointer is given to the fno, the read index of the directory object is rewinded.
-
When support of long file name (LFN) is enabled, a member altname[] is defined in the file information structure to store the short file name of the object. In case of the some conditions listed below, short file name is stored into the fname[] and altname[] has a null string.
+
When support of long file name (LFN) is enabled, a member altname[] is defined in the file information structure to store the short file name of the object. If the long file name is not accessible due to some reason listed below, short file name is stored to the fname[] and altname[] has a null string.
-
The item has no long file name. (Not the case at exFAT volume)
-
Setting of FF_MAX_LFN is insufficient for the long file name. (Not the case at FF_MAX_LFN == 255)
-
The long file name contains any character not allowed in ANSI/OEM code. (Not the case at FF_LFN_UNICODE == 1)
+
The item has no LFN. (Not the case at exFAT volume)
+
Setting of FF_MAX_LFN is insufficient to handle the LFN. (Not the case at FF_MAX_LFN == 255)
+
Setting of FF_LFN_BUF is insufficient to store the LFN.
+
The LFN contains any character not defined in current code page. (Not the case at FF_LFN_UNICODE >= 1)
-
There is a problem on reading a directory of exFAT volume. The exFAT does not support short file name. This means no name can be returned on the condition above. If it is the case, "?" is returned into the fname[] to indicate that the object is not accessible. To avoid this problem, configure FatFs FF_LFN_UNICODE = 1 and FF_MAX_LFN = 255 to support the full feature of LFN specification.
+
There is a problem on reading a directory of exFAT volume. The exFAT does not support short file name. This means no name can be returned on the condition above. If it is the case, "?" is returned into the fname[] to indicate that the object is not accessible. To avoid this problem, configure FatFs FF_LFN_UNICODE >= 1 and FF_MAX_LFN == 255 to support the full feature of LFN specification.
The DIR structure is used for the work area to read a directory by f_oepndir, f_readdir, f_findfirst and f_findnext function. Application program must not modify any member in this structure, or any file on the volume can be collapsed.
+
The DIR structure is used for the work area to read a directory by f_oepndir, f_readdir, f_findfirst and f_findnext function. Application program must not modify any member in this structure, or f_readdir function will not work properly.
OEM code page to be used for the path name. Valid values are as follows.
Value
Meaning
-
0
Initial value (non-ASCII character cannot be used)
+
0
Initial value (any extended character cannot be used)
437
U.S.
720
Arabic
737
Greek
@@ -67,13 +67,13 @@ FRESULT f_setcp (
Description
-
The f_setcp function sets the active code page for the path name. Also code conversion of string functions will be affected by the code page when FF_LFN_UNICODE = 1 and FF_STRF_ENCODE = 0. Because the initial setting of the code page is 0 and API function with non-ASCII character will not work properly. Any valid code page needs to be set on the system start-up and it should not be changed on the fly.
+
The f_setcp function sets the active code page for the path name. Also code conversion of string functions will be affected by the setting of code page when FF_LFN_UNICODE >= 1 and FF_STRF_ENCODE == 0. Because the initial setting of the code page is 0 and API function with extended character will not work properly, a valid code page needs to be set on the system start-up and it should not be changed on the fly.
When the string has a drive number, the volume label will be set to the volume specified by the drive number. If not, the volume label will be set to the default drive. If length of the given volume label is zero, the volume label on the volume will be removed. The format of the volume label on the FAT volume is similar to the file name but there are some differences shown below:
-
Period is not allowed.
+
Dot is not allowed.
Spaces can be contained anywhere in the volume label. Trailing spaces are truncated off at FAT volume.
Up to 11 bytes long as conversion of OEM code page at FAT volume.
Up to 11 characters long at exFAT volume. Lower case is preserved.
@@ -61,7 +61,7 @@ FRESULT f_setlabel (
QuickInfo
-
Available when FF_FS_READONLY == 0 and FF_USE_LABEL == 1.
The FATFS structure (filesystem object) 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. Initialization of the structure is done by volume mount process whenever necessary. Application program must not modify any member in this structure, or the FAT volume can be collapsed.
+
The FATFS structure (filesystem object) 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. Initialization of the structure is done by volume mount process whenever necessary. Application program must not modify any member in this structure, or the FAT volume will be collapsed.
typedefstruct {
BYTE fs_type; /* FAT type (0, FS_FAT12, FS_FAT16, FS_FAT32 or FS_EXFAT) */
@@ -27,7 +27,7 @@
#if FF_MAX_SS != FF_MIN_SS
WORD ssize; /* Sector size (512,1024,2048 or 4096) */#endif
-#if FF_FS_EXFAT
+#if FF_FS_EXFAT
BYTE* dirbuf; /* Directory entry block scratchpad buffer */#endif#if FF_FS_REENTRANT
@@ -39,7 +39,7 @@
#endif#if FF_FS_RPATH
DWORD cdir; /* Cluster number of current directory (0:root) */
-#if FF_FS_EXFAT
+#if FF_FS_EXFAT
DWORD cdc_scl; /* Containing directory start cluster (invalid when cdir is 0) */
DWORD cdc_size; /* b31-b8:Size of containing directory, b7-b0: Chain status */
DWORD cdc_ofs; /* Offset in the containing directory (invalid when cdir is 0) */
diff --git a/documents/doc/sfile.html b/documents/doc/sfile.html
index d3731f0..599b8d2 100644
--- a/documents/doc/sfile.html
+++ b/documents/doc/sfile.html
@@ -1,7 +1,7 @@
-
+
@@ -13,7 +13,7 @@
FIL
-
The FIL structure (file object) holds the state of an open file. It is created by f_open function and discarded by f_close function. Application program must not modify any member in this structure except for cltbl, or any data on the FAT volume can be collapsed. Note that a sector buffer is defined in this structure at non-tiny configuration (FF_FS_TINY == 0), so that the FIL structures at that configuration should not be defined as auto variable.
+
The FIL structure (file object) holds the state of an open file. It is created by f_open function and discarded by f_close function. Application program must not modify any member in this structure except for cltbl, or the FAT volume will be collapsed. Note that a sector buffer is defined in this structure at non-tiny configuration (FF_FS_TINY == 0), so that the FIL structures at that configuration should not be defined as auto variable.
typedefstruct {
diff --git a/documents/doc/sfileinfo.html b/documents/doc/sfileinfo.html
index 311c0c3..c9597a9 100644
--- a/documents/doc/sfileinfo.html
+++ b/documents/doc/sfileinfo.html
@@ -1,7 +1,7 @@
-
+
@@ -21,10 +21,10 @@
WORD ftime; /* Last modified time */
BYTE fattrib; /* Attribute */#if FF_USE_LFN
- TCHAR altname[13]; /* Alternative object name */
- TCHAR fname[FF_MAX_LFN + 1]; /* Primary object name */
+ TCHAR altname[FF_SFN_BUF + 1]; /* Alternative object name */
+ TCHAR fname[FF_LFN_BUF + 1]; /* Primary object name */#else
- TCHAR fname[13]; /* Object name */
+ TCHAR fname[12 + 1]; /* Object name */#endif
} FILINFO;
@@ -59,7 +59,7 @@
fattrib
Indicates the file/directory attribute in combination of AM_DIR, AM_RDO, AM_HID, AM_SYS and AM_ARC.
fname[]
-
The null-terminated object name is stored. A null string is stored when no item to read and it indicates this structure is invalid.
+
The null-terminated object name is stored. 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 at LFN configuration.
altname[]
Alternative object name is stored if available. This member is not available at non-LFN configuration.
diff --git a/documents/doc/unlink.html b/documents/doc/unlink.html
index fa24a76..edd6371 100644
--- a/documents/doc/unlink.html
+++ b/documents/doc/unlink.html
@@ -1,7 +1,7 @@
-
+
@@ -65,7 +65,7 @@ If condition of the object to be removed is applicable to the following terms, t
QuickInfo
-
Available when FF_FS_READONLY == 0 and FF_FS_MINIMIZE == 0.
