FatFs module is an experimental project to implement a FAT file system to small embdded system. Because the module is written in compliance with ANSI C, it can be used for most 8/16 bit microcontrollers, such as PIC, AVR, H8, Z80 and etc..., without any modification. To use the FatFs module, low level disk I/O functions for each recording media must be provided by user. I created two modules in different configurations in consideration of various use. For read only applications, wriiting codes can also be eliminated to reduce the code size.
+
FatFs module is an experimental project to implement FAT file system to small embdded systems. The FatFs module is written in compliance with ANSI C, therefore it is independent of hardware architecture. It can be implemented to most 8/16 small microcontrollers, such as PIC, AVR, H8, Z80 and etc..., without any changes. I created two modules in different configurations in consideration of various use. For read only applications, writing codes can also be eliminated to reduce the module size. To use the FatFs module, low level disk I/O functions for each media must be provided by user.
Features of FatFs Module
Separated buffer for FAT and each file. Suitable for fast multiple file accsess.
Low memory consumption (ex. avr-gcc)
-
Program Code: 7752 bytes (R/W cfg.), 4154 bytes (R/O cfg.)
The FatFs module is opened for education, reserch and development. You can use, modify and republish it for personal, non-profit or profit use without any limitation under your responsibility.
Out of alignment. In unbuffered mode, specified offset must be aligned on 512 byte boundary.
FR_RW_ERROR
Any error occured in low level disk I/O.
FR_INCORRECT_DISK_CHANGE
-
Incorrect disk removal, such as a medium change during any file opend, has been occured.
+
Incorrect disk removal, such as a medium change during any file is opend, has been occured.
FR_NOT_ENABLED
FatFs module has not been enabled.
@@ -59,15 +58,15 @@ FRESULT f_lseek (
// Move to offset of 5000 from top of file.
res = f_lseek(&file, 5000);
- if (res) die(res);
- // Move to 3000 bytes front of current offset.
+ // Forward 3000 bytes
res = f_lseek(&file, file.fptr + 3000);
- if (res) die(res);
- // Move to 2000 bytes back of current offset.
+ // Rewind 2000 bytes
res = f_lseek(&file, file.fptr - 2000);
- if (res) die(res);
+
+ // Move to end of file
+ res = f_lseek(&file, 0xFFFFFFFF);
Pointer to the blank file object structure to be initialized. After the f_open function succeeded, the file can be accessed with the file object structure until it is closed. The member buffer in the structure must be initialized with the address of a 512 bytes file read/write buffer before or immediataly after the f_open function. The initialization is not needed when FA_UNBUFFERED flag has been specified.
+
Pointer to the blank file object structure to be initialized. After the f_open() succeeded, the file can be accessed with the file object structure until it is closed.
FileName
Pointer to a null-terminated string specifies the full-path file name to create or open. The directory separator is '/'. Because the FatFs module does not have a concept of current directory, a full-path name that followed from the root directory must be used. Leading space charactors are skipped if exist and heading '/' can be exist or omitted.
ModeFlags
Specifies the type of access and open method for the file. It is specified by a combination of following flags.
-
Value
Description
-
FA_READ
Specifies read access to the object. Data can be read from the file. Combine with FA_WRITE for read-write access.
-
FA_WRITE
Specifies write access to the object. Data can be written to the file. Combine with FA_READ for read-write access.
-
FA_UNBUFFERED
This is for only FatFs module. When not specified, the file can be read/written in stream I/O via the file read/write buffer pointed by member 'buffer' in the file object. When specified, file read/write buffer is not used and number of bytes to read/write must be integer multiple of 512.
-
FA_OPEN_EXISTING
Opens the file. The function fails if the file does not exist.
-
FA_CREATE_ALWAYS
Creates a new file. If the file exists, it is truncated and overwritten.
-
FA_OPEN_ALWAYS
Opens the file, if it exists. If the file does not exist, the function creates the file.
+
Value
Description
+
FA_READ
Specifies read access to the object. Data can be read from the file. Combine with FA_WRITE for read-write access.
+
FA_WRITE
Specifies write access to the object. Data can be written to the file. Combine with FA_READ for read-write access.
+
FA_OPEN_EXISTING
Opens the file. The function fails if the file does not exist.
+
FA_CREATE_ALWAYS
Creates a new file. If the file exists, it is truncated and overwritten.
+
FA_OPEN_ALWAYS
Opens the file, if it exists. If the file does not exist, the function creates the file.
@@ -64,7 +64,7 @@ FRESULT f_open (
FR_RW_ERROR
Any error occured in low level disk I/O.
FR_INCORRECT_DISK_CHANGE
-
Incorrect disk removal, such as a medium change during any file opend, has been occured.
+
Incorrect disk removal, such as a medium change during any file is opend, has been occured.
FR_NOT_ENABLED
FatFs module has not been enabled.
FR_NO_FILESYSTEM
@@ -75,46 +75,41 @@ FRESULT f_open (
Description
-
To start to use the FatFs module, prepare a work area (FATFS structure), clear the structure and store the address to the global variable 'FatFs' to allocate the work area to the FatFs module. Then the FatFs module can work.
-
Flags FA_WRITE, FA_CREATE_ALWAYS, FA_OPEN_ALWAYS are not supported in read-only configuration. Flag FA_UNBUFFERED is not supported in Tiny-FatFs.
+
To start to use the FatFs module, prepare a work area (FATFS structure), clear it and set its address to the global pointer 'FatFs' to allocate the work area to the FatFs module. Then the FatFs module can work.
+
Flags FA_WRITE, FA_CREATE_ALWAYS, FA_OPEN_ALWAYS are not supported in read-only configuration.
-
Sample Code
+
Example (File Copy)
void main ()
{
FATFS fs; // FatFs work area
FIL fsrc, fdst; // file structures
- BYTE fbuff[512*2]; // file r/w buffers (not required for Tiny-FatFs)
BYTE buffer[4096]; // file copy buffer
FRESULT res; // FatFs function common result code
WORD br, bw; // File R/W count
- // Activate FatFs module
+ // Give a work area for FatFs (activate module)
memset(&fs, 0, sizeof(FATFS));
FatFs = &fs;
// Open source file
- fsrc.buffer = fbuff+0; // (not required for Tiny-FatFs)
res = f_open(&fsrc, "/srcfile.dat", FA_OPEN_EXISTING | FA_READ);
if (res) die(res);
// Create destination file
- fdst.buffer = fbuff+512; // (not required for Tiny-FatFs)
res = f_open(&fdst, "/dstfile.dat", FA_CREATE_ALWAYS | FA_WRITE);
if (res) die(res);
// Copy source to destination
for (;;) {
res = f_read(&fsrc, buffer, sizeof(buffer), &br);
- if (res) die(res);
- if (br == 0) break;
+ if (res || br == 0) break;
res = f_write(&fdst, buffer, br, &bw);
- if (res) die(res);
- if (bw < br) break;
+ if (res || bw < br) break;
}
// Close all files
diff --git a/doc/en/opendir.html b/doc/en/opendir.html
index d0ca017..99b0646 100644
--- a/doc/en/opendir.html
+++ b/doc/en/opendir.html
@@ -3,6 +3,7 @@
+
FatFs - f_opendir
@@ -35,7 +36,7 @@ FRESULT f_opendir (
Return Values
FR_OK
-
The function succeeded. The DirObject structure is used for subsequent calls to read the directory items.
+
The function succeeded. The DirObject structure is used for subsequent calls to read the directory entries.
FR_NOPATH
Could not find the path.
FR_INVALID_NAME
@@ -45,7 +46,7 @@ FRESULT f_opendir (
FR_RW_ERROR
Any error occured in low level disk I/O.
FR_INCORRECT_DISK_CHANGE
-
Incorrect disk removal, such as a medium change during any file opend, has been occured.
+
Incorrect disk removal, such as a medium change during any file is opend, has been occured.
The function denied due to the file has been opened in write only mode.
-
FR_ALIGN_ERROR
-
The file has been opened in unbufferred mode but unaligned access was detected.
FR_RW_ERROR
Any error occured in low level disk I/O.
FR_NOT_READY
@@ -58,7 +57,7 @@ FRESULT f_read (
Description
-
The read/write pointer increases in number of bytes read. The ByteRead will be smaller than ByteToRead when the read pointer reached to end of the file or alignment error occured during the read operation. In unbufferred mode, last fractional bytes cannot be read due to FR_ALIGN_ERROR.
+
The read/write pointer increases in number of bytes read. The ByteRead will be smaller than ByteToRead when the read pointer reached to end of the file or alignment error occured during the read operation.
The FIL structure holds state of a file and it is allocated by an application program. Only buffer member can be initialized by the application program.
+
The FIL structure holds state of a file and it is allocated by an application program. There is no member that can be changed by the application program.
FatFs
@@ -23,9 +24,9 @@ typedef struct _FIL {
DWORD curr_sect; // Current sector
DWORD dir_sect; // Sector# containing the directory entry
BYTE* dir_ptr; // Ponter to the directory entry in the window
- BYTE* buffer; // Pointer to 512 byte file R/W buffer
BYTE flag; // File status flags
BYTE sect_clust; // Left sectors in current cluster
+ BYTE buffer[512]; // File R/W buffer
} FIL;
Incorrect disk removal, such as a medium change during any file opend, has been occured.
+
Incorrect disk removal, such as a medium change during any file is opend, has been occured.
FR_NOT_ENABLED
FatFs module has not been enabled.
@@ -45,7 +46,7 @@ FRESULT f_sync (
Description
-
The f_sync writes back the cached information of a file being written into the disk. This is the same function as f_close but the file is left opened and can continue the file access. This is suitable for an application of data logger that opens a file for long time in writing mode. The f_sync of periodic or immediataly after f_wriete can minimize the lost data due to an unintentional black out or disk removal. This function is not supported in read-only configuration.
+
The f_sync() writes back the cached information of the file being written. This performs the same function as f_close() but the file is left opened and can continue file read/write operations to the file. This is suitable for applications that open files for a long time in writing mode, such as data logger. Performing f_sync() of periodic or immediataly after f_write() can minimize risk of data loss due to sudden blackout or unintentional disk removal. This function is not supported in read-only configuration.
The function denied due to the file has been opened in read only mode.
-
FR_ALIGN_ERROR
-
The file has been opened in unbufferred mode but unaligned access was detected.
FR_RW_ERROR
Any error occured in low level disk I/O.
FR_NOT_READY
@@ -58,7 +57,7 @@ FRESULT f_write (
Description
-
The read/write pointer increases in number of bytes written. The ByteWritten will be smaller than ByteToWrite when disk full or alignment error occured during write function. This function is not supported in read only configuration.
+
The read/write pointer increases in number of bytes written. The ByteWritten will be smaller than ByteToWrite when disk gets full during write function. This function is not supported in read only configuration.
- // Move to offset of 5000 from top of file.
+ // ファイルオフセット 5000 へ移動
res = f_lseek(&file, 5000);
- if (res) die(res);
- // Move to 3000 bytes front of current offset.
+ // 3000バイト進める
res = f_lseek(&file, file.fptr + 3000);
- if (res) die(res);
- // Move to 2000 bytes back of current offset.
+ // 2000バイト戻す
res = f_lseek(&file, file.fptr - 2000);
- if (res) die(res);
+
+ // ファイル末尾 + 1 へ移動
+ res = f_lseek(&file, 0xFFFFFFFF);
-
